【万字长文】Gemini 3 Pro 全面指南：从免费订阅到 CLI / Agent 实战

string	启动服务器时使用的工作目录。	`undefined`
`mcpServers.<SERVER_NAME>.url`	string	使用 Server-Sent Events（SSE）通信的 MCP 服务器 URL。	`undefined`
`mcpServers.<SERVER_NAME>.httpUrl`	string	使用可流式 HTTP 通信的 MCP 服务器 URL。	`undefined`
`mcpServers.<SERVER_NAME>.headers`	object	随请求发送到 `url` 或 `httpUrl` 的 HTTP 头映射。	`undefined`
`mcpServers.<SERVER_NAME>.timeout`	number	MCP 服务器请求的超时时间（毫秒）。	`undefined`
`mcpServers.<SERVER_NAME>.trust`	boolean	信任该服务器并绕过所有工具调用确认。	`undefined`
`mcpServers.<SERVER_NAME>.description`	string	服务器的简要描述，用于展示用途。	`undefined`
`mcpServers.<SERVER_NAME>.includeTools`	string[]	从该 MCP 服务器中包含的工具名称列表（白名单）；未指定则启用全部工具。	`undefined`
`mcpServers.<SERVER_NAME>.excludeTools`	string[]	从该 MCP 服务器中排除的工具名称列表；优先级高于 `includeTools`。	`undefined`

4.16 telemetry

为 Gemini CLI 配置日志记录与指标采集。

属性	类型	说明	取值 / 备注
`enabled`	boolean	是否启用 telemetry。	—
`target`	string	telemetry 的采集目标位置。	`local` / `gcp`
`otlpEndpoint`	string	OTLP Exporter 的端点。	—
`otlpProtocol`	string	OTLP Exporter 的协议。	`grpc` / `http`
`logPrompts`	boolean	是否在日志中包含用户 prompt 的内容。	—
`outfile`	string	当 `target` 为 `local` 时，telemetry 写入的文件路径。	—
`useCollector`	boolean	是否使用外部 OTLP collector。	—

4.17 settings.json 示例

下面是一个具有嵌套结构的 settings.json 文件示例，该结构自v0.3.0 起提供：

{
  "general": {
    "vimMode": true,
    "preferredEditor": "code",
    "sessionRetention": {
      "enabled": true,
      "maxAge": "30d",
      "maxCount": 100
    }
  },
  "ui": {
    "theme": "GitHub",
    "hideBanner": true,
    "hideTips": false,
    "customWittyPhrases": [
      "You forget a thousand things every day. Make sure this is one of ’em",
      "Connecting to AGI"
    ]
  },
  "tools": {
    "sandbox": "docker",
    "discoveryCommand": "bin/get_tools",
    "callCommand": "bin/call_tool",
    "exclude": ["write_file"]
  },
  "mcpServers": {
    "mainServer": {
      "command": "bin/mcp_server.py"
    },
    "anotherServer": {
      "command": "node",
      "args": ["mcp_server.js", "--verbose"]
    }
  },
  "telemetry": {
    "enabled": true,
    "target": "local",
    "otlpEndpoint": "http://localhost:4317",
    "logPrompts": true
  },
  "privacy": {
    "usageStatisticsEnabled": true
  },
  "model": {
    "name": "gemini-1.5-pro-latest",
    "maxSessionTurns": 10,
    "summarizeToolOutput": {
      "run_shell_command": {
        "tokenBudget": 100
      }
    }
  },
  "context": {
    "fileName": ["CONTEXT.md", "GEMINI.md"],
    "includeDirectories": ["path/to/dir1", "~/path/to/dir2", "../path/to/dir3"],
    "loadFromIncludeDirectories": true,
    "fileFiltering": {
      "respectGitIgnore": false
    }
  },
  "advanced": {
    "excludedEnvVars": ["DEBUG", "DEBUG_MODE", "NODE_ENV"]
  }
}

json

4.18 命令历史记录

CLI 会保留你运行过的 shell 命令历史记录。为避免在不同项目之间发生冲突，该历史记录会存储在你用户主目录下的项目专用目录中。

位置： ~/.gemini/tmp/<project_hash>/shell_history

<project_hash> 是根据你项目的根路径生成的唯一标识符。
历史记录存储在名为 shell_history 的文件中。

4.19 环境变量

环境变量是配置应用程序的常见方式，尤其适用于API key 等敏感信息，或用于可能因环境不同而变化的设置，CLI 会自动从 .env 文件加载环境变量，加载顺序为：

Step 1. 当前工作目录中的 .env 文件。

Step 2. 若未找到，则向上在父目录中搜索，直到找到
.env 文件或到达项目根目录（由 .git 文件夹标识）或
主目录。

Step 3. 若仍未找到，则查找 ~/.env（位于用户主目录中）。

环境变量排除： 某些环境变量（如 DEBUG 和DEBUG_MODE）会被自动排除，不从项目 .env
文件中加载，以防干扰 gemini-cli 的行为。来自.gemini/.env 文件的变量永远不会被排除。你可以使用settings.json 文件中的 advanced.excludedEnvVars 设置来自定义此行为。

4.19.1 变量参数

环境变量	说明	备注 / 示例
`GEMINI_API_KEY`	你的 Gemini API key，用于访问 Gemini API。	在 `~/.bashrc` / `~/.zshrc` 或 `.env` 中设置
`GEMINI_MODEL`	指定默认使用的 Gemini 模型，覆盖内置默认值。	`export GEMINI_MODEL="gemini-3-flash-preview"`
`GOOGLE_API_KEY`	Google Cloud API key；express 模式下使用 Vertex AI 所必需。	`export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY"`
`GOOGLE_CLOUD_PROJECT`	Google Cloud Project ID；使用 Code Assist 或 Vertex AI 所必需。	`export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"`
`GOOGLE_APPLICATION_CREDENTIALS`	Google Application Credentials JSON 文件路径。	`export GOOGLE_APPLICATION_CREDENTIALS="/path/to/credentials.json"`
`OTLP_GOOGLE_CLOUD_PROJECT`	Telemetry 使用的 Google Cloud Project ID。	`export OTLP_GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"`
`GEMINI_TELEMETRY_ENABLED`	启用 telemetry（`true` / `1` 启用，其余视为禁用）。	覆盖 `telemetry.enabled`
`GEMINI_TELEMETRY_TARGET`	设置 telemetry 目标位置。	`local` / `gcp`，覆盖 `telemetry.target`
`GEMINI_TELEMETRY_OTLP_ENDPOINT`	设置 telemetry 的 OTLP 端点。	覆盖 `telemetry.otlpEndpoint`
`GEMINI_TELEMETRY_OTLP_PROTOCOL`	设置 telemetry 的 OTLP 协议。	`grpc` / `http`，覆盖 `telemetry.otlpProtocol`
`GEMINI_TELEMETRY_LOG_PROMPTS`	是否记录用户 prompt 到 telemetry。	覆盖 `telemetry.logPrompts`
`GEMINI_TELEMETRY_OUTFILE`	当目标为 `local` 时写入 telemetry 的文件路径。	覆盖 `telemetry.outfile`
`GEMINI_TELEMETRY_USE_COLLECTOR`	是否使用外部 OTLP collector。	覆盖 `telemetry.useCollector`
`GOOGLE_CLOUD_LOCATION`	Google Cloud Project 的区域（非 express 模式下 Vertex AI 必需）。	`export GOOGLE_CLOUD_LOCATION="us-central1"`
`GEMINI_SANDBOX`	`settings.json` 中 `sandbox` 的替代方案。	`true` / `false` / `docker` / `podman` / 自定义命令
`GEMINI_SYSTEM_MD`	用 Markdown 文件内容替换内置 system prompt。	`true` 使用 `./.gemini/system.md`
`GEMINI_WRITE_SYSTEM_MD`	将当前内置 system prompt 写入文件。	`true` 写入 `./.gemini/system.md`
`SEATBELT_PROFILE`	macOS 专用：切换 sandbox-exec profile。	`permissive-open` / `strict` / 自定义
`DEBUG` / `DEBUG_MODE`	启用详细 debug 日志。	建议在 `.gemini/.env` 中设置
`NO_COLOR`	禁用 CLI 中的所有彩色输出。	任意值
`CLI_TITLE`	自定义 CLI 窗口标题。	字符串
`CODE_ASSIST_ENDPOINT`	指定 Code Assist server 的端点。	用于开发与测试

4.19.2 环境变量脱敏

为防止敏感信息意外泄露，Gemini CLI 在执行工具（例如shell 命令）时，会自动从环境变量中打码潜在的秘密信息。这种“尽力而为”的打码适用于从系统继承的变量或从 .env 文件加载的变量。

默认打码规则：

按名称： 若变量名包含敏感词，如 TOKEN、SECRET、PASSWORD、KEY、AUTH``CREDENTIAL、PRIVATE 或 CERT，则会被打码。
按值： 若变量值匹配已知的秘密模式，则会被打码，例如：私钥（RSA、OpenSSH、PGP 等）、证书、包含凭据的 URL、API key 与 token（GitHub、Google、AWS、Stripe、Slack 等）
特定黑名单： 某些变量如 CLIENT_ID、DB_URI、DATABASE_URL 和 CONNECTION_STRING 默认总会被打码。

白名单（永不打码）：

常见系统变量（例如 PATH、HOME、USER、SHELL、TERM、LANG）。
以 GEMINI_CLI_ 开头的变量。
GitHub Action 特有变量。

你可以在 settings.json 文件中自定义该行为：

security.allowedEnvironmentVariables: 一个变量名列表，用于
永不打码，即使它们匹配敏感模式。
security.blockedEnvironmentVariables: 一个变量名列表，用于
总是打码，即使它们不匹配敏感模式。

{
  "security": {
    "allowedEnvironmentVariables": ["MY_PUBLIC_KEY", "NOT_A_SECRET_TOKEN"],
    "blockedEnvironmentVariables": ["INTERNAL_IP_ADDRESS"]
  }
}

json

4.20 命令行参数

在运行 CLI 时直接传入的参数可以覆盖该会话中的其他配置。

--model <model_name> (-m <model_name>):
- 指定本次会话使用的 Gemini model。
- 示例：npm start -- --model gemini-3-pro-preview
--prompt <your_prompt> (-p <your_prompt>):
- 用于将 prompt 直接传给命令。这会以非交互模式调用 Gemini CLI。
- 对于脚本示例，使用 --output-format json 标志以获得结构化输出。
--prompt-interactive <your_prompt> (-i <your_prompt>):
- 启动交互会话，并将所提供的 prompt 作为初始输入。
- prompt 会在交互会话中处理，而不是在此之前。
- 当从 stdin 通过管道传入输入时不可用。
- 示例：gemini -i "explain this code"
--output-format <format>:
- 描述： 指定非交互模式下 CLI 输出的格式。
- 取值：
  - text:（默认）标准的人类可读输出。
  - json: 机器可读的 JSON 输出。
  - stream-json: 以流式方式输出 JSON，实时发出事件。
