sync-docs

sync-docs 技能是一款专为软件工程师设计的专业自动化工具，旨在维护高质量且即时更新的专案文档。它作为一个编排引擎，分析源代码与项目文档之间的关联，确保 README、变更日志与技术文档能反映代码库的真实状态。通过整合 Git 并利用 repo-map 等静态分析工具，它能识别在快速开发周期中经常出现的差异，例如被移除的函数导出、教程中过时的代码片段或导入路径的变更。此技能适用于 Pull Request 审核前、版本发布准备阶段或重大重构后，以确保项目产出物中不会堆积技术债。

• 自动根据变更文件及如 README.md、CHANGELOG.md 等文件模式发现相关文档。

• 通过比较 package.json 中的项目元数据与文档版本进行版本验证。

• 导出项分析，用于检测出现在文档中但实际上已不存在于实现中的代码符号，有效找出过时的参考信息。

• 变更日志维护，通过扫描“Unreleased”区段并验证提交消息与记录之变更是否对齐。

• 智能备援机制，若未安装如 ast-grep 等进阶 AST 工具，则自动改用基于正则表达式 (regex) 的检测方式。

• 结构化的结果汇报，在不进行未经授权之直接修改的前提下提供可操作的反馈，让开发者在应用变更前能先进行检阅。

• 用户应通过以下语法调用此技能：sync-docs [report|apply] [--scope=all|recent|before-pr] [--include-undocumented]。

• 默认范围集中在自上次提交至 main 分支以来的变更，这针对开发期间的快速检查进行了优化。

• --include-undocumented 标志对于发掘缺乏技术文档说明的公开 API 接口非常实用。

• 虽然工具提供了 apply 模式，但它是在安全优先的架构下运作，由编排器负责管理最终的变更应用。

• 限制：若能初始化 repo-map.json，将能显著增强符号检测的有效性；在较大且复杂的仓库中，系统可能会建议用户安装 ast-grep 以达到最高准确度。