Gemini CLI 深度解析：功能介绍与实现原理

一、概述

Gemini CLI 是 Google 推出的开源终端 AI 编程智能体，将 Gemini 模型的能力直接带入开发者的终端环境。它以 Apache 2.0 协议完全开源，具有业界最慷慨的免费额度和最大的上下文窗口。

发布时间：2025 年 6 月 25 日（Google I/O Connect 大会后公开发布）
技术栈：TypeScript（monorepo 架构）
开源协议：Apache 2.0
GitHub：google-gemini/gemini-cli
底层模型：Gemini 2.5 Pro / Gemini 2.5 Flash / Gemini 3 系列
上下文窗口：1M tokens（业界最大）
免费额度：60 次请求/分钟，1000 次请求/天

二、核心架构与实现原理

2.1 Monorepo 模块化架构

Gemini CLI 采用 TypeScript monorepo 结构，核心分为两个独立包和一个工具层：

gemini-cli/
├── packages/
│   ├── cli/                    ← CLI 前端包
│   │   ├── src/
│   │   │   ├── input/          ← 用户输入处理（含自动补全）
│   │   │   ├── display/        ← 响应渲染与格式化
│   │   │   ├── history/        ← 会话历史管理
│   │   │   ├── themes/         ← 主题与 UI 定制
│   │   │   └── config/         ← 配置与设置管理
│   │   └── ...
│   │
│   └── core/                   ← Core 后端包
│       ├── src/
│       │   ├── core/
│       │   │   ├── prompts.ts  ← 系统提示构建
│       │   │   ├── api.ts      ← Gemini API 客户端
│       │   │   └── state.ts    ← 状态管理
│       │   ├── tools/          ← 内建工具实现
│       │   │   ├── ls.ts
│       │   │   ├── readFile.ts
│       │   │   ├── writeFile.ts
│       │   │   ├── grep.ts
│       │   │   ├── glob.ts
│       │   │   ├── edit.ts
│       │   │   ├── shell.ts
│       │   │   ├── webFetch.ts
│       │   │   ├── webSearch.ts
│       │   │   └── memory.ts
│       │   └── agents/         ← 子智能体定义
│       └── ...
│
├── docs/                       ← 文档
└── .gemini/                    ← 配置文件

前后端分离设计的意义：

层	包	职责	可替换性
前端	`packages/cli`	输入处理、UI 渲染、主题、快捷键	可替换为 Web UI、IDE 插件等
后端	`packages/core`	API 通信、提示构建、工具注册执行、状态管理	可嵌入其他应用
工具	`packages/core/src/tools/`	各类工具的独立实现	可扩展、可替换

这种分离使得核心逻辑可以独立于终端 UI 进行开发和测试，也方便将 Core 包嵌入到其他应用或 CI/CD 流程中。

2.2 智能体循环（Agent Loop）

Gemini CLI 的智能体循环与业界通用的 ReAct 模式一致，但有其独特的实现细节：

┌─────────────────────────────────────────────────────────────────┐
│                     Gemini CLI Agent Loop                       │
│                                                                 │
│  ① 用户输入处理                                                  │
│     │  CLI 包处理键盘输入、自动补全、文件路径引用                     │
│     │  支持 Vim 模式编辑                                         │
│     ▼                                                           │
│  ② 提示构建（Prompt Construction）                                │
│     │  Core 包组装：系统提示 + GEMINI.md + 对话历史 + 工具定义        │
│     │  函数：getCoreSystemPrompt()                               │
│     ▼                                                           │
│  ③ API 调用                                                     │
│     │  发送到 Gemini API（AI Studio 或 Vertex AI）                │
│     │  返回：文本响应 / 工具调用请求 / 两者兼有                      │
│     ▼                                                           │
│  ④ 工具执行                                                     │
│     │  Core 包验证参数                                           │
│     │  检查执行策略（是否需要用户确认）                               │
│     │  执行工具并收集结果                                          │
│     ▼                                                           │
│  ⑤ 结果回送                                                     │
│     │  工具结果追加到对话历史                                      │
│     │  回到步骤 ③，直到 Gemini 不再请求工具调用                     │
│     ▼                                                           │
│  ⑥ 响应渲染                                                     │
│     │  CLI 包格式化并显示最终响应                                   │
│     │  应用当前主题样式                                            │
│     ▼                                                           │
│  等待下一次用户输入...                                             │
└─────────────────────────────────────────────────────────────────┘

2.3 系统提示构建（System Prompt Construction）

系统提示的构建发生在 packages/core/src/core/prompts.ts 的 getCoreSystemPrompt() 函数中：