- 注意： 对于结构化输出与脚本编写，请使用 --output-format json 或 --output-format stream-json 标志。
--sandbox (-s): 为本次会话启用 sandbox 模式。
--debug (-d): 为本次会话启用 debug 模式，提供更详细的输出。按 F12 打开debug 控制台以查看额外日志。
--help（或 -h）: 显示命令行参数的帮助信息。
--yolo: 启用 YOLO 模式，该模式会自动批准所有工具调用。
--approval-mode <mode>:设置工具调用的批准模式。可用模式：
- default: 每次工具调用都提示批准（默认行为）
- auto_edit: 自动批准编辑工具（replace、write_file），其余仍提示
- yolo: 自动批准所有工具调用（等同于 --yolo）
- plan: 工具调用只读模式（需要启用实验性 planning）。
  
  注意： 该模式目前仍在开发中，尚未完全
  可用。
- 不能与 --yolo 同时使用。新统一方式请使用 --approval-mode=yolo 代替--yolo。
- 示例：gemini --approval-mode auto_edit
--allowed-tools <tool1,tool2,...>:
- 一个以逗号分隔的工具名称列表，将绕过确认对话框。
- 示例：gemini --allowed-tools "ShellTool(git status)"
--extensions <extension_name ...> (-e <extension_name ...>):
- 指定本次会话要使用的扩展列表。若未提供，则使用所有可用扩展。
- 使用特殊术语 gemini -e none 可禁用所有扩展。
- 示例：gemini -e my-extension -e my-other-extension
--list-extensions (-l): 列出所有可用扩展并退出。
--resume [session_id] (-r [session_id]):
- 恢复先前的聊天会话。对最近的会话使用 “latest”，提供会话索引编号，或提供完整的会话UUID。
- 若未提供 session_id，则默认为 “latest”。
- 示例：gemini --resume 5 或 gemini --resume latest 或 gemini --resume a1b2c3d4-e5f6-7890-abcd-ef1234567890 或 gemini --resume
--list-sessions:
- 列出当前项目的所有可用聊天会话并退出。
- 显示会话索引、日期、消息数量，以及第一条用户消息的预览。
- 示例：gemini --list-sessions
--delete-session <identifier>:
- 通过索引编号或完整会话 UUID 删除特定聊天会话。
- 请先使用 --list-sessions 查看可用会话、它们的索引与UUID。
- 示例：gemini --delete-session 3 或 gemini --delete-session a1b2c3d4-e5f6-7890-abcd-ef1234567890
--include-directories <dir1,dir2,...>:
- 为多目录支持包含额外目录到工作区。
- 可以多次指定或使用逗号分隔的值。
- 最多可添加 5 个目录。
- 示例：--include-directories /path/to/project1,/path/to/project2 或
  --include-directories /path/to/project1 --include-directories /path/to/project2
--screen-reader: 启用屏幕阅读器模式，通过调整 TUI 以更好地兼容屏幕阅读器。
--version: 显示 CLI 的版本。
--experimental-acp: 以 ACP 模式启动 agent。
--allowed-mcp-server-names: 允许的 MCP server 名称。
--fake-responses: 指向包含伪造 model 响应的文件路径，用于测试。
--record-responses: 指向用于记录 model 响应的文件路径，用于测试。

4.21 上下文文件（Context Files）

Context files 虽然并不严格用于配置 CLI 的 _behavior_，但它们（默认使用 GEMINI.md，也可通过 context.fileName 设置配置）对于配置提供给 Gemini model 的 _instructional context_（也称为“memory”）至关重要。这个强大功能允许你提供项目专用说明、编码风格指南或任何相关背景信息，使 AI 的响应更贴合且更准确地满足你的需求，CLI 还包含 UI 元素，例如页脚中的指示器显示已加载的 context files 数量，以便让你了解当前激活的context。

用途： 这些 Markdown 文件包含你希望 Gemini model 在交互期间知晓的说明、指南或 context，系统被设计为以分层方式管理此 instructional context。

4.21.1 示例 context file 内容

下面是一个概念性示例（例如 GEMINI.md），展示 TypeScript项目根目录中的 context file 可能包含的内容：

## Project: My Awesome TypeScript Library

### General Instructions:

- When generating new TypeScript code, please follow the existing coding style.
- Ensure all new functions and classes have JSDoc comments.
- Prefer functional programming paradigms where appropriate.
- All code should be compatible with TypeScript 5.0 and Node.js 20+.

### Coding Style:

- Use 2 spaces for indentation.
- Interface names should be prefixed with `I` (e.g., `IUserService`).
- Private class members should be prefixed with an underscore (`_`).
- Always use strict equality (`===` and `!==`).

### Specific Component: `src/api/client.ts`

- This file handles all outbound API requests.
- When adding new API call functions, ensure they include robust error handling
  and logging.
- Use the existing `fetchWithRetry` utility for all GET requests.

### Regarding Dependencies:

- Avoid introducing new external dependencies unless absolutely necessary.
- If a new dependency is required, please state the reason.

markdown

这个示例展示了你如何提供通用的项目 context、特定的编码规范，甚至关于特定文件或组件的说明。你的 context files 越相关且精确，AI 就越能更好地协助你。强烈建议使用项目专用 context files 来建立约定与 context。

分层加载与优先级： CLI 通过从多个位置加载 context files（例如 GEMINI.md）来实现精巧的分层 memory 系统。该列表中越靠下（越具体）的文件内容通常会覆盖或补充越靠上（越通用）的文件内容。可使用 /memory show 命令检查具体的拼接顺序与最终 context。典型加载顺序为：

全局 context file：
- 位置：~/.gemini/<configured-context-filename>（例如
  用户主目录中的 ~/.gemini/GEMINI.md）。
- 作用域：为所有项目提供默认说明。
项目根目录及祖先目录的 context files：
- 位置：CLI 会在
  当前工作目录中搜索配置的 context file，然后在每个父目录中继续搜索，直到
  项目根目录（由 .git 文件夹标识）或用户主目录。
- 作用域：为整个项目或其重要部分提供相关 context。
子目录 context files（上下文/本地）：
- 位置：CLI 还会在
  当前工作目录下方的子目录中扫描配置的 context file（遵循 node_modules、.git 等常见
  忽略模式）。该搜索的广度默认限制为 200 个目录，但可通过 settings.json 中的
  context.discoveryMaxDirs 设置进行配置。
- 作用域：为特定组件、模块或子区域提供高度具体的说明。

拼接与 UI 指示： 所有找到的 context files 的内容会被拼接（并带有分隔符以标明其来源与路径）并作为 system prompt 的一部分提供给 Gemini model。CLI 页脚会显示已加载 context files 的数量，让你能快速直观地了解当前激活的 instructional context。

导入内容： 你可以使用 @path/to/file.md 语法导入其他 Markdown 文件，从而模块化你的 context files。更多细节请参见

用于 memory 管理的命令：

使用 /memory refresh 强制重新扫描并重新加载所有 context files（来自所有已配置位置）。这会更新 AI 的 instructional context。
使用 /memory show 显示当前加载的 combined instructional context，以便你验证层级与正在被 AI 使用的内容。

通过理解并利用这些配置层与 context files 的分层特性，你可以有效管理 AI 的 memory，并将
Gemini CLI 的响应更好地定制为符合你的特定需求与项目。

4.22 沙箱

Gemini CLI 可以在沙箱环境中执行潜在不安全的操作（例如 shell 命令和文件修改），以保护你的系统。

Sandboxing 默认禁用，但你可以通过以下几种方式启用：

使用 --sandbox 或 -s 标志。
设置 GEMINI_SANDBOX 环境变量。
在使用 --yolo 或 --approval-mode=yolo 时默认启用 sandbox。

默认情况下，它使用预构建的 gemini-cli-sandbox Docker image。

对于项目专用的 sandboxing 需求，你可以在项目根目录创建自定义 Dockerfile，路径为.gemini/sandbox.Dockerfile。该 Dockerfile 可以基于基础 sandbox image：

FROM gemini-cli-sandbox

## Add your custom dependencies or configurations here
## For example:
## RUN apt-get update && apt-get install -y some-package
## COPY ./my-config /app/my-config

dockerfile

当存在 .gemini/sandbox.Dockerfile 时，你可以在运行 Gemini CLI 时使用 BUILD_SANDBOX环境变量来自动构建自定义sandbox image：

BUILD_SANDBOX=1 gemini -s

bash

4.23 使用统计

为了帮助我们改进 Gemini CLI，我们会收集匿名化的 usage statistics。该数据帮助我们了解 CLI 的使用方式、识别常见问题，并确定新功能的优先级。

我们收集的内容：

工具调用： 我们记录被调用的工具名称、它们是否成功或失败，以及执行耗时。我们不收集传递给工具的参数或任何返回数据。
API 请求： 我们记录每次请求所使用的 Gemini model、请求耗时，以及是否成功。我们不收集prompts 或响应的内容。
会话信息： 我们收集有关 CLI 配置的信息，例如启用的工具与 approval mode。

我们不收集的内容：

个人身份信息（PII）： 我们不收集任何个人信息，例如你的姓名、邮箱地址或 API key。
Prompt 与响应内容： 我们不会记录 prompts 的内容或 Gemini model 的响应内容。
文件内容： 我们不会记录由 CLI 读取或写入的任何文件内容。

如何选择退出：

你可以随时通过将 settings.json 文件中 privacy 类别下的usageStatisticsEnabled 属性设置为 false 来选择退出 usage statistics 收集：

{
  "privacy": {
    "usageStatisticsEnabled": false
  }
}

json

4.24 小结

到这里，Gemini CLI 的整体配置体系就完整串起来了，理解它的关键，并不是记住所有配置项，而是掌握**“在什么场景下，用哪种方式配置”**，读者们可以按下面这个思路来使用 Gemini CLI：

一、长期稳定的偏好，用 settings.json

如果某个配置 每天都会用、希望一直生效，那就放进 settings.json：

常用模型（model.name）
UI 行为（主题、是否隐藏 Banner、是否显示上下文信息）
是否启用 sandbox
工具白名单 / 自动批准策略
会话保留策略、上下文压缩策略等

