使用 indexion wiki…

当项目使用 `.indexion/wiki/` 维护 Markdown 知识库时，用这套命令完成页面增改、过期检测、结构 lint、语义 reconcile 和索引/日志维护。

适用场景

解决思路

1. 将 wiki 页面视为四个同步工件：页面内容 `<id>.md`、manifest 条目 `wiki.json`、搜索索引 `vectors.db`/`search-sections.json`/`tfidf-vocabulary.json`、审计日志 `log.json`；用 `wiki pages update` 一次性更新四者，避免只改 `.md` 导致其余三个过期。
2. 如果迫不得已直接用 `Edit` 等编辑了 `.md`，必须立即执行：`indexion wiki pages update --id=<page-id> --content=.indexion/wiki/<page-id>.md --sources="<comma-separated sources from wiki.json>" --provenance=synthesized --actor="agent:claude" --wiki-dir=.indexion/wiki`
3. 每个 wiki 页面在 manifest 中维护两个 provenance 字段：`provenance` 取 `extracted`/`synthesized`/`manual`，`last_actor` 取 `indexion`/`agent:<name>`/`user`；新增或更新页面时显式传入。
4. 熟悉命令结构：`indexion wiki` 下有 `pages plan`、`pages add`、`pages update`、`pages ingest`、`index build`、`lint`、`export`、`import`、`log`。
5. 作为 agent 导航 wiki 时，先运行 `indexion wiki index build --wiki-dir=.indexion/wiki` 生成/重建 `index.md`，再 `cat .indexion/wiki/index.md` 阅读；`index.md` 按分类列出页面并标识 hub pages（被链接最多的页面），hub pages 是理解陌生代码库的最佳起点。
6. 写新页面：先把内容写到临时文件，例如 `cat > /tmp/my-page.md << 'EOF' ... EOF`。
7. 写新页面：用 `indexion wiki pages add --id=my-page --title="My Page Title" --content=/tmp/my-page.md --sources="src/my-module/" --provenance=synthesized --actor="agent:claude" --wiki-dir=.indexion/wiki` 注册；该命令写入 `.md`、更新 `wiki.json`、更新搜索索引、追加日志。
8. `--sources` 用于把页面链接到源文件做变更跟踪；始终指定它，否则页面不会被 `wiki pages ingest` 发现。
9. 更新已有页面：先把新内容写到临时文件，例如 `cat > /tmp/updated.md << 'EOF' ... EOF`。
10. 更新已有页面：用 `indexion wiki pages update --id=existing-page --content=/tmp/updated.md --sources="src/my-module/,src/other/" --provenance=synthesized --actor="agent:claude" --wiki-dir=.indexion/wiki`；该命令覆盖 `.md`、更新 `wiki.json` 元数据、增量更新搜索索引、追加 `log.json`。
11. 更新已有页面预期输出：`Updated page 'existing-page' (search index updated)`。
12. 检测哪些页面需要更新：运行 `indexion wiki pages ingest --wiki-dir=.indexion/wiki` 找出源文件自上次运行后已变化的页面；用 `indexion wiki pages ingest --dry-run --wiki-dir=.indexion/wiki` 预览而不记录新哈希状态。
13. 理解 `ingest`：它会哈希 `wiki.json` 中列出的每个源文件，并与 `.indexion/wiki/ingest-manifest.json` 比较；它输出更新任务列表，但不会重写页面，重写是 agent 的职责。
14. 按 ingest 驱动的更新工作流执行：1) 运行 `wiki pages ingest` 获取任务列表；2) 对每个任务读取已变更的源文件；3) 用 `wiki pages update` 更新 wiki 页面；4) 重跑 `ingest`，应报告 0 个页面需要处理。
15. 验证结构完整性：运行 `indexion wiki lint --wiki-dir=.indexion/wiki`，执行全部 6 项结构检查。
16. lint 的 6 项检查内容：Broken links（指向不存在页面的 `wiki://page-id` 引用）、Orphan pages（无法从导航树到达且无其他页面链接）、Missing cross-references（共享源文件但互不链接的页面）、Stale sources（磁盘上已不存在的 `sources` 路径）、Empty pages（内容几乎为零的页面）、Manifest-file mismatch（`wiki.json` 条目无 `.md` 文件或反之）。
17. 写完新页面后必须运行 `wiki lint`，完成前修复所有问题。
18. 当相关概念被拆分到不同页面时交叉引用警告常见；通过添加 `## See Also` 小节并使用 `wiki://page-id` 链接修复。
19. 验证内容准确性：`wiki lint` 查结构问题，`plan reconcile` 查语义漂移——wiki 页面描述的代码符号是否仍存在、代码自页面上次写入后是否已变化。
20. 使用 `plan reconcile` 时始终以项目根目录 `.` 为目标；`--doc` 限制参与文档，但目标目录决定代码符号全集；指向子目录会缩小符号集并产生 zero-fragment 报告。命令：`indexion plan reconcile --doc='.indexion/wiki/*.md' --doc-spec=markdown --format=md .`
21. 读 reconcile 报告：Summary 的关键指标是 `New logical reviews`（自上次运行以来的新漂移）。
22. 读 Suggested Review Groups：`stale_doc` 表示代码在 wiki 页面最后更新之后发生变化，用 `wiki pages update` 更新页面；`missing_doc` 表示代码符号没有对应 wiki 覆盖，添加覆盖或用 `wiki pages add` 创建新页面；`review_both` 表示 wiki 比代码更新，验证 wiki 内容正确，这是维护周期后的预期状态。
23. 每个 group 列出受影响符号和涉及的 `Docs:` wiki 页面；没有 `Docs:` 行表示没有 wiki 页面覆盖该模块。
24. 维护后 reconcile 候选不会归零，三类残留：1) 没有 wiki 页面的模块产生 `missing_doc`，需要覆盖则创建页面；2) 限定方法名（wiki 中的 `Type::method`）不匹配裸符号名（代码中的 `method`），添加条目前先 grep wiki 中的符号名验证；3) 跨模块同名符号（`get`、`tokenize`、`to_json_string`）造成跨模块误报，检查 wiki 页面实际描述哪个模块。
25. 用 `New logical reviews` 作为收敛指标；当它降为 0 时，所有可操作漂移已处理。
26. 执行完整 wiki 维护周期：1) `indexion wiki pages ingest --wiki-dir=.indexion/wiki` 检测过期页面；2) `cat .indexion/wiki/index.md` 理解 wiki 结构；3) 对每个过期页面读取变更源文件、写新内容到临时文件，然后通过 `indexion wiki pages update --id=<page-id> --content=/tmp/updated.md --sources="..." --provenance=synthesized --actor="agent:<name>" --wiki-dir=.indexion/wiki` 更新，不要直接编辑 `.md`；4) `indexion wiki lint --wiki-dir=.indexion/wiki` 验证结构完整性；5) 运行 `indexion plan reconcile --doc='.indexion/wiki/*.md' --doc-spec=markdown --format=md .` 验证内容准确性，以项目根目录为目标，迭代到 NLR=0，先修 `stale_doc`，预期 2-3 轮，每次修复用 `wiki pages update` 而非直接编辑 `.md`；6) `indexion wiki index build --wiki-dir=.indexion/wiki` 重新生成导航索引；7) `indexion wiki pages ingest --dry-run --wiki-dir=.indexion/wiki` 确认一切最新。
27. 从零规划新 wiki 或做结构大改时：运行 `indexion wiki pages plan --format=md <project-dir>` 分析项目并生成页面结构提案。
28. 执行规划：对每个提案页面运行 `indexion wiki pages add --id=<id> --title="..." --content=/tmp/page.md --sources="..." --provenance=synthesized --actor="agent:<name>"`。
29. 无需初始化步骤：第一次 `wiki pages add` 会自动创建 `.indexion/wiki/` 和空的 `wiki.json` manifest；没有单独的 `wiki init` 命令。
30. `wiki pages plan` 使用 CodeGraph 提议基于概念的页面，而不是基于文件的页面；优先概念页面（如 「KGF System」）而不是文件页面（如 「src/kgf/lexer/lexer.mbt」）。
31. 构建搜索索引：`indexion wiki index build --wiki-dir=.indexion/wiki` 只构建导航索引 `index.md`；`indexion wiki index build --full --wiki-dir=.indexion/wiki` 构建导航 + 向量搜索索引 `vectors.db`；`indexion wiki index build --dry-run --wiki-dir=.indexion/wiki` 预览 `index.md` 不写入。
32. 使用 `--full` 后，`indexion search .indexion/wiki/` 会使用预构建向量，而不是每次查询从头重建。
33. 检查审计轨迹：`indexion wiki log --wiki-dir=.indexion/wiki --tail=20` 查看最近操作；`indexion wiki log --wiki-dir=.indexion/wiki --json` 查看完整 JSON 日志。
34. 每次 `pages add`、`pages update`、`lint`、`pages ingest`、`index build` 都会追加到 `.indexion/wiki/log.json`；用日志验证之前 agent 运行是否正确完成，或理解页面最后修改原因。
35. 注意陷阱：反引号包裹的 `wiki://` 引用不是链接，lint 会正确忽略代码 span 中的 `wiki://`；要创建真实交叉引用，使用裸 `wiki://page-id` 或 Markdown 链接 `[Title](wiki://page-id)`。
36. 注意陷阱：`wiki pages ingest` 记录的是上次运行时的状态；如果通过 `pages update` 向页面的 `sources` 列表添加新源文件，下一次 `ingest` 会显示该页面需要处理（因为新源文件没有记录哈希），这是预期行为，更新后再运行一次 `ingest` 记录基线。

适用边界 · 注意事项

• 项目未安装 indexion 或没有使用 `.indexion/wiki/` 知识库时不适用。
• 仅维护普通 Markdown 文档、不依赖 `wiki.json`/搜索索引/审计日志同步机制时不适用。
• 无法接受以项目根目录为目标运行 `plan reconcile`（例如只允许扫描子目录）时，语义漂移检查会失真，不建议使用。