项目概览

agents-cli 是 Google 推出的面向 Agent 开发全生命周期的命令行工具，定位为"构建、评估、部署与运维 AI Agent"的统一入口。它既可以作为本地 CLI 直接调用，也可以作为一组建在 Claude / Gemini 等 IDE 客户端上的 Skill（google-agents-cli-workflow、google-agents-cli-deploy、google-agents-cli-adk-code 等），指导编码 Agent 完成从规格设计到上线的全部动作 资料来源：README.md:1-40。

工具面向两类使用对象：

• 直接使用 CLI 的开发者：通过 agents-cli scaffold、agents-cli eval、agents-cli deploy 等子命令完成项目脚手架生成、评测与部署。
• 通过 Skill 间接使用：在 IDE 中由编码 Agent 自动驱动 CLI，从而以自然语言方式完成整个 Agent 工程的搭建 资料来源：docs/src/guide/lifecycle.md:10-30。

当前最新发布为 Release v1.0.0（GA），相比早期版本，重部署会保留 Agent Runtime 与 Cloud Run 上既有的部署规格，Agent Runtime 的源码打包也会尊重 .gcloudignore 与 .gitignore 资料来源：README.md:60-90。

安装与初始化

CLI 通过 setup 子命令族完成首次安装、登录与环境校验，入口在 src/google/agents/cli/setup/cmd_setup.py 中定义 资料来源：src/google/agents/cli/setup/cmd_setup.py:1-60。

典型安装流程包括：

1. 安装 CLI 本身：推荐使用 uv tool install 或 pipx install google-agents-cli 等隔离方式安装，避免污染全局 Python 环境。
2. 执行 agents-cli setup：该命令会引导用户完成 Google Cloud CLI 安装检查、gcloud auth application-default login、默认项目与区域设置。
3. 执行 agents-cli update：在已有安装上自更新到最新版本。注意：在非 UTF-8 的 Windows 控制台中，agents-cli update 可能触发 Python 的 UnicodeDecodeError 堆栈，这是社区反馈最多的安装类问题之一 资料来源：src/google/agents/cli/setup/cmd_update.py:1-120。

认证流程由 src/google/agents/cli/auth.py 封装，统一通过 Application Default Credentials (ADC) 与 Google Cloud / Vertex AI 通信 资料来源：src/google/agents/cli/auth.py:1-80。

已知安装痛点（社区反馈）

核心命令与生命周期

CLI 设计围绕一条端到端生命周期展开，官方在 docs/src/guide/lifecycle.md 中将其形式化为：

spec → scaffold → build → evaluate → deploy → publish / observe

该生命周期同时也是社区 #47、#48、#49 号提议中"可选 AISP 机器可读契约"的目标骨架 资料来源：docs/src/guide/lifecycle.md:40-90。

scaffold create 接受本地或远程 Git 模板，但需注意：远程模板会被克隆并读取其中的 agents-cli-manifest.yaml，目前对 settings.agent_directory 缺少路径校验，存在任意写入风险（社区 #50） 资料来源：src/google/agents/cli/main.py:80-160。

deploy 子命令支持多种目标：agent_runtime（Vertex AI Agent Engine）、cloud_run、gke。agent_runtime 模式下构建用的 Python 版本历史上取自 CLI 自身解释器，社区 #36 反映了该行为与项目实际 Python 需求不一致的问题 资料来源：src/google/agents/cli/main.py:200-280。

生命周期中的常见陷阱

除安装阶段问题外，生命周期中也有若干已被记录的"踩坑点"：

• A2A + Agent Runtime 区域错位：使用 adk_a2a 模板并部署到非 us-central1 区域时，Agent Card 的 url 仍被硬编码为 us-central1（社区 #28） 资料来源：src/google/agents/cli/main.py:160-200。
• A2A 运行时未完全托管：脚手架生成的 A2A Agent 默认使用内存版 session/task store，而非托管服务（社区 #5）。
• infra 缺少默认 dry-run：terraform apply 会直接执行，社区 #4 建议默认改为 terraform plan 以提升安全性。
• ADK-Java / TypeScript / Go 多语言支持不足：社区 #9 提出 Skill 尚未覆盖 adk-java 等多语言 Agent 的代码生成模式。

