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

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

【免费下载链接】gemini-cliAn open-source AI agent that brings the power of Gemini directly into your terminal.项目地址: https://gitcode.com/GitHub_Trending/gemi/gemini-cli

本文系统讲解 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]

关键行为说明（与 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 } ] }

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中支持变量替换：

从 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等模板。

【免费下载链接】gemini-cliAn open-source AI agent that brings the power of Gemini directly into your terminal.项目地址: https://gitcode.com/GitHub_Trending/gemi/gemini-cli