indexion-readme

indexion readme — README 构建

根据模板、文档注释、手写文本和各包的 README 构建项目 README。本技能涵盖构建方面：搭建框架、生成、规划、组装和验证。若要评估现有文档，请参阅 indexion-documentation。

文件位置

各项目的约定有所不同；编辑前请检查实际存在的文件：

资源	常见位置
配置	doc.json（仓库根目录）或 .indexion/readme/doc.json
各包模板	docs/templates/readme.md（没有 SoT 常量；通过 --template 指定）
静态文本	docs/intro.md、docs/installation.md、docs/license.md、…
各包 README	cmd/<name>/README.md、src/<name>/README.md
组装后的根 README	通常是 README.md。有些项目使用 .mbt.md 后缀，让该文件同时成为 MoonBit doctest 模块——这种情况下，README.md 是指向 README.mbt.md 的符号链接。
.indexion.toml	[doc] config_path / per_package 会自动加载 doc.json

首先要检查的是 git diff / ls -la，确认是否存在：README.md 符号链接、doc.json（位于根目录或 .indexion/readme/ 下）以及 .indexion.toml。这些文件的存在情况能说明 README 是手动维护、构建组装还是混合方式生成。

工作流概览

doc init                      → .indexion/readme/template.md + doc.json (greenfield)
edit doc.json + docs/*.md     → declare sources of truth
doc readme --per-package      → cmd/<pkg>/README.md (API skeletons; non-overwriting)
hand-write each per-package README's Overview / Usage / Options / Examples
doc readme --config           → assembled root README
plan drift <prev> <new>       → verify the assembled output (or hand-edit) is purely additive

步骤 1：初始化（仅适用于全新项目）

indexion doc init <project-dir>

此操作会创建 .indexion/readme/template.md + .indexion/readme/doc.json。如果项目已经有 doc.json，或 .indexion.toml 已指向某个配置文件，请跳过此步骤。

步骤 2：配置 doc.json

{
  "$schema": "./schemas/doc-config.schema.json",
  "version": "1.0",
  "spec": "moonbit",
  "output": { "format": "markdown", "filename": "README.md" },
  "packages": [
    {
      "path": "cmd/<name>",
      "title": "<command name>",
      "include_in_root": true,
      "sections": ["overview", "usage"]
    }
    // …one entry per package that should appear in the assembled root README
  ],
  "root": {
    "output": "README.md",
    "sections": [
      { "type": "static",   "file": "docs/intro.md" },
      { "type": "toc",      "title": "Commands" },
      { "type": "packages", "filter": "cmd/**" },
      { "type": "static",   "file": "docs/installation.md" },
      { "type": "static",   "file": "docs/license.md" }
    ]
  }
}

根目录部分类型：

• static — 原样包含 Markdown 文件
• toc — 插入目录标题
• packages — 从 packages 数组中提取条目，并按 glob 进行筛选

包字段：

• include_in_root — 是否将该包纳入组装后的根 README
• sections — 要提取的 README 标题；由各包提取流程使用。请注意，根目录中的 { "type": "packages" } 当前会生成包链接表格，而不是各包 sections 所暗示的丰富概览/用法展开。请参阅下文的“已知限制”。

步骤 3：生成各包 README

indexion doc readme --per-package src/ cmd/

此操作会在每个尚无 README 的包目录中生成 README.md。不会覆盖——已有的各包 README 会保持不变。

生成的骨架仅包含 API 内容（通过 KGF 从 /// 文档注释中提取）。请将其作为起点，之后手动撰写概览、用法、选项和示例等文本部分。

# Single package to stdout
indexion doc readme src/kgf/lexer/

# Single package to a file
indexion doc readme -o=README.md src/kgf/lexer/

关于副作用的说明：doc readme --template=<t> <paths...>（下文的基于模板的模式）会遍历给定路径，并为尚无 README 的包自动创建各包 README——即使没有指定 --per-package 也是如此。如果对较大的路径（cmd/、src/）运行，可能会在无关包中生成新文件。请使用较窄的路径，或在之后通过 git status 检查并清理意外创建的文件。

步骤 4：编写静态内容

创建 docs/intro.md、docs/installation.md 等文件——具体取决于 root.sections 中引用的内容。这些是手写文本；组装器会原样纳入。

步骤 5：生成写作计划（可选）

indexion plan readme --template=docs/templates/readme.md --plans-dir=.indexion/plans src/

此操作会为各部分生成写作任务，供手动撰写或借助大模型协助撰写。

步骤 6：组装 README

# Config-driven (preferred; doc.json controls layout and packages list)
indexion doc readme --config=doc.json

# Template-driven (alternative; {{include:…}} and {{packages}} placeholders)
indexion doc readme --template=docs/templates/readme.md -o=README.md cmd/

配置文件可位于仓库根目录或 .indexion/readme/ 下。使用 .indexion.toml 中的 [doc] config_path = "…" 后，--config= 标志就可以省略。

步骤 7：使用 plan drift 验证

重新生成或手动编辑根目录 README 后，请验证变更仅为新增内容（没有悄然删除内容，也没有重新排版无关章节）：

# Snapshot the previous version
git show HEAD:README.md > /tmp/README.before.md

# Compare against the new version
indexion plan drift --top=20 /tmp/README.before.md README.md

请留意输出中的以下内容：

• Drift terms in /tmp/README.before.md (missing on the other side): (none)——没有删除任何内容
• Drift terms in README.md (missing on the other side): …——恰好是你打算新增的词汇（命令名称、新标志、新概念）
• 小幅新增内容的 Cosine similarity 接近 1.0；如果重组了某个章节，该值会显著降低

用于 CI 集成：

indexion plan drift --vocab-threshold=0.05 /tmp/README.before.md README.md
# exits 1 if cosine_distance > 0.05 — useful as a guard against accidental large rewrites

同样的工作流也适用于翻译后的 README 文件对（README.md ↔ README-ja.md）：跨语言漂移检测可直接使用，因为词汇子词切分会委托给 kgfs/natural/ 中的自然语言 KGF。

模板语法

模板文件支持 {{placeholder}} 替换：

占位符	展开内容
{{include:path}}	文件内容（相对于项目根目录）
{{packages}}	所有已发现的包（根据 CLI 的 --include / --exclude 进行筛选）
{{module_doc}}	仅模块级文档

.indexion.toml 集成

[doc]
config_path = "doc.json"   # auto-loads doc.json without --config
per_package = true         # makes `doc readme <path>` default to --per-package

显式指定的 --config=… 始终具有最高优先级。

已知限制：packages 根章节生成的是表格，而非丰富展开内容

doc-config.schema.json 允许在每个 packageEntry 上设置 sections: ["overview", "usage", …]，但当前的 doc readme --config 实现不会在根目录输出 { "type": "packages" } 时内联展开这些章节。它会输出一个包链接表格，描述为空。

这会带来两个实际影响：

1. 如果项目已纳入版本控制的根目录 README 包含丰富的逐命令 Overview / Usage 段落，那么这些内容目前并非由 doc readme --config 生成，而是手动维护的。将 doc readme --config -o=/tmp/regen.md 与已纳入版本控制的 README 进行差异比较，即可了解其中有多少内容是手动整理的；差异非常大说明 README 主要由手动维护。
2. 对于新命令，除了向 doc.json 添加包条目并编写对应包的 README 外，目前还需要在汇总后的 README 中手动补充丰富章节。使用上文的 plan drift 验证，确认手动编辑只会新增内容，不会删除内容。

如果你修复了此限制（使 { "type": "packages" } 遵循每个条目的 sections 设置），请更新此技能并移除此章节。

常见问题

“doc readme --per-package 没有生成任何内容”

• 所有包都已有 README。此命令只会创建新文件， 不会覆盖文件。请先删除现有 README，再重新生成。

“在 cmd/ 上运行 doc readme --template …，却在我未修改的包中创建了 README”

• 模板模式会在后台自动为缺少 README 的包生成文件。 请改用范围更窄的路径，或通过 git status 撤销意外创建的文件。

“自动生成的逐包 README 只有 API 列表”

• 这是有意如此。请手动编写 Overview、Usage、Options、Examples。对于 CLI 命令， 权威行为说明来自 indexion <command> --help。

“我对 README.md 的手动修改会被 doc readme --config 覆盖”

• 如果汇总器最终生成了丰富内容结构（见“已知限制”），确实会被覆盖。 在此之前，汇总器生成的内容是严格子集（表格），因此你对丰富章节的手动修改会保留。请务必运行 plan drift 交叉检查，确保无误。

“README.md 的编辑破坏了无关章节”

• 运行 plan drift HEAD:README.md README.md，查看上一版本对应的“missing on the other side”输出。如果其中列出的内容不是 (none)，就说明你删除了内容。