个人使用：放在 ~/.gemini/settings.json

项目使用 / 团队协作：放在项目根目录 .gemini/settings.json，让所有人 clone 后即生效

二、敏感或环境相关的值，用环境变量

凡是 API Key、Credential、不同机器不一样的配置，都不要写死在配置文件中：

GEMINI_API_KEY
GOOGLE_APPLICATION_CREDENTIALS
Telemetry / Sandbox / Debug 开关
CI 环境下的特殊参数

推荐做法是：

本地：使用 .env 或 shell 配置文件
项目：使用 .gemini/.env
CI/CD：使用平台提供的 Secret / Env 配置

这样既安全，又不会污染仓库。

三、只想临时改一次，用命令行参数

只是这一次想换模型、开 debug、跑脚本，不需要动任何配置文件：

临时切模型：--model
非交互调用：--prompt
机器可读输出：--output-format json
强制 sandbox / debug / resume 会话

命令行参数始终拥有最高优先级，适合测试、排错和自动化脚本。

四、真正提升效果的关键 Context Files（GEMINI.md）

如果希望 Gemini 更懂你的项目，而不仅仅是“能回答问题”，那么一定要使用 GEMINI.md 或自定义 context files：

项目背景说明
编码规范 / 风格约定
目录结构说明
工具使用约束
团队协作规则

这部分内容会作为 system prompt 注入模型，是影响回答质量最直接、性价比最高的配置手段。

五、一句话使用原则

默认行为不满意 → settings.json
涉及密钥和环境差异 → 环境变量
只想改一次 → CLI 参数
想让模型“更聪明” → context files

理解并善用这套分层配置机制，就可以把 Gemini CLI 从“能用”，调教到“顺手、可控、可复用”。希望能帮助到大家，感谢阅读，本文完！

05 工程化与治理：Checkpoint、Sandbox、Telemetry 与企业最佳实践

在这里插入图片描述

本文是进阶篇”，重点整理 Gemini CLI 中更偏工程/企业落地的能力：

Checkpointing（检查点）：AI 写文件前自动快照，随时回滚
企业级集中式配置：系统默认值/覆盖项/用户/工作区的合并与优先级
安全治理：工具白名单/黑名单、禁用 YOLO、MCP 工具治理、网络代理、审计遥测
Sandbox（沙箱）：Docker/Podman/macOS Seatbelt 隔离执行
OpenTelemetry：日志/指标/Trace 可观测性，成本与治理更透明

5.1 Checkpointing（检查点）

原文地址：https://geminicli.com/docs/cli/checkpointing/

一句话解释： 当你允许 Gemini CLI 调用会“改文件”的工具（比如写文件、替换内容）时，它会先自动做一次项目快照，确保你随时能恢复到“改之前”的状态。

这让你可以更大胆地让 AI 做重构/批量修改，因为你知道——随时可撤销。

5.1.1 工作原理

当你批准一个会修改文件系统的工具（例如 write_file 或 replace）时，CLI 会自动创建一个“检查点”。检查点包含：

Git 快照（影子仓库提交）
- CLI 会在一个特殊的影子 Git 仓库中创建一次提交
- 影子仓库位置：~/.gemini/history/<project_hash>
- 这不会干扰你自己项目的 Git 仓库（你的 .git 不会被动）
对话历史 ：与 agent 的整个对话会被保存（方便恢复上下文）
工具调用信息 ：即将执行的工具调用细节也会被记录（恢复后可重新执行/修改/忽略）

5.1.2 数据存放在哪？

所有检查点数据都会存储在本机：

Git 快照（影子仓库）：~/.gemini/history/<project_hash>
对话历史与工具调用 JSON：通常在
~/.gemini/tmp/<project_hash>/checkpoints

这也意味着它适合企业环境：不会把你的项目快照上传到远程仓库。

5.1.3 启用 Checkpointing

注意：--checkpointing 这个命令行标志已在 0.11.0 移除，现在只能通过 settings.json 开启。

在你的 settings.json 里添加：

{
  "general": {
    "checkpointing": {
      "enabled": true
    }
  }
}

json

5.1.4 使用 /restore 管理检查点

启用后，检查点会自动创建。管理它们用 /restore。

1）列出当前项目所有检查点：

/restore

text

CLI 会列出检查点文件，一般命名类似：

2025-06-22T10-00-00_000Z-my-file.txt-write_file

含义通常是：时间戳 + 文件名 + 工具名

2）恢复到某个检查点：

/restore <checkpoint_file>

text

例子：

/restore 2025-06-22T10-00-00_000Z-my-file.txt-write_file

text

恢复后会发生三件事：

项目文件回滚到快照状态
CLI 内对话历史恢复
原始工具调用会再次出现（你可以重新运行/修改/忽略）

5.2 面向企业的 Gemini CLI（集中式配置 + 安全治理最佳实践）

企业里最常见的痛点是：

大家配置不一致
工具权限不可控
网络、审计、合规无法统一管理

Gemini CLI 提供了 系统级配置 来解决这些问题。

5.2.1 系统设置文件

企业管理中最强大的工具是全局系统设置文件：

system-defaults.json：系统默认基线（最低优先级）
settings.json：系统覆盖项（最高优先级，最终裁决）

CLI 会从 4 个文件合并配置（单值设置优先级如下）：

系统默认值（system-defaults.json）
用户设置（~/.gemini/settings.json）
工作区设置（<project>/.gemini/settings.json）
系统覆盖项（settings.json）最高

对数组/对象类型（如 includeDirectories、mcpServers），是“合并”而不是直接覆盖。

5.2.2 合并示例

系统默认值（system-defaults.json）：

{
  "ui": {
    "theme": "default-corporate-theme"
  },
  "context": {
    "includeDirectories": ["/etc/gemini-cli/common-context"]
  }
}

json

用户设置（~/.gemini/settings.json）：

{
  "ui": {
    "theme": "user-preferred-dark-theme"
  },
  "mcpServers": {
    "corp-server": {
      "command": "/usr/local/bin/corp-server-dev"
    },
    "user-tool": {
      "command": "npm start --prefix ~/tools/my-tool"
    }
  },
  "context": {
    "includeDirectories": ["~/gemini-context"]
  }
}

json

工作区设置（/.gemini/settings.json）：

{
  "ui": {
    "theme": "project-specific-light-theme"
  },
  "mcpServers": {
    "project-tool": {
      "command": "npm start"
    }
  },
  "context": {
    "includeDirectories": ["./project-context"]
  }
}

json

系统覆盖项（/etc/…/settings.json）：

{
  "ui": {
    "theme": "system-enforced-theme"
  },
  "mcpServers": {
    "corp-server": {
      "command": "/usr/local/bin/corp-server-prod"
    }
  },
  "context": {
    "includeDirectories": ["/etc/gemini-cli/global-context"]
  }
}

json

最终合并结果（最终真正生效的配置）：

{
  "ui": {
    "theme": "system-enforced-theme"
  },
  "mcpServers": {
    "corp-server": {
      "command": "/usr/local/bin/corp-server-prod"
    },
    "user-tool": {
      "command": "npm start --prefix ~/tools/my-tool"
    },
    "project-tool": {
      "command": "npm start"
    }
  },
  "context": {
    "includeDirectories": [
      "/etc/gemini-cli/common-context",
      "~/gemini-context",
      "./project-context",
      "/etc/gemini-cli/global-context"
    ]
  }
}

json

结论：

theme：系统覆盖项最高优先级，强制生效
mcpServers：对象合并，同名 corp-server 以系统覆盖项为准
includeDirectories：数组拼接（系统默认 → 用户 → 工作区 → 系统覆盖）

5.2.3 系统配置文件的位置（不同系统）

Linux：/etc/gemini-cli/settings.json
Windows：C:\ProgramData\gemini-cli\settings.json
macOS：/Library/Application Support/GeminiCli/settings.json
可用环境变量覆盖：GEMINI_CLI_SYSTEM_SETTINGS_PATH

5.2.4 企业常用技巧

问题：用户可以自己 export GEMINI_CLI_SYSTEM_SETTINGS_PATH=... 指向别的配置，从而绕开公司策略。

解决：用一个 wrapper 脚本把环境变量写死。

把下面脚本保存为 /usr/local/bin/gemini（并确保它在 PATH 中优先于真实 gemini）：

#!/bin/bash

## Enforce the path to the corporate system settings file.
export GEMINI_CLI_SYSTEM_SETTINGS_PATH="/etc/gemini-cli/settings.json"

## Find the original gemini executable.
REAL_GEMINI_PATH=$(type -aP gemini | grep -v "^$(type -P gemini)$" | head -n 1)

if [ -z "$REAL_GEMINI_PATH" ]; then
  echo "Error: The original 'gemini' executable was not found." >&2
  exit 1
fi

## Pass all arguments to the real Gemini CLI executable.
exec "$REAL_GEMINI_PATH" "$@"

bash

5.2.5 工具访问控制（白名单优先 + 禁用 YOLO 模式）

企业安全治理的核心目标：最小权限原则（Least Privilege）。

5.2.5.1 coreTools（允许列表）

只允许安全的只读工具（示例：读文件 + 列目录）：

{
  "tools": {
    "core": ["ReadFileTool", "GlobTool", "ShellTool(ls)"]
  }
}

json

5.2.5.2 excludeTools（阻止列表）

例如阻止删除命令：

{
  "tools": {
    "exclude": ["ShellTool(rm -rf)"]
  }
}

json

风险：黑名单是字符串匹配思路，聪明用户可能绕过。生产环境建议优先使用白名单。

5.2.5.3 禁用 YOLO 模式

目的：防止模型在没有明确批准的情况下执行工具。

{
  "security": {
    "disableYoloMode": true
  }
}

json

5.2.6 MCP（自定义工具）治理

如果你们用 MCP server（Model-Context Protocol）接入内部工具，就一定要理解：

mcpServers 会合并
同名 server 的优先级：System > Workspace > User
用户无法覆盖 system 定义，但可以新增“新名字”的 server（除非你用 allowed 限制）

5.2.6.1 限制 MCP 服务器暴露的工具（includeTools / excludeTools）

推荐 includeTools（只开放必要能力）：

{
  "mcp": {
    "allowed": ["third-party-analyzer"]
  },
  "mcpServers": {
    "third-party-analyzer": {
      "command": "/usr/local/bin/start-3p-analyzer.sh",
      "includeTools": ["code-search", "get-ticket-details"]
    }
  }
}

json

5.2.6.2 更安全的企业模式（system 中同时定义 + 加 allowed 白名单）

