indexion-wiki

indexion wiki

indexion 的 wiki 系统在 .indexion/wiki/ 中维护一个知识库，其中的 Markdown 文件由 wiki.json 清单管理。

Wiki 页面不只是一个 .md 文件

一个 wiki 页面由四种同步的内容组成：

内容	文件	更新方式
页面内容	<id>.md	wiki pages add、wiki pages update
清单条目	wiki.json	wiki pages add、wiki pages update
搜索索引	vectors.db、search-sections.json、tfidf-vocabulary.json	wiki pages update、wiki index build --full
审计日志	log.json	每条修改 wiki 的命令

wiki pages update 会一次性更新全部四项内容。 直接编辑 .md 文件只会更新第一项。其他三项会过时——搜索会返回旧结果，清单会记录错误的来源信息，日志也不会记录此次更改。

如果你直接编辑 .md 文件（例如使用 Edit 工具），必须立即接着执行：

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

每个 wiki 页面在清单中还包含两个来源信息字段：

• provenance："extracted" | "synthesized" | "manual"
• last_actor："indexion" | "agent:<name>" | "user"

命令结构

indexion wiki
  ├── pages
  │   ├── plan    -- propose page structure (init-like)
  │   ├── add     -- create a new page (writes .md + manifest + index + log)
  │   ├── update  -- update an existing page (writes .md + manifest + index + log)
  │   └── ingest  -- detect stale pages by hashing sources
  ├── index
  │   └── build   -- rebuild index.md (and optionally vectors.db)
  ├── lint        -- structural integrity checks (no LLM needed)
  ├── export      -- export to GitHub/GitLab wiki format
  ├── import      -- import from GitHub/GitLab wiki format
  └── log         -- operation audit trail

浏览 Wiki（作为 Agent）

阅读具体页面前，先查看索引：

# Generate or regenerate index.md — the entry point for navigation
indexion wiki index build --wiki-dir=.indexion/wiki

# Then read it
cat .indexion/wiki/index.md

index.md 按类别列出页面，并标明中心页面（链接最多的页面）。 中心页面最适合作为理解陌生代码库的起点。

编写新页面

# 1. Write content to a temp file
cat > /tmp/my-page.md << 'EOF'
# My Page Title
...content...
EOF

# 2. Register it — this writes .md, updates wiki.json, updates search index, appends log
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

--sources 字段将页面关联到源文件，以便跟踪变更。 务必指定此字段——没有来源的页面不会被 wiki pages ingest 发现。

更新现有页面

# 1. Write new content to a temp file
cat > /tmp/updated.md << 'EOF'
# Updated Page
...new content...
EOF

# 2. Update — this overwrites .md, updates wiki.json metadata,
#    incrementally updates the search index, and appends to log.json
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

预期输出：Updated page 'existing-page' (search index updated)

检测需要更新的内容

# Find pages whose source files have changed since the last run
indexion wiki pages ingest --wiki-dir=.indexion/wiki

# Preview without recording the new hash state
indexion wiki pages ingest --dry-run --wiki-dir=.indexion/wiki

ingest 会对 wiki.json 中列出的每个源文件进行哈希计算，并与 .indexion/wiki/ingest-manifest.json 中的记录进行比较。它会输出更新任务列表，但 不会重写页面——这由 Agent 负责。

工作流：

1. 运行 wiki pages ingest 获取任务列表。
2. 对每项任务，阅读已更改的源文件。
3. 使用 wiki pages update 更新 wiki 页面。
4. 重新运行 ingest——此时应报告有 0 个页面需要处理。

验证结构完整性

# Run all 6 structural checks
indexion wiki lint --wiki-dir=.indexion/wiki

检查项	检查内容
链接失效	指向不存在页面的 wiki://page-id 引用
孤立页面	无法从导航树访问，且未被其他页面链接的页面
缺少交叉引用	共享源文件但未相互链接的页面
来源过时	磁盘上已不存在的 sources 路径
空页面	内容几乎为空的页面
清单与文件不匹配	wiki.json 中存在但没有对应 .md 文件的条目（反之亦然）

编写新页面后，务必运行 wiki lint，并在完成前修复所有问题。

相关概念分散在不同页面时，常会出现交叉引用警告。 可通过添加包含 wiki://page-id 链接的 ## See Also 部分来修复。

验证内容准确性（plan reconcile）

wiki lint 会检查结构问题。plan reconcile 会检查语义偏移—— wiki 页面中描述的代码符号是否仍然存在，以及代码自页面上次编写后是否发生了变化。

始终以项目根目录（.）为目标。 --doc 标志用于限制参与处理的文档，但目标目录决定代码符号的范围。将子目录设为目标会缩小符号集，并导致报告中片段数为 0。

indexion plan reconcile \
  --doc='.indexion/wiki/*.md' \
  --doc-spec=markdown \
  --format=md \
  .