这些问题共同反映出：CLI 与 Skill 已构成相对完整的生命周期骨架，但在跨平台体验、跨语言支持与安全默认行为上仍有演进空间。建议在落地生产前，先以小规模项目跑通 scaffold → eval → deploy 三段，验证区域、Python 版本与模板来源后再批量扩展。

概述与设计目标

agents-cli 的 skills/ 目录并非 CLI 自身的运行时模块，而是一套面向 AI 编码 Agent（如 Gemini CLI、Claude Code 等）的可加载指令集。每个子目录下的 SKILL.md 是一份结构化提示词，描述在某个 agent 构建阶段应当遵循的流程、最佳实践与 agents-cli 命令调用方式。资料来源：skills/README.md:1-30

技能体系的核心目标是让外部编码 Agent 在「不重新学习 agents-cli 命令行」的前提下，通过加载技能自动获得与官方一致的代理构建工作流。Skills 之间通过共享生命周期约定互相串联，避免每个 Agent 各自为政。资料来源：skills/google-agents-cli-workflow/SKILL.md:1-25

技能清单与生命周期映射

agents-cli 当前提供至少五个面向不同阶段的技能，覆盖从需求规范到上线观测的完整链路：

资料来源：skills/README.md:31-80、skills/google-agents-cli-workflow/SKILL.md:10-40

各阶段技能的关键约定

工作流技能（workflow） 是入口技能，它向编码 Agent 明确：在每个阶段应当按需加载对应 phase 技能，而不是把所有命令铺开给 Agent。这种「按需加载」机制能显著减少上下文窗口占用。资料来源：skills/google-agents-cli-workflow/SKILL.md:26-55

ADK 代码技能（adk-code） 聚焦 ADK Python 模式（LlmAgent、SequentialAgent、ParallelAgent、LoopAgent、工具与子代理），并指导在 scaffold create 生成的项目结构上修改。它也覆盖状态、回调与事件，是 #9（adk-java 支持）等社区扩展诉求的参照基线。资料来源：skills/google-agents-cli-adk-code/SKILL.md:1-50

部署技能（deploy） 是当前社区讨论最密集的技能。它要求编码 Agent 在执行 agents-cli deploy 前先核对：Python 版本（呼应 #36 中 CLI 自身 Python 与项目 Python 不一致导致的 litellm 失败）、部署区域（呼应 #28 中 adk_a2a 卡片被强制盖戳 us-central1 的问题）、.gcloudignore/.gitignore 打包策略（v1.0.0 行为），以及 infra 子命令默认 terraform plan 而非 apply 的安全默认（呼应 #4）。资料来源：skills/google-agents-cli-deploy/SKILL.md:30-90

评估技能（eval） 强调 EvalCase.session_input.state 用法（呼应 #52 中按评估用例初始化 ADK 会话状态的诉求），并要求评估流程产出可追溯的失败分析，与 AISP 评估质量契约（#49）的设计哲学一致。资料来源：skills/google-agents-cli-eval/SKILL.md:20-60

观测技能（observability） 是相对独立的一块，约定在部署完成后如何打开结构化日志、Trace 关联与监控告警，是 AISP 部署就绪契约（#48）中 observe 阶段的具体落点。资料来源：skills/google-agents-cli-observability/SKILL.md:1-40

社区驱动的演进方向

多项提案显示，社区希望 Skills 体系从「过程性提示词」演进为「可机读的契约（Contract）」：

• #47 提出 spec → scaffold → build → eval → deploy → observe 的全生命周期 AISP 契约，与 workflow 技能描述的流程高度同构。
• #48、#49 分别提议为 deploy 与 eval 增加部署就绪与评估质量契约，复用现有技能中的检查项。
• #44 建议在 workflow、deploy、adk-code 等技能中加入「先核验官方文档再写代码」的前置步骤，以减少基于过时文档生成的缺陷代码。

这些讨论的共同指向是：Skills 将从单段 Markdown 提示词升级为可被编码 Agent 与外部工具共同校验的声明性规范。资料来源：skills/README.md:60-90

flowchart LR
  A[workflow 技能] --> B[adk-code 技能]
  A --> C[eval 技能]
  B --> D[deploy 技能]
  C --> D
  D --> E[observability 技能]
  A -.按需加载.-> B
  A -.按需加载.-> C
  A -.按需加载.-> D
  A -.按需加载.-> E

