pmem-ai 0.6.3 → 0.7.0

package/docs/v0.6.4 pre-design.md

@@ -0,0 +1,526 @@
+# v0.6.4 前置设计决策
+
+本文档记录 pmem v0.6.4 开工前的产品与技术决策。v0.6.4 的核心定位：
+
+> **Polish & Wrap v0.6 Track**
+>
+> v0.6.3 已发布到 npm。当前进入 v0.6 track 的"干净收尾"阶段。
+>
+> v0.6.4 不新增大型子系统，不改变 memory schema，不做通用化（v0.7.0 目标）、
+> embedding、MCP/REST、Graph UI、telemetry 或远程服务。
+> v0.6.4 只收尾 v0.6 期间累积的低风险 polish 任务，
+> 让 v0.6 track 以稳定状态结束，并为 v0.7.0 通用化设计让出干净的基础。
+>
+> v0.6.4 要回答的唯一问题：
+> **v0.6 track 是否在用户面足够打磨完，让 v0.7.0 通用化有干净的工作基底？**
+
+---
+
+## 一、背景：v0.6 期间累积的 polish 任务
+
+v0.6.0/0.6.1/0.6.2/0.6.3 连续发布期间，pre-design 文档、handover 文档、pre-design 备注中累积了 8 项
+低风险 polish 任务。这些任务的特点：
+
+- 单任务工作量 ≤ 1 天
+- 不引入新概念、不改 schema
+- 不动 v0.6 已经收敛的"success criteria"
+- 大部分来自 pre-design §三 "已知非阻塞 P2" 列表或 handover "待观察"列表
+
+| # | 来源 | 任务 | 严重程度 |
+|---|------|------|----------|
+| 1 | v0.6.2 pre-design §三 / §十一 末尾 | rename `splitFrontmatter()` body `trimStart()` polish | 非阻塞 P2 |
+| 2 | v0.6 pre-design §成功标准 5 / §九 P1 | integration 模板版本化 + verify 旧模板警告 | 低 |
+| 3 | v0.6 pre-design §九 P2 / handover-v0.6 §九 | Codex / Cursor 深度 slash command 入口 | P2 |
+| 4 | v0.6 pre-design §九 P2 / handover-v0.6 §九 | session start 探测 + `--create-if-missing` 评估 | P2（design 评估） |
+| 5 | v0.6.2 pre-design §5.6 | session 状态丢失根因排查与修复 | P1 |
+| 6 | v0.6.2 pre-design §4.1d | pmem doctor lock 状态可读性 polish | 低 |
+| 7 | v0.6 pre-design §九 P2 | `--guided` 缺字段时的引导 polish | P2 |
+| 8 | v0.6.2 pre-design §4.3 | rename `--dry-run` 对 frontmatter 字段的 diff 输出 | 低 |
+
+此外，v0.6.4 自身还应该补**两条文档同步**（不增加代码但必须做）：
+
+| # | 来源 | 任务 |
+|---|------|------|
+| 9 | （本 pre-design 自提）| `docs/project-roadmap.md` 补 v0.6.2 / v0.6.3 已发布条目 |
+| 10 | （本 pre-design 自提）| `docs/project-roadmap.md` 增 v0.6.4 "Polish & Wrap" 条目 |
+
+---
+
+## 二、v0.6.4 产品目标
+
+### 一句话目标
+
+> **让 v0.6 track 干净收尾——8 项 polish 全部完成 + 2 项文档同步，让 v0.7.0 通用化有干净基底。**
+
+### 用户对象
+
+| 用户 | 收益 |
+|------|------|
+| 重度项目使用者 | rename 不再 `trimStart` body 空白；doctor lock 状态更可读；rename frontmatter 字段 rename 的 diff 清晰 |
+| Code agent | integration verify 能识别 stale 模板（不被模板静默过期坑）；Codex/Cursor 入口补齐；session start 探测降低"刚启动就报 No active session" 的概率 |
+| 首次试用者 | `--guided` 缺字段时给出明确的"可补参数"列表 |
+
+### 成功标准
+
+1. `pmem rename` 改 body 后，body 原始空白逐字节保留（除用户显式编辑外）。
+2. `pmem integration verify` 在模板版本与项目 manifest 不匹配时输出明确的 warning 级别 issue + 修复指引。
+3. `pmem integration install codex` 生成 `.codex/commands/pmem-*.md` 等价的 Codex entry；`pmem integration install cursor` 生成 `.cursor/commands/pmem-*.md`。
+4. `pmem doctor` 的 lock 检查在 active 状态下输出 age、stale 判定、明确的下一步建议。
+5. `pmem init --guided` 在缺失 `--description` / `--stage` / `--next` 任意字段时，输出"可补哪些参数 + 等价 CLI 命令"。
+6. `pmem rename --dry-run` 在 frontmatter 字段（如 `aliases`）命中时也输出 diff 预览。
+7. session 状态丢失根因报告写进 `docs/handover-v0.6.4.md`（即使根因没复现），明确推迟或修复的判定。
+8. `docs/project-roadmap.md` 补 v0.6.2 / v0.6.3 / v0.6.4 三条已发布/规划条目。
+
+---
+
+## 三、scope 分级
+
+### P0 — 必须完成（v0.6 track 收尾的核心）
+
+| 任务 | 说明 | 复杂度 |
+|------|------|--------|
+| 任务 5：session 状态丢失根因 | 排查 src/commands/session.ts:77-82 偶发场景；写根因报告；可能修复或明确推迟 | 中 |
+| 任务 9 + 10：roadmap 文档同步 | 补 v0.6.2/v0.6.3/v0.6.4 三条 | 低 |
+
+### P1 — 强烈建议（8 项 polish 中影响面较大的 3 项）
+
+| 任务 | 说明 | 复杂度 |
+|------|------|--------|
+| 任务 1：rename trimStart 修复 | 记录 frontmatter end 位置，body 原始 slice | 低 |
+| 任务 2：integration 模板版本化 | manifest.integration.template_version 与 .pmem/integrations/* 标记的 version 字段对比 | 中 |
+| 任务 3：Codex/Cursor 深度入口 | 补 `.codex/commands/` 和 `.cursor/commands/` | 中 |
+
+### P2 — 可延后到 v0.6.5（如存在）或放弃
+
+| 任务 | 说明 | 复杂度 |
+|------|------|--------|
+| 任务 4：session start --create-if-missing | 仅做 design 评估（不实现），决策记录到 docs | 低（design only） |
+| 任务 6：doctor lock 可读性 | active 状态加 age + stale 判定 + 下一步建议 | 低 |
+| 任务 7：--guided 缺字段引导 | 列出"可补哪些参数" | 低 |
+| 任务 8：rename --dry-run frontmatter diff | `aliases` / `tags` 字段 rename 的 diff 预览 | 低 |
+
+### 明确不做（推迟到 v0.7+）
+
+v0.6.4 不触碰以下方向，避免 scope 蔓延：
+
+- **通用化（v0.7.0 主目标）**——`pmem new` 类型解锁、status 目录匹配去误报、`id_pattern` 占位符、`recall.foundational_types` 通用化、init 模板目录可配置等
+- discover provider 化、discover 默认禁用
+- init --type-preset wizard
+- auto_update.* 字段真正接通
+- `card_globs` 真的被 rebuild 消费
+- 完整 dirty lifecycle（`open/resolved/superseded/ignored/archived`）
+- `pmem dirty list/resolve/prune`
+- embedding / semantic search
+- MCP Server / REST API
+- Graph UI
+- telemetry
+- 多项目 workspace
+- 多语言 CLI
+
+### 范围纪律
+
+v0.6.4 是 v0.6 track 的最后一块。如果某项 polish 在调研中
+发现需要更大改动（"low" 变 "medium"），立即停止并移交给 v0.7.0 处理。
+**不主动扩大 v0.6.4 scope。**
+
+---
+
+## 四、P0 详细设计
+
+### 4.1 session 状态丢失根因排查
+
+**现状：**
+
+`src/commands/session.ts:77-82` 偶发 "No active pmem session found" 错误。
+v0.6.2 已修复 lock 自动清理、doctor session query bug，但根因未明确闭环。
+
+**已知候选根因：**
+
+1. **WAL 模式写入可见性**：`session start` 写入 SQLite 后进程退出，下次 `session end` 在另一进程中读取，但 WAL 未 checkpoint 导致旧连接看不到新写入。
+2. **数据库连接关闭时机**：`closeDatabase()` 在写入前关闭导致未提交。
+3. **多次 start 隐式行为**：用户 `session start` 两次，第二次写入覆盖了第一次的 session_id，但 `session end` 检查的是"最近一个未 end 的 session"，可能错位。
+
+**排查策略：**
+
+1. 复现：在 temp 目录模拟快速 start → end 周期，连续 20 次，统计失败率
+2. 检查 `src/core/db.ts` 的 SQLite 打开方式（journal_mode = WAL?）
+3. 若根因在 WAL：在 `session start` 写入后显式 `PRAGMA wal_checkpoint(PASSIVE)`
+4. 若根因在连接关闭：调整 `closeDatabase()` 时机
+5. 若根因在多次 start：增加 idempotent start（第二次 start 检测到 active session 时返回现有 session_id）
+
+**DoD：**
+
+- 复现脚本写到 `scripts/repro-session-loss.sh`
+- 根因报告写到 `docs/handover-v0.6.4.md` §session 状态丢失章节
+- 若有修复：附带 E2E 验证
+- 若无修复：明确推迟到 v0.7+，附"v0.6.4 已确认根因为 X，修复需要改 Y，v0.6.4 范围内不引入此改动"
+
+### 4.2 docs/project-roadmap.md 同步
+
+**当前缺失条目：**
+
+v0.6.2 "Real-User Friction Fixes" ✅ 已发布
+v0.6.3 "Relationship Auto-Discovery" ✅ 已发布
+v0.6.4 "Polish & Wrap" （本设计文档正在规划）
+
+**修改点：**
+
+- 在 "v0.6.1 — Actionable Update Suggestions ✅ 已发布" 之后追加 v0.6.2、v0.6.3 两条
+- 主题、核心交付、推迟到 v0.7+ 的项各列一项
+- 在末尾"未决事项" 增 v0.7.0 "通用化基础" 候选方向
+- 本文档（v0.6.4 pre-design）作为 v0.6.4 条目的设计依据引用
+
+---
+
+## 五、P1 详细设计
+
+### 5.1 rename trimStart 修复（任务 1）
+
+**现状：**
+
+`src/commands/rename.ts` 的 `splitFrontmatter()` 调用 `body.trimStart()`。
+v0.6.2 pre-design §十一 末尾明确：
+
+> 已知非阻塞 P2：rename.ts 的 splitFrontmatter() 对 body 做了 trimStart()，
+> 因此"完全保留 body 原始空白"的说法不严谨。
+> 后续 polish 可改为记录 frontmatter end 后的原始 body slice。
+
+**修改点：**
+
+```typescript
+// 之前
+function splitFrontmatter(content: string): { frontmatter: string; body: string } {
+  // ... 解析 frontmatter
+  return { frontmatter, body: parsed.body.trimStart() };  // ← trimStart 多余
+}
+
+// 之后
+function splitFrontmatter(content: string): { frontmatter: string; body: string } {
+  // 找到 '---' 结束行
+  const fmEnd = content.indexOf('\n---');
+  if (fmEnd === -1) return { frontmatter: '', body: content };
+  const slice = content.slice(fmEnd + 4);
+  // 跳过 '---' 后的第一个换行（如果有）
+  const bodyStart = slice.startsWith('\n') ? 1 : 0;
+  return { frontmatter: content.slice(0, fmEnd + 4), body: slice.slice(bodyStart) };
+  // 保留原始空白
+}
+```
+
+**DoD：**
+
+- body 原始空白逐字节保留（除 user 显式编辑外）
+- 补单测覆盖：body 前导空格、body 前导 \n\n、body 前导空行 + 普通内容
+- 重新跑 E2E `pmem rename` 套件，frontmatter hash 不变
+
+### 5.2 integration 模板版本化（任务 2）
+
+**现状：**
+
+`src/core/manifest.ts:142-144` 的 `ManifestIntegration.template_version` 字段已定义，
+但 `src/commands/integration.ts` 的 `verify` 子命令**未读这个字段**——只检查文件存在。
+
+**修改点：**
+
+**a) 集成模板安装时写入 version 标记：**
+
+```yaml
+# .pmem/integrations/claude-code/CLAUDE.md (顶部 frontmatter)
+---
+pmem_integration_version: '0.6.4'
+last_pmem_version: '0.6.3'
+---
+```
+
+**b) verify 时比较：**
+
+```typescript
+// integration verify
+const manifestTemplateVersion = manifest.integrations.claude_code?.template_version;
+const installedVersion = parseFrontmatter(fs.readFileSync(installedPath))?.pmem_integration_version;
+
+if (manifestTemplateVersion && installedVersion !== manifestTemplateVersion) {
+  issues.push({
+    severity: 'warning',
+    type: 'integration_stale_template',
+    message: `Integration template for ${framework} is stale: installed v${installedVersion}, manifest expects v${manifestTemplateVersion}.`,
+    fix: `Run: pmem integration install ${framework} --force`,
+  });
+}
+```
+
+**DoD：**
+
+- `pmem integration install` 写入 `pmem_integration_version` 到集成文件 frontmatter
+- `pmem integration verify` 比较版本，不匹配时输出 warning
+- 旧项目（无 version 字段）不报错，输出 "version unknown" 提示
+
+### 5.3 Codex / Cursor 深度入口（任务 3）
+
+**现状：**
+
+v0.6.0 已交付 Claude Code 的 `.claude/commands/pmem-*.md` 入口。
+Codex / Cursor / Windsurf / Copilot 的"深度入口"未实现。
+Codex 当前只有 `.pmem/integrations/codex/AGENTS.md`（agent instructions，非 slash command）。
+
+**修改点：**
+
+**a) Codex entry：**
+
+`.pmem/integrations/codex/AGENTS.md` 已有。增加：
+
+- `.codex/commands/pmem-recall.md`（codex command 形式）
+- `.codex/commands/pmem-ask.md`
+- `.codex/commands/pmem-update.md`
+- `.codex/commands/pmem-distill.md`
+
+或按 Codex 当前实际支持的 command 形式（pending 调研）。
+
+**b) Cursor entry：**
+
+- `.cursor/commands/pmem-recall.md`
+- `.cursor/commands/pmem-ask.md`
+- `.cursor/commands/pmem-update.md`
+- `.cursor/commands/pmem-distill.md`
+
+**c) `pmem integration install` 扩展：**
+
+- `pmem integration install codex` 生成 Codex entry
+- `pmem integration install cursor` 生成 Cursor entry
+- `pmem integration list` 增加 `codex` / `cursor` 深度入口支持
+
+**DoD：**
+
+- 4 个 slash command 文件 (recall/ask/update/distill) 在 codex 和 cursor 下都生成
+- `pmem integration verify` 检测这些 entry 存在
+- E2E 覆盖 integration install codex / cursor
+
+**调研节点：**
+
+开工前需先查 Codex 和 Cursor 的实际 command 文件形式（v0.6 阶段可能已有规范）。
+若 Codex/Cursor 实际不支持等价 slash command，改为在 AGENTS.md / .cursor/rules/pmem.mdc 中
+明示 "调用 pmem 应当执行 `pmem recall --budget 2000`" 的等价命令。
+
+---
+
+## 六、P2 详细设计
+
+### 6.1 session start --create-if-missing 评估（任务 4）
+
+**目标：**
+
+仅为 design 评估，不实现。
+
+**评估输出：**
+
+- 现有 `pmem session start` 在 `.pmem/` 不存在时行为是什么？
+- 加 `--create-if-missing` option 的风险面：自动创建可能掩盖"用户在错目录跑 pmem"的问题
+- 推荐决策：实现 / 推迟 / 放弃 + 理由
+
+**DoD：**
+
+- 评估报告写进 `docs/handover-v0.6.4.md` §session start 探测章节
+- 决策明确：实现则附 pre-design 草稿；推迟则附 v0.7+ 评估锚点
+
+### 6.2 doctor lock 可读性（任务 6）
+
+**现状：**
+
+v0.6.2 已实现 doctor lock 三种状态输出。`active` 状态只显示 "Lock held by <pid>"。
+
+**修改点：**
+
+```typescript
+// 之前
+Lock: ✗ Active lock held at .pmem/.lock (age: 2s). Another pmem process may be running.
+
+// 之后
+Lock: ✗ Active lock held at .pmem/.lock
+        Owner: pmem (PID: 12345)
+        Age: 2s (stale threshold: 60s)
+        → If another pmem is not actually running, wait 60s and run: pmem verify --fix-locks
+        → Or check process: ps -p 12345
+```
+
+**DoD：**
+
+- 列出 lock age、owner pid、stale 阈值
+- 给出明确的下一步建议
+- E2E 覆盖三种状态
+
+### 6.3 --guided 缺字段引导（任务 7）
+
+**现状：**
+
+`src/commands/init.ts` 的 `--guided` 模式在缺 `--description` / `--stage` / `--next` 时
+使用空字符串或默认值，没有明确告知用户"还差哪些参数"。
+
+**修改点：**
+
+```bash
+# 之前
+$ pmem init my-project --guided
+# 静默使用空 description
+
+# 之后
+$ pmem init my-project --guided
+⚠ Missing --description. --guided works best with all three context flags.
+  You can re-run with: pmem init my-project --guided \
+    --description "<one-line project purpose>" \
+    --stage "<current stage>" \
+    --next "<immediate next step>"
+  Or answer via: pmem init my-project --guided --answers ./pmem-init.json
+```
+
+**DoD：**
+
+- 三个字段任一缺失时输出可补参数提示
+- 不阻断流程（仍能 init 成功，但提示更明显）
+- E2E 覆盖三种缺失场景
+
+### 6.4 rename --dry-run frontmatter diff（任务 8）
+
+**现状：**
+
+`pmem rename` 当前只对 body 生效。但用户重命名项目时常会改 `aliases` / `tags` /
+`related` 字段。当前需要 `rename --write` 不动这些字段，用户得手动编辑。
+
+**修改点：**
+
+`--dry-run` 模式在 frontmatter 字段（`aliases`, `tags`, `related`, `depends_on`）
+命中 `find` 模式时，输出 diff 预览：
+
+```
+File: .pmem/characters/zhangsan.md
+Frontmatter: aliases
+  - "张三"
+  + "张小三"   (alias #0, replacement of "张三")
+```
+
+**注意：** `--write` 模式**不动** frontmatter 字段（仍只改 body）。
+`--dry-run` 显示 frontmatter 命中是"给用户一个完整的变更预览"，让用户知道
+"如果想改这些字段，需要手动编辑"。
+
+**DoD：**
+
+- `--dry-run` 模式扫描 frontmatter 字段并显示 diff
+- `--write` 模式**不**改 frontmatter（保持 v0.6.2 安全语义）
+- E2E 覆盖：frontmatter 命中 + body 命中 + 两者都命中的 dry-run 输出
+
+---
+
+## 七、测试计划
+
+### P0 测试
+
+- session 状态丢失：复现脚本 + 根因报告
+- roadmap 文档同步：grep 验证 v0.6.2/0.6.3/0.6.4 都出现在 roadmap
+
+### P1 测试
+
+| 测试项 | 类型 |
+|--------|------|
+| rename body 原始空白保留（前导空格、\n\n、空行） | 单元 |
+| rename frontmatter hash 不变 | E2E（已存在，重新跑） |
+| integration install 写入 pmem_integration_version | 单元 |
+| integration verify 比较 template_version | 单元 |
+| integration install codex 生成 4 个 command 文件 | E2E |
+| integration install cursor 生成 4 个 command 文件 | E2E |
+
+### P2 测试
+
+- doctor lock active 状态输出 age + pid + 下一步建议
+- init --guided 缺字段提示
+- rename --dry-run frontmatter diff 输出
+
+### 通用
+
+- `npm test` 通过
+- CI 通过（Node 18/20/22）
+- 旧 E2E 套件不退步
+
+---
+
+## 八、无 schema migration
+
+v0.6.4 不改变 manifest schema_version、不改变卡片 frontmatter 结构、不改变数据库表结构。
+
+变更仅涉及：
+- CLI 行为（rename body 不 trimStart、integration 写 version 字段、init --guided 提示）
+- 模板内容（Codex / Cursor command 文件新增）
+- 文档（roadmap 同步、handover-v0.6.4.md 新建）
+
+所有现有 `.pmem/` 目录在 v0.6.4 下无需迁移即可正常使用。
+对 `pmem_integration_version` 字段的引入采用**前向兼容**策略：
+- 旧项目无此字段 → `verify` 输出 "version unknown" 提示，不报错
+- 新安装的 integration 写入此字段
+
+---
+
+## 九、与 v0.7.0 的关系
+
+v0.6.4 与 v0.7.0 的边界：
+
+| 维度 | v0.6.4 | v0.7.0 |
+|------|--------|--------|
+| 主题 | Polish & Wrap v0.6 | Universal Agent Memory |
+| 改动范围 | rename / integration / init --guided / session / doctor | 类型系统 / status / recall / manifest 通用化 |
+| schema 变更 | 无 | 可能（card_types / type_dirs / foundational_types 新字段） |
+| 风险面 | 低（局部 polish） | 中（manifest schema 变化） |
+| 主线 | 收尾 v0.6 track | 启动 v0.7 track |
+
+**v0.6.4 完成后开 v0.7.0 分支**：v0.6.4 不并发 v0.7.0 准备工作。
+v0.7.0 详细设计另写 `docs/v0.7.0 pre-design.md`，
+不放在本文档中（保持每个 pre-design 文档的 scope 单一）。
+
+---
+
+## 十、DoD
+
+### 通用
+
+- [ ] `npm test` 通过
+- [ ] 旧 E2E 套件不退步
+- [ ] CI 通过（Node 18/20/22）
+- [ ] `CHANGELOG.md` 追加 v0.6.4 条目
+- [ ] `docs/project-roadmap.md` 补 v0.6.2 / v0.6.3 / v0.6.4 三条
+
+### P0
+
+- [ ] session 状态丢失根因报告 + 复现脚本
+- [ ] 若有修复，附 E2E 验证
+
+### P1
+
+- [ ] rename body 原始空白保留
+- [ ] integration template_version 字段写入 + verify 比较
+- [ ] Codex / Cursor 深度入口（4 个 command 文件 / 框架）
+
+### P2
+
+- [ ] doctor lock 可读性 polish
+- [ ] init --guided 缺字段提示
+- [ ] rename --dry-run frontmatter diff
+- [ ] session start --create-if-missing design 评估
+
+---
+
+## 十一、审批记录
+
+| 角色 | 决定 | 日期 |
+|------|------|------|
+| 提交人 | Claude Opus 4.6 | 2026-06-02 |
+| CTO | 待审批 | 2026-06-02 |
+
+### 调研来源
+
+本 pre-design 的 8 项 polish 任务来源：
+
+1. `docs/v0.6.2 pre-design.md` §三 末尾（"已知非阻塞 P2"）—— 任务 1
+2. `docs/v0.6.2 pre-design.md` §4.1d + §11 末尾 —— 任务 5、6
+3. `docs/v0.6.2 pre-design.md` §4.3 —— 任务 8
+4. `docs/v0.6 pre-design.md` §九 P1#4 —— 任务 2
+5. `docs/v0.6 pre-design.md` §九 P2 —— 任务 3、7
+6. `docs/handover-v0.6.md` §九 —— 任务 3、4
+
+并发限制：v0.6.4 完成后才开 v0.7.0 分支（按 CTO 2026-06-02 决策）。