Gemini CLI 扩展参考：`gemini extensions` 命令与 `gemini-extension.json` 清单全解析

本文系统讲解 Gemini CLI 扩展机制的两大核心：终端下的 gemini extensions 命令组（安装、卸载、启用/禁用、更新、模板创建、本地链接、配置）以及 gemini-extension.json 清单文件的完整字段语义，并结合仓库源码印证加载流程、设置存储（.env 与系统钥匙串）与变量替换的底层实现。读完后，你可以独立完成扩展的全生命周期管理，并能构建包含 MCP 服务器、自定义命令、Hooks、Skills、策略与主题的完整扩展包。

命令组总览与使用边界

gemini extensions 命令组是管理扩展的唯一终端入口，涵盖安装、卸载、禁用/启用、更新、配置、新建与本地链接等操作。在使用前需要明确两个使用边界（原文档明确说明）：

1. 交互式模式内不支持管理类命令：gemini extensions install 等管理命令只能在 CLI 外部执行；进入交互式会话后，只能通过 /extensions list 查看已安装的扩展。
2. 配置变更需重启会话生效：所有管理操作（包括对斜杠命令的更新）只有在重启 CLI 会话后才生效。

安装扩展：install

安装时提供 GitHub 仓库 URL 或本地文件路径：

gemini extensions install <source> [--ref <ref>] [--auto-update] [--pre-release] [--consent] [--skip-settings]

参数	说明
<source>	扩展的 GitHub URL 或本地路径。
--ref	要安装的 git 引用（分支、标签或提交）。
--auto-update	为该扩展启用自动更新。
--pre-release	允许安装预发布版本。
--consent	确认了解安全风险，跳过确认提示。
--skip-settings	跳过安装时的配置（settings 填写）流程。

关键行为说明（与 install.ts 的实现对应）：

• 安装的是副本，不是引用：Gemini CLI 在安装时会创建扩展的副本，后续要从源仓库拉取变更必须执行 gemini extensions update。
• 从 GitHub 安装要求本机装有 git。
• 本地安装会触发信任检查：从源码看，当源类型为 local 或 link 时，handleInstall 会调用 isWorkspaceTrusted 判断目录是否受信；未受信时执行 FolderTrustDiscoveryService.discover，向用户列出该目录包含的自定义命令、MCP 服务器、Hooks、Skills、Agents 与设置覆盖项，并展示发现错误与安全警告，用户确认后才会将该目录写入受信列表并继续安装。
• --consent 的行为：跳过交互式确认提示，但仍会把 INSTALL_WARNING_MESSAGE 记入调试日志；这是面向自动化脚本的选项，请自行确认安全影响。
• --skip-settings 的行为：源码中它把 requestSetting 回调置为 null，即安装过程中不再交互式询问 manifest 里声明的 settings（如 API key）。

卸载扩展：uninstall

gemini extensions uninstall <name...>

支持一次传入多个扩展名批量卸载。

禁用扩展：disable

扩展默认在全局范围内启用，可以整体禁用，也可以只针对特定工作区禁用：

gemini extensions disable <name> [--scope <scope>]

• <name>：要禁用的扩展名。
• --scope：禁用作用域，取值为 user 或 workspace。

启用扩展：enable

重新启用已禁用的扩展：

gemini extensions enable <name> [--scope <scope>]

参数与 disable 完全对称：<name> 为扩展名，--scope 取 user 或 workspace。

更新扩展：update

将扩展更新到其 gemini-extension.json 中指定的版本：

gemini extensions update <name>

一次性更新所有已安装扩展：

gemini extensions update --all

从模板创建扩展：new

gemini extensions new <path> [template]

• <path>：要创建的目录。
• [template]：使用的模板（文档示例给出 mcp-server、context、custom-commands）。

从源码（new.ts）可以看到两个实现细节：

• 模板取自内置的 examples 目录，当前仓库内置的模板包括 custom-commands、exclude-tools、hooks、mcp-server、policies、skills、themes-example（见 examples 目录），yargs 通过 choices 限定合法模板名。
• 如果不指定模板，命令会创建一个空目录并写入一份最小清单：{"name": <目录名>, "version": "1.0.0"}，随后提示用 gemini extensions link <path> 进行测试。

本地链接扩展：link

在开发目录与 Gemini CLI 扩展目录之间创建符号链接，让你无需重新安装即可立即测试改动：

gemini extensions link <path>

开发工作流推荐组合：gemini extensions new（或手写目录）→ 开发 → gemini extensions link 热测试。

配置扩展设置：config

更新扩展的用户设置（详见下文“扩展设置”一节）：

gemini extensions config <name> [setting] [--scope <scope>]

结合 configure.ts 的实现，可以补充三点：

