Gemini CLI 扩展

本文档与 v0.4.0 版本保持最新。

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

要查看扩展的示例，您可以浏览 Gemini CLI 扩展库。

有关创建您的第一个扩展的指南，请参阅入门文档。

有关设置 GitHub 发布的高级指南，请参阅发布文档。

扩展管理

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

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

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

安装扩展

您可以使用 gemini extensions install 安装扩展，可以是 GitHub URL 或本地路径。

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

注意：如果您要从 GitHub 安装扩展，您需要在计算机上安装 git。有关帮助，请参阅git 安装说明。

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

<source>: 要安装的扩展的 github URL 或本地路径。
--ref: 要从中安装的 git ref。
--auto-update: 为此扩展启用自动更新。
--pre-release: 为此扩展启用预发布版本。
--consent: 认识到安装扩展的安全风险并跳过确认提示。

卸载扩展

…（此处原文未给出，假设需要继续翻译）

要卸载一个或多个扩展，请运行以下命令：

`gemini extensions uninstall <name...>`

禁用扩展

默认情况下，扩展在所有工作空间中都是启用的。您可以选择完全禁用扩展或在特定工作空间中禁用。

gemini extensions disable [—scope ]

<name>：要禁用的扩展名称。
--scope：禁用扩展的范围（user 或 workspace）。

启用扩展

您可以使用 gemini extensions enable <name> 启用扩展。您还可以在特定工作空间内使用 gemini extensions enable <name> --scope=workspace 启用扩展。

gemini extensions enable [—scope ]

<name>：要启用的扩展名称。
--scope：启用扩展的范围（user 或 workspace）。

更新扩展

对于从本地路径或 git 仓库安装的扩展，您可以使用 gemini extensions update <name> 明确更新到最新版本（如 gemini-extension.json version 字段所示）。

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

gemini extensions update —all

创建一个样板扩展

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

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

gemini extensions new [template]

<path>：创建扩展的路径。
[template]：要使用的样板模板。

链接本地扩展

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

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

gemini extensions link

<path>：要链接的扩展路径。

工作原理

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

扩展作为一个包含有 package.json 文件的目录存在。例如：

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

`gemini-extension.json`

package.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` 文件](../get-started/configuration.md) 中的 MCP 服务器设置一样。如果扩展和 ``settings.json`` 文件都设置了同名的 MCP 服务器，则优先采用 ``settings.json`` 文件中定义的服务器。
  - 请注意，除 ``trust`` 外，所有 MCP 服务器配置选项都受支持。
- ``contextFileName``：包含扩展上下文的文件的名称。这将用于从扩展目录加载上下文。如果未使用此属性，但扩展目录中存在 ``GEMINI.md`` 文件，则将加载该文件。
- ``excludeTools``：要从模型中排除的工具名称数组。对于支持此功能的支持命令的工具，您还可以指定特定的命令限制，如 ``run_shell_command`` 工具。例如，``"excludeTools": ["run_shell_command(rm -rf)"]`` 将阻止 ``rm -rf`` 命令。请注意，这与可以在 MCP 服务器配置中列出的 MCP 服务器 ``excludeTools`` 功能不同。

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

### 设置

_注意：这是一个实验性功能。我们不推荐扩展作者将其作为核心流程的一部分引入设置._

扩展可以定义设置，用户在安装时会被提示提供这些设置。这对于扩展需要的功能性配置，如 API 密钥、URL 等非常有用。

要定义设置，请在您的 `gemini-extension.json` 文件中添加一个 `settings` 数组。数组中的每个对象应具有以下属性：

- `name`：设置的友好名称。
- `description`：设置描述及其用途。
- `envVar`：设置将存储为的环境变量名称。
- `sensitive`：可选布尔值。如果为真，则模糊用户提供的输入并将秘密存储在密钥链存储中。**示例**

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

当用户安装此扩展时，他们将被提示输入他们的 API 密钥。该值将被保存到扩展目录中的 .env 文件（例如，<home>/.gemini/extensions/my-api-extension/.env）。

您可以通过运行以下命令查看扩展设置的列表：

gemini extensions list

并且可以使用以下命令更新给定设置：

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

--scope：设置的范围（user 或 workspace）。这是可选的，默认为 user。

自定义命令

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

示例

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

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

将提供以下命令：

代码块显示为 /deploy 在帮助中
代码块显示为 /gcs:sync 在帮助中

钩子

扩展可以提供钩子，以在特定的生命周期事件上截取和自定义 Gemini CLI 的行为。扩展提供的钩子必须在扩展目录中的 hooks/hooks.json 文件中定义。

[!IMPORTANT] 钩子不是直接在 gemini-extension.json 中定义的。CLI 会特别查找 hooks/hooks.json 文件。

目录结构

.gemini/extensions/my-extension/
├── gemini-extension.json
└── hooks/
    └── hooks.json

`hooks/hooks.json` 格式

hooks.json 文件包含一个 hooks 对象，其中键是事件名称，值是钩子定义的数组。

{
  "hooks": {
    "before_agent": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node ${extensionPath}/scripts/setup.js",
            "name": "Extension Setup"
          }
        ]
      }
    ]
  }
}

支持的变量

就像 gemini-extension.json 一样，hooks/hooks.json 文件支持变量替换。这对于使用 ${extensionPath} 引用扩展目录中的脚本特别有用。

冲突解决

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

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

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

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

变量

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

支持的变量：

变量	描述
`${extensionPath}`	用户文件系统中插件的完全限定路径，例如，‘/Users/username/.gemini/extensions/example-extension’。这不会解析符号链接。
`${workspacePath}`	当前工作空间的完全限定路径。
`${/} or ${pathSeparator}`	路径分隔符（因操作系统而异）。
`${process.execPath}`	执行 CLI 的 Node.js 二进制文件的路径。

Gemini CLI 扩展

Gemini CLI 扩展

扩展管理

安装扩展

卸载扩展

禁用扩展

启用扩展

更新扩展

创建一个样板扩展

链接本地扩展

工作原理

gemini-extension.json

自定义命令

钩子

目录结构

hooks/hooks.json 格式

支持的变量

冲突解决

变量

`gemini-extension.json`

`hooks/hooks.json` 格式