企业官网建设流程全解析

agents-cli scaffold 命令 Flag 参考：create 与 enhance 的完整参数体系及源码解析

【免费下载链接】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

本篇围绕 scaffold 技能的 flags.md 参考文档 展开，完整覆盖agents-cli scaffold create与agents-cli scaffold enhance两条命令的全部 Flag 定义、默认值与取值范围，并结合同仓库中 create 命令源码、enhance 命令源码 和 模板常量定义 深入解析每个参数的底层行为：项目名校验与归一化、部署目标与会话类型的默认值推导链、严格编程模式下的必填约束，以及 enhance 基于三方比对（smart-merge）的增量更新机制。读完后你可以准确写出可复制运行的 scaffold 命令，并理解每个 Flag 在源码中究竟如何生效。

1. scaffold 命令组总览

scaffold是 agents-cli 中负责“项目脚手架”的命令组，其命令组定义在 cmd_scaffold_group.py，包含三个子命令：

本文聚焦 flags.md 文档覆盖的create与enhance两条命令的 Flag 参考。两条命令共享一套模板类选项，在源码中由shared_template_options装饰器统一挂载（见 create.py 第 69–168 行），因此大部分 Flag 在两条命令中行为一致。

2.agents-cli scaffold createFlag 全表

以下表格完整继承 flags.md 中的createFlag 参考：

查看某版本 CLI 的完整可用 Flag：agents-cli scaffold create --help。

2.1 ADK 专属说明

• --adk是内置 ADK 模板的快捷方式，而adk是唯一的内置模板。--agent还可以接收模板仓库形式（<org>/<repo>[/<path>]@<tag>或local@<path>），其他框架正是以此方式交付。
• 如需使用 Google AI Studio 替代 Vertex AI，编辑生成项目的.env：注释掉GOOGLE_*三行，取消注释GEMINI_API_KEY。生成的.env模板即如此组织（见 python 基础模板的 .env.example）：

# Vertex AI Configuration (default) GOOGLE_GENAI_USE_VERTEXAI=true GOOGLE_CLOUD_PROJECT=your-gcp-project-id GOOGLE_CLOUD_LOCATION=global # Alternatively, for Gemini API via Google AI Studio, # comment out the three lines above and uncomment: # GEMINI_API_KEY=your-api-key-here

2.2 取值范围由源码枚举保证

--session-type、--cicd-runner、--deployment-target的合法取值在源码中以click.Choice硬约束，非法值会被 Click 直接拒绝：

• SESSION_TYPES枚举（template.py 第 55–68 行）：
  • in_memory：无状态，数据驻留内存；
  • cloud_sql：PostgreSQL 持久化；
  • agent_platform_sessions：托管会话服务。
• DEPLOYMENT_TARGETS枚举（template.py 第 396–413 行）：
  • agent_runtime：Vertex AI 托管平台；
  • cloud_run：Serverless 容器平台；
  • gke：托管 Kubernetes（Autopilot）；
  • none：不做云部署。
• --cicd-runner的 Choice 列表为["google_cloud_build", "github_actions", "skip"]（见 create.py 第 126–130 行）。

3.create关键 Flag 的源码级行为

3.1--adk：快速开始模式的默认值覆写链

--adk并非简单别名，源码中它会强制覆写多个参数（create.py 第 403–426 行）：

1. agent强制置为adk，若同时传了其他--agent值会被忽略并打印警告；
2. deployment_target强制置为agent_runtime，同样忽略其他取值；
3. prototype = True、auto_approve = True，即跳过所有交互提问。

因此agents-cli scaffold create my-agent --adk等价于--agent adk --deployment-target agent_runtime --prototype --auto-approve，是官方推荐的最快启动路径。

3.2--prototype：跳过 CI/CD 与 Terraform 的双重效果

--prototype在源码中有两处联动效果：

• 未指定--deployment-target时，自动推导deployment_target='none'（create.py 第 717–723 行）；
• CI/CD 运行器强制置为skip，即使显式传了--cicd-runner github_actions也会被忽略并提示（create.py 第 836–844 行）。

这实现了 flags.md 所说的 “Prototype First” 模式：先只生成可运行的代码（仍含 Dockerfile），待 agent 迭代完成后再用scaffold enhance追加部署与 CI/CD。

3.3--agent：四种模板来源的解析流程

--agent的取值解析逻辑位于 create.py 第 476–566 行，支持四种来源：

1. 本地名（如adk）：从内置agents/目录加载对应.template；旧名（adk_base、adk_a2a_base、adk_a2a）通过AGENT_ALIASES映射到adk（template.py 第 49–53 行）；
2. 本地路径：local@/path/to/template，源码会将其复制到临时目录再套用模板；
3. 远程模板仓库：<org>/<repo>[/<path>]@<tag>或完整 Git URL，由remote_template.fetch_remote_template拉取；
4. adk-samples 快捷方式：adk@<name>，拉取 ADK 示例仓库并用启发式方式模板化，CLI 会提示“需按生成的 README 完成配置”。

从源码结构看，模板来源会以recorded_spec记录到项目清单中，后续enhance与upgrade可据此重新拉取同一模板——这是 enhance 无需重新指定--agent也能复现原模板的基础。

3.4 项目名约束：26 字符上限与自动归一化

flags.md 未展开但源码中明确存在的两条规则：

• 项目名超过 26 字符直接报错（UsageError），与技能文档“26 字符以内、仅限小写字母/数字/连字符”的约束一致（create.py 第 388–393 行）；
• 含大写或下划线的名称会被自动归一化：转小写、下划线替换为连字符，并打印提示（normalize_project_name）。

另外注意：不要预先mkdir项目目录——若目标目录已存在，create会直接报 “Project directory ... already exists”。

