Add repo-memory CLI test docs

2026-03-20 15:42:35 +08:00
parent e32c81db12
commit a6ffc376e3
43 changed files with 1583 additions and 17 deletions
@@ -0,0 +1,138 @@
+# Repo Memory Workflow Test Plan
+
+## Scope
+
+This document tracks cross-command scenarios where the main value is the
+interaction between multiple `repo-memory` subcommands.
+
+All examples assume:
+
+- isolated temp DB and repo fixtures
+- assertions follow the shared rules in [../_shared/README.md](../_shared/README.md)
+- commands use the concrete fixture paths created for the case
+
+## case: add-search-events-roundtrip
+
+### 用例意义
+
+验证 `add -> search -> events` 的主干链路可用，确保新写入的 durable knowledge 能被立即检索并带有可追溯历史。
+
+### 前置条件
+
+- `TMPDIR/repo` 是一个已提交初始 commit 的 Git 仓库
+- 证据文件 `TMPDIR/repo/app/app/src/main/java/foo/AITask.java` 已存在
+- 空数据库已完成 `init`
+
+### 输入
+
+```bash
+repo-memory add --db TMPDIR/repo-memory.db --repo TMPDIR/repo --kind term --key AITask --summary "Plan 内嵌任务结构，不是独立表" --status confirmed --source-path TMPDIR/repo/app/app/src/main/java/foo/AITask.java --source-line 42 --alias "AI Task" --dep file:TMPDIR/repo/app/app/src/main/java/foo/AITask.java:hard
+repo-memory search --db TMPDIR/repo-memory.db --repo repo --query "AI Task"
+repo-memory events --db TMPDIR/repo-memory.db --id 1
+```
+
+### 预期输出
+
+- `add` 输出 `upserted entry 1 (term:AITask)`
+- `search` 返回 `term:AITask [confirmed]`
+- `events` 以 `term:AITask [confirmed] #1` 开头，并包含 `created`
+
+### 断言结论
+
+- 新增 entry 后无需额外同步即可被搜索到
+- alias 可参与搜索命中
+- 事件历史足以追溯 durable knowledge 的创建来源
+
+## case: ingest-search-list-across-sections
+
+### 用例意义
+
+验证 `ingest -> search -> list` 可以把 `docs/ai` Markdown 中的多个 section 转成可搜索、可枚举的知识条目。
+
+### 前置条件
+
+- `TMPDIR/repo` 是一个已提交初始 commit 的 Git 仓库
+- `TMPDIR/repo/docs/ai/repo-memory.md` 包含 `Module Map` 与 `Danger Zones` 等 section
+- 目标数据库路径尚未初始化也可，因为该用例验证 `ingest` 的自动 schema bootstrap
+
+### 输入
+
+```bash
+repo-memory ingest --db TMPDIR/repo-memory.db --repo TMPDIR/repo
+repo-memory search --db TMPDIR/repo-memory.db --repo repo --query "gateway"
+repo-memory list --db TMPDIR/repo-memory.db --repo repo
+```
+
+### 预期输出
+
+- `ingest` 输出 `ingested 1 docs from ABS_REPO`
+- `search` 命中从 `Module Map` 导入的 section
+- `list` 至少包含 `module:repo-memory:module-map` 与 `danger:repo-memory:danger-zones`
+
+### 断言结论
+
+- 一个 Markdown 文件可以导出多个 durable knowledge entry
+- 导入 entry 默认状态为 `confirmed`
+- `ingest` 既完成导入，也完成 repo 注册与 schema 初始化
+
+## case: add-link-and-resolve-related-entry
+
+### 用例意义
+
+验证两个 entry 可以通过 `link` 建立关系，同时各自的历史记录仍可独立读取。
+
+### 前置条件
+
+- 空数据库已完成 `init`
+- 同一 repo 下已存在 `term:AITask` 与 `chain:ai-insight.get` 两条 entry
+
+### 输入
+
+```bash
+repo-memory link --db TMPDIR/repo-memory.db --from-id 1 --to-id 2 --relation related_to
+sqlite3 TMPDIR/repo-memory.db "SELECT relation FROM knowledge_links WHERE from_entry_id = 1 AND to_entry_id = 2;"
+repo-memory events --db TMPDIR/repo-memory.db --id 1
+repo-memory events --db TMPDIR/repo-memory.db --id 2
+```
+
+### 预期输出
+
+- `link` 输出 `linked #1 -[related_to]-> #2`
+- SQL 查询返回一行 `related_to`
+- 两个 `events` 调用仍能分别读取各自历史
+
+### 断言结论
+
+- `link` 的副作用被持久化，而不是只回显成功文本
+- entry 关系与 entry 历史是两个独立维度
+
+## case: verify-downgrades-after-repo-change
+
+### 用例意义
+
+验证 `add -> verify -> list -> events` 在 repo 内容变更后会把已确认知识降级到需要复核或过期状态。
+
+### 前置条件
+
+- `TMPDIR/repo` 是一个已提交初始 commit 的 Git 仓库
+- 已存在一个 `confirmed` entry，硬依赖 `TMPDIR/repo/foo.txt`
+- 在 `verify` 前，`foo.txt` 已被修改或删除
+
+### 输入
+
+```bash
+repo-memory verify --db TMPDIR/repo-memory.db --repo TMPDIR/repo
+repo-memory list --db TMPDIR/repo-memory.db --repo repo
+repo-memory events --db TMPDIR/repo-memory.db --id 1
+```
+
+### 预期输出
+
+- `verify` 输出包含 `verified 1 entries`
+- `list` 中相应 entry 状态变为 `needs_review` 或 `stale`
+- `events` 中新增 `downgraded` 或 `marked_stale` 事件
+
+### 断言结论
+
+- `verify` 会根据 repo 当前状态重新评估 durable knowledge
+- 状态变化不仅更新当前 entry，也会追加历史事件供后续审计