Gemini CLI 扩展

本文档与 v0.4.0 版本同步更新。

Gemini CLI 扩展将提示、MCP 服务器和自定义命令打包成一种熟悉且用户友好的格式。通过扩展，您可以扩展 Gemini CLI 的功能并与他人共享这些功能。它们被设计成易于安装和共享。

请参阅入门文档以获取创建第一个扩展的指南。

请参阅发布文档以获取设置 GitHub 发行的进阶指南。

扩展管理

我们提供一套使用 gemini extensions 命令的扩展管理工具。

请注意，这些命令不支持在 CLI 内部使用，尽管您可以使用 /extensions list 子命令列出已安装的扩展。

请注意，所有这些命令将在重启后反映在活动的 CLI 会话中。

安装扩展

您可以使用 gemini extensions install 命令，通过 GitHub URL 或本地路径来安装扩展。

请注意，我们会创建已安装扩展的副本，因此您需要运行 gemini extensions update 来拉取本地定义的扩展和 GitHub 上的扩展的更改。

注意：如果您要从 GitHub 安装扩展，则需要在您的机器上安装 git。请参阅 git 安装说明获取帮助。

gemini extensions install https://github.com/gemini-cli-extensions/security

这将安装 Gemini CLI 安全扩展，该扩展提供了对 /security:analyze 命令的支持。

卸载扩展

要卸载，请运行 gemini extensions uninstall extension-name，例如，在安装示例的情况下：

gemini extensions uninstall gemini-cli-security

禁用扩展

默认情况下，扩展在所有工作区中都处于启用状态。您可以完全禁用扩展，或为其特定工作区禁用。

例如，gemini extensions disable extension-name 将在用户级别禁用该扩展，因此它将在任何地方都被禁用。gemini extensions disable extension-name --scope=workspace 将仅在当前工作区禁用该扩展。

启用扩展

您可以使用 gemini extensions enable extension-name 来启用扩展。您也可以在当前工作区内，使用 gemini extensions enable extension-name --scope=workspace 来为特定工作区启用扩展。

如果您在顶层禁用了某个扩展，并且只在特定位置启用它，这将非常有用。

更新扩展

对于从本地路径或 Git 存储库安装的扩展，您可以使用 gemini extensions update extension-name 显式更新到最新版本（如 gemini-extension.json 的 version 字段所示）。

您可以使用以下命令更新所有扩展：

gemini extensions update --all

扩展创建

我们提供命令来简化扩展开发。

创建样板扩展

我们提供了一些示例扩展：context、custom-commands、exclude-tools 和 mcp-server。您可以在此处查看这些示例。

要使用您选择的类型将其中一个示例复制到开发目录中，请运行：

gemini extensions new path/to/directory custom-commands

链接本地扩展

gemini extensions link 命令将在扩展安装目录和开发路径之间创建一个符号链接。

这很有用，因为这样您就不必在每次进行想要测试的更改时都运行 gemini extensions update。

gemini extensions link path/to/directory

工作原理

启动时，Gemini CLI 会在 <home>/.gemini/extensions 中查找扩展。

扩展存在于一个包含 gemini-extension.json 文件的目录中。例如：

<home>/.gemini/extensions/my-extension/gemini-extension.json

`gemini-extension.json`

gemini-extension.json 文件包含扩展的配置。该文件具有以下结构：

json

{
  "name": "my-extension",
  "version": "1.0.0",
  "mcpServers": {
    "my-server": {
      "command": "node my-server.js"
    }
  },
  "contextFileName": "GEMINI.md",
  "excludeTools": ["run_shell_command"]
}

name: 扩展的名称。它用于唯一标识扩展，并在扩展命令与用户或项目命令同名时进行冲突解决。名称应为小写字母或数字，并使用连字符代替下划线或空格。这是用户在 CLI 中引用您的扩展的方式。请注意，我们期望此名称与扩展目录名称匹配。
version: 扩展的版本。
mcpServers: 要配置的 MCP 服务器的映射。键是服务器的名称，值是服务器配置。这些服务器将在启动时加载，就像在 settings.json 文件中配置的 MCP 服务器一样。如果扩展和 settings.json 文件都配置了同名的 MCP 服务器，则 settings.json 文件中定义的服务器具有优先权。
- 请注意，除了 trust 之外，所有 MCP 服务器配置选项都受支持。
contextFileName: 包含扩展上下文的文件的名称。它将用于从扩展目录加载上下文。如果未使用此属性但您的扩展目录中存在 GEMINI.md 文件，则将加载该文件。
excludeTools: 要从模型中排除的工具名称数组。您还可以为支持的工具指定特定于命令的限制，例如 run_shell_command 工具。例如，"excludeTools": ["run_shell_command(rm -rf)"] 将阻止 rm -rf 命令。请注意，这与 MCP 服务器的 excludeTools 功能不同，后者可以在 MCP 服务器配置中列出。

当 Gemini CLI 启动时，它会加载所有扩展并合并它们的配置。如果存在任何冲突，工作区配置将具有优先权。

自定义命令

扩展可以通过在扩展目录内的 commands/ 子目录中放置 TOML 文件来提供自定义命令。这些命令遵循与用户和项目自定义命令相同的格式，并使用标准的命名约定。

示例

一个名为 gcp 的扩展，具有以下结构：

.gemini/extensions/gcp/
├── gemini-extension.json
└── commands/
    ├── deploy.toml
    └── gcs/
        └── sync.toml

这将提供以下命令：

/deploy - 在帮助中显示为 [gcp] Custom command from deploy.toml
/gcs:sync - 在帮助中显示为 [gcp] Custom command from sync.toml

冲突解决

扩展命令的优先级最低。当与用户或项目命令发生冲突时：

无冲突: 扩展命令使用其自然名称（例如 /deploy）
有冲突: 扩展命令将被重命名，并带有扩展前缀（例如 /gcp.deploy）

例如，如果用户和 gcp 扩展都定义了一个 deploy 命令：

/deploy - 执行用户的 deploy 命令
/gcp.deploy - 执行扩展的 deploy 命令（标记为 [gcp] 标签）

变量

Gemini CLI 扩展允许在 gemini-extension.json 中进行变量替换。这可能很有用，例如，如果您需要当前目录来运行 MCP 服务器，可以使用 "cwd": "${extensionPath}${/}run.ts"。

支持的变量：

变量	描述
`${extensionPath}`	扩展在用户文件系统中的完整路径，例如 `/Users/username/.gemini/extensions/example-extension`。此路径不会解开符号链接。
`${workspacePath}`	当前工作区的完整路径。
`${/} 或 ${pathSeparator}`	路径分隔符（因操作系统而异）。

Gemini CLI 扩展 ​

扩展管理 ​

安装扩展 ​

卸载扩展 ​

禁用扩展 ​

启用扩展 ​

更新扩展 ​

扩展创建 ​

创建样板扩展 ​

链接本地扩展 ​

工作原理 ​

gemini-extension.json ​

自定义命令 ​

冲突解决 ​

变量 ​