name: docs-update description: 当代码变更时更新用户文档。适用于更新文档、审查文档、处理文档变更、运行计划文档任务或分析最近提交以确定文档需求。 license: MIT
文档机器人
自动审查代码变更并更新用户文档，以保持与代码库同步。支持跨文档平台（如Mintlify、Docusaurus、GitBook、Fumadocs等），并适用于单仓库和多仓库设置。
工作流程
1. 识别重要代码变更
确定哪些提交需要文档更新：
- 找到默认分支
- 获取最近提交（默认：最近24小时，或接受用户指定时间段）
- 检查每个提交的变更，以了解修改内容
筛选重要变更：
- 新功能或能力
- API变更（新端点、参数、返回值）
- 破坏性变更
- 新配置选项
- 新CLI命令或标志
- 用户行为变更
跳过文档更新：
- 内部重构
- 仅测试变更
- 次要错误修复
- 代码中的拼写更正
- 无用户影响的性能优化
保守处理：质量优于数量。当不确定重要性时，跳过更新。
2. 分析文档上下文
定位文档：
- 检查当前仓库中的文档目录（单仓库模式）
- 在环境中查找单独的文档仓库
识别文档平台： 通过检查配置文件目录结构确定平台（如Mintlify、Docusaurus、GitBook、Fumadocs或通用Markdown）。
理解文档风格： 阅读几个现有文档文件，以识别语气、声音、结构、代码示例模式、术语和格式化约定。检查风格指南或贡献文档。
3. 确定文档更新
将代码变更映射到文档需求（新内容、修改或添加到现有内容）。
指南：
- 优先处理用户面变更，而非实现细节
- 匹配现有文档的详细程度（有些文档全面，其他最小化）
- 保留现有准确内容——尽可能严格添加
- 保持内容聚焦，避免通用建议
4. 生成文档变更
匹配现有风格：
- 使用步骤2中识别的相同语气、声音和正式程度
- 遵循相同的标题结构和层次
- 使用一致的术语
- 匹配代码块格式化（语言标签、高亮）
- 遵循平台约定（frontmatter、特殊语法、自定义组件）
5. 执行或报告
测试模式（当用户要求“查看会有什么变更”时）：
输出文本摘要描述：
- 在提交中检测到什么变更
- 哪些文档文件将被修改
- 将添加或更改什么内容
- 为什么需要这些更新的理由
执行模式（作为自动化运行时）：
-
创建一个描述性分支名称（例如
docs/auto-update-YYYYMMDD） -
对适当文件进行文档变更
-
提交并带有描述性消息，列出变更
- 包含共同作者行：
Co-Authored-By: Warp <agent@warp.dev>
- 包含共同作者行：
-
推送分支并创建PR，描述中链接到相关提交：
- 列出哪些代码变更触发了哪些文档更新
- 包括源仓库的提交引用或URL
- 请求审查准确性和完整性
多仓库设置
当源代码和文档位于不同仓库时，识别源仓库的变更，然后切换到文档仓库并遵循上述工作流程。在PR描述中引用源提交。
边缘案例
- 如果未找到重要变更，报告不需要文档更新
- 如果文档平台不明确，默认使用标准Markdown语法
- 如果与现有内容冲突，保留现有信息并记录冲突供人工审查
关键原则
- 保守性：宁愿跳过，也不要混乱文档
- 一致性：精确匹配现有风格、语气和结构
- 上下文性：考虑完整文档环境，而不仅是单个文件
- 清晰性：解释变更的重要性和更新理由
- 实用性：专注于帮助用户完成任务，而非描述实现