indexion-wiki

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

indexion wiki

indexion 维基系统

indexion's wiki system maintains a knowledge base at

.indexion/wiki/

as a collection of Markdown files governed by a

wiki.json

manifest.

indexion 的维基系统在

.indexion/wiki/

目录下维护一个知识库，由

wiki.json

清单管控的一系列Markdown文件组成。

A wiki page is not just a

.md

file

维基页面不只是一个

.md

文件

A wiki page consists of four synchronized artifacts:

Artifact	File	Updated by
Page content	`<id>.md`	`wiki pages add` , `wiki pages update`
Manifest entry	`wiki.json`	`wiki pages add` , `wiki pages update`
Search index	`vectors.db` , `search-sections.json` , `tfidf-vocabulary.json`	`wiki pages update` , `wiki index build --full`
Audit log	`log.json`	Every wiki-modifying command

wiki pages update
updates all four at once. Editing the

.md

file directly updates only the first. The other three become stale — search returns old results, the manifest carries wrong provenance, and the log has no record of the change.

If you edit a

.md

directly (e.g. via

Edit

tool), you must immediately follow up:

bash

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

Every wiki page also carries two provenance fields in the manifest:

provenance

"extracted"

"synthesized"

"manual"

last_actor

"indexion"

"agent:<name>"

"user"

维基页面由四个同步的工件组成：

工件	文件	更新方式
页面内容	`<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 pages update

会一次性更新这四个工件。**直接编辑

.md

文件只会更新第一个工件，另外三个会变得过期——搜索返回旧结果、清单包含错误的来源信息，且日志中没有该变更的记录。

如果直接编辑

.md

文件（例如通过

Edit

工具），你必须立即执行以下操作：

bash

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

每个维基页面在清单中还包含两个来源字段：

provenance

：

"extracted"

"synthesized"

"manual"

last_actor

：

"indexion"

"agent:<name>"

"user"

Command Structure

命令结构

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

indexion wiki
  ├── pages
  │   ├── plan    -- 提议页面结构（类似init功能）
  │   ├── add     -- 创建新页面（写入.md文件 + 清单 + 索引 + 日志）
  │   ├── update  -- 更新现有页面（写入.md文件 + 清单 + 索引 + 日志）
  │   └── ingest  -- 通过哈希源文件检测过期页面
  ├── index
  │   └── build   -- 重建index.md（可选同时重建vectors.db）
  ├── lint        -- 结构完整性检查（无需LLM）
  ├── export      -- 导出为GitHub/GitLab维基格式
  ├── import      -- 从GitHub/GitLab维基格式导入
  └── log         -- 操作审计追踪

Navigating the Wiki (as an agent)

以Agent身份导航维基系统

Before reading individual pages, start with the index:

bash

undefined

在阅读单个页面之前，先从索引开始：

bash

undefined

Generate or regenerate index.md — the entry point for navigation

生成或重新生成index.md——导航的入口

indexion wiki index build --wiki-dir=.indexion/wiki

Then read it

然后查看它

cat .indexion/wiki/index.md


`index.md` lists pages by category and identifies **hub pages** (most-linked pages).
Hub pages are the best starting points for understanding an unfamiliar codebase.

cat .indexion/wiki/index.md


`index.md` 按类别列出页面，并标记**枢纽页面**（被链接最多的页面）。枢纽页面是了解陌生代码库的最佳起点。

Writing a New Page

创建新页面

bash

undefined

bash

undefined

1. Write content to a temp file

1. 将内容写入临时文件

cat > /tmp/my-page.md << 'EOF'

My Page Title

我的页面标题

...content... EOF

...内容... EOF

2. Register it — this writes .md, updates wiki.json, updates search index, appends log

2. 注册页面——这会写入.md文件、更新wiki.json、更新搜索索引并追加日志

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


The `--sources` field links the page to source files for change tracking.
Always specify it — pages without sources are invisible to `wiki pages ingest`.

indexion wiki pages add
--id=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` 忽略。

Updating an Existing Page

更新现有页面

bash

undefined

bash

undefined

1. Write new content to a temp file

1. 将新内容写入临时文件

cat > /tmp/updated.md << 'EOF'

Updated Page

更新后的页面

...new content... EOF

...新内容... EOF

2. Update — this overwrites .md, updates wiki.json metadata,