资料来源：skills/google-agents-cli-workflow/SKILL.md:26-55、skills/README.md:31-80

总体职责与命令分组

scaffold 是一个命令分组（group），由 cmd_scaffold_group.py 注册到主 CLI，下辖三类核心子命令：create、enhance、upgrade。create 用于从模板生成新项目；enhance 用于向已有项目注入额外片段（functions、tools、CICD 等）；upgrade 用于将已有项目与上游模板对齐升级。其核心抽象是「模板（Template）」，由 utils/template.py 定义数据结构与本地渲染逻辑，由 utils/remote_template.py 负责拉取并校验远端模板仓库，从而支持本地打包模板与远程 Git 仓库模板两种来源。资料来源：src/google/agents/cli/scaffold/cmd_scaffold_group.py:1-80

`create`：从模板生成新项目

commands/create.py 是 scaffold create 的实现入口。典型用法包含三个关键参数：

• <project-name>：目标项目目录名；
• --agent <template>：模板标识，可以是内置模板名（如 adk、adk_a2a、tool 等），也可以是远程 Git 仓库地址；
• --deployment-target：可选的部署目标（如 agent_runtime、cloud_run、gke），用于在生成阶段调整与目标运行时相关的配置（例如 Agent Card url、Vertex location、内存会话存储等）。

执行流程大致分为：参数解析 → 模板解析（本地优先，未命中则调用 remote_template 克隆远端仓库）→ 读取 agents-cli-manifest.yaml → 根据 manifest 中的 settings.agent_directory 等字段渲染目录结构 → 写入目标路径。资料来源：src/google/agents/cli/scaffold/commands/create.py:1-200

模板数据结构与渲染

utils/template.py 抽象了一个模板对象，承载模板自身的元数据以及「对目标项目应做哪些文件/目录替换」的配置。模板内部通常包含一个 agents-cli-manifest.yaml，声明 agent 目录、占位符、可选注入点以及与部署目标的耦合点。渲染时，模板占位符（如 ${project_name}、模型 ID、Google Cloud 区域等）会被替换为来自 CLI 参数与本地上下文的实际值。这一抽象是 create 与 upgrade 共享的，因此升级流程本质上是一次「以新模板重新渲染、对已有项目做 diff 应用」的过程。资料来源：src/google/agents/cli/scaffold/utils/template.py:1-150

远端模板：克隆、校验与已知风险

utils/remote_template.py 负责把 --agent <git-url> 形式指定的远端模板拉取到本地临时目录，然后交给 template.py 进行解析。该模块需要承担「克隆 → 定位 manifest → 在临时目录展开」的职责。社区中已报告一个高严重度安全问题（issue #50）：当使用远程模板时，manifest 中的 settings.agent_directory 字段未被严格校验，可能允许 .. 等路径片段越界，从而把文件写到目标项目之外的位置。该问题目前已触发对远端模板路径校验的修复讨论，新版 manifest 解析需要在落地前对 agent_directory 做规范化与越界检查。资料来源：src/google/agents/cli/scaffold/utils/remote_template.py:1-180，社区反馈：issue #50

此外，adk_a2a 模板在 --deployment-target agent_runtime 路径下存在一个老问题：构建 A2A Agent 时未在 Vertex AI SDK 中指定 region，导致 Agent Card 的 url 字段被错误地戳上 us-central1（issue #28）。修复方向是在 create 阶段将用户传入的 region 通过环境变量或代码注入到模板渲染结果中。

`enhance` 与 `upgrade`：在已有项目上叠加能力

commands/enhance.py 提供对已有项目进行「能力注入」的入口，例如加入新的 tool、sub-agent、CICD 模板等；操作逻辑通常会以注入脚本或追加片段的形式复用同一套模板引擎。commands/upgrade.py 则面向已存在项目，将其与目标模板的新版本对齐，常见动作包括同步 manifest 字段、补齐缺失文件、刷新占位符。两者共同遵循「template.py 渲染 + manifest 驱动」的设计，因此对模板作者而言，编写一个既能用于 create 也能用于 enhance/upgrade 的 manifest 是关键。资料来源：src/google/agents/cli/scaffold/commands/enhance.py:1-120，src/google/agents/cli/scaffold/commands/upgrade.py:1-120