系统提示组装流程：

  ┌──────────────────────────┐
  │ 检查 GEMINI_SYSTEM_MD    │  ← 环境变量，支持自定义系统提示
  │ 环境变量                  │     默认路径: .gemini/system.md
  └────────────┬─────────────┘     设为 "0" 或 "false" 使用内建提示
               │
  ┌────────────▼─────────────┐
  │ 加载内建系统提示           │  ← 核心行为准则
  │ (Built-in System Prompt)  │     定义 CLI 智能体的角色和行为
  └────────────┬─────────────┘
               │
  ┌────────────▼─────────────┐
  │ 加载 GEMINI.md 层次       │  ← 项目特定上下文
  │ 全局 → 项目 → 子目录      │     类似 Claude Code 的 CLAUDE.md
  └────────────┬─────────────┘
               │
  ┌────────────▼─────────────┐
  │ 注入工具定义              │  ← JSON Schema 格式
  │ (Tool Definitions)       │     内建工具 + MCP 工具
  └────────────┬─────────────┘
               │
  ┌────────────▼─────────────┐
  │ 附加专用提示              │  ← 根据场景动态添加
  │ Edit Corrector /          │
  │ Loop Detector /           │
  │ Output Summarizer         │
  └──────────────────────────┘

内建系统提示的核心指令：

约定遵循：严格遵守项目现有约定（分析周围代码、测试和配置）
库验证：使用任何库前，先验证项目中已建立的使用模式（检查 package.json、Cargo.toml、imports 等）
风格一致：模仿现有的代码模式、命名约定、类型系统和架构模式
注释节制：仅在必要时添加，关注"为什么"而非"是什么"
主动执行：彻底完成请求，合理推进后续操作
歧义确认：不在未经确认的情况下扩大范围

专用辅助提示（超越核心系统提示的附加模块）：

提示模块	功能	触发条件
Edit Corrector Prompt	修正失败的文件编辑操作	编辑工具执行失败时
Tool Output Summarizer	压缩冗长的工具输出	工具输出超过阈值时
Loop Detection Prompt	检测并打断重复的工具调用序列	检测到循环模式时
Issue Triage Prompt	GitHub 工作流中的自动 Issue 分类	GitHub Actions 集成时

2.4 工具注册与执行管道（Tool Registry & Execution Pipeline）

┌──────────────────────────────────────────────────────┐
│                  ToolRegistry                         │
│                                                      │
│  工具来源：                                            │
│  ┌──────────────┐  ┌──────────────┐  ┌────────────┐ │
│  │ 内建工具      │  │ 动态发现      │  │ MCP 服务器  │ │
│  │ (Built-in)   │  │ (Discovery)  │  │ (External) │ │
│  │              │  │              │  │            │ │
│  │ ReadFile     │  │ tools.       │  │ GitHub     │ │
│  │ WriteFile    │  │ discovery    │  │ Postgres   │ │
│  │ EditTool     │  │ Command      │  │ Sentry     │ │
│  │ ShellTool    │  │ 配置         │  │ Custom...  │ │
│  │ GrepTool     │  │              │  │            │ │
│  │ GlobTool     │  │              │  │            │ │
│  │ ...          │  │              │  │            │ │
│  └──────────────┘  └──────────────┘  └────────────┘ │
│                                                      │
│  执行管道：                                            │
│  ① Gemini API 返回工具调用请求                          │
│  ② ToolRegistry 查找对应工具                           │
│  ③ 检查 ExecutionPolicy（执行策略）                     │
│     ├── 只读操作 → 自动执行                             │
│     └── 写入/命令 → 请求用户确认                        │
│  ④ 执行工具，收集结果                                   │
│  ⑤ 将结果返回给 Gemini API                            │
└──────────────────────────────────────────────────────┘

三、内建工具体系

3.1 工具总览

Gemini CLI 提供 11 个内建工具，按功能分为四类：

分类	工具	功能	需确认
文件系统	`LSTool`	列出目录内容	否
	`ReadFileTool`	读取单个文件内容	否
	`ReadManyFilesTool`	批量读取多个文件	否
	`WriteFileTool`	创建或覆写文件	是
	`EditTool`	文件局部修改	是
	`GlobTool`	按模式匹配查找文件	否
	`GrepTool`	按正则搜索文件内容	否
系统交互	`ShellTool`	执行 Shell 命令	是
网络	`WebFetchTool`	获取 URL 内容	是
	`WebSearchTool`	执行 Google 搜索	否
记忆	`MemoryTool`	管理 AI 记忆（save_memory）	否

3.2 与 Claude Code 工具的对比

功能	Gemini CLI	Claude Code
文件读取	`ReadFileTool` + `ReadManyFilesTool`	`Read`
文件写入	`WriteFileTool`	`Write`
文件编辑	`EditTool`	`Edit`
目录列表	`LSTool`（专用工具）	通过 `Bash(ls)` 实现
文件搜索	`GlobTool`	`Glob`
内容搜索	`GrepTool`	`Grep`
命令执行	`ShellTool`	`Bash`
网页获取	`WebFetchTool`	`WebFetch`
Web 搜索	`WebSearchTool`（内建 Google 搜索）	需通过 MCP
批量文件读取	`ReadManyFilesTool`（原生支持）	需多次调用 `Read`
目录列表	`LSTool`（专用）	无专用工具
记忆工具	`MemoryTool`	无（通过 CLAUDE.md 手动管理）
任务管理	无专用工具	`TodoWrite`

