api-reference-audit

ADK API 参考文档审查器（api-ref-audit）

此技能会审查 adk-docs 仓库中所有语言 SDK 的 API 参考文档，并报告过时内容。这是一项报告与指导技能：它会检测偏差，针对不同发布对象推荐正确的发布流程，并且仅在用户明确要求时才生成可执行计划。默认情况下，它不会编辑文件、运行生成器或创建 PR。

审查涵盖以下三类偏差：

1. docs/api-reference/ 下的生成式 API 参考文档未能跟上最新的 SDK 版本。
2. 正文和示例中的硬编码版本字符串（依赖项坐标、pom.xml 版本），这些内容必须随每次 Java/Kotlin 版本发布而更新。
3. 代码示例偏差（仅作轻量标记）：引用固定版本或明显已弃用 API 的示例。本技能不负责深入验证示例。

重要

下方的映射仅供参考，并非权威依据。文件布局、脚本路径和团队流程都可能变化。每一步都要确认路径或标记是否存在；如果查找失败，应重新推导，而不是盲目相信表格。

版本对照表（仓库内版本与上游实际版本）

每个表面都代表本仓库发布的一种 API 参考文档：Python API、Python CLI、Python REST API、Python Agent Config、TypeScript、Go、Java 和 Kotlin。

对于每种表面，请从列出的文件中读取仓库内版本，然后与上游最新版本及软件包注册表进行比较。

表面	仓库内版本标记	上游仓库	软件包注册表
Python API	docs/api-reference/python/_static/documentation_options.js（VERSION:）	google/adk-python	PyPI google-adk
Python CLI	docs/api-reference/cli/_static/documentation_options.js（VERSION:）和 docs/api-reference/cli/index.html（"ADK X.Y.Z"）	google/adk-python	PyPI google-adk
Python REST API	docs/api-reference/rest/openapi.json（info.version）	google/adk-python	PyPI google-adk
Python Agent Config	无版本标记；将 agentconfig/index.html 中的类型集合与上游 AgentConfig.json 进行差异比较	google/adk-python（与 Python API/CLI/REST 版本相同）	不适用
TypeScript	docs/api-reference/typescript/variables/version.html（version 常量）；与 docs/api-reference/typescript/index.html（<title> 中的 "... - vX.Y.Z"）交叉核对	google/adk-js（单体仓库；见注释）	npm @google/adk（权威来源）
Go	外部托管于 pkg.go.dev；验证 docs/api-reference/index.md 中的链接	google/adk-go	pkg.go.dev
Java	docs/api-reference/java/index.html（<title> 中的 "Maven Parent POM X.Y.Z API"）	google/adk-java（权威来源）	Maven Central com.google.adk:google-adk（更新滞后；仅供交叉核对）
Kotlin	docs/api-reference/kotlin/index.html（标题附近的版本字符串）	google/adk-kotlin（权威来源）	Maven Central com.google.adk:google-adk-kotlin-core（更新滞后；仅供交叉核对）

注释：

• Python API、CLI 和 REST 都跟随同一个 adk-python 版本，因此通常会同步更新。如果它们版本不一致，请标记出来。
• Python Agent Config 没有版本字段。请从目标标签对应的上游 AgentConfig.json 中解析 $defs 对象的键（以及顶层的 oneOf 变体），例如 jq '."$defs" | keys'。不要 用子字符串搜索 *Config：这会混淆属性名称（camelCase，例如 imageConfig）和类型名称（PascalCase，例如 ImageConfig），导致 误报差异。将每个 $defs 键作为完整单词在 agentconfig/index.html 中逐一核对； 如果上游存在某个键，但页面中缺少该键（反之亦然），即为差异。
• TypeScript：使用 npm @google/adk 的 dist-tags.latest 作为权威 版本。adk-js 是一个单体仓库，使用带软件包前缀的标签（例如 main-v1.4.0、 integrations-v1.4.0），因此 gh ... releases/latest 可能返回属于 其他软件包而非 @google/adk 的版本。本仓库中的 version 常量与 npm 发布的 @google/adk 软件包版本一致，并随其一同发布，因此直接比较两者即可：只要版本不同， 就表示文档落后了。生成脚本会克隆 adk-v<version> 标签（核心 @google/adk 软件包标签）。
• Go 文档不会在本仓库中构建。请确认版本，并检查 index.md 中的链接是否指向正确的主版本 （例如 v2.x 和 v1.x）。Go 版本也固定在 examples/go/go.mod / go.sum 中， 且正文中会出现 /adk/v2 导入路径（例如 docs/events/index.md、docs/2.0/）， 因此也请检查这些位置。

