Indexion README 构建
将以下提示词粘贴到你的 AI 对话框中:
请根据 https://skillhub.cn/install/skillhub.md,安装 @org-eyw2ohcx/trkbt10-indexion-skills-indexion-readme。
技能介绍
要解决的麻烦
多包仓库里根 README.md 往往要拼 intro、安装说明、各子包说明,还要从 /// 文档注释抽出 API 片段;有人手写、有人靠脚本,缺乏统一装配约定时,改一处容易漏另一处,也难以判断 doc readme --config 重生会不会抹掉你手工写的段落。
技能如何覆盖「构建」侧
本技能面向 indexion 的 README 构造流程,而不是评估已有文档质量(那属于 indexion-documentation)。开始前应先 git diff / ls -la 确认:README.md 是否为符号链接、doc.json 在根目录还是 .indexion/readme/、是否存在 .indexion.toml——从而判断是手写、组装还是混合模式。
典型步骤包括:
- 初始化:绿场项目创建
.indexion/readme/template.md与doc.json(已有配置则跳过) - 配置
doc.json:static引用docs/intro.md等;toc插入目录;packages按 glob 拉取包列表 - 按包生成:
doc readme --per-package不覆盖已有cmd/**/README.md;骨架来自 KGF 抽取的 API,Overview/Usage 需手写 - 组装与校验:
doc readme --config输出根 README;用 plan drift 对比,确认变更仅为增量、无静默删段
模板还支持 {{include:path}}、{{packages}}、{{module_doc}} 等占位符。
边界与坑
根级 { "type": "packages" } 目前只输出包链接表格,不会在根 README 内联展开 per-package 的 overview/usage——若你看到富文本段落,多半是手工维护的。doc readme --template 会在遍历路径时副作用式为缺 README 的包自动建文件,扫太宽路径要留意 git status。自动生成包内 README 设计为 API 清单,CLI 行为仍以 indexion --help 为准。
使用场景
- 接手 indexion 项目时先判断根 README 是手写、组装还是 symlink,再决定改 doc.json 还是直接改 Markdown
- 为新子包补齐 `cmd/**/README.md` 骨架,再手写 Overview/Usage,并确认不会触发 template 模式在无关目录建文件
- 根 README 改版后跑 plan drift,核对旧版词汇未被静默删除、仅增加预期命令与概念
- 在 doc.json 新增包条目后组装根 README,并手工补全 packages 表格无法生成的富文本段落
适合人员
- 维护 MoonBit/indexion 多包仓库、需要把静态文档与按包 README 合成根说明的库作者
- 为 CLI 子命令补文档、希望从 `///` 注释生成 API 骨架再补全用例的框架维护者
- 在 CI 中校验 README 与中/日双语对(如 `README.md` ↔ `README-ja.md`)无跨语言漂移的发布工程师
- 刚引入 `.indexion.toml` 与 `doc.json`,不清楚 `static`/`packages` 段如何编排的新贡献者