阅读报告

摘要 — 关键指标是 New logical reviews（自上次运行以来新增的漂移）。

建议审核分组 — 可采取行动的核心内容：

类别	含义	操作
stale_doc	代码在 wiki 页面上次更新后发生了更改	通过 wiki pages update 更新页面
missing_doc	代码符号没有对应的 wiki 覆盖内容	添加覆盖内容，或通过 wiki pages add 创建新页面
review_both	wiki 比代码更新	验证 wiki 内容是否正确；这是维护周期结束后的预期状态

每个分组都会列出受影响的符号，以及涉及的 Docs: wiki 页面。 没有 Docs: 行的分组表示没有 wiki 页面覆盖该模块。

维护后仍然存在的剩余候选项

协调候选项永远不会归零。候选项持续存在的来源有三种：

1. 没有 wiki 页面的模块会产生 missing_doc。如果需要覆盖内容，请创建页面。
2. 限定的方法名称（wiki 中的 Type::method）与代码中的裸符号名称 （method）不匹配。添加条目之前，先在 wiki 中搜索该符号名称进行确认。
3. 不同模块中的同名符号（get、tokenize、to_json_string）会导致 跨模块误报。请检查 wiki 页面实际描述的是哪个模块。

将 New logical reviews 作为收敛指标。该指标归零时， 所有可操作的漂移都已处理完毕。

完整的 Wiki 维护周期

# 1. Detect stale pages (source files changed)
indexion wiki pages ingest --wiki-dir=.indexion/wiki

# 2. Read the index to understand the wiki structure
cat .indexion/wiki/index.md

# 3. For each stale page: read changed sources, write new content to temp file,
#    then update through the command (NOT by editing .md directly)
indexion wiki pages update --id=<page-id> --content=/tmp/updated.md \
  --sources="..." --provenance=synthesized --actor="agent:<name>" \
  --wiki-dir=.indexion/wiki

# 4. Verify structural integrity
indexion wiki lint --wiki-dir=.indexion/wiki

# 5. Verify content accuracy — target project root, iterate until NLR=0
indexion plan reconcile \
  --doc='.indexion/wiki/*.md' \
  --doc-spec=markdown \
  --format=md \
  .
# → Fix stale_doc groups first. Re-run. Expect 2-3 rounds.
# → For each fix, use `wiki pages update`, not direct .md edits.

# 6. Regenerate the navigation index
indexion wiki index build --wiki-dir=.indexion/wiki

# 7. Confirm everything is current
indexion wiki pages ingest --dry-run --wiki-dir=.indexion/wiki

从零开始规划新 Wiki

如果 wiki 尚不存在，或需要进行结构性改造：

# Analyze the project and generate a page structure proposal
indexion wiki pages plan --format=md <project-dir>

# Then execute the plan: add each proposed page
indexion wiki pages add --id=<id> --title="..." --content=/tmp/page.md \
  --sources="..." --provenance=synthesized --actor="agent:<name>"

无需执行初始化步骤。 首次调用 wiki pages add 会自动 创建 .indexion/wiki/ 和一个空的 wiki.json 清单。没有单独的 wiki init 命令。

wiki pages plan 使用 CodeGraph 提出基于概念的页面，而非基于文件的页面。 优先使用概念页面（例如“KGF System”），而不是文件页面（例如“src/kgf/lexer/lexer.mbt”）。

构建搜索索引

# Build navigation index only (index.md)
indexion wiki index build --wiki-dir=.indexion/wiki

# Build navigation + vector search index (vectors.db)
indexion wiki index build --full --wiki-dir=.indexion/wiki

# Preview index.md without writing
indexion wiki index build --dry-run --wiki-dir=.indexion/wiki

使用 --full 时，indexion search .indexion/wiki/ 会使用预先构建的向量， 而不是在每次查询时从头开始重新构建。

检查审计跟踪

# Recent operations
indexion wiki log --wiki-dir=.indexion/wiki --tail=20

# Full log as JSON
indexion wiki log --wiki-dir=.indexion/wiki --json

每次调用 pages add、pages update、lint、pages ingest 和 index build 都会向 .indexion/wiki/log.json 追加记录。使用日志可验证先前的 Agent 运行是否正确完成， 或了解页面上次修改的原因。

关键注意事项

用反引号括起来的 wiki:// 引用不是链接。 lint 检查器会正确地 忽略代码片段中的 wiki://。请使用不带反引号的 wiki://page-id 或 Markdown 链接 [Title](wiki://page-id) 来创建真实的交叉引用。

wiki pages ingest 会记录上次运行时的清单状态。 如果通过 pages update 将新的源文件 添加到页面的 sources 列表中，下一次 ingest 运行会显示该页面需要处理 （因为新来源没有记录的哈希值）。这是预期行为——更新后再次运行 ingest 以记录基准状态。