一、项目定位与核心能力

Gemini CLI 是 Google 官方开源的命令行 AI 智能体工具，基于 Apache 2.0 协议发布，将 Gemini 系列大模型能力直接嵌入开发者终端。它不仅支持交互式对话与代码生成，还可通过 Gemini CLI GitHub Action 集成到 PR Review、Issue 分类与自动化工作流中（README.md:10-32）。

其核心项目括：内置工具调用（文件操作、Shell、Web 抓取）、MCP（Model Context Protocol）服务器扩展、GEMINI.md 项目级上下文文件、会话 Checkpointing 断点续传、Token Caching，以及非交互式 Headless 模式（gemini -p "..." --output-format stream-json）用于自动化脚本场景（README.md:60-78）。

认证方面提供两种主要路径：Sign in with Google（OAuth）面向个人开发者与 Code Assist 许可持有者，免费档 60 req/min；以及 API Key 模式（README.md:35-50），由核心包统一处理鉴权。

二、系统架构总览

Gemini CLI 采用 Monorepo 多包架构，按职责拆分以支持 CLI 客户端、SDK、Headless 服务端、IDE 集成与机器人工具等多种运行形态。

graph TB
  User[开发者 / 终端用户] --> CLI[packages/cli<br/>交互式 Ink UI]
  User --> Headless[CLI Headless 模式<br/>脚本与 CI]
  User --> A2A[packages/a2a-server<br/>HTTP + A2A 协议]
  User --> VSCode[packages/vscode-ide-companion<br/>IDE 插件]
  CLI --> Core[packages/core<br/>引擎 / 工具 / 策略]
  Headless --> Core
  A2A --> Core
  VSCode --> Core
  Core --> SDK[packages/sdk<br/>Tool 定义 Zod Schema]
  Core --> MCP[(MCP Servers<br/>~/.gemini/settings.json)]
  Core --> Policies[Policy Engine<br/>policies/*.toml]
  Core --> DevTools[packages/devtools<br/>网络面板]
  Core --> Bot[tools/gemini-cli-bot<br/>仓库健康指标]
  SDK --> Extensions[extensions/<br/>MCP / Skills / 策略]

核心包 packages/core 是引擎中心，集中管理配置、工具注册、消息总线（MessageBus）和策略引擎；packages/cli 负责基于 Ink 的 React 终端 UI 与斜杠命令；packages/a2a-server 将其能力以 Agent-to-Agent HTTP 接口对外暴露（packages/a2a-server/src/http/app.ts:1-40）。

三、主要包与组件

ACP（Agent Communication Protocol）模块位于 packages/cli/src/acp，将 CLI 能力通过 JSON-RPC 暴露给外部编辑器，包含 acpSession.ts（会话管理）、acpCommandHandler.ts（/memory、/init 等斜杠命令拦截）与 acpFileSystemService.ts（受工作区边界限制的文件系统访问）（packages/cli/src/acp/README.md）。

四、扩展与集成机制

MCP 服务器扩展：用户可在 ~/.gemini/settings.json 配置 MCP 服务（如 @github、@slack），CLI 通过 @server 前缀调用。官方提供完整示例，演示 fetch_posts 工具与 poem-writer 提示的注册方式（packages/cli/src/commands/extensions/examples/mcp-server/README.md），测试侧也提供 TestMcpServerBuilder 简化 MCP 客户端测试（packages/test-utils/src/test-mcp-server.ts）。

策略引擎（Policy Engine）：扩展可通过 policies/*.toml 贡献安全规则，例如强制 rm -rf 需用户确认、拒绝 grep 搜索 .env 等敏感文件。安全设计上，扩展提交的 allow 决策与 yolo 模式会被忽略，确保扩展只能加固安全、不可绕过用户确认（packages/cli/src/commands/extensions/examples/policies/README.md）。

五、社区关注点与架构影响

社区反馈集中在几类架构相关痛点：

• 执行安全（Issue #26856）：用户报告 AI 在未充分确认的情况下删除大量文件，请求回滚——这正是策略引擎与可信目录（Trusted Folders）机制的设计动机（README.md）。
• 规划模式（Issue #4666）：呼声最高的特性之一是"Plan Mode"，希望在规划阶段屏蔽写入工具。SDK 的 Tool 声明式结构使工具按类别注册并可被策略拦截，为该特性提供了天然实现位（packages/sdk/src/tool.ts）。
• Agent Skills（Issue #11506）：与 Claude Code 兼容的 Skills 体系请求，与现有 MCP / 扩展机制互补。

See Also

• 工具与扩展开发：packages/sdk/src/tool.ts
• 策略引擎示例：packages/cli/src/commands/extensions/examples/policies/README.md
• ACP 协议模块：packages/cli/src/acp/README.md
• VS Code 集成：packages/vscode-ide-companion/README.md
• 公共路线图：Issue #4191 — Public Roadmap

概述

"Plan Mode"（计划模式）是社区高度期待的一项代理工作流能力，用于在执行复杂代码变更前先由模型产出可审阅的计划，并通过禁用写类工具来避免误操作直接落盘。社区 Issue #4666 中明确提出希望引入该模式：当进入计划模式后，所有写入型工具（如 WriteFile、Edit、replace、run_shell_command 中具有副作用的命令等）都应被策略层拦截，仅保留只读工具，从而让用户在审批前可以审阅计划全文。

资料来源：README.md:18-27

Gemini CLI 的整体代理工作流由工具注册、策略引擎、任务调度与消息总线四部分组成。README.md 提到的"沙箱与安全"以及"可信文件夹"等机制正是为这类受限执行环境提供基础，Plan Mode 实际上是把"受限执行"的思想从文件系统边界下沉到了模型工具调用边界。

工具与策略引擎

代理工作流的最基本单元是 Tool。在 packages/sdk/src/tool.ts 中，ToolDefinition 描述了工具的 name、description 与 Zod 校验的 inputSchema，而 Tool 接口再附加一个 action 回调：

export interface ToolDefinition<T extends z.ZodTypeAny> {
  name: string;
  description: string;
  inputSchema: T;
  sendErrorsToModel?: boolean;
}

资料来源：packages/sdk/src/tool.ts:31-49

策略层则通过 TOML 规则把工具按 tool_name 与命令模式分类处理。扩展示例 packages/cli/src/commands/extensions/examples/policies/README.md 展示了 policies/*.toml 的用法：可以为 rm -rf 类命令强制 ask_user，为 grep .env 直接 deny，并通过 allowed-path 这类安全检查器约束所有写操作的路径。这些机制是 Plan Mode "按工具白名单/黑名单切换行为"的基础设施。

资料来源：packages/cli/src/commands/extensions/examples/policies/README.md:11-21

任务调度与审批模式

A2A 服务端的 Task 是承载代理回合的核心对象，它在创建时即订阅消息总线，并在调度阶段把模型返回的 ToolCallRequestInfo 交给 Scheduler 处理。事件驱动版本通过 Scheduler 监听 TOOL_CALLS_UPDATE 消息来推进工具状态。

资料来源：packages/a2a-server/src/agent/task-event-driven.test.ts:23-32

关键的安全门控是 ApprovalMode，它在配置层决定工具调用是 ask_user、自动批准还是拒绝：

import { ApprovalMode } from '@google/gemini-cli-core';
const task = new Task('task-id', 'context-id', mockConfig, mockEventBus);

资料来源：packages/a2a-server/src/agent/task-event-driven.test.ts:36-37

工具调用状态机会经历 scheduled → awaiting_approval → executing → completed/failed 等阶段。race-condition.test.ts 验证了当多个工具同时进入 awaiting_approval 时，订阅者必须正确处理并发确认消息，避免任务挂起。

资料来源：packages/a2a-server/src/agent/race-condition.test.ts:31-50

A2A / ACP 会话通道

代理工作流还需要面向外部客户端的通道。packages/a2a-server/src/http/app.ts 通过 customUserBuilder 支持 Bearer 与 Basic 两种认证方式，并注册 code_generation 等技能；acpSession.ts 则在本地 CLI 中管理 prompt 执行、@path 文件解析与工具拦截。

资料来源：packages/a2a-server/src/http/app.ts:39-66、packages/cli/src/acp/README.md:9-19

flowchart LR
    U[用户提示] --> S[Session/Task]
    S -->|只读工具| R[检索/分析]
    S -->|策略引擎| P{Plan Mode?}
    P -->|是| W[阻断写工具<br/>产出计划]
    P -->|否| A[进入 awaiting_approval]
    A -->|用户批准| X[执行写入]
    A -->|拒绝| S
    W -->|用户确认| A

社区关注点

社区对代理工作流的安全性非常敏感。Issue #26856 报告了一次写工具误删数千文件的事故，凸显了"在执行前必须先有可审阅计划"的必要性。Issue #2553 则反映出 WriteFile 在非英文语境下的编码可靠性问题，提示 Plan Mode 还应覆盖写工具的内容校验。另一项呼声较高的是 #11506 "Add Skill to Gemini CLI like Claude Code"，可以视为 Plan Mode 的进阶形态——把可复用的代理技能注册为命名工具，再受同一套策略与审批机制约束。

参见

• Tool 系统与 SDK 基础
• 策略引擎与扩展机制
• 沙箱与可信文件夹

概述

Gemini CLI 提供了多层次的扩展与定制机制，使用户能够根据项目需求调整智能体的行为、可用工具以及系统提示。核心概念主要分为三类：自定义命令（Slash Commands，如 /help、/chat）、上下文文件（GEMINI.md）以及 Agent Skills（技能包）。这三者结合，可让团队沉淀可复用的工作流、领域知识与专业工具集。

资料来源：README.md:60-95

社区对扩展性的关注度持续上升：Issue #11506「Add Skill to Gemini CLI like Claude Code」明确请求引入类似 Claude Code 的 Agent Skills 能力，理由是「生态兼容性」。同时，Issue #4666 提出的 Plan Mode（通过禁用写工具来规划复杂代码变更）也属于 Skills/Commands 扩展能力的一部分，体现出用户对「按需切换工作模式」的强烈需求。

自定义命令与上下文文件

Gemini CLI 通过 Slash Commands 提供内建交互入口，并支持用户编写自定义命令。可通过 ~/.gemini/settings.json 进行全局配置，亦可在项目根目录放置 GEMINI.md 文件，为智能体提供持久的项目级上下文。

# 启动 CLI 后可使用内建命令
gemini
> /help
> /chat

社区曾报告在使用自定义系统提示时遇到 WriteFile 工具保存文本出现乱码（�）的问题（Issue #2553），提示在通过 GEMINI.md 或自定义命令注入包含特殊字符或多语言内容时，需要注意编码与字符集设置。

资料来源：README.md:38-95, README.md:108-118

Agent Skills SDK

面向 SDK 集成者与扩展开发者，Gemini CLI 在 @google/gemini-cli-sdk 包中暴露了声明式的 Skills 与 Tools API。Skill 通过目录引用加载，可包含提示、工具与行为定义。

// packages/sdk/src/skills.ts
export type SkillReference = { type: 'dir'; path: string };

export function skillDir(path: string): SkillReference {
  return { type: 'dir', path };
}

SkillReference 使用判别联合（type: 'dir'）来描述技能加载源，调用方通过 skillDir('/path/to/skill') 即可生成对目录的引用。这种设计使得技能可被灵活地挂载到会话上下文中，供智能体在执行任务时按需激活。

资料来源：packages/sdk/src/skills.ts:10-23

自定义工具与系统提示

除了 Skills，SDK 还提供 Tool 与 ToolDefinition 接口，允许开发者以 Zod Schema 形式声明工具的输入参数，并通过 action 回调执行业务逻辑。系统提示（SystemInstructions）既可以是静态字符串，也可以是基于 SessionContext 动态生成的函数。

import { z, tool } from '@google/gemini-cli-sdk';

const myTool = tool(
  {
    name: 'get_weather',
    description: 'Get the current weather for a location',
    inputSchema: z.object({ city: z.string() }),
  },
  async (params) => `Weather in ${params.city}: Sunny, 25°C`,
);

值得注意的是，动态 SystemInstructions 函数从 SessionContext 读取数据时，必须对输入进行净化（移除换行符、]、转义 < 与 >），以防止提示注入攻击。

资料来源：packages/sdk/src/tool.ts:30-115, packages/sdk/src/types.ts:14-32

扩展机制：MCP Server 与 Policy Engine

Gemini CLI 的扩展体系还包含 MCP（Model Context Protocol）服务器 与 Policy Engine 两类特殊形态。

MCP Server 扩展通过 @modelcontextprotocol/sdk 暴露工具与提示词，例如内置的 mcp-server 示例实现了 fetch_posts 工具与 poem-writer 提示词，可通过 gemini extensions new 模板生成。

Policy Engine 扩展则通过 policies/ 目录下的 .toml 文件贡献安全规则与检查器，例如要求 rm -rf 必须经用户确认、拒绝使用 grep 搜索敏感文件（如 .env），并对所有写操作执行 allowed-path 路径校验。出于安全考虑，CLI 会忽略扩展贡献的任何 allow 决策或 yolo 模式配置——扩展只能强化安全，不能绕过用户确认。

# 示意：policy 示例中定义的 rm -rf 确认规则
[[rule]]
tool = "shell"
command_pattern = "rm\\s+-rf"
decision = "ask"
message = "请确认是否执行递归删除"

资料来源：packages/cli/src/commands/extensions/examples/mcp-server/README.md:1-30, packages/cli/src/commands/extensions/examples/policies/README.md:1-36

常见失败模式与最佳实践

基于源码与社区反馈，使用 Skills 与自定义命令时需注意以下问题：

1. 提示注入风险：动态 SystemInstructions 必须净化 SessionContext 中读取的数据，否则恶意输入可能污染系统提示。
2. 编码问题：自定义系统提示中嵌入多语言或特殊字符时，WriteFile 可能写入乱码（�），建议在写入前显式声明 UTF-8 编码。
3. 权限边界：Policy Engine 的 allow 决策与 yolo 模式不可被扩展覆盖，用户确认环节始终保留。
4. 工具可见性：通过 ModelVisibleError 抛出的错误会回传给模型供其重试，但应仅在确实需要模型重决策时使用，避免暴露内部栈轨迹。

See Also

• README.md — 项目总览与认证配置
• packages/sdk/src/skills.ts — Skills 类型与工厂函数
• packages/sdk/src/tool.ts — Tool 定义与 ModelVisibleError
• packages/sdk/src/types.ts — Agent 选项与 SystemInstructions
• Issue #11506 Add Skill to Gemini CLI like Claude Code
• Issue #4666 Introduce a "Plan Mode"

内置工具系统是 Gemini CLI 中模型与外部环境交互的核心机制。模型通过调用工具完成文件读写、Shell 执行、Web 抓取、任务跟踪等动作；用户也可以基于 MCP（Model Context Protocol）扩展自定义工具。packages/sdk/src/tool.ts 定义了工具的标准化接口，贯穿 CLI、A2A Server 与 SDK 三层架构。资料来源：README.md、packages/sdk/src/tool.ts:1-45

工具的定义与结构

工具由四部分组成：唯一标识 name、供模型阅读的 description、用于参数校验的 Zod inputSchema、以及执行逻辑 action。ToolDefinition<T> 描述元数据，Tool<T> 在其上附加可调用函数。SDK 暴露的 tool() 工厂方法将声明与实现合并，并允许 action 接收可选的 SessionContext 以访问文件系统、Shell 等会话状态。资料来源：packages/sdk/src/tool.ts:47-115

import { z, tool } from '@google/gemini-cli-sdk';

const myTool = tool(
  {
    name: 'get_weather',
    description: 'Get the current weather for a location',
    inputSchema: z.object({ city: z.string() }),
  },
  async ({ city }) => `Weather in ${city}: Sunny`,
);

底层实现通过 BaseDeclarativeTool、BaseToolInvocation、Kind 与 MessageBus 与工具实现解耦。集成测试 tool.integration.test.ts 演示了如何将工具传入 GeminiCliAgent 的 tools 选项，并通过 fakeResponses / recordResponses 进行回放与录制。资料来源：packages/sdk/src/tool.integration.test.ts:20-50

工具的错误处理与执行流

工具抛出的异常默认不会回传到模型，错误由会话层捕获。SDK 提供 ModelVisibleError，将错误信息以对话内容形式反馈给模型，便于自动重试或策略调整；ToolDefinition 上的 sendErrorsToModel 标志则可整体控制错误可见性。资料来源：packages/sdk/src/tool.test.ts:10-40

flowchart LR
  A[模型调用工具] --> B[Zod 参数校验]
  B --> C{校验通过?}
  C -- 否 --> D[抛出错误]
  C -- 是 --> E[执行 action]
  E -- 成功 --> F[结果 JSON 序列化]
  E -- 失败 --> G{ModelVisibleError?}
  G -- 是 --> H[错误回传模型]
  G -- 否 --> I[会话层捕获]

在 A2A Server 中，Task 类负责调度这些工具调用，并通过 MessageBusType.TOOL_CONFIRMATION 与 MessageBusType.TOOL_CALLS_UPDATE 协调确认流程与状态更新，避免多个工具并发时的竞态问题。资料来源：packages/a2a-server/src/agent/race-condition.test.ts:21-67

扩展机制与测试支持

packages/cli/src/commands/extensions/examples/mcp-server 提供了最小可用的 MCP 服务器示例，演示如何通过 gemini-extension.json 将自定义工具注册到 Gemini CLI，它暴露 fetch_posts 工具与 poem-writer 提示。packages/test-utils/src/test-mcp-server.ts 中的 TestMcpServerBuilder 为单元测试提供快速搭建 MCP 模拟服务的能力，可声明工具名称、JSON Schema 与响应内容。资料来源：packages/cli/src/commands/extensions/examples/mcp-server/README.md:1-30、packages/test-utils/src/test-mcp-server.ts:20-55

内置工具的核心实现位于 packages/core 包。package.json 中依赖 zod（参数校验）、simple-git（版本控制）、systeminformation（系统信息）、tree-sitter-bash（Shell 解析）等库，支撑文件、Shell、Web 等内置工具的能力。资料来源：packages/core/package.json:48-78

与社区关注点的关联

社区高度关注的“计划模式”（Plan Mode，参考 Issue #4666）正是建立在工具系统之上：通过在特定状态下禁用写类工具（如 WriteFile、破坏性 Shell），迫使用户先与模型确认方案。Issue #2553 中 WriteFile 保存后出现乱码的问题说明，写类工具的编码与编码协商仍需更稳健的默认行为；Issue #11506 中提出的 Skills 机制则代表对工具系统的进一步抽象与生态兼容需求。这些反馈共同指向同一方向：工具系统需要更清晰的权限边界、更可配置的扩展接口，以及更稳定的执行语义。

See Also

• MCP 服务器集成
• 内置工具概览
• 文件系统工具
• Shell 工具
• 可信文件夹与沙箱

1. 概览：可扩展性体系

Gemini CLI 采用三层可扩展性架构，允许用户在保持核心简洁的前提下注入工具、命令与安全策略。顶层是 扩展（Extension） 机制，通过 gemini-extension.json 清单将自定义能力挂载到 CLI；中间层是 MCP（Model Context Protocol）服务器，使任意遵循 MCP 协议的进程都能把工具暴露给模型；底层是 Hooks 与 Policy 引擎，通过 policies/*.toml 在工具调用前进行规则校验与拦截。三者协同构成了「生态兼容」的目标，这也是社区强烈诉求的核心（参见 Issue #11506 提出的 Skill 能力）。

flowchart TB
    User[用户输入] --> CLI[Gemini CLI 核心]
    CLI --> Ext[扩展清单<br/>gemini-extension.json]
    CLI --> MCP[MCP 服务器<br/>@modelcontextprotocol/sdk]
    CLI --> Pol[Policy 引擎<br/>policies/*.toml]
    MCP --> Tools[动态工具注册]
    Ext --> Tools
    Pol -.拦截/允许.-> Tools
    Tools --> Model[Gemini 模型]

资料来源：packages/cli/src/commands/extensions/examples/mcp-server/README.md:1-30、packages/cli/src/commands/extensions/examples/policies/README.md:1-30。

2. 扩展（Extension）机制

扩展是 Gemini CLI 的第一公民。每个扩展是一个包含 gemini-extension.json 清单的目录，CLI 通过该清单发现命令、上下文文件、模型与可选的 MCP 服务器。仓库内置的 gemini extensions new 脚手架会拷贝 examples/ 下的模板，从而引导用户快速创建。

典型扩展结构包括：

扩展既可本地链接（gemini extensions link <path>），也可远程安装。Policy 引擎示例明确指出：扩展只能加固安全，不能绕过 allow 决策或 yolo 模式——这是一种「单向收紧」的安全设计。

资料来源：packages/cli/src/commands/extensions/examples/policies/README.md:25-30。

3. MCP 协议集成

MCP（Model Context Protocol）是一套允许外部进程把工具与提示词暴露给 LLM 代理的标准协议。Gemini CLI 将 MCP 服务器视为「外部工具源」，运行时通过 JSON-RPC 发现并调用工具。

仓库自带的 MCP 示例 examples/mcp-server 演示了最小可运行实现：使用 @modelcontextprotocol/sdk 暴露 fetch_posts 工具和 poem-writer 提示词，并通过 package.json 中的 "type": "module" 启用 ESM。用户在 ~/.gemini/settings.json 中注册后，即可在 CLI 内通过 @server 前缀调用。

资料来源：packages/cli/src/commands/extensions/examples/mcp-server/README.md:3-22、packages/cli/src/commands/extensions/examples/mcp-server/package.json:1-13。

测试侧同样有完整支持：packages/test-utils/src/test-mcp-server.ts 提供了 TestMcpServerBuilder，允许测试用例以编程方式构造带工具定义、JSON Schema 与响应体的虚拟 MCP 服务，从而对客户端逻辑做端到端验证。TestTool 接口要求显式声明 inputSchema 与 content[].text 响应结构，贴合 MCP 官方协议。

资料来源：packages/test-utils/src/test-mcp-server.ts:7-49。

4. Hooks 与 Policy 引擎

Policy 引擎以 .toml 规则文件驱动，针对工具调用执行三类判定：allow（放行）、deny（拒绝并返回自定义消息）、ask（要求用户确认）。示例策略包括：

• 拦截 rm -rf 命令要求确认
• 拒绝 grep .env 这类敏感文件检索
• 通过 allowed-path 安全检查器校验所有写入路径

值得注意的是，扩展贡献的 allow 决策与 yolo 模式会被 CLI 忽略，确保「权限只能收紧、不能放宽」的不变式。

资料来源：packages/cli/src/commands/extensions/examples/policies/README.md:18-30。

5. SDK 与外部集成层

对于希望以编程方式嵌入 Gemini CLI 的开发者，@google/gemini-cli-sdk 提供了声明式工具 API。tool() 函数接受 ToolDefinition（name + description + Zod inputSchema）与 action 回调，返回完整的 Tool 对象。sendErrorsToModel 标志位决定异常是否回传模型以便自愈；ModelVisibleError 则是一个专用错误类，把消息以受控方式暴露给模型。

import { z, tool } from '@google/gemini-cli-sdk';
const getWeather = tool(
  { name: 'get_weather', description: '获取城市天气',
    inputSchema: z.object({ city: z.string() }) },
  async ({ city }) => `Weather in ${city}: Sunny`,
);

资料来源：packages/sdk/src/tool.ts:30-103、packages/sdk/src/tool.test.ts:17-40。

6. 配套协议：ACP 与 A2A

除 MCP 外，Gemini CLI 还实现了 ACP（Agent Communication Protocol） 与 A2A（Agent-to-Agent） 两种外部接口。ACP 面向 IDE 客户端（如 VS Code 伴生插件），由 acpSession.ts 处理会话生命周期、@path 文件解析与工具执行流；A2A 则面向代理间协作，coderAgentCard 在 a2a-server/src/http/app.ts 中声明能力（code_generation 示例标签），并通过 customUserBuilder 支持 Bearer / Basic 两种身份头解析。

资料来源：packages/cli/src/acp/README.md:7-20、packages/a2a-server/src/http/app.ts:38-58。

7. 社区关注点与失败模式

社区讨论（参见 Issue #4666）反映出对「写操作拦截」类 Hook 的强需求，例如 Plan Mode 要求在计划阶段屏蔽写入工具，这本质上是一类 ask/拒绝的策略。Issue #2553 则暴露了一个常见陷阱：当自定义系统提示词与文件编码不匹配时，工具写入会产生 � 字符——可通过在策略中校验文件二进制安全来缓解。

See Also

• README.md — 项目总览与认证
• 配置参考 — settings.json 字段说明

概述与设计目标

Gemini CLI 的前端 UI 是一套基于终端的交互式界面（Terminal User Interface），运行在 Node.js 20+ 环境之上，使用 Ink（React for CLIs）渲染组件 资料来源：package.json:8-11。整个项目以 monorepo 形式组织在 packages/* 工作区下，主要分为核心包 @google/gemini-cli-core、CLI 包 @google/gemini-cli、SDK 包 @google/gemini-cli-sdk 与 A2A 服务器包 资料来源：package.json:10-14。

UI 层的职责包括：渲染对话历史与流式响应、收集用户输入、展示工具调用结果、暴露斜杠命令（如 /help、/chat、/bug），以及通过主题（Themes）控制配色与外观 资料来源：README.md:96-128。此外，CLI 还提供「受信任文件夹（Trusted Folders）」沙箱机制与 /sandbox 模式以约束危险操作，这直接影响前端的确认弹窗与权限提示交互 资料来源：README.md:130-150。

主题与外观定制

主题系统允许用户为终端界面选择预设或自定义的配色方案。Gemini CLI 文档明确将「主题」作为一项可配置项，链接到独立文档 Themes Guide 资料来源：README.md:96-100。主题通过解析 settings.json 中的 theme 字段在启动时加载，并在运行时通过命令面板动态切换。配色既影响静态文本（用户输入、模型回复），也影响语义元素——例如工具调用状态的彩色徽章、错误信息的红色高亮等。

下表列出与 UI 视觉一致性相关的核心配置入口（数据基于仓库当前结构归纳）：

交互模式：工具、命令与 ACP

Gemini CLI 的所有交互都围绕「工具（Tool）」与「斜杠命令（Slash Command）」两个原语展开。SDK 抽象出统一的 Tool<T> 接口：name 与 description 决定模型如何决定调用时机，inputSchema 是 Zod 类型约束（同时通过 zodToJsonSchema 转 JSON Schema 暴露给模型），action 是实际执行体 资料来源：packages/sdk/src/tool.ts:71-130。当 sendErrorsToModel 设为 true 时，异常会以 ModelVisibleError 形式回传模型，便于自纠错——这一行为直接影响前端对错误的展示策略 资料来源：packages/sdk/src/tool.ts:35-50。

斜杠命令体系则覆盖本地命令、扩展命令与代理协议命令三类。在 ACP（Agent Client Protocol）集成路径下，packages/cli/src/acp/ 模块承担外部编辑器（如 Zed、JetBrains）通过 stdio 接入 Gemini CLI 的职责。模块按职责拆分：

• acpRpcDispatcher.ts：RPC 入口与认证；
• acpSessionManager.ts：会话生命周期；
• acpSession.ts：提示词循环、工具执行、@path 文件解析与流式回传；
• acpCommandHandler.ts：拦截并执行 /memory、/init 等斜杠命令；
• acpFileSystemService.ts：受工作区边界约束的文件系统访问 资料来源：packages/cli/src/acp/README.md:21-30。

这种分层让 UI 主循环与代理协议共用同一套 Tool 与命令执行管线，避免双端实现漂移。

flowchart LR
  User[终端用户] --> CLI[CLI UI Ink 渲染]
  CLI -->|输入提示 / 斜杠命令| CmdH[命令处理器]
  CLI -->|消息| Session[会话循环]
  Session --> Tool[Tool SDK]
  Tool -->|结果| Session
  Session -->|流式输出| CLI
  CLI -.ACP 协议.-> Ext[外部编辑器]
  Ext -.stdio JSON-RPC.-> CLI

MCP 扩展、扩展点与测试基础设施

前端可交互范围通过 MCP（Model Context Protocol）服务器进一步扩展。仓库内置了一份最小 MCP 服务器示例，位于 packages/cli/src/commands/extensions/examples/mcp-server，演示了如何暴露工具（fetch_posts）与提示词（poem-writer）给 Gemini CLI 资料来源：packages/cli/src/commands/extensions/examples/mcp-server/README.md:5-20。用户在终端中通过 @<server-name> 形式触发，例如：

> @github List my open pull requests
> @database Run a query to find inactive users

MCP 服务器配置位于 ~/.gemini/settings.json，遵循标准 mcpServers 字段约定 资料来源：README.md:170-185。

测试侧提供了 TestMcpServerBuilder 用于在 Vitest 中构建伪 MCP 响应，可指定工具名、描述、JSON Schema 与字符串或对象形式的回复内容 资料来源：packages/test-utils/src/test-mcp-server.ts:30-60。这使得 UI 组件的端到端测试不必依赖真实网络服务。

已知交互风险与社区关注点

社区高互动议题反映了若干 UI/交互痛点。Issue #4666（30 评论）呼吁引入「Plan Mode」，建议在按下 Shift+Tab 两次时禁用写工具以让模型先输出计划再执行——属于对当前「工具自动执行」UI 流的安全增强请求 资料来源：community context: #4666。Issue #11506 则希望对齐 Claude Code 的 Skills 体系，把可复用的「技能」作为前端可调度的扩展原语 资料来源：community context: #11506。

在文本写入路径上，Issue #2553 报告 WriteFile 在特定编码环境下会写入「�」替换字符，提示 UI 与底层 I/O 流之间需要更明确的编码协商（例如显式 utf-8 写入） 资料来源：community context: #2553。此外，Issue #26856 反映了一次因模型误判指令而导致用户工作区被大范围删除的事故，凸显出在 UI 中加入「破坏性操作的二次确认」与「可回滚的检查点（Checkpointing）」的重要性——而后者已是官方支持的特性 资料来源：README.md:115-118。

综合来看，Gemini CLI 的前端正朝着「可观察、可中断、可回滚」的交互范式演进，主题与沙箱是当前最成熟的两条定制通道。

See Also

• 配置与身份验证
• MCP 服务器集成
• 沙箱与安全模型
• 工具与扩展开发

会话（Session）是 Gemini CLI 与 Gemini 模型之间一次连续交互的载体。在长链路、多工具、多步骤的智能体任务中，用户经常需要“中断后继续”、“回退若干步重试”，甚至“在另一台机器上恢复同一段对话”。Gemini CLI 将这些能力抽象为 会话管理 + Checkpoint（检查点）+ 重放（Replay） 三件套，从而把不可逆的 AI 行为变成可回溯、可恢复的工作流。

1. 会话（Session）的核心抽象

在 SDK 层，工具（Tool）执行时可以通过 SessionContext 拿到“当前会话”的引用，用以访问文件系统、Shell 上下文与其他会话状态。Tool 接口的 action 签名中明确包含 context?: SessionContext 参数，证明会话状态是跨工具调用共享的，而不仅仅是某一轮 prompt 的私有变量。资料来源：packages/sdk/src/tool.ts

A2A Server 端则会为每一次执行请求构造一个 Agent 上下文，并在 code_generation 技能描述中说明：“按用户请求生成代码片段或完整文件，流式（streaming）输出结果”。这种流式会话模型与本地 CLI 的会话持久化是同一套设计思想的两端：服务端强调“边推边记录”，本地端则落盘为 Checkpoint。资料来源：packages/a2a-server/src/http/app.ts

flowchart LR
    U[用户输入] --> S[Session 会话上下文]
    S --> T1[Tool 1 执行]
    T1 --> C1{是否触发 Checkpoint}
    C1 -- 是 --> CK[(Checkpoint 存储)]
    C1 -- 否 --> S
    S --> T2[Tool 2 执行]
    T2 --> M[返回模型上下文]
    CK -. 恢复/重放 .-> S

2. Checkpoint（检查点）机制

README 的特性列表中明确写道：“Conversation checkpointing to save and resume complex sessions”，即“对话检查点，用于保存与恢复复杂会话”。Checkpoint 的目标不是缓存单个 HTTP 响应，而是序列化整段对话状态：用户消息、模型回复、工具调用参数、工具执行结果，以及相关的环境变量与配置。资料来源：README.md

在工具链层面，Checkpointer 通常与以下子系统联动：

• Token Caching：将已用过的 system prompt、工具定义与历史消息在本地缓存，避免恢复会话时重复消耗 token。README 在“Core Features”一节将 Token Caching 与 Checkpointing 并列展示，说明二者协同生效。资料来源：README.md
• 持久化目录：Checkpoint 默认会落在 ~/.gemini/ 下的会话存储区，与 settings.json、扩展元数据等并列管理。
• 关联扩展与策略：扩展（Extension）所声明的 MCP 工具、策略（Policy）规则会在 Checkpoint 中被打包，恢复时连同策略一并生效，确保权限判定一致。资料来源：packages/cli/src/commands/extensions/examples/policies/README.md

3. 重放（Replay）与恢复

重放是 Checkpoint 的“逆操作”：给定一个 Checkpoint 标识符，CLI 把磁盘上的状态重新灌回运行时内存，包括历史消息、工具调用栈、当前挂起的工具调用等。ACP（Agent Client Protocol）层在源码中直接提供了 acpResume.test.ts，用于验证“从已保存会话加载并恢复”的集成路径。这条测试与 acpSession.ts 中的提示循环、工具执行、命令拦截逻辑共同保证：恢复后模型看到的上下文与中断前等价。资料来源：packages/cli/src/acp/README.md

重放能力在实际工程中有三类典型用途：

4. 社区关注与已知风险

社区中高互动的话题与本能力直接相关：

• Plan Mode 诉求（Issue #4666）：用户希望 Gemini CLI 引入 Claude Code 类似的“计划模式”，在执行写操作前先建立 Checkpoint，避免不可逆修改。该模式本质上就是把 Checkpoint 提前到工具执行之前。资料来源：Issue #4666
• 数据丢失投诉（Issue #26856）：有用户报告 AI “擅自删除大量文件且不可恢复”，反映出对自动 Checkpoint 与回退机制的强烈需求。社区建议在出问题时立即导出 Chat History JSON 配合 Checkpoint 进行取证与回滚。资料来源：Issue #26856
• 编码损坏（Issue #2553）：使用 WriteFile 写入文本后出现 � 字符。此类问题在没有 Checkpoint 的情况下极易演变为不可逆错误，启用会话级 Checkpoint 后可一键回退到损坏之前的版本。资料来源：Issue #2553

5. 实践建议

1. 开启自动 Checkpoint：在 ~/.gemini/settings.json 中确认 checkpointing 处于启用状态，并对长任务手动使用 /chat save 命名保存关键节点。
2. 结合 Token Caching：对包含大量 GEMINI.md 上下文、扩展工具定义的会话，启用 Token Caching 可显著降低恢复时的延迟与费用。资料来源：README.md
3. 谨慎对待扩展策略：扩展贡献的 Policy 在恢复时会原样生效，README 提示“Gemini CLI 忽略扩展贡献的 allow 决策和 yolo 模式”，恢复后应再次确认当前信任级别。资料来源：packages/cli/src/commands/extensions/examples/policies/README.md

另请参阅

• README.md
• packages/cli/src/acp/README.md
• packages/sdk/src/tool.ts
• packages/a2a-server/src/http/app.ts

概述

Gemini CLI 是一个具备完整自主执行能力的命令行 AI Agent，能在本地调用文件系统和 shell 直接修改代码与运行环境。这种高自治度同时带来显著的安全边界问题——一旦 Agent 误判或被诱导执行破坏性命令，用户的本地工作目录可能遭到不可逆的破坏（社区 issue #26856 即是用户反馈"AI 删除了价值 300 美元的 Obsidian 笔记文件"的典型案例）。

为平衡能力与风险，Gemini CLI 在三个层面提供保护机制：沙箱执行、信任文件夹与 IDE 集成边界。这三者共同构成了 Agent 在用户机器上活动的安全围栏。资料来源：README.md

沙箱执行模型

沙箱（Sandbox）将 Agent 的 shell 工具调用限制在受控的执行环境中，避免对宿主机造成意外破坏。Gemini CLI 在 packages/core 包中按平台分别实现了沙箱管理器：

资料来源：packages/core/src/sandbox/macos/MacOsSandboxManager.ts、packages/core/src/sandbox/linux/LinuxSandboxManager.ts

packages/core/package.json 的 optionalDependencies 中列出了 @lydell/node-pty 及其各平台二进制包，说明沙箱环境下仍需要 PTY 支持以提供交互式 shell 体验。资料来源：packages/core/package.json

flowchart LR
  A[用户 Prompt] --> B[Gemini Agent]
  B --> C{工具调用}
  C -->|shell| D[Sandbox Manager]
  D -->|macOS| E[sandbox-exec]
  D -->|Linux| F[user namespace + seccomp]
  E --> G[受限子进程]
  F --> G
  G --> H[结果回传 Agent]

对于希望完全隔离的用户，沙箱模式可与"无写入工具"策略叠加使用——这也正是社区 issue #4666 提出的"Plan Mode"诉求的核心动机：先让 Agent 输出计划，确认后再放行写工具。资料来源：docs/cli/sandbox.md

信任文件夹与权限控制

"信任文件夹"（Trusted Folders）是比沙箱更细粒度的策略层：用户可以为不同项目目录授予不同的执行权限（如允许 WriteFile、禁止 Shell、或全部拒绝）。当 Agent 在非信任目录中尝试危险操作时，会弹出确认对话框。资料来源：docs/cli/trusted-folders.md

在 SDK 层面，工具开发者可以通过 sendErrorsToModel 标志控制错误是否回传给模型，从而影响 Agent 的自纠错行为；当工具抛出 ModelVisibleError 时，模型能看见具体失败原因并调整策略。资料来源：packages/sdk/src/tool.ts

企业用户还可以通过 ~/.gemini/settings.json 统一下发策略，配合 MCP 服务器白名单实现集中管控。资料来源：docs/cli/enterprise.md

IDE 集成

Gemini CLI 提供 VS Code 配套的 IDE 集成，让 Agent 能在编辑器侧边栏直接看到当前打开的文件、光标位置与选区上下文，而无需反复读取磁盘。这一集成也带来新的安全考量：编辑器上下文天然跨越多个工作区，因此信任文件夹策略在 IDE 会话中同样生效。资料来源：docs/ide-integration/index.md

此外，A2A（Agent-to-Agent）服务器在远程暴露 Agent 能力时，要求显式的 HTTP 认证：支持 Bearer 与 Basic 两种方案，未携带有效凭据的请求会被回退为 UnauthenticatedUser，从而在网络层拒绝访问。资料来源：packages/a2a-server/src/http/app.ts

常见问题与社区反馈

社区高赞讨论中有两条与本页主题直接相关：

1. Plan Mode（issue #4666，30 评论）：用户希望 Agent 在执行 WriteFile、Edit 等写工具前必须先输出计划并获得确认。这与沙箱思路不同，但目标一致——降低误操作风险。
2. 不可逆数据丢失（issue #26856，45 评论）：反映了当前默认安全机制仍不足以阻止"模型误判 + 用户未在场"时的破坏性操作。建议结合沙箱、信任文件夹与定期 Checkpoint 共同使用。

Checkpoint（会话快照）配合上述机制，可让用户在损失发生后回退到上一稳定状态。资料来源：docs/cli/checkpointing.md（文档站外链）

See Also

• 核心功能与 CLI 命令
• MCP 服务器集成
• SDK 与 Agent 编程接口
• 遥测与监控

Pitfall Log / 踩坑日志

项目：google-gemini/gemini-cli

摘要：发现 38 个潜在踩坑项，其中 18 个为 high/blocking；最高优先级：安装坑 - 来源证据：Allow for local agents to be backgroundable。

1. 安装坑 · 来源证据：Allow for local agents to be backgroundable

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

2. 安装坑 · 来源证据：GeminiCLI.com Feedback: [ISSUE]

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

3. 安装坑 · 来源证据：Rewind BUG

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

4. 安装坑 · 来源证据：Surface or quarantine invalid Auto Memory inbox patches

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Surface or quarantine invalid Auto Memory inbox patches
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/google-gemini/gemini-cli/issues/26523 | 来源类型 github_issue 暴露的待验证使用条件。

5. 配置坑 · 来源证据：Memory system bugs and quality improvements

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Memory system bugs and quality improvements
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/google-gemini/gemini-cli/issues/26516 | 来源类型 github_issue 暴露的待验证使用条件。

6. 运行坑 · 来源证据：Change the steering eval test to always pass

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Change the steering eval test to always pass
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/google-gemini/gemini-cli/issues/23313 | 来源类型 github_issue 暴露的待验证使用条件。

7. 运行坑 · 来源证据：Dev + Review Loop Subagent Example within Gemini CLI Repo

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Dev + Review Loop Subagent Example within Gemini CLI Repo
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/google-gemini/gemini-cli/issues/22600 | 来源类型 github_issue 暴露的待验证使用条件。

8. 运行坑 · 来源证据：Model frequently creates tmp scripts in random spots

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Model frequently creates tmp scripts in random spots
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/google-gemini/gemini-cli/issues/23571 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

9. 运行坑 · 来源证据：Stabilize and Enhance Internal Project Evaluations

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Stabilize and Enhance Internal Project Evaluations
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/google-gemini/gemini-cli/issues/23166 | 来源类型 github_issue 暴露的待验证使用条件。

10. 维护坑 · 来源证据：Gemini CLI encounters 400 error with > 128 tools

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Gemini CLI encounters 400 error with > 128 tools
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/google-gemini/gemini-cli/issues/24246 | 来源类型 github_issue 暴露的待验证使用条件。

11. 安全/权限坑 · 失败模式：security_permissions: Add deterministic redaction and reduce Auto Memory logging

• 严重度：high
• 证据强度：source_linked
• 发现：Developers should check this security_permissions risk before relying on the project: Add deterministic redaction and reduce Auto Memory logging
• 对用户的影响：Developers may expose sensitive permissions or credentials: Add deterministic redaction and reduce Auto Memory logging
• 证据：failure_mode_cluster:github_issue | https://github.com/google-gemini/gemini-cli/issues/26525 | Add deterministic redaction and reduce Auto Memory logging

12. 安全/权限坑 · 失败模式：security_permissions: Robust component level evalutions

• 严重度：high
• 证据强度：source_linked
• 发现：Developers should check this security_permissions risk before relying on the project: Robust component level evalutions
• 对用户的影响：Developers may expose sensitive permissions or credentials: Robust component level evalutions
• 证据：failure_mode_cluster:github_issue | https://github.com/google-gemini/gemini-cli/issues/24353 | Robust component level evalutions

13. 安全/权限坑 · 来源证据：Add deterministic redaction and reduce Auto Memory logging

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add deterministic redaction and reduce Auto Memory logging
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/google-gemini/gemini-cli/issues/26525 | 来源类型 github_issue 暴露的待验证使用条件。

14. 安全/权限坑 · 来源证据：Assess the impact of AST-aware file reads, search, and mapping

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Assess the impact of AST-aware file reads, search, and mapping
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/google-gemini/gemini-cli/issues/22745 | 来源类型 github_issue 暴露的待验证使用条件。

15. 安全/权限坑 · 来源证据：Robust component level evalutions

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Robust component level evalutions
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/google-gemini/gemini-cli/issues/24353 | 来源类型 github_issue 暴露的待验证使用条件。

16. 安全/权限坑 · 来源证据：Shell command execution gets stuck with "Waiting input" after command completes

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Shell command execution gets stuck with "Waiting input" after command completes
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/google-gemini/gemini-cli/issues/25166 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

17. 安全/权限坑 · 来源证据：Stop Auto Memory from retrying low-signal sessions indefinitely

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Stop Auto Memory from retrying low-signal sessions indefinitely
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/google-gemini/gemini-cli/issues/26522 | 来源类型 github_issue 暴露的待验证使用条件。

18. 安全/权限坑 · 来源证据：Utilize Generalist to help solve build fix use case

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Utilize Generalist to help solve build fix use case
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/google-gemini/gemini-cli/issues/22602 | 来源类型 github_issue 暴露的待验证使用条件。

19. 安装坑 · 失败模式：installation: Assess the impact of AST-aware file reads, search, and mapping

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Assess the impact of AST-aware file reads, search, and mapping
• 对用户的影响：Developers may fail before the first successful local run: Assess the impact of AST-aware file reads, search, and mapping
• 证据：failure_mode_cluster:github_issue | https://github.com/google-gemini/gemini-cli/issues/22745 | Assess the impact of AST-aware file reads, search, and mapping

20. 配置坑 · 失败模式：configuration: Memory system bugs and quality improvements

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: Memory system bugs and quality improvements
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Memory system bugs and quality improvements
• 证据：failure_mode_cluster:github_issue | https://github.com/google-gemini/gemini-cli/issues/26516 | Memory system bugs and quality improvements

21. 配置坑 · 失败模式：configuration: Shell command execution gets stuck with "Waiting input" after command completes

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: Shell command execution gets stuck with "Waiting input" after command completes
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Shell command execution gets stuck with "Waiting input" after command completes
• 证据：failure_mode_cluster:github_issue | https://github.com/google-gemini/gemini-cli/issues/25166 | Shell command execution gets stuck with "Waiting input" after command completes

22. 配置坑 · 失败模式：configuration: Stop Auto Memory from retrying low-signal sessions indefinitely

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: Stop Auto Memory from retrying low-signal sessions indefinitely
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Stop Auto Memory from retrying low-signal sessions indefinitely
• 证据：failure_mode_cluster:github_issue | https://github.com/google-gemini/gemini-cli/issues/26522 | Stop Auto Memory from retrying low-signal sessions indefinitely

23. 配置坑 · 失败模式：configuration: Surface or quarantine invalid Auto Memory inbox patches

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: Surface or quarantine invalid Auto Memory inbox patches
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Surface or quarantine invalid Auto Memory inbox patches
• 证据：failure_mode_cluster:github_issue | https://github.com/google-gemini/gemini-cli/issues/26523 | Surface or quarantine invalid Auto Memory inbox patches

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

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

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

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

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

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

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

28. 能力坑 · 失败模式：capability: Agent should stop/discourage destructive behavior

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this capability risk before relying on the project: Agent should stop/discourage destructive behavior
• 对用户的影响：Developers may hit a documented source-backed failure mode: Agent should stop/discourage destructive behavior
• 证据：failure_mode_cluster:github_issue | https://github.com/google-gemini/gemini-cli/issues/22672 | Agent should stop/discourage destructive behavior

29. 能力坑 · 失败模式：capability: Allow for local agents to be backgroundable

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this capability risk before relying on the project: Allow for local agents to be backgroundable
• 对用户的影响：Developers may hit a documented source-backed failure mode: Allow for local agents to be backgroundable
• 证据：failure_mode_cluster:github_issue | https://github.com/google-gemini/gemini-cli/issues/22741 | Allow for local agents to be backgroundable

30. 能力坑 · 失败模式：capability: Change the steering eval test to always pass

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this capability risk before relying on the project: Change the steering eval test to always pass
• 对用户的影响：Developers may hit a documented source-backed failure mode: Change the steering eval test to always pass
• 证据：failure_mode_cluster:github_issue | https://github.com/google-gemini/gemini-cli/issues/23313 | Change the steering eval test to always pass

31. 能力坑 · 失败模式：capability: Corruption after exiting external editors in terminalBuffer mode

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this capability risk before relying on the project: Corruption after exiting external editors in terminalBuffer mode
• 对用户的影响：Developers may hit a documented source-backed failure mode: Corruption after exiting external editors in terminalBuffer mode
• 证据：failure_mode_cluster:github_issue | https://github.com/google-gemini/gemini-cli/issues/24935 | Corruption after exiting external editors in terminalBuffer mode

32. 能力坑 · 失败模式：capability: Gemini CLI encounters 400 error with > 128 tools

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this capability risk before relying on the project: Gemini CLI encounters 400 error with > 128 tools
• 对用户的影响：Developers may hit a documented source-backed failure mode: Gemini CLI encounters 400 error with > 128 tools
• 证据：failure_mode_cluster:github_issue | https://github.com/google-gemini/gemini-cli/issues/24246 | Gemini CLI encounters 400 error with > 128 tools

33. 能力坑 · 失败模式：capability: Investigate using AST aware CLI tools to map codebase

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this capability risk before relying on the project: Investigate using AST aware CLI tools to map codebase
• 对用户的影响：Developers may hit a documented source-backed failure mode: Investigate using AST aware CLI tools to map codebase
• 证据：failure_mode_cluster:github_issue | https://github.com/google-gemini/gemini-cli/issues/22746 | Investigate using AST aware CLI tools to map codebase

34. 能力坑 · 失败模式：capability: Investigate using AST aware tools to search and perform file reads

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this capability risk before relying on the project: Investigate using AST aware tools to search and perform file reads
• 对用户的影响：Developers may hit a documented source-backed failure mode: Investigate using AST aware tools to search and perform file reads
• 证据：failure_mode_cluster:github_issue | https://github.com/google-gemini/gemini-cli/issues/22747 | Investigate using AST aware tools to search and perform file reads

35. 能力坑 · 失败模式：capability: Model frequently creates tmp scripts in random spots

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this capability risk before relying on the project: Model frequently creates tmp scripts in random spots
• 对用户的影响：Developers may hit a documented source-backed failure mode: Model frequently creates tmp scripts in random spots
• 证据：failure_mode_cluster:github_issue | https://github.com/google-gemini/gemini-cli/issues/23571 | Model frequently creates tmp scripts in random spots

36. 运行坑 · 失败模式：performance: Stabilize and Enhance Internal Project Evaluations

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this performance risk before relying on the project: Stabilize and Enhance Internal Project Evaluations
• 对用户的影响：Developers may hit a documented source-backed failure mode: Stabilize and Enhance Internal Project Evaluations
• 证据：failure_mode_cluster:github_issue | https://github.com/google-gemini/gemini-cli/issues/23166 | Stabilize and Enhance Internal Project Evaluations

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

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

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

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