integration-review

ADK 集成页面审查员（integration-review）

此技能用于指导对 adk-docs 仓库中集成文档页面进行严格审查。集成页面位于 docs/integrations/ 下，用于介绍第三方工具、插件、可观测性平台、数据存储、MCP 服务、连接器以及 ADK Agent 的其他扩展。

本次审查的权威依据是：

1. 仓库的 CONTRIBUTING.md（请参阅“Integrations”部分及其验收标准）。
2. 现有的已发布集成页面，它们是真正的模板。务必打开并与同类别的页面进行对比：
   • MCP 工具：docs/integrations/github.md、docs/integrations/notion.md
   • 可观测性：docs/integrations/phoenix.md、docs/integrations/arize-ax.md
   • 插件：docs/integrations/daytona.md、docs/integrations/goodmem.md
3. 目录渲染逻辑：scripts/integrations.py。

说明

每当有人要求审查集成页面或集成 PR 时，都要阅读此技能并遵循其中的步骤。

审查流程

第 1 步：收集变更

• 如果审查 PR，请使用 gh 拉取并阅读完整的累计差异，而不是只看单个提交：gh pr view <n> --repo google/adk-docs 和 gh pr diff <n> --repo google/adk-docs。过时的 mkdocs.yml 条目或资源文件可能只会出现在完整差异中。
• 检查是否启用了“Allow edits from maintainers”（maintainerCanModify），以便之后需要时可以直接推送修复。
• 确认 CLA 已签署（google-cla bot）。未签署的 CLA 属于 🔴 严重问题，在签署前不得合并。
• 如果审查本地文件，请运行 git status 和 git diff 查看变更。

第 2 步：查找并阅读相似页面