2. 更新页面——这会覆盖.md文件、更新wiki.json元数据、

incrementally updates the search index, and appends to log.json

增量更新搜索索引并追加到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


Expected output: `Updated page 'existing-page' (search index updated)`

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)`

Detecting What Needs Updating

检测需要更新的内容

bash

undefined

bash

undefined

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` hashes every source file listed in `wiki.json` and compares against
`.indexion/wiki/ingest-manifest.json`. It outputs an update task list but does
**not** rewrite pages — that is the agent's responsibility.

Workflow:
1. Run `wiki pages ingest` to get the task list.
2. For each task, read the changed source files.
3. Update the wiki page with `wiki pages update`.
4. Re-run `ingest` — it should report 0 pages needing attention.

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` 更新维基页面。
4. 重新运行 `ingest`——此时应报告0个需要处理的页面。

Verifying Structural Integrity

验证结构完整性

bash

undefined

bash

undefined

Run all 6 structural checks

运行全部6项结构检查

indexion wiki lint --wiki-dir=.indexion/wiki


| Check | What it finds |
|-------|--------------|
| Broken links | `wiki://page-id` references to pages that don't exist |
| Orphan pages | Pages unreachable from nav tree and not linked by any other page |
| Missing cross-references | Pages sharing source files that don't link to each other |
| Stale sources | `sources` paths that no longer exist on disk |
| Empty pages | Pages with near-zero content |
| Manifest-file mismatch | `wiki.json` entries with no `.md` file (or vice versa) |

After writing new pages, always run `wiki lint` and fix any issues before finishing.

Cross-reference warnings are common when related concepts are split across pages.
Fix them by adding a `## See Also` section with `wiki://page-id` links.

indexion wiki lint --wiki-dir=.indexion/wiki


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

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

当相关概念分散在多个页面时，交叉引用警告很常见。可通过添加包含 `wiki://page-id` 链接的 `## 另请参阅` 部分来修复。

Verifying Content Accuracy (

plan reconcile

)

验证内容准确性（

plan reconcile

）

wiki lint

catches structural problems.

plan reconcile

catches semantic drift — whether the code symbols described in a wiki page still exist and whether the code has changed since the page was last written.

Always target the project root (
.
). The

--doc

flag restricts which documents participate, but the target directory determines the code symbol universe. Targeting a subdirectory shrinks the symbol set and produces zero-fragment reports.

bash

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

wiki lint

检测结构问题。

plan reconcile

检测语义偏差——维基页面中描述的代码符号是否仍然存在，以及自页面最后编写以来代码是否已变更。

务必以项目根目录（
.
）为目标。

--doc

标志限制参与的文档，但目标目录决定了代码符号的范围。以子目录为目标会缩小符号集并生成零片段报告。

bash

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

Reading the report

解读报告

Summary — key metric is

New logical reviews

(fresh drift since last run).

Suggested Review Groups — the actionable core:

Category	Meaning	Action
`stale_doc`	Code changed after the wiki page was last updated	Update the page via `wiki pages update`
`missing_doc`	Code symbols with no matching wiki coverage	Add coverage or create a new page via `wiki pages add`
`review_both`	Wiki is newer than code	Verify the wiki content is correct; this is the expected state after a maintenance cycle

Each group lists affected symbols and the

Docs:

wiki pages involved. Groups without a

Docs:

line mean no wiki page covers that module.

摘要——关键指标是

New logical reviews

（自上次运行以来的新偏差）。

建议的审查组——可执行的核心内容：

类别	含义	操作
`stale_doc`	维基页面更新后代码已变更	通过 `wiki pages update` 更新页面
`missing_doc`	代码符号没有对应的维基覆盖	添加覆盖内容或通过 `wiki pages add` 创建新页面
`review_both`	维基比代码更新	验证维基内容是否正确；这是维护周期后的预期状态

每个组列出受影响的符号和涉及的

Docs:

维基页面。没有

Docs:

行的组表示没有维基页面覆盖该模块。

Residual candidates that persist after maintenance

维护后仍存在的残留候选项

Reconcile candidates never reach zero. Three sources of persistent candidates:

Modules without wiki pages produce
```
missing_doc
```
. Create pages if coverage is needed.
Qualified method names (
```
Type::method
```
in wiki) don't match bare symbol names (
```
method
```
in code). Verify by grepping the wiki for the symbol name before adding entries.
Same-name symbols across modules (
```
get
```
,
```
tokenize
```
,
```
to_json_string
```
) cause cross-module false positives. Check which module the wiki page actually describes.

