indexion-readme

indexion readme — README 构建

从模板、文档注释、手写散文和每个包的 README 构建项目 README。此技能涵盖构建方面：脚手架、生成、规划、组装和验证。如需评估现有文档，请参见 indexion-documentation。

文件位置

约定因项目而异；编辑前请检查实际存在的内容：

资产	常见位置模式
配置	doc.json（仓库根目录）或 .indexion/readme/doc.json
每个包的模板	docs/templates/readme.md（无固定来源；通过 --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 文档测试模块 — 此时 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（全新项目）
编辑 doc.json + docs/*.md     → 声明数据来源
doc readme --per-package      → cmd/<pkg>/README.md（API 骨架；不覆盖）
手动编写每个包 README 的概述/用法/选项/示例
doc readme --config           → 组装的根 README
plan drift <prev> <new>       → 验证组装输出（或手动编辑）是纯添加性的

步骤 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": "<命令名称>",
      "include_in_root": true,
      "sections": ["overview", "usage"]
    }
    // …每个应出现在组装根 README 中的包对应一个条目
  ],
  "root": {
    "output": "README.md",
    "sections": [
      { "type": "static",   "file": "docs/intro.md" },
      { "type": "toc",      "title": "命令" },
      { "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 从 /// 文档注释中提取）。将其视为起点，之后手动编写散文部分（概述、用法、选项、示例）。

# 单个包输出到标准输出
indexion doc readme src/kgf/lexer/

# 单个包输出到文件
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/

为手动或 LLM 辅助写作生成每个部分的写作任务。

步骤 6：组装 README

# 配置驱动（推荐；doc.json 控制布局和包列表）
indexion doc readme --config=doc.json

# 模板驱动（替代方案；{{include:…}} 和 {{packages}} 占位符）
indexion doc readme --template=docs/templates/readme.md -o=README.md cmd/

配置路径可以位于仓库根目录或 .indexion/readme/ 下。使用 .indexion.toml 的 [doc] config_path = "…" 时，--config= 标志变为可选。

步骤 7：使用 plan drift 验证

在重新生成或对根 README 进行任何手动编辑后，验证更改是纯添加性的（没有静默删除，没有重新排列不相关的部分）：

# 快照之前的版本
git show HEAD:README.md > /tmp/README.before.md

# 与新版本比较
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
# 如果 cosine_distance > 0.05 则退出码为 1 — 用作防止意外大规模重写的保护

相同的工作流程适用于翻译的 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"   # 自动加载 doc.json，无需 --config
per_package = true         # 使 `doc readme <path>` 默认使用 --per-package

显式 --config=… 始终优先。

已知限制：packages 根部分生成表格，而非丰富展开

doc-config.schema.json 允许在每个 packageEntry 上使用 sections: ["overview", "usage", …]，但当前的 doc readme --config 实现在根中发出 { "type": "packages" } 时，不会内联展开这些部分。输出是一个包链接的 markdown 表格，描述为空。

两个实际后果：

1. 如果项目已检入的根 README 具有丰富的每个命令概述/用法段落，则它们不是由当前的 doc readme --config 生成的。它们是手动维护的。将 doc readme --config -o=/tmp/regen.md 与检入的 README 进行差异比较，以查看其中有多少是手动策划的；非常大的差异意味着 README 主要是手动维护的。
2. 对于新命令，你当前需要同时手动编辑丰富部分到组装的 README 中，除了将包条目添加到 doc.json 并编写每个包的 README。使用上面的 plan drift 验证来确认手动编辑仅添加，从不删除。

如果你修复了这个限制（使得 { "type": "packages" } 尊重每个条目的 sections），请更新此技能以删除此部分。

常见陷阱

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

• 所有包已有 README。该命令仅创建新文件，从不覆盖。先删除现有 README 以重新生成。

"doc readme --template … 在 cmd/ 上创建了我未触及的包的 README"

• 模板模式会作为副作用自动生成缺失的每个包 README。要么传递窄路径，要么从 git status 中还原意外创建的文件。

"自动生成的每个包 README 只是 API 列表"

• 这是设计使然。手动编写概述、用法、选项、示例。对于 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) 之外的任何内容，则你删除了内容。