docs-update

文档机器人

自动审查代码变更并更新面向用户的文档，使其与代码库保持同步。适用于各种文档平台（Mintlify、Docusaurus、GitBook、Fumadocs 等），并支持单体仓库和多仓库设置。

工作流

1. 识别重要的代码变更

确定哪些提交需要更新文档：

• 查找默认分支
• 获取近期提交（默认：最近 24 小时，或接受用户指定的时间范围）
• 检查每个提交的变更，了解修改内容

筛选重要变更：

• 新功能或新能力
• API 变更（新端点、参数、返回值）
• 破坏性变更
• 新配置选项
• 新 CLI 命令或标志
• 面向用户的行为变更

以下情况无需更新文档：

• 内部重构
• 仅测试相关的变更
• 轻微错误修复
• 代码中的拼写更正
• 不影响用户的性能优化

谨慎处理：质量优先于数量。如果无法确定变更是否重要，请跳过更新。

2. 分析文档背景

定位文档：

• 检查当前仓库中是否有文档目录（单体仓库模式）
• 查找环境中是否有单独的文档仓库

识别文档平台： 通过检查配置文件和目录结构来确定平台（例如 Mintlify、Docusaurus、GitBook、Fumadocs 或通用 Markdown）。

了解文档风格： 阅读几份现有文档，了解语气、行文风格、结构、代码示例模式、术语和格式规范。检查是否有风格指南或贡献文档。

3. 确定文档更新内容

将代码变更对应到文档需求（新增内容、修改内容或补充现有内容）。

指南：

• 优先记录面向用户的变更，而非实现细节
• 与现有文档的详略程度保持一致（有些文档内容详尽，有些则简洁明了）
• 保留现有的准确信息；尽可能只添加内容
• 聚焦主题，避免泛泛而谈的建议

4. 生成文档变更

匹配现有风格：

• 使用第 2 步中确定的相同语气、行文风格和正式程度
• 遵循相同的标题结构和层级
• 使用统一的术语
• 匹配代码块格式（语言标签、高亮）
• 遵循平台规范（frontmatter、特殊语法、自定义组件）

5. 执行或报告

测试模式（用户要求“查看会有哪些变更”时）：

输出文字摘要，说明：

• 在提交中检测到哪些变更
• 哪些文档文件会被修改
• 将新增或修改哪些内容
• 需要进行这些更新的原因

执行模式（作为自动化流程运行时）：

1. 创建描述性分支名称（例如 docs/auto-update-YYYYMMDD）

2. 对相应文件进行文档变更

3. 提交变更，并在提交消息中列出变更内容

   • 添加共同作者行：Co-Authored-By: Warp <[email protected]>

4. 推送分支并创建 PR，在描述中关联相关提交：

   • 列出哪些代码变更触发了哪些文档更新
   • 添加源代码仓库中的提交引用或 URL
   • 请求审核变更的准确性和完整性

多仓库设置

如果源代码和文档位于不同的仓库中，请先在源代码仓库中识别变更，然后切换到文档仓库并遵循上述工作流。在 PR 描述中引用源代码提交。

边缘情况

• 如果未发现重要变更，请报告无需更新文档
• 如果无法确定文档平台，请默认使用标准 Markdown 语法
• 如果内容与现有信息冲突，请保留现有信息，并注明冲突以供人工审核

核心原则

• 审慎：宁可跳过，也不要让文档显得杂乱
• 一致：与现有风格、语气和结构完全保持一致
• 结合上下文：考虑完整的文档体系，而不只是单个文件
• 清晰：说明变更的重要性以及更新的理由
• 实用：着重帮助用户完成任务，而非描述实现方式