pmem-ai 0.5.0

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

@@ -0,0 +1,481 @@
+# v0.5 前置设计决策
+
+本文档记录 pmem v0.5 开工前的最终产品与技术决策。v0.5 的核心定位：
+
+> **Productization Beta**
+>
+> 不是继续堆新能力，不是 embedding，不是 MCP/REST 服务，也不是 Graph UI。
+> 而是：把 v0.4 已经跑通的 Agent Workflow Runtime 包装成一个真实项目可以安装、理解、运行、验证、反馈的 Beta 产品。
+>
+> v0.5 要回答的唯一问题：**pmem 能否作为一个可上线的 CLI 产品，被真实 code agent 和开发者稳定使用？**
+
+---
+
+## 一、v0.5 产品目标
+
+v0.4 已经证明 pmem 可以进入真实 agent 开发工作流。v0.5 不再证明"能不能跑"，而是证明"别人能不能顺利用起来"。
+
+### 一句话目标
+
+> **任何熟悉 CLI 的开发者或 code agent，都能从安装 pmem 开始，在一个真实项目里完成一次完整 memory workflow，并知道每一步为什么发生、失败时该怎么办。**
+
+### 用户对象
+
+| 用户 | 需求 |
+|------|------|
+| 项目维护者 | 安装 pmem、初始化项目记忆、理解目录结构和命令 |
+| Code agent | 低 token 恢复上下文、感知代码变更、维护 memory cards |
+| 早期试用者 | 跟随 README 完成 quick start，并能报告具体问题 |
+
+### 成功标准
+
+1. 从 `npm pack` 产物安装后，`pmem --version`、`pmem init`、`pmem rebuild`、`pmem recall` 可直接运行。
+2. README 能独立解释 pmem 是什么、适合谁、如何在 5 分钟内跑通。
+3. 一个真实项目 E2E 脚本覆盖：安装 → 初始化 → 创建 card → rebuild → recall/ask → status → mark-dirty → update suggest → verify。
+4. `CLAUDE.md`、`AGENTS.md`、integration templates 统一到 v0.5 产品口径。
+5. 常见失败场景有清楚错误提示：无 `.pmem`、无 DB、非 git 项目、空项目、损坏 DB、无匹配结果。
+6. release checklist 能指导一次可重复的 Beta 发布。
+
+---
+
+## 二、v0.5 不做的事情（范围排除）
+
+以下方向在 v0.5 明确不做，除非后续真实试用反馈证明它们是 Beta 上线阻塞项。
+
+| 排除项 | 原因 |
+|--------|------|
+| API embedding | v0.5 目标是产品化，不引入 API key、网络依赖、成本和隐私变量 |
+| local embedding | 包体积、跨平台、模型选择都不适合 Beta 产品主线 |
+| `pmem serve` / MCP / REST | CLI 已能满足 code agent 接入；服务化会扩大运维和协议面 |
+| Graph UI | UI 不是 Beta 可用性的前置条件 |
+| 多用户远程服务 | 超出本地 CLI 产品定位 |
+| 自动 commit message 生成 | 与 project memory 主线弱相关 |
+| 基础遥测 | Beta 阶段先用显式反馈和 issue，不采集用户数据 |
+| `pmem backup` / `pmem restore` 新命令 | 暂不新增命令；继续依赖迁移备份和 Git 版本控制 |
+| `pmem verify --report` 仪表板 | 可作为后续增强，不进入 v0.5 P0 |
+
+v0.5 的克制原则：**只做让现有能力变成产品所必需的事情。**
+
+---
+
+## 三、v0.5 目标闭环
+
+```
+开发者获取 pmem
+  ↓
+npm pack / npm install 安装
+  ↓
+pmem --version 确认 CLI 可用
+  ↓
+在真实项目中 pmem init / init --guided
+  ↓
+阅读 README / AGENTS.md / CLAUDE.md 接入 agent workflow
+  ↓
+pmem rebuild 建立 SQLite index
+  ↓
+pmem recall / ask 获取上下文
+  ↓
+开发者或 agent 修改代码
+  ↓
+pmem status / mark-dirty --auto
+  ↓
+pmem update --suggest / --confirm
+  ↓
+pmem verify 确认一致性
+  ↓
+按 release checklist 发布 Beta
+```
+
+这条链路是 v0.5 的"产品回路"。每一个 P0 都必须服务这条回路。
+
+---
+
+## 四、优先级表
+
+### P0 — 必须完成
+
+| # | 功能 | 说明 |
+|---|------|------|
+| 1 | README.md | 产品定位、安装、quick start、核心概念、agent workflow、命令参考、故障排查 |
+| 2 | npm package readiness | 修正 package metadata、files/bin、lockfile version、`npm pack` smoke test |
+| 3 | install E2E | 覆盖本地 pack 安装后的 CLI 路径，不只跑 `ts-node` |
+| 4 | real-project E2E | 在 `temp/` 中模拟真实项目，从 init 到 verify 完整闭环 |
+| 5 | Agent docs sync | 同步 `AGENTS.md`、`CLAUDE.md`、integration templates 到 v0.5 口径 |
+| 6 | Error UX pass | 梳理常见错误与 exit code，保证 agent 和人都能读懂 |
+| 7 | Release checklist | 版本号、build/test、pack、smoke、changelog、publish 前检查 |
+| 8 | Public command contract | 固化 v0.5 支持命令、输出格式、退出码，避免 README 与实现漂移 |
+
+### P1 — 应该完成
+
+| # | 功能 | 说明 |
+|---|------|------|
+| 1 | 示例项目 / demo fixture | 最小可运行 demo，用于 README 和 E2E |
+| 2 | CHANGELOG.md | 从 v0.1 到 v0.5 的用户可读版本记录 |
+| 3 | Troubleshooting 扩展 | DB 损坏、FTS5 不可用、非 git 项目、空项目等诊断步骤 |
+| 4 | `pmem doctor` 评估 | 先设计是否需要，默认不实现；若错误 UX 不足再考虑 |
+| 5 | CLI help 文案打磨 | Commander description / option help 与 README 对齐 |
+
+### P2 — 可推迟
+
+| 功能 | 说明 |
+|------|------|
+| npm public publish | v0.5.0 可以先做到可发布；是否实际 publish 由发布策略决定 |
+| GitHub issue templates | 外部公开后再补 |
+| 网站 / landing page | README 足够承载 Beta |
+| 性能专项优化 | 仅修 Beta E2E 暴露的明显性能问题 |
+
+---
+
+## 五、发布策略
+
+v0.5 采用两层发布标准：
+
+### Internal Beta Readiness
+
+必须满足：
+
+```bash
+npm test
+npm run build
+npm pack --dry-run
+npm pack
+npm install -g ./pmem-0.5.0.tgz
+pmem --version
+pmem init <project>
+pmem rebuild
+pmem recall
+pmem verify
+```
+
+Internal Beta 的目标是证明：**包产物可以被安装，安装后的二进制可以在真实目录工作。**
+
+### Public Beta Readiness
+
+在 Internal Beta 基础上增加：
+
+1. README 以外部用户视角完整可读。
+2. package metadata 可发布：name、version、description、license、bin、files、keywords、repository。
+3. CHANGELOG 记录 v0.5 的用户价值和 breaking notes。
+4. release checklist 逐项通过。
+5. 明确是否执行 `npm publish`，以及包名是否可用。
+
+v0.5.0 的开发目标是达到 **Public Beta Readiness**。是否真正公开发布，可在 release 前最后决定。
+
+---
+
+## 六、文档设计
+
+### README.md 结构
+
+README 是 v0.5 最重要的产品界面。建议结构：
+
+```markdown
+# pmem
+
+One-line value proposition.
+
+## Why pmem
+## Who it is for
+## Install
+## 5-minute Quick Start
+## Core Concepts
+  - Markdown cards
+  - SQLite runtime
+  - recall / ask
+  - dirty / update / distill
+## Agent Workflow
+## CLI Reference
+## Exit Codes
+## Project Layout
+## Troubleshooting
+## Roadmap
+## License
+```
+
+文档原则：
+
+1. 先告诉用户"为什么需要 pmem"，再告诉用户命令。
+2. 所有命令示例都必须能在 fresh clone + install 后运行。
+3. 不把历史设计细节塞进 README；历史细节留在 `docs/`。
+4. 对 agent 友好：给出可复制的 session start / session end 工作流。
+
+### Agent 指令文档
+
+需要同步的文件：
+
+| 文件 | 目标 |
+|------|------|
+| `AGENTS.md` | Codex 入口指令，v0.5 产品口径 |
+| `CLAUDE.md` | Claude Code 入口指令，不能继续停留在 v0.2 |
+| `.pmem/integrations/*` 模板 | init 生成的新项目默认得到 v0.5 workflow |
+
+要求：这些文件不能互相矛盾。命令列表、退出码、SQLite/Markdown 关系必须一致。
+
+---
+
+## 七、E2E 测试设计
+
+v0.5 需要把"能安装并跑通"变成可重复验证。
+
+### E2E 1：package install smoke
+
+目的：验证 npm 包产物本身。
+
+流程：
+
+```bash
+npm run build
+npm pack
+npm install -g ./pmem-*.tgz
+pmem --version
+pmem --help
+```
+
+验收：
+
+- 全局 `pmem` 可执行。
+- 版本号与 `package.json` 一致。
+- help 中列出 v0.5 支持命令。
+
+### E2E 2：fresh project workflow
+
+目的：验证新用户 5 分钟 quick start。
+
+流程：
+
+```bash
+mkdir temp/e2e-fresh-project
+cd temp/e2e-fresh-project
+pmem init e2e-fresh-project
+pmem rebuild
+pmem recall --budget 2000
+pmem verify
+```
+
+验收：
+
+- 空项目有清楚输出，不 crash。
+- 如 verify 因缺少 card/DB 给 warning，README 必须解释下一步。
+
+### E2E 3：real memory workflow
+
+目的：验证真实 agent 使用闭环。
+
+流程：
+
+```bash
+pmem init e2e-real
+mkdir -p src .pmem/modules .pmem/decisions .pmem/traces
+echo "export const value = 1;" > src/index.ts
+# 写入含 source_files 的 module card
+pmem rebuild
+pmem recall --format compact --budget 2000
+pmem ask "core" --format json
+echo "export const value = 2;" > src/index.ts
+pmem status --format json
+pmem mark-dirty --auto
+pmem update --suggest --format json
+pmem update --confirm -s "Updated core module" -n "Continue testing pmem workflow"
+pmem verify
+```
+
+验收：
+
+- `status` 能发现改动。
+- `mark-dirty --auto` 能标记相关 card，或给出可理解的无匹配提示。
+- `update --suggest` exit code 1 被视为"有建议"，不是失败。
+- `verify` 最终通过或给出可操作 warning。
+
+### E2E 4：non-git fallback
+
+目的：验证非 git 项目的 mtime fallback。
+
+验收：
+
+- `pmem status` 不依赖 git repo。
+- `.pmem/.last-status` 行为可解释。
+
+---
+
+## 八、错误与退出码设计
+
+v0.5 不必新增大量能力，但必须让失败变得可诊断。
+
+### 保留退出码协议
+
+| 命令 | 0 | 1 | 2 |
+|------|---|---|---|
+| `pmem status` | 有变更 | 无变更 | 错误 |
+| `pmem update --suggest` | 无建议 | 有建议 | 错误 |
+| `pmem distill --suggest` | 无需蒸馏 | 建议蒸馏 | 错误 |
+| `pmem verify` | 通过 | warning | error |
+
+### 错误信息原则
+
+每个错误或 warning 应该回答：
+
+1. 发生了什么。
+2. 为什么这不是理想状态。
+3. 用户或 agent 下一步该运行什么命令。
+
+示例：
+
+```txt
+No .pmem directory found.
+Run `pmem init <project-name>` in your project root.
+```
+
+```txt
+.pmem/pmem.db not found.
+Run `pmem rebuild` after adding at least one memory card.
+```
+
+### 必查场景
+
+| 场景 | 期望 |
+|------|------|
+| 无 `.pmem` | 提示 `pmem init` |
+| 无 `pmem.db` | 提示 `pmem rebuild`，并解释空项目可能无法生成 DB |
+| 损坏 DB | 提示备份 DB 后重新 `pmem rebuild --full` |
+| FTS5 不可用 | 降级 LIKE 查询，不把它当错误 |
+| 非 git 项目 | 使用 mtime fallback，并说明 source 是 `mtime` |
+| `ask` 无结果 | 提示尝试 `pmem recall` 或检查 aliases/tags/source_files |
+| dirty flags 未解决 | 提示 `pmem update --suggest` / `pmem update --confirm` |
+
+---
+
+## 九、Package Readiness 设计
+
+### package.json
+
+必须确认：
+
+| 字段 | 要求 |
+|------|------|
+| `name` | 发布前确认 npm 包名可用；若不可用，选择 scoped 包名 |
+| `version` | v0.5.0 |
+| `description` | 用户可读，不只技术描述 |
+| `bin.pmem` | 指向 `dist/index.js` |
+| `files` | 只包含 dist、README、LICENSE、docs 必要文件 |
+| `repository` | 指向实际仓库 |
+| `license` | 与 LICENSE 文件一致 |
+| `engines.node` | `>=18` |
+| `keywords` | agent, memory, cli, project-memory, codex, claude |
+
+### package-lock.json
+
+根版本必须与 `package.json` 一致。当前仓库曾出现 `package.json = 0.4.0`、`package-lock.json = 0.1.0` 的不一致，v0.5 必须修正。
+
+### npm pack 验收
+
+检查 tarball 内容：
+
+- 包含 `dist/index.js`
+- 包含 README
+- 不包含 `src/`，除非决定发布源码
+- 不包含 `temp/`
+- 不包含 `.pmem/`
+- 不包含 `node_modules/`
+
+---
+
+## 十、实现顺序
+
+```
+Step 0: 冻结 v0.5 pre-design（本文档）
+  ↓
+Step 1: 产品入口文档
+  - README.md
+  - CLAUDE.md / AGENTS.md 同步
+  - integration templates 同步
+  ↓
+Step 2: package readiness
+  - package.json metadata
+  - package-lock version
+  - npm pack dry-run
+  ↓
+Step 3: E2E 脚本
+  - package install smoke
+  - fresh project workflow
+  - real memory workflow
+  - non-git fallback
+  ↓
+Step 4: Error UX pass
+  - 常见失败场景
+  - exit code 文档与实现一致性
+  ↓
+Step 5: Release checklist / changelog
+  - CHANGELOG.md
+  - docs/release-checklist-v0.5.md
+  ↓
+Step 6: Beta release validation
+  - npm test
+  - npm run build
+  - npm pack
+  - install smoke
+  - E2E 全通过
+```
+
+---
+
+## 十一、v0.5 验收清单
+
+### 产品验收
+
+- [ ] README 能让新用户独立完成 quick start
+- [ ] Agent 文档明确 session start / work / session end 流程
+- [ ] CLI help 与 README 命令一致
+- [ ] exit code 语义完整记录
+- [ ] 常见错误都有下一步建议
+
+### 工程验收
+
+- [ ] `npm test` 通过
+- [ ] `npm run build` 通过
+- [ ] `npm pack --dry-run` 内容正确
+- [ ] tarball 安装后 `pmem --version` 正确
+- [ ] install smoke E2E 通过
+- [ ] real workflow E2E 通过
+- [ ] package version / lockfile version 一致
+
+### 发布验收
+
+- [ ] CHANGELOG.md 包含 v0.5.0
+- [ ] release checklist 全部通过
+- [ ] package metadata 完整
+- [ ] npm publish 前确认包名和发布权限
+
+---
+
+## 十二、v0.5 最终决策表
+
+| 问题 | 最终决策 |
+|------|---------|
+| v0.5 主线 | Productization Beta |
+| 是否做 embedding | 不做 |
+| 是否做 serve / MCP / REST | 不做 |
+| 是否做 Graph UI | 不做 |
+| 是否新增 backup/restore | 不做，继续依赖 Git 和迁移备份 |
+| 是否做 telemetry | 不做 |
+| 是否直接 public publish | 目标达到 Public Beta Readiness，是否 publish 发布前决定 |
+| 最重要交付 | README + npm package readiness + install/real-workflow E2E |
+| v0.5 成功定义 | 一个外部开发者或 agent 可以安装并跑通完整 memory workflow |
+
+---
+
+## 十三、v0.5 一句话定义
+
+> **pmem v0.5 是把 v0.4 的 Agent Workflow Runtime 产品化成可安装、可理解、可验证、可发布的 Beta CLI。**
+
+更工程化：
+
+```txt
+pmem v0.5 =
+  v0.4 workflow runtime
++ README / Quick Start / troubleshooting
++ npm package readiness
++ install smoke E2E
++ real project workflow E2E
++ agent instruction sync
++ release checklist
+```

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "pmem-ai",
+  "version": "0.5.0",
+  "description": "Project Memory for AI Agents: a local CLI runtime for project context, recall, and memory updates",
+  "main": "dist/index.js",
+  "bin": {
+    "pmem": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "ts-node src/index.ts",
+    "start": "node dist/index.js",
+    "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"
+  },
+  "keywords": [
+    "agent",
+    "memory",
+    "project-memory",
+    "cli",
+    "ai",
+    "codex",
+    "claude",
+    "sqlite"
+  ],
+  "author": "",
+  "license": "MIT",
+  "type": "commonjs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/KkSss999/pmem.git"
+  },
+  "bugs": {
+    "url": "https://github.com/KkSss999/pmem/issues"
+  },
+  "homepage": "https://github.com/KkSss999/pmem#readme",
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "dist/**/*.map",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.js.map",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.d.ts.map",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "docs/*.md"
+  ],
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^25.9.1",
+    "ts-node": "^10.9.2",
+    "typescript": "^6.0.3"
+  },
+  "dependencies": {
+    "better-sqlite3": "^12.10.0",
+    "commander": "^14.0.3",
+    "js-yaml": "^4.1.1"
+  }
+}