Gemini CLI 的独特优势：内建 Google 搜索能力和批量文件读取。

3.3 Google 搜索增强（Search Grounding）

Google 搜索增强是 Gemini CLI 最独特的内建能力之一，直接利用了 Google 的搜索基础设施：

用户提问："React 19 的最新 API 变更是什么？"
        │
        ▼
  Gemini 模型分析提问
  判断需要实时信息
        │
        ▼
  自动生成搜索查询
  调用 Google Search API
        │
        ▼
  处理搜索结果
  提取关键信息
        │
        ▼
  结合搜索结果生成响应
  附带 groundingMetadata：
    ├── 搜索查询列表
    ├── 引用来源
    └── 来源验证信息

实现特点：

模型自动判断是否需要搜索（无需显式调用）
支持所有语言的搜索
返回结果包含来源引用，减少幻觉
提供实时信息访问能力

四、上下文窗口管理

4.1 1M Token 的巨大优势

Gemini CLI 拥有 1,000,000 tokens 的上下文窗口，是 Claude Code（200K）的 5 倍：

上下文窗口对比：

Claude Code:  ████████████████████  200K tokens
Codex CLI:    ████████████████████  ~200K tokens（估计）
Gemini CLI:   ████████████████████████████████████████████████████████████████████████████████████████████████████  1M tokens

这意味着 Gemini CLI 可以一次性加载更多代码文件、更长的对话历史和更多的工具结果，在处理大型代码库时优势明显。

4.2 上下文压缩机制

尽管拥有巨大的上下文窗口，Gemini CLI 仍然需要压缩管理：

自动压缩：

基于阈值触发（默认 model.compressionThreshold = 0.5，即 50% 容量时开始考虑压缩）
将对话历史总结为精简形式
保留用户意图和系统指令

手动压缩：

bash

/compress                              # 默认压缩
/compress Focus on the authentication flow  # 带焦点提示的定向压缩

计划中的高级特性：

特性	状态	说明
工具输出自动蒸馏（Auto-distillation）	开发中	使用轻量模型自动总结大量工具输出
过时输出省略（Stale Output Elision）	开发中	折叠不再相关的工具输出
会话暂存区（Session Scratchpad）	计划中	智能体的工作记忆，在压缩后存活
状态检查点（Checkpoint State）	计划中	允许智能体声明不可变状态快照

4.3 记忆系统（Memory System）

┌────────────────────────────────────────────────────────────────┐
│                     Gemini CLI 记忆层次                         │
│                                                                │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐ │
│  │ 会话记忆      │  │ 自动记忆      │  │ GEMINI.md 项目记忆    │ │
│  │              │  │              │  │                      │ │
│  │ 对话上下文    │  │ save_memory  │  │ 全局: ~/.gemini/     │ │
│  │ 工具执行结果  │  │ 工具自动写入  │  │   GEMINI.md          │ │
│  │              │  │              │  │ 项目: ./GEMINI.md    │ │
│  │ 会话结束丢失  │  │ 写入全局     │  │ 子目录: src/         │ │
│  │              │  │ GEMINI.md    │  │   GEMINI.md          │ │
│  └──────────────┘  └──────────────┘  └──────────────────────┘ │
│                                                                │
│  管理命令：                                                     │
│  /memory show    — 显示所有记忆内容                              │
│  /memory refresh — 重新加载 GEMINI.md                           │
│  /memory add     — 追加到全局 GEMINI.md                         │
└────────────────────────────────────────────────────────────────┘

GEMINI.md 与 CLAUDE.md 的区别：

特性	GEMINI.md	CLAUDE.md
文件名可配置	是（支持 AGENTS.md、CONTEXT.md 等）	否（固定为 CLAUDE.md）
模块化导入	支持 `@file.md` 语法导入其他文件	不支持
AI 自动写入	`save_memory` 工具自动追加	需手动编辑
.gitignore 尊重	子目录扫描时遵守 .gitignore	遵守
管理命令	`/memory` 系列命令	无专用命令

自定义上下文文件名（兼容其他工具的项目）：

json

// .gemini/settings.json
{
  "context": {
    "fileName": ["AGENTS.md", "CONTEXT.md", "GEMINI.md"]
  }
}

五、权限与安全体系

5.1 执行策略（Execution Policy）

Gemini CLI 的权限控制通过 Policy Engine（策略引擎）实现：

工具调用请求
      │
      ▼
┌──────────────────┐
│  Policy Engine   │
│                  │
│  规则匹配：       │
│  ┌─────────────┐ │
│  │ 工具名      │ │ ← 按工具名匹配
│  │ 参数模式    │ │ ← 按参数内容匹配
│  │ 执行环境    │ │ ← 按运行环境匹配
│  │ 优先级排序  │ │ ← 高优先级规则先匹配
│  └─────────────┘ │
│                  │
│  决策结果：       │
│  ├── Allow       │ ← 自动执行
│  ├── Deny        │ ← 拒绝执行
│  └── Confirm     │ ← 请求用户确认
└──────────────────┘