硬编码的版本引用

这些固定版本的字符串是有意保留且有用的：它们向开发者展示了应使用的确切依赖版本。审计的任务是确保这些版本保持最新，而不是将其移除。它们会随着每次 Java/Kotlin 版本发布而过时，并在单独的 PR 中更新（参见流程图）。通过 grep 查找当前引用；不要只依赖文件列表，因为随着时间推移可能会出现新页面。

• grep 目标：

  • 在 docs/**/*.md 中查找 com.google.adk:google-adk 和 com.google.adk:google-adk-kotlin
  • 在 docs/**/*.md 和 examples/java/**/pom.xml 中查找 <google-adk.version>
  • 在集成页面中查找独立的 google-adk>=X.Y.Z 版本固定项（仅报告；这些是最低版本固定项，并非文档版本更新）

• 已知包含这些内容的文件（请核实，不要假定列表完整）：

  • docs/get-started/installation.md
  • docs/get-started/java.md
  • docs/get-started/kotlin.md
  • docs/live/get-started/streaming-java.md
  • docs/deploy/cloud-run.md
  • docs/agents/models/litert-lm.md
  • docs/integrations/firestore-session-service.md
  • examples/java/**/pom.xml

• 切勿标记或更新语言支持标签。 language-support-tag span 中的版本（例如 <span class="lst-python">Python v1.32.0</span>）表示某项功能首次引入的版本，而非最新发布版本。请勿更改它们；更新这些版本会错误地表示功能的可用时间。

各发布面的流程图（负责人、工具、步骤）

将每个条目视为起始提示。提出建议前，请确认脚本仍然存在，并检查最近一次匹配的版本更新 PR，以确认当前流程。

• Python API：可自行处理。运行 bash tools/python-api-docs/generate.sh <version>，然后创建 PR（该脚本通过 Sphinx 注入 Google Analytics 标签）。
• Python CLI：可自行处理。运行 bash tools/python-cli-docs/generate.sh <version>，然后创建 PR。GA 标签通过脚本中的 Sphinx 布局模板注入。
• Python REST API：可自行处理。运行 bash tools/python-rest-api-docs/generate.sh <version>，然后创建 PR。GA 标签已嵌入生成的 index.html。
• Python Agent 配置：根据 adk-python schema 使用 json-schema-for-humans 重新生成；目前尚无 tools/ 生成脚本，因此请按手动更新处理。
• TypeScript：可自行处理，只需一个 PR。运行 bash tools/typescript-api-docs/generate.sh <version>（其中 <version> 是审计中确定的 npm @google/adk 版本），然后创建 PR。该脚本会克隆 adk-js 的 adk-v<version> 标签，通过 TypeDoc 的 --includeVersion 将版本添加到页面标题，并使用 awk 后处理将 Google Analytics 标签注入每个 HTML 文件。
• Java：可自行处理。运行 bash tools/java-api-docs/generate.sh <version>，重新生成 docs/api-reference/java/ 下的 Javadoc 资源（GA 标签会自动注入每个 HTML 文件），并更新硬编码的依赖版本和 pom.xml 值。这些工作可以拆分成两个 PR（Javadoc 资源的 PR 标题为 chore: update ADK Java doc to version <X>，依赖版本固定项的 PR 标题为 Update ADK Java dependency versions to <X>），也可以合并在一起。
• Kotlin：可自行处理，只需一个 PR。运行 bash tools/kotlin-api-docs/generate.sh <version>，然后创建一个 PR，将生成的资源和硬编码的 Kotlin 引用（installation.md、get-started/kotlin.md、litert-lm.md）一并提交。GA 标签会自动注入每个 HTML 文件。