system settings.json 示例（强治理）：

{
  "mcp": {
    "allowed": ["corp-data-api", "source-code-analyzer"]
  },
  "mcpServers": {
    "corp-data-api": {
      "command": "/usr/local/bin/start-corp-api.sh",
      "timeout": 5000
    },
    "source-code-analyzer": {
      "command": "/usr/local/bin/start-analyzer.sh"
    }
  }
}

json

效果：

用户新增的 server 名字不在 mcp.allowed → 直接被阻止
同名 server 即使用户定义 → system 会覆盖

5.2.6.3 不安全模式（只定义 server 但不加 allowed）

{
  "mcpServers": {
    "corp-data-api": {
      "command": "/usr/local/bin/start-corp-api.sh"
    }
  }
}

json

风险：用户可以在自己 settings 里新增任意 server，最终会合并进可用工具列表。

5.3 Sandbox（沙箱）

原文地址：https://geminicli.com/docs/cli/sandbox/

沙箱的定位：在 AI 工具执行与宿主机之间加一道隔离层，避免误操作造成系统损坏。

沙箱方式有如下两种：

macOS Seatbelt（仅 macOS）：sandbox-exec，轻量
Docker/Podman 容器沙箱：跨平台、隔离更强（推荐企业）

安装与验证方式如下：

npm install -g @google/gemini-cli
gemini --version

bash

快速开启沙箱（3 种方式）

方式 1：命令行 flag

gemini -s -p "analyze the code structure"

bash

方式 2：环境变量

export GEMINI_SANDBOX=true
gemini -p "run the test suite"

bash

方式 3：settings.json（长期配置）

{
  "tools": {
    "sandbox": "docker"
  }
}

json

启用优先级（从高到低）：

命令行：-s/--sandbox
环境变量：GEMINI_SANDBOX=true|docker|podman|sandbox-exec
settings：{"tools":{"sandbox":true}}（或指定 docker/podman）

macOS Seatbelt Profiles（常用）：

通过 SEATBELT_PROFILE 环境变量设置：

permissive-open（默认）：限制写入外部目录，允许网络
permissive-closed：限制写入外部目录，不允许网络
restrictive-open：更严格，允许网络
restrictive-closed：最严格

自定义容器沙箱参数（SANDBOX_FLAGS）

例如 Podman 禁用 SELinux label：

export SANDBOX_FLAGS="--security-opt label=disable"

bash

多个参数：

export SANDBOX_FLAGS="--flag1 --flag2=value"

bash

调试沙箱（DEBUG）：

DEBUG=1 gemini -s -p "debug command"

bash

注意：项目 .env 的 DEBUG=true 不会影响 gemini-cli，因为会被自动排除，需要调试请用 .gemini/.env

5.4 OpenTelemetry 可观测性

原文地址：https://geminicli.com/docs/cli/telemetry/

为什么需要可观测性？

统计团队使用情况与功能采用率
监控 token、延迟、失败率
审计工具调用（谁在用什么工具做什么）
成本优化（缓存 token、模型路由、重试行为）

5.4.1 核心配置项（settings.json / 环境变量）

所有遥测行为都由 .gemini/settings.json 控制，也可以用环境变量覆盖。

常见配置示例：

{
  "telemetry": {
    "enabled": true,
    "target": "gcp",
    "logPrompts": false
  }
}

json

企业建议：

enabled: true（开启）
logPrompts: false（不要采集 prompt 文本，避免敏感信息泄露）
target: gcp 或 local 看你们的后端

5.4.2 Google Cloud 遥测（推荐 Direct Export）

1）启用遥测：

{
  "telemetry": {
    "enabled": true,
    "target": "gcp"
  }
}

json

2）运行 CLI 并产生数据：

正常使用 gemini 即可。

3）查看（Console）：

Logs / Metrics / Traces：在 Google Cloud Console 中查看

5.4.3 本地遥测

{
  "telemetry": {
    "enabled": true,
    "target": "local",
    "otlpEndpoint": "",
    "outfile": ".gemini/telemetry.log"
  }
}

json

5.4.4 典型企业 system settings 汇总示例

{
  "tools": {
    "sandbox": "docker",
    "core": [
      "ReadFileTool",
      "GlobTool",
      "ShellTool(ls)",
      "ShellTool(cat)",
      "ShellTool(grep)"
    ]
  },
  "mcp": {
    "allowed": ["corp-tools"]
  },
  "mcpServers": {
    "corp-tools": {
      "command": "/opt/gemini-tools/start.sh",
      "timeout": 5000
    }
  },
  "telemetry": {
    "enabled": true,
    "target": "gcp",
    "otlpEndpoint": "https://telemetry-prod.example.com:4317",
    "logPrompts": false
  },
  "advanced": {
    "bugCommand": {
      "urlTemplate": "https://servicedesk.example.com/new-ticket?title={title}&details={info}"
    }
  },
  "privacy": {
    "usageStatisticsEnabled": false
  }
}

json

5.5 小结

到这里，Gemini CLI 的企业级与工程化能力就基本梳理完了。可以看到，Gemini CLI 的设计目标并不只是“提升个人编码效率”，而是从一开始就围绕 可控性、安全性与可运维性 来构建，这也是它能进入真实工程与企业环境的关键。

回顾一下本文涉及的几个关键能力：

Checkpointing：让 AI 的“写文件 / 重构 / 批量修改”变成一件可回滚、可恢复、可审计的事情 → 这是 AI 能真正进入生产仓库的前提
集中式配置与优先级合并：系统 / 用户 / 工作区 / 覆盖项的多层合并 → 让“统一策略 + 灵活使用”不再是二选一
工具治理 + MCP 安全模型：白名单优先、禁用 YOLO、MCP allowed + includeTools → 把 AI 的能力牢牢限制在“你允许的边界内”
Sandbox（沙箱执行）：Docker / Podman / macOS Seatbelt → 即使 AI 出错，也被关在笼子里
OpenTelemetry 可观测性：日志、指标、Trace、成本、审计 → 让 AI 使用情况像任何一个后端服务一样“看得见、管得住”

感谢阅读，希望能帮助到大家，本文完！

06 Skills：按需加载的专家技能体系（Agent Skills）

在这里插入图片描述

如果要真正把 Gemini CLI 用到中大型项目或团队协作场景中时，一个绕不开的问题也逐渐显现出来：

如何让 AI 在“知道得足够多”的同时，又不过度消耗上下文、避免被无关信息干扰？

传统的做法，往往是通过 PROMPT.md、GEMINI.md 等全局上下文文件，把所有背景知识一股脑塞给模型，随着项目演进，这类文件不可避免地变得臃肿、难维护，也越来越“吃 Token”。为了解决这一痛点，可以使用 —— Agent Skills。

本文将围绕 Agent Skills 的设计理念、启用方式、目录规范以及一个完整的实战案例，带大家理解它是如何通过 “按需加载上下文”的方式，让 AI 真正具备 模块化、可复用、可治理的专家能。

6.1 什么是 Agent Skills？

在传统的 AI 辅助开发中，我们通常会在项目根目录下放置一个类似于 PROMPT.md 或 GEMINI.md 的全局上下文文件。但这种做法有一个痛点：随着项目变大，全局背景信息会越来越多，不仅消耗大量的 Token，还可能让 AI 的注意力分散。

Agent Skills 就是为了解决这个问题而生的，它是基于“Agent Skills 开放标准”构建的，简单来说，它将 特定领域的知识、操作流程和相关资源打包成一个独立的文件夹。

它的核心逻辑是“按需加载” (On-demand expertise)： AI 平时并不知道这些详细指令，只有当你提出相关需求时，Gemini 才会自动“激活”对应的技能，将相关上下文拉取到当前会话中。

四大核心优势：

【按需加载 (Progressive Disclosure)】：初始阶段只加载技能的元数据（名称和描述），大幅节省 Context Tokens。
【知识沉淀与共享】：可以将复杂的团队工作流（例如特定的代码审查规范、部署流程）打包，团队成员开箱即用。
【可复用的工作流】：确保复杂的多步任务始终以一致的标准化流程执行。
【资源捆绑】：不仅能写 Prompt，还能把脚本、模板、示例数据和指令打包在一起给 AI 使用。

6.2 启用与管理技能

注意： 该功能目前处于实验阶段，需要开启 experimental.skills 才能使用。你可以在 /settings 交互界面中搜索 “Skills” 进行开启。

Gemini CLI 会从三个主要位置自动发现技能（优先级依次降低）：

Workspace 技能 (.gemini/skills/)：特定于当前项目的技能，建议提交到 Git 仓库与团队共享。
User 技能 (~/.gemini/skills/)：你的个人专属技能，在所有项目中均可使用。
Extension 技能：随扩展程序安装的技能。

在终端中，可以使用 gemini skills 命令行工具来管理：

## 列出所有已发现的技能
gemini skills list

## 从 Git 仓库安装一个公开的技能包
gemini skills install https://github.com/user/repo.git

## 安装到特定项目的 Workspace 作用域
gemini skills install /path/to/skill --scope workspace

## 启用/禁用特定技能
gemini skills enable my-expertise

bash

如果正处于 Gemini 的交互式会话中，也可以使用斜杠命令：

/skills list：查看技能状态
/skills disable <name> / /skills enable <name>：管理技能开关

6.3 案例实战

创建一个 Skill 非常简单，它本质上就是一个包含 SKILL.md 文件的目录。

建议遵循以下官方推荐的约定（虽然只有 SKILL.md 是必选的）：

my-skill/
├── SKILL.md        # (必选) 元数据和核心指令 Prompt
├── scripts/        # (可选) 可供 AI 运行的 bash/python/node 脚本
├── references/     # (可选) 静态文档、Schema 或示例数据
└── assets/         # (可选) 代码模板等二进制资源

text

当技能被激活时，AI 可以看到整个文件夹的目录树，并能读取里面的脚本和资源！

这里以 代码审查专家 (Code Reviewer) 案例 讲解。

SKILL.md 由两部分组成：顶部的 YAML 元数据，和底部的 Markdown 指令。

最重要的一点：description 字段是 AI 决定是否激活该技能的唯一依据，必须写得精准！

我们在 ~/.gemini/skills/code-reviewer/SKILL.md 中创建以下内容：

---
name: code-reviewer
description: 专门审查代码风格、安全性和性能。当用户要求“反馈”、“Review”、“审查”或“检查代码”时使用此技能。
---

## Code Reviewer (代码审查专家)

你是一名资深的技术专家。当用户要求审查代码时，请严格遵守以下工作流：

