# https://github.com/google/agents-cli 项目说明书

生成时间：2026-07-05 16:01:30 UTC

## 目录

- [项目概览、安装与生命周期](#page-1)
- [Skills 技能体系与编码 Agent 集成](#page-2)
- [脚手架命令与项目模板](#page-3)
- [评估、部署、发布与可观测性工作流](#page-4)

<a id='page-1'></a>

## 项目概览、安装与生命周期

### 相关页面

相关主题：[Skills 技能体系与编码 Agent 集成](#page-2), [脚手架命令与项目模板](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/google/agents-cli/blob/main/README.md)
- [src/google/agents/cli/main.py](https://github.com/google/agents-cli/blob/main/src/google/agents/cli/main.py)
- [src/google/agents/cli/auth.py](https://github.com/google/agents-cli/blob/main/src/google/agents/cli/auth.py)
- [src/google/agents/cli/setup/cmd_setup.py](https://github.com/google/agents-cli/blob/main/src/google/agents/cli/setup/cmd_setup.py)
- [src/google/agents/cli/setup/cmd_update.py](https://github.com/google/agents-cli/blob/main/src/google/agents/cli/setup/cmd_update.py)
- [docs/src/guide/lifecycle.md](https://github.com/google/agents-cli/blob/main/docs/src/guide/lifecycle.md)
- [docs/src/guide/install.md](https://github.com/google/agents-cli/blob/main/docs/src/guide/install.md)
</details>

# 项目概览、安装与生命周期

## 项目概览

`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]()。

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

| 问题编号 | 描述 | 影响 |
| --- | --- | --- |
| #21 | Windows 上需手动管理 Python、gcloud、ADC，PATH 处理繁琐 | 新用户体验 |
| #36 | `deploy --deployment-target agent_runtime` 使用 CLI 自身的 Python 版本构建 | 依赖兼容性 |
| #37 | Windows 控制台非 UTF-8 时 `update` 报 `UnicodeDecodeError` | 升级体验 |

## 核心命令与生命周期

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

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

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

| 阶段 | 对应命令 | 关键能力 |
| --- | --- | --- |
| spec | 与 IDE Skill 对话 | 自然语言需求 → 设计规格 |
| scaffold | `agents-cli scaffold create <project> --agent <template>` | 拉取模板生成项目骨架 |
| build | 由 Skill 驱动的 `google-agents-cli-adk-code` | 按最佳实践生成 ADK/A2A/Java 代码 |
| evaluate | `agents-cli eval generate / grade / dataset synth` | 生成用例、评分、合成数据集 |
| deploy | `agents-cli deploy --deployment-target {agent_runtime, cloud_run, gke}` | 一键部署到目标运行时 |
| observe | `agents-cli infra` 与 Cloud 监控 | Terraform / 监控集成 |

`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 版本与模板来源后再批量扩展。

---

<a id='page-2'></a>

## Skills 技能体系与编码 Agent 集成

### 相关页面

相关主题：[项目概览、安装与生命周期](#page-1), [脚手架命令与项目模板](#page-3), [评估、部署、发布与可观测性工作流](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [skills/README.md](https://github.com/google/agents-cli/blob/main/skills/README.md)
- [skills/google-agents-cli-workflow/SKILL.md](https://github.com/google/agents-cli/blob/main/skills/google-agents-cli-workflow/SKILL.md)
- [skills/google-agents-cli-adk-code/SKILL.md](https://github.com/google/agents-cli/blob/main/skills/google-agents-cli-adk-code/SKILL.md)
- [skills/google-agents-cli-deploy/SKILL.md](https://github.com/google/agents-cli/blob/main/skills/google-agents-cli-deploy/SKILL.md)
- [skills/google-agents-cli-eval/SKILL.md](https://github.com/google/agents-cli/blob/main/skills/google-agents-cli-eval/SKILL.md)
- [skills/google-agents-cli-observability/SKILL.md](https://github.com/google/agents-cli/blob/main/skills/google-agents-cli-observability/SKILL.md)
</details>

# Skills 技能体系与编码 Agent 集成

## 概述与设计目标

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` 当前提供至少五个面向不同阶段的技能，覆盖从需求规范到上线观测的完整链路：

| 技能名称 | 阶段 | 主要职责 | 对应 CLI 命令族 |
| --- | --- | --- | --- |
| `google-agents-cli-workflow` | 总览/编排 | 编排 `spec → scaffold → build → eval → deploy → observe` 整体流程 | 全部子命令 |
| `google-agents-cli-adk-code` | 构建 | 指导 ADK Python 代码生成、组件组合、状态管理 | `scaffold`、`build` |
| `google-agents-cli-deploy` | 上线 | 评估部署目标（Agent Runtime、Cloud Run、GKE），处理 CI/CD、密钥、服务账号 | `deploy`、`infra` |
| `google-agents-cli-eval` | 评估 | 数据集生成、评分、失败分析、优化追踪 | `eval generate`、`eval grade`、`eval dataset synth` |
| `google-agents-cli-observability` | 观测 | 接入 Cloud Logging / Cloud Trace / Cloud Monitoring | `deploy` 后的运维 |

资料来源：[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]()

```mermaid
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]()

---

<a id='page-3'></a>

## 脚手架命令与项目模板

### 相关页面

相关主题：[Skills 技能体系与编码 Agent 集成](#page-2), [评估、部署、发布与可观测性工作流](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/google/agents/cli/scaffold/cmd_scaffold_group.py](https://github.com/google/agents-cli/blob/main/src/google/agents/cli/scaffold/cmd_scaffold_group.py)
- [src/google/agents/cli/scaffold/commands/create.py](https://github.com/google/agents-cli/scaffold/commands/create.py)
- [src/google/agents/cli/scaffold/commands/enhance.py](https://github.com/google/agents-cli/scaffold/commands/enhance.py)
- [src/google/agents/cli/scaffold/commands/upgrade.py](https://github.com/google/agents-cli/scaffold/commands/upgrade.py)
- [src/google/agents/cli/scaffold/utils/template.py](https://github.com/google/agents/cli/scaffold/utils/template.py)
- [src/google/agents/cli/scaffold/utils/remote_template.py](https://github.com/google/agents-cli/scaffold/utils/remote_template.py)
</details>

# 脚手架命令与项目模板

`agents-cli scaffold` 是 agents-cli 提供的项目脚手架子系统，用于从预定义模板快速生成符合 Google ADK / Agent Runtime / A2A 等多种形态的智能体项目骨架，并通过 `enhance` 与 `upgrade` 子命令在已有项目上叠加额外能力或同步模板变更。

## 总体职责与命令分组

`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` 各子命令与模板模块的协作关系：

| 子命令 | 入口文件 | 主要协作模块 | 典型用途 |
| --- | --- | --- | --- |
| `scaffold create` | `commands/create.py` | `utils/template.py`、`utils/remote_template.py` | 从模板生成全新项目 |
| `scaffold enhance` | `commands/enhance.py` | `utils/template.py` | 在已有项目注入新能力 |
| `scaffold upgrade` | `commands/upgrade.py` | `utils/template.py` | 将已有项目与模板新版本对齐 |

`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

---

<a id='page-4'></a>

## 评估、部署、发布与可观测性工作流

### 相关页面

相关主题：[Skills 技能体系与编码 Agent 集成](#page-2), [脚手架命令与项目模板](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/google/agents/cli/eval/cmd_generate.py](https://github.com/google/agents-cli/blob/main/src/google/agents/cli/eval/cmd_generate.py)
- [src/google/agents/cli/eval/cmd_grade.py](https://github.com/google/agents-cli/blob/main/src/google/agents/cli/eval/cmd_grade.py)
- [src/google/agents/cli/eval/cmd_analyze.py](https://github.com/google/agents-cli/blob/main/src/google/agents/cli/eval/cmd_analyze.py)
- [src/google/agents/cli/eval/cmd_dataset.py](https://github.com/google/agents-cli/blob/main/src/google/agents/cli/eval/cmd_dataset.py)
- [src/google/agents/cli/eval/cmd_optimize.py](https://github.com/google/agents-cli/blob/main/src/google/agents/cli/eval/cmd_optimize.py)
- [src/google/agents/cli/deploy/cmd_deploy.py](https://github.com/google/agents-cli/blob/main/src/google/agents/cli/deploy/cmd_deploy.py)
- [src/google/agents/cli/deploy/cmd_publish.py](https://github.com/google/agents-cli/blob/main/src/google/agents/cli/deploy/cmd_publish.py)
- [src/google/agents/cli/observability/cmd_observe.py](https://github.com/google/agents-cli/blob/main/src/google/agents/cli/observability/cmd_observe.py)
</details>

# 评估、部署、发布与可观测性工作流

## 概述

`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` 是一组子命令的集合，覆盖"生成用例 → 评分 → 失败分析 → 数据集合成 → 提示优化"的完整评估循环。

| 子命令 | 主要职责 | 关键输入 / 输出 |
| --- | --- | --- |
| `eval generate` | 用 agent 跑评测集，产出原始事件与响应 | 输入：数据集；输出：推理记录 |
| `eval grade` | 对推理记录打分 | 输入：推理记录、评分维度；输出：分数报告 |
| `eval analyze` | 聚合失败案例、做错误分析 | 输入：评分报告；输出：分桶失败原因 |
| `eval dataset synth` | 合成新评测用例 | 输入：种子用例；输出：扩展数据集 |
| `eval optimize` | 基于评分结果调优 prompt / 参数 | 输入：分数 + 失败分析；输出：建议或回写 prompt |

### 生成与每案会话状态（#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` 的输出交叉校验。

```mermaid
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 版本对齐。

```text
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]()

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：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

<!-- canonical_name: google/agents-cli; human_manual_source: deepwiki_human_wiki -->