• --scope 取值为 user 或 workspace，默认 user。
• [setting] 可传设置的显示名（name）或环境变量名（envVar），二者皆可匹配。
• 该功能受实验开关保护：settings.json 中 experimental.extensionConfig 置为 false 时命令会直接报错退出（默认开启）。
• 命令会拒绝包含路径分隔符或 .. 的扩展名，防止路径穿越。

扩展格式与加载机制

Gemini CLI 从 <home>/.gemini/extensions 目录加载扩展，每个扩展的根目录必须包含一个 gemini-extension.json 文件。

从源码看，该目录由 storage.ts 中的 ExtensionStorage.getUserExtensionsDir() 解析，而每个扩展目录内还会额外存放两类文件：

• .gemini-extension-install.json：安装元数据（记录来源类型、ref 等），供 update 与 migratedTo 迁移逻辑使用；
• .env：非敏感设置的值文件（见“扩展设置”一节）。

gemini-extension.json 完整示例

{
  "name": "my-extension",
  "version": "1.0.0",
  "description": "My awesome extension",
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["${extensionPath}/my-server.js"],
      "cwd": "${extensionPath}"
    }
  },
  "contextFileName": "GEMINI.md",
  "excludeTools": ["run_shell_command"],
  "migratedTo": "https://github.com/new-owner/new-extension-repo",
  "plan": {
    "directory": ".gemini/plans"
  }
}

字段说明：

• name：扩展名称，用于唯一标识扩展，并在扩展命令与用户/项目命令同名时参与冲突消解。命名要求为小写字母或数字，用连字符代替下划线或空格；该名称应扩展目录名保持一致，用户也将以此名称在 CLI 中引用你的扩展。
• version：扩展版本。
• description：扩展的简短描述（会展示在扩展画廊中）。
• migratedTo：扩展迁移后的新仓库源 URL。设置后，CLI 会自动检查新源的更新，并在发现更新时将扩展安装迁移到新源。
• mcpServers：MCP 服务器映射，键为服务器名，值为服务器配置。这些服务器在启动时加载，行为等同于 settings.json 中定义的 MCP 服务器。注意：
  • 若扩展与 settings.json 定义了同名的 MCP 服务器，settings.json 中的定义优先；
  • 除 trust 外，所有 MCP 服务器配置项均受支持；
  • 为可移植性，引用扩展目录内文件时应使用 ${extensionPath}；
  • 可执行文件与参数应分别放在 command 与 args 中，不要都塞进 command。
• contextFileName：包含扩展上下文的文件名，从扩展目录加载。若不声明该属性但扩展目录中存在 GEMINI.md，则该文件会被自动加载。
• excludeTools：要从模型中排除的工具名数组。支持对部分工具做命令级限制，例如 "excludeTools": ["run_shell_command(rm -rf)"] 会拦截 rm -rf 命令。注意这与 MCP 服务器配置中列出的 excludeTools 功能不同。
• plan：规划功能配置。
  • plan.directory：规划产物存储目录；用户未在工作区设置中指定时作为回退。若扩展与用户都未指定，默认为 ~/.gemini/tmp/<project>/<session-id>/plans/。

对应的磁盘结构类型定义见 extension.ts 中的 ExtensionConfig 接口（name、version、mcpServers、contextFileName、excludeTools、settings、themes、plan、migratedTo）。

启动时 Gemini CLI 会加载所有扩展并合并其配置；如有冲突，工作区配置优先。

扩展设置（Settings）

扩展可以在安装时要求用户提供设置（如 API key 或 URL）。这些值存储在扩展目录内的 .env 文件中。在清单中添加 settings 数组来声明：

{
  "name": "my-api-extension",
  "version": "1.0.0",
  "settings": [
    {
      "name": "API Key",
      "description": "Your API key for the service.",
      "envVar": "MY_API_KEY",
      "sensitive": true
    }
  ]
}

字段	说明
name	设置的显示名。
description	设置的清晰说明。
envVar	值所存储的环境变量名。
sensitive	为 true 时，值存入系统钥匙串，并在 UI 中做掩码处理。

extensionSettings.ts 的实现进一步揭示了存储细节：

• 敏感与非敏感分流存储：sensitive: true 的值经 KeychainTokenStorage 写入系统钥匙串（键名形如 Gemini CLI Extensions <扩展名> <extensionId>，workspace 作用域还会追加工作区目录）；非敏感值写入 .env 文件，且 .env 内容会经过校验——变量名必须匹配 ^[a-zA-Z_][a-zA-Z0-9_]*$，值不能包含换行。
• 作用域：user 作用域的 .env 位于扩展目录内（<home>/.gemini/extensions/<name>/.env）；workspace 作用域则写入 <workspaceDir>/.env。getEnvContents 合并两者时，workspace 值覆盖 user 值。
• 设置变更的增量同步：getSettingsChanges 会对比新旧 settings 清单，对新增项提问、对移除项从 .env/钥匙串中清理，升级扩展时不会留下过期密钥。