5.2 YOLO 模式（自动批准）

YOLO（You Only Live Once）模式是 Gemini CLI 的特色功能，允许跳过所有确认提示：

bash

# 启动方式 1：命令行标志
gemini --yolo "修复所有 lint 错误"
gemini -y "重构这个模块"

# 启动方式 2：环境变量（持久化）
export GEMINI_YOLO_MODE=true

# 启动方式 3：配置文件
# ~/.gemini/settings.json
{ "yolo": true }

# 启动方式 4：会话内切换
# 按 Ctrl+Y 随时切换 YOLO 模式开/关

安全建议：YOLO 模式跳过所有确认（包括文件修改、Shell 命令、网络请求），仅在隔离环境或充分信任的场景下使用。推荐先在普通模式下审查计划，确认方向正确后再按 Ctrl+Y 切换为 YOLO 模式进行批量执行。

5.3 `--allowed-tools` 精细控制

介于默认模式（全部确认）和 YOLO 模式（全部跳过）之间的折中方案：

bash

# 仅信任特定工具
gemini --allowed-tools "ReadFileTool,GlobTool,GrepTool"

也可在 settings.json 中配置 allowedTools 列表。

5.4 多层沙箱隔离

Gemini CLI 提供业界最丰富的沙箱选项，按平台和隔离强度分层：

Linux 平台

沙箱方案	隔离强度	实现原理	依赖
gVisor	最强	用户空间内核拦截所有系统调用，在 Go 编写的沙箱内核中处理	Docker + runsc 运行时
LXC/LXD	强	完整系统容器沙箱（含 systemd/snapd），工作区通过 bind mount 挂载	LXC 容器需预创建
bubblewrap + seccomp	中	bubblewrap 限制文件系统访问，seccomp 限制系统调用	bubblewrap 包

bubblewrap 禁止路径实现：

对于每个 forbiddenPath：
  ├── 如果是目录 → 用空的只读 tmpfs 覆盖 (--ro-bind-try)
  └── 如果是文件 → 用 /dev/null 覆盖

macOS 平台

使用内建 Seatbelt 沙箱：

通过 sandbox-exec 执行，使用动态生成的安全配置文件
限制项目目录外的文件写入
forbiddenPaths 通过在配置文件末尾追加显式 deny 规则实现：
```
(deny file-read* file-write* (subpath "/path/to/forbidden"))
```
1
deny 规则严格在 allow 规则之后应用

Windows 平台

使用 icacls 设置完整性级别：

对文件/目录设置"低强制级别"（Low Mandatory Level）
forbiddenPaths 通过注入 Deny ACE（访问控制条目）实现，目标为 Low Mandatory Level SID（*S-1-16-4096）

跨平台一致性

forbiddenPaths 字段在 ExecutionPolicy 中统一定义，各平台沙箱管理器通过各自的 OS 原生机制实现。共享工具函数（如 tryRealpath）提供一致的符号链接解析和错误处理。

六、子智能体系统（Subagents）

6.1 声明式智能体框架

Gemini CLI 的子智能体基于声明式智能体框架（Declarative Agent Framework），核心组件：

┌────────────────────────────────────────────────────────┐
│                Declarative Agent Framework              │
│                                                        │
│  ┌─────────────────┐    ┌─────────────────┐            │
│  │ AgentDefinition │    │ AgentExecutor   │            │
│  │                 │    │                 │            │
│  │ • name          │    │ 工作阶段：       │            │
│  │ • description   │    │ ① 迭代式工具调用 │            │
│  │ • systemPrompt  │    │   (Work Phase)  │            │
│  │ • tools[]       │    │                 │            │
│  │ • processOutput │    │ 提取阶段：       │            │
│  │ • maxTurns      │    │ ② 综合发现结果   │            │
│  │ • thinkingBudget│    │   (Extraction)  │            │
│  └────────┬────────┘    └────────┬────────┘            │
│           │                      │                     │
│  ┌────────▼──────────────────────▼────────┐            │
│  │          SubagentToolWrapper            │            │
│  │                                        │            │
│  │  将 AgentDefinition 包装为可调用的工具   │            │
│  │  动态生成 JSON Schema                   │            │
│  │  注册到主智能体的工具列表                 │            │
│  └────────────────────────────────────────┘            │
│                                                        │
│  ┌────────────────────────────────────────┐            │
│  │          AgentRegistry                  │            │
│  │                                        │            │
│  │  管理所有可用的智能体定义                  │            │
│  │  支持 /agents list/enable/disable       │            │
│  └────────────────────────────────────────┘            │
└────────────────────────────────────────────────────────┘

AgentExecutor 的双阶段执行：

