pmem-ai 0.5.0 → 0.6.0

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

@@ -0,0 +1,550 @@
+# v0.6 前置设计决策
+
+本文档记录 pmem v0.6 开工前的产品与技术规划。v0.6 的核心定位：
+
+> **Agent-native Workflow Polish**
+>
+> v0.5 已经完成 Beta 开发并上线 npm，证明 pmem 可以作为一个可安装、可理解、可验证的 CLI 产品被真实项目使用。
+>
+> v0.6 不追求 embedding、MCP/REST、Graph UI、遥测或远程服务。
+> v0.6 的目标是：把 v0.5 已经成立的本地记忆运行时，打磨成更适合 AI Agent 程序化调用、跨会话恢复、无人工兜底使用的工具。
+>
+> v0.6 要回答的唯一问题：**pmem 能否在真实 Agent 工作流里低摩擦地启动、调用、失败恢复，并让第一次使用也能感受到清楚的下一步？**
+
+---
+
+## 一、背景：v0.5 Beta 真实使用反馈
+
+v0.5 上线后，实际使用 pmem 进行辅助记忆的 Agent 反馈出一个关键结论：
+
+> pmem 的价值不在单次长会话里立刻显现，而在跨会话场景中显现。
+
+这与 pmem 的产品定位一致。单次连续开发时，对话上下文仍然足够；但下次重新打开项目时，`pmem recall`、`pmem ask`、`pmem status`、`pmem update` 和 `pmem verify` 才会把历史决策、模块关系、变更影响和下一步恢复出来。
+
+同时，反馈暴露出 v0.5 Beta 的下一批摩擦点：
+
+| 反馈 | 本质问题 |
+|------|----------|
+| `init --guided` 只能交互式回答，Agent 难以脚本化 | CLI 仍偏人类终端使用，而非 Agent-native |
+| `mark-dirty --auto` 在非 git 场景出现 raw stack trace | 错误 UX 不足，Agent 无法可靠判断下一步 |
+| `update --suggest --format json` 在空项目返回空数组，无解释 | 首次使用缺少引导和价值感 |
+| `session end` 未 start 时只报 `No active session` | session workflow 对 Agent 不够容错 |
+| `.pmem/skills/*.md` 没有注册成 Claude Code slash commands | integration 文件存在，但未成为目标框架可直接调用的入口 |
+
+v0.6 的设计围绕这些真实反馈展开。
+
+---
+
+## 二、v0.6 产品目标
+
+v0.6 的目标不是扩大 pmem 的能力边界，而是降低已有能力在真实 Agent 环境里的调用摩擦。
+
+### 一句话目标
+
+> **任何 code agent 都能非交互式初始化 pmem、按框架入口调用 pmem workflow、读懂空结果和错误提示，并在跨会话时恢复项目记忆。**
+
+### 用户对象
+
+| 用户 | 需求 |
+|------|------|
+| Code agent | 不依赖 TTY 交互，能用命令参数、JSON、文件和 exit code 自动完成 workflow |
+| 项目维护者 | 能为不同 Agent 框架安装真实可用的入口，而不只是阅读文档 |
+| 首次试用者 | 即使项目没有 memory cards，也知道下一步该创建什么、为什么 |
+| Beta 反馈者 | 能报告具体命令、错误、输出和 integration 状态 |
+
+### 成功标准
+
+1. `pmem init --guided` 有非交互式等价路径，可被脚本和 Agent 稳定调用。
+2. 非 git 项目、缺少 git、空项目、未开始 session 等场景没有 raw stack trace。
+3. `update --suggest`、`ask`、`recall` 等空结果输出包含可操作 next step。
+4. `pmem integration install claude-code` 能生成 Claude Code 可直接调用的 slash command 文件。
+5. `pmem integration verify` 能检查框架入口是否真的存在，而不只检查 `.pmem/integrations/` 模板目录。
+6. README / AGENTS / CLAUDE / integration templates 明确解释：pmem 的核心价值在跨会话项目记忆。
+7. 新增 E2E 覆盖非交互 init、Agent integration install、空项目引导、非 git 错误 UX。
+
+---
+
+## 三、v0.6 不做的事情（范围排除）
+
+以下方向继续不进入 v0.6 主线，除非真实 Beta 用户证明它们是 adoption 阻塞项。
+
+| 排除项 | 原因 |
+|--------|------|
+| API embedding / local embedding | v0.6 关注 Agent 调用摩擦，不引入模型、API key、成本和隐私变量 |
+| `pmem serve` / MCP / REST | 服务化会扩大协议面；当前反馈集中在 CLI 与 integration |
+| Graph UI | UI 不能解决当前最痛的非交互、错误 UX、框架入口问题 |
+| 遥测 | Beta 反馈继续依赖显式采访、issue、E2E 复现 |
+| 远程同步 / 多用户服务 | 与本地 CLI runtime 定位不一致 |
+| 自动 session 大规模行为改造 | 可以改进容错和提示，但不让 session 隐式行为变得不可解释 |
+| 数据库作为 memory 主源 | Markdown cards 仍是唯一 source of truth |
+
+v0.6 的克制原则：**只做让 pmem 更适合 Agent 程序化使用的打磨。**
+
+---
+
+## 四、v0.6 目标闭环
+
+```txt
+Agent / developer 安装 pmem
+  ↓
+非交互式 pmem init
+  ↓
+安装目标框架 integration
+  ↓
+通过 slash command / AGENTS / CLAUDE 入口运行 recall
+  ↓
+首次空项目得到下一步引导
+  ↓
+Agent 修改代码
+  ↓
+pmem status / mark-dirty 在 git 或非 git 项目都给可诊断输出
+  ↓
+pmem update --suggest 给出建议或解释为什么没有建议
+  ↓
+pmem update --confirm 写入 trace / update log
+  ↓
+pmem verify 检查一致性
+  ↓
+下一次会话用 pmem recall 恢复跨会话上下文
+```
+
+这条链路是 v0.6 的产品回路。v0.6 的所有 P0 都必须服务这条回路。
+
+---
+
+## 五、优先级表
+
+### P0 — 必须完成
+
+| # | 功能 | 说明 |
+|---|------|------|
+| 1 | 非交互 init | 为 `init --guided` 增加参数或文件输入，支持 Agent 和 CI 脚本稳定初始化 |
+| 2 | git 前置检查与友好错误 | `mark-dirty --auto` / `status` 在无 git、非 git repo、git 不可用时给出清楚提示 |
+| 3 | 空结果引导 | `update --suggest`、`ask`、必要时 `recall` 在空项目或无匹配时输出 next step |
+| 4 | session 容错 UX | `session end` 无 active session 时给出可操作建议；评估是否支持 `--create-if-missing` |
+| 5 | Claude Code slash commands | `integration install claude-code` 生成 `.claude/commands/pmem-*.md` |
+| 6 | integration verify 增强 | 检查 root files、settings、slash commands、Cursor rules、Codex AGENTS 入口是否存在 |
+| 7 | Agent-native E2E | 覆盖非交互 init、integration install、空结果引导、非 git fallback |
+| 8 | 全局 skills 安装 | `pmem install --skills --claude/--codex/--gemini` 一键安装 skill 到 agent 全局目录 |
+| 9 | 文档口径同步 | README / AGENTS / CLAUDE / integration templates 增加跨会话价值和 Agent-native 调用说明 |
+
+### P1 — 应该完成
+
+| # | 功能 | 说明 |
+|---|------|------|
+| 1 | JSON answers 文件 | 在命令参数之外支持 `pmem init --answers <file.json>`，便于复杂初始化和模板化 |
+| 2 | `--format json` 的 message 字段 | 对空结果和 warnings 提供机器可读 `message` / `next_steps` |
+| 3 | `pmem doctor` 评估 | 先设计是否需要统一诊断命令；默认不作为 P0 |
+| 4 | integration 模板版本化 | 记录模板版本，并在 verify 中提示旧模板 |
+| 5 | 首次使用 recipe | README 增加 "first memory card" 和 "second session" 示例 |
+| 6 | release checklist v0.6 | 独立记录 v0.6 发布前检查项 |
+
+### P2 — 可推迟
+
+| 功能 | 说明 |
+|------|------|
+| Cursor / Windsurf / Codex 深度命令入口 | v0.6 优先 Claude Code slash commands；其他框架先保持模板文档 |
+| 自动 session start | 可能隐藏 workflow 状态，先用提示和显式 option 验证 |
+| interactive wizard 重写 | 当前问题是非交互缺口，不是终端 UI 体验 |
+| 示例视频 / 网站 | README 和 docs 足以承载 v0.6 |
+
+---
+
+## 六、关键设计
+
+### 1. 非交互 init
+
+推荐新增两条路径：
+
+```bash
+pmem init MyProject --guided \
+  --description "Project Memory for AI Agents" \
+  --stage "v0.6 planning" \
+  --next "Implement agent-native workflow polish"
+```
+
+```bash
+pmem init MyProject --answers ./pmem-init.json
+```
+
+`pmem-init.json` 示例：
+
+```json
+{
+  "description": "Project Memory for AI Agents",
+  "stage": "v0.6 planning",
+  "next": "Implement agent-native workflow polish"
+}
+```
+
+设计原则：
+
+1. `--guided` 继续保留给人类用户。
+2. 当三个字段都由参数或 answers 文件提供时，不打开 readline。
+3. 参数优先级高于 answers 文件，便于脚本覆盖单个字段。
+4. 缺字段时应报出缺少哪些字段，并提示可用参数，不进入半交互状态。
+5. JSON 文件字段命名要稳定，避免未来破坏脚本。
+
+### 2. 错误 UX 与 exit code
+
+v0.6 不改变既有 workflow signal exit code 语义，但要保证错误可诊断。
+
+示例：
+
+```txt
+Cannot auto-detect changed files because this directory is not a git repository.
+Next: run `pmem status --since <timestamp>` or initialize git with `git init`.
+```
+
+```txt
+No active pmem session found.
+Next: run `pmem session start -a "<agent-name>"`, or use `pmem session end --allow-missing` if this is expected.
+```
+
+JSON 输出建议：
+
+```json
+{
+  "ok": true,
+  "suggestions": [],
+  "message": "No memory cards are dirty yet.",
+  "next_steps": [
+    "Run pmem mark-dirty --auto after editing files.",
+    "Create a first module card with source_files if this is a new project."
+  ]
+}
+```
+
+### 3. 空项目首次价值感
+
+空项目不能只给空数组。pmem 应该把"没有记忆"解释为一个可推进状态。
+
+`update --suggest` 空结果应区分：
+
+| 场景 | 输出 |
+|------|------|
+| 没有 cards | 提示创建第一张 module / decision / task card |
+| 有 cards 但没有 dirty flags | 提示运行 `status` / `mark-dirty --auto` |
+| 有 dirty flags 但无法匹配 source files | 提示补充 `source_files` |
+| 已经全部 clean | 提示 `verify` 或继续开发 |
+
+### 4. Claude Code slash commands
+
+`pmem integration install claude-code` 应生成：
+
+```txt
+.claude/
+  commands/
+    pmem-recall.md
+    pmem-ask.md
+    pmem-update.md
+    pmem-distill.md
+```
+
+建议命令：
+
+| Slash command | pmem workflow |
+|---------------|---------------|
+| `/pmem-recall` | `pmem recall --format compact --budget 2000` |
+| `/pmem-ask <query>` | `pmem ask "<query>" --format compact` |
+| `/pmem-update` | `status` → `mark-dirty --auto` → `update --suggest` → confirm guidance |
+| `/pmem-distill` | `pmem distill --suggest` → optional confirm → `verify` |
+
+这些文件不应只是说明文档，而应成为 Claude Code 能直接发现的 command entry。
+
+### 5. Integration verification
+
+`pmem integration verify` 在 v0.6 应检查：
+
+| Framework | 检查项 |
+|-----------|--------|
+| claude-code | root `CLAUDE.md`、`.claude/settings.json`、`.claude/commands/pmem-*.md` |
+| cursor | `.cursor/rules/pmem.mdc` |
+| codex | root `AGENTS.md` 或指定 integration template |
+| all | `.pmem/integrations/<framework>/` 模板版本与 manifest 记录 |
+
+verify 输出必须告诉用户缺失文件的生成命令。
+
+### 6. Global skills installation
+
+参考 playwright-cli 的 `install --skills` 模式。pmem 包自带 `skills/pmem/` 目录，包含符合 agent skill 规范的 `SKILL.md` 和 `references/` 参考文档。
+
+```bash
+pmem install --skills --claude    # → ~/.claude/skills/pmem/
+pmem install --skills --codex     # → ~/.codex/skills/pmem/
+pmem install --skills --gemini    # → ~/.gemini/skills/pmem/
+pmem install --skills --all       # → 全部检测到的 agent 目录
+```
+
+Skill 文件格式遵循 agent skill 规范：
+
+```yaml
+---
+name: pmem
+description: Project memory for AI agents — recall, ask, update, verify
+allowed-tools: Bash(pmem:*)
+---
+```
+
+目录结构：
+
+```txt
+skills/pmem/
+  SKILL.md              # 主 skill 文件（命令参考 + 工作流示例）
+  references/
+    session-workflow.md  # session start → recall → ask → update → verify → session end
+    first-init.md        # 首次初始化步骤
+    troubleshooting.md   # 常见问题
+```
+
+与 `pmem init` 生成的项目级 `.pmem/skills/` 不同，全局 skills 让 agent 在任何项目中都能被引导使用 pmem，而项目级 skills 提供该项目的具体记忆维护指引。
+
+安装逻辑：
+1. 读取 pmem 包内 `skills/pmem/` 目录
+2. 复制到目标 agent 的全局 skills 目录（`~/.claude/skills/pmem/` 等）
+3. 若目标目录已存在，覆盖更新
+4. `--all` 模式检测用户机器上存在的 agent 并全部安装
+
+---
+
+## 七、E2E 测试设计
+
+v0.6 E2E 应继续放在 `temp/` 下，避免污染仓库。
+
+### E2E 1：non-interactive init
+
+```bash
+mkdir -p temp/e2e-v06-init
+cd temp/e2e-v06-init
+pmem init v06-init \
+  --guided \
+  --description "v0.6 init smoke" \
+  --stage "Agent-native beta" \
+  --next "Run recall"
+pmem rebuild
+pmem recall --format compact --budget 2000
+pmem verify
+```
+
+验收：
+
+- 命令不等待 TTY。
+- 初始化内容进入 `.pmem/index.md` / `.pmem/state.md` / `.pmem/next.md` 或等价卡片。
+- `verify` 可诊断通过或给出可操作 warning。
+
+### E2E 2：answers file init
+
+```bash
+cat > temp/pmem-init.json <<'JSON'
+{
+  "description": "answers file smoke",
+  "stage": "v0.6",
+  "next": "Install integration"
+}
+JSON
+
+pmem init v06-answers --answers temp/pmem-init.json
+```
+
+验收：
+
+- JSON 可解析。
+- 缺字段有清楚错误。
+- 参数能覆盖 answers 文件字段。
+
+### E2E 3：Claude Code integration
+
+```bash
+pmem init v06-claude --description "x" --stage "y" --next "z"
+pmem integration install claude-code
+pmem integration verify
+```
+
+验收：
+
+- 生成 `CLAUDE.md`。
+- 生成 `.claude/commands/pmem-recall.md` 等 slash command 文件。
+- verify 能列出 installed / missing 状态。
+
+### E2E 4：empty result guidance
+
+```bash
+pmem init v06-empty --description "x" --stage "y" --next "z"
+pmem rebuild
+pmem update --suggest --format json
+pmem ask "filters" --format json
+```
+
+验收：
+
+- 空结果包含人类可读 message。
+- JSON 输出包含机器可读 next steps。
+- exit code 保持文档约定。
+
+### E2E 5：non-git UX
+
+```bash
+mkdir -p temp/e2e-v06-non-git
+cd temp/e2e-v06-non-git
+pmem init non-git --description "x" --stage "y" --next "z"
+pmem status --format json
+pmem mark-dirty --auto
+```
+
+验收：
+
+- 没有 raw stack trace。
+- 输出说明使用 mtime fallback 或解释 git requirement。
+- exit code 与文档一致。
+
+### E2E 6：skills install
+
+```bash
+pmem install --skills --claude
+pmem install --skills --codex
+pmem install --skills --all
+```
+
+验收：
+- `~/.claude/skills/pmem/SKILL.md` 存在且内容正确。
+- `~/.codex/skills/pmem/SKILL.md` 存在且内容正确。
+- `--all` 安装到所有可用 agent 目录。
+
+---
+
+## 八、文档设计
+
+### README.md 更新
+
+新增或强化：
+
+1. "When pmem helps"：单次会话 vs 跨会话价值。
+2. "Agent-native init"：非交互初始化示例。
+3. "First memory card"：如何创建第一张有 `source_files` 的 module card。
+4. "Second session test"：关闭上下文后用 `pmem recall` 恢复。
+5. "Integrations"：Claude Code slash commands、Codex AGENTS、Cursor rules。
+
+### AGENTS.md / CLAUDE.md 更新
+
+需要把当前开发轨道改为 v0.6，并明确：
+
+- v0.5 已完成 Beta 与 npm 上线。
+- v0.6 聚焦 Agent-native workflow polish。
+- 不引入 embedding、MCP/REST、Graph UI、telemetry。
+- 当前最高优先级是非交互 init、错误 UX、空结果引导、Claude Code slash commands。
+
+### Integration templates 更新
+
+`.pmem/integrations/*` 模板应与 root `AGENTS.md` / `CLAUDE.md` 一致，避免新项目初始化后得到过时指令。
+
+---
+
+## 九、实现顺序
+
+```txt
+Step 0: 冻结 v0.6 pre-design（本文档）
+  ↓
+Step 1: 非交互 init
+  - CLI options
+  - answers JSON
+  - validation / tests
+  ↓
+Step 2: Error UX pass
+  - git 前置检查
+  - session missing UX
+  - empty result guidance
+  ↓
+Step 3: Claude Code integration
+  - slash command templates
+  - install output
+  - verify checks
+  ↓
+Step 4: Global skills installation
+  - skills/pmem/SKILL.md + references/
+  - pmem install --skills command
+  - E2E
+  ↓
+Step 5: Agent-native E2E
+  - non-interactive init
+  - integration install
+  - empty guidance
+  - non-git UX
+  - skills install
+  ↓
+Step 6: Docs sync
+  - README
+  - AGENTS / CLAUDE
+  - integration templates
+  - release checklist v0.6
+```
+
+---
+
+## 十、v0.6 验收清单
+
+### 产品验收
+
+- [ ] 新用户能不用 TTY 初始化 pmem。
+- [ ] Agent 能通过 Claude Code slash commands 触发核心 workflow。
+- [ ] 空项目和空结果都有下一步建议。
+- [ ] 非 git / git 不可用 / session missing 没有 raw stack trace。
+- [ ] 新用户可一键安装 pmem skills 到 Claude Code / Codex / Gemini 全局目录。
+- [ ] Skills 文件符合 agent skill 规范 (SKILL.md + references/)。
+- [ ] README 明确解释 pmem 的跨会话价值。
+
+### 工程验收
+
+- [ ] `npm test` 通过。
+- [ ] `npm run build` 通过。
+- [ ] 非交互 init E2E 通过。
+- [ ] answers file init E2E 通过。
+- [ ] Claude Code integration E2E 通过。
+- [ ] empty result guidance E2E 通过。
+- [ ] non-git UX E2E 通过。
+
+### 发布验收
+
+- [ ] `CHANGELOG.md` 包含 v0.6.0。
+- [ ] package version / lockfile / CLI version 一致。
+- [ ] npm pack smoke 通过。
+- [ ] release checklist v0.6 通过。
+
+---
+
+## 十一、v0.6 最终决策表
+
+| 问题 | 最终决策 |
+|------|---------|
+| v0.6 主线 | Agent-native Workflow Polish |
+| 是否做 embedding | 不做 |
+| 是否做 MCP / REST / serve | 不做 |
+| 是否做 Graph UI | 不做 |
+| 是否做 telemetry | 不做 |
+| 是否新增非交互 init | 做，P0 |
+| 是否生成 Claude Code slash commands | 做，P0 |
+| 是否做全局 skills 安装 | 做，P0，参考 playwright-cli install --skills 模式 |
+| 是否自动 session start | 暂不默认做，先改错误 UX 和显式 option |
+| 是否改变 Markdown source of truth | 不改变 |
+| 最重要交付 | 非交互 init + 错误 UX + 空结果引导 + Agent integration 入口 |
+| v0.6 成功定义 | Agent 可以低摩擦、可脚本化地使用 pmem 完成跨会话记忆 workflow |
+
+---
+
+## 十二、v0.6 一句话定义
+
+> **pmem v0.6 是把 v0.5 的 Beta CLI 打磨成 Agent-native、可脚本化、错误可诊断、跨会话价值更清楚的项目记忆运行时。**
+
+更工程化：
+
+```txt
+pmem v0.6 =
+  v0.5 npm Beta
++ non-interactive init
++ actionable empty states
++ friendlier error UX
++ session workflow tolerance
++ Claude Code slash commands
++ integration verification
++ global skills installation
++ Agent-native E2E
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmem-ai",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Project Memory for AI Agents: a local CLI runtime for project context, recall, and memory updates",
   "main": "dist/index.js",
   "bin": {
@@ -13,7 +13,13 @@
     "test": "node --require ts-node/register --test src/core/*.test.ts",
     "test:e2e:install": "bash scripts/e2e-install-smoke.sh",
     "test:e2e:workflow": "bash scripts/e2e-real-workflow.sh",
-    "test:e2e:non-git": "bash scripts/e2e-non-git-fallback.sh"
+    "test:e2e:non-git": "bash scripts/e2e-non-git-fallback.sh",
+    "test:e2e:v06-init": "bash scripts/e2e-v06-non-interactive-init.sh",
+    "test:e2e:v06-answers": "bash scripts/e2e-v06-answers-file.sh",
+    "test:e2e:v06-claude": "bash scripts/e2e-v06-claude-integration.sh",
+    "test:e2e:v06-empty": "bash scripts/e2e-v06-empty-guidance.sh",
+    "test:e2e:v06-nongit": "bash scripts/e2e-v06-non-git-ux.sh",
+    "test:e2e:v06-skills": "bash scripts/e2e-v06-skills.sh"
   },
   "keywords": [
     "agent",
@@ -47,6 +53,7 @@
     "!dist/**/*.test.js.map",
     "!dist/**/*.test.d.ts",
     "!dist/**/*.test.d.ts.map",
+    "skills/**/*.md",
     "README.md",
     "CHANGELOG.md",
     "LICENSE",