agent-starter-pack Makefile 模板回归测试套件从快照、哈希到 Jinja2 条件渲染的完整实践指南【免费下载链接】agent-starter-packShip AI Agents to Google Cloud in minutes, not months. Production-ready templates with built-in CI/CD, evaluation, and observability.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-starter-pack本指南围绕agent-starter-pack仓库中的 Makefile 模板测试套件 展开深入讲解如何对base_templates下的 Jinja2 化 Makefile 模板进行回归测试通过 Snapshot全量输出对比、HashSHA256 快速校验与 Feature关键 target 存在性校验三层测试机制保证重构模板时不会改变任何 Agent 类型、部署目标与功能组合下生成产物。读完本文你将掌握该测试套件的运行方式、基准基线baseline更新流程、测试失败排查方法以及从源码级理解 Makefile 模板渲染与合并的底层原理。为什么需要一个 Makefile 模板测试套件agent-starter-pack的核心价值在于几分钟内把 AI Agent 交付到 Google Cloud用户通过 CLIagent-starter-pack create选择语言Python / Go / Java / TypeScript、Agent 类型ADK、ADK Live、Agentic RAG、LangGraph 等与部署目标Cloud Run / Agent Engine / GKECLI 会以 Cookieccutter Jinja2 的方式渲染出一套包含Makefile的完整项目骨架。其中Makefile是一个信息密度极高的聚合产物它把依赖安装、本地 playground、后端部署、数据接入、测试、lint、Agent 评估、Gemini Enterprise 注册等数十个目标target全部编排在一起并且依据几十个 cookiecutter 上下文变量通过 Jinja2 条件渲染出不同内容。一旦有人重构了模板例如抽取公共变量、调整条件分支哪怕改错一个{% if %}都可能导致特定 Agent 类型如 ADK Live丢失build-frontend目标特定部署目标如 Agent Engine丢失playground-remote目标自定义命令custom commands覆盖逻辑失效数据接入型 AgentVertex AI Search / Vector Search丢失setup-datastore、sync-data等目标。正因如此tests/unit/test_makefile_template.py 用渲染 → 与基线对比的方式做回归保护配套的 tests/unit/README_MAKEFILE_TESTS.md 记录了运行、排查与更新基线的完整工作流。测试覆盖范围9 类核心配置矩阵按 README_MAKEFILE_TESTS.md 所述测试覆盖 9 类核心配置。这 9 类配置在源码中由TEST_CONFIGURATIONS字典定义见 test_makefile_template.py每个配置就是一个完整的 cookiecutter 上下文包含project_name、agent_directory、deployment_target、cicd_runner、is_adk、is_adk_live、is_a2a、data_ingestion、agent_garden、settings等字段配置类别部署目标关键特征ADK Baseadk_cloud_run_no_data/adk_agent_engine_no_data/adk_gke_no_dataCloud Run / Agent Engine / GKEis_adk: True无数据接入ADK Liveadk_live_cloud_run/adk_live_agent_engine/adk_live_gkeCloud Run / Agent Engine / GKEis_adk_live: True含前端构建目标Agentic RAGagentic_rag_cloud_run_vertex_search/agentic_rag_cloud_run_vector_searchCloud Rundata_ingestion: True区分 Vertex AI Search 与 Vector SearchLangGraphlanggraph_cloud_run/langgraph_agent_engine/langgraph_gkeCloud Run / Agent Engine / GKEis_a2a: Trueagent_name: langgraph自定义命令agent_with_custom_commandsCloud Runsettings.commands含 override 与 extraAgent Gardenagent_with_agent_gardenCloud Runcicd_runner: skipagent_garden: TrueADK A2Aadk_a2a_cloud_run/adk_a2a_agent_engine/adk_a2a_gkeCloud Run / Agent Engine / GKEis_adk与is_a2a同时为 True此外还包含 Go 语言adk_go_cloud_run/adk_go_gke与 Java 语言adk_java_cloud_run/adk_java_gke的专用配置矩阵见 GO_TEST_CONFIGURATIONS 与 JAVA_TEST_CONFIGURATIONS。所有配置合计超过 20 个仓库中的 makefile_hashes.json 里登记了 21 个配置的 SHA256 基线。运行测试三条命令覆盖三种需求套件推荐用uv run pytest运行项目根目录 pyproject.toml 已配置 uv 环境# 运行全部测试 uv run pytest tests/unit/test_makefile_template.py -v # 按类别过滤哈希测试最快无大 diff 输出 uv run pytest tests/unit/test_makefile_template.py -v -k test_makefile_hash # 按类别过滤快照测试失败时输出完整 diff uv run pytest tests/unit/test_makefile_template.py -v -k test_makefile_snapshot # 按功能过滤只跑 ADK Live 相关用例 uv run pytest tests/unit/test_makefile_template.py -v -k test_adk_live-k关键字过滤依赖 pytest 对测试名的子串匹配例如test_adk_live会命中test_adk_live_has_frontend_targets、test_adk_live_agent_engine_has_remote_playground等用例。若只想针对某一个配置跑快照测试可以直接定位参数化用例uv run pytest tests/unit/test_makefile_template.py::TestMakefileGeneration::test_makefile_snapshot[adk_cloud_run_no_data] -v在 CI/CD 中套件被设计为一条命令即可接入README_MAKEFILE_TESTS.md 中给出了 GitHub Actions 风格的 YAML 片段- name: Test Makefile Template run: uv run pytest tests/unit/test_makefile_template.py -v三层测试机制Snapshot / Hash / Feature套件的设计思路是分层防护用最轻量的手段快速发现问题用最完整的输出精确定位差异。三种测试类型各司其职Snapshot全量输出对比用于调试Snapshot 测试test_makefile_snapshot把渲染结果与 tests/fixtures/makefile_snapshots/ 下同名.makefile文件逐字符比较失败时报告完整差异方便肉眼审查生成产物到底哪里变了。例如 adk_cloud_run_no_data.makefile 是一份完整的 ADK Cloud Run 项目 Makefile 快照。Snapshot 文件不存在时例如新增配置后首次运行测试会自动写入新快照并pytest.skip提示开发者确认快照内容后再正式纳入基线。HashSHA256 校验服务于 CI/CD 速度Hash 测试test_makefile_hash对渲染结果做hashlib.sha256摘要与 makefile_hashes.json 中的注册值比对。相比 SnapshotHash 不产生大段 diff 输出、占用更少 CI 日志适合作为快速回归门禁只有哈希不匹配时才需要用 Snapshot 测试生成完整 diff 进一步定位。Feature关键 target 存在性验证用于功能正确性Feature 测试不是输出对比而是断言生成的 Makefile 中必须包含某类目标直接守护功能不被模板重构破坏。这些断言从源码中可以直接读出来test_adk_live_has_frontend_targetsADK Live 必须包含build-frontend:与build-frontend-if-needed:test_adk_live_agent_engine_has_remote_playgroundADK Live Agent Engine 必须包含playground-remote:、ui:、playground-dev:test_vertex_search_has_data_ingestion_targetsVertex AI Search 配置必须包含setup-datastore:、data-ingestion:、sync-data:与start_connector_runtest_vector_search_has_data_ingestion_targetVector Search 配置必须包含setup-datastore:、data-ingestion:、--collection-id、--local、VECTOR_SEARCH_COLLECTION且不应包含sync-data:test_custom_commands_override 与 test_custom_commands_extra自定义命令的 override 与 extra 必须生效test_deployment_specific_custom_command部署目标相关的自定义命令必须选中当前部署目标对应的变体test_agent_garden_labelsAgent Garden 配置必须包含deployed-withagent-garden等标签test_cloud_run_backend_command 与 test_agent_engine_backend_commandCloud Run 走gcloud beta run deploy、Agent Engine 走uv exportapp_utils.deploytest_all_configs_have_required_targets所有配置都必须有install:、playground:、backend:、test:、lint:五个公共目标同时按cicd_runner/data_ingestion组合断言setup-dev-env:或setup-datastore:的出现与否。Go 与 Java 还有各自的必需目标断言Go 要求install、playground、test、lint、buildtest_go_makefile_has_required_targetsJava 额外要求使用 Maven 命令test_java_makefile_uses_maven。底层原理MakefileRenderer 如何用 Jinja2 复刻 Cookieccutter 渲染测试并不直接调用 CLI 的渲染逻辑而是用MakefileRenderer类test_makefile_template.py在测试进程内独立完成模板渲染从而做到快、隔离、可控class MakefileRenderer: def __init__(self, language: str python) - None: self.language language template_dir ( Path(__file__).parent.parent.parent / agent_starter_pack / base_templates / language ) self.env Environment( loaderFileSystemLoader(str(template_dir)), undefinedStrictUndefined, keep_trailing_newlineTrue, ) self.env.add_extension(jinja2.ext.do)几个关键点值得展开模板目录即语言基础模板目录template_dir指向 agent_starter_pack/base_templates/python或go、java通过FileSystemLoader加载该目录下的Makefile模板。StrictUndefined开启未定义变量报错模板里任何引用了但上下文未提供的变量都会直接抛错而不是静默渲染为空。README 的 Troubleshooting 中提到 Missing variables:StrictUndefinedis already enabled正是指这个行为——它让模板引用了不存在的配置字段这类问题在测试期就暴露。keep_trailing_newlineTrue保证渲染结果保留尾部换行使 Snapshot 对比不受行尾差异干扰。jinja2.ext.do扩展这是 Cookieccutter 渲染 Makefile 时用到的扩展测试环境主动注册确保与真实生成流程的行为一致。render()以cookiecutter为命名空间template.render(cookiecuttercontext)复刻了真实渲染时{{ cookiecutter.xxx }}的变量路径。测试通过pytest.fixture分别提供 Python / Go / Java 三个渲染器makefile_renderer 等并配合两个持久化 fixture——snapshot_dir指向 tests/fixtures/makefile_snapshots/hash_file指向 tests/fixtures/makefile_hashes.json见 snapshot_dir注意它们不是tmp目录而是仓库内真实持久化路径这正是基线文件的存放位置。模板侧的证据Jinja2 条件分支与可配置项测试断言的内容都能在真实模板里找到对应实现。以 agent_starter_pack/base_templates/python/Makefile 为例自定义命令覆盖install与playground目标通过cookiecutter.settings.get(commands, {}).get(override, {})判断是否用自定义命令替换默认的uv sync/ playground 启动逻辑模板 L34-L51extra命令则循环生成Agent-Specific Commands段L94-L121且支持按部署目标选择命令变体。这与 agent_with_custom_commands.makefile 快照中custom-task:与env-specific-task:的实际输出一一对应。ADK Live 前端目标build-frontend、build-frontend-if-needed带增量构建判断、playground-remote、ui、playground-dev均由cookiecutter.is_adk_live及deployment_target agent_engine条件控制L137-L192。数据接入目标data_ingestiondatastore_type分支决定生成 Vertex AI Search 版本的setup-datastore/data-ingestion/sync-data还是 Vector Search 版本后者没有sync-dataL337-L385。部署命令deploy目标按cloud_run/gke/agent_engine三个分支渲染L266-L331Agent Engine 分支使用uv export导出依赖并调用app_utils.deploy。Agent 评估仅is_adk且非is_adk_live时生成eval与eval-all目标L409-L437。模板开头还有一个extracted|default(false)分支被agent-starter-pack extract提取出的精简 Agent 项目会生成一个最小化 Makefile只保留install与playground。这说明同一套测试机制覆盖了完整项目与提取项目两类渲染路径。在真实生成流程中的位置render_and_merge_makefiles测试模拟的渲染在生产流程中由render_and_merge_makefiles完成。在 agent_starter_pack/cli/utils/template.py 中可以看到CLI 生成项目时会把Makefile加入_copy_without_render列表template.py避免 Cookieccutter 的默认渲染路径处理它项目骨架生成完毕后调用render_and_merge_makefiles以语言基础模板路径为基准渲染基础 Makefile若使用了远程模板remote template还会把远程模板中的 Makefile 与基础 Makefile 合并生成最终产物。这也解释了测试为何按语言提供独立渲染器基础 Makefile 模板是按语言分目录存放的base_templates/go/Makefile、base_templates/java/Makefile、base_templates/typescript/Makefile测试需要逐一覆盖。重构工作流把改模板变成可验证的变更README 给出的重构流程本质上是一种 TDD 式的基线守护循环改动前先跑测试确认基线是绿的记录当前行为对 agent_starter_pack/base_templates 下的 Makefile 模板做小步增量修改频繁运行测试第一时间捕捉意外变更用-k test_makefile_hash做快速反馈全部通过后重构完成。配套的重构建议来自 README 与模板实践包括使用 Jinja2 变量提升可复用性、为复杂条件分支写注释、按 Agent / 部署类型分组目标以及保持小步提交。测试失败排查三类失败三种解法README 把失败归纳为三类结合源码可以给出更精确的定位路径Snapshot 失败生成产物变了Makefile output changed for config. To update snapshots, delete tests/fixtures/makefile_snapshots/config.makefile and rerun tests.先用git diff tests/fixtures/makefile_snapshots/config.makefile审查差异是否符合预期例如新增目标、调整命令。若是有意为之删除对应快照文件后重跑测试会自动重新生成基线。Hash 失败内容摘要变了说明渲染结果发生变化。如果确认是预期变更删除 tests/fixtures/makefile_hashes.json 后重跑即可重新登记全部哈希若只想更新单个配置可只删对应哈希条目。注意 Hash 失败通常伴随 Snapshot 失败先用 Snapshot 的 diff 确认变更内容再更新基线。Feature 失败必需目标缺失Required target target missing in config这是功能退化信号需要回到模板检查 Jinja2 条件分支——例如{%- if cookiecutter.is_adk_live %}是否在重构中被误删或条件变量名是否被改写导致分支永远不进入。此时应修复模板本身而不是更新基线。其他常见问题README Troubleshooting测试太慢优先用-k test_makefile_hash需要看差异用-k test_makefile_snapshotJinja2 报错错误消息自带行号直接定位模板对应行未定义变量StrictUndefined已开启检查 cookiecutter 上下文是否漏传字段。新增配置扩展测试矩阵的完整步骤当项目新增一种 Agent 类型或功能组合例如未来的新部署目标时按以下步骤把新配置纳入回归保护在 test_makefile_template.py 的TEST_CONFIGURATIONSPython、GO_TEST_CONFIGURATIONSGo或JAVA_TEST_CONFIGURATIONSJava中添加新配置条目字段必须完整覆盖模板引用的所有 cookiecutter 变量运行测试生成基线uv run pytest tests/unit/test_makefile_template.py -v首次运行时快照与哈希都会自动写入并跳过该用例 3. 人工核验新快照内容cat tests/fixtures/makefile_snapshots/config.makefile确认install、playground、deploy、test、lint等目标以及该功能特有的目标都正确生成 4. 如果新功能带有专属 target 语义如 ADK Live 的build-frontend建议同时新增一条 Feature 断言用例防止后续重构悄悄删掉关键目标 5. 提交代码时一并提交新增的.makefile快照与更新后的makefile_hashes.json作为新基线入库。与周边测试的协同不止于单元测试Makefile 模板测试并非孤立存在。仓库中还有一套 tests/integration/test_makefile_usability.py它通过validate_makefile_usability从生成的 Makefile 能否真正被 make 执行的角度做集成校验例如检查目标引用的文件/目录是否存在、命令是否可解析并组合语言与部署目标进行批量验证get_makefile_test_combinations。单元测试负责模板渲染正确性集成测试负责渲染结果可用性两者配合共同守护Makefile这条交付链路的质量。小结agent-starter-pack的 Makefile 模板测试套件为Jinja2 条件模板重构这一高风险动作提供了三层防线Feature 断言守住功能底线关键 target 永不丢失Snapshot 对比给出人类可读的完整 diffSHA256 哈希为 CI/CD 提供秒级快速门禁。它把模板改坏了从用户创建项目后才发现前移到提交代码前就被拦截。对于任何维护 Cookieccutter / Jinja2 模板型脚手架项目的团队这套配置矩阵 三层断言 自动基线的组合都是值得直接借鉴的回归测试范式。关键文件速查测试套件说明tests/unit/README_MAKEFILE_TESTS.md测试实现tests/unit/test_makefile_template.pyPython Makefile 模板agent_starter_pack/base_templates/python/MakefileGo / Java 模板agent_starter_pack/base_templates/go/Makefile、agent_starter_pack/base_templates/java/Makefile快照基线与哈希基线tests/fixtures/makefile_snapshots/、tests/fixtures/makefile_hashes.json生成流程中的渲染入口agent_starter_pack/cli/utils/template.py集成侧的可执行性校验tests/integration/test_makefile_usability.py【免费下载链接】agent-starter-packShip AI Agents to Google Cloud in minutes, not months. Production-ready templates with built-in CI/CD, evaluation, and observability.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-starter-pack创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 agent-starter-pack Makefile 模板回归测试套件：从快照、哈希到 Jinja2 条件渲染的完整实践指南
agent-starter-pack Makefile 模板回归测试套件从快照、哈希到 Jinja2 条件渲染的完整实践指南【免费下载链接】agent-starter-packShip AI Agents to Google Cloud in minutes, not months. Production-ready templates with built-in CI/CD, evaluation, and observability.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-starter-pack本指南围绕agent-starter-pack仓库中的 Makefile 模板测试套件 展开深入讲解如何对base_templates下的 Jinja2 化 Makefile 模板进行回归测试通过 Snapshot全量输出对比、HashSHA256 快速校验与 Feature关键 target 存在性校验三层测试机制保证重构模板时不会改变任何 Agent 类型、部署目标与功能组合下生成产物。读完本文你将掌握该测试套件的运行方式、基准基线baseline更新流程、测试失败排查方法以及从源码级理解 Makefile 模板渲染与合并的底层原理。为什么需要一个 Makefile 模板测试套件agent-starter-pack的核心价值在于几分钟内把 AI Agent 交付到 Google Cloud用户通过 CLIagent-starter-pack create选择语言Python / Go / Java / TypeScript、Agent 类型ADK、ADK Live、Agentic RAG、LangGraph 等与部署目标Cloud Run / Agent Engine / GKECLI 会以 Cookieccutter Jinja2 的方式渲染出一套包含Makefile的完整项目骨架。其中Makefile是一个信息密度极高的聚合产物它把依赖安装、本地 playground、后端部署、数据接入、测试、lint、Agent 评估、Gemini Enterprise 注册等数十个目标target全部编排在一起并且依据几十个 cookiecutter 上下文变量通过 Jinja2 条件渲染出不同内容。一旦有人重构了模板例如抽取公共变量、调整条件分支哪怕改错一个{% if %}都可能导致特定 Agent 类型如 ADK Live丢失build-frontend目标特定部署目标如 Agent Engine丢失playground-remote目标自定义命令custom commands覆盖逻辑失效数据接入型 AgentVertex AI Search / Vector Search丢失setup-datastore、sync-data等目标。正因如此tests/unit/test_makefile_template.py 用渲染 → 与基线对比的方式做回归保护配套的 tests/unit/README_MAKEFILE_TESTS.md 记录了运行、排查与更新基线的完整工作流。测试覆盖范围9 类核心配置矩阵按 README_MAKEFILE_TESTS.md 所述测试覆盖 9 类核心配置。这 9 类配置在源码中由TEST_CONFIGURATIONS字典定义见 test_makefile_template.py每个配置就是一个完整的 cookiecutter 上下文包含project_name、agent_directory、deployment_target、cicd_runner、is_adk、is_adk_live、is_a2a、data_ingestion、agent_garden、settings等字段配置类别部署目标关键特征ADK Baseadk_cloud_run_no_data/adk_agent_engine_no_data/adk_gke_no_dataCloud Run / Agent Engine / GKEis_adk: True无数据接入ADK Liveadk_live_cloud_run/adk_live_agent_engine/adk_live_gkeCloud Run / Agent Engine / GKEis_adk_live: True含前端构建目标Agentic RAGagentic_rag_cloud_run_vertex_search/agentic_rag_cloud_run_vector_searchCloud Rundata_ingestion: True区分 Vertex AI Search 与 Vector SearchLangGraphlanggraph_cloud_run/langgraph_agent_engine/langgraph_gkeCloud Run / Agent Engine / GKEis_a2a: Trueagent_name: langgraph自定义命令agent_with_custom_commandsCloud Runsettings.commands含 override 与 extraAgent Gardenagent_with_agent_gardenCloud Runcicd_runner: skipagent_garden: TrueADK A2Aadk_a2a_cloud_run/adk_a2a_agent_engine/adk_a2a_gkeCloud Run / Agent Engine / GKEis_adk与is_a2a同时为 True此外还包含 Go 语言adk_go_cloud_run/adk_go_gke与 Java 语言adk_java_cloud_run/adk_java_gke的专用配置矩阵见 GO_TEST_CONFIGURATIONS 与 JAVA_TEST_CONFIGURATIONS。所有配置合计超过 20 个仓库中的 makefile_hashes.json 里登记了 21 个配置的 SHA256 基线。运行测试三条命令覆盖三种需求套件推荐用uv run pytest运行项目根目录 pyproject.toml 已配置 uv 环境# 运行全部测试 uv run pytest tests/unit/test_makefile_template.py -v # 按类别过滤哈希测试最快无大 diff 输出 uv run pytest tests/unit/test_makefile_template.py -v -k test_makefile_hash # 按类别过滤快照测试失败时输出完整 diff uv run pytest tests/unit/test_makefile_template.py -v -k test_makefile_snapshot # 按功能过滤只跑 ADK Live 相关用例 uv run pytest tests/unit/test_makefile_template.py -v -k test_adk_live-k关键字过滤依赖 pytest 对测试名的子串匹配例如test_adk_live会命中test_adk_live_has_frontend_targets、test_adk_live_agent_engine_has_remote_playground等用例。若只想针对某一个配置跑快照测试可以直接定位参数化用例uv run pytest tests/unit/test_makefile_template.py::TestMakefileGeneration::test_makefile_snapshot[adk_cloud_run_no_data] -v在 CI/CD 中套件被设计为一条命令即可接入README_MAKEFILE_TESTS.md 中给出了 GitHub Actions 风格的 YAML 片段- name: Test Makefile Template run: uv run pytest tests/unit/test_makefile_template.py -v三层测试机制Snapshot / Hash / Feature套件的设计思路是分层防护用最轻量的手段快速发现问题用最完整的输出精确定位差异。三种测试类型各司其职Snapshot全量输出对比用于调试Snapshot 测试test_makefile_snapshot把渲染结果与 tests/fixtures/makefile_snapshots/ 下同名.makefile文件逐字符比较失败时报告完整差异方便肉眼审查生成产物到底哪里变了。例如 adk_cloud_run_no_data.makefile 是一份完整的 ADK Cloud Run 项目 Makefile 快照。Snapshot 文件不存在时例如新增配置后首次运行测试会自动写入新快照并pytest.skip提示开发者确认快照内容后再正式纳入基线。HashSHA256 校验服务于 CI/CD 速度Hash 测试test_makefile_hash对渲染结果做hashlib.sha256摘要与 makefile_hashes.json 中的注册值比对。相比 SnapshotHash 不产生大段 diff 输出、占用更少 CI 日志适合作为快速回归门禁只有哈希不匹配时才需要用 Snapshot 测试生成完整 diff 进一步定位。Feature关键 target 存在性验证用于功能正确性Feature 测试不是输出对比而是断言生成的 Makefile 中必须包含某类目标直接守护功能不被模板重构破坏。这些断言从源码中可以直接读出来test_adk_live_has_frontend_targetsADK Live 必须包含build-frontend:与build-frontend-if-needed:test_adk_live_agent_engine_has_remote_playgroundADK Live Agent Engine 必须包含playground-remote:、ui:、playground-dev:test_vertex_search_has_data_ingestion_targetsVertex AI Search 配置必须包含setup-datastore:、data-ingestion:、sync-data:与start_connector_runtest_vector_search_has_data_ingestion_targetVector Search 配置必须包含setup-datastore:、data-ingestion:、--collection-id、--local、VECTOR_SEARCH_COLLECTION且不应包含sync-data:test_custom_commands_override 与 test_custom_commands_extra自定义命令的 override 与 extra 必须生效test_deployment_specific_custom_command部署目标相关的自定义命令必须选中当前部署目标对应的变体test_agent_garden_labelsAgent Garden 配置必须包含deployed-withagent-garden等标签test_cloud_run_backend_command 与 test_agent_engine_backend_commandCloud Run 走gcloud beta run deploy、Agent Engine 走uv exportapp_utils.deploytest_all_configs_have_required_targets所有配置都必须有install:、playground:、backend:、test:、lint:五个公共目标同时按cicd_runner/data_ingestion组合断言setup-dev-env:或setup-datastore:的出现与否。Go 与 Java 还有各自的必需目标断言Go 要求install、playground、test、lint、buildtest_go_makefile_has_required_targetsJava 额外要求使用 Maven 命令test_java_makefile_uses_maven。底层原理MakefileRenderer 如何用 Jinja2 复刻 Cookieccutter 渲染测试并不直接调用 CLI 的渲染逻辑而是用MakefileRenderer类test_makefile_template.py在测试进程内独立完成模板渲染从而做到快、隔离、可控class MakefileRenderer: def __init__(self, language: str python) - None: self.language language template_dir ( Path(__file__).parent.parent.parent / agent_starter_pack / base_templates / language ) self.env Environment( loaderFileSystemLoader(str(template_dir)), undefinedStrictUndefined, keep_trailing_newlineTrue, ) self.env.add_extension(jinja2.ext.do)几个关键点值得展开模板目录即语言基础模板目录template_dir指向 agent_starter_pack/base_templates/python或go、java通过FileSystemLoader加载该目录下的Makefile模板。StrictUndefined开启未定义变量报错模板里任何引用了但上下文未提供的变量都会直接抛错而不是静默渲染为空。README 的 Troubleshooting 中提到 Missing variables:StrictUndefinedis already enabled正是指这个行为——它让模板引用了不存在的配置字段这类问题在测试期就暴露。keep_trailing_newlineTrue保证渲染结果保留尾部换行使 Snapshot 对比不受行尾差异干扰。jinja2.ext.do扩展这是 Cookieccutter 渲染 Makefile 时用到的扩展测试环境主动注册确保与真实生成流程的行为一致。render()以cookiecutter为命名空间template.render(cookiecuttercontext)复刻了真实渲染时{{ cookiecutter.xxx }}的变量路径。测试通过pytest.fixture分别提供 Python / Go / Java 三个渲染器makefile_renderer 等并配合两个持久化 fixture——snapshot_dir指向 tests/fixtures/makefile_snapshots/hash_file指向 tests/fixtures/makefile_hashes.json见 snapshot_dir注意它们不是tmp目录而是仓库内真实持久化路径这正是基线文件的存放位置。模板侧的证据Jinja2 条件分支与可配置项测试断言的内容都能在真实模板里找到对应实现。以 agent_starter_pack/base_templates/python/Makefile 为例自定义命令覆盖install与playground目标通过cookiecutter.settings.get(commands, {}).get(override, {})判断是否用自定义命令替换默认的uv sync/ playground 启动逻辑模板 L34-L51extra命令则循环生成Agent-Specific Commands段L94-L121且支持按部署目标选择命令变体。这与 agent_with_custom_commands.makefile 快照中custom-task:与env-specific-task:的实际输出一一对应。ADK Live 前端目标build-frontend、build-frontend-if-needed带增量构建判断、playground-remote、ui、playground-dev均由cookiecutter.is_adk_live及deployment_target agent_engine条件控制L137-L192。数据接入目标data_ingestiondatastore_type分支决定生成 Vertex AI Search 版本的setup-datastore/data-ingestion/sync-data还是 Vector Search 版本后者没有sync-dataL337-L385。部署命令deploy目标按cloud_run/gke/agent_engine三个分支渲染L266-L331Agent Engine 分支使用uv export导出依赖并调用app_utils.deploy。Agent 评估仅is_adk且非is_adk_live时生成eval与eval-all目标L409-L437。模板开头还有一个extracted|default(false)分支被agent-starter-pack extract提取出的精简 Agent 项目会生成一个最小化 Makefile只保留install与playground。这说明同一套测试机制覆盖了完整项目与提取项目两类渲染路径。在真实生成流程中的位置render_and_merge_makefiles测试模拟的渲染在生产流程中由render_and_merge_makefiles完成。在 agent_starter_pack/cli/utils/template.py 中可以看到CLI 生成项目时会把Makefile加入_copy_without_render列表template.py避免 Cookieccutter 的默认渲染路径处理它项目骨架生成完毕后调用render_and_merge_makefiles以语言基础模板路径为基准渲染基础 Makefile若使用了远程模板remote template还会把远程模板中的 Makefile 与基础 Makefile 合并生成最终产物。这也解释了测试为何按语言提供独立渲染器基础 Makefile 模板是按语言分目录存放的base_templates/go/Makefile、base_templates/java/Makefile、base_templates/typescript/Makefile测试需要逐一覆盖。重构工作流把改模板变成可验证的变更README 给出的重构流程本质上是一种 TDD 式的基线守护循环改动前先跑测试确认基线是绿的记录当前行为对 agent_starter_pack/base_templates 下的 Makefile 模板做小步增量修改频繁运行测试第一时间捕捉意外变更用-k test_makefile_hash做快速反馈全部通过后重构完成。配套的重构建议来自 README 与模板实践包括使用 Jinja2 变量提升可复用性、为复杂条件分支写注释、按 Agent / 部署类型分组目标以及保持小步提交。测试失败排查三类失败三种解法README 把失败归纳为三类结合源码可以给出更精确的定位路径Snapshot 失败生成产物变了Makefile output changed for config. To update snapshots, delete tests/fixtures/makefile_snapshots/config.makefile and rerun tests.先用git diff tests/fixtures/makefile_snapshots/config.makefile审查差异是否符合预期例如新增目标、调整命令。若是有意为之删除对应快照文件后重跑测试会自动重新生成基线。Hash 失败内容摘要变了说明渲染结果发生变化。如果确认是预期变更删除 tests/fixtures/makefile_hashes.json 后重跑即可重新登记全部哈希若只想更新单个配置可只删对应哈希条目。注意 Hash 失败通常伴随 Snapshot 失败先用 Snapshot 的 diff 确认变更内容再更新基线。Feature 失败必需目标缺失Required target target missing in config这是功能退化信号需要回到模板检查 Jinja2 条件分支——例如{%- if cookiecutter.is_adk_live %}是否在重构中被误删或条件变量名是否被改写导致分支永远不进入。此时应修复模板本身而不是更新基线。其他常见问题README Troubleshooting测试太慢优先用-k test_makefile_hash需要看差异用-k test_makefile_snapshotJinja2 报错错误消息自带行号直接定位模板对应行未定义变量StrictUndefined已开启检查 cookiecutter 上下文是否漏传字段。新增配置扩展测试矩阵的完整步骤当项目新增一种 Agent 类型或功能组合例如未来的新部署目标时按以下步骤把新配置纳入回归保护在 test_makefile_template.py 的TEST_CONFIGURATIONSPython、GO_TEST_CONFIGURATIONSGo或JAVA_TEST_CONFIGURATIONSJava中添加新配置条目字段必须完整覆盖模板引用的所有 cookiecutter 变量运行测试生成基线uv run pytest tests/unit/test_makefile_template.py -v首次运行时快照与哈希都会自动写入并跳过该用例 3. 人工核验新快照内容cat tests/fixtures/makefile_snapshots/config.makefile确认install、playground、deploy、test、lint等目标以及该功能特有的目标都正确生成 4. 如果新功能带有专属 target 语义如 ADK Live 的build-frontend建议同时新增一条 Feature 断言用例防止后续重构悄悄删掉关键目标 5. 提交代码时一并提交新增的.makefile快照与更新后的makefile_hashes.json作为新基线入库。与周边测试的协同不止于单元测试Makefile 模板测试并非孤立存在。仓库中还有一套 tests/integration/test_makefile_usability.py它通过validate_makefile_usability从生成的 Makefile 能否真正被 make 执行的角度做集成校验例如检查目标引用的文件/目录是否存在、命令是否可解析并组合语言与部署目标进行批量验证get_makefile_test_combinations。单元测试负责模板渲染正确性集成测试负责渲染结果可用性两者配合共同守护Makefile这条交付链路的质量。小结agent-starter-pack的 Makefile 模板测试套件为Jinja2 条件模板重构这一高风险动作提供了三层防线Feature 断言守住功能底线关键 target 永不丢失Snapshot 对比给出人类可读的完整 diffSHA256 哈希为 CI/CD 提供秒级快速门禁。它把模板改坏了从用户创建项目后才发现前移到提交代码前就被拦截。对于任何维护 Cookieccutter / Jinja2 模板型脚手架项目的团队这套配置矩阵 三层断言 自动基线的组合都是值得直接借鉴的回归测试范式。关键文件速查测试套件说明tests/unit/README_MAKEFILE_TESTS.md测试实现tests/unit/test_makefile_template.pyPython Makefile 模板agent_starter_pack/base_templates/python/MakefileGo / Java 模板agent_starter_pack/base_templates/go/Makefile、agent_starter_pack/base_templates/java/Makefile快照基线与哈希基线tests/fixtures/makefile_snapshots/、tests/fixtures/makefile_hashes.json生成流程中的渲染入口agent_starter_pack/cli/utils/template.py集成侧的可执行性校验tests/integration/test_makefile_usability.py【免费下载链接】agent-starter-packShip AI Agents to Google Cloud in minutes, not months. Production-ready templates with built-in CI/CD, evaluation, and observability.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-starter-pack创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考