3.5--session-type与部署目标的联动

会话类型的最终取值由部署目标决定（create.py 第 764–829 行）：

非 Python 语言模板（Go/Java/TypeScript）无论传什么都回退为in_memory并打印警告。这也解释了 flags.md 中“与cloud_run或gke目标搭配使用（Agent Runtime 自行管理会话）”的备注。

3.6 默认值与“严格编程模式”

文档表格中列出的默认值（--region us-east1、--agent-guidance-filename GEMINI.md、--output-dir 当前目录）与源码逐一对应：

• --region在shared_template_options中声明default="us-east1"（create.py 第 93–97 行）；
• --agent-guidance-filename默认"GEMINI.md"（create.py 第 163–167 行），可按 IDE 传CLAUDE.md（Claude Code）或AGENTS.md（OpenAI Codex 等）；
• --deployment-target选项本身未声明默认值——在严格的编程模式（strict programmatic）下它是必填项，缺失会抛出UsageError并提示改用-i或-y；表格中 “默认agent_runtime” 描述的是--adk快速开始及交互/自动批准模式下的选择结果。

三种运行模式的行为差异：

• 无-i无-y：严格编程模式，所有必需参数必须以 Flag 显式提供，否则报错；
• --auto-approve/-y：跳过提问，缺失参数取默认值（如项目名缺省为my-agent、部署目标取该模板第一个可用目标）；
• --interactive/-i：面向人工终端，弹出编号菜单（模板选择、部署目标、会话类型、CI/CD 运行器、区域确认）。

--skip-checks/-s会跳过 GCP 凭证与 Vertex AI 的验证（仍会尝试解析一个 project ID 写入.env，便于本地开发）；--bq-analytics则把 BigQuery Agent Analytics 插件加入生成物，用于 agent 观测分析。

4.agents-cli scaffold enhanceFlag 全表

flags.md 中的enhanceFlag 参考如下（在已有项目目录内执行，或用路径代替.）：

查看完整 Flag 列表：agents-cli scaffold enhance --help。

--force、--dry-run、--prefer-new三个 enhance 独有选项在 enhance.py 第 818–836 行 中定义，注意源码校验了--dry-run与--force不可同时使用（二者语义冲突：一个跳过比对，一个预览比对结果）。

4.1 smart-merge：enhance 的三方比对机制

enhance 的核心不是“直接覆盖文件”，而是基于 agents-cli-manifest.yaml 中保存的生成元数据做三方比对（run_three_way_merge 调用点见 enhance.py 第 781–795 行）：

1. 用原始生成参数（manifest 中记录的create_params）在临时目录重建 “old” 模板树；
2. 用old 参数 + 本次 enhance 的覆写参数重建 “new” 模板树（参数拼装逻辑见 _build_enhance_create_args）；
3. 以“当前项目文件”为结果、old/new 为基线做三方对比，只更新用户未修改过的文件——你的 agent 逻辑与自定义代码得以保留；
4. 应用前自动备份项目（backup 工具），应用后把新参数回写 manifest。

在此机制下：

• --force：跳过比对，全量覆写；
• --dry-run：只预览差异清单，不落盘（要求项目已有保存元数据，否则无法重建 old 树）；
• --prefer-new：某文件既被模板更新又被用户修改（冲突）时，以新模板为准；
• --agent-directory：若 agent 代码不在默认的app/下（例如放在agent/），必须传入，否则比对基准与落点都会错位。

4.2 版本锁定与保存配置复用

从源码结构看，enhance 还内置了版本锁定能力：若项目记录的acli_version与当前 CLI 版本不同，enhance 会通过uvx google-agents-cli@<锁定版本>以原版本重放命令（enhance.py 第 235–280 行），保证模板行为与项目创建时一致；_ENV_SKIP_VERSION_LOCK环境变量可跳过锁定。

4.3 典型 enhance 场景

# 在原型项目上追加 Agent Runtime 部署 agents-cli scaffold enhance . --deployment-target agent_runtime # 追加 GitHub Actions CI/CD 流水线 agents-cli scaffold enhance . --cicd-runner github_actions # 先预览变更再应用 agents-cli scaffold enhance . --deployment-target gke --dry-run

当部署目标从cloud_run/gke切换到agent_runtime时，manifest 中残留的session_type会被自动清除（_stale_manifest_keys_for_target），与 create 侧“Agent Runtime 自管会话”的规则保持一致。

5. 实践建议与约束小结

1. 快速起步：agents-cli scaffold create my-agent --adk一条命令完成 adk + agent_runtime + prototype 三合一，跳过所有交互；
2. Prototype First：先--prototype让 agent 代码跑通，再enhance . --deployment-target <target>追加基础设施，避免一次性生成大量尚不需要的 Terraform/CI 文件；
3. 编程化调用（CI、Agent 调用场景）：不要依赖交互模式，显式传齐--agent、--deployment-target等必需参数，需要无交互确认时加--auto-approve；
4. AI Studio 用户：生成后按 base_templates/python/.env.example 的注释，注释GOOGLE_*三行并启用GEMINI_API_KEY；
5. 已有项目：确认 agent 代码目录后再 decide 是否传--agent-directory；对非标准结构可先在/tmp下scaffold create ref-project --output-dir /tmp生成参考项目，按需挑选文件（此用法见同目录 SKILL.md 的 “Scaffold as Reference” 章节）。

6. 参考文件索引

本文描述的行为基于当前仓库版本的源码与文档；不同 agents-cli 版本的 Flag 集合可能变化，请以agents-cli scaffold create --help/agents-cli scaffold enhance --help的实际输出为准。

【免费下载链接】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