环境变量清洗（Security 机制）

出于安全考虑，敏感环境变量默认会被过滤，不会传递给扩展或 MCP 服务器。扩展不会继承用户完整的 shell 环境变量，它们只能访问：

1. 标准的安全变量（如 HOME、PATH、TMPDIR）；
2. 在 gemini-extension.json 的 settings 数组中通过 envVar 显式声明并请求的变量。

因此，如果扩展需要特定的环境变量（API key、自定义主机名、配置路径等），必须在 settings 数组中声明，CLI 才会将其加入白名单供扩展使用。这是编写扩展时最容易被忽略的一条硬性约束。

扩展可提供的能力清单

自定义命令

在扩展的 commands/ 子目录中放置 TOML 文件即可提供自定义命令，命令名由目录结构决定。以扩展 gcp 为例：

• commands/deploy.toml → /deploy
• commands/gcs/sync.toml → /gcs:sync（用冒号命名空间）

Hooks

通过 hooks 拦截并自定义 CLI 行为。注意 Hooks 不定义在 gemini-extension.json 中，而是放在扩展目录的 hooks/hooks.json 文件里。

Agent Skills

通过打包 agent skills 提供专门化工作流：将技能定义放入 skills/ 目录。例如 skills/security-audit/SKILL.md 会暴露一个 security-audit 技能。

子代理（预览功能）

子代理（Sub-agents）目前为预览功能，仍在积极开发中。

在扩展根目录添加 agents/ 目录，放入代理定义文件（.md），即可向用户暴露可委派任务的子代理。

策略引擎（Policy Engine）

扩展可以为 Gemini CLI 的 策略引擎 贡献策略规则与安全校验器，规则定义在 .toml 文件中，在扩展激活时生效。在扩展根目录创建 policies/ 目录并放入 .toml 策略文件即可，CLI 会自动加载其中所有 .toml。

扩展贡献的规则运行在独立的 tier 2 层级，与工作区策略同层：优先级高于默认规则，但低于用户或管理员策略。

安全警告：出于安全考虑，Gemini CLI 会忽略扩展策略中的任何 allow 决策与 yolo 模式配置，确保扩展无法在未经确认的情况下自动批准工具调用或绕过安全措施。

policies.toml 示例：

[[rule]]
mcpName = "my_server"
toolName = "dangerous_tool"
decision = "ask_user"
priority = 100

[[safety_checker]]
mcpName = "my_server"
toolName = "write_data"
priority = 200
[safety_checker.checker]
type = "in-process"
name = "allowed-path"
required_context = ["environment"]

主题

扩展可以在 gemini-extension.json 的 themes 数组中提供自定义主题：

{
  "name": "my-green-extension",
  "version": "1.0.0",
  "themes": [
    {
      "name": "shades-of-green",
      "type": "custom",
      "background": {
        "primary": "#1a362a"
      },
      "text": {
        "primary": "#a6e3a1",
        "secondary": "#6e8e7a",
        "link": "#89e689"
      },
      "status": {
        "success": "#76c076",
        "warning": "#d9e689",
        "error": "#b34e4e"
      },
      "border": {
        "default": "#4a6c5a"
      },
      "ui": {
        "comment": "#6e8e7a"
      }
    }
  ]
}

扩展主题可通过 /theme 命令或 settings.json 中的 ui.theme 属性选择。引用扩展主题时，主题名后以括号附带扩展名，例如 shades-of-green (my-green-extension)。

冲突消解

扩展命令的优先级最低。当扩展命令名与用户或项目命令冲突时，扩展命令会以扩展名前缀（点号分隔）呈现，例如 /gcp.deploy。

变量替换

Gemini CLI 在 gemini-extension.json 与 hooks/hooks.json 中支持变量替换：

变量	说明
${extensionPath}	扩展目录的绝对路径。
${workspacePath}	当前工作区的绝对路径。
${/}	平台相关的路径分隔符。

从 variables.ts 的实现可以看到其工作原理：hydrateString 用正则 /\${(.*?)}/g 扫描字符串并替换已定义的变量，recursivelyHydrateStrings 递归处理整个 JSON 对象（包括嵌套数组与对象），替换发生在扩展清单装载阶段。此外，递归水合时通过 UNMARSHALL_KEY_IGNORE_LIST 显式丢弃 __proto__、constructor、prototype 三个键，防御原型污染；validateVariables 则保证必填变量缺失时提前报错。${/} 的使用可以跨平台安全地拼接 command/args 中的本地脚本路径，例如 ${extensionPath}${/}bin${/}server.js。

延伸阅读

• 从零构建第一个扩展：构建扩展指南
• 安全与可靠性实践：扩展最佳实践
• 扩展概览与画廊入口：扩展总览
• 命令与设置定义示例参考 examples 目录 中的 mcp-server、hooks、policies 等模板。