Track

New logical reviews

as the convergence metric. When it reaches zero, all actionable drift has been addressed.

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

没有维基页面的模块会产生
```
missing_doc
```
。如果需要覆盖，创建页面即可。
限定方法名（维基中的
```
Type::method
```
）与代码中的裸符号名（
```
method
```
）不匹配。添加条目前，通过在维基中搜索符号名进行验证。
跨模块同名符号（
```
get
```
、
```
tokenize
```
、
```
to_json_string
```
）会导致跨模块误报。检查维基页面实际描述的是哪个模块。

将

New logical reviews

作为收敛指标。当它归零时，所有可处理的偏差都已解决。

Full Wiki Maintenance Cycle

完整的维基维护周期

bash

undefined

bash

undefined

1. Detect stale pages (source files changed)

1. 检测过期页面（源文件已变更）

indexion wiki pages ingest --wiki-dir=.indexion/wiki

2. Read the index to understand the wiki structure

2. 查看索引以了解维基结构

cat .indexion/wiki/index.md

3. For each stale page: read changed sources, write new content to temp file,

3. 针对每个过期页面：阅读已变更的源文件，将新内容写入临时文件，

then update through the command (NOT by editing .md directly)

然后通过命令更新（不要直接编辑.md文件）

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

4. 验证结构完整性

indexion wiki lint --wiki-dir=.indexion/wiki

5. Verify content accuracy — target project root, iterate until NLR=0

5. 验证内容准确性——以项目根目录为目标，重复运行直到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.

→ 先修复stale_doc组。重新运行。预计需要2-3轮。

→ For each fix, use

wiki pages update

, not direct .md edits.

→ 每次修复都使用

wiki pages update

，不要直接编辑.md文件。

6. Regenerate the navigation index

6. 重新生成导航索引

indexion wiki index build --wiki-dir=.indexion/wiki

7. Confirm everything is current

7. 确认所有内容都是最新的

indexion wiki pages ingest --dry-run --wiki-dir=.indexion/wiki

undefined

indexion wiki pages ingest --dry-run --wiki-dir=.indexion/wiki

undefined

Planning a New Wiki from Scratch

从零开始规划新维基系统

When the wiki doesn't exist yet or needs a structural overhaul:

bash

undefined

当维基系统尚未存在或需要结构性整改时：

bash

undefined

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>"


**No initialization step is needed.** The first `wiki pages add` call automatically
creates `.indexion/wiki/` and an empty `wiki.json` manifest. There is no separate
`wiki init` command.

`wiki pages plan` uses the CodeGraph to propose concept-based pages, not file-based ones.
Prefer concept pages (e.g., "KGF System") over file pages (e.g., "src/kgf/lexer/lexer.mbt").

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系统”）而非文件页面（例如“src/kgf/lexer/lexer.mbt”）。

Building the Search Index

构建搜索索引

bash

undefined

bash

undefined

Build navigation index only (index.md)

仅构建导航索引（index.md）

indexion wiki index build --wiki-dir=.indexion/wiki

Build navigation + vector search index (vectors.db)

构建导航+向量搜索索引（vectors.db）

indexion wiki index build --full --wiki-dir=.indexion/wiki

Preview index.md without writing

预览index.md但不写入

indexion wiki index build --dry-run --wiki-dir=.indexion/wiki


With `--full`, `indexion search .indexion/wiki/` will use the pre-built vectors
instead of rebuilding from scratch on each query.

indexion wiki index build --dry-run --wiki-dir=.indexion/wiki


使用`--full`参数时，`indexion search .indexion/wiki/`将使用预构建的向量，而非每次查询时从头重建。

Checking the Audit Trail

检查审计追踪

bash

undefined

bash

undefined

Recent operations

Full log as JSON

完整日志（JSON格式）

indexion wiki log --wiki-dir=.indexion/wiki --json


Every `pages add`, `pages update`, `lint`, `pages ingest`, and `index build` call appends to
`.indexion/wiki/log.json`. Use the log to verify that previous agent runs completed
correctly, or to understand why a page was last modified.

indexion wiki log --wiki-dir=.indexion/wiki --json


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