1. **分析**：审查暂存的 Git 变更或提供的特定文件。确保变更范围合理。
2. **风格**：确保代码遵循本项目的规范（参考项目根目录的编码指南）。
3. **安全性**：重点检查 SQL 注入、XSS、敏感信息硬编码等安全隐患。
4. **测试覆盖**：验证新逻辑是否包含对应的单元测试。

**输出格式**：请以简洁的 Markdown 列表形式，分别列出“亮点 (Strengths)”和“改进建议 (Opportunities)”。

markdown

下次当你对 Gemini CLI 说：“帮我 Review 一下刚才写的代码” 时，Gemini 就会识别到触发词，自动激活这个技能，并按照你设定的 4 步流程进行专业的代码审查。

不用担心 AI 乱用你的本地文件。Agent Skills 的运行机制在安全方面设计得很周到：

激活拦截：当 AI 想要激活某个技能时，CLI 会弹出一个用户确认提示，告知你技能的名称和请求访问的目录。
沙箱隔离：只有你批准后，SKILL.md 的内容才会被注入历史记录，对应的文件夹权限才会被开放给 AI。

6.4 技能编写建议

想要用好 Agent Skills，建议遵循以下几点：

① Description（描述）是重中之重：AI 激活技能的逻辑类似于函数的语义搜索，你的 description 应该包含具体的触发词。例如，不要写“擅长写代码”，而是写“当需要生成 React 组件或编写前端测试用例时使用”。

② 区分作用域 (Scope)：

将个人的提效工具放在 User 级别 (~/.gemini/skills/)，比如“Git Commit Message 生成器”、“个人周报总结助手”。
将团队规范放在 Workspace 级别 (.gemini/skills/)，比如“团队特有 CI/CD 修复指南”、“微服务部署脚本助手”，并将其提交到 Git。

③ “Don’t Just Prompt, Automate” (结合脚本)：

既然支持文件夹，就不要只在 SKILL.md 里写文字，如果技能是关于“日志分析”，不如在 scripts/ 下放一个 python 脚本专门抓取日志，并在 SKILL.md 里告诉 AI：“遇到错误时，先运行 scripts/fetch_logs.py 获取最新日志”。

6.5 小结

从本质上看，Agent Skills 并不是“又一种 Prompt 写法”，而是 Gemini CLI 在 Agent 架构层面迈出的关键一步：

它把“提示工程”从一次性的文本输入，升级为可版本化、可组合、可审计的能力模块。

通过 Agent Skills，你可以：

把零散的 Prompt 沉淀为长期资产
把个人经验升级为团队共享的专家能力
把复杂流程从“靠记忆”变成“可自动执行的标准化工作流”

Agent Skills 几乎是一个绕不开、也非常值得尽早投入的能力。如果你觉得本文对你有帮助，欢迎点赞、收藏或关注，谢谢大家的阅读，本文完！

07 Tools：内置工具与工具调用模型

在这里插入图片描述

经过前面几篇文章的铺垫，相信大家已经能够顺利使用 Gemini CLI 完成日常开发任务，但在实际工程中，真正拉开效率差距的，并不是“会不会用命令”，而是是否理解 Gemini CLI 背后那套工具机制。

Gemini CLI 并不是一个简单的对话式终端，而是通过一组高度模块化的 Tools，让大模型能够直接：

感知并操作本地文件系统
执行真实的 Shell 命令并基于结果继续推理
获取最新的网络信息，避免模型幻觉
记住项目规范与个人偏好
在复杂任务中进行自我规划与状态管理
甚至通过 MCP 协议对接外部系统

本文将聚焦 Gemini CLI 的核心工具体系，结合官方文档与真实案例，逐一拆解每类工具的设计目的、使用方式以及工程实践中的最佳用法。

7.1 核心工具深度解析

7.1.1 文件系统工具 (File System)

官方文档链接：https://geminicli.com/docs/tools/file-system

这是与日常开发结合最紧密的工具集，赋予了 AI 操作本地代码库的能力。

list_directory (列出目录)

用于查看项目结构。AI 会自动读取项目中的 .gitignore 文件，智能过滤掉 node_modules 等无关文件，从而减少 Token 消耗并保持上下文简洁。

read_file (读取文件)

这是 AI 理解代码的核心途径。除了纯文本文件，它还支持读取图片、音频甚至 PDF。对于超大文件，该工具支持智能分页读取，防止撑爆模型的上下文窗口。

write_file (写入文件)

直接在本地创建或覆盖文件。如果路径中包含不存在的文件夹，它会自动创建完整的目录树。出于安全考虑，此操作默认需要用户在终端按回车确认。

search_file_content (内容搜索)

在代码库中搜索特定文本。其底层优先调用 git grep 命令，这使得它能够实现毫秒级的跨文件搜索，比传统的遍历快得多。

replace (智能替换)

极其强大的代码修改工具。与传统的正则匹配不同，它通过“上下文匹配”来修改文件。即使目标文件在你和 AI 对话期间发生了轻微的偏移（如加了换行），它的自我纠错机制也能精准定位修改位置，大大提高了安全性。

7.1.2 Shell 命令行工具 (Shell)

官方文档链接：https://geminicli.com/docs/tools/shell

让 AI 替你执行 Git 操作、运行构建脚本，甚至启动开发服务器。

run_shell_command (运行命令)

AI 可以通过此工具执行任意系统命令，并捕获标准输出 (Stdout)、错误输出 (Stderr) 和退出码，支持在命令末尾添加 & 符号以启动后台进程。

交互式 TUI 支持

如果开启了交互模式，AI 甚至可以运行 vim、htop 或 git rebase -i 等基于文本用户界面（TUI）的复杂程序。

安全配置建议 (settings.json)：强烈建议在配置文件中使用白名单模式，严防 AI 误操作

{
  "tools": {
    "shell": {
      "enableInteractiveShell": true, 
      "core": ["run_shell_command(git)", "run_shell_command(npm)", "run_shell_command(pnpm)"], 
      "exclude": ["run_shell_command(rm)"] 
    }
  }
}

json

7.1.3 网络获取与搜索

官方文档链接：https://geminicli.com/docs/tools/web-fetch

摆脱本地环境限制，让 AI 获取实时资讯。

web_fetch (网页抓取)

单次请求最多可并发抓取 20 个 URL。如果目标网站屏蔽了 Gemini 的官方服务器 API，CLI 会自动降级，使用你的本地网络环境进行抓取，确保成功率。

google_web_search (谷歌搜索)

官方文档链接：Web Search Tool

内置了 Google Search API。返回的结果不仅包含摘要信息，还会提供可验证的来源链接（Citations），确保信息的准确性。

7.1.4 记忆工具

官方文档链接：https://geminicli.com/docs/tools/memory

避免每次对话都要重复介绍项目背景和代码规范。

save_memory (保存记忆)

该工具会将你的偏好信息永久写入 ~/.gemini/GEMINI.md 文件中。每次启动 CLI 时，系统会自动将该文件内容作为 System Prompt 的一部分加载。

最佳实践：建议仅用于存储核心元数据，如项目规范（“总是使用 TypeScript”）、代码风格偏好等，不建议存储大段的对话历史。

7.1.5 Todos 任务清单

官方文档链接：https://geminicli.com/docs/tools/todos

面对长链条的复杂需求，AI 的思路容易发散，Todos 工具帮助 AI 进行“自我规划”。

write_todos (编写待办)

当接到复杂指令（如“初始化一个 React 项目”）时，AI 会先生成任务列表，每个任务包含 pending、in_progress 或 completed 状态。在执行过程中，你可以随时按 Ctrl+T 快捷键，弹出工作进度面板查看 AI 当前进展。

7.1.6 MCP 服务器集成

官方文档链接：https://geminicli.com/docs/tools/mcp-server

MCP (Model Context Protocol) 是一种开放标准，通过它，Gemini CLI 的能力可以被无限扩展。

可以通过配置 MCP 服务器，让 Gemini CLI 连接到任何外部系统，例如公司内部的 Jira、本地的 MySQL 数据库，或者是 AWS 云资源。在终端输入 /mcp 即可进入交互式管理界面。

7.2 案例实践

接下来看看在真实场景中，Gemini CLI 是如何工作的。

案例一：自动化重构老旧代码 (结合 File System)

场景：接手老 React 项目，需将所有废弃的 componentWillMount 重构为 useEffect。

用户 Prompt：“在 src 目录下找出所有使用 componentWillMount 的组件，理解逻辑，并用 useEffect 重构。”
AI 执行流：glob 搜索 → read_file 阅读上下文 → replace 生成差异 Diff → 等待按回车确认→ 瞬间修改完毕。

案例二：一键排查并修复 CI/CD 报错 (结合 Shell)

场景：拉取新代码后，npm run test 终端爆红。

用户 Prompt：“帮我运行 npm run test，分析报错原因，修复代码并自动重新运行直到通过。”
AI 执行流：run_shell_command 运行测试 → 分析 Stderr 发现 lodash 版本过低 → run_shell_command("npm install lodash@latest") → 再次运行测试 → 全绿通过。

案例三：解决冷门框架的疑难杂症 (结合 Web Search)

用户 Prompt：“我在用 Fresh 框架时遇到 ‘Dynamic imports not allowed’ 报错，搜一下 GitHub Issues 给解决方案。”
AI 执行流：google_web_search 搜索 GitHub → web_fetch 抓取前三个 Issue 详情 → 直接告诉你：去 deno.json 里加一行配置项即可。

案例四：新员工的自动入职向导 (结合 Memory)

第一天告诉 AI：“记住：我们的后端是 Go，Git Commit 必须带上 Jira ID（如 feat: [JIRA-123]…）。”
几天后日常开发：
- 用户：“帮我把当前修改提交一下。”
- AI：自动运行 git status，分析 Diff，生成 feat: [JIRA-123] 增加用户登录接口，无需重复提示规范！

案例五：全栈项目从 0 到 1 (结合 Todos)

用户 Prompt：“用 FastAPI 和 Vue3 初始化一个记账本，要有前后端目录和添加账单 API。”
AI 执行流：触发 write_todos，生成包含建目录、装依赖、写代码的 8 步清单，像流水线一样推进，永不“断片”。

案例六：化身临时 DBA (结合 MCP)

前提：配置了 MySQL MCP Server。
用户 Prompt：“帮我查一下 users 表里 ID 为 10086 的用户，最近的 5 条金币消耗记录。”
AI 执行流：通过 MCP 读取表结构 (get_table_schema) → 自动写 SQL (run_sql) 以 Markdown 表格形式返回数据。

7.3 小结

本文参考：https://geminicli.com/docs/tools