查找至少 5 个相似页面并通读全文。可先扫描 catalog_tags（grep catalog_tags docs/integrations/*.md），一次性找出候选页面，并匹配正在审查的标签（例如 mcp、observability）；再根据产品领域、结构模板和语言支持等其他线索扩大范围（它们不必都属于完全相同的类别）。通读全文，而不只是 frontmatter，才能依据实际示例和仓库惯例开展审查，而不是从此技能中的模板推断一切。

第 3 步：逐项检查清单

逐一检查下方审查清单中的所有维度。

第 4 步：验证代码、软件包和链接

进行实际验证，而不是只做表面检查（请参阅“深入验证”）。

第 5 步：调查开发者价值和成熟度

收集关于项目成熟度、采用情况以及是否真正与 ADK 集成的客观证据（请参阅“开发者价值和成熟度”）。评估应以可验证的事实为依据，而非主观印象或 PR 自身的宣传内容。

第 6 步：报告、决策并停止

生成按优先级排序的报告（请参阅“报告格式”），然后给出“审查决策与回复”中要求的三项后续内容：顶层审查回复、决策（批准、要求修改或关闭 PR），以及带行号定位的评论草稿。不要编辑文件、向 GitHub 发帖，也不要默认提出修复问题。完成后停止，并等待明确的修复指示。

第 7 步（仅在收到要求时）：应用修复

只有在用户明确要求修复发现的问题时，才应用精确修改；尽可能保留贡献者的措辞；除非另有指示，否则只修复 ADK 自身的问题（将供应商 SDK 的 Bug 留给作者处理）；在可行时使用 mkdocs serve 验证。

审查清单

1. Frontmatter（目录元数据）

每个页面开头都必须包含且仅包含以下四个 YAML 字段：

---
catalog_title: <Display Name>
catalog_description: <short verb-led phrase>
catalog_icon: /integrations/assets/<slug>.png
catalog_tags: ["<tag>", "<tag>"]
---

• catalog_title：卡片上显示的易读产品名称。
• catalog_description：简短、以动词开头，约 45 到 75 个字符（约 6 到 11 个词）。如果超过约 80 个字符，应标记为可能会在卡片上出现不自然的换行。不得重复产品名称（标题中已有）。不要冗长列举技术；应描述集成的用途。不要夸大其能力。
• catalog_icon：/integrations/assets/<slug>.png（或 .svg 或 .jpg）。引用的资源文件必须实际存在于 docs/integrations/assets/ 中，且为有效图像。
• catalog_tags：由小写标签组成的 JSON 数组。只能使用目录中已有的标签；切勿自行编造新标签。 标签可以组合（例如 ["data", "mcp"]）。正文中使用 MCP 的页面必须包含 mcp 标签。运行一次 grep catalog_tags docs/integrations/*.md，列出有效标签。

2. 结构和必需元素

• H1 标题格式为 # <Product> <type> for ADK，其中 <type> 应与类别相符（例如 # GitHub MCP tool for ADK、# AgentOps observability for ADK、# Daytona plugin for ADK）。

• H1 后立即添加语言支持标签，使用 HTML（不能使用粗体 Markdown）：

  <div class="language-support-tag">
    <span class="lst-supported">Supported in ADK</span><span class="lst-python">Python</span><span class="lst-typescript">TypeScript</span>
  </div>
  

  • 仅支持 Python 的集成应删除 TypeScript span。
  • 各个 span 必须位于同一行。 不得将 span 拆分到多行。
  • 使用普通粗体 Markdown 代替此 div 属于缺陷。

• 章节顺序应符合以下三种类别模板之一：

  • MCP 工具：## Use cases -> ## Prerequisites -> ## Use with agent（Python / TypeScript 选项卡）-> ## Available tools -> ## Configuration（可选）-> ## Additional resources
  • 可观测性：简介 -> ## Overview -> ## Installation -> ## Setup -> ## Observe -> ## Support and Resources
  • 插件：## Use cases -> ## Prerequisites -> ## Installation -> ## Use with agent -> ## Available tools -> ## Configuration（可选）-> ## Additional resources

• 章节名称：优先使用 ## Use with agent，而不是 ## Usage 或冗长的 ## Example: ... 标题。安装步骤优先使用 ## Installation。优先使用具体名称（Available tools、Available methods），而不是笼统的 ## API。

• 标记内容过少或过度拆分的章节（许多 H2 章节都只有一个代码块）；建议合并为带编号步骤的 ## Setup。一个可直接复制粘贴、端到端的代码块完全可行，而且通常比拆分为 Setup/Observe 更方便用户。

3. 代码正确性

• 示例代码中的模型字符串应使用 gemini-flash-latest、gemini-pro-latest 或其他有效的 *-latest 别名，而不要使用特定版本的模型字符串；后者会增加新模型版本发布时的维护负担。
• 标准导入语句：from google.adk.agents import Agent（简写形式）；MCP 使用 from google.adk.tools.mcp_tool import McpToolset。
• Agent 变量应为 root_agent（Python）/ rootAgent（TypeScript）；TypeScript 文件末尾应为 export { rootAgent };。
• MCP 示例应使用 MkDocs Material 选项卡（=== "Python" / === "TypeScript"，相关情况下使用嵌套子选项卡，例如 === "Local MCP Server"）。选项卡内的 admonition 应缩进 8 个空格。
• 代码必须完整、可运行，并符合实际的 ADK 和供应商 API（参见“Deep verification”）。

4. 风格与排版

• 尽量少用破折号及其他常见的 AI 生成内容特征。 对于 **term** — definition 这样的项目符号，将破折号替换为冒号；在正文中 拆分成两个句子，或使用逗号／括号。对于第三方所有的内容，标记问题但留给作者处理；对于你编辑的内容，删除这些破折号。
• 在正文和代码注释中，Agent Development Kit 应简称为“ADK”，绝不要称作“Google ADK”或“The ADK”。
• 句子不要以行内代码开头。 改写句子（例如：“package-name 库添加了……”而不是“package-name 添加了……”）。
• 避免营销倾向。 这些是 ADK 文档；删除带有营销意味、夸大其词的内容。

5. 链接与资源

• ADK 文档内部链接应使用站点相对路径（例如 /sessions/memory/），而非绝对链接 https://adk.dev/... 或旧版链接 https://google.github.io/...。相对链接可在 PR 预览中正常解析，适应域名变更，也能通过链接检查器检测。对于供应商所有的页面，这只是小问题，但通常应修复。
• 来自 docs/integrations/ 页面中的图片引用应使用 assets/<img>.png，而不是 ../assets/...，除非图片确实位于 docs/assets/。请根据同类页面实际使用的路径核对，不要凭空推测。
• 外部链接必须可访问（HTTP 200）。查找指向不存在的仓库、示例或文档的虚构链接。发现此类链接时，建议删除，或请作者提供正确的目标，而不是自行猜测。

6. 目录机制

• 集成页面由 docs/integrations/index.md 中的 render_catalog('integrations/*.md') 自动发现。无需在 mkdocs.yml 中添加导航项；添加导航项是错误的。
• 卡片按文件名的字母顺序排序。选择排序合理的文件名，并去掉包名作为前缀（例如，使用 mongodb.md，而不是 mongodb-mcp-server.md；避免使用会排到最前面的 adk- 前缀文件名）。
• 只有在页面从现有 URL 重命名或移动时，才在 mkdocs.yml 中添加重定向。重定向应直接指向最终目标；绝不要串联重定向。
• 添加新的集成时，只需提供带有正确 frontmatter 的 .md 文件和 assets/ 中的图标资源。

深入验证

根据实际 API 和库代码验证所有代码示例。规范源代码仓库列在 docs/community/contributing-guide.md 中。

• 确认包的实际情况：确认 PyPI（或 npm）上存在该软件包，并确保文中所述版本和 Python 要求与实际情况相符。
• ADK API：根据相关语言 SDK 的规范源代码仓库（列于 docs/community/contributing-guide.md）验证代码示例中使用的每个 ADK 符号和模式，例如 Runner、run_async、create_session、append_event、save_artifact、 session／artifact 服务 URI、adk web／adk run CLI 标志以及 genai 类型。 不要假设本地已有代码库：使用 gh 或 git 获取源代码（如果已有本地克隆，也可以使用），并检查文档所针对的已发布版本，而不是可能领先或落后于该版本的 main 分支。记录你验证所依据的版本，并标记不匹配之处。
• 供应商 SDK：根据供应商 SDK 源代码或文档验证供应商的类、方法和参数。
• 问题归属：区分由 ADK 负责的问题和由供应商 SDK 负责的问题（标记问题并留给作者处理）。
• 尽可能手动测试：使用真实的 ADK Agent 运行示例；至少运行 mkdocs serve，确认卡片可以正常显示且图标能加载。

开发者价值和成熟度

集成页面属于 ADK 官方文档，因此集成必须提供真实且有证据支持的开发者价值，才值得收录。此处的目标是调查并判断该集成面向的是一个成熟的平台，具备实际用途、良好的记录和真实的采用情况，还是一个全新或采用率低、缺乏实质内容的项目。请进行调查并报告证据；不要根据 PR 自身的描述或营销内容推断其价值。

收集客观、可验证的信号，并为每项信号注明来源：

• 软件包的实际情况和历史：确认确实存在已发布的软件包。查询 PyPI JSON API（https://pypi.org/pypi/<pkg>/json）或 npm registry（https://registry.npmjs.org/<pkg>），了解首次发布的日期、发布次数和最新版本，并检查下载量（pypistats 或 npm downloads API）。软件包不存在，或与 PR 在同一天发布，是强烈的负面信号。
• 源代码仓库信号：使用 gh api repos/<owner>/<repo> 获取 created_at、星标数、复刻数、贡献者人数、提交次数、发布记录、许可证和最后提交日期。仓库创建于最近几周、只有少量提交、只有一位作者或没有许可证，都是负面信号。
• 采用情况和记录：根据可验证的信号评估实际使用情况：软件包下载量（见上文）、仓库星标数、复刻数和依赖该项目的其他项目，以及通过网络搜索找到的已记录的生产用户、案例研究或独立第三方报道，并了解产品已运营多久。广泛且可验证的使用情况是正面信号；所有来源都找不到相关证据则是负面信号。
• 真正的 ADK 集成：确认项目确实使用 ADK 扩展点（回调、插件、工具集、MCP），而不是修改 google-genai 等依赖项，或仅用普通函数封装 REST API 并将其作为 ADK 集成（请对照“深入验证”和下方的范围触发条件进行交叉核查）。
• 网站是否正常运行：确认链接指向的是一个真实、正常运行的产品网站，而不是停放域名或占位页面。

权衡证据。 新项目并不一定价值低：成熟供应商推出全新软件包，或具备明确用途、真实源代码仓库、测试和许可证的项目，都可信，不应被视为价值方面的问题。真正值得担忧的是多个负面信号叠加：项目刚刚创建且尚未发布、缺乏采用情况或过往记录、没有源代码或许可证、没有真正使用 ADK 扩展点，以及页面所作的声明无法通过核查证实。如果证据不一，应给予贡献者善意推定，列明事实，并建议将是否关闭交由维护者酌情判断，而不是直接断定结果。保持表述中立、客观。

接受与拒绝

拒绝条件（关闭 PR）：

• 记录尚未发布、尚未合并或虚构的 API。我们不能记录尚不存在的功能。
• 重复已有页面（特定供应商的功能应放在供应商自己的文档中，现有 ADK 页面最多添加一行链接）。
• 代码与实际的 ADK 或供应商 API 不符。
• 链接失效或凭空捏造。
• CLA 未签署。
• 对开发者的价值或成熟度不足：全新仓库、尚未发布或当天发布的包、没有采用情况或过往记录，或没有源代码仓库或许可证。请用“开发者价值与成熟度”中的证据支持这一判断，并将其视为维护者的判断，而非自动裁决。
• 错误描述集成：声称与 ADK 集成，实际却使用忽略 ADK 扩展点的手动代码。
• 超出范围：没有 ADK 专属产物的通用“将 REST API 封装为函数工具”页面。ADK 文档不是 API 目录。
• 垃圾内容信号（与两个项目都没有关联、没有 ADK 专属功能、刷贡献图、使用率低且非常新的集成）。

**优质页面：**包含完整的四字段 frontmatter，其中有简短、以动词开头的描述和有效的现有标签；H1 正确，语言支持 div 为单行；采用正确的分类模板，且各章节具体、不零散；代码完整、可运行且经过手动测试，使用 gemini-flash-latest（或有效的 *-latest 别名）和规范导入（MCP 页面还应有 Python 和 TypeScript 选项卡）；内部链接使用相对路径，外部链接有效，图标资源有效；没有冗长的 AI 生成语言；提及“ADK”时用法正确，没有夸大或营销偏见；自动发现，无需编辑导航。

报告格式

生成按优先级分类的 Markdown 报告，每项发现都附上准确的 file:line 和上下文。使用带行号的读取、grep -n 或 diff 的块头，从正在审查的文件（本地页面，或通过 gh pr diff 获取的 PR 内容或抓取的副本）推导行号；绝不可估算（不要使用 ~）。 始终按顺序列出全部四个级别，并在没有发现的级别下写明 None，以明确说明没有 Critical 问题，而不是仅仅暗示。若某项确实可改可不改，应归入 🔵 小问题；🔴、🟠 和 🟡 仅用于合并前必须修复的问题。

• 🔴 严重：虚构或尚未发布的 API、无法运行的代码、失效或凭空捏造的链接、未签署的 CLA、目标目录错误、重复页面。
• 🟠 质量：结构或模板不匹配、缺少或命名错误的章节、夸大描述、供应商或 ADK API 详情错误。
• 🟡 风格：冗长的 AI 生成语言、不当使用“ADK”、以内联代码开头的句子、措辞、模型字符串、导入、描述长度、营销语气。
• 🔵 小问题：标签逗号间距、供应商自有页面上的 ADK 链接使用绝对路径还是相对路径、图片尺寸、标题大小写变体。

此处列出的每项发现都必须在输出 3 中至少对应一条带行号的评论（跨多个位置的发现，每个位置各写一条评论）；报告和评论必须涵盖相同事项。

列出各级别后，添加一段简短的开发者价值与成熟度说明：概述“研究开发者价值与成熟度”步骤中收集的证据（包的历史、采用情况和过往记录、仓库信号、是否真正使用 ADK 扩展），为每项信号附上来源链接，并以初步倾向结尾。如果研究结论认为价值或成熟度不足，也要将其记录为标记为“判断项”的 🔴 严重问题，以便与批准门槛保持一致。

完成优先级报告后，生成下方“审查决定与回复”中要求的输出。

审查决定与回复

在按优先级排列的报告之后，依次给出以下三项输出。它们对应 GitHub PR 审查中的审查正文、决定和行内评论。以下内容均为草稿：不要发布到 GitHub，不要运行 gh，也不要编辑文件，除非用户明确要求。

1. 顶层审查回复

撰写一段简短的审查正文（几句话），适合粘贴到 GitHub PR 审查摘要中。说明集成内容、总体评估、主要原因以及后续需要做什么。使用下文的“反馈语气”：简短、直接、委婉且可执行。如果决定是关闭 PR，请根据“拒绝回复模板”中的相应片段改写，并填入具体证据。

2. 决定

恰好选择一种决定，并引用上方报告中的具体发现作为依据。对照“接受与拒绝”标准，确保决定与标准一致。

• 批准：报告中没有 🔴、🟠 或 🟡 级别的发现（三者均为 None）；最多只剩 🔵 级别的小问题，且页面符合“优秀页面”的标准。
• 请求修改（常见情况）：页面可修复，但存在任何必须在合并前解决的 🔴/🟠/🟡 级别发现。列出必须修复的项目。
• 关闭 PR：触发了“接受与拒绝”中的拒绝条件（虚构/尚未发布的 API、重复页面、代码与实际 ADK 或供应商 API 不符、链接失效或虚构、CLA 未签署、错误描述集成、超出范围、价值/成熟度不足、垃圾信息迹象）。建议关闭 PR，并记录原因（如适用，链接到取代它的文档或 PR）。如果唯一的问题是开发者价值/成熟度不足（代码本身可用），请将其明确标为维护者的判断，并依据“开发者价值与成熟度”部分的说明提出建议，而不是将其作为自动的硬性阻止条件。

除非有充分且明确的理由说明审查确实无法作出上述三种决定之一，否则不要使用不作决定的普通“评论”结果。

3. 带行号定位的评论

提供一份可直接复制粘贴的 PR 行内评论列表，供维护者添加到差异中。涵盖报告中的所有发现，包括全部四个级别（🔴 🟠 🟡 🔵）。不要按严重程度筛选，也不要认为某些类别不值得评论：所有标记的问题，直到最后一个小问题，都必须有评论，确保维护者可以完整传达所有问题，不遗漏任何一项。

• 每条评论都应按原样粘贴到 GitHub 行内评论中：先写 file:line（或 file:start-end）定位符，并单独一行写级别表情符号，接着以引用块形式写一到两句建议，方便复制。例如：

  docs/integrations/weave.md:76 🟡 风格

  使用 model="gemini-flash-latest"，而不是固定版本的 model="gemini-2.5-flash"，以符合仓库惯例并避免 模型版本频繁变动。

• 使用与发现对应的精确 file:line，从被审查文件（本地页面或 PR 差异）中获取，切勿估算（不要使用 ~）。只有当某项发现确实无法对应到具体行时（例如缺少某个章节，或价值与成熟度判断），才退而使用页面级或 frontmatter 级评论，并明确说明这一点。

• 按照报告中的顺序，按级别对评论分组。

• 一项发现可以对应多条评论：如果某个问题涉及多个位置（例如 Python 和 TypeScript 示例中存在同一问题），则每个位置都要各写一条评论。

• 完成前进行核对：报告中的每项发现至少对应一条评论（因此评论数量应等于或多于发现数量）。如果有任何发现没有评论，就补上，不要提交不完整的列表。

这些都只是草稿；不要发布。

完成以上三项输出后，立即停止。除非用户明确要求，否则不要修改文件。

反馈语气（用于你撰写的 PR 评论）

• 简短直接。每个要点用两三句话说明。
• 外交得体，并提供可行的替代方案（例如：“你是否有仓库中的示例 Agent？如果没有，可以移除这个链接，让本页面作为示例。”）。
• 使用准确且可执行的术语（例如，对于 frontmatter 字段，应说“重命名目录标题”，而不是“重命名页面”）。关于操作方法，请参阅贡献指南，避免过度解释。

拒绝回复模板

当决定关闭 PR 时，请根据下方相应的模板调整顶层审查回复。这些模板体现了维护者一贯的语气；请保持简短，并将每个 [方括号] 替换为针对该 PR 经核实的具体证据。附上验收标准链接（https://github.com/google/adk-docs/blob/main/CONTRIBUTING.md#acceptance-criteria）。可能适用多个模板；请合并相关段落。

• 对开发者的价值：“感谢提交 PR！根据我们的[验收标准]审查后，我们目前无法接受此集成。对开发者的价值： 我们希望集成能为使用 ADK 构建 Agent 的开发者带来明确且有实际依据的价值，并会评估项目成熟度、活跃用户群体和过往记录等因素。[证据：例如，配套仓库创建于最近几周内，没有可供集成的已发布软件包，且项目尚未达到我们期望的社区采用度或过往记录。]”
• 完整性和可测试性：“感谢提交 PR。根据我们的[验收标准]审查后，我们目前无法接受此集成。完整性和可测试性： 文档中的代码示例必须可正常运行，供开发者使用。[证据：例如，引用的 ADK 导入项和类并不存在 / <pkg> 软件包尚未发布 / 示例从尚未合并的 PR 中导入内容。]”
• 可发布性：“感谢提交 PR。但我们无法接受此集成。根据我们的[验收标准]，我们不能发布可能规避技术保护措施、违反服务条款或未经授权访问服务的集成。[证据]”
• 超出范围：“感谢提交 PR！但此集成页面不属于 ADK 文档的范围。集成页面介绍的是扩展 ADK 或与 ADK 紧密集成的第三方功能（工具、插件、工具集、MCP 服务或可观测性平台）。[证据：例如，此页面定义了调用 REST API 的普通函数，属于通用的‘将 REST API 封装为函数工具’模式，该模式已有文档说明，且适用于任何 API。ADK 文档不是 API 目录。]”
• 重复 / 已被取代：“感谢提交 PR。此内容已被 #<N> 取代 / 与现有的 [<page>] 重复。[可选：供应商特有的功能应放在供应商自己的文档中，现有 ADK 页面最多添加一行链接。]”