命令与模板的关系

下表汇总了 scaffold 各子命令与模板模块的协作关系：

cmd_scaffold_group.py 通过 Click 风格的分组注册将上述三者挂在 agents-cli scaffold 之下，使得 agents-cli scaffold create|enhance|upgrade 形成统一的用户面。资料来源：src/google/agents/cli/scaffold/cmd_scaffold_group.py:1-80

与部署的关系及 v1.0.0 变更

虽然 scaffold 本身只负责生成与升级项目骨架，但其产物会直接影响后续 agents-cli deploy 的行为：模板里写入的 Python 版本、依赖列表、Agent Engine 入口文件等会在部署阶段被消费。v1.0.0 GA 发布说明中明确指出，对 Agent Runtime 与 Cloud Run 的重部署现在会保留原有部署 spec，并开始遵循 .gcloudignore / .gitignore 打包源文件——这两项行为变化都要求 scaffold 生成的项目具备清晰的 manifest 与忽略文件约定，以避免部署阶段打包到不期望的内容。建议在使用 scaffold create 后，保留并审阅模板生成的 .gcloudignore 与 agents-cli-manifest.yaml，以保持脚手架与部署链路的一致性。资料来源：v1.0.0 Release Notes

概述

agents-cli 将 agent 的生命周期抽象为可机读、可复现的阶段序列：spec → scaffold → build → evaluate → deploy → publish → observe。其中"评估—部署—发布—可观测性"四个阶段由 agents-cli eval、agents-cli deploy 与相关的 publish/observe 子命令承载，构成了从模型行为验证到生产运行观测的完整闭环。

整个工作流强调三件事：(1) 可重复性——评估数据集与部署规格与源代码一同版本化；(2) 可观测性——trace、指标与日志贯穿评估与生产；(3) 可回滚性——重新部署会保留上一次部署的规格，而非重置未指定字段（v1.0.0 行为）。AISP 提案（详见 issue #47、#48、#49）进一步建议引入可选的机器可读契约来约束这些阶段。

资料来源：src/google/agents/cli/eval/cmd_generate.py:1-40，src/google/agents/cli/deploy/cmd_deploy.py:1-50

评估子命令（Eval）

agents-cli eval 是一组子命令的集合，覆盖"生成用例 → 评分 → 失败分析 → 数据集合成 → 提示优化"的完整评估循环。

生成与每案会话状态（#52）

社区反馈希望在 eval generate 中支持 EvalCase.session_input.state，以在推理前为每个评测用例注入 ADK session 状态，例如模拟多轮上下文或受角色限制的会话前提。该能力由 cmd_generate.py 中负责组装 EvalCase 的逻辑承担，目前通过 ADK 原生 schema 透传。

资料来源：src/google/agents/cli/eval/cmd_generate.py:80-160

评分、数据集合成与优化

eval grade 通过可插拔的评判器（rubric 或 model-based grader）产出 0–1 分或分类标签；eval analyze 将同一维度的失败聚合为可操作的修复建议；eval dataset synth 利用 agent 自动派生新的边缘用例；eval optimize 则把分数与失败原因映射回 prompt 配置的局部编辑，以求迭代收敛。

资料来源：src/google/agents/cli/eval/cmd_grade.py:30-120，src/google/agents/cli/eval/cmd_analyze.py:20-90，src/google/agents/cli/eval/cmd_dataset.py:15-70，src/google/agents/cli/eval/cmd_optimize.py:25-110

评估质量契约（#49，AISP 提案）

AISP 提案建议引入可选的机器可读评估质量契约，覆盖：数据集覆盖率（如类别、难度分布）、评分一致性、失败分析完整度以及优化轨迹可追溯性。该契约以 YAML/JSON 形式位于评估目录，与 eval grade 的输出交叉校验。

flowchart LR
  A[EvalCase + session_input.state] --> B[eval generate]
  B --> C[推理记录]
  C --> D[eval grade]
  D --> E[分数报告]
  E --> F[eval analyze]
  F --> G[失败分桶]
  G --> H[eval optimize]
  H --> I[回写 prompt]
  I --> B

部署子命令（Deploy）

agents-cli deploy 通过 --deployment-target 区分三种目标：

