pmem-ai 0.5.0

package/docs/v0.2 pre-roadmap.md

@@ -0,0 +1,270 @@
+# v0.2 前置路线图
+
+本文档定义 v0.2 的目标架构、命令优先级和实现顺序。设计依据来自 `v0.2 pre-design.md`，不与 `Voorlopige projekidee.md` 中的长期愿景冲突。
+
+---
+
+## 一、v0.2 主题
+
+> **可信地长期使用** — 冷启动不空、并发不丢、卡片不乱、版本可迁、记忆可持续。
+
+v0.1 证明了"能记"。v0.2 要证明"值得长期记"。
+
+---
+
+## 二、v0.2 目录结构
+
+```txt
+.pmem/
+  manifest.yml
+
+  index.md
+  state.md
+  next.md
+
+  modules/
+  features/
+  decisions/
+  tasks/
+  traces/
+  risks/
+  summaries/
+
+  candidates/                  # 新增：冷启动扫描候选项
+    modules.generated.md
+
+  indexes/
+    graph.json
+    bm25.json
+    card_hashes.json           # 新增：乐观锁快照
+
+  skills/
+    recall.md
+    update.md
+    distill.md                 # 新增
+
+  integrations/
+    claude-code/
+    cursor/
+    codex/
+
+  backups/                     # 新增：迁移前自动备份
+  migrations/                  # 新增：项目自定义迁移（预留）
+
+AGENTS.md
+```
+
+**变化点：**
+- 新增 `risks/` — 风险卡片目录
+- 新增 `candidates/` — 冷启动扫描产物，不直接进入 `modules/`
+- 新增 `indexes/card_hashes.json` — 乐观锁快照
+- 新增 `backups/`、`migrations/` — 迁移基础设施
+- 新增 `skills/distill.md` — 蒸馏操作手册
+
+---
+
+## 三、v0.2 manifest 目标形态
+
+```yml
+pmem:
+  schema_version: "0.2"
+  protocol_version: "0.2"
+  created_by: "0.2.0"
+  last_migrated_by: null
+
+project:
+  name: ""
+  language: "zh-CN"
+  status: "active"
+
+memory_status:
+  completeness: "incomplete"       # incomplete | partial | usable | mature
+  initialized_mode: "guided"       # minimal | guided | from_manifest | imported
+  dirty: false
+  dirty_since: null
+  dirty_reason: null
+
+source_of_truth:
+  type: markdown_cards
+  card_globs:
+    - ".pmem/modules/**/*.md"
+    - ".pmem/features/**/*.md"
+    - ".pmem/decisions/**/*.md"
+    - ".pmem/tasks/**/*.md"
+    - ".pmem/traces/**/*.md"
+    - ".pmem/risks/**/*.md"
+
+indexes:
+  path: ".pmem/indexes"
+  generated: true
+  graph:
+    mode: single
+    path: ".pmem/indexes/graph.json"
+  keyword:
+    mode: bm25
+    path: ".pmem/indexes/bm25.json"
+  hashes:
+    path: ".pmem/indexes/card_hashes.json"
+
+concurrency:
+  lock: file
+  lock_path: ".pmem/.lock"
+  timeout: "5s"
+  stale_after: "60s"
+  on_timeout: "abort"
+  optimistic_lock: true
+  atomic_write: true
+
+auto_update:
+  enabled: true
+  on_code_change: mark_dirty
+  on_doc_change: mark_dirty
+  on_memory_change: rebuild_indexes
+  on_session_end: prompt
+  min_trace_interval: "30m"
+  max_auto_traces_per_day: 5
+  trace_policy:
+    require_meaningful_change: true
+    require_summary: true
+    require_related_node: true
+
+card_policy:
+  id_pattern: "^(project|module|feature|task|decision|trace|risk|assumption|resource|integration)\\.[a-z0-9._-]+$"
+  max_tokens:
+    module: 1200
+    feature: 1000
+    decision: 800
+    task: 600
+    trace: 1000
+  max_sections:
+    module: 8
+    feature: 8
+    decision: 6
+    task: 6
+  warn_when_related_count_gt: 12
+
+distill:
+  enabled: true
+  cadence: weekly
+  max_undistilled_traces: 20
+  require_confirmation: true
+  suggest_card_splits: true
+
+freshness:
+  default_ttl: "14d"
+  stale_on_related_code_change: true
+  require_last_verified: true
+
+integrations:
+  active: []
+  compatibility: {}
+
+migrations:
+  applied: []
+```
+
+---
+
+## 四、命令优先级
+
+### P0 — 必须完成（工程底座）
+
+| 命令 | 说明 |
+|------|------|
+| `pmem init --guided` | 交互式冷启动，v0.2 核心功能 |
+| `pmem init` | 增强：生成 candidates、标记 memory_incomplete |
+| `pmem verify` | 增强：检查 schema_version、card_policy 违规、card 过大 |
+| `pmem rebuild` | 增强：生成 card_hashes.json、支持乐观锁快照 |
+| `pmem migrate --dry-run` | 预览迁移变更 |
+| `pmem migrate --to 0.2` | 执行迁移（带自动备份） |
+| `pmem mark-dirty` | 增强：更新 memory_status.dirty |
+
+### P1 — 应该完成（长期可用性）
+
+| 命令 | 说明 |
+|------|------|
+| `pmem distill` | trace → card 蒸馏（建议模式，需确认） |
+| `pmem distill --suggest-splits` | 建议拆分过大卡片 |
+| `pmem lock status` | 查看锁状态 |
+| `pmem update --auto --mode=suggest` | 增强：冲突检测、乐观锁检查 |
+| `pmem update --confirm` | 增强：atomic write、锁保护 |
+
+### P2 — 可延后
+
+| 命令 | 说明 |
+|------|------|
+| `pmem split --interactive` | 交互式拆分卡片 |
+| `pmem update --merge` | section-level 安全合并 |
+| `pmem init --from <file>` | 声明式初始化 |
+| `pmem bootstrap-scan --deep` | 深度学习项目结构 |
+
+---
+
+## 五、实现顺序
+
+```
+Phase 1: 类型与 manifest 升级
+  ├── 新增 v0.2 类型（CardPolicy, ConcurrencyConfig, MemoryStatus, MigrationRecord 等）
+  ├── 升级 Manifest 类型
+  ├── 升级 manifest 序列化/反序列化
+  └── 更新默认 manifest 模板
+
+Phase 2: 迁移系统
+  ├── pmem migrate --dry-run
+  ├── pmem migrate --to 0.2（0.1→0.2 迁移规则）
+  ├── 自动备份（.pmem/backups/）
+  └── pmem verify 版本检查
+
+Phase 3: 并发保护
+  ├── file lock（.pmem/.lock）
+  ├── atomic write（.tmp → fsync → rename）
+  ├── card_hashes.json 乐观锁
+  ├── 冲突检测与报告
+  └── pmem lock status
+
+Phase 4: 冷启动
+  ├── pmem init --guided（交互式问答）
+  ├── pmem init 增强（扫描、candidates/、memory_incomplete）
+  ├── 降级 recall 输出
+  └── pmem init --from <file>（P2，可延后）
+
+Phase 5: 卡片治理
+  ├── card_policy 校验（ID 命名、大小阈值）
+  ├── pmem verify 增强（card_policy 违规检测）
+  ├── pmem distill（trace → card 蒸馏建议）
+  └── pmem distill --suggest-splits
+
+Phase 6: 收尾
+  ├── skills/distill.md
+  ├── .pmem/integrations/ 模板更新
+  ├── 端到端测试
+  └── 文档更新
+```
+
+---
+
+## 六、从 v0.1 到 v0.2 的关键架构变化
+
+| 方面 | v0.1 | v0.2 |
+|------|------|------|
+| 主数据类型 | `CardFrontmatter` 8 字段 | 新增 `schema_version`, `version`, `content_hash` |
+| 并发 | 无保护 | 文件锁 + 乐观锁 + 原子写 |
+| init | 空骨架 | 三种模式 + candidates + memory_incomplete |
+| verify | index 一致性 | + schema 版本 + card_policy 违规 + 过大卡片 |
+| manifest | 无版本标识 | `pmem.schema_version` + `migrations.applied` |
+| rebuild | graph.json 单一索引 | + card_hashes.json |
+| update | 直接写入 | atomic write + 冲突检测 |
+| 卡片粒度 | 无约束 | card_policy 强制校验 |
+
+---
+
+## 七、不在此版本的内容
+
+- embeddings / semantic search → v0.3
+- SQLite 图索引 → v0.3
+- `pmem serve` HTTP API / MCP Server → v0.3
+- graph 分片存储 → v0.3
+- 增量 rebuild → v0.3
+- 记忆质量评分 → v0.3
+- 自动拆分卡片 → v0.3
+- section-level merge → v0.2 P2（可延后）