工作阶段（Work Phase）：子智能体在独立上下文中进行迭代式工具调用，探索代码库、执行命令等
提取阶段（Extraction Phase）：将工作阶段的发现综合为结构化报告返回给主对话

6.2 内建子智能体

子智能体	功能	调用方式	工具权限
Codebase Investigator	复杂的多步骤代码分析、依赖逆向、架构理解	自动委派 / `@codebase_investigator`	只读工具
Generalist Agent	通用任务路由，将任务分发给合适的专业子智能体	默认启用	全部工具
CLI Help Agent	提供 Gemini CLI 自身的使用帮助和专业知识	自动 / `@cli_help`	只读
Browser Agent	自动化 Web 浏览器任务（表单填写、信息提取等）	`@browser_agent`	浏览器工具

6.3 Codebase Investigator 详解

Codebase Investigator 是 Gemini CLI 最具特色的子智能体，专为复杂的代码库分析设计：

输入："我们的缓存层是如何工作的？"
        │
        ▼
  ┌──────────────────────────┐
  │  Codebase Investigator   │
  │                          │
  │  独立上下文窗口            │
  │  可配置最大轮次            │
  │  可配置思考预算            │
  │  可选模型                 │
  │                          │
  │  执行过程：                │
  │  ① 分析问题，制定探索策略  │
  │  ② 使用 Grep/Glob 搜索   │
  │  ③ 读取关键文件           │
  │  ④ 追踪调用链和依赖关系   │
  │  ⑤ 综合发现生成报告        │
  └──────────────────────────┘
        │
        ▼
  返回结构化报告：
  ├── 摘要（Summary）
  ├── 完整探索轨迹（Exploration Trace）
  └── 关键代码分析（Critical Code Analysis）

配置选项（settings.json）：

json

{
  "agents": {
    "codebase_investigator": {
      "enabled": true,
      "maxTurns": 20,
      "model": "gemini-2.5-pro",
      "thinkingBudget": 8192
    }
  }
}

6.4 子智能体管理

bash

/agents list      # 列出所有可用子智能体及其状态
/agents enable <name>   # 启用子智能体
/agents disable <name>  # 禁用子智能体
/agents config         # 查看子智能体配置
/agents reload         # 重新加载子智能体定义

七、Plan Mode（计划模式）

7.1 工作原理

Plan Mode 自 2026 年 3 月起默认启用，要求 AI 在执行任何修改操作前先呈现完整的执行计划供用户审查：

用户请求："给用户模块添加邮箱验证功能"
        │
        ▼
  ┌──────────────────────────┐
  │  Plan Mode 工作流         │
  │                          │
  │  ① 分析请求              │
  │  ② 探索代码库             │
  │  ③ 生成执行计划           │
  │     • 修改哪些文件         │
  │     • 每个文件的变更内容    │
  │     • 执行顺序和依赖关系   │
  │     • 可能的风险和注意事项  │
  │  ④ 呈现计划给用户审查      │
  └────────────┬─────────────┘
               │
          用户审查
          ├── 批准 → 按计划执行
          ├── 修改 → 调整计划后重新审查
          └── 拒绝 → 终止

7.2 计划持久化

Plan Mode 的一个重要特性：已批准的计划在上下文压缩（chat compression）后仍然保留。这解决了长会话中因自动压缩导致的"中途迷失"问题——即使对话历史被压缩总结，智能体仍然记得已批准的执行计划并继续执行。

八、会话管理与检查点

8.1 会话检查点（Checkpointing）

bash

# 保存当前会话
/chat save my-feature-work

# 列出所有检查点
/chat list

# 恢复到指定检查点
/chat resume my-feature-work
# 或
/resume my-feature-work

# 删除检查点
/chat delete my-feature-work

# 分享会话（生成可分享的摘要）
/chat share

# 调试会话状态
/chat debug

存储位置：

Linux/macOS：~/.gemini/tmp/<project_hash>/
每个检查点包含完整的对话历史、工具结果和上下文状态

8.2 文件恢复

bash

/restore    # 将项目文件恢复到工具执行前的状态

这是一个安全网机制——如果智能体的修改结果不满意，可以一键回退所有文件变更。

九、终端 UI 与交互体验

9.1 主题系统

Gemini CLI 提供丰富的预定义主题和完整的自定义能力：

预定义主题：

类型	主题
暗色	ANSI、Atom One、Ayu、Default（默认）、Dracula、GitHub Dark
亮色	ANSI Light、Ayu Light、Default Light、GitHub Light、Google Code、Xcode

自动主题切换：

json

// settings.json
{
  "ui": {
    "autoThemeSwitching": true  // 根据终端背景色自动切换亮/暗主题
  }
}

自定义主题：

json

