adk-verify-snippets

验证 Markdown 代码片段

从 Markdown 文件中提取每个 ```python 代码块，通过随附的 run.py 测试工具在各自的子进程中运行，并生成一份报告，涵盖每个代码片段的加载状态、运行状态和行覆盖率。

只读约定

验证文档绝不能更改文档。不得在仓库中创建、修改或删除任何文件——包括正在验证的 Markdown 文件、其中的代码块以及此 SKILL.md。报告失败项；不要修复，也不要提供补丁。

脚本只执行以下两项写入操作：在仓库外的系统临时目录中创建临时 .py 文件（退出时删除），以及在源 Markdown 文件旁写入报告。

先决条件

1. ADK 开发环境——在仓库根目录下、激活 uv 虚拟环境后运行（参见 adk-setup 技能）。

2. coverage，可选。它不是项目声明的依赖项，因此需要显式安装；如果未安装，“Coverage”列会显示 —。

   uv pip install coverage
   

3. Gemini API 密钥，仅当代码片段会构建 Agent、App 或 Workflow 时需要——这些代码片段会调用在线 API 执行。

   export GEMINI_API_KEY="{your_key}"
   # or
   export GOOGLE_API_KEY="{your_key}"
   

   如果两者都已设置，测试工具会移除 GOOGLE_API_KEY，因此以 GEMINI_API_KEY 为准。

用法

uv run --no-sync python .agents/skills/adk-verify-snippets/scripts/verify_md.py {path_to_markdown_file}

脚本会输出每个代码片段的运行进度，然后在源文件旁写入报告，并打印报告的完整路径。

报告文件名由源文件名（不含扩展名）转换为小写，并移除除 [a-z0-9_] 以外的所有字符，再加上 _REPORT.md 构成。因此，Workflow-Guide.md 会生成 workflowguide_REPORT.md，而不是 Workflow-Guide_REPORT.md——请使用脚本打印的路径，不要自行推算。

报告包含一张执行摘要表，每个代码片段占一行；随后为每个代码片段提供详细部分，其中包括代码块、执行日志（标准输出以及标准错误/回溯）和覆盖率输出。

每个代码片段的分类方式

可运行——包含模块级 ADK 组件

如果代码片段将 Workflow、Agent 或 App 赋值给模块级变量，测试工具会调用 Gemini API 执行该代码片段。

• 变量名无关紧要；测试工具会扫描 vars(module)。
• 优先级依次为 Workflow、根 Agent、App。如果代码片段中任何位置存在 Workflow，则优先于其中的任何 Agent。
• 根 Agent 是未出现在其他 Agent 的 sub_agents 中的第一个 Agent，因此无论 Agent 的定义顺序如何，多 Agent 代码片段都能正确解析。
• App 必须使用 root_agent 构建，否则运行会失败。
• 发送的提示词为 "Test input topic"。如需覆盖此值，请在代码片段中定义一个模块级的 test_input 字符串。

仅加载——不包含 ADK 组件

测试工具会确认代码片段可以编译并导入，不会调用 API。 报告会显示 ➖ NO ADK COMPONENT。

已跳过——标注为 ignore

在 `` 这一行单独放置，并紧接在开头的 ```python 围栏之前，即可排除代码块。适用于伪代码、示例片段以及需要外部设置的代码片段。报告会显示 ⏭️ SKIPPED。

```python
# pseudo-code — not runnable as-is
my_agent = Agent(model="gemini-ultra-hypothetical", ...)
```

导致正确代码片段被报告为损坏的限制

使用 `` 标注，而不是编辑文档来绕过以下限制。

• 代码片段之间没有共享状态。 每个代码片段都会在全新的 子进程中运行，因此依赖前一个代码块中的导入项或变量的代码片段会因 NameError 或 ImportError 而失败。
• 每个代码片段的超时时间为 120 秒，超时后进程会被终止， 该代码片段会被报告为运行失败。
• 标注位置。 标注适用于下一个 ```python 代码围栏。两者之间可以有空行；如果中间有任何说明文字行或标题，标注就会失效。
• 裸 ``` 会关闭代码块。 解析器会在遇到第一个不带语言标签的围栏时关闭 Python 代码块，因此在代码片段中作为内容使用的裸围栏会截断代码片段。带标签的围栏（例如 ```bash）会作为字面内容保留，不会造成问题。
• 模块级 asyncio.run() 会与运行工具自身的事件循环冲突，并导致代码片段被报告为运行失败。代码片段应将顶层异步调用放在 if __name__ == "__main__": 后面。

向用户反馈

阅读生成的报告，并按原样复制其中的 Executive Summary 表格——六列保持不变，顺序不变，不得重命名或删除任何列： Snippet | Preceding Heading | Load Phase | Run Phase | Coverage | Details。 展示该表格后即停止。