本文从工具视角系统梳理了 Gemini CLI 的能力体系，重点解析了文件系统、Shell、网络搜索、记忆、Todos 以及 MCP 等核心工具的设计与使用方式。

这些工具共同构成了 Gemini CLI 的执行基础，使大模型能够在真实开发环境中完成“读代码、跑命令、查资料、记规范、推进任务”等工程行为，只有理解并合理组合这些工具，才能在实际项目中稳定、高效地发挥 Gemini CLI 的价值。感谢阅读，希望能帮助到大家，本文完！

08 Hooks：生命周期拦截与安全加固

在这里插入图片描述

在 AI 辅助开发的浪潮中，Gemini CLI 提供了一种将大模型能力无缝集成到终端的方法。然而，真正的生产力提升往往来自于“量身定制”。如何在 AI 开始写代码前，强行灌输你的项目架构图？如何在 AI 试图删除敏感文件时，紧急制动？

本文将带你深入探索 Gemini CLI 的核心定制机制——Hooks（钩子）。通过本文，你将掌握其底层 I/O 机制、全生命周期事件流。

8.1 核心架构

Gemini CLI 的运行机制是一个经典的智能体循环 (Agentic Loop)：它接收输入，调用模型，解析意图，执行工具，再将结果反馈给模型。Hooks 是这个循环中的“拦截器”，它们在不修改 CLI 源码的情况下，通过标准输入输出（stdin/stdout）进行进程间通信（IPC）。

8.1.1 Hook 的基础配置 (hook.json)

要注册一个 Hook，你需要在项目根目录下的 .gemini/hooks/<hook-name>/ 文件夹中创建两个文件：

脚本文件（如 index.js 或 main.py）
hook.json (配置清单)：这决定了你的脚本在什么时候触发。

示例 hook.json：

{
  "name": "project-context-injector",
  "description": "在 AI 思考前注入项目架构说明",
  "events": ["BeforeAgent"], 
  "command": "node index.js",
  "enabled": true
}

json

8.1.2 进程间通信法则 (IPC Rules)

输入 (Stdin)：Gemini CLI 暂停循环，将当前上下文以 JSON 字符串形式灌入你的脚本。
输出 (Stdout)：你的脚本只能向 stdout 输出合法的 JSON 字符串，作为对 CLI 的响应。
日志 (Stderr)：所有的 console.log (非JSON)、调试信息、错误警告，必须且只能输出到 stderr。Gemini CLI 会捕获这些信息并在调试面板中展示。

注意：如果在 Python 中写了 print("Starting hook...")，或者在 Node 中写了 console.log("Fetching data")，会导致 CLI 接收到的 JSON 损坏，触发解析错误。

8.2 生命周期事件 (Hook Events Reference)

原文链接：https://geminicli.com/docs/hooks/reference

Gemini CLI 提供了极其细粒度的控制点，以下是智能体循环中触发 Hook 的顺序：

事件名称 (Event)	触发时机	典型应用场景
`BeforeAgent`	用户输入刚进来，AI 开始思考前。	上下文注入：附加代码规范、Git diff 历史。
`BeforeModel`	CLI 即将向大模型发送网络请求前。	提示词改写：动态翻译、自动添加 Few-shot 示例。
`AfterModel`	大模型返回原始文本响应后。	内容审核：过滤违禁词、结构化解析输出。
`BeforeTool`	CLI 解析出需要调用工具（如执行 bash、读写文件）时。	安全沙箱：拦截危险命令（如 `rm -rf`），防止密钥泄露。
`AfterTool`	工具执行完毕，结果即将发回给模型前。	结果脱敏：将执行结果中的敏感 IP、密码替换为 `[REDACTED]`。
`AfterAgent`	整个交互轮次结束，最终回复呈现给用户后。	异步操作：记录日志到数据库、触发 Webhook 通知。

8.3 案例实践

原文链接：https://geminicli.com/docs/hooks/writing-hooks

8.3.1 案例一：[Node.js] 缓存高耗时操作 (最佳实践)

如果你的 Hook 需要查询大型数据库，每次都查会拖慢 AI 速度，我们需要实现缓存机制。

目录：.gemini/hooks/cache-demo/index.js
事件：BeforeAgent

#!/usr/bin/env node
const fs = require('fs');
const path = require('path');

// 从 stdin 读取 CLI 传入的当前状态
const input = JSON.parse(fs.readFileSync(0, 'utf-8'));

// 缓存文件路径
const CACHE_FILE = path.join(process.env.GEMINI_PROJECT_DIR, '.gemini/hook-cache.json');
const CACHE_TTL = 3600 * 1000; // 缓存 1 小时

async function getProjectContext() {
  // 检查缓存
  if (fs.existsSync(CACHE_FILE)) {
    const cache = JSON.parse(fs.readFileSync(CACHE_FILE, 'utf-8'));
    if (Date.now() - cache.timestamp < CACHE_TTL) {
      console.error("[Hook] 命中缓存，极速返回！"); // 输出到 stderr
      return cache.data;
    }
  }

  console.error("[Hook] 缓存失效，正在请求远程 API...");
  // 模拟耗时网络请求...
  const data = "项目规范：React 18, TailwindCSS, 严禁使用 class 组件。"; 
  
  // 写入缓存
  fs.writeFileSync(CACHE_FILE, JSON.stringify({ timestamp: Date.now(), data }));
  return data;
}

(async () => {
  const context = await getProjectContext();
  
  // 最终的 JSON 输出到 stdout
  console.log(JSON.stringify({
    hookSpecificOutput: {
      hookEventName: 'BeforeAgent',
      additionalContext: `\n### 实时项目上下文\n${context}`
    }
  }));
})();

javascript

8.3.2 案例二：[Python] 拦截危险的系统命令

Python 在数据处理和安全检查上非常方便。我们写一个拦截 sudo 或 rm 命令的安全 Hook。

目录：.gemini/hooks/security-check/main.py
事件：BeforeTool

#!/usr/bin/env python3
import sys
import json

def main():
    # 1. 从标准输入读取上下文
    input_data = json.load(sys.stdin)
    
    # 2. 获取当前要执行的工具和内容
    tool_name = input_data.get("tool_name")
    tool_input = input_data.get("tool_input", {}).get("content", "")

    # 3. 安全检测逻辑
    dangerous_keywords = ["rm -rf", "sudo", "chown", "chmod 777"]
    
    if tool_name == "shell":
        for kw in dangerous_keywords:
            if kw in tool_input:
                # 打印到 stderr 作为调试记录
                print(f"[安全警告] 拦截到危险命令: {kw}", file=sys.stderr)
                
                # 4. 输出拦截指令到 stdout
                result = {
                    "decision": "deny",  # 关键：拒绝执行
                    "reason": f"检测到危险的 Shell 命令: {kw}",
                    "systemMessage": "⚠️ 安全策略阻止了本次操作，请手动执行或修改命令。"
                }
                print(json.dumps(result))
                sys.exit(2) # 退出码 2 表示系统阻止

    # 5. 安全通过
    print(json.dumps({"decision": "allow"}))
    sys.exit(0)

if __name__ == "__main__":
    main()

python

8.4 数据结构参考 (Reference)

为了精确控制，你需要了解 CLI 会传入哪些数据，以及你可以返回哪些字段。

8.4.1 CLI 输入给 Hook 的数据 (stdin)

无论哪个事件，都会收到这个核心对象：

{
  "timestamp": "2024-05-20T10:00:00Z",
  "session_id": "ses_abc123",
  "hook_event_name": "BeforeAgent",
  "messages": [ /* 完整的历史对话记录数组 */ ],
  "working_dir": "/Users/dev/my-project",
  "tool_name": "shell", // 仅在 Tool 相关事件中存在
  "tool_input": { ... } // 仅在 Tool 相关事件中存在
}

json

8.4.2 Hook 可以返回的控制字段 (stdout)

你的输出直接决定了 CLI 的下一步行为：

additionalContext (String): 在 prompt 后追加的不可见（对用户）上下文。
prompt (String): 直接覆盖用户的原始 prompt。
decision (“allow” | “deny”): 在 Tool 事件中，决定是否执行工具。
continue (Boolean): 设为 false 可在此轮次中强制停止整个循环。

8.5 小结

本文围绕 Gemini CLI 的 Hooks 机制 展开，系统性地介绍了其在智能体循环中的定位与工作原理，重点解析了 Hook 的基础配置方式、基于 stdin/stdout 的进程间通信规则，以及 Hooks 在 Agent 全生命周期中可介入的关键事件节点。感谢阅读，希望能帮助到大家，本文完！

09 Extensions：扩展打包、开发与发布

在这里插入图片描述

通过 Gemini CLI 扩展，可以将提示词（Prompts）、MCP（模型上下文协议）服务器、Agent 技能（Agent Skills）和自定义命令打包成一个用户友好的格式。无论你是想为团队内部构建特定的工作流，还是想向开源社区分享你的 AI 工具，Gemini CLI 扩展都能轻松满足。

本文将基于官方文档，详细介绍 Gemini CLI 扩展的工作原理、开发流程、最佳实践以及如何发布你的扩展。

9.1 什么是 Extensions？

简单来说，Gemini CLI 扩展（Extensions）是一个包含配置和代码的目录，用于扩展 CLI 的原生能力，它的核心功能包括：

MCP 服务器集成：允许模型调用外部工具（如读取文件、调用 API、查询数据库）。
自定义命令 (Custom Commands)：为常用的复杂 Prompt 创建快捷指令（如 /fs:grep-code）。
Agent 技能 (Agent Skills)：提供按需触发的专家能力和专门的工作流程。
生命周期钩子 (Hooks)：在 CLI 的特定生命周期事件中拦截和自定义行为。

9.1.1 扩展的工作原理

启动时，Gemini CLI 会在 ~/.gemini/extensions/ 目录下查找扩展，每个扩展的核心是 gemini-extension.json 配置文件。如果存在冲突（例如扩展命令与用户命令同名），扩展命令会自动添加扩展名前缀进行冲突解决（例如 /gcp.deploy）。

9.2 快速入门

从零开始，创建一个包含 MCP 服务器和自定义命令的扩展。

9.2.1 前置准备

确保已经安装了 Gemini CLI 以及 Node.js / TypeScript 环境。

9.2.2 初始化扩展

Gemini CLI 提供了现成的模板，运行以下命令，使用 mcp-server 模板创建名为 my-first-extension 的扩展：

gemini extensions new my-first-extension mcp-server

bash

这会生成一个包含 gemini-extension.json、package.json 和 TypeScript 源码的目录结构。