// settings.json
{
  "theme": {
    "custom": {
      "Background": "#1a1b26",
      "Foreground": "#c0caf5",
      "AccentBlue": "#7aa2f7",
      "AccentGreen": "#9ece6a",
      "AccentRed": "#f7768e",
      "AccentYellow": "#e0af68",
      "AccentCyan": "#7dcfff",
      "AccentMagenta": "#bb9af7"
    }
  }
}

9.2 Vim 模式

Gemini CLI 原生支持 Vim 编辑模式：

json

// settings.json
{
  "general": {
    "vimMode": true
  }
}

支持的 Vim 功能（v0.35.0+）：

基础移动：h/j/k/l、w/b/e/0/$
字符操作：x（删除）、~（切换大小写）、r（替换）
查找移动：f/F/t/T（行内查找）
复制粘贴：y（yank）、p（paste），使用无名寄存器
模式切换：i/a/I/A/o/O（进入插入模式）、Esc/Ctrl+[（返回普通模式）

9.3 键盘快捷键

快捷键	功能	场景
`Ctrl+C`	中断当前操作	通用
`Ctrl+D`	退出 Gemini CLI	通用
`Ctrl+L`	清屏	通用
`Ctrl+Y`	切换 YOLO 模式	通用
`Ctrl+S`	保存会话	通用
`Ctrl+T`	切换主题	通用
`Ctrl+O`	打开文件	通用
`Ctrl+V`	粘贴（支持图片）	输入区
`Ctrl+X`	打开外部编辑器	输入区
`Ctrl+A` / `Ctrl+E`	行首 / 行尾	输入区
`Ctrl+U` / `Ctrl+K`	删除到行首 / 行尾	输入区
`Tab`	自动补全	建议面板
`1-9`	快速选择建议	建议面板

可定制快捷键（v0.35.0+）：支持字面字符绑定和 Kitty 扩展终端协议键。

9.4 动态窗口标题

终端窗口标题会根据状态动态变化：

图标	状态
◇	Ready（就绪）
✋	Action Required（需要用户操作）
✦	Working（工作中）

十、MCP（Model Context Protocol）集成

10.1 MCP 架构

┌─────────────────────────────────────────────────────────────┐
│                    Gemini CLI MCP 集成                       │
│                                                             │
│  ┌─────────────────┐                                        │
│  │  Discovery Layer │  发现层                                │
│  │                  │                                       │
│  │  遍历配置的服务器 │                                       │
│  │  建立连接        │                                       │
│  │  获取工具定义    │                                        │
│  │  注册到全局注册表 │                                       │
│  └────────┬────────┘                                        │
│           │                                                 │
│  ┌────────▼────────┐                                        │
│  │  Execution Layer │  执行层                                │
│  │                  │                                       │
│  │  处理确认逻辑    │                                        │
│  │  调用 MCP 服务器 │                                        │
│  │  处理响应格式    │                                        │
│  └─────────────────┘                                        │
│                                                             │
│  传输机制：                                                   │
│  ├── Stdio  — 通过 stdin/stdout 与本地子进程通信（最常用）     │
│  ├── SSE    — Server-Sent Events（已废弃）                   │
│  └── HTTP   — HTTP 流式传输（远程服务推荐）                    │
└─────────────────────────────────────────────────────────────┘

10.2 MCP 暴露的三种资源类型

类型	说明	在 Gemini CLI 中的使用
Prompts	预定义提示模板	作为斜杠命令使用
Resources	数据源	Gemini 可读取的外部数据
Tools	可调用函数	注册为智能体可调用的工具

10.3 配置示例

json

// ~/.gemini/settings.json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"],
      "env": {}
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "$GITHUB_TOKEN"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "$DATABASE_URL"
      }
    }
  }
}

10.4 MCP 管理命令

bash

/mcp desc      # 显示已连接 MCP 服务器的工具描述
/mcp nodesc    # 隐藏工具描述
/mcp schema    # 显示工具的 JSON Schema

十一、扩展思考（Extended Thinking）

11.1 实现方式

Gemini CLI 通过 thinkingConfig 支持扩展思考：

json

// settings.json 中的模型配置
{
  "model": {
    "name": "gemini-2.5-pro",
    "thinkingConfig": {
      "level": "HIGH"   // LOW / MEDIUM / HIGH
    }
  }
}

11.2 思考级别

级别	延迟影响	适用场景
LOW	最低	简单查询、直接的代码生成
MEDIUM	中等	一般的代码分析和重构
HIGH	最高	复杂的架构决策、深度调试、安全审查

Gemini 3 模型默认使用 HIGH 模式。对于简单查询，建议切换到 LOW 或 MEDIUM 以减少不必要的延迟。

11.3 与子智能体的集成

Codebase Investigator 子智能体可以独立配置 thinkingBudget（思考 Token 预算），使其在进行复杂代码分析时拥有更多的推理空间，而不影响主对话的思考配置。

十二、配置体系

12.1 配置层次（优先级从低到高）

① 默认值（Default values）
    │
② 系统默认配置（/etc/gemini-cli/system-defaults.json）
    │
③ 用户配置（~/.gemini/settings.json）
    │