验证流程

• 建议使用脚本前，确认每个引用的脚本都存在于 tools/ 下。
• 检查最近一次匹配的版本更新，以确认实际的当前流程及其涉及的文件，例如：
  • gh pr list --repo google/adk-docs --state merged --search "Kotlin"
  • gh pr list --repo google/adk-docs --state merged --search "CLI reference"
  • gh pr list --repo google/adk-docs --state merged --search "Java"
  • gh pr list --repo google/adk-docs --state merged --search "TypeScript"

审计工作流

步骤 1：读取仓库内版本

针对版本映射表中的每个界面，读取标记文件并记录当前版本。使用 grep/Read 查找 JS 和 HTML 标记，并从 rest/openapi.json 中解析 info.version。如果标记路径无法解析，请重新推导路径（搜索生成的输出），并记录这一差异。

步骤 2：获取上游发布版本和注册表版本

对于每个 SDK，获取最新发布版本和最新已发布的软件包版本：

• GitHub 最新发布版本和标签：
  • gh api repos/google/adk-python/releases/latest --jq .tag_name
  • 对 adk-go、adk-kotlin、adk-java 重复此操作。
  • 对于 adk-js，不要使用 releases/latest（monorepo 标签会为软件包添加前缀，例如 main-v1.4.0）；应以 npm @google/adk 为准。
• 软件包注册表：
  • PyPI：获取 https://pypi.org/pypi/google-adk/json 并读取 info.version。
  • npm：获取 https://registry.npmjs.org/@google/adk 并读取 dist-tags.latest。
  • Maven Central：查询 https://search.maven.org/solrsearch/select?q=g:com.google.adk+AND+a:google-adk&rows=1&wt=json 并读取 latestVersion（Kotlin 使用 a:google-adk-kotlin-core）。
• 对于 Java 和 Kotlin，以 GitHub 发布版本/标签为准。 Maven Central 搜索索引经常落后于实际发布版本（它返回的版本曾低于本仓库中已发布的版本）。将注册表结果仅用作交叉核对；如果与 GitHub 标签不一致，请以标签为准，并注明索引滞后。
• 如果 GitHub 标签与注册表版本不一致，请注明两者（某个版本可能已打标签但尚未发布，也可能已发布但尚未打标签）。

步骤 3：对每个界面分类

将每个界面标记为以下状态之一：

• 已更新：仓库内版本与最新上游发布版本相同。
• 落后：仓库内版本早于最新发布版本（报告差距，例如 2.3.0 -> 2.4.1）。
• 未知 / 手动检查：上游查询失败，或界面没有可自动执行的检查。Agent Config 不属于“未知”；应通过类型集合差异进行分类（如果上游新增或移除了类型，则标记为落后）。

指出常见情况：Python API、CLI 和 REST 应共用同一个 adk-python 版本，但实际并非如此。

对于 Agent Config，运行版本映射表“Notes”中所述的类型集合差异检查，以确定其状态是已更新还是落后。

步骤 4：检查硬编码的版本引用

对“硬编码的版本引用”中的目标进行 grep，并将每个固定版本与最新 Java 和 Kotlin 发布版本进行比较。列出所有需要更新的文件和行。将最低版本固定项（google-adk>=X.Y.Z）分开处理；只有当其引用的版本高于已发布版本或明显过时时，才标记出来。

步骤 5：标记示例代码的轻微偏差

