4.16 telemetry

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

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"]
  }
}

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 变量参数

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"]
  }
}

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.

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

---

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

1. 全局 context file：
   • 位置：~/.gemini/<configured-context-filename>（例如
     用户主目录中的 ~/.gemini/GEMINI.md）。
   • 作用域：为所有项目提供默认说明。
2. 项目根目录及祖先目录的 context files：
   • 位置：CLI 会在
     当前工作目录中搜索配置的 context file，然后在每个父目录中继续搜索，直到
     项目根目录（由 .git 文件夹标识）或用户主目录。
   • 作用域：为整个项目或其重要部分提供相关 context。
3. 子目录 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

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

BUILD_SANDBOX=1 gemini -s

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
  }
}

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 会自动创建一个“检查点”。检查点包含：

1. Git 快照（影子仓库提交）

   • CLI 会在一个特殊的影子 Git 仓库中创建一次提交
   • 影子仓库位置：~/.gemini/history/<project_hash>
   • 这不会干扰你自己项目的 Git 仓库（你的 .git 不会被动）

2. 对话历史 ：与 agent 的整个对话会被保存（方便恢复上下文）

3. 工具调用信息 ：即将执行的工具调用细节也会被记录（恢复后可重新执行/修改/忽略）

---

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
    }
  }
}

---

5.1.4 使用 /restore 管理检查点

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

---

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

/restore

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

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

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

---

2）恢复到某个检查点：

/restore <checkpoint_file>

例子：

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

恢复后会发生三件事：

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

---

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

企业里最常见的痛点是：

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

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

---

5.2.1 系统设置文件

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

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

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

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

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

---

5.2.2 合并示例

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

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

用户设置（~/.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"]
  }
}

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

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

系统覆盖项（/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"]
  }
}

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

{
  "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"
    ]
  }
}

结论：

• 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" "$@"

---

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

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

---

5.2.5.1 coreTools（允许列表）

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

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

---

5.2.5.2 excludeTools（阻止列表）

例如阻止删除命令：

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

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

---

5.2.5.3 禁用 YOLO 模式

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

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

---

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"]
    }
  }
}

---

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"
    }
  }
}

效果：

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

---

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

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

风险：用户可以在自己 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

---

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

方式 1：命令行 flag

gemini -s -p "analyze the code structure"

方式 2：环境变量

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

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

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

---

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

1. 命令行：-s/--sandbox
2. 环境变量：GEMINI_SANDBOX=true|docker|podman|sandbox-exec
3. 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"

多个参数：

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

---

调试沙箱（DEBUG）：

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

注意：项目 .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
  }
}

企业建议：

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

---

5.4.2 Google Cloud 遥测（推荐 Direct Export）

1）启用遥测：

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

2）运行 CLI 并产生数据：

正常使用 gemini 即可。

3）查看（Console）：

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

---

5.4.3 本地遥测

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

---

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
  }
}

---

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 会从三个主要位置自动发现技能（优先级依次降低）：

1. Workspace 技能 (.gemini/skills/)：特定于当前项目的技能，建议提交到 Git 仓库与团队共享。
2. User 技能 (~/.gemini/skills/)：你的个人专属技能，在所有项目中均可使用。
3. 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

如果正处于 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/         # (可选) 代码模板等二进制资源

当技能被激活时，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)”。

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

---

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

1. 激活拦截：当 AI 想要激活某个技能时，CLI 会弹出一个用户确认提示，告知你技能的名称和请求访问的目录。
2. 沙箱隔离：只有你批准后，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)"] 
    }
  }
}

---

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
}

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 的顺序：

---

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}`
    }
  }));
})();

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()

---

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 相关事件中存在
}

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

这会生成一个包含 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}"
    }
  }
}

小贴士：使用 ${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)) }] };
});

9.2.5 构建与本地链接

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

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

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

---

9.3 丰富扩展功能

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

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

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

重启后，可以运行 /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
  }
]

安装时，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

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

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

---

9.6 小结

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

---

参考文档：

• Gemini CLI Extensions 概述
• Gemini CLI Extensions 入门教程
• Gemini CLI Extensions 发布指南

码字不易，如果本文对您有帮助，欢迎点赞、收藏并在评论区分享你的 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

Step 2. 构建：

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

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

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

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

npm run preflight

这个命令会执行 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 官方文档整理，技术在不断迭代，建议以官方最新文档为准。参考：

• 官方文档首页：https://geminicli.com/docs
• GitHub 仓库：https://github.com/google-gemini/gemini-cli
• 架构概览：https://geminicli.com/docs/architecture
• 贡献指南：https://geminicli.com/docs/contributing

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

---

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

11.1 Gemini 3 为何物？

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

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

11.1.1 使用形态矩阵

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

---

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 辅助开发范式的全面升级：

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

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