④ 项目配置（.gemini/settings.json）
    │
⑤ 系统强制配置（/etc/gemini-cli/settings.json）
    │
⑥ 环境变量（GEMINI_* 等）
    │
⑦ 命令行参数（--yolo, --model 等）  ← 最高优先级

12.2 关键配置项

json

// ~/.gemini/settings.json 完整示例
{
  // 模型配置
  "model": {
    "name": "gemini-2.5-pro",
    "compressionThreshold": 0.5,
    "thinkingConfig": { "level": "MEDIUM" }
  },

  // 通用设置
  "general": {
    "vimMode": false
  },

  // UI 设置
  "ui": {
    "theme": "dracula",
    "autoThemeSwitching": true
  },

  // 上下文配置
  "context": {
    "fileName": ["GEMINI.md", "AGENTS.md"]
  },

  // 子智能体配置
  "agents": {
    "codebase_investigator": {
      "enabled": true,
      "maxTurns": 20
    },
    "generalist_agent": {
      "enabled": true
    }
  },

  // MCP 服务器
  "mcpServers": {},

  // 权限
  "allowedTools": [],
  "yolo": false
}

12.3 环境变量支持

配置文件中支持通过 $VAR_NAME 或 ${VAR_NAME} 语法引用环境变量，避免在配置文件中硬编码敏感信息。

十三、完整斜杠命令参考

命令	功能	子命令
`/help` 或 `/?`	显示帮助信息	—
`/about`	显示版本信息	—
`/clear`	清屏	—
`/compress`	压缩上下文	可附加焦点提示
`/memory`	管理记忆	`show` / `refresh` / `add <text>`
`/chat`	会话管理	`save` / `resume` / `list` / `delete` / `share` / `debug`
`/resume`	恢复会话	同 `/chat`
`/stats`	显示会话统计	Token 用量、缓存节省、会话时长
`/agents`	管理子智能体	`list` / `reload` / `enable` / `disable` / `config`
`/mcp`	管理 MCP 服务器	`desc` / `nodesc` / `schema`
`/restore`	恢复文件到修改前状态	—
`/directory`	管理工作区目录	`add` / `show`
`/extensions`	列出活跃扩展	—
`/tools`	管理工具	—
`/editor`	选择外部编辑器	—
`/theme`	切换主题	—
`/auth`	切换认证方式	—
`/bug`	提交 Bug 报告	—
`/copy`	复制内容到剪贴板	—

十四、安装与认证

14.1 多种安装方式

bash

# npm 全局安装
npm install -g @anthropic-ai/gemini-cli

# Homebrew (macOS/Linux)
brew install gemini-cli

# MacPorts
sudo port install gemini-cli

# Anaconda
conda install -c conda-forge gemini-cli

# 免安装运行
npx @anthropic-ai/gemini-cli

14.2 认证方式

方式	适用场景	免费额度
个人 Google 账号	个人开发者	60 次/分钟，1000 次/天
AI Studio API Key	按量付费	取决于配额
Vertex AI	企业/GCP 用户	取决于配额

十五、与 Claude Code 的关键差异

维度	Gemini CLI	Claude Code
开源程度	完全开源（Apache 2.0）	SDK 开源，CLI 部分开源
上下文窗口	1M tokens（5x）	200K tokens
免费额度	1000 次/天	无免费额度
Web 搜索	内建 Google 搜索	需 MCP 扩展
Vim 模式	原生支持	不支持
主题系统	丰富的主题 + 自定义	基础终端样式
沙箱选项	gVisor/LXC/bubblewrap/Seatbelt	Seatbelt/bubblewrap
子智能体框架	声明式框架 + AgentExecutor	Task 工具 + 固定子智能体
系统提示	可完全替换（GEMINI_SYSTEM_MD）	不可替换，仅可追加
记忆管理	save_memory 工具自动写入	手动编辑 CLAUDE.md
文件恢复	`/restore` 一键回退	需手动 Git 操作
推理质量	8.3/10	9.0/10
Hooks 系统	无（通过 MCP 扩展）	22+ 生命周期事件
IDE 集成	终端原生	VS Code + JetBrains

十六、总结

Gemini CLI 的核心定位可以用三个词概括：开源、慷慨、可扩展。

架构层面：它采用清晰的前后端分离（CLI 包 + Core 包），使核心逻辑可以独立复用。声明式智能体框架（AgentDefinition + AgentExecutor + SubagentToolWrapper）让子智能体的定义和管理变得声明式和可配置。

差异化优势：

1M token 上下文窗口使其在大型代码库分析场景中独具优势
Google 搜索内建集成提供了其他工具需要额外配置 MCP 才能获得的实时信息能力
完全开源意味着社区可以审查、贡献和定制每一行代码
多层沙箱方案（gVisor/LXC/bubblewrap/Seatbelt）提供了从轻量到重量级的完整安全隔离选项
免费额度（1000 次/天）极大降低了 AI 编程智能体的使用门槛