• agent_runtime：Vertex AI Agent Engine。该路径在 v1.0.0 中保留了已有的部署规格，并按 .gcloudignore/.gitignore 过滤上传的源码包。已知问题包括：用 CLI 自身的 Python 版本决定运行时版本（#36），以及 adk_a2a 模板在非 us-central1 区域会硬编码 us-central1 作为 Agent Card 的 URL 区域（#28）。
• cloud_run：基于 Cloud Run 的容器化部署，同样在 v1.0.0 中保留已有 spec。
• GKE / 其他：通过通用的容器镜像构建路径。

cmd_deploy.py 负责解析部署规格、与目标平台 SDK（如 vertexai._genai.AgentEngine）交互并上传源代码包。社区请求（#45）补充 --python-version 选项，以便与依赖所要求的 Python 版本对齐。

agents-cli deploy <project> --deployment-target agent_runtime [--region <r>] [--python-version <v>]

资料来源：src/google/agents/cli/deploy/cmd_deploy.py:60-200，src/google/agents/cli/deploy/cmd_deploy.py:200-320

发布与部署就绪契约（#48，AISP 提案）

AISP 提案建议在 deploy 之前插入可选的发布就绪校验，覆盖：评估必须通过、变更需审批人签字、可回滚策略已配置、可观测性 sink 已接入。cmd_publish.py 充当这些门禁的执行器，决定是否允许进入生产替换。

资料来源：src/google/agents/cli/deploy/cmd_publish.py:20-140

可观测性与工作流集成

可观测性子命令（agents-cli observe）使用与评估共享的 trace 模型，以便把评估阶段的失败 trace 与生产阶段的实际 trace 放进同一张对比视图。AISP 提案（#47）建议把 observe 作为闭环的最后一步，把生产 trace 反馈到下一轮的 eval dataset synth，从而让数据集随真实漂移持续演化。

资料来源：src/google/agents/cli/observability/cmd_observe.py:30-150

已知边界与社区关注点

• #52：eval generate 中对每案 ADK session 状态的一等支持。
• #36：agent_runtime 构建版本跟随 CLI 自身的 Python（sys.version_info），与项目脱节。
• #28：adk_a2a 的 A2A Agent Card URL 在非 us-central1 区域被错误地硬编码。
• #45：在 deploy 中暴露 --python-version 选项。
• #5：agent_runtime 上 A2A scaffold 使用了内存 session / task store，未接入托管服务。
• #49、#48、#47：分别为 eval、deploy、整体生命周期引入可选 AISP 契约。

资料来源：src/google/agents/cli/eval/cmd_generate.py:1-40，src/google/agents/cli/deploy/cmd_deploy.py:1-50

Pitfall Log / 踩坑日志

项目：google/agents-cli

摘要：发现 40 个潜在踩坑项，其中 15 个为 high/blocking；最高优先级：安装坑 - 来源证据：Add a proactive "verify against official docs" step before code generation。

1. 安装坑 · 来源证据：Add a proactive "verify against official docs" step before code generation

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add a proactive "verify against official docs" step before code generation
• 对用户的影响：可能影响升级、迁移或版本选择。
• 证据：community_evidence:github | https://github.com/google/agents-cli/issues/44 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

2. 安装坑 · 来源证据：Deployment fails to resolve the `litellm` package version and fails

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Deployment fails to resolve the litellm package version and fails
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/google/agents-cli/issues/42 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

3. 安装坑 · 来源证据：Doc link "Agent Garden" is incorrect

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Doc link "Agent Garden" is incorrect
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/google/agents-cli/issues/29 | 来源类型 github_issue 暴露的待验证使用条件。

4. 安装坑 · 来源证据：Support for writing code using ADK-Java patterns (also Typescript, Go)

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Support for writing code using ADK-Java patterns (also Typescript, Go)
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/google/agents-cli/issues/9 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

5. 安装坑 · 来源证据：`adk_a2a` (agent_runtime) scaffold does not set Vertex location before building the A2A agent → card URL stamped with u…

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：adk_a2a (agent_runtime) scaffold does not set Vertex location before building the A2A agent → card URL stamped with us-central1 for non-us-central1 deploys
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/google/agents-cli/issues/28 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