9.2.3 理解核心文件 gemini-extension.json

这是扩展的“身份证”，定义了扩展如何被加载：

{
  "name": "my-first-extension",
  "version": "1.0.0",
  "mcpServers": {
    "nodeServer": {
      "command": "node",
      "args": ["${extensionPath}${/}dist${/}example.js"],
      "cwd": "${extensionPath}"
    }
  }
}

json

小贴士：使用 ${extensionPath} 变量可以确保扩展无论安装在何处，路径都能正确解析。

9.2.4 编写 MCP 工具代码 (example.ts)

在 example.ts 中，可以注册自定义工具。例如，注册一个获取网络数据的工具 fetch_posts：

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
// ... 省略 imports
const server = new McpServer({ name: 'prompt-server', version: '1.0.0' });

server.registerTool('fetch_posts', {
  description: '从公共 API 获取帖子列表。',
  inputSchema: z.object({}).shape,
}, async () => {
  const apiResponse = await fetch('https://jsonplaceholder.typicode.com/posts');
  const posts = await apiResponse.json();
  return { content: [{ type: 'text', text: JSON.stringify(posts.slice(0, 5)) }] };
});

typescript

9.2.5 构建与本地链接

在开发阶段，我们使用 link 命令将开发目录链接到 CLI 扩展目录，这样改动可以实时生效：

cd my-first-extension
npm install
npm run build
gemini extensions link .

bash

重启 Gemini CLI 后，你就可以对 AI 说：“Fetch posts” 来测试你的新工具了。

9.3 丰富扩展功能

9.3.1 添加自定义命令 (Custom Commands)

在扩展目录下创建 commands/fs/grep-code.toml：

prompt = """
请总结以下模式的搜索结果 `{{args}}`。
搜索结果：
!{grep -r {{args}} .}
"""

toml

重启后，可以运行 /fs:grep-code "console.log"，AI 会自动帮你搜索并分析代码。

9.3.2 提供持久上下文 (GEMINI.md)

在根目录创建 GEMINI.md，并在 gemini-extension.json 中配置 "contextFileName": "GEMINI.md"。这里的文本会作为系统提示词加载，指导 AI 如何使用你的扩展。

9.3.3 添加 Agent 技能 (Agent Skills)

在 skills/security-audit/SKILL.md 中定义安全审计技能。当用户询问“检查安全漏洞”时，CLI 会自动激活这个技能，而不需要常驻内存。

9.4 最佳实践与用法指南

9.4.1 用户环境配置 (Settings)

如果扩展需要 API Key，不要硬编码。使用 gemini-extension.json 中的 settings 字段：

"settings": [
  {
    "name": "API Key",
    "description": "Your API key for the service.",
    "envVar": "MY_API_KEY",
    "sensitive": true
  }
]

json

安装时，CLI 会安全地提示用户输入，并保存在扩展目录下的 .env 文件中。

9.4.2 巧用变量

在配置和 Hook 中，善用以下变量：

${extensionPath}: 扩展安装路径
${workspacePath}: 当前工作区路径
${/}: 跨平台的路径分隔符

9.4.3 扩展管理日常用法

作为用户或开发者，你常用以下命令来管理扩展：

安装：gemini extensions install <github-url-or-local-path>
更新：gemini extensions update <name> (更新所有扩展可加 --all)
启用/禁用：gemini extensions disable <name> --scope workspace (支持工作区级别隔离)
卸载：gemini extensions uninstall <name>

9.5 如何发布?

开发完成后，如何分享给全世界？Gemini CLI 支持两种发布模式：

9.5.1 通过 Git 仓库发布（推荐日常迭代）

最简单的方法。只需将代码推送到公开的 GitHub 仓库，用户即可通过 URL 安装：

gemini extensions install https://github.com/your-name/your-extension

bash

Release Channels 管理：用户可以通过 --ref=stable 安装特定分支。你可以用 dev 分支开发，稳定后 Merge 到 stable 或默认分支。

9.5.2 通过 GitHub Releases 发布（适合生产环境）

对于包含编译步骤（如 TypeScript 构建）或特定平台二进制文件的扩展，GitHub Releases 是最佳选择。用户下载的是打包好的压缩文件，速度更快。

自动化发布最佳实践 (GitHub Actions)：
利用 GitHub Actions 自动构建多平台包。包的命名规范必须遵循：{平台}.{架构}.{扩展名}.{压缩格式}，例如 darwin.arm64.my-tool.tar.gz。

## 示例 GitHub Action 步骤片段
- name: Create release assets
  run: |
    npm run package -- --platform=darwin --arch=arm64
    npm run package -- --platform=linux --arch=x64
    npm run package -- --platform=win32 --arch=x64

yaml

当配置正确时，Gemini CLI 会自动检测用户的操作系统（macOS/Linux/Windows）并下载匹配的架构包。

9.6 小结

Gemini CLI 的扩展机制极其灵活且对开发者友好。从简单的 Prompt 集合到包含复杂 MCP 逻辑的本地工具库，它都能轻松胜任，赶紧动手开发你的第一个扩展，打造属于你自己的超级 AI 命令行吧！

参考文档：

码字不易，如果本文对您有帮助，欢迎点赞、收藏并在评论区分享你的 Gemini CLI 扩展想法！

10 架构与贡献：CLI 组件解密与参与贡献

在这里插入图片描述

随着大模型技术的爆发，如何在终端（Terminal）高效地与 AI 交互成为了开发者关注的焦点，今天我们来聊聊 Gemini CLI —— 一个不仅能让你在命令行畅玩 Gemini 模型，还拥有强大插件系统和严谨架构的开源工具。无论你是想高效使用 Gemini，还是想学习如何开发一个高质量的 AI CLI 工具，这篇文章都能带你一探究竟。

10.1 Gemini CLI 是什么？

简单来说，Gemini CLI 是一个交互式的 REPL（Read-Eval-Print Loop）环境，它将 Google Gemini 模型的强大能力直接带入了本地的终端。

不像简单的 API 调用脚本，Gemini CLI 是一个成熟的生产力工具，它具备以下特性：

丰富的工具集（Tools）：它不仅仅是聊天。内置了文件系统操作（读写文件）、Shell 命令执行、网页抓取（Web Fetch）、Google 搜索、甚至管理你的代办事项（Todos）。
扩展性（Extensions）：支持安装和开发扩展，你可以像给 VS Code 装插件一样给它增强功能。
沙箱机制（Sandbox）：在执行系统命令或文件操作时，支持容器化的沙箱环境，确保你的主机安全。
企业级特性：支持 Checkpointing（检查点保存会话）、Headless 模式（用于自动化脚本）、以及 Token 缓存优化。

10.2 架构解密

了解工具的架构不仅有助于使用，更是学习优秀系统设计的良机。根据官方的架构文档，Gemini CLI 采用了前后端分离的设计理念（尽管它们都运行在本地）。

10.2.1 核心组件分离

Gemini CLI 主要由两个核心包组成：

packages/cli (前端/客户端)：

职责：负责“门面”工作，处理用户输入、管理历史记录、渲染 UI（使用 Ink 库构建的 React 终端 UI）、处理主题和配置。
关键点：它专注于用户体验，不处理具体的 AI 逻辑。

packages/core (后端/核心)：

职责：这是“大脑”，它接收 CLI 的请求，构建 Prompt，与 Gemini API 通信，并管理工具（Tools）的注册与执行。
关键点：所有的状态管理、对话上下文、以及工具调用的逻辑都在这里。

10.2.2 交互流程

当你在终端输入一条命令时，由于系统内部发生了一系列精妙的流转：

Step 1 用户输入：：你在 packages/cli 提供的界面中输入 Prompt。
Step 2 请求转发：：CLI 将输入发送给 packages/core。
Step 3 Prompt 构建与 API 请求：：Core 层构建包含上下文和工具定义的 Prompt，发送给 Gemini API。
Step 4 模型决策：
- Gemini API 返回直接回复。
- 或者，Gemini API 请求调用某个工具（比如“读取这个文件”）。
Step 5 工具执行：：
- 如果是敏感操作（如写文件、执行 Shell），Core 层会请求用户确认（除非在沙箱或只读模式下）。
- Core 执行工具，并将结果返还给 Gemini API。
Step 6 最终响应：API 生成最终回答，Core 将其传回 CLI，CLI 渲染展示给用户。

这种 模块化（Modularity） 设计使得开发者可以轻松替换前端 UI，或者将 Core 复用到其他应用中。

10.3 开发者指南：如何参与贡献？

Gemini CLI 是开源的，如果你想为它贡献代码，或者想魔改一个属于自己的版本，官方的贡献指南非常详尽。以下是核心步骤的精简版。

10.3.1 环境准备

Node.js 版本：开发环境下，官方强烈建议使用 Node.js ~20.19.0。这通常是因为上游依赖的特定问题，使用 nvm 可以轻松切换。
包管理器：项目使用 npm。

10.3.2 开发工作流

Step 1. Fork & Clone：

git clone https://github.com/google-gemini/gemini-cli.git
cd gemini-cli
npm install

bash

Step 2. 构建：

npm run build       # 构建所有包
## 或者
npm run build:all   # 构建包 + 沙箱容器（推荐）

bash

Step 3. 运行与调试：

启动：npm start
调试（VS Code）：直接按 F5 或运行 npm run debug。
UI 调试：由于 CLI 使用了 React，你可以使用 React DevTools 来调试终端 UI！

DEV=true npm start
## 在另一个终端运行
npx react-devtools@4.28.5

bash

10.3.3 提交代码前的检查 (Preflight)

在提交 PR 之前，务必运行“起飞前检查”：

npm run preflight

bash

这个命令会执行 ESLint、Prettier 格式化以及所有的单元测试，确保你的代码符合规范。

10.3.4 提 PR 流程

关联 Issue：所有的 PR 必须关联一个现有的 Issue。
前端自动化审查：如果你修改了 packages/cli，可以在 PR 评论中运行 /review-frontend <PR_NUMBER>，官方提供了一个实验性的工具来自动审查 React 反模式。
分配：看到感兴趣的 Issue，评论 /assign 即可认领（每人最多同时认领 3 个）。

10.4 小结

Gemini CLI 展示了现代 AI 命令行工具应有的样子：人性化的交互、安全的沙箱机制以及清晰解耦的架构。

本文基于 Gemini CLI 官方文档整理，技术在不断迭代，建议以官方最新文档为准。参考：

希望本文能帮助到大家，谢谢阅读，本文完！

11 总结回顾：核心能力与最佳实践

在这里插入图片描述