Key Pitfalls

关键陷阱

Backtick-quoted
wiki://
references are not links. The lint checker correctly ignores

wiki://

in code spans. Use bare

wiki://page-id

or Markdown links

[Title](wiki://page-id)

to create real cross-references.

wiki pages ingest
manifests state at the time of the last run. If you add new source files to a page's

sources

list via

pages update

, the next

ingest

run will show that page as needing attention (because the new sources have no recorded hash). This is expected behavior — run

ingest

again after the update to record the baseline.

**反引号包裹的

wiki://

引用不是链接。**检查器会正确忽略代码块中的

wiki://

。使用裸

wiki://page-id

或Markdown链接

[标题](wiki://page-id)

来创建真正的交叉引用。

wiki pages ingest

记录上次运行时的状态。**如果通过

pages update

为页面的

sources

列表添加新源文件，下次

ingest

运行会显示该页面需要处理（因为新源文件没有记录的哈希值）。这是预期行为——更新后再次运行

ingest

以记录基线。

indexion-wiki

Original

Translation

indexion wiki

indexion 维基系统

A wiki page is not just a .md file

维基页面不只是一个 .md 文件

Command Structure

命令结构

Navigating the Wiki (as an agent)

以Agent身份导航维基系统

Generate or regenerate index.md — the entry point for navigation

生成或重新生成index.md——导航的入口

Then read it

然后查看它

Writing a New Page

创建新页面

1. Write content to a temp file

1. 将内容写入临时文件

My Page Title

我的页面标题

2. Register it — this writes .md, updates wiki.json, updates search index, appends log

2. 注册页面——这会写入.md文件、更新wiki.json、更新搜索索引并追加日志

Updating an Existing Page

更新现有页面

1. Write new content to a temp file

1. 将新内容写入临时文件

Updated Page

更新后的页面

2. Update — this overwrites .md, updates wiki.json metadata,

2. 更新页面——这会覆盖.md文件、更新wiki.json元数据、

incrementally updates the search index, and appends to log.json

增量更新搜索索引并追加到log.json

Detecting What Needs Updating

检测需要更新的内容

Find pages whose source files have changed since the last run

查找自上次运行以来源文件已变更的页面

Preview without recording the new hash state

预览但不记录新的哈希状态

Verifying Structural Integrity

验证结构完整性

Run all 6 structural checks

运行全部6项结构检查

Verifying Content Accuracy (plan reconcile)

验证内容准确性（plan reconcile）

Reading the report

解读报告

Residual candidates that persist after maintenance

维护后仍存在的残留候选项

Full Wiki Maintenance Cycle

完整的维基维护周期

1. Detect stale pages (source files changed)

1. 检测过期页面（源文件已变更）

2. Read the index to understand the wiki structure

2. 查看索引以了解维基结构

3. For each stale page: read changed sources, write new content to temp file,

3. 针对每个过期页面：阅读已变更的源文件，将新内容写入临时文件，

then update through the command (NOT by editing .md directly)

然后通过命令更新（不要直接编辑.md文件）

4. Verify structural integrity

4. 验证结构完整性

5. Verify content accuracy — target project root, iterate until NLR=0

5. 验证内容准确性——以项目根目录为目标，重复运行直到NLR=0

→ Fix stale_doc groups first. Re-run. Expect 2-3 rounds.

→ 先修复stale_doc组。重新运行。预计需要2-3轮。

→ For each fix, use wiki pages update, not direct .md edits.

→ 每次修复都使用wiki pages update，不要直接编辑.md文件。

6. Regenerate the navigation index

6. 重新生成导航索引

7. Confirm everything is current

7. 确认所有内容都是最新的

Planning a New Wiki from Scratch

从零开始规划新维基系统

Analyze the project and generate a page structure proposal

分析项目并生成页面结构提议

Then execute the plan: add each proposed page

然后执行计划：添加每个提议的页面

Building the Search Index

构建搜索索引

Build navigation index only (index.md)

A wiki page is not just a
`.md`
file

维基页面不只是一个
`.md`
文件

Verifying Content Accuracy (
`plan reconcile`
)

验证内容准确性（
`plan reconcile`
）

→ For each fix, use
`wiki pages update`
, not direct .md edits.

→ 每次修复都使用
`wiki pages update`
，不要直接编辑.md文件。