# https://github.com/google-gemini/gemini-cli 项目说明书
生成时间：2026-05-13 09:42:22 UTC
## 目录
- [项目概述](#page-overview)
- [安装与配置](#page-installation)
- [系统架构](#page-architecture)
- [包结构详解](#page-package-structure)
- [核心工具集](#page-tools)
- [代理系统与子代理](#page-agent-system)
- [上下文管理与压缩](#page-context-management)
- [CLI用户界面](#page-cli-ui)
- [命令系统](#page-commands)
- [安全策略与策略引擎](#page-security-policy)
## 项目概述
### 相关页面
相关主题：[安装与配置](#page-installation), [系统架构](#page-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/google-gemini/gemini-cli/blob/main/README.md)
- [packages/cli/src/ui/components/AboutBox.tsx](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/ui/components/AboutBox.tsx)
- [packages/cli/src/ui/components/AppHeader.tsx](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/ui/components/AppHeader.tsx)
- [packages/core/src/agents/skill-extraction-agent.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/agents/skill-extraction-agent.ts)
- [packages/core/src/services/chatRecordingService.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/services/chatRecordingService.ts)
- [packages/core/src/skills/builtin/skill-creator/SKILL.md](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/skills/builtin/skill-creator/SKILL.md)
# 项目概述
## 项目简介
Gemini CLI 是由 Google 开发的一款命令行工具，它将 Gemini AI 的强大能力直接带到终端环境中。通过自然语言交互，开发者可以在不离开命令行界面的情况下完成代码理解、生成、调试以及自动化任务执行等多种工作。资料来源：[README.md:1-50]()
该项目采用 TypeScript/Node.js 构建，支持多平台运行（Windows、macOS、Linux），并提供 npm、Homebrew、MacPorts 和 Conda 等多种安装方式。资料来源：[README.md:150-200]()
## 系统架构
Gemini CLI 采用模块化架构设计，主要由以下几个核心包组成：
| 包名称 | 职责描述 |
|--------|----------|
| `packages/cli` | 命令行界面实现，包含 UI 组件、用户交互和身份验证 |
| `packages/core` | 核心业务逻辑，包含 Agent 系统、技能管理和上下文管理 |
| `packages/devtools` | 开发工具组件，提供调试和网络请求分析功能 |
```mermaid
graph TD
A[用户终端] --> B[CLI 入口层]
B --> C[UI 组件层]
C --> D[核心业务层]
D --> E[Agent 代理层]
E --> F[模型服务层]
E --> G[技能系统层]
E --> H[上下文管理]
F --> I[Gemini API]
G --> J[本地技能存储]
H --> K[对话记录服务]
```
资料来源：[packages/cli/src/gemini.tsx](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/gemini.tsx)
## 核心功能模块
### 1. 用户界面系统
Gemini CLI 提供了一个功能丰富的终端用户界面，使用 React 风格组件构建。主要界面组件包括：
**头部组件 (AppHeader)**
显示应用状态信息，包括版本号、更新状态和用户身份信息。资料来源：[packages/cli/src/ui/components/AppHeader.tsx:1-80]()
```typescript
// AppHeader 核心数据结构
interface AppHeaderProps {
showHeader: boolean;
showDetails: boolean;
config: Settings;
updateInfo?: UpdateInfo;
bannerVisible: boolean;
bannerText?: string;
}
```
**关于对话框 (AboutBox)**
展示详细的系统信息，包括 CLI 版本、Git 提交信息、当前使用的模型、沙箱环境配置和操作系统信息。资料来源：[packages/cli/src/ui/components/AboutBox.tsx:1-60]()
### 2. 认证与隐私系统
认证流程通过 `AuthDialog` 组件管理，支持多种认证方式。用户首次使用时会看到服务条款和隐私声明提示。资料来源：[packages/cli/src/ui/auth/AuthDialog.tsx:1-80]()
隐私声明文件包括：
- **GeminiPrivacyNotice.tsx** - Gemini API 隐私条款
- **CloudFreePrivacyNotice.tsx** - 免费服务隐私通知
这些组件向用户明确说明数据收集范围和使用目的，包括人类审阅者可能阅读处理数据以提升产品质量的机制。资料来源：[packages/cli/src/ui/privacy/CloudFreePrivacyNotice.tsx:1-50]()
### 3. 技能（Skills）系统
技能系统是 Gemini CLI 的核心扩展机制，允许用户创建和管理可重用的任务模板。
**技能创建器 (Skill Creator)**
内置的技能创建器指导用户如何构建高质量技能。一个完整的技能包包含以下结构：资料来源：[packages/core/src/skills/builtin/skill-creator/SKILL.md:1-100]()
```
skill-name/
├── SKILL.md # 必需：技能定义和触发条件
├── scripts/ # 可选：确定性执行脚本
├── references/ # 可选：参考文档
└── assets/ # 可选：资源文件
```
**技能提取代理 (Skill Extraction Agent)**
智能地从对话历史中提取有价值的工作流程，并将其转换为可重用的技能。该代理使用结构化的 patch 格式来记录文件变更。资料来源：[packages/core/src/agents/skill-extraction-agent.ts:1-50]()
### 4. 对话录制服务
`ChatRecordingService` 负责管理会话历史，支持会话的保存、加载和恢复。每个会话记录包含：资料来源：[packages/core/src/services/chatRecordingService.ts:1-80]()
| 字段 | 类型 | 说明 |
|------|------|------|
| sessionId | string | 会话唯一标识符 |
| projectHash | string | 项目哈希值 |
| startTime | string | 会话开始时间 |
| lastUpdated | string | 最后更新时间 |
| messages | Message[] | 完整消息历史 |
| memoryScratchpad | string | 记忆便签内容 |
```mermaid
graph LR
A[用户对话] --> B[ChatRecordingService]
B --> C[JSONL 文件存储]
D[会话恢复] --> B
B --> E[上下文加载]
E --> F[Agent 处理]
```
### 5. 上下文图构建
`toGraph.ts` 模块负责将对话历史转换为结构化的上下文图，支持消息去重和历史追溯。系统通过 MD5 哈希生成稳定的轮次标识，确保相同内容的消息能够被正确识别。资料来源：[packages/core/src/context/graph/toGraph.ts:1-80]()
### 6. 扩展系统
Gemini CLI 支持 MCP（Model Context Protocol）扩展，允许第三方开发者扩展功能。扩展详情界面 (`ExtensionDetails`) 显示每个扩展的版本、星级、Google 拥有标识以及支持的特性标签。资料来源：[packages/cli/src/ui/components/views/ExtensionDetails.tsx:1-100]()
## 主要功能特性
### 代码理解与生成
- 查询和编辑大型代码库
- 使用多模态能力从 PDF、图片或草图生成新应用
- 使用自然语言调试和排除问题
### 自动化与集成
- 自动化运维任务，如查询 Pull Request 或处理复杂变基
- 通过 MCP 服务器连接新能力，包括使用 Imagen、Veo 或 Lyria 进行媒体生成
- 在脚本中非交互式运行，实现工作流自动化
### 高级能力
- 内置 Google Search 集成，获取实时信息
- 对话检查点功能，保存和恢复复杂会话
- 自定义上下文文件（GEMINI.md），为项目定制行为
### GitHub 集成
可通过 Gemini CLI GitHub Action 直接将 Gemini CLI 集成到 GitHub 工作流中。资料来源：[README.md:80-120]()
## 发布渠道
| 渠道 | 发布频率 | 特点 |
|------|----------|------|
| Preview | 每周二 UTC 23:59 | 未经完全验证，可能存在回归问题 |
| Stable | 每周二 UTC 20:00 | 经过验证的稳定版本 |
| Nightly | 每日 UTC 00:00 | 主分支最新变更，可能包含未解决问题 |
资料来源：[README.md:180-220]()
## 安装方式
Gemini CLI 支持多种安装途径：
| 安装方式 | 命令 |
|----------|------|
| npm 全局安装 | `npm install -g @google/gemini-cli` |
| Homebrew | `brew install gemini-cli` |
| MacPorts | `sudo port install gemini-cli` |
| Conda 环境 | 通过 conda 环境安装 nodejs 后使用 npm |
资料来源：[README.md:140-170]()
## 技术栈概览
- **运行时**: Node.js
- **UI 框架**: React + TypeScript
- **终端渲染**: Ink（React for CLI）
- **包管理**: npm workspaces
- **语言**: TypeScript
---
## 安装与配置
### 相关页面
相关主题：[项目概述](#page-overview)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/google-gemini/gemini-cli/blob/main/README.md)
- [packages/cli/src/ui/auth/AuthDialog.tsx](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/ui/auth/AuthDialog.tsx)
- [packages/cli/src/ui/auth/LoginRestartDialog.tsx](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/ui/auth/LoginRestartDialog.tsx)
- [packages/cli/src/ui/components/AboutBox.tsx](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/ui/components/AboutBox.tsx)
# 安装与配置
Gemini CLI 是 Google 开发的命令行工具，为开发者提供基于 AI 的代码理解和生成能力。本页面详细介绍 Gemini CLI 的多种安装方式、认证配置以及基础设置，帮助用户快速上手使用。
## 系统要求
在开始安装之前，请确保系统满足以下要求：
| 要求项 | 说明 |
|--------|------|
| Node.js | 推荐 Node.js 18.x 或更高版本 |
| 包管理器 | npm、yarn 或 pnpm |
| 操作系统 | macOS、Linux、Windows |
| 网络 | 能够访问 npm registry 和 Google AI 服务 |
## 安装方式
Gemini CLI 支持多种安装方式，用户可根据自身环境选择最适合的方法。
### 通过 npm 全局安装
最直接的安装方式是通过 npm 进行全局安装：
```bash
npm install -g @google/gemini-cli
```
资料来源：[README.md:1]()
### 通过 Homebrew 安装（macOS/Linux）
macOS 和 Linux 用户可使用 Homebrew 进行安装：
```bash
brew install gemini-cli
```
资料来源：[README.md:1]()
### 通过 MacPorts 安装（macOS）
macOS 用户也可选择 MacPorts 方式：
```bash
sudo port install gemini-cli
```
资料来源：[README.md:1]()
### 通过 Anaconda 安装（受限环境）
对于受限环境，Anaconda 提供了隔离的安装方案：
```bash
# 创建并激活新环境
conda create -y -n gemini_env -c conda-forge nodejs
conda activate gemini_env
# 在环境内通过 npm 全局安装 Gemini CLI
npm install -g @google/gemini-cli
```
资料来源：[README.md:1]()
## 发布渠道
Gemini CLI 提供三种发布渠道，用户可根据需求选择不同的版本。
### 预览版（Preview）
新的预览版本每周二 UTC 23:59 发布，这些版本可能包含回归问题或其他待解决的问题。适合希望测试最新功能的用户：
```bash
npm install -g @google/gemini-cli@preview
```
资料来源：[README.md:1]()
### 稳定版（Stable）
新的稳定版本每周二 UTC 20:00 发布，这是对上周预览版的完整升级，并包含所有 bug 修复和验证：
```bash
npm install -g @google/gemini-cli@latest
```
资料来源：[README.md:1]()
### 夜间版（Nightly）
每日 UTC 00:00 发布，包含主分支的所有最新更改：
```bash
npm install -g @google/gemini-cli@nightly
```
资料来源：[README.md:1]()
## 认证配置
首次使用 Gemini CLI 时需要进行身份验证。工具支持多种认证方式。
### 认证方式选择
启动 Gemini CLI 后，系统会显示认证对话框，提示选择认证方式：
```bash
gemini
```
认证界面会展示以下选项供用户选择：
- Google 账号登录
- API Key 认证（适用于企业用户）
- 其他认证方式
用户可使用 Enter 键进行选择。资料来源：[AuthDialog.tsx:1]()
### Google 登录流程
选择 Google 账号登录后，系统会显示登录进度：
```
使用 Google 账号登录中... 正在重启 Gemini CLI 以继续。
```
登录成功后需要重启 CLI 以完成认证流程：
```
您已成功使用 Google 账号登录。Gemini CLI 需要重新启动。
请按 R 重启，或按 Esc 选择其他认证方式。
```
资料来源：[LoginRestartDialog.tsx:1]()
### 服务条款与隐私声明
在认证过程中，用户需要阅读并同意以下服务条款：
| 条款 | 链接 |
|------|------|
| Gemini API 概述 | https://ai.google.dev/docs/gemini_api_overview |
| AI Studio 服务条款 | https://aistudio.google.com/ |
| Google 开发者服务条款 | https://developers.google.com/terms |
| Gemini API 附加服务条款 | https://ai.google.dev/gemini-api/terms |
资料来源：[packages/cli/src/ui/privacy/GeminiPrivacyNotice.tsx:1]()
### 数据收集与隐私
Gemini CLI 会收集以下数据用于改进产品和服务：
- 您的提示词及相关代码
- 生成的输出和代码编辑
- 相关功能使用信息
- 您的反馈
为确保质量并改进产品，人工审核员可能会阅读、标注和处理收集的数据。Google 会采取措施在审核前断开数据与 Google 账号的关联，存储期限最长为 18 个月。
资料来源：[packages/cli/src/ui/privacy/CloudFreePrivacyNotice.tsx:1]()
## 配置文件
### 设置文件位置
Gemini CLI 的配置文件位于用户主目录下的 `~/.gemini/settings.json`。此文件可自定义工具的各种行为和选项。
资料来源：[README.md:1]()
### MCP 服务器配置
通过 MCP（Model Context Protocol）服务器配置，可以扩展 Gemini CLI 的功能：
```json
{
"mcpServers": {
"@github": {},
"@slack": {},
"@database": {}
}
}
```
配置后即可在对话中使用 MCP 服务器功能：
```
> @github 列出我的开放拉取请求
> @slack 发送今日提交的摘要到 #dev 频道
> @database 运行查询以查找非活跃用户
```
资料来源：[README.md:1]()
## 验证安装
安装完成后，可通过以下方式验证安装是否成功并查看版本信息。
### 查看版本信息
```bash
gemini --version
```
或启动交互式会话后，在关于对话框中查看：
| 信息项 | 说明 |
|--------|------|
| CLI 版本 | 当前安装的版本号 |
| Git 提交 | 源代码的 Git 提交哈希 |
| 模型 | 当前使用的 AI 模型 |
| 沙盒环境 | 沙盒配置信息 |
| 操作系统 | 当前操作系统信息 |
资料来源：[AboutBox.tsx:1]()
### 快速测试
创建测试目录并启动 Gemini CLI：
```bash
cd new-project/
gemini
> 写一个简单的问候程序
```
如果程序能够正常响应，说明安装和配置均已成功。
资料来源：[README.md:1]()
## 卸载指南
如需卸载 Gemini CLI，请参阅官方卸载指南：https://www.geminicli.com/docs/resources/uninstall
资料来源：[README.md:1]()
## 故障排除
### 常见安装问题
| 问题 | 解决方案 |
|------|----------|
| 权限错误 | 使用 `sudo` 或配置 npm 全局路径 |
| Node.js 版本不兼容 | 升级到 Node.js 18.x 或更高版本 |
| 网络连接失败 | 检查代理设置或使用国内镜像 |
### 认证问题
如果认证过程中遇到问题：
1. 确保 Google 账号可以正常访问 Google AI 服务
2. 检查网络连接是否正常
3. 清除浏览器缓存后重试
4. 使用 `/bug` 命令直接从 CLI 报告问题
## 下一步
安装和配置完成后，您可以：
- 阅读[命令参考文档](https://www.geminicli.com/docs/reference/commands)了解所有可用命令
- 配置 [MCP 服务器](https://www.geminicli.com/docs/tools/mcp-server) 扩展功能
- 设置 [GEMINI.md 文件](https://www.geminicli.com/docs/cli/gemini-md) 为项目提供持久上下文
---
## 系统架构
### 相关页面
相关主题：[包结构详解](#page-package-structure), [核心工具集](#page-tools)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/cli/src/ui/components/AboutBox.tsx](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/ui/components/AboutBox.tsx)
- [packages/cli/src/ui/components/AppHeader.tsx](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/ui/components/AppHeader.tsx)
- [packages/cli/src/ui/auth/AuthDialog.tsx](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/ui/auth/AuthDialog.tsx)
- [packages/core/src/agents/skill-extraction-agent.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/agents/skill-extraction-agent.ts)
- [packages/core/src/services/chatRecordingService.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/services/chatRecordingService.ts)
- [packages/cli/src/ui/components/views/ExtensionDetails.tsx](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/ui/components/views/ExtensionDetails.tsx)
# 系统架构
## 概述
Gemini CLI 是 Google 开发的一款命令行工具，旨在通过自然语言交互帮助开发者完成代码理解、生成、调试和自动化任务。该工具基于 Gemini 模型构建，支持交互式和非交互式两种运行模式，可无缝集成到各类开发工作流中。
系统的核心架构分为三大层次：**CLI 层**（命令行接口和 UI 渲染）、**Core 层**（核心业务逻辑和代理系统）以及**扩展层**（技能系统、MCP 服务器和自定义命令）。这种分层设计确保了各模块的职责清晰，便于维护和扩展。
资料来源：[packages/cli/src/ui/components/AboutBox.tsx:1-50]()
## 核心组件架构
### 组件层次结构
Gemini CLI 采用 monorepo 结构，主要包含以下核心包：
| 包名 | 职责 | 主要功能 |
|------|------|----------|
| `packages/cli` | 命令行接口层 | CLI 入口、UI 组件、交互处理、配置管理 |
| `packages/core` | 核心业务层 | 代理系统、技能提取、聊天录制、服务层 |
| `packages/devtools` | 开发者工具 | API 调试、日志查看、请求监控 |
资料来源：[README.md:1-100]()
### 包间依赖关系
```mermaid
graph TD
A[packages/cli] --> B[packages/core]
A --> C[packages/devtools]
B --> D[Gemini API]
C --> B
A --> E[用户终端]
```
CLI 包依赖于 Core 包提供核心功能，同时通过 devtools 包提供调试能力。用户通过终端与 CLI 层交互，CLI 层调用 Core 层处理业务逻辑，最终与外部 Gemini API 通信。
## CLI 层架构
### 入口点设计
CLI 层提供两种运行模式以适应不同的使用场景：
| 模式 | 文件位置 | 用途 |
|------|----------|------|
| 交互模式 | `packages/cli/src/interactiveCli.tsx` | 实时对话、工具确认、用户交互 |
| 非交互模式 | `packages/cli/src/nonInteractiveCli.ts` | 脚本集成、自动化任务、CI/CD |
交互模式使用 React 组件渲染终端 UI，支持键盘导航和实时反馈；非交互模式则专注于参数解析和一次性任务执行。
资料来源：[packages/cli/src/ui/components/AboutBox.tsx:1-30]()
### UI 组件体系
UI 层基于 React 和 Ink（终端 React）构建，主要组件包括：
```mermaid
graph TD
A[AppHeader] --> B[UserIdentity]
A --> C[Banner]
D[Dialogs] --> E[AuthDialog]
D --> F[FolderTrustDialog]
D --> G[ModelDialog]
D --> H[InboxDialog]
I[Messages] --> J[ToolConfirmationMessage]
I --> K[ScrollableDiffViewport]
L[Views] --> M[ExtensionDetails]
L --> N[GemmaStatus]
```
**核心 UI 组件说明：**
- **AppHeader**：应用头部，显示版本信息（`v{version}`）、更新状态、用户身份和计划信息
- **AuthDialog**：认证对话框，处理 Google 账户登录和服务条款确认
- **FolderTrustDialog**：文件夹信任对话框，扫描并展示本地配置文件的安全警告
- **ModelDialog**：模型选择对话框，显示 API 配额信息
- **ToolConfirmationMessage**：工具确认消息，处理文件修改和外部编辑器集成
资料来源：[packages/cli/src/ui/components/AppHeader.tsx:1-80]()
资料来源：[packages/cli/src/ui/auth/AuthDialog.tsx:1-60]()
### 应用头部组件
`AppHeader` 组件负责渲染应用的主标识和元信息，支持两种布局模式：
```typescript
// 列布局：用于窄终端或存在 Logo 文本时
const useColumnLayout = !!logoTextArt || isNarrow;
// 行布局：用于宽终端
flexDirection={useColumnLayout ? 'column' : 'row'}
```
头部信息包括：CLI 版本号、模型版本、沙箱环境、操作系统信息以及可选的 Git 提交信息。
资料来源：[packages/cli/src/ui/components/AboutBox.tsx:20-50]()
资料来源：[packages/cli/src/ui/components/AppHeader.tsx:30-70]()
## Core 层架构
### 代理系统
Core 层的核心是代理系统，负责处理用户请求、调用工具和管理对话状态。
**技能提取代理**（`skill-extraction-agent.ts`）是该系统的关键组件：
- 从对话中识别可复用的工作流程
- 生成统一差异格式（unified diff）的补丁文件
- 将补丁保存至 `~/.gemini/skills/.patch`
- 支持技能合并、作用域管理和质量验证
```mermaid
graph TD
A[用户对话] --> B[技能提取代理]
B --> C{分析有效性}
C -->|有有效模式| D[生成补丁]
C -->|无有效模式| E[静默丢弃]
D --> F[验证补丁格式]
F -->|通过| G[保存至 skills 目录]
F -->|失败| E
```
资料来源：[packages/core/src/agents/skill-extraction-agent.ts:1-100]()
### 聊天录制服务
`ChatRecordingService` 负责管理和持久化对话记录：
```typescript
export class ChatRecordingService {
private conversationFile: string | null = null;
private cachedConversation: ConversationRecord | null = null;
private sessionId: string;
private projectHash: string;
}
```
对话记录包含以下元数据：
| 字段 | 类型 | 说明 |
|------|------|------|
| `sessionId` | string | 会话唯一标识 |
| `projectHash` | string | 项目哈希值 |
| `startTime` | ISO8601 | 会话开始时间 |
| `lastUpdated` | ISO8601 | 最后更新时间 |
| `memoryScratchpad` | string | 记忆便签内容 |
| `messageCount` | number | 消息总数 |
| `userMessageCount` | number | 用户消息数 |
资料来源：[packages/core/src/services/chatRecordingService.ts:1-80]()
## 认证与隐私系统
### 认证流程
认证系统通过 `AuthDialog` 组件引导用户完成登录流程：
```mermaid
graph TD
A[启动 CLI] --> B{检查认证状态}
B -->|未认证| C[显示 AuthDialog]
B -->|已认证| D[进入主界面]
C --> D
C --> E[选择认证方式]
E --> F[完成登录]
F --> D
```
认证对话框包含以下选项和处理逻辑：
- Google 账户登录
- 服务条款确认
- 隐私政策链接展示
资料来源：[packages/cli/src/ui/auth/AuthDialog.tsx:30-70]()
### 隐私通知机制
系统提供多层次的隐私通知：
| 通知类型 | 触发条件 | 数据处理 |
|----------|----------|----------|
| `GeminiPrivacyNotice` | Gemini API 使用 | 展示 API 服务条款 |
| `CloudFreePrivacyNotice` | 免费版用户 | 数据收集选项控制 |
隐私通知展示相关链接和条款：
- Gemini API 概述：https://ai.google.dev/docs/gemini_api_overview
- API 服务条款：https://developers.google.com/terms
- Gemini API 附加条款：https://ai.google.dev/gemini-api/terms
资料来源：[packages/cli/src/ui/privacy/GeminiPrivacyNotice.tsx:1-30]()
## 技能系统
### 技能目录结构
每个技能（Skill）遵循标准目录结构：
```
/
├── SKILL.md # 技能定义（必需）
├── scripts/ # 可执行脚本
├── references/ # 参考文档
└── assets/ # 静态资源
```
**SKILL.md 结构：**
- **Frontmatter（YAML）**：包含 `name` 和 `description` 字段
- **Body（Markdown）**：使用说明和指导，仅在技能触发后加载
资料来源：[packages/core/src/skills/builtin/skill-creator/SKILL.md:1-80]()
### 扩展功能标识
扩展详情页面（`ExtensionDetails`）通过功能标签标识扩展能力：
| 标签 | 标识颜色 | 功能说明 |
|------|----------|----------|
| MCP | 主题色 | MCP 服务器集成 |
| Context | 错误色 | Context 文件支持 |
| Hooks | 警告色 | 生命周期钩子 |
| Skills | 成功色 | 技能系统支持 |
| Commands | 主题色 | 自定义命令 |
资料来源：[packages/cli/src/ui/components/views/ExtensionDetails.tsx:40-80]()
## 配置与信任系统
### 文件夹信任对话框
`FolderTrustDialog` 负责扫描工作目录的安全配置：
```mermaid
graph TD
A[加载配置] --> B{发现配置}
B -->|有错误| C[显示错误列表]
B -->|有警告| D[显示安全警告]
B -->|正常| E[列出已发现配置]
C --> F{用户确认}
D --> F
E --> F
F -->|信任| G[加载配置]
F -->|取消| H[跳过]
```
信任配置包括：
- 自定义命令（`.gemini/commands/`）
- 钩子脚本（`.gemini/hooks/`）
- MCP 服务器配置
- 智能体技能
- 项目设置
资料来源：[packages/cli/src/ui/components/FolderTrustDialog.tsx:1-60]()
## 部署与发布架构
### 发布渠道
系统支持三种发布渠道以满足不同用户需求：
| 渠道 | 标签 | 发布周期 | 适用场景 |
|------|------|----------|----------|
| 预览版 | `preview` | 每周二 UTC 23:59 | 测试新功能 |
| 稳定版 | `latest` | 每周二 UTC 20:00 | 生产环境 |
| 每日版 | `nightly` | 每日 UTC 00:00 | 紧跟主分支 |
安装命令示例：
```bash
# 预览版
npm install -g @google/gemini-cli@preview
# 稳定版
npm install -g @google/gemini-cli@latest
# 每日版
npm install -g @google/gemini-cli@nightly
```
### 多平台安装支持
| 平台 | 安装方式 |
|------|----------|
| 通用 | `npm install -g @google/gemini-cli` |
| macOS/Linux | `brew install gemini-cli` |
| macOS | `sudo port install gemini-cli` |
| 受限环境 | Anaconda + Node.js 环境 |
资料来源：[README.md:100-180]()
## 关键技术栈
| 层级 | 技术选型 | 用途 |
|------|----------|------|
| CLI 框架 | Commander.js / Yargs | 命令行参数解析 |
| UI 渲染 | Ink (React for CLI) | 终端界面渲染 |
| 状态管理 | React Hooks | 组件状态管理 |
| 核心逻辑 | TypeScript | 类型安全开发 |
| API 调用 | Gemini SDK | 与 Gemini API 通信 |
| 数据存储 | JSONL | 对话记录持久化 |
## 总结
Gemini CLI 采用清晰的分层架构设计，通过 CLI 层处理用户交互和终端渲染，Core 层提供核心业务能力，扩展层支持技能系统和第三方集成。系统重视安全性和用户隐私，提供完善的认证流程和配置信任机制，同时支持多种发布渠道以适应不同用户的使用需求。
---
## 包结构详解
### 相关页面
相关主题：[系统架构](#page-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/a2a-server/src/index.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/a2a-server/src/index.ts)
- [packages/cli/src/index.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/index.ts)
- [packages/core/src/index.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/index.ts)
- [packages/sdk/src/index.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/sdk/src/index.ts)
# 包结构详解
## 概述
Gemini CLI 是一个基于 monorepo 架构的 Google 开源项目，采用了 pnpm workspace 模式进行多包管理。项目源码位于 `packages/` 目录下，包含四个主要子包：`cli`、`core`、`sdk` 和 `a2a-server`。这种模块化设计将命令行界面、核心业务逻辑、软件开发工具包和协议服务分离，使得各模块可以独立演进和测试，同时保持整体系统的内聚性。
从项目配置文件和源码结构来看，Gemini CLI 的包设计遵循了清晰的关注点分离原则。`cli` 包负责终端 UI 渲染和用户交互，`core` 包实现代理逻辑、工具注册和配置管理，`sdk` 包提供对外编程接口，而 `a2a-server` 包则处理 Agent-to-Agent 通信协议。这种分层架构使得开发者可以根据需求选择性地使用或扩展特定模块。
## 包架构总览
Gemini CLI 的包结构可以划分为四个核心模块，每个模块承担不同的职责。
| 包名称 | 主要职责 | 依赖关系 |
|--------|----------|----------|
| `cli` | 命令行界面、UI 组件、用户交互 | 依赖 core、sdk |
| `core` | 代理逻辑、工具注册、配置管理、聊天录制 | 基础包，无 core 外依赖 |
| `sdk` | 外部 SDK 接口封装 | 依赖 core |
| `a2a-server` | Agent 间通信协议服务 | 独立运行 |
```
┌─────────────────────────────────────────────────────────┐
│ Gemini CLI Monorepo │
├──────────────┬──────────────┬──────────────┬────────────┤
│ cli │ core │ sdk │ a2a-server│
├──────────────┼──────────────┼──────────────┼────────────┤
│ UI 组件 │ Agent 逻辑 │ 外部接口 │ 协议服务 │
│ 隐私通知 │ 工具系统 │ API 封装 │ MCP 集成 │
│ 帮助系统 │ 配置管理 │ 开发者工具 │ 通信路由 │
│ 状态显示 │ 聊天录制 │ │ │
└──────────────┴──────────────┴──────────────┴────────────┘
```
## CLI 包详解
`packages/cli` 是用户直接交互的前端包，负责所有终端界面的渲染和命令解析。该包的源码组织遵循功能模块化原则，将不同类型的 UI 组件放置在相应的目录结构中。
### 目录结构
CLI 包的主要目录包括 `ui/` 目录下的多个子模块：`components/` 存放通用 UI 组件，`privacy/` 处理隐私政策展示，`views/` 包含特定视图组件如状态页面和扩展详情页。这种组织方式使得代码易于导航和维护。
### UI 组件体系
CLI 包的 UI 组件采用了分层设计模式。从源码中可以看到几个关键的 UI 组件类型：
**AboutBox 组件**负责显示应用元信息，包括 CLI 版本、Git 提交信息、模型版本、沙盒环境和操作系统信息。该组件从配置文件和构建时注入的环境变量中获取数据，并使用主题化的样式进行展示。
```tsx
// 显示应用信息的结构示例
interface AppInfo {
cliVersion: string; // CLI 版本号
gitCommit: string; // Git 提交哈希
modelVersion: string; // 使用的模型版本
sandboxEnv: string; // 沙盒环境类型
os: string; // 操作系统
}
```
**AppHeader 组件**是应用的主头部，负责渲染横幅、Logo 和用户身份信息。该组件支持两种布局模式：列布局（column）和行布局（row），根据终端宽度和 Logo 存在与否自动切换。当显示更新状态时，还会在头部右侧显示更新进度指示器。
**GemmaStatus 组件**专门用于显示 Gemma 模型的运行状态，包括二进制文件路径、模型下载状态、服务器运行状态和设置启用状态。每个状态项都配有状态指示点，直观地反映各组件的运行情况。
**Help 组件**提供交互式帮助信息，展示所有可用的斜杠命令及其描述。该组件支持命令隐藏、分类显示和子命令展开等高级功能，帮助用户快速了解 CLI 的使用方式。
### 隐私通知系统
Gemini CLI 实现了多套隐私通知界面以适应不同的使用场景。**CloudFreePrivacyNotice 组件**用于免费版本，向用户清晰说明数据收集政策，并提供数据收集选项的开关控制。该组件使用单选按钮让用户在允许或禁止 Google 使用数据之间做出选择，并将用户偏好持久化到配置系统中。
**GeminiPrivacyNotice 组件**则提供更详细的法律条款链接，包括 Gemini API 概述、Google AI Studio 使用条款、API 服务条款和 Gemini API 附加服务条款。这些链接帮助用户在法律层面了解使用 Gemini CLI 的权利和义务。
### 扩展详情展示
**ExtensionDetails 组件**负责渲染扩展市场的扩展卡片信息。该组件显示扩展名称、版本、GitHub 星标数、Google 拥有标识以及扩展支持的特性标签。支持的特性标签包括 MCP（模型上下文协议）、Context file（上下文文件）、Hooks（钩子）、Skills（技能）和 Custom Commands（自定义命令），每种特性用不同的颜色区分。
## Core 包详解
`packages/core` 是整个项目的基础层，包含了代理逻辑、工具系统、配置管理和聊天录制等核心功能。该包不依赖其他内部包，而是作为其他包的基础依赖。
### 代理与工具系统
**config.ts** 文件实现了核心的配置管理和工具注册系统。该系统支持灵活的工具有条件注册机制，开发者可以通过配置指定启用哪些工具。工具注册采用工厂模式，通过 `maybeRegister` 函数包装，在满足配置条件时才执行实际注册。
```typescript
// 工具注册的条件判断逻辑示例
const maybeRegister = (toolName: string, coreTools: string[] | undefined,
normalizedClassName: string, registerFn: () => void) => {
let isEnabled = false;
if (coreTools) {
isEnabled = coreTools.some(
(tool) =>
tool === toolName ||
tool === normalizedClassName ||
tool.startsWith(`${toolName}(`) ||
tool.startsWith(`${normalizedClassName}(`)
);
}
if (isEnabled) {
registerFn();
}
};
```
配置系统还支持工具的回退机制。以 Ripgrep 为例，当配置启用 Ripgrep 但系统检测到不可用时，会自动回退到 GrepTool 并记录警告日志，同时触发 `RipgrepFallbackEvent` 事件供监控使用。
### 聊天录制服务
**chatRecordingService.ts** 实现了会话持久化和恢复功能。该服务负责将聊天记录以 JSONL 格式存储到文件系统，并在需要时加载和重建会话状态。服务返回的会话记录包含丰富的元数据：
```typescript
interface ConversationRecord {
sessionId: string; // 会话唯一标识
projectHash: string; // 项目哈希值
startTime: string; // 开始时间 ISO 格式
lastUpdated: string; // 最后更新时间
summary: string | undefined; // 会话摘要
memoryScratchpad: string; // 记忆便签
directories: string[]; // 关联目录列表
kind: string; // 会话类型
messages: Message[]; // 消息列表
messageCount: number; // 消息总数
userMessageCount: number; // 用户消息数
firstUserMessage: string; // 首个用户消息
hasUserOrAssistantMessage: boolean; // 是否有人机对话
}
```
### 技能提取代理
**skill-extraction-agent.ts** 实现了从对话历史中自动提取技能的功能。该代理使用统一的 diff 补丁格式来描述技能文件的创建和更新操作，补丁文件存储在 `~/.gemini/skills/.patch` 路径下。代理遵循严格的质量规则，包括合并重复技能、保持职责清晰、确保每个技能包含触发条件、执行步骤和验证方法。
### 策略辅助系统
**policyHelpers.test.ts** 揭示了模型路由策略的实现细节。系统支持单模型直接返回和模型链策略两种模式。当配置使用 "auto" 模型时，系统会返回默认的模型链 `[Pro, Flash]`，优先使用高级模型，在资源受限或性能要求时自动降级。这种设计使得 CLI 能够适应不同的使用场景和资源限制。
## SDK 包详解
`packages/sdk` 为开发者提供编程接口封装，使得第三方应用可以集成 Gemini CLI 的核心能力。该包的封装层次更高，屏蔽了内部实现细节，提供稳定对外的 API。
SDK 包作为核心功能与外部消费者之间的桥梁，其设计目标是保持 API 稳定性，使得依赖该 SDK 的应用能够在 CLI 版本升级时保持兼容。
## A2A Server 包详解
`packages/a2a-server` 实现了 Agent-to-Agent 通信协议服务。该包独立运行，提供标准的通信接口，使得不同的 AI Agent 能够相互发现和交互。A2A 协议支持 MCP（Model Context Protocol）服务器的集成，允许 Gemini CLI 扩展其能力边界，包括 Imagen 图像生成、Veo 视频生成和 Lyria 音乐生成等高级功能。
## 包间依赖关系
各包之间的依赖关系经过精心设计，形成了清晰的层次结构：
```mermaid
graph TD
A[cli 包] --> B[core 包]
A --> C[sdk 包]
B --> C
D[a2a-server 包] --> B
D --> C
E[外部依赖] --> B
E --> C
E --> A
```
核心依赖原则包括：CLI 包依赖 core 和 sdk 以复用核心逻辑；core 包作为基础层不依赖其他内部包；sdk 包依赖 core 提供编程接口；a2a-server 独立运行但可与 core 交互以获取代理能力。
## 安装与发布
Gemini CLI 支持多种安装渠道，满足不同用户的需求：
| 渠道 | 发布频率 | 稳定性 | 安装命令 |
|------|----------|--------|----------|
| Preview | 每周二 UTC 23:59 | 未经完全测试 | `npm install -g @google/gemini-cli@preview` |
| Stable | 每周二 UTC 20:00 | 经过验证 | `npm install -g @google/gemini-cli@latest` |
| Nightly | 每日 UTC 00:00 | 可能存在问题 | `npm install -g @google/gemini-cli@nightly` |
除 npm 外，项目还支持 Homebrew、MacPorts 和 Anaconda 等安装方式，适应不同的操作系统和环境限制。这种多渠道发布策略使得用户可以根据对稳定性的要求选择合适的版本，同时也为测试新功能提供了便捷的途径。
## 源码文件对应关系
根据项目结构和源码分析，各主要功能模块与源码文件的对应关系如下：
| 功能模块 | 主要源文件 | 所在包 |
|----------|------------|--------|
| 命令行入口 | `packages/cli/src/index.ts` | cli |
| UI 组件库 | `packages/cli/src/ui/components/` | cli |
| 隐私通知 | `packages/cli/src/ui/privacy/` | cli |
| 配置管理 | `packages/core/src/config/config.ts` | core |
| 工具注册 | `packages/core/src/config/config.ts` | core |
| 聊天录制 | `packages/core/src/services/chatRecordingService.ts` | core |
| 技能提取 | `packages/core/src/agents/skill-extraction-agent.ts` | core |
| 策略路由 | `packages/core/src/availability/policyHelpers.test.ts` | core |
| SDK 接口 | `packages/sdk/src/index.ts` | sdk |
| A2A 服务 | `packages/a2a-server/src/index.ts` | a2a-server |
## 开发指南
基于包结构设计，开发者在添加新功能时应遵循以下原则：
**包边界原则**：避免使用相对路径跨包导入，优先通过包名导入。这种设计确保了包的边界清晰，便于未来的包拆分和独立发布。
**协议设计**：新增 RPC 方法应添加到 `acpRpcDispatcher.ts`，会话状态存储在 `acpSession.ts`，协议辅助函数添加到 `acpUtils.ts`。
**代码规范**：所有新文件必须包含 Apache-2.0 许可证头，使用 Zod 模式验证不可信输入，避免使用 `any` 类型断言。测试文件应放置在源码同目录下，使用 `.test.ts` 扩展名。
## 总结
Gemini CLI 的包结构设计体现了现代 monorepo 项目的最佳实践。通过将 CLI 界面、核心逻辑、SDK 接口和协议服务分离，项目实现了关注点清晰、职责明确、易于测试和扩展的目标。各包之间的依赖关系经过精心规划，形成了稳定的基础层（core）支撑上层应用（cli、sdk、a2a-server）的架构模式。
---
## 核心工具集
### 相关页面
相关主题：[代理系统与子代理](#page-agent-system)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/core/src/config/config.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/config/config.ts)
- [packages/core/src/tools/shell.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/tools/shell.ts) *(项目引用)*
- [packages/core/src/agents/skill-extraction-agent.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/agents/skill-extraction-agent.ts)
- [packages/cli/src/ui/components/messages/ToolConfirmationMessage.tsx](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/ui/components/messages/ToolConfirmationMessage.tsx)
- [packages/core/src/context/graph/toGraph.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/context/graph/toGraph.ts)
- [packages/core/src/services/chatRecordingService.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/services/chatRecordingService.ts)
# 核心工具集
## 概述
Gemini CLI 的核心工具集是 CLI 与用户代码库进行交互的基础能力层。这些工具提供了文件读写、代码搜索、Shell 命令执行、网络搜索与内容获取等核心功能，使 AI Agent 能够理解、修改和分析用户的代码环境。
工具注册采用动态机制，通过配置类 `CoreConfig` 的 `registerTools()` 方法根据用户配置选择性注册可用工具。工具实现遵循统一的注册接口，每个工具继承自基础工具类并与消息总线 (`MessageBus`) 集成以实现事件驱动的通信。
## 工具注册架构
### 动态注册机制
工具注册通过 `maybeRegister` 辅助函数实现，该函数检查工具是否在 `coreTools` 配置列表中启用，只有启用状态下才会调用注册函数将工具实例添加到注册表：
```typescript
const maybeRegister = (
toolClass: ToolConstructor,
registerFn: () => void
) => {
let isEnabled = false;
if (!coreTools) {
isEnabled = true;
} else if (coreTools) {
isEnabled = coreTools.some(
(tool) =>
tool === toolName ||
tool === normalizedClassName ||
tool.startsWith(`${toolName}(`) ||
tool.startsWith(`${normalizedClassName}(`),
);
}
if (isEnabled) {
registerFn();
}
};
```
资料来源：[packages/core/src/config/config.ts:120-147]()
### 工具注册流程图
```mermaid
graph TD
A[CoreConfig 初始化] --> B[调用 registerTools]
B --> C{检查 coreTools 配置}
C -->|未配置| D[默认启用所有工具]
C -->|已配置| E{遍历 coreTools 列表}
E -->|工具匹配| F[调用 maybeRegister]
F --> G{工具已启用?}
G -->|是| H[注册工具到 Registry]
G -->|否| I[跳过注册]
H --> J[工具可用]
```
## 核心工具类型
### 文件操作工具
| 工具名称 | 类名 | 功能描述 |
|---------|------|---------|
| 文件列表 | `LSTool` | 列出目录内容和文件结构 |
| 文件读取 | `ReadFileTool` | 读取指定路径的文件内容 |
| 文件写入 | `WriteFileTool` | 创建或更新文件内容 |
#### 文件工具的 Patch 格式
在技能提取和文件更新场景中，工具使用统一的 unified diff patch 格式：
```diff
--- /absolute/path/to/original/SKILL.md
+++ /absolute/path/to/original/SKILL.md
@@ -, +, @@
-
+
```
Patch 规则要点：
- 使用绝对路径，禁止 `a/` 或 `b/` 前缀
- 每个 hunk 需要包含 3 行上下文
- `@@` 头部行数必须准确
- 新文件使用 `/dev/null` 作为源路径
资料来源：[packages/core/src/agents/skill-extraction-agent.ts]()
### 搜索工具
| 工具名称 | 类名 | 优先级 | 回退方案 |
|---------|------|--------|---------|
| 高级搜索 | `RipGrepTool` | 高 | 依赖系统 ripgrep |
| 基础搜索 | `GrepTool` | 低 | 默认 GrepTool |
#### Ripgrep 回退机制
当检测到 `useRipgrep` 配置启用时，系统会尝试注册 `RipGrepTool`。若系统不具备 ripgrep 能力，则自动回退到 `GrepTool`：
```typescript
if (this.getUseRipgrep()) {
let useRipgrep = false;
try {
useRipgrep = await canUseRipgrep();
} catch (error: unknown) {
errorString = String(error);
}
if (useRipgrep) {
maybeRegister(RipGrepTool, () =>
registry.registerTool(new RipGrepTool(this, this.messageBus)),
);
} else {
debugLogger.warn(`Ripgrep is not available. Falling back to GrepTool.`);
maybeRegister(GrepTool, () =>
registry.registerTool(new GrepTool(this, this.messageBus)),
);
}
}
```
资料来源：[packages/core/src/config/config.ts:130-146]()
### Shell 执行工具
Shell 工具允许 AI Agent 执行系统命令。执行前需要用户确认权限，权限范围包括：
| 权限类型 | 说明 |
|---------|------|
| 网络访问 | 允许访问所有 URL |
| 写权限 | 允许写入的路径列表 |
| 读权限 | 允许读取的路径列表 |
工具确认消息格式示例：
```tsx
• Network: All Urls
• Write: /path/to/project
• Read: /path/to/project
```
资料来源：[packages/cli/src/ui/components/messages/ToolConfirmationMessage.tsx]()
### 网络工具
| 工具名称 | 功能 |
|---------|------|
| `WebSearch` | 执行 Google 搜索，获取实时信息 |
| `WebFetch` | 获取指定 URL 的网页内容 |
## 工具确认与权限管理
### 权限确认流程
```mermaid
sequenceDiagram
participant User as 用户
participant Tool as 工具调用
participant UI as 确认界面
participant Core as 核心引擎
Tool->>Core: 请求执行命令
Core->>UI: 显示 ToolConfirmationMessage
User->>UI: 批准/拒绝
alt 批准
UI->>Core: 确认执行
Core->>Tool: 放行执行
Tool->>User: 返回结果
else 拒绝
UI->>Core: 拒绝执行
Core->>Tool: 终止操作
end
```
### 自动编辑模式
当配置 `ApprovalMode` 设置为 `YOLO` 或 `AUTO_EDIT` 时，系统会自动批准工具执行，无需用户手动确认：
```typescript
const isAutoEdit =
config.getApprovalMode() === ApprovalMode.YOLO ||
config.getApprovalMode() === ApprovalMode.AUTO_EDIT;
```
资料来源：[packages/cli/src/ui/components/messages/ToolConfirmationMessage.tsx]()
## 工具与消息总线
工具通过 `MessageBus` 实现事件驱动的通信架构。每个工具实例在注册时接收消息总线引用，支持以下事件类型：
- `ToolStarted` - 工具开始执行
- `ToolCompleted` - 工具执行完成
- `ToolError` - 工具执行错误
- `ToolConfirmationRequired` - 需要用户确认
工具实例接收消息总线的方式：
```typescript
registry.registerTool(new ReadFileTool(this, this.messageBus));
registry.registerTool(new LSTool(this, this.messageBus));
```
资料来源：[packages/core/src/config/config.ts:139-146]()
## 对话上下文中的工具调用
### Turn ID 生成机制
每次工具调用都会生成稳定的唯一标识符，用于追踪对话历史：
```typescript
const turnContent = JSON.stringify(msg.parts);
const h = createHash('md5')
.update(`${msg.role}:${turnContent}`)
.digest('hex');
const occurrence = (seenHashes.get(h) || 0) + 1;
seenHashes.set(h, occurrence);
const turnSalt = `${h}_${occurrence}`;
const turnId = getStableId(msg, this.nodeIdentityMap, turnSalt, -1);
```
资料来源：[packages/core/src/context/graph/toGraph.ts]()
### 函数调用标识
函数调用和函数响应在对话图中使用不同前缀的标识符：
| 调用类型 | 标识符格式 |
|---------|-----------|
| 函数调用 | `call_${functionCall.id}_${turnSalt}_${partIdx}` |
| 函数响应 | `resp_${functionResponse.id}_${turnSalt}_${partIdx}` |
## 会话记录与工具调用追溯
`ChatRecordingService` 负责记录工具调用历史，保存到 JSONL 文件格式：
```typescript
export interface ConversationRecord {
sessionId: string;
projectHash: string;
startTime: string;
lastUpdated: string;
summary?: string;
memoryScratchpad?: string;
directories?: string[];
kind: string;
messages: Message[];
messageCount: number;
userMessageCount: number;
firstUserMessage?: string;
hasUserOrAssistantMessage: boolean;
}
```
资料来源：[packages/core/src/services/chatRecordingService.ts]()
## 配置参考
### coreTools 配置选项
```typescript
interface CoreToolsConfig {
coreTools?: Array<
| 'read_file'
| 'read_file(...)'
| 'write_file'
| 'write_file(...)'
| 'ls'
| 'ls(...)'
| 'grep'
| 'grep(...)'
| 'ripgrep'
| 'ripgrep(...)'
| 'web_search'
| 'web_search(...)'
| 'web_fetch'
| 'web_fetch(...)'
>;
useRipgrep?: boolean;
}
```
### ApprovalMode 配置
| 模式 | 行为 |
|------|------|
| `MANUAL` | 所有操作需要用户手动确认 |
| `AUTO_EDIT` | 编辑操作自动批准 |
| `YOLO` | 所有操作自动批准 |
| `DISABLED` | 禁用确认机制 |
## 扩展与 MCP 集成
核心工具集支持通过 MCP (Model Context Protocol) 服务器进行扩展。MCP 提示命令在帮助界面中带有 `[MCP]` 标签标识：
```tsx
{command.kind === CommandKind.MCP_PROMPT && (
[MCP]
)}
```
扩展工具可添加的能力标签：
| 标签 | 含义 |
|------|------|
| `MCP` | MCP 服务器集成 |
| `Context file` | 支持上下文文件 |
| `Hooks` | 支持生命周期钩子 |
| `Skills` | 支持技能系统 |
| `Commands` | 支持自定义命令 |
资料来源：[packages/cli/src/ui/components/Help.tsx]()
---
## 代理系统与子代理
### 相关页面
相关主题：[核心工具集](#page-tools), [上下文管理与压缩](#page-context-management)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/core/src/agent/agent-session.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/agent/agent-session.ts)
- [packages/core/src/agents/registry.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/agents/registry.ts)
- [packages/core/src/agents/agent-scheduler.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/agents/agent-scheduler.ts)
- [packages/core/src/agents/generalist-agent.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/agents/generalist-agent.ts)
- [packages/core/src/agents/a2a-client-manager.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/agents/a2a-client-manager.ts)
- [packages/core/src/agents/skill-extraction-agent.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/agents/skill-extraction-agent.ts)
- [packages/core/src/config/config.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/config/config.ts)
- [packages/core/src/prompts/snippets.legacy.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/prompts/snippets.legacy.ts)
- [packages/core/src/availability/policyHelpers.test.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/availability/policyHelpers.test.ts)
- [packages/sdk/src/tool.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/sdk/src/tool.ts)
# 代理系统与子代理
## 概述
Gemini CLI 的代理系统（Agent System）是整个命令-line 工具的核心架构，负责协调用户交互、任务执行和工具调用。该系统采用模块化设计，支持多种类型的代理（Agent），包括通用代理（Generalist Agent）和专业技能提取代理（Skill Extraction Agent）。代理系统通过注册机制（Registry）和调度器（Scheduler）统一管理所有代理的生命周期，实现灵活的扩展性和高度的可维护性。
## 系统架构
### 核心组件关系
```mermaid
graph TD
User[用户交互] --> CLI[CLI 界面层]
CLI --> Session[AgentSession]
Session --> Registry[AgentRegistry]
Registry --> Scheduler[AgentScheduler]
Scheduler --> GeneralistAgent[通用代理]
Scheduler --> SkillExtractionAgent[技能提取代理]
GeneralistAgent --> Tools[工具集]
SkillExtractionAgent --> SkillManager[技能管理器]
Tools --> FileSystem[文件系统工具]
Tools --> Shell[Shell 执行工具]
Tools --> Grep[RipGrep/Grep 工具]
Tools --> MCP[MCP 服务器工具]
```
### 代理类型体系
| 代理类型 | 文件位置 | 职责描述 |
|---------|---------|---------|
| GeneralistAgent | `packages/core/src/agents/generalist-agent.ts` | 通用任务处理，支持代码理解、生成、调试 |
| SkillExtractionAgent | `packages/core/src/agents/skill-extraction-agent.ts` | 从会话历史中提取可复用的技能模式 |
| 未来扩展代理 | `packages/core/src/agents/` 目录 | 通过注册机制动态加载 |
## 代理注册机制
### 注册表（AgentRegistry）
代理系统通过 `AgentRegistry` 实现代理的注册和管理。该注册表维护了一个代理实例的映射表，支持按类型动态查询和实例化。
```mermaid
classDiagram
class AgentRegistry {
-Map~string, Agent~ agents
+registerAgent(agent: Agent): void
+getAgent(type: string): Agent
+listAgents(): Agent[]
}
```
注册表的核心方法包括：
- **registerAgent()** - 将新代理实例注册到系统中
- **getAgent()** - 根据代理类型获取对应实例
- **listAgents()** - 列出所有已注册的代理
### 调度器（AgentScheduler）
`AgentScheduler` 负责协调多个代理之间的工作分配和执行顺序。它维护一个任务队列，并根据代理的能力和当前系统状态将任务路由到合适的代理。
## 通用代理（Generalist Agent）
### 核心职责
通用代理是 Gemini CLI 的主要工作代理，负责处理用户的各种自然语言请求。其主要功能包括：
| 功能类别 | 具体能力 |
|---------|---------|
| 代码理解 | 分析代码库结构、理解模块依赖、解释算法逻辑 |
| 代码生成 | 根据描述生成新代码、模板、配置文件 |
| 调试排错 | 定位问题、分析错误原因、提供修复建议 |
| 任务自动化 | 执行命令行操作、处理 Git 工作流、查询 Pull Request |
### 工具集成
通用代理通过 `Tool` 接口与各种工具进行交互。核心工具包括：
| 工具名称 | 实现文件 | 功能描述 |
|---------|---------|---------|
| LSTool | `config.ts` | 列出目录内容和文件结构 |
| ReadFileTool | `config.ts` | 读取文件内容 |
| RipGrepTool | `config.ts` | 使用 Ripgrep 进行正则搜索（优先） |
| GrepTool | `config.ts` | 使用标准 Grep 进行搜索（回退方案） |
| UpdateTopicTool | `config.ts` | 更新会话主题 |
工具注册采用条件注册模式，根据系统环境自动选择最优实现：
```typescript
// 资料来源：packages/core/src/config/config.ts
if (this.getUseRipgrep()) {
let useRipgrep = false;
try {
useRipgrep = await canUseRipgrep();
} catch (error: unknown) {
errorString = String(error);
}
if (useRipgrep) {
maybeRegister(RipGrepTool, () =>
registry.registerTool(new RipGrepTool(this, this.messageBus)),
);
} else {
debugLogger.warn(`Ripgrep is not available. Falling back to GrepTool.`);
maybeRegister(GrepTool, () =>
registry.registerTool(new GrepTool(this, this.messageBus)),
);
}
}
```
## 技能提取代理（Skill Extraction Agent）
### 概述
技能提取代理（Skill Extraction Agent）是一个专门的子代理，负责从用户与通用代理的会话历史中自动识别和提取可复用的技能模式。这些提取的技能可以被保存为 `SKILL.md` 文件，供将来类似任务使用。
### 工作流程
```mermaid
graph TD
Start[会话进行中] --> Analyze{分析会话历史}
Analyze --> |发现模式| CreateSkill[创建技能]
CreateSkill --> GeneratePatch[生成 Patch 文件]
GeneratePatch --> ValidatePatch[验证 Patch 有效性]
ValidatePatch --> |通过| SaveSkill[保存技能到 .inbox]
ValidatePatch --> |失败| Discard[静默丢弃]
Analyze --> |无明显模式| NoOp[不创建技能]
SaveSkill --> End[技能可用]
NoOp --> End
```
### 技能文件结构
技能代理创建的技能文件遵循标准化结构：
| 文件类型 | 用途 | 加载时机 |
|---------|-----|---------|
| `FORMS.md` | 表单定义和交互规范 | 特定命令需要时 |
| `REFERENCE.md` | API 参考和详细文档 | 引用时按需加载 |
| `EXAMPLES.md` | 代码示例和使用模式 | 示例请求时 |
| `SKILL.md` | 主入口，包含元数据和导航 | 始终加载 |
### Patch 文件格式
技能代理使用标准化的统一 diff 格式（Unified Diff）来描述文件变更：
```diff
--- /absolute/path/to/original/SKILL.md
+++ /absolute/path/to/original/SKILL.md
@@ -, +, @@
-
+
```
**关键规则**：
- 必须使用绝对路径，禁止使用 `a/` 或 `b/` 前缀
- 每个变更块需要包含 3 行上下文
- `@@` 头部的行数必须精确匹配
- Patch 文件名必须为 `extraction.patch`
- 路径必须在允许的根目录下
### 质量规则
技能提取代理实施严格的质量控制：
| 规则 | 描述 |
|-----|------|
| 去重合并 | 优先合并相似技能而非创建新技能 |
| 职责明确 | 避免创建"万能"技能，保持职责单一 |
| 必需元素 | 每个技能必须包含：触发条件、处理流程、注意事项、验证步骤 |
| 证据驱动 | 必须有来自会话历史的明确证据支持技能创建 |
| 空操作正常 | 创建 0 个技能是正常结果，不应强制创建 |
## 代理会话（AgentSession）
### 会话管理
`AgentSession` 是用户与代理系统交互的主要入口点，负责维护对话状态和消息历史。
```mermaid
graph LR
User[用户消息] --> Session[AgentSession]
Session --> Record[ChatRecordingService]
Record --> Storage[JSONL 文件]
Session --> Graph[ContextGraphBuilder]
Graph --> Context[上下文图]
Context --> Model[AI 模型]
Model --> Response[代理响应]
```
### 会话记录服务
`ChatRecordingService` 负责持久化会话数据，支持以下功能：
| 功能 | 描述 |
|-----|------|
| 消息存储 | 将用户和代理消息保存到 JSONL 文件 |
| 元数据管理 | 维护 sessionId、projectHash、startTime 等元信息 |
| 条件加载 | 支持仅加载元数据或完整消息 |
| 增量更新 | 追踪最后更新时间，支持断点续传 |
会话元数据结构：
```typescript
interface ConversationMetadata {
sessionId: string;
projectHash: string;
startTime: string;
lastUpdated: string;
summary?: string;
memoryScratchpad?: string;
directories?: string[];
kind?: string;
messageCount: number;
userMessageCount: number;
firstUserMessage?: string;
hasUserOrAssistantMessage: boolean;
}
```
## A2A 客户端管理器
### Agent-to-Agent 通信
`a2a-client-manager.ts` 实现了代理之间的通信协议，支持多代理协作场景。
### 核心功能
A2A 客户端管理器处理以下类型的通信：
- **任务委托** - 将复杂任务分解并委托给专业代理
- **结果聚合** - 收集多个子代理的执行结果
- **状态同步** - 保持代理间的状态一致性
## 策略与配置
### 模型策略链
代理系统使用策略链（Policy Chain）来选择合适的 AI 模型：
```typescript
// 资料来源：packages/core/src/availability/policyHelpers.test.ts
describe('policyHelpers', () => {
describe('resolvePolicyChain', () => {
it('returns a single-model chain for a custom model', () => {
const config = createMockConfig({
getModel: () => 'custom-model',
});
const chain = resolvePolicyChain(config);
expect(chain).toHaveLength(1);
expect(chain[0]?.model).toBe('custom-model');
});
it('returns the default chain when active model is "auto"', () => {
const config = createMockConfig({
getModel: () => DEFAULT_GEMINI_MODEL_AUTO,
});
const chain = resolvePolicyChain(config);
// Expect default chain [Pro, Flash]
expect(chain).toHaveLength(2);
});
});
});
```
### 策略链规则
| 模型设置 | 策略行为 |
|---------|---------|
| 自定义模型 | 返回单模型链，直接使用指定模型 |
| 自动模式 (`auto`) | 返回默认链 [Pro, Flash]，自动降级 |
| Pro 不可用 | 自动切换到 Flash |
### 工具配置
工具注册支持细粒度控制：
| 配置项 | 描述 |
|-------|------|
| `coreTools` | 显式启用/禁用核心工具列表 |
| 模式匹配 | 支持 `toolName`、`ClassName`、`toolName(params)` 三种匹配方式 |
| Ripgrep 回退 | 自动检测 Ripgrep 可用性，无则回退到 GrepTool |
## 规划模式（Plan Mode）
### 工作流程
当启用规划模式时，系统使用专门的提示模板来引导代理进行结构化规划：
```typescript
// 资料来源：packages/core/src/prompts/snippets.legacy.ts
export function renderPlanningWorkflow(
options?: PlanningWorkflowOptions,
): string {
if (!options) return '';
return `
# Active Approval Mode: Plan
You are operating in **Plan Mode** - a structured planning workflow for designing implementation strategies before execution.
## Available Tools
The following read-only tools are available in Plan Mode:
${options.planModeToolsList}
- \`${WRITE_FILE_TOOL_NAME}\` - Save plans to the plans directory
- \`${EDIT_TOOL_NAME}\` - Update plans in the plans directory
...
`;
}
```
### 规划模式特点
| 特性 | 描述 |
|-----|------|
| 只读工具 | 仅允许使用查看类工具 |
| 计划存储 | 允许写入计划文件到 plans 目录 |
| 审批流程 | 计划需用户审批后才能执行 |
## SDK 工具集成
### 工具定义与执行
通过 SDK，第三方可以扩展代理系统的工具集：
```typescript
// 资料来源：packages/sdk/src/tool.ts
bindContext(context: SessionContext): SdkTool {
return new SdkTool(this.definition, this.messageBus, undefined, context);
}
createInvocationWithContext(
params: z.infer,
messageBus: MessageBus,
context: SessionContext | undefined,
toolName?: string,
): ToolInvocation, ToolResult> {
return new SdkToolInvocation(
params,
messageBus,
this.definition.action,
context || this.context,
toolName || this.name,
this.definition.sendErrorsToModel,
);
}
```
### 工具创建示例
SDK 提供了简化工具创建的辅助函数：
```typescript
import { z, tool } from '@google/gemini-cli-sdk';
const myTool = tool({
name: 'myTool',
description: 'A custom tool for specific tasks',
inputSchema: z.object({
param1: z.string(),
param2: z.number().optional(),
}),
async action(params) {
// Tool implementation
return { result: 'success' };
},
});
```
## 总结
Gemini CLI 的代理系统采用分层架构设计，通过注册机制实现了高度的可扩展性。通用代理负责处理日常任务，技能提取代理则通过智能分析会话历史自动构建知识库，两者协同工作为用户提供智能化的命令行辅助体验。系统支持通过 SDK 扩展工具集，并通过策略链机制灵活选择 AI 模型，确保在不同场景下都能提供最优的性能和结果质量。
---
## 上下文管理与压缩
### 相关页面
相关主题：[代理系统与子代理](#page-agent-system), [核心工具集](#page-tools)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/core/src/context/graph/toGraph.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/context/graph/toGraph.ts)
- [packages/core/src/services/chatRecordingService.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/services/chatRecordingService.ts)
- [packages/core/src/context/graph/render.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/context/processors/rollingSummaryProcessor.ts)
- [packages/core/src/agents/cli-help-agent.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/agents/cli-help-agent.ts)
# 上下文管理与压缩
## 概述
在 Gemini CLI 中，上下文管理是确保大型对话会话能够持续运行而不会超出模型令牌限制的核心机制。系统通过多种策略组合，包括对话历史压缩、消息去重、上下文图构建和滚动摘要，来高效管理对话状态。
## 核心组件架构
### 上下文管理系统
上下文管理由多个协同工作的组件构成：
| 组件 | 文件路径 | 职责 |
|------|----------|------|
| ContextGraphBuilder | `packages/core/src/context/graph/toGraph.ts` | 构建对话消息图，处理历史消息转换 |
| ChatRecordingService | `packages/core/src/services/chatRecordingService.ts` | 会话持久化和元数据管理 |
| ChatCompressionService | `packages/core/src/context/chatCompressionService.ts` | 对话内容压缩和摘要生成 |
| RollingSummaryProcessor | `packages/core/src/context/processors/rollingSummaryProcessor.ts` | 滚动式摘要处理 |
## 对话历史处理流程
### 消息图构建机制
系统通过 `ContextGraphBuilder` 将原始对话历史转换为优化的图结构：
```mermaid
graph TD
A[原始消息历史] --> B[Legacy环境头检查]
B --> C{是否为遗留格式?}
C -->|是| D[跳过该消息轮次]
C -->|否| E[遍历消息部件]
E --> F[生成消息哈希]
F --> G[计算出现次数]
G --> H[生成稳定TurnID]
H --> I[用户消息处理]
H --> J[函数调用/响应处理]
I --> K[构建上下文图]
J --> K
```
### 消息标识生成策略
每个对话轮次都会生成稳定的唯一标识符，确保会话恢复和状态追踪的可靠性：
1. **内容哈希**：使用 MD5 哈希基于 `角色:内容` 组合生成唯一指纹
2. **出现计数**：同一条消息可能出现多次，系统通过计数区分
3. **盐值生成：`turnSalt` = `${哈希}_${出现次数}` 格式
4. **稳定ID：通过 `getStableId` 函数结合节点标识映射生成最终ID
资料来源：[packages/core/src/context/graph/toGraph.ts:1-50]()
### 遗留环境头处理
系统包含对旧版环境头的兼容性处理：
```typescript
// 防御性检查：跳过遗留环境头，无论其出现在对话中的哪个位置
if (msg.role === 'user' && msg.parts.length === 1) {
const text = msg.parts[0].text;
if (
text?.startsWith('') &&
text?.includes('This is the Gemini CLI')
) {
debugLogger.log(
'[ContextGraphBuilder] Skipping legacy environment header turn from graph.',
);
continue;
}
}
```
这种设计确保了系统演进过程中的向后兼容性，同时维护上下文图的干净结构。
## 会话持久化与服务
### ChatRecordingService 的角色
`ChatRecordingService` 负责会话的持久化存储和元数据管理：
| 功能 | 描述 |
|------|------|
| 会话ID管理 | 为每个对话会话分配唯一标识符 |
| 项目哈希 | 基于项目目录生成唯一项目标识 |
| 时间戳追踪 | 记录会话开始时间、最后更新时间 |
| 摘要管理 | 支持会话摘要的存储和检索 |
| 消息统计 | 追踪用户消息数、总消息数 |
### 对话记录数据结构
```typescript
interface ConversationRecord {
sessionId: string; // 会话唯一标识
projectHash: string; // 项目标识哈希
startTime: string; // ISO格式开始时间
lastUpdated: string; // 最后更新时间
summary?: string; // 会话摘要
memoryScratchpad?: string; // 记忆便签
directories: string[]; // 相关目录
kind: string; // 会话类型
messages: Message[]; // 实际消息内容
messageCount: number; // 总消息数
userMessageCount: number; // 用户消息数
firstUserMessage?: string; // 首条用户消息
hasUserOrAssistantMessage: boolean; // 是否有用户/助手消息
}
```
### 元数据模式
系统支持两种加载模式以优化性能：
1. **完整模式 (`metadataOnly: false`)**：加载所有消息内容和元数据
2. **仅元数据模式 (`metadataOnly: true`)**：仅加载元数据，用于快速列表展示
```typescript
return {
messages: options?.metadataOnly ? [] : loadedMessages,
messageCount: options?.metadataOnly
? metadataMessages.length || messageIds.length
: loadedMessages.length,
};
```
资料来源：[packages/core/src/services/chatRecordingService.ts:1-100]()
## 上下文压缩策略
### 压缩服务架构
虽然完整的压缩服务源码未在当前上下文中，但根据系统设计模式，上下文压缩通常包括：
| 压缩策略 | 应用场景 |
|----------|----------|
| 滚动摘要 | 长对话的历史消息压缩 |
| 选择性保留 | 保留关键系统消息和最后N条消息 |
| 消息合并 | 合并连续的同类消息 |
| 元数据裁剪 | 移除冗余的元数据字段 |
### 摘要处理器
`RollingSummaryProcessor` 实现滚动式摘要生成，周期性地将早期对话内容压缩为摘要，同时保留会话的关键上下文。
## CLI Help Agent 与上下文
CLI Help Agent 是上下文管理的一个典型应用场景，它利用上下文信息提供准确的帮助响应：
```
### Runtime Context
- **CLI Version:** ${cliVersion}
- **Active Model:** ${activeModel}
- **Today's Date:** ${today}
```
代理通过内部文档工具 `get_internal_docs` 获取最新文档，并结合运行时上下文给出精确答案。这种设计确保了帮助信息的准确性和时效性。
资料来源：[packages/core/src/agents/cli-help-agent.ts:1-30]()
## 关键设计模式
### 1. 延迟加载模式
通过 `metadataOnly` 选项，系统可以仅在需要时加载完整消息内容，显著降低内存占用。
### 2. 稳定标识符系统
使用哈希+计数的组合方式确保即使相同内容的消息也能获得唯一标识：
```typescript
const turnContent = JSON.stringify(msg.parts);
const h = createHash('md5')
.update(`${msg.role}:${turnContent}`)
.digest('hex');
const occurrence = (seenHashes.get(h) || 0) + 1;
seenHashes.set(h, occurrence);
const turnSalt = `${h}_${occurrence}`;
```
### 3. 向后兼容性
通过显式检测和跳过遗留格式，系统可以在不破坏现有会话的情况下演进。
## 配置与使用
### 上下文相关配置
| 配置项 | 位置 | 说明 |
|--------|------|------|
| `showUserIdentity` | UI设置 | 控制用户身份信息显示 |
| 会话存储路径 | 用户目录 | `~/.gemini/` 下的会话文件 |
### 上下文持久化
会话检查点保存在用户目录：
```
~/.gemini/
├── policies/
│ └── auto-saved.toml # 自动保存的策略配置
└── [会话数据文件] # JSONL格式的会话记录
```
## 错误处理与调试
系统包含完善的调试日志机制：
```typescript
debugLogger.log('[ContextGraphBuilder] Skipping legacy environment header turn from graph.');
debugLogger.error('Error loading conversation record from JSONL:', error);
```
开发者可以通过设置适当的日志级别来监控上下文管理行为。
## 总结
Gemini CLI 的上下文管理与压缩系统通过以下核心机制确保高效运行：
1. **图结构存储**：将对话历史转换为优化的图数据结构
2. **稳定标识**：基于内容哈希的稳定ID生成确保会话一致性
3. **分层加载**：支持元数据和完整内容的两级加载模式
4. **滚动压缩**：周期性摘要生成防止上下文无限增长
5. **向后兼容**：优雅处理历史格式和演进中的数据结构
---
## CLI用户界面
### 相关页面
相关主题：[命令系统](#page-commands), [系统架构](#page-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/cli/src/ui/App.tsx](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/ui/App.tsx)
- [packages/cli/src/ui/components/Composer.tsx](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/ui/components/Composer.tsx)
- [packages/cli/src/ui/components/MainContent.tsx](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/ui/components/MainContent.tsx)
- [packages/cli/src/ui/components/ToolConfirmationQueue.tsx](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/ui/components/ToolConfirmationQueue.tsx)
- [packages/cli/src/ui/themes/theme-manager.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/ui/themes/theme-manager.ts)
# CLI用户界面
## 概述
Gemini CLI 的用户界面（UI）是基于终端的交互式命令行工具界面，采用 React 风格组件化架构构建在 Node.js 运行时之上。界面设计遵循终端友好原则，使用 `ink`（React for CLI）框架实现完整的交互式用户体验，支持富文本渲染、颜色主题、键盘快捷键和多区域布局管理。
UI 系统的核心职责包括：
- 提供消息对话区域，展示用户输入、模型响应和工具调用结果
- 实现 Composer（输入组合器）处理用户命令和自然语言输入
- 管理工具确认流程，包括文件读写、网络访问等权限审批
- 应用主题和配色方案，保持视觉一致性
- 处理键盘快捷键和导航交互
资料来源：[packages/cli/src/ui/App.tsx:1-50]()
## 架构设计
### 整体架构
CLI UI 采用分层架构，从上至下分为四个主要层次：
```mermaid
graph TD
A[App 根组件] --> B[AppHeader 头部区域]
A --> C[MainContent 主内容区域]
A --> D[Composer 输入组合器]
A --> E[工具确认队列]
B --> B1[Logo 显示]
B --> B2[版本信息]
B --> B3[用户身份]
B --> B4[横幅通知]
C --> C1[消息列表]
C --> C2[工具执行结果]
C --> C3[对话框层]
D --> D1[多行输入框]
D --> D2[快捷方式按钮]
D --> D3[发送按钮]
```
### 组件层次结构
```
App
├── AppHeader
│ ├── Logo/版本信息
│ ├── UserIdentity
│ └── Banner
├── MainContent
│ ├── Messages
│ │ ├── UserMessage
│ │ ├── ModelMessage
│ │ └── ToolResultMessage
│ ├── Dialogs
│ │ ├── InboxDialog
│ │ ├── FolderTrustDialog
│ │ └── ExtensionRegistryView
│ └── Views
│ ├── GemmaStatus
│ └── ExtensionDetails
├── ToolConfirmationQueue
└── Composer
├── InputArea
└── ActionButtons
```
资料来源：[packages/cli/src/ui/App.tsx:50-150]()
## 核心组件详解
### App 根组件
`App` 是整个 CLI 界面的根组件，负责协调所有子组件的状态和布局。它维护以下关键状态：
| 状态字段 | 类型 | 说明 |
|---------|------|------|
| `showHeader` | boolean | 控制头部区域显示 |
| `showComposer` | boolean | 控制输入区域显示 |
| `toolConfirmations` | array | 待确认的工具调用队列 |
| `activeDialog` | DialogType | 当前激活的对话框类型 |
根组件通过 React Context 向下传递配置和主题信息，确保所有子组件能够访问统一的应用状态。
资料来源：[packages/cli/src/ui/App.tsx:100-200]()
### MainContent 主内容区域
`MainContent` 组件是消息显示和对话框渲染的核心容器。它根据当前状态渲染三种不同的内容模式：
1. **消息模式**：展示对话历史和工具执行结果
2. **对话框模式**：叠加显示各类交互对话框
3. **混合模式**：消息列表配合悬浮对话框
组件支持平滑的内容切换动画，通过 `useLayoutEffect` 优化重渲染性能。
资料来源：[packages/cli/src/ui/components/MainContent.tsx:1-80]()
### Composer 输入组合器
`Composer` 是用户输入的核心交互组件，提供类终端的输入体验：
| 功能 | 快捷键 | 说明 |
|------|--------|------|
| 发送消息 | Enter/⌘+Enter | 提交当前输入 |
| 多行输入 | Shift+Enter | 换行继续输入 |
| 自然语言命令 | 普通文本 | 自动解析执行意图 |
| Shell 命令 | `!` 前缀 | 执行 shell 命令 |
| 文件引用 | `@` 前缀 | 引用特定文件 |
| 取消操作 | Esc (双击) | 清空输入或取消当前操作 |
Composer 支持通过配置切换不同的输入模式，包括标准模式、YOLO 模式（自动接受所有操作）和审核模式。
资料来源：[packages/cli/src/ui/components/Composer.tsx:1-120]()
### ToolConfirmationQueue 工具确认队列
工具确认队列负责管理和展示需要用户授权的操作请求。主要确认类型包括：
| 确认类型 | 显示内容 | 典型场景 |
|---------|---------|---------|
| `file-read` | 文件路径列表 | 读取项目文件 |
| `file-write` | 目标文件列表 | 创建或修改文件 |
| `network` | 访问的 URL | HTTP 请求 |
| `exec` | 命令详情 | Shell 命令执行 |
每个确认项包含以下属性：
- `toolName`：工具名称
- `confirmationDetails`：详细确认信息
- `onApprove`：批准回调
- `onDeny`：拒绝回调
资料来源：[packages/cli/src/ui/components/ToolConfirmationQueue.tsx:1-100]()
## 主题系统
### ThemeManager 主题管理器
`ThemeManager` 负责统一管理 CLI 界面的视觉呈现，采用声明式主题配置：
```typescript
interface Theme {
text: {
primary: string;
secondary: string;
link: string;
accent: string;
};
status: {
success: string;
warning: string;
error: string;
};
bg: string;
border: string;
}
```
### 内置主题变体
| 主题名称 | 适用场景 | 特点 |
|---------|---------|------|
| `dark` | 深色终端背景 | 高对比度文字 |
| `light` | 浅色终端背景 | 柔和配色 |
| `nord` | Nord 配色方案 | 蓝灰色调 |
| `dracula` | Dracula 配色 | 紫色主调 |
主题支持通过 `GEMINI_THEME` 环境变量或配置文件进行切换。
资料来源：[packages/cli/src/ui/themes/theme-manager.ts:1-80]()
## 交互流程
### 对话交互流程
```mermaid
sequenceDiagram
participant User as 用户
participant Composer as Composer组件
participant App as App根组件
participant Core as Core引擎
participant Model as Gemini模型
User->>Composer: 输入文本/命令
Composer->>App: 提交消息
App->>Core: 发送请求
Core->>Model: 流式请求
Model-->>Core: 流式响应
Core-->>App: 消息片段
App->>Composer: 清空输入
App-->>User: 显示消息
Note over Core,Model: 工具调用阶段
Core->>App: 请求工具确认
App->>User: 显示确认对话框
User->>App: 批准/拒绝
App-->>Core: 确认结果
```
### 工具确认流程
当模型请求执行敏感操作时，UI 层按以下步骤处理：
1. **检测请求**：Core 引擎识别需要确认的工具调用
2. **创建确认项**：生成包含操作详情的确认对象
3. **添加到队列**：将确认项加入 `ToolConfirmationQueue`
4. **用户决策**：用户查看详情并做出选择
5. **执行反馈**：根据用户决策执行或拒绝操作
6. **状态更新**：更新消息状态为已完成/已拒绝
资料来源：[packages/cli/src/ui/App.tsx:200-280]()
## 组件通信机制
### Props Drilling 与 Context
CLI UI 采用混合状态管理策略：
- **Props Drilling**：用于紧密耦合的父子组件间通信
- **React Context**：用于跨层级状态共享
- `ConfigContext`：应用配置
- `ThemeContext`：主题信息
- `MessagesContext`：消息历史
### 事件流处理
| 事件类型 | 处理层级 | 传播方向 |
|---------|---------|---------|
| 键盘事件 | Composer | 组件内处理 |
| 对话事件 | App | 根组件协调 |
| 确认事件 | ToolConfirmationQueue | 队列内部处理 |
资料来源：[packages/cli/src/ui/components/ToolConfirmationQueue.tsx:50-80]()
## 界面布局与响应式设计
### 固定布局模式
CLI UI 采用固定布局设计，针对标准终端尺寸优化：
| 区域 | 固定属性 | 说明 |
|-----|---------|------|
| 头部 | 固定高度 | Logo、版本、状态 |
| 消息区 | 弹性高度 | 占据主要内容空间 |
| 输入区 | 固定高度 | Composer 组件 |
### 宽度自适应
界面支持宽度自适应调整，当终端宽度小于阈值时自动切换为紧凑布局模式。Logo 和元数据从水平排列改为垂直堆叠。
资料来源：[packages/cli/src/ui/components/AppHeader.tsx:30-60]()
## 隐私通知组件
### 双隐私体系
Gemini CLI 根据用户使用模式展示不同的隐私声明：
| 隐私通知 | 适用场景 | 内容重点 |
|---------|---------|---------|
| `CloudFreePrivacyNotice` | 免费用户 | 数据收集和使用说明 |
| `GeminiPrivacyNotice` | 付费/企业用户 | API 服务条款引用 |
隐私通知在首次使用或设置变更时显示，包含以下核心内容：
- 数据收集范围说明
- 人类审核流程披露
- 数据保留期限（18个月）
- 退出选项
资料来源：[packages/cli/src/ui/privacy/CloudFreePrivacyNotice.tsx:1-50]()
## 辅助功能与可达性
### 键盘导航支持
完整的键盘操作支持确保纯键盘用户的可用性：
- **Tab 导航**：在可交互元素间切换
- **方向键**：列表项选择
- **Enter**：确认选择
- **Escape**：取消/返回
### 屏幕阅读器兼容
UI 元素包含语义化的 `aria-*` 属性标注，支持辅助技术正确解读界面结构。
## 扩展机制
### 对话框扩展
CLI UI 提供对话框扩展点，允许注册自定义对话框类型：
| 扩展类型 | 注册方式 | 典型用途 |
|---------|---------|---------|
| `InboxDialog` | 技能/补丁通知 | 技能安装确认 |
| `FolderTrustDialog` | 文件夹信任 | 本地配置加载确认 |
| `ExtensionRegistryView` | 扩展管理 | 扩展浏览和安装 |
### 视图扩展
`ExtensionDetails` 和 `ExtensionRegistryView` 组件支持展示扩展元数据，包括版本号、星级评分、功能标签等。
资料来源：[packages/cli/src/ui/components/views/ExtensionDetails.tsx:1-60]()
## 总结
Gemini CLI 用户界面是一个功能完备的终端交互系统，通过组件化架构实现了清晰的功能分离和良好的可维护性。界面设计充分考虑了终端环境的特殊性，在有限的视觉表现空间内提供了丰富的交互功能，包括对话管理、工具确认、主题定制和扩展支持等核心能力。
---
## 命令系统
### 相关页面
相关主题：[CLI用户界面](#page-cli-ui)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/cli/src/ui/components/Help.tsx](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/ui/components/Help.tsx)
- [packages/cli/src/ui/components/messages/ToolConfirmationMessage.tsx](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/ui/components/messages/ToolConfirmationMessage.tsx)
- [packages/core/src/agents/skill-extraction-agent.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/agents/skill-extraction-agent.ts)
- [packages/cli/src/ui/components/AboutBox.tsx](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/ui/components/AboutBox.tsx)
- [README.md](https://github.com/google-gemini/gemini-cli/blob/main/README.md)
# 命令系统
## 概述
Gemini CLI 的命令系统是用户与 CLI 交互的核心机制，提供了一套完整的命令执行框架。该系统支持多种命令类型，包括内置命令（Built-in Commands）、自定义命令（Custom Commands）和 MCP 命令（Model Context Protocol Commands）。命令系统设计为模块化架构，允许用户通过斜杠命令（`/`前缀）快速调用各种功能，同时支持自然语言执行 shell 命令。
命令系统的主要职责包括命令的注册、解析、路由和执行。通过统一的消息总线（MessageBus）架构，命令系统与工具系统紧密集成，实现了命令执行与 AI 模型响应的无缝衔接。系统还提供了完善的确认机制，确保涉及敏感操作（如网络访问、文件写入）的命令在执行前获得用户授权。
## 命令类型
### 内置命令
内置命令是 Gemini CLI 预置的标准功能集，提供了 CLI 核心操作的入口点。这些命令覆盖了帮助信息、聊天管理、系统设置等常用功能。用户可以通过在输入框中输入 `/commandname` 的方式直接调用这些命令。
内置命令的显示格式包含命令名称和描述信息，部分命令还支持子命令（subCommands）。系统会自动过滤掉标记为隐藏（hidden）的命令，只向用户展示可用的命令选项。命令的分类和组织便于用户快速找到所需功能。
| 命令类型 | 触发方式 | 可见性 |
|---------|---------|-------|
| 主命令 | `/commandname` | 默认显示 |
| 子命令 | `/commandname subcommand` | 嵌套显示 |
| MCP命令 | `/commandname [MCP]` | 带MCP标识 |
| Shell命令 | `!command` | 使用感叹号前缀 |
### MCP 命令
MCP（Model Context Protocol）命令是来自外部 MCP 服务器的命令。系统通过 MCP 协议与外部服务器通信，获取这些命令的定义和功能描述。MCP 命令在帮助界面中以 `[MCP]` 标签标识，便于用户识别其来源。
MCP 命令的确认流程与内置命令类似，但在工具确认界面中会明确标注为 MCP 类型。当 MCP 命令涉及网络访问或文件操作时，系统会显示相应的警告信息，提示用户注意安全风险。
### Shell 命令
Shell 命令允许用户直接在 CLI 环境中执行系统 shell 命令。用户可以通过两种方式触发 shell 命令：使用 `!` 前缀（如 `!npm run start`），或使用自然语言描述（如 "start server"）。
Shell 命令在确认界面中以黄色警告色标识，突出显示其潜在风险。系统会对每个 shell 命令进行安全检查，确认其是否涉及网络访问、文件读写等敏感操作。
## 命令解析机制
### 命令解析器架构
命令解析器（SlashCommandResolver）是命令系统的核心组件，负责将用户输入转换为可执行的命令对象。当用户在 CLI 输入框中输入以 `/` 开头的文本时，系统会触发命令解析流程。
解析器首先识别命令前缀，然后匹配用户输入与已注册的命令名称。如果找到完全匹配的命令，则直接返回该命令对象；如果未找到完全匹配，则可能触发命令建议或错误提示。
```
graph TD
A[用户输入 /command] --> B[命令解析器接收]
B --> C{命令类型判断}
C -->|内置命令| D[查找内置命令注册表]
C -->|MCP命令| E[查询MCP服务器]
C -->|自定义命令| F[搜索自定义命令目录]
D --> G[返回命令对象]
E --> G
F --> G
G --> H[执行命令处理器]
H --> I[返回执行结果]
```
### 命令注册流程
内置命令通过 BuiltinCommandLoader 在 CLI 启动时自动注册到命令系统中。加载器扫描预定义的命令模块，将每个命令及其元数据（名称、描述、子命令等）添加到命令注册表中。
自定义命令则通过文件系统监控实现动态加载。当用户在 `.gemini/commands` 目录下创建新的命令定义文件时，系统会自动检测并注册这些命令，无需重启 CLI。
## 命令确认机制
### 工具确认界面
当命令涉及敏感操作时，系统会显示工具确认界面（ToolConfirmationMessage）供用户审核。该界面清晰列出命令将执行的各项操作及其权限范围。
确认界面显示的信息包括：
- **命令名称**：显示即将执行的命令名称
- **网络访问**：如果命令需要网络访问，标注为 "Network: All Urls"
- **写入路径**：列出所有将被写入的文件路径
- **读取路径**：列出所有将被读取的文件路径
### 安全提示
Shell 命令在确认界面中以黄色警告色高亮显示，提醒用户这些命令将在系统级别执行。系统会根据 `ApprovalMode` 配置决定是否需要用户手动确认：
- **Manual 模式**：所有敏感操作都需要用户手动确认
- **Auto-Edit 模式**：自动批准编辑类操作
- **YOLO 模式**：跳过所有确认直接执行（不推荐）
| 确认模式 | 网络访问 | 文件写入 | 文件读取 |
|---------|---------|---------|---------|
| Manual | 需确认 | 需确认 | 需确认 |
| Auto-Edit | 需确认 | 自动批准 | 自动批准 |
| YOLO | 自动批准 | 自动批准 | 自动批准 |
## 自定义命令
### 命令定义
Gemini CLI 支持用户创建自定义命令来扩展功能。自定义命令存储在项目根目录的 `.gemini/commands` 目录下（资料来源：[README.md:1-100]()）。每个自定义命令都是一个独立的文件，可以包含特定的提示词和执行逻辑。
自定义命令的主要用途包括：
- 封装常用的复杂工作流程为一键操作
- 为特定项目创建专用命令集
- 共享和复用团队的最佳实践
### 创建流程
用户可以通过自然语言描述想要创建的命令功能，Gemini CLI 会自动生成相应的命令定义文件。创建过程中，系统会引导用户完善以下信息：
1. **触发条件（Triggers）**：定义命令被激活的关键词或模式
2. **执行步骤（Procedure）**：详细描述命令的执行逻辑
3. **注意事项（Pitfalls）**：提醒用户可能遇到的问题
4. **验证步骤（Verification）**：如何确认命令执行成功
### 技能提取与命令生成
skill-extraction-agent 模块（资料来源：[packages/core/src/agents/skill-extraction-agent.ts:1-100]()）负责从用户的对话历史中提取有价值的工作流程，并将其转化为可复用的技能或命令。该智能体分析会话内容，识别重复性操作，并建议用户是否需要创建自定义命令来简化这些操作。
## 命令显示组件
### 帮助界面
Help.tsx（资料来源：[packages/cli/src/ui/components/Help.tsx:1-100]()）组件负责渲染命令帮助界面。该组件从命令注册表中获取所有可用命令，过滤隐藏命令后按类别展示给用户。
帮助界面的布局特点：
- 主命令以粗体显示，带有强调色标识
- 子命令通过缩进和斜线前缀区分
- MCP 命令标注 `[MCP]` 标签
- Shell 命令使用 `!` 前缀标识
### 关于界面
AboutBox.tsx（资料来源：[packages/cli/src/ui/components/AboutBox.tsx:1-100]()）组件显示 CLI 版本信息和系统配置状态。该界面虽然不直接处理命令执行，但为用户提供当前会话的技术上下文，包括：
- CLI 版本号
- Git 提交信息
- 当前使用的模型版本
- Sandbox 环境配置
- 操作系统信息
## 键盘快捷键
命令系统与输入处理系统紧密集成，提供了丰富的键盘快捷键来提升操作效率：
| 快捷键 | 功能 | 说明 |
|-------|------|------|
| `Ctrl+Left/Right` | 单词跳转 | 在输入框中按单词快速移动光标 |
| `Ctrl+C` | 退出 | 退出当前 CLI 会话 |
| `/` | 命令触发 | 开始输入斜杠命令 |
## 扩展机制
### MCP 服务器集成
Gemini CLI 通过 MCP（Model Context Protocol）协议支持扩展服务器。用户可以配置额外的 MCP 服务器来引入新的命令和能力。官方示例包括与 Google Cloud Platform 的 Vertex AI Creative Studio 集成，支持媒体生成功能（Imagen、Veo、Lyria）。
MCP 服务器的配置通过标准 MCP 配置格式管理，CLI 启动时自动发现并注册可用的 MCP 命令。
### 工具绑定
命令系统与工具系统共享相同的消息总线架构。命令可以调用底层工具来完成具体操作，如文件读写、shell 执行、网络请求等。这种设计实现了命令层与功能层的分离，便于维护和扩展。
## 数据流
```
graph LR
A[用户输入] --> B{输入解析}
B -->|/command| C[内置命令]
B -->|!command| D[Shell命令]
B -->|自然语言| E[AI模型处理]
C --> F[命令执行器]
D --> G[Shell执行器]
E --> H[意图识别]
H --> I[工具调用]
F --> J[结果展示]
G --> J
I --> J
J --> K[UI更新]
```
## 最佳实践
### 命令命名规范
创建自定义命令时，建议遵循以下命名规范：
- 使用小写字母和连字符（如 `my-custom-command`）
- 避免与内置命令名称冲突
- 使用描述性名称，使命令用途一目了然
### 安全考虑
- 谨慎使用 YOLO 模式，该模式跳过所有安全确认
- 创建涉及文件操作的命令时，明确指定允许的路径范围
- 定期检查已注册的命令列表，确保没有未授权的命令
### 性能优化
- 避免在命令中执行过于复杂的逻辑
- 将耗时操作拆分为多个独立命令
- 使用子命令组织复杂的功能集
## 参考资料
- Gemini CLI 官方文档：https://www.geminicli.com/docs/reference/commands
- 自定义命令指南：https://www.geminicli.com/docs/cli/custom-commands
- 键盘快捷键参考：https://www.geminicli.com/docs/reference/keyboard-shortcuts
---
## 安全策略与策略引擎
### 相关页面
相关主题：[代理系统与子代理](#page-agent-system)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/core/src/policy/policy-engine.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/policy/policy-engine.ts)
- [packages/core/src/policy/toml-loader.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/policy/toml-loader.ts)
- [packages/core/src/policy/shell-safety.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/policy/shell-safety.ts)
- [packages/core/src/policy/sandboxPolicyManager.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/policy/sandboxPolicyManager.ts)
- [packages/core/src/availability/policyHelpers.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/availability/policyHelpers.ts)
- [packages/core/src/config/config.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/config/config.ts)
- [packages/cli/src/commands/extensions/examples/policies/README.md](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/commands/extensions/examples/policies/README.md)
# 安全策略与策略引擎
## 概述
Gemini CLI 的安全策略与策略引擎是保护用户系统安全的核心组件。该系统通过 TOML 配置文件定义安全规则，并在 CLI 执行命令前进行安全检查，防止恶意或危险操作执行。
策略引擎的核心职责包括：
- 加载和解析 `.toml` 格式的策略文件
- 在命令执行前进行安全验证
- 管理沙箱环境的访问权限
- 处理 shell 命令的安全性评估
- 支持扩展程序贡献额外的安全规则
## 架构设计
```mermaid
graph TD
A[用户命令] --> B[策略引擎 PolicyEngine]
B --> C{TOML 加载器
TomlLoader}
C --> D[核心策略文件]
C --> E[扩展策略文件]
C --> F[用户自定义策略]
D --> G[规则引擎]
E --> G
F --> G
G --> H{安全检查}
H -->|通过| I[命令执行]
H -->|拒绝| J[安全警告]
H -->|需要确认| K[用户确认对话框]
L[ShellSafety] --> G
M[SandboxPolicyManager] --> G
```
### 核心组件
| 组件 | 文件路径 | 职责 |
|------|----------|------|
| PolicyEngine | `packages/core/src/policy/policy-engine.ts` | 主策略引擎，协调所有策略检查 |
| TomlLoader | `packages/core/src/policy/toml-loader.ts` | 解析 TOML 格式的策略配置文件 |
| ShellSafety | `packages/core/src/policy/shell-safety.ts` | Shell 命令安全性检查 |
| SandboxPolicyManager | `packages/core/src/policy/sandboxPolicyManager.ts` | 沙箱环境策略管理 |
| policyHelpers | `packages/core/src/availability/policyHelpers.ts` | 策略链解析和辅助函数 |
## 策略文件格式
### TOML 配置文件结构
策略引擎使用 TOML 格式定义安全规则。每个策略文件包含以下核心部分：
```toml
# 规则定义
[rules]
# 规则名称 = 规则类型
# 确认要求
[confirm]
# 命令模式 = 确认消息
# 拒绝规则
[deny]
# 命令模式 = 拒绝消息
# 允许路径
[allowed_paths]
# 列出允许访问的目录
```
### 策略文件位置
策略文件按优先级从低到高搜索：
1. **内置核心策略** - CLI 内置的安全规则
2. **扩展贡献的策略** - 第三方扩展添加的策略
3. **用户自定义策略** - 用户本地配置的策略
资料来源：[packages/cli/src/commands/extensions/examples/policies/README.md]()
## 策略类型
### 1. 确认规则 (Confirm Rules)
需要用户确认才能执行的命令。配置格式：
```toml
[confirm]
"rm -rf" = "此命令将递归删除文件，是否继续？"
"sudo" = "即将以管理员权限执行命令"
```
当策略引擎检测到匹配的命令模式时，会暂停执行并显示确认对话框。
### 2. 拒绝规则 (Deny Rules)
完全禁止执行的命令。
```toml
[deny]
"grep.*\\.env" = "禁止搜索敏感文件"
"*credential*" = "禁止访问凭证相关文件"
```
资料来源：[packages/cli/src/commands/extensions/examples/policies/README.md]()
### 3. 路径限制规则 (Path Restrictions)
限制文件操作在特定目录范围内。
```toml
[allowed_paths]
read = ["/home/user/project", "/tmp"]
write = ["/home/user/project/src"]
```
### 4. 安全检查器 (Safety Checkers)
自定义的安全检查器函数，在特定操作前执行：
```toml
[safety_checkers]
allowed_path = true # 启用路径验证检查器
```
## 策略引擎核心流程
```mermaid
sequenceDiagram
participant CLI as Gemini CLI
participant PE as PolicyEngine
participant TL as TomlLoader
participant SS as ShellSafety
participant SPM as SandboxPolicyManager
CLI->>PE: 执行命令请求
PE->>TL: 加载策略配置
TL-->>PE: 返回策略规则列表
PE->>SS: 检查 Shell 安全性
SS-->>PE: 安全检查结果
PE->>SPM: 验证沙箱权限
SPM-->>PE: 沙箱检查结果
PE->>PE: 综合评估
alt 所有检查通过
PE-->>CLI: 允许执行
else 存在风险
PE-->>CLI: 请求用户确认
else 违反规则
PE-->>CLI: 拒绝执行
end
```
### 主要检查步骤
1. **策略加载阶段** - 收集所有适用策略
2. **模式匹配阶段** - 匹配命令与规则模式
3. **安全评估阶段** - 评估命令风险等级
4. **决策输出阶段** - 返回执行决策
## 沙箱策略管理
### SandboxPolicyManager
`SandboxPolicyManager` 负责管理沙箱执行环境的访问控制策略。
主要功能：
- **目录访问控制** - 限制沙箱内进程的文件系统访问
- **网络访问限制** - 控制沙箱进程的网络通信
- **进程隔离** - 管理沙箱内进程的执行权限
资料来源：[packages/core/src/policy/sandboxPolicyManager.ts]()
### 沙箱模式
| 模式 | 描述 | 安全性 |
|------|------|--------|
| unrestricted | 无限制模式 | 低 |
| restricted | 限制模式，仅允许预定义操作 | 中 |
| sandboxed | 完全沙箱模式，最严格限制 | 高 |
## Shell 安全检查
### ShellSafety 模块
`ShellSafety` 模块专门处理 Shell 命令的安全性评估。
```typescript
interface ShellSafetyCheck {
command: string; // 待检查的命令
riskLevel: RiskLevel; // 风险等级
matchedRules: string[]; // 匹配的规则列表
requiresConfirmation: boolean; // 是否需要确认
canDeny: boolean; // 是否可以拒绝
}
```
### 内置危险命令检测
策略引擎内置以下危险命令的自动检测：
- `rm -rf` - 递归删除文件
- `dd` - 直接磁盘写入
- `mkfs` - 格式化文件系统
- `> /dev/sd*` - 直接写入设备文件
## 策略扩展机制
### 扩展贡献策略
第三方扩展可以通过 `gemini-extension.json` 清单文件贡献安全策略：
```json
{
"policies": [
"policies/*.toml"
]
}
```
扩展贡献的策略文件必须位于扩展目录的 `policies/` 子目录中。
### 安全限制
**重要安全约束**：Gemini CLI 会忽略扩展贡献的任何 `allow` 决策或 `yolo` 模式配置。这确保了扩展只能增强安全性，而不能绕过用户确认机制。
资料来源：[packages/cli/src/commands/extensions/examples/policies/README.md]()
## 配置与集成
### 工具注册中的策略应用
策略引擎与工具注册系统集成，在工具注册时应用策略配置：
```typescript
maybeRegister(UpdateTopicTool, () =>
registry.registerTool(new UpdateTopicTool(this, this.messageBus)),
);
maybeRegister(LSTool, () =>
registry.registerTool(new LSTool(this, this.messageBus)),
);
maybeRegister(ReadFileTool, () =>
registry.registerTool(new ReadFileTool(this, this.messageBus)),
);
```
资料来源：[packages/core/src/config/config.ts:45-55]()
### 策略链解析
`policyHelpers` 模块提供策略链解析功能，支持多模型场景下的策略协调：
```typescript
function resolvePolicyChain(config: Config): PolicyChain {
// 根据当前配置返回适用的策略链
// 支持自定义模型和目录模型的策略分发
}
```
资料来源：[packages/core/src/availability/policyHelpers.ts]()
## 错误处理
### 策略验证失败
策略引擎会对加载的策略进行验证：
- TOML 语法验证
- 规则模式语法检查
- 路径有效性验证
- 冲突规则检测
验证失败的策略会被静默丢弃，不会影响其他策略的执行。
### 运行时错误
当策略检查过程中发生错误时：
1. 记录详细错误日志
2. 返回保守的安全决策（拒绝执行）
3. 向用户显示友好的错误提示
## 最佳实践
### 为扩展编写策略
1. **明确作用域** - 每个策略文件应有单一明确的目的
2. **使用具体模式** - 避免过于宽泛的通配符匹配
3. **提供清晰消息** - 拒绝和确认消息应清楚说明原因
4. **包含验证步骤** - 添加验证或陷阱步骤确保规则有效
### 用户自定义策略
用户可以在本地配置目录中创建自定义策略文件：
```
~/.gemini-cli/
├── policies/
│ ├── custom-deny.toml
│ └── project-rules.toml
```
## 总结
Gemini CLI 的安全策略与策略引擎通过模块化设计实现了灵活且强大的安全控制机制。TOML 格式的配置文件提供了易于维护的策略定义方式，而多层级的策略加载和验证流程确保了系统安全性。扩展机制允许社区贡献额外的安全规则，同时保持了核心安全约束不被绕过。
---
---
## Doramagic 踩坑日志
项目：google-gemini/gemini-cli
摘要：发现 23 个潜在踩坑项，其中 14 个为 high/blocking；最高优先级：安装坑 - 来源证据：Surface or quarantine invalid Auto Memory inbox patches。
## 1. 安装坑 · 来源证据：Surface or quarantine invalid Auto Memory inbox patches
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Surface or quarantine invalid Auto Memory inbox patches
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_58be51e305414f12a3dd5f6c39b5e777 | https://github.com/google-gemini/gemini-cli/issues/26523 | 来源类型 github_issue 暴露的待验证使用条件。
## 2. 配置坑 · 来源证据：Memory system bugs and quality improvements
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Memory system bugs and quality improvements
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_956d952c67c7469189ec67aef86139d4 | https://github.com/google-gemini/gemini-cli/issues/26516 | 来源类型 github_issue 暴露的待验证使用条件。
## 3. 运行坑 · 来源证据：Change the steering eval test to always pass
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Change the steering eval test to always pass
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_e480448796b34a7da894c9769d69b46c | https://github.com/google-gemini/gemini-cli/issues/23313 | 来源类型 github_issue 暴露的待验证使用条件。
## 4. 运行坑 · 来源证据：Model frequently creates tmp scripts in random spots
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Model frequently creates tmp scripts in random spots
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_abead6f384f94be497a8893d52d0ca2b | https://github.com/google-gemini/gemini-cli/issues/23571 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 5. 维护坑 · 来源证据：Gemini CLI encounters 400 error with > 128 tools
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Gemini CLI encounters 400 error with > 128 tools
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_1e04a5efd78143d79b2ef38a564c428f | https://github.com/google-gemini/gemini-cli/issues/24246 | 来源类型 github_issue 暴露的待验证使用条件。
## 6. 安全/权限坑 · 来源证据：Add deterministic redaction and reduce Auto Memory logging
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add deterministic redaction and reduce Auto Memory logging
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_33c66a37dc674c5084470c52157d3f4b | https://github.com/google-gemini/gemini-cli/issues/26525 | 来源类型 github_issue 暴露的待验证使用条件。
## 7. 安全/权限坑 · 来源证据：All model quotas not resetting, even after days
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：All model quotas not resetting, even after days
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_1ed06494b0e8487e9f5b9b5faa68374c | https://github.com/google-gemini/gemini-cli/issues/26967 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。
## 8. 安全/权限坑 · 来源证据：Gemini CLI 0.42.0-preview.1: [API Error: ..... v1internal:generateContent failed, reason: ] Request contains an invalid…
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Gemini CLI 0.42.0-preview.1: [API Error: ..... v1internal:generateContent failed, reason: ] Request contains an invalid argument at process.processTicksAndReje…
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_9f0cc269f15147bf94171001a3d0a145 | https://github.com/google-gemini/gemini-cli/issues/26572 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 9. 安全/权限坑 · 来源证据：Gemini failed to open in a temporary path A:\
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Gemini failed to open in a temporary path A:\
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_b7b6d80c305d48d2a7548e12a6621b72 | https://github.com/google-gemini/gemini-cli/issues/25216 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 10. 安全/权限坑 · 来源证据：Robust component level evalutions
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Robust component level evalutions
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_0b7e5ce9e4de49d1aae81349f2856cd7 | https://github.com/google-gemini/gemini-cli/issues/24353 | 来源类型 github_issue 暴露的待验证使用条件。
## 11. 安全/权限坑 · 来源证据：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
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_73f28f340a29499e9a1718d38d5500ad | https://github.com/google-gemini/gemini-cli/issues/25166 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。
## 12. 安全/权限坑 · 来源证据：Stop Auto Memory from retrying low-signal sessions indefinitely
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Stop Auto Memory from retrying low-signal sessions indefinitely
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_fb1dec66ee3c4a9f9faf5cb91b286667 | https://github.com/google-gemini/gemini-cli/issues/26522 | 来源类型 github_issue 暴露的待验证使用条件。
## 13. 安全/权限坑 · 来源证据：Tool "save_memory" not found.
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Tool "save_memory" not found.
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_7b0f9e9404664597ab5f60b481da55fe | https://github.com/google-gemini/gemini-cli/issues/26563 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。
## 14. 安全/权限坑 · 来源证据：Your idiotic AI disobeyed me completely lied and has now cost me 300 dollars worth of work that went into my obsidian -…
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Your idiotic AI disobeyed me completely lied and has now cost me 300 dollars worth of work that went into my obsidian - 10000s of files and work deleted not re…
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_4bdaf010293245ac9e6f4ceece341d76 | https://github.com/google-gemini/gemini-cli/issues/26856 | 来源类型 github_issue 暴露的待验证使用条件。
## 15. 安装坑 · 来源证据：feat(cli): expose model thinking events in --output-format stream-json
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：feat(cli): expose model thinking events in --output-format stream-json
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_5c2ad6806ee6413dbf441b91f6862364 | https://github.com/google-gemini/gemini-cli/issues/22083 | 来源类型 github_issue 暴露的待验证使用条件。
## 16. 能力坑 · 能力判断依赖假设
- 严重度：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.
## 17. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:968197216 | https://github.com/google-gemini/gemini-cli | last_activity_observed missing
## 18. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:968197216 | https://github.com/google-gemini/gemini-cli | no_demo; severity=medium
## 19. 安全/权限坑 · 存在安全注意事项
- 严重度：medium
- 证据强度：source_linked
- 发现：No sandbox install has been executed yet; downstream must verify before user use.
- 对用户的影响：用户安装前需要知道权限边界和敏感操作。
- 建议检查：转成明确权限清单和安全审查提示。
- 防护动作：安全注意事项必须面向用户前置展示。
- 证据：risks.safety_notes | github_repo:968197216 | https://github.com/google-gemini/gemini-cli | No sandbox install has been executed yet; downstream must verify before user use.
## 20. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:968197216 | https://github.com/google-gemini/gemini-cli | no_demo; severity=medium
## 21. 安全/权限坑 · 来源证据：CLI on start picks wrong default model
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：CLI on start picks wrong default model
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_4285a488cff443c1a1e3586dbea13786 | https://github.com/google-gemini/gemini-cli/issues/26971 | 来源类型 github_issue 暴露的待验证使用条件。
## 22. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:968197216 | https://github.com/google-gemini/gemini-cli | issue_or_pr_quality=unknown
## 23. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:968197216 | https://github.com/google-gemini/gemini-cli | release_recency=unknown