11.1 Gemini 3 为何物？

我们不应把 Gemini 简单理解为“聊天版 AI”，它更像是 嵌入在搜索、办公、开发与操作系统中的通用智能引擎。Gemini 3 的核心变革在于：

原生多模态：从底层同时理解文本、图片、音频、视频和代码，并进行跨模态推理。
Agent-First (智能体优先)：AI 不再只是“回答”，而是具备了“执行”能力（读写文件、跑命令）。
生态闭环：结合 Antigravity (Agent-First AI IDE)、Google Workspace 等，成为系统级智能中枢。

11.1.1 使用形态矩阵

Gemini 提供了零门槛到深度集成的多种使用形态：

使用形态	定位与适用场景
Web / 移动端 App	零门槛日常创作、多模态实时交互 (Live API)。
Gemini CLI	核心推荐：终端里的 AI 助手，适合代码开发、自动化运维。
API / SDK / AI Studio	工程化集成，支持长上下文、工具调用与产品化。
Antigravity (IDE)	高级开发者 / Agent 玩家，让 AI 代理自动写代码、跑命令的 IDE。

11.2 环境准备与架构解密

11.2.1 极速安装与订阅

订阅准备：利用美区环境与学生身份（Gmail + 米国地址），可薅取 Gemini 3 Pro 免费一年订阅。
CLI 安装：依赖 Node.js (>= 18.x)，全局安装：npm install -g @google/gemini-cli。（Windows 强烈推荐使用 WSL 环境）。

11.2.2 CLI 架构（前后端分离）

Gemini CLI 采用模块化设计：

前端（packages/cli）：负责 UI 渲染（使用 React 终端 UI）、用户输入和主题。
后端（packages/core）：负责 Prompt 构建、与 Gemini API 通信以及工具（Tools）的执行。

11.2.3 配置体系（分层合并）

Gemini CLI 拥有一套严谨的配置优先级（从高到低）：
命令行参数 > 环境变量 > 系统设置(System) > 项目设置(Workspace) > 用户设置(User) > 默认值。

最佳实践： 敏感 API Key 用 环境变量；项目规范用 项目级 settings.json；临时改动用 命令行参数。

11.3 操控艺术：交互与自动化

Gemini CLI 提供了极其丰富的控制台交互能力：

11.3.1 三大核心命令符号

/ (斜杠 - 系统命令)：控制 CLI 元数据。如 /model (切换模型)、/memory (刷新上下文)、/restore (快照恢复)、/mcp (管理外部服务)。
@ (At - 上下文注入)：将文件或目录无缝注入 Prompt。支持 Git 过滤，如 @src/my_project/ 总结代码。
! (感叹号 - Shell透传)：直接在 AI 环境执行系统命令，如 !git status。

11.3.1.1 自定义命令与宏

你可以使用 .toml 文件将常用指令沉淀为快捷命令（如 /git:commit）。

{{args}}：动态注入用户输入。
!{...}：执行 Shell 命令并注入其标准输出（如 !{git diff}）。
@{...}：注入指定文件内容。

11.3.2 无头模式 (Headless Mode)

专为 CI/CD 和自动化脚本设计。

用法：gemini --prompt "..." --output-format json (或 stream-json)
价值：可以通过管道符（Pipe）与其他命令结合，例如：cat code.py | gemini -p "找 Bug" > report.txt。

11.4 Agent 核心扩展能力矩阵

这是 Gemini CLI 拉开生产力差距的关键，主要由 Tools、Skills、Hooks、Extensions 四大模块组成。

11.4.1 Tools（工具：AI 的手和眼）

赋予大模型操作物理世界的能力：

文件系统：list_directory, read_file, write_file, replace (智能正则修正)。
Shell 命令行：执行编译、Git 操作等，捕获 stdout/stderr。
网络与搜索：google_web_search (防幻觉)、web_fetch (实时抓取)。
Todos (规划)：write_todos 帮助 AI 将复杂任务拆解为多步列表。
MCP (外部集成)：通过标准协议对接 Jira、数据库等第三方系统。

11.4.2 Agent Skills（技能：按需加载的专家）

解决全局 GEMINI.md 过度消耗 Token 的痛点。

机制：打包成 SKILL.md 目录。平时只加载元数据，当用户提到“触发词”时，精准按需加载。
组成：Prompt + 脚本文件 (scripts) + 静态资源 (assets)。

11.4.3 Hooks（钩子：生命周期拦截器）

通过标准的 stdin/stdout 进行进程间通信（IPC），在 AI 的生命周期中进行拦截：

BeforeAgent：注入实时项目上下文。
BeforeTool：安全拦截，检测到 rm -rf 等危险命令时直接熔断。
AfterTool：对输出结果进行脱敏（如隐藏密码）。

11.4.4 Extensions（扩展：分发与共享）

将 Tools (MCP)、Skills、Commands、Hooks 打包成 gemini-extension.json。支持通过 Git 或 GitHub Releases 一键分发给团队或社区。

11.5 企业级安全与治理

在企业落地时，Gemini CLI 提供了严格的安全与可观测性保障：

11.5.1 Checkpoint (检查点与回滚)

原理：AI 每次修改文件前，自动在隐藏影子仓库（~/.gemini/history/）做 Git 快照。
价值：允许 AI 大胆重构，随时通过 /restore 命令回滚到工具执行前的状态，确保代码安全。

11.5.2 Sandbox (沙箱隔离)

AI 执行的所有 Shell 命令都可以被关进沙箱，避免误删系统文件。

支持方式：macOS Seatbelt、Docker、Podman。
开启方式：gemini -s 或配置 GEMINI_SANDBOX=docker。

11.5.3 权限治理与可观测性

禁用 YOLO 模式：通过配置 disableYoloMode: true 强制要求人工确认。
工具白名单：通过 tools.core 配置仅允许使用的安全工具（如只读工具）。
MCP 治理：使用 allowed 和 includeTools 控制第三方服务的数据访问。
OpenTelemetry：将 Token 消耗、延迟、工具调用日志导出到 GCP 或本地，实现成本追踪与审计。

11.6 小结

Google Gemini 3 的发布，标志着 AI 辅助开发范式的全面升级：

从“聊代码”到“改代码”：通过 File System Tools 和 Checkpoint 机制，AI 已经可以直接参与项目的读写与重构。
从“万能助手”到“模块化专家”：通过 Skills 机制和 Context 的分层加载，实现了低 Token 消耗下的高精度领域知识覆盖。
从“个人提效”到“工程化落地”：Headless 模式、Hooks 机制以及 OpenTelemetry 的支持，让 AI 可以作为标准组件嵌入到企业 CI/CD 流水线中。

一句话原则：善用 settings.json 定制基础体验，用环境变量管密钥，用上下文文件 (GEMINI.md) 让模型懂你，用 Tools 和 Hooks 拓展边界。

posted @ 2026-04-23 21:01 charyGao 阅读(90) 评论(0) 收藏举报

刷新页面返回顶部

硅基文明

代码改变不了世界，但是改变世界需要代码。 正在找工作，欢迎发 JD 到我邮箱，坐标上海浦东新区。

【万字长文】Gemini 3 Pro 全面指南：从免费订阅到 CLI / Agent 实战

4.16 telemetry

4.17 settings.json 示例

4.18 命令历史记录

4.19 环境变量

4.19.1 变量参数

4.19.2 环境变量脱敏

4.20 命令行参数

4.21 上下文文件（Context Files）

4.21.1 示例 context file 内容

4.22 沙箱

4.23 使用统计

4.24 小结

05 工程化与治理：Checkpoint、Sandbox、Telemetry 与企业最佳实践

5.1 Checkpointing（检查点）

5.1.1 工作原理

5.1.2 数据存放在哪？

5.1.3 启用 Checkpointing

5.1.4 使用 /restore 管理检查点

5.2 面向企业的 Gemini CLI（集中式配置 + 安全治理最佳实践）

5.2.1 系统设置文件

5.2.2 合并示例

5.2.3 系统配置文件的位置（不同系统）

5.2.4 企业常用技巧

5.2.5 工具访问控制（白名单优先 + 禁用 YOLO 模式）

5.2.5.1 coreTools（允许列表）

5.2.5.2 excludeTools（阻止列表）

5.2.5.3 禁用 YOLO 模式

5.2.6 MCP（自定义工具）治理

5.2.6.1 限制 MCP 服务器暴露的工具（includeTools / excludeTools）

5.2.6.2 更安全的企业模式（system 中同时定义 + 加 allowed 白名单）

5.2.6.3 不安全模式（只定义 server 但不加 allowed）

5.3 Sandbox（沙箱）

5.4 OpenTelemetry 可观测性

5.4.1 核心配置项（settings.json / 环境变量）

5.4.2 Google Cloud 遥测（推荐 Direct Export）

5.4.3 本地遥测

5.4.4 典型企业 system settings 汇总示例

5.5 小结

感谢阅读，希望能帮助到大家，本文完！

06 Skills：按需加载的专家技能体系（Agent Skills）

6.1 什么是 Agent Skills？

6.2 启用与管理技能

6.3 案例实战

6.4 技能编写建议

6.5 小结

07 Tools：内置工具与工具调用模型

7.1 核心工具深度解析

7.1.1 文件系统工具 (File System)

7.1.2 Shell 命令行工具 (Shell)

7.1.3 网络获取与搜索

7.1.4 记忆工具

7.1.5 Todos 任务清单

7.1.6 MCP 服务器集成

7.2 案例实践

7.3 小结

08 Hooks：生命周期拦截与安全加固

8.1 核心架构

8.1.1 Hook 的基础配置 (hook.json)

8.1.2 进程间通信法则 (IPC Rules)

8.2 生命周期事件 (Hook Events Reference)

8.3 案例实践

8.3.1 案例一：[Node.js] 缓存高耗时操作 (最佳实践)

8.3.2 案例二：[Python] 拦截危险的系统命令

8.4 数据结构参考 (Reference)

8.4.1 CLI 输入给 Hook 的数据 (stdin)

8.4.2 Hook 可以返回的控制字段 (stdout)

8.5 小结

09 Extensions：扩展打包、开发与发布

9.1 什么是 Extensions？

9.1.1 扩展的工作原理

9.2 快速入门

9.2.1 前置准备

9.2.2 初始化扩展

9.2.3 理解核心文件 gemini-extension.json

9.2.4 编写 MCP 工具代码 (example.ts)

9.2.5 构建与本地链接

9.3 丰富扩展功能

代码改变不了世界，但是改变世界需要代码。正在找工作，欢迎发 JD 到我邮箱，坐标上海浦东新区。