adk-bot-review

审查 adk-bot 提出的更改（adk-bot-review）

此技能指导如何严格审查 adk-bot 的更改，确保文档更新在技术上准确、范围恰当，并遵循 ADK 文档规范和 Google 开发者文档风格。

第 1 步：验证并研究 adk-bot 提出的更改

• 检查 PR 标题是否简要说明了更新主题，而不只是描述问题。
• 确认更改直接在 .md 文件中进行，并且没有过早移除“do not merge”状态标签。
• 检查 PR 的可合并状态和 CI 状态。将 git 冲突和失败的检查记录为待解决的问题，或在汇总 PR 中修复。
• 输入内容是一个由 adk-bot 编写的 PR，偶尔也可能有几个。从 PR 追溯到问题以及它要处理的具体事项。根据 PR 标题（“Update ADK doc according to issue # - ”）和正文确定该事项。adk-bot 经常会针对同一事项创建多个 PR。如果提供了多个 PR，请确认它们处理的是同一事项，并将其作为一组汇总内容一起审查。如果它们处理的是不同事项，请先询问用户要聚焦哪一个，再继续。
• 在整个代码仓库中搜索已关闭的问题以及已合并或已拒绝的 PR，查找相似主题。确保机器人不会重新引入维护者此前讨论并否决的更改、API 或风格选择。
• 总结该事项预期的更改及其说明的理由，并在接下来的步骤中依据这一意图进行技术验证。

第 2 步：评估更新标准和架构

• 优先进行范围较小、针对性强的更新；只有现有文档完全不清楚时，才进行全面改写。
• 确认更新能够带来有用的学习体验，并且开发者可以据此采取行动。
• 确保内容在 ADK 文档信息架构中的位置恰当。
• 确认更新篇幅和优先级适合具体的代码更改（检查现有文档或 API 参考中是否已涵盖相关内容）。

第 3 步：根据源代码和意图验证更改

• 绝不要假定 AI Agent 的代码片段正确。
• 对照 https://github.com/google/adk-python 仓库交叉检查所有代码示例。
• 根据相关 pull request 和 https://github.com/google/adk-python 仓库中的实际 ADK 代码核实信息。
• 确认更改确实实现了关联问题和 adk-bot PR 所要达成的目标，并解决了其中引用的问题事项。
• 标记任何偏离既定意图的更改，以及更改未能涵盖的意图部分。

第 4 步：检查质量和风格

标题

• 保持 h1、h2、h3 层级合理，不要出现空标题（连续堆叠标题）。
• 标题不要编号（使用 ## This heading，而不是 ## 1. This heading）。
• 使用祈使语气的标题（例如，“Build agents”，而不是 “Building agents”）。
• 标题中不要使用命令名称；应指出要完成的任务。

语言

• 以 Google 开发者文档风格（https://developers.google.com/style）作为规范依据；对于其中未涵盖的内容，请查阅该风格指南。
• 使用主动语态（例如，“The system does X”，而不是 “X is done”）。
• 绝不要在没有名词宾语的情况下使用单词 “this”（例如，“This function is used...”，而不是 “This is used...”）。

代码片段和格式

• 普通 Markdown 文本每行不得超过 80 个字符（较长的 URL、不可拆分的代码块或表格除外）。
• 检查反引号（```）前的空格是否会导致渲染错误。
• 笔记和警告使用 mkdocs-material 的 !!! warning/tip/note 告示格式，不要使用引用格式（>）。
• 除代码语法外，不要使用全大写；需要强调时使用粗体或斜体。

步骤 5：汇报检查结果并确定建议

首先，汇总上述验证步骤的检查结果，按阻塞项、必需修改、细节问题的顺序排列。然后从以下结果中选择一项，并根据检查结果说明理由：

• 关闭机器人 PR。（有时）更改有误、已过时、针对已弃用或尚未发布的 API，或者相关内容已由现有文档或已合并的 PR 覆盖。记录原因，并链接替代文档或 PR。
• 原样批准（很少）。机器人 PR 正确、位置合适，无需修改。
• 直接编辑后批准（有时）。现有分支可用，但需要解决冲突、纠正错误、合并内容、润色文案或调整位置。
• 新建一个整合 PR（最常见）。将 1-3 个机器人 PR 的更改重新整理成一个 PR，修复代码错误和幻觉内容、提升质量，并将内容放在正确的文件中。然后关闭已被取代的机器人 PR。

还要确认更改针对的是正确的文件（文件可能已移动或重新整理，或者修改内容本该放在其他页面）。

步骤 6：制定行动计划

输出所选建议对应的具体后续行动：

• 需要进行的具体本地修改：文件路径、修改内容、代码修复、整合 1-3 个机器人 PR，以及正确的内容位置。
• 简要列出支持建议的验证结果，按阻塞项、必需修改、细节问题的顺序排列（阻塞项包括未经验证或虚构的代码、文件有误、CI 检查失败、渲染异常）。
• 需要关闭哪些机器人 PR。
• 按照仓库规范撰写 PR 描述：
  • 用简短的项目符号列表概述更改内容
  • Rendered page: <预览链接>
  • Agent PR: <链接>
  • Original issue: # - <条目>

需要遵循的风格规则

• 示例代码中的模型字符串应使用 gemini-flash-latest、gemini-pro-latest 或其他有效的 *-latest 别名，而不是特定版本的模型字符串，因为发布新模型版本时，后者会增加维护负担。
• 导入语句：from google.adk.agents import Agent；MCP 使用 from google.adk.tools.mcp_tool import McpToolset。Python 中的 Agent 变量为 root_agent。
• 不使用长破折号，也不写冗长的 AI 生成内容：在 **术语**：定义 项目符号中使用冒号；否则将内容拆分成多个句子。
• 提及 ADK 时，只使用“ADK”，不要使用“Google ADK”或“The ADK”。
• 句子不要以行内代码词语开头。
• ADK 文档内部链接使用站点相对路径（例如 /sessions/memory/）；外部链接必须可访问。不要编造链接。
• 根据实际 API 和库代码验证所有代码示例。权威源代码仓库列于 docs/community/contributing-guide.md。