6. 安装坑 · 来源证据：repo init with cicd, for a2a ,adk , tool, and sub agent init.

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：repo init with cicd, for a2a ,adk , tool, and sub agent init.
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/google/agents-cli/issues/39 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

7. 安装坑 · 来源证据：v0.5.0: deploy to agent_runtime builds on the CLI's own Python (sys.version_info), not the project's — fails when a dep…

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.5.0: deploy to agent_runtime builds on the CLI's own Python (sys.version_info), not the project's — fails when a dependency lacks a wheel for that version (…
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/google/agents-cli/issues/36 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

8. 配置坑 · 来源证据：Add an init command to create agents-cli-manifest.yaml for existing ADK projects

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Add an init command to create agents-cli-manifest.yaml for existing ADK projects
• 对用户的影响：可能影响升级、迁移或版本选择。
• 证据：community_evidence:github | https://github.com/google/agents-cli/issues/25 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

9. 配置坑 · 来源证据：agents-cli update floods console with Python UnicodeDecodeError tracebacks on non-UTF-8 Windows consoles

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：agents-cli update floods console with Python UnicodeDecodeError tracebacks on non-UTF-8 Windows consoles
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/google/agents-cli/issues/37 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

10. 安全/权限坑 · 失败模式：security_permissions: Add an optional AISP deployment readiness contract for eval, approval, deploy, rollback, and...

• 严重度：high
• 证据强度：source_linked
• 发现：Developers should check this security_permissions risk before relying on the project: Add an optional AISP deployment readiness contract for eval, approval, deploy, rollback, and observability gates
• 对用户的影响：Developers may expose sensitive permissions or credentials: Add an optional AISP deployment readiness contract for eval, approval, deploy, rollback, and observability gates
• 证据：failure_mode_cluster:github_issue | https://github.com/google/agents-cli/issues/48 | Add an optional AISP deployment readiness contract for eval, approval, deploy, rollback, and observability gates

11. 安全/权限坑 · 失败模式：security_permissions: Support Antigravity SDK as a first-class agent implementation framework

• 严重度：high
• 证据强度：source_linked
• 发现：Developers should check this security_permissions risk before relying on the project: Support Antigravity SDK as a first-class agent implementation framework
• 对用户的影响：Developers may expose sensitive permissions or credentials: Support Antigravity SDK as a first-class agent implementation framework
• 证据：failure_mode_cluster:github_issue | https://github.com/google/agents-cli/issues/41 | Support Antigravity SDK as a first-class agent implementation framework

12. 安全/权限坑 · 来源证据：Provide a bundled GUI client or a standalone desktop app instead of relying on heavy CLI setups

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Provide a bundled GUI client or a standalone desktop app instead of relying on heavy CLI setups
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/google/agents-cli/issues/21 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

13. 安全/权限坑 · 来源证据：Python version option for agents-cli deploy

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Python version option for agents-cli deploy
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/google/agents-cli/issues/45 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

14. 安全/权限坑 · 来源证据：Support Antigravity SDK as a first-class agent implementation framework

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Support Antigravity SDK as a first-class agent implementation framework
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/google/agents-cli/issues/41 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

15. 安全/权限坑 · 来源证据：run --mode a2a: agent-card transport endpoint is not pinned to --url; bearer token can be sent to a card-specified host

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：run --mode a2a: agent-card transport endpoint is not pinned to --url; bearer token can be sent to a card-specified host
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/google/agents-cli/issues/46 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

16. 安装坑 · 失败模式：installation: Add an optional AISP lifecycle contract for spec → scaffold → build → eval → deploy → observe

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Add an optional AISP lifecycle contract for spec → scaffold → build → eval → deploy → observe
• 对用户的影响：Developers may fail before the first successful local run: Add an optional AISP lifecycle contract for spec → scaffold → build → eval → deploy → observe
• 证据：failure_mode_cluster:github_issue | https://github.com/google/agents-cli/issues/47 | Add an optional AISP lifecycle contract for spec → scaffold → build → eval → deploy → observe

17. 安装坑 · 失败模式：installation: Deployment fails to resolve the `litellm` package version and fails

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Deployment fails to resolve the litellm package version and fails
• 对用户的影响：Developers may fail before the first successful local run: Deployment fails to resolve the litellm package version and fails
• 证据：failure_mode_cluster:github_issue | https://github.com/google/agents-cli/issues/42 | Deployment fails to resolve the litellm package version and fails

18. 安装坑 · 失败模式：installation: Path traversal in remote-template scaffolding → arbitrary file write (agents-cli scaffold cre...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Path traversal in remote-template scaffolding → arbitrary file write (agents-cli scaffold create --agent <remote>)
• 对用户的影响：Developers may fail before the first successful local run: Path traversal in remote-template scaffolding → arbitrary file write (agents-cli scaffold create --agent <remote>)
• 证据：failure_mode_cluster:github_issue | https://github.com/google/agents-cli/issues/50 | Path traversal in remote-template scaffolding → arbitrary file write (agents-cli scaffold create --agent <remote>)

19. 安装坑 · 失败模式：installation: Provide a bundled GUI client or a standalone desktop app instead of relying on heavy CLI setups

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Provide a bundled GUI client or a standalone desktop app instead of relying on heavy CLI setups
• 对用户的影响：Developers may fail before the first successful local run: Provide a bundled GUI client or a standalone desktop app instead of relying on heavy CLI setups
• 证据：failure_mode_cluster:github_issue | https://github.com/google/agents-cli/issues/21 | Provide a bundled GUI client or a standalone desktop app instead of relying on heavy CLI setups

20. 安装坑 · 失败模式：installation: Python version option for agents-cli deploy

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Python version option for agents-cli deploy
• 对用户的影响：Developers may fail before the first successful local run: Python version option for agents-cli deploy
• 证据：failure_mode_cluster:github_issue | https://github.com/google/agents-cli/issues/45 | Python version option for agents-cli deploy

21. 安装坑 · 失败模式：installation: run --mode a2a: agent-card transport endpoint is not pinned to --url; bearer token can be sen...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: run --mode a2a: agent-card transport endpoint is not pinned to --url; bearer token can be sent to a card-specified host
• 对用户的影响：Developers may fail before the first successful local run: run --mode a2a: agent-card transport endpoint is not pinned to --url; bearer token can be sent to a card-specified host
• 证据：failure_mode_cluster:github_issue | https://github.com/google/agents-cli/issues/46 | run --mode a2a: agent-card transport endpoint is not pinned to --url; bearer token can be sent to a card-specified host

22. 安装坑 · 失败模式：installation: v0.5.0: deploy to agent_runtime builds on the CLI's own Python (sys.version_info), not the pr...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v0.5.0: deploy to agent_runtime builds on the CLI's own Python (sys.version_info), not the project's — fails when a dependency lacks a wheel for that version (e.g. Python 3.14 +...
• 对用户的影响：Developers may fail before the first successful local run: v0.5.0: deploy to agent_runtime builds on the CLI's own Python (sys.version_info), not the project's — fails when a dependency lacks a wheel for that version (e.g. Python 3.14 +...
• 证据：failure_mode_cluster:github_issue | https://github.com/google/agents-cli/issues/36 | v0.5.0: deploy to agent_runtime builds on the CLI's own Python (sys.version_info), not the project's — fails when a dependency lacks a wheel for that version (e.g. Python 3.14 +...

23. 安装坑 · 来源证据：Add an optional AISP lifecycle contract for spec → scaffold → build → eval → deploy → observe

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add an optional AISP lifecycle contract for spec → scaffold → build → eval → deploy → observe
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/google/agents-cli/issues/47 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

24. 安装坑 · 来源证据：Bug: Replicas low on memory on workerpool0 during data ingestion pipeline

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Bug: Replicas low on memory on workerpool0 during data ingestion pipeline
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/google/agents-cli/issues/43 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

25. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/google/agents-cli | host_targets=claude_code, claude, chatgpt

26. 配置坑 · 失败模式：configuration: Add a proactive "verify against official docs" step before code generation

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: Add a proactive "verify against official docs" step before code generation
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Add a proactive "verify against official docs" step before code generation
• 证据：failure_mode_cluster:github_issue | https://github.com/google/agents-cli/issues/44 | Add a proactive "verify against official docs" step before code generation

27. 配置坑 · 失败模式：configuration: Add an init command to create agents-cli-manifest.yaml for existing ADK projects

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: Add an init command to create agents-cli-manifest.yaml for existing ADK projects
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Add an init command to create agents-cli-manifest.yaml for existing ADK projects
• 证据：failure_mode_cluster:github_issue | https://github.com/google/agents-cli/issues/25 | Add an init command to create agents-cli-manifest.yaml for existing ADK projects

28. 配置坑 · 失败模式：configuration: Add an optional AISP eval quality contract for dataset coverage, grading, failure analysis, a...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: Add an optional AISP eval quality contract for dataset coverage, grading, failure analysis, and optimization traces
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Add an optional AISP eval quality contract for dataset coverage, grading, failure analysis, and optimization traces
• 证据：failure_mode_cluster:github_issue | https://github.com/google/agents-cli/issues/49 | Add an optional AISP eval quality contract for dataset coverage, grading, failure analysis, and optimization traces

29. 配置坑 · 失败模式：configuration: `adk_a2a` (agent_runtime) scaffold does not set Vertex location before building the A2A agent...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: adk_a2a (agent_runtime) scaffold does not set Vertex location before building the A2A agent → card URL stamped with us-central1 for non-us-central1 deploys
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: adk_a2a (agent_runtime) scaffold does not set Vertex location before building the A2A agent → card URL stamped with us-central1 for non-us-central1 deploys
• 证据：failure_mode_cluster:github_issue | https://github.com/google/agents-cli/issues/28 | adk_a2a (agent_runtime) scaffold does not set Vertex location before building the A2A agent → card URL stamped with us-central1 for non-us-central1 deploys

30. 配置坑 · 失败模式：configuration: repo init with cicd, for a2a ,adk , tool, and sub agent init.

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: repo init with cicd, for a2a ,adk , tool, and sub agent init.
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: repo init with cicd, for a2a ,adk , tool, and sub agent init.
• 证据：failure_mode_cluster:github_issue | https://github.com/google/agents-cli/issues/39 | repo init with cicd, for a2a ,adk , tool, and sub agent init.

31. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/google/agents-cli | README/documentation is current enough for a first validation pass.

32. 运行坑 · 失败模式：runtime: agents-cli update floods console with Python UnicodeDecodeError tracebacks on non-UTF-8 Windo...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this runtime risk before relying on the project: agents-cli update floods console with Python UnicodeDecodeError tracebacks on non-UTF-8 Windows consoles
• 对用户的影响：Developers may hit a documented source-backed failure mode: agents-cli update floods console with Python UnicodeDecodeError tracebacks on non-UTF-8 Windows consoles
• 证据：failure_mode_cluster:github_issue | https://github.com/google/agents-cli/issues/37 | agents-cli update floods console with Python UnicodeDecodeError tracebacks on non-UTF-8 Windows consoles

33. 运行坑 · 运行可能依赖外部服务

• 严重度：medium
• 证据强度：source_linked
• 发现：项目说明出现 external service/cloud/webhook/database 等运行依赖关键词。
• 对用户的影响：本地安装成功不等于能力可用，外部服务不可用会阻断体验。
• 证据：packet_text.keyword_scan | https://github.com/google/agents-cli | matched external service / cloud / webhook / database keyword

34. 维护坑 · 失败模式：migration: Support per-eval-case ADK session state in `agents-cli eval generate`

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this migration risk before relying on the project: Support per-eval-case ADK session state in agents-cli eval generate
• 对用户的影响：Developers may hit a documented source-backed failure mode: Support per-eval-case ADK session state in agents-cli eval generate
• 证据：failure_mode_cluster:github_issue | https://github.com/google/agents-cli/issues/52 | Support per-eval-case ADK session state in agents-cli eval generate

35. 维护坑 · 来源证据：Support per-eval-case ADK session state in `agents-cli eval generate`

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Support per-eval-case ADK session state in agents-cli eval generate
• 对用户的影响：可能影响升级、迁移或版本选择。
• 证据：community_evidence:github | https://github.com/google/agents-cli/issues/52 | 来源类型 github_issue 暴露的待验证使用条件。

36. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/google/agents-cli | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/google/agents-cli | no_demo; severity=medium

38. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/google/agents-cli | no_demo; severity=medium

39. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/google/agents-cli | issue_or_pr_quality=unknown

40. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/google/agents-cli | release_recency=unknown