需要改进的方面：

推理质量（8.3/10）仍落后于 Claude Code（9.0/10）
上下文压缩系统仍在演进中（auto-distillation、session scratchpad 等功能尚在开发）
缺少类似 Claude Code Hooks 的确定性生命周期自动化机制
部分功能（Browser Agent、LXC 沙箱）仍处于实验阶段

Gemini CLI 代表了 AI 编程工具"开放、平民化"的方向——通过开源代码、慷慨的免费额度和丰富的定制能力，让每一个开发者都能平等地获得 AI 编程智能体的能力。

docs

hook

watcher

Gemini CLI 深度解析：功能介绍与实现原理 ​

一、概述 ​

二、核心架构与实现原理 ​

2.1 Monorepo 模块化架构 ​

2.2 智能体循环（Agent Loop） ​

2.3 系统提示构建（System Prompt Construction） ​

2.4 工具注册与执行管道（Tool Registry & Execution Pipeline） ​

三、内建工具体系 ​

3.1 工具总览 ​

3.2 与 Claude Code 工具的对比 ​

3.3 Google 搜索增强（Search Grounding） ​

四、上下文窗口管理 ​

4.1 1M Token 的巨大优势 ​

4.2 上下文压缩机制 ​

4.3 记忆系统（Memory System） ​

五、权限与安全体系 ​

5.1 执行策略（Execution Policy） ​

5.2 YOLO 模式（自动批准） ​

5.3 --allowed-tools 精细控制 ​

5.4 多层沙箱隔离 ​

Linux 平台 ​

macOS 平台 ​

Windows 平台 ​

跨平台一致性 ​

六、子智能体系统（Subagents） ​

6.1 声明式智能体框架 ​

6.2 内建子智能体 ​

6.3 Codebase Investigator 详解 ​

6.4 子智能体管理 ​

七、Plan Mode（计划模式） ​

7.1 工作原理 ​

7.2 计划持久化 ​

八、会话管理与检查点 ​

8.1 会话检查点（Checkpointing） ​

8.2 文件恢复 ​

九、终端 UI 与交互体验 ​

9.1 主题系统 ​

9.2 Vim 模式 ​

9.3 键盘快捷键 ​

9.4 动态窗口标题 ​

十、MCP（Model Context Protocol）集成 ​

10.1 MCP 架构 ​

10.2 MCP 暴露的三种资源类型 ​

10.3 配置示例 ​

10.4 MCP 管理命令 ​

十一、扩展思考（Extended Thinking） ​

11.1 实现方式 ​

11.2 思考级别 ​

11.3 与子智能体的集成 ​

十二、配置体系 ​

12.1 配置层次（优先级从低到高） ​

12.2 关键配置项 ​

12.3 环境变量支持 ​

十三、完整斜杠命令参考 ​

十四、安装与认证 ​

14.1 多种安装方式 ​

14.2 认证方式 ​

十五、与 Claude Code 的关键差异 ​

十六、总结 ​

Gemini CLI 深度解析：功能介绍与实现原理

一、概述

二、核心架构与实现原理

2.1 Monorepo 模块化架构

2.2 智能体循环（Agent Loop）

2.3 系统提示构建（System Prompt Construction）

2.4 工具注册与执行管道（Tool Registry & Execution Pipeline）

三、内建工具体系

3.1 工具总览

3.2 与 Claude Code 工具的对比

3.3 Google 搜索增强（Search Grounding）

四、上下文窗口管理

4.1 1M Token 的巨大优势

4.2 上下文压缩机制

4.3 记忆系统（Memory System）

五、权限与安全体系

5.1 执行策略（Execution Policy）

5.2 YOLO 模式（自动批准）

5.3 `--allowed-tools` 精细控制

5.4 多层沙箱隔离

Linux 平台

macOS 平台

Windows 平台

跨平台一致性

六、子智能体系统（Subagents）

6.1 声明式智能体框架

6.2 内建子智能体

6.3 Codebase Investigator 详解

6.4 子智能体管理

七、Plan Mode（计划模式）

7.1 工作原理

7.2 计划持久化

八、会话管理与检查点

8.1 会话检查点（Checkpointing）

8.2 文件恢复

九、终端 UI 与交互体验

9.1 主题系统

9.2 Vim 模式

9.3 键盘快捷键

9.4 动态窗口标题

十、MCP（Model Context Protocol）集成

10.1 MCP 架构

10.2 MCP 暴露的三种资源类型

10.3 配置示例

10.4 MCP 管理命令

十一、扩展思考（Extended Thinking）

11.1 实现方式

11.2 思考级别

11.3 与子智能体的集成

十二、配置体系

12.1 配置层次（优先级从低到高）

12.2 关键配置项

12.3 环境变量支持

十三、完整斜杠命令参考

十四、安装与认证

14.1 多种安装方式

14.2 认证方式

十五、与 Claude Code 的关键差异

十六、总结