Markdown 目录自动生成器

要解决的问题

随着文档和 README 不断迭代，目录（TOC）往往滞后于正文结构。手动维护锚点容易出错，标题层级一旦调整，链接就可能失效、跳转错乱甚至 404。一次看似不大的重排，可能让整篇文档的导航变得不可信。

工作原理

技能在文档发布或更新前触发，调用上游工具 DocToc，扫描 Markdown 中的现有标题，自动生成或刷新可跳转的目录。

核心流程拆为三步：

• 定位标题：只读取已有标题，不新增、不删除。
• 生成锚点：依据标题文本生成稳定锚点链接，插入或更新 TOC 块。
• 增量刷新：对已存在目录做增量更新，避免重复插入，多次运行结果一致。

关键一点：它只做导航，不生成正文。文档内容先写好，再由它补齐目录。

适用边界与注意点

• 适用：README 更新、发布前目录刷新，尤其需要可靠文档内导航的仓库。
• 不适用：从零生成正文时还没有标题，应先完成内容再使用。
• 前置依赖：需要 Node.js、npm 与命令行；也可通过 Docker 镜像部署。
• 版本差异：不同 DocToc 版本的锚点规则略有差异，建议锁定上游版本，避免 CI 中目录格式漂移。