update-readme

README 更新工作流

适用场景

每当 README 需要进行结构性更新时，使用此技能。 先运行 Skill(sanctum:git-workspace-review)，以了解仓库背景和差异。

不适用场景

• 更新内联文档：使用 doc-updates
• 整合临时报告：使用 doc-consolidation

必需的进度项

1. update-readme:language-audit
2. update-readme:exemplar-research
3. update-readme:outline-aligned
4. update-readme:edits-applied
5. update-readme:slop-scanned - 通过 scribe 检测 AI 标记
6. update-readme:verification-reporting

步骤 1 - 语言审查（update-readme:language-audit）

• 确认 pwd、git status -sb，以及用于参考的基线分支。
• 使用仓库启发式方法（清单文件、文件数量）检测主要语言。
• 记录会影响文档的次要语言（例如，TypeScript 前端和 Rust 后端），以便 README 能同时介绍二者。
• 记录所用方法和发现。

详细的检测模式和命令请参见 modules/language-audit.md。

步骤 2 - 范例研究（update-readme:exemplar-research）

• 对每种主要和次要语言，使用网页搜索查找高质量 README（星标数、近期更新情况、维护者活跃度）。
• 每种语言选取 2-3 个范例仓库，并总结其相关之处（章节顺序、视觉元素、快速入门的清晰度、治理信息、数学内容讲解等）。
• 保存每个范例的引用，以便最终摘要明确引用它们。

搜索查询模式和评估标准请参见 modules/exemplar-research.md。

步骤 3 - 大纲对齐（update-readme:outline-aligned）

README 是索引，不是手册。 开篇说明项目是什么、如何安装，并提供一张便于浏览的单元（插件、命令、软件包）表格；其他内容都链接到别处。

README 是面向 newcomer 的文档。 读者从未接触过这个项目，因此判断每个候选章节是否应保留的标准是：读者能否在安装并运行一个功能之前用到它。原理、备选方案和内部细节属于 expert 内容：将它们提取到 docs/deep-dive/<topic>.md 或 book/，并在 README 中用一行链接说明该页面面向的读者。绝不要为了缩短 README 而删除这些内容。层级表和删减测试：scribe:slop-detector 模块 audience-targeting.md。

如果 README 声明了不同的层级（例如内部工具，且读者都是已经在使用它的人），应在开篇说明。

2026 年简化本仓库根目录的 README 时，通过删除内嵌的深度内容并改为链接到 book/，将其从 435 行缩减到 200 行（字数减少 65%）。目标应是这种结构，而不是逐节检查是否覆盖全面。

• 将当前 README 标题（rg -n '^#' README.md）与步骤 2 中的范例进行比较。精简的市场和 CLI 工具 README（asdf-vm/asdf-plugins、ohmyzsh/ohmyzsh、ryoppippi/ccusage）都采用索引结构：介绍文字约少于 500 词，由单元表格承担主要内容，深度内容则通过链接提供。
• 只保留值得出现在索引中的章节：一行价值主张、一种安装方式、精简的命令或单元表格、简短的“内容概览”、一个文档链接章节，以及最后列出的元数据（要求、贡献、许可证）。对于其他每个候选章节，都要问：这应该放在 README 中，还是放在链接指向的页面中？
• 默认链接到其他页面。将深入的架构说明、常见问题、路线图、变更日志、其他安装方式和各单元的详细信息移至各自的页面。各单元文档应与单元放在一起（中心辐射式结构），不要在根目录中重复。
• 顺序体现优先级：先是标题和标语，然后是安装方式、索引表格、简短的功能概览、文档链接，最后是维护信息（要求、贡献、许可证）。
• 将内部文档（docs/、book/、specs/、commands/）对应到链接它们的章节，使 README 能引导读者深入了解，而不是重述这些内容。

软性预算：市场或集合项目的根目录 README 通常约为 150-400 行正文，另加任何索引表格。会随时间增长的章节（路线图、常见问题、变更日志）应放在链接指向的页面中，而不是 README 中。

步骤 4 - 应用编辑（update-readme:edits-applied）

• 直接在 README.md（或指定文件）中实现新的结构。
• 遵循 Skill(leyline:markdown-formatting) 规范：正文每行不超过 80 个字符（优先在句子或分句边界换行），标题前后留空行，仅使用 ATX 标题，列表前留空行，长 URL 使用引用式链接。
• 保持文字简洁且有依据；避免营销套话。
• 优先删除并添加链接，而不是内嵌内容。如果某个章节与文档页面重复，就删去并链接到该页面；如果内容会随时间增长，则将其完全移出 README。
• 只有在比较表、功能列表或示意图源自当前仓库资源时才添加，不要添加推测性内容。
• 提及算法或性能声明时，应指向仓库内的基准测试或测试，或指向有记录的数学评审。

步骤 4.5 - AI 废话检测（update-readme:slop-scanned）

对更新后的 README 运行 Skill(scribe:slop-detector)，检测 AI 生成内容的标记。

Scribe 集成

scribe 插件提供 AI 灌水检测：

Skill(scribe:slop-detector) --target README.md

它可以检测：

• 一级词汇：delve、tapestry、comprehensive、leveraging 等
• 短语模式：“In today's fast-paced world”“cannot be overstated”
• 结构标记：过度使用 em 破折号、滥用项目符号、句式单调
• 营销语言：“enterprise-ready”“cutting-edge”“seamless”

整改

如果灌水评分超过 2.0（中等），请运用 Skill(scribe:doc-generator) 原则：

1. 用具体内容为每项主张提供依据
2. 删除公式化的开场和结尾
3. 多用数字、命令和文件名，少用形容词
4. 平衡项目符号与叙述性文字
5. 展现作者视角（权衡、推理）

如需大幅清理，请使用：

Agent(scribe:doc-editor) --target README.md

步骤 5 - 验证与报告 (update-readme:verification-reporting)

• 重新阅读更新后的 README，检查其清晰度、可访问性（章节长度、项目符号是否平衡）以及链接是否准确。
• 运行 git diff README.md（或已编辑的文件），并截取片段用于最终报告。
• 总结检测到的语言、示例来源（附引用）、关键结构决策和后续待办事项（例如添加徽章、上传图表）。

退出标准

• 所有进度项均已完成。
• README 采用索引式结构：简介控制在软性篇幅预算内（约 150-400 行，另加任何单元表格），提供一种安装方式，以及便于浏览的单元／命令表。
• README 中没有章节与 book/ 或 docs/ 页面重复；详细内容应通过链接引导，而非直接嵌入（rg -n '^#' README.md 中的每个标题都应对应一个值得收录在索引中的章节）。
• README 面向 newcomer；否则应在开头说明其面向的层级。
• 为适应目标层级而删减的内容应放在有链接指向的页面中，而非丢弃（docs/deep-dive/ 或 book/）。
• README 引用了内部文档和外部示例，并附有引用。
• 已记录研究笔记和命令参考，方便未来审阅者复现流程。

故障排查

常见问题

文档不同步 运行 make docs-sync-check，确认能力文档仍与插件注册信息一致

构建失败 检查是否已安装所有必需的依赖项

链接失效 检查文档文件中的相对路径