adk-samples 提交指南基于 Recipe Checklist 的 contrib 配方Recipe全流程规范化【免费下载链接】adk-samplesA collection of sample agents built with Agent Development Kit (ADK)项目地址: https://gitcode.com/GitHub_Trending/ad/adk-samples本篇技术指南以仓库 docs/recipe-checklist.md 为核心骨架系统讲解在 adk-samples 项目中向contrib/目录提交一个合格 ADK 示例配方Recipe所需的一切从 AI 技能一键准备、通用与语言专项检查项到 PR 前的校验、格式化、测试命令再到失败排查与自动化评审机制。读完你将掌握一套可复现的提交流程并理解仓库内 tools/validate.py 等校验工具背后为什么这样检查的底层逻辑。背景什么是 recipe它放在哪里adk-samples 是一个经过筛选的、可直接运行的 ADKAgent Development Kit示例集合。仓库 docs/README.md 将recipe定义为一个聚焦的、自包含的 agent 示例位于contrib/下用于演示某一种具体的 ADK 模式。它的读者有两类人寻找起点或可借鉴模式的 ADK 开发者以及代替用户阅读代码的 AI 编码助手。因此一个清晰的目录结构和一份聚焦的README.md对两类读者都至关重要。一个好的 recipe 必须满足三个条件有明确意图、能解决一个具体问题、有新的东西可以教给别人。如果无法用一句话说清这个 recipe 演示了什么、谁受益就说明它还不够聚焦单纯复制已有示例而没有新增洞察的 recipe 可能不会被接受。每个 recipe 都位于root/lang/name结构下详见 docs/recipe-handbook/anatomy.mdcore/由 agents-cli 团队维护或contrib/社区贡献。贡献者提交的新 recipe 一律进入contrib/。core/下的 recipe 额外要求一个为编码 agent 撰写的AGENTS.md意图、关键文件、复用建议contrib/不强制要求。第一步提议一个新 recipe如果是全新的 recipe不能直接动手写代码而要先在 GitHub 上使用Propose a New Recipe模板开启一个 issue等待批准后再将其加入contrib/并打开 PR。如果是更新已有 recipe则可以跳过这一步直接对照检查清单执行。第二步用 AI 技能一键准备最快路径如果本地配置了 AI 编码助手例如 CloudCode最快捷的方式是执行prepare-python-recipe技能——它按正确顺序自动运行其余所有技能。若没有 AI 助手可直接跳到PR 前命令一节手动执行。下表是 docs/recipe-checklist.md 中给出的技能清单各技能的深入细节见 docs/recipe-handbook/skills-catalog.md技能作用示例提示词prepare-python-recipe按顺序运行下面所有技能是到达 PR-ready 状态的最快路径prepare the python recipe contrib/python/my-recipegenerate-manifest根据 recipe 文件生成一份合法的manifest.yamlgenerate manifest for contrib/python/my-recipealign-recipe-pyproject修正pyproject.toml以符合仓库约定align pyproject.toml for contrib/python/my-recipeextract-python-environment-variables从 Python 源码提取环境变量写入.env.example并在需要处补上load_dotenv()extract env vars for contrib/python/my-recipegenerate-python-runnability-test生成tests/test_runnability.py冒烟测试generate runnability test for contrib/python/my-recipemake-python-recipe-deployable添加服务化文件使 recipe 可作为容器运行。可选不随prepare-python-recipe执行make contrib/python/my-recipe deployable理解prepare-python-recipe的七阶段流水线从 docs/recipe-handbook/skills-catalog.md 的说明看prepare-python-recipe内部按序执行七个阶段generate-manifest— 生成 manifestextract-python-environment-variables— 提取环境变量align-recipe-pyproject— 对齐 pyproject 约定ruff format与ruff check— 格式化与 lintuv lock— 更新锁文件generate-python-runnability-test— 生成冒烟测试py_compile验证生成的测试文件。它是交互式的会在固定的决策点或需要你拍板时暂停同时可安全重复执行不会覆盖你手写的.env.example或 Python 代码。更新已有 recipe 时对它执行prepare-python-recipe即可自动套用最新要求。第三步通用检查清单所有语言适用以下为每个 recipe 无论语言都必须满足的硬性条件详见 docs/recipe-checklist.md 与 docs/recipe-handbook/anatomy.md明确且唯一的目的解决一个具体问题并带来新的可教内容。正确的位置位于contrib/lang/name。命名合规文件夹名 ≤ 30 字符仅允许小写字母与连字符正则^[a-z][a-z-]*$。从源码 tools/validate_structure.py 可见该正则被硬编码在_FOLDER_NAME_RE中违反时校验器还会用_suggest_folder_name给出一个近似合法名供git mv参考——命名违规会被单独报告且与长度违规分开计保证一次 CI 运行能看到全部问题。体积上限contrib/下最多 70 个文件 / 2 MB。仅用于文档的截图与示意图必须转成 WebP 格式如cwebp -q 85。值得注意的是uv.lock、__pycache__/、.venv/、node_modules/、target/、build/、vendor/、go.sum等生成物与缓存不计入统计对应各类语言的排除项见 docs/recipe-handbook/anatomy.md。manifest.yaml合法包含真实的ownership.team与ownership.poc可用generate-manifest技能生成。README.md达标≥ 100 词、含 setup 小节与带代码块的 run 小节——这些由 CI 强制检查。manifest.yamlrecipe 的元数据核心anatomy.md 给出了必填字段与常用可选字段字段取值typestandalone可运行或module可导入的子 agentstatusactive或inactivelanguagepython、java、go、kotlin、typescriptdescription描述文字至少 10 个字符ownership.team团队名ownership.poc负责人的 GitHub 用户 ID其中两个字段不只是元数据CI 会据此采取行动ownership.poc是 recipe 需要维护时联系的人status追踪 recipe 的健康状态——默认active若问题长期未解决会被置为inactive再进一步则被弃用并从仓库移除参见 docs/recipe-handbook/troubleshooting.md 中Recipe is marked inactive一节。常用可选字段包括deployable是否支持一键部署默认false、licenseSPDX 标识、ownership.contributors其他 GitHub 用户 ID、tags、architecture.agentsingle/multi、architecture.stateful、architecture.datasourceshardcoded/local/external、dependencies.libraries、dependencies.services。枚举字段的完整合法值集合以 .github/schemas/manifest-schema.json 为准。一个最小示例type: standalone status: active language: python description: A retrieval-augmented search agent over public docs. ownership: team: your-team-name poc: your-github-username从 tools/validate_manifest.py 的实现可以深入理解两点占位符单独检测ownership.team与ownership.poc的脚手架占位文本如TODO: Replace with your team name能通过 schema 但会被单独报为ownership-placeholder以TODO开头的description同样会被捕获因为它的长度已满足 schema 的 minLength。诊断信息可执行jsonschema 的原始 JSONPath 错误会被翻译成哪个 YAML 字段、阈值是多少、该怎么改三条信息例如字段缺失时会直接列出缺失字段及其 schema 描述。README.md内容的强制要求每个 recipe 必须有一份README.md至少要覆盖recipe 做什么一段话、Setup前置条件、凭据、环境变量、Run启动 agent 的确切命令。CI 强制以下内容检查不能含TODO:占位符至少 100 词作为描述的代理指标必须有一个 setup 小节标题需包含Setup、Prerequisites、Installation、Requirements、Configuration、Getting Started、Before You Begin、Environment之一必须有一个 run 小节标题需包含Run、Running、Usage、Quickstart、Start、Deploy、Launch、How to Run之一且下方至少有一个围栏代码块。第四步语言专项检查已弃用模型提醒gemini-2.0-flash与gemini-2.5-flash不再被接受请使用gemini-3.5-flash。Python 专项Python recipe 的检查项如下详见 docs/recipe-handbook/languages/python.mdpyproject.toml对齐仓库约定AI 技能align-recipe-pyprojectuv.lock同步——在 recipe 根目录执行uv lock.env.example声明 recipe 读取的每一个环境变量AI 技能extract-python-environment-variables在包__init__.py而非agent.py中调用load_dotenv()模型名从环境变量读取不得硬编码在源码中存在tests/test_runnability.pyAI 技能generate-python-runnability-test。Python recipe 的标准目录布局contrib/python/my-recipe/ pyproject.toml # 项目说明 依赖 uv.lock # 固定依赖版本 .env.example # recipe 读取的环境变量 manifest.yaml # recipe 元数据 README.md # 描述、setup、run app/ __init__.py # 先运行 load_dotenv()再导入 agent agent.py # agent 代码 tests/ test_runnability.py # 导入冒烟测试最佳实践Python 包名使用app。虽然并非强制但仓库根部的 Ruff/isort 配置假设了它known-first-party [app]其他命名会产生错误的 import 排序。Python 最低版本要求为3.11。可直接复制的起始模板pyproject.toml最小模板[project] name my-recipe version 0.1.0 requires-python 3.11 dependencies [ google-adk, python-dotenv1.0.0, ] [build-system] requires [hatchling] build-backend hatchling.build其中[project].name由 recipe 所在位置推导core/language/recipe或contrib/language/recipe用文件夹名如deep-search、financial-advisor而skills/vertical/solution用vertical-solution如retail-product-search因为仅凭文件夹名在多个 vertical 之间并不唯一。注意不要在 recipe 的pyproject.toml中添加[tool.ruff]或本地ruff.toml——Ruff 配置集中在仓库根部。.env.example模板GOOGLE_CLOUD_PROJECTyour-project-id GOOGLE_CLOUD_LOCATIONus-central1 MODEL_NAMEgemini-3.5-flashapp/__init__.py模板——关键是load_dotenv()必须在__init__.py而非agent.py中调用因为包导入时__init__.py先执行.env会在任何 agent 导入期环境变量读取之前加载# noqa: E402告诉 Ruff 这个延迟导入是有意为之from dotenv import load_dotenv load_dotenv() from . import agent # noqa: E402tests/test_runnability.py模板——这是最低要求核心思路是导入app.agent并断言root_agent不为None必要时可根据 recipe 情况调整或扩展Runnability tests for the recipe. def test_agent_runnability() - None: Verify agent.py imports and defines root_agent. import app.agent assert app.agent.root_agent is not None集成测试与 CI 的排除规则访问真实外部资源Gemini、BigQuery、第三方 API的测试属于集成测试CI 出于速度和凭据原因默认跳过需在开 PR 前本地运行。被 CI 排除的两类模式模式排除内容tests/integration/该目录下的所有内容**/test_integration.py任意深度下同名文件Java / Go / TypeScript / Kotlin 专项这些语言的语言专项指南尚在编写中写代码前应先阅读对应页面Go · Java · TypeScript · Kotlin。不过第 3 节的结构性检查已全部适用——运行uv run validate $RECIPE_PATH并对照 docs/recipe-handbook/anatomy.md 检查布局规则即可。第五步开 PR 前的命令与 CI 完全一致本节所有命令都在仓库根目录执行与 CI 运行的内容一致。它们全部使用$RECIPE_PATH变量请先设置它。设置 recipe 路径在运行下面的任何命令之前先执行一次export RECIPE_PATHcontrib/python/my-recipe将my-recipe替换为你的 recipe 文件夹名。一键粘贴先粘贴这一段一个代码块、一次粘贴即可完成全部流程前提是已设置$RECIPE_PATH# 从仓库根目录 uv run validate $RECIPE_PATH # 校验 manifest 与结构 uv run ruff format $RECIPE_PATH # 格式化 recipe 代码 uv run ruff check --fix $RECIPE_PATH # 修复 lint 错误 # 从 recipe 根目录 cd $RECIPE_PATH uv lock # 更新锁文件 uv run pytest # 运行测试结构性检查validate 工具详解uv run validate recipe-path会对 recipe 运行全部结构性校验器并逐项报告 PASS / FAIL。从 tools/validate.py 的源码可以看到它支持的子命令manifest、structure、readme外加placement回答recipe 是否放对了文件夹——单个 recipe 级校验器看不到放错位置的 recipe因为收集器根本不会采集到它所以 CI 将其作为独立任务注册进来是为了让贡献者在本地就能发现这类问题。uv run validate manifest $RECIPE_PATH uv run validate structure $RECIPE_PATH uv run validate readme $RECIPE_PATH各子命令的职责validate manifest—— 对照 .github/schemas/manifest-schema.json 校验manifest.yaml并验证ownership.team/ownership.poc不是占位符validate structure—— 检查文件夹名、体积、必需文件与布局规则来自 .github/policy.yml 的required_files、required_dirs、recipe_size_limits、recipe_naming等段落具体见 tools/validate_structure.pyvalidate readme—— 检查 README.md 是否含 setup 小节、run 小节、代码块以及最低词数。从 tools/validate.py 的实现还能看到几个值得了解的细节退出码语义0全部通过、1存在违规、还有单独的 CI 故障码——校验器自身崩溃CI fault的优先级高于普通违规因为把故障折叠成违规会让工作流对贡献者说你的 recipe 无效而实际是校验器自身出了 bug空 scope 不会静默通过uv run validate structure skills若匹配不到任何 recipe会给出诊断而非报告0 个 recipe 通过避免 typo 的 scope 得到虚假的绿色结果语言检测只看manifest.language路径约定如core/python/foo/对结构校验器没有任何语义必需文件规则是always每个 recipe 都要README.mdby_rootcore/要AGENTS.md、skills/要SKILL.md/EVAL.yaml/scripts/by_languagePython 要pyproject.toml、uv.lock、.env.example、tests/test_runnability.py的三方并集且每条规则都带来源标注回答为什么我的 recipe 必须要有这个文件。格式化与 lint仅 Pythonuv run ruff format $RECIPE_PATH uv run ruff check $RECIPE_PATHRuff 规则集中在仓库根部行宽 80、双引号recipe 内不允许存在本地 Ruff 配置否则会覆盖根配置。测试仅 Python与 CI 一致排除集成测试cd $RECIPE_PATH uv run pytest --ignoretests/integration --ignore-glob**/test_integration.py集成测试的本地运行CI 默认排除集成测试。关于排除模式以及如何在开 PR 前本地运行参见 docs/recipe-handbook/languages/python.md 的 Integration tests 一节。本地运行方式cd contrib/python/my-recipe uv run pytest tests/integration # 仅集成测试 uv run pytest # 完整测试套件第六步失败时怎么办CI 失败时遵循以下原则详见 docs/recipe-handbook/troubleshooting.mdCI 在 PR 上失败 → 查阅 troubleshooting它把错误直接映射到修复方案每个小节末尾都有确认修复命令先修validate-recipe-structure的失败——结构性错误会掩盖下游 Python 专项检查的问题部分失败存在级联效应一份过期的uv.lock会同时导致python-dependency-policy与python-tests失败先修根因再推送CI 会在每次推送到 PR 分支时自动重跑无需手动触发想了解完整故事 → recipe-handbook 总览。常见的典型问题与修复节选自 troubleshooting症状修复ownership.team仍是占位符设置真实的团队名与 GitHub 用户 ID文件夹超过 2 MB / 70 文件删除不应提交的生成物、超过 1 MB 的数据文件移入存储桶并在 README 中链接、截图转 WebPcwebp -q 85uv.lock与pyproject.toml不同步uv lock --project recipe-pathuv.lock含 git/VCS 或本地路径依赖改依赖 PyPI 上已发布的包后重新锁定README 少于 100 词补充真实描述、setup 与 run 步骤目标 200–300 词pyproject.toml含[tool.ruff]或本地ruff.toml删除Ruff 配置集中在仓库根部缺少必需文件大多有生成器manifest.yaml→generate-manifest、.env.example→extract-python-environment-variables、tests/test_runnability.py→generate-python-runnability-test、uv.lock→uv lock --project值得单独提示的两点一是git 无法提交空目录——若必需目录看起来存在却被报缺失多半是本地有目录但 git 从未提交它此时应提交一个占位文件touch recipe-path/scripts/.gitkeep git add recipe-path/scripts/.gitkeep二是已退役目录——recipe 曾位于仓库根部的language/agents/recipe这些根已关闭改动其中的 recipe 需整体迁移到contrib/language/recipe并补齐新要求。另外status: inactive的 recipe 会收到[NOTICE]警告但不会阻止 PR。修复后需在同一个 PR 中手动将status改回active——没有任何机制会自动重置该字段。同样属于非阻塞提示的还有硬编码模型名应替换为os.getenv(MODEL_NAME)、GOOGLE_CLOUD_PROJECT/GOOGLE_CLOUD_LOCATION/MODEL_NAME缺失于.env.example等。第七步自动化评审机制打开 PR 后包括 fork 的 PR且每次 push 都会触发会有三位 AI 评审者——正确性correctness、安全性security、可维护性maintainability——自动运行。它们只对新增代码行评论且仅报告 critical 或 high 级别问题评审意见是建议性的最终仍需维护者人工评审和批准。维护者可通过在 PR 上评论ai-review可附带关注重点手动重跑。超过 300 个变更文件的 PR 会被跳过评审因为 GitHub 无法提供如此大的 diff。关于评审节奏的补充来自 docs/recipe-handbook/troubleshooting.md每轮评审只读取自上一轮以来的变化因此修复评论的 push 几乎不会再产生新发现每轮允许的评论数逐轮递减且有硬性上限第二轮之后仅运行 Correctness 与 Security 两条流水线。每次自动化评审的最后一行会告诉你当前进度如第几轮、本 PR 已用多少条评论额度、本轮上限。House Rules 流水线是例外——它是脚本而非模型报告的是大多会导致 CI 失败的仓库规则会持续评论直到修复。若不同意某条评论可以 resolve 该线程或回复 评审者将不再在后续轮次提出类似问题。结语从提出新 recipe 的 issue、借助prepare-python-recipe一键准备到逐项通过通用与语言专项检查、在 PR 前跑完 validate/ruff/uv 命令链再到理解失败级联与自动化评审的节奏——docs/recipe-checklist.md 把整套流程压缩到了一页纸里而 tools/validate.py、tools/validate_manifest.py、tools/validate_structure.py 等源码则揭示了这些规则为什么这么定的底层逻辑。日常提交以检查清单为操作手册遇到疑问再回到 docs/recipe-handbook/README.md 及其各分页anatomy、Python 语言规则、技能目录、故障排查寻找深度解释即可让每一个进入contrib/的 recipe 都达到可运行、可维护、可被社区复用的标准。【免费下载链接】adk-samplesA collection of sample agents built with Agent Development Kit (ADK)项目地址: https://gitcode.com/GitHub_Trending/ad/adk-samples创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考