快速扫描（不进行深入审计）：记录硬编码模型版本或软件包版本、明显已弃用的导入，或已被新发布版本的变更日志取代的用法。将这些作为提示报告，并建议另行进行专门的示例审计以作深入核实。此处不要尝试重写示例。

步骤 6：验证 Go 链接

确认 docs/api-reference/index.md 中的链接指向 pkg.go.dev 上正确的 Go 主版本，并确认其中涵盖最新的 adk-go 发布版本。此外，还要检查 examples/go/go.mod / go.sum 中固定的版本，以及正文中的 /adk/v2 导入路径（例如 docs/events/index.md、docs/2.0/）。

报告格式

生成一份 Markdown 报告。先列出状态表，再按优先级列出发现。

状态表（每个表面一行）：

表面	仓库内	上游最新版本	状态	建议操作

在表格后按优先级列出发现。仅列出需要采取行动的项目；任何地方都不要写“无需操作”或“已确认正确”，包括其他内容需要采取行动的条目中。如果某个表面无需处理，其表格行已说明这一点。

• 🔴 已过时 / 已损坏：某个表面落后多个版本、API 参考链接损坏或不正确，或者版本标记彼此不一致（例如 Python API、CLI、REST 使用不同版本）。
• 🟠 硬编码版本过时：列出需要升级的依赖坐标和 pom.xml 值的 file:line，并注明旧版本 -> 新版本。
• 🟡 示例漂移提示：列出可能需要更新的示例；建议执行深入示例审查。

对于每个过时的表面，注明流程图中的建议流程（自助脚本、等待团队处理或手动处理），以便用户了解如何继续。

报告结束后，立即停止。除非用户明确要求，否则不要修改文件、运行生成器或创建 PR。

可执行计划（仅在用户要求时）

用户要求继续处理时，请针对每个过时的表面给出具体后续操作：

• 如果可以自助处理，给出要运行的确切命令，例如：
  • bash tools/python-api-docs/generate.sh <new-version>
  • bash tools/python-cli-docs/generate.sh <new-version>
  • bash tools/python-rest-api-docs/generate.sh <new-version>
  • bash tools/java-api-docs/generate.sh <new-version>
  • bash tools/kotlin-api-docs/generate.sh <new-version>
  • bash tools/typescript-api-docs/generate.sh <new-version>
• 对于硬编码版本，列出精确的 file:line 修改（旧版本 -> 新版本），包括 examples/java/**/pom.xml。
• 指明哪些表面需要一并更新（Python API、CLI 和 REST 共用一个 adk-python 版本），因此应作为单独的 PR 提交，但在同一轮中完成升级。
• 针对每个过时的表面提供 PR 描述，并遵循仓库惯例：
  • 用简短的项目符号概述变更内容
  • Rendered page: <预览链接，如适用>
  • 上游发布链接和版本
• 最后说明用户如何继续：自行运行命令、等待所属团队处理，或让 Agent 执行计划。

PR 标题惯例

遵循既有标题格式，以便历史记录易于搜索：

• Python API：Update API reference docs for ADK Python <X.Y.Z>
• Python CLI：Update CLI reference docs for ADK Python <X.Y.Z>
• Python REST API：Update REST API reference docs for ADK Python <X.Y.Z>
• TypeScript：Update API reference docs for ADK TypeScript <X.Y.Z>
• Java API：chore: update ADK Java doc to version <X.Y.Z>
• Java 依赖升级：Update ADK Java dependency versions to <X.Y.Z>
• Kotlin：Update ADK Kotlin to <X.Y.Z>

需要纳入的风格规则

• 版本必须精确写为 old -> new；绝不猜测未从标记中读取或未从上游获取的版本。
• 不要编造链接；仅使用读到的标记和已获取的发布信息。
• 不要使用长破折号，也不要写冗长的 AI 风格内容。
• 权威源代码仓库列于 docs/community/contributing-guide.md。