Agent Skills
返回列表
💻

Indexion README 构建

开发编程 更新于 2026.08.29

将以下提示词粘贴到你的 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` 段如何编排的新贡献者