企业官网建设流程全解析

agents-cli scaffold enhance 实战：给已有项目「外挂」部署和 CI/CD 能力

【免费下载链接】agents-cliThe CLI and skills that turn any coding assistant into an expert at creating, evaluating, and deploying AI agents on Google Cloud.项目地址: https://gitcode.com/GitHub_Trending/ag/agents-cli

本文介绍如何用agents-cli的scaffold enhance命令，一条命令给已有的 AI Agent 项目「外挂」上 Google Cloud 部署配置和 CI/CD 管道。无需手写 Terraform 和 GitHub Actions，smart-merge 机制还会自动保护你改过的每一行代码——从原型到生产，全程几分钟搞定。

一、enhance 解决什么问题：不动业务代码，只加「基础设施」

如果你已经有一个能跑起来的 Agent 项目（比如用 ADK 写的 Python 原型），现在想部署上线，通常要手动补齐一堆东西：Dockerfile、deployment/下的 Terraform 配置、CI/CD 工作流、Makefile、环境变量文件……这些文件不仅多，还容易写得和官方推荐结构不一致。

scaffold enhance的设计哲学是：把项目模板「就地应用」到你的现有目录，只添加基础设施文件，不碰你的 Agent 逻辑。它的几个关键特性：

• 🧬Smart-merge 三方对比：生成「原始模板」与「增强后模板」做对比，只覆盖你没有修改过的文件，你自定义的代码原样保留；
• 💾自动备份：写盘前会先在~/.agents-cli/backups/创建项目备份；
• 📋配置持久化：所有参数记录在agents-cli-manifest.yaml中，后续升级、再次 enhance 时自动复用（并锁定当时的 agents-cli 版本）。

下图展示了 agents-cli 所处的整体平台架构，可以看到 Deployment（Agent Runtime / Cloud Run）与 CI/CD、IaC 是它重点覆盖的环节：

二、三步上手：给已有项目添加部署能力

第 1 步：安装 agents-cli

确保环境有 Python 3.11+ 和uv，然后一条命令完成安装与技能注入：

uvx google-agents-cli setup

第 2 步：在项目目录内执行 enhance

进入你的项目目录，用.指向当前目录即可。按需组合两个最核心的参数：

# 添加部署目标（agent_runtime / cloud_run / gke） agents-cli scaffold enhance . --deployment-target cloud_run # 添加 CI/CD 管道（github_actions / google_cloud_build） agents-cli scaffold enhance . --cicd-runner github_actions

命令执行后会显示确认信息（新增哪些模板文件、备份位置等），确认后开始写盘。如果你希望用交互式菜单逐项选择部署目标、会话存储、CI/CD Runner，可以加上--interactive。

第 3 步：建议先用 --dry-run 预览

在不确定的情况下，先预览变更、零风险：

agents-cli scaffold enhance . --deployment-target gke --dry-run

确认变更列表符合预期后，去掉--dry-run正式执行。

三、部署目标怎么选：agent_runtime、cloud_run 还是 gke

enhance 支持四大部署目标，后续可以随时用同一条命令切换目标：

💡 小提示：切到agent_runtime后，enhance 会自动清理 manifest 里无意义的session_type配置——因为 Agent Runtime 会内部管理会话。

四、CI/CD 管道：拉取请求测试 → 合并上 Staging → 手动批准上生产

执行--cicd-runner后，项目会获得一套「原型到生产」的标准流水线：

整个流程分三段，对应生成的工作流文件：

1. CI 管道（Pull Request 触发）：跑单元测试 + 集成测试；
2. Staging CD 管道（合并到main触发）：构建并推送容器镜像 → 部署 Staging → 自动负载测试；
3. 生产部署（Staging 成功后）：需要手动批准，部署的是与 Staging 完全相同的镜像。

脚手架生成的是「模板文件」，真正开通双环境（staging/prod）基础设施，只需再执行一条命令，Terraform 会自动完成资源配置和仓库连接：

agents-cli infra cicd \ --staging-project my-staging-project \ --prod-project my-prod-project

Runner 的选型（GitHub Actions 使用 Workload Identity Federation 免密钥认证，Cloud Build 则自动创建 GitHub 连接）会自动从项目配置中检测。

五、实战技巧与常见坑 🛠️

另外，本地开发和验证完全不依赖 Google Cloud：agents-cli run "test prompt"做冒烟测试，agents-cli eval run做系统化评估，确认没问题再上线。

六、延伸阅读：源码与文档导航

想深入某个环节，可以直接阅读项目内的这些资料：

• 脚手架技能完整指南（含所有约束与最佳实践）：skills/google-agents-cli-scaffold/SKILL.md
• create/enhance全部参数速查表：skills/google-agents-cli-scaffold/references/flags.md
• enhance 命令核心实现（smart-merge 调用入口）：src/google/agents/cli/scaffold/commands/enhance.py
• 部署目标详解（Agent Runtime / Cloud Run / GKE）：docs/src/guide/deployment.md
• CI/CD 与生产环境完整文档：docs/src/guide/cicd.md
• 项目配置清单模板（enhance 会更新这个文件）：src/google/agents/cli/scaffold/base_templates/_shared/agents-cli-manifest.yaml

总结：原型阶段专注写 Agent 逻辑，等它稳定了，一句agents-cli scaffold enhance就能把部署和 CI/CD「外挂」上去——这正是官方推荐的 Prototype First 工作流。

【免费下载链接】agents-cliThe CLI and skills that turn any coding assistant into an expert at creating, evaluating, and deploying AI agents on Google Cloud.项目地址: https://gitcode.com/GitHub_Trending/ag/agents-cli