Skip to content

Gemini CLI 扩展

¥Gemini CLI Extensions

Gemini CLI 支持可用于配置和扩展其功能的扩展。

¥Gemini CLI supports extensions that can be used to configure and extend its functionality.

工作原理

¥How it works

启动时，Gemini CLI 会在两个位置查找扩展：

¥On startup, Gemini CLI looks for extensions in two locations:

  1. <workspace>/.gemini/extensions

    ¥<workspace>/.gemini/extensions

  2. <home>/.gemini/extensions

    ¥<home>/.gemini/extensions

Gemini CLI 会从两个位置加载所有扩展。如果两个位置都存在同名的扩展，则工作区目录中的扩展优先。

¥Gemini CLI loads all extensions from both locations. If an extension with the same name exists in both locations, the extension in the workspace directory takes precedence.

在每个位置中，各个扩展都以包含以下内容的目录形式存在：gemini-extension.json文件。例如：

¥Within each location, individual extensions exist as a directory that contains a gemini-extension.json file. For example:

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

¥<workspace>/.gemini/extensions/my-extension/gemini-extension.json

gemini-extension.json

¥gemini-extension.json

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

¥The gemini-extension.json file contains the configuration for the extension. The file has the following structure:

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

  • name：扩展的名称。用于唯一标识扩展，并在扩展命令与用户或项目命令同名时用于解决冲突。

    ¥name: The name of the extension. This is used to uniquely identify the extension and for conflict resolution when extension commands have the same name as user or project commands.

  • version：扩展的版本。

    ¥version: The version of the extension.

  • mcpServers：要配置的 MCP 服务器映射。键是服务器名称，值是服务器配置。这些服务器将在启动时加载，就像在settings.json文件。如果扩展名和settings.json文件配置一个同名的 MCP 服务器，该服务器在settings.json文件优先。

    ¥mcpServers: A map of MCP servers to configure. The key is the name of the server, and the value is the server configuration. These servers will be loaded on startup just like MCP servers configured in a settings.json file. If both an extension and a settings.json file configure an MCP server with the same name, the server defined in the settings.json file takes precedence.

  • contextFileName：包含扩展上下文的文件的名称。这将用于从工作区加载上下文。如果未使用此属性，但GEMINI.md文件存在于您的扩展目录中，那么该文件将被加载。

    ¥contextFileName: The name of the file that contains the context for the extension. This will be used to load the context from the workspace. If this property is not used but a GEMINI.md file is present in your extension directory, then that file will be loaded.

  • excludeTools：要从模型中排除的工具名称数组。您还可以为支持该命令的工具指定特定于命令的限制，例如run_shell_command工具。例如，"excludeTools": ["run_shell_command(rm -rf)"]将阻止rm -rf命令。

    ¥excludeTools: An array of tool names to exclude from the model. You can also specify command-specific restrictions for tools that support it, like the run_shell_command tool. For example, "excludeTools": ["run_shell_command(rm -rf)"] will block the rm -rf command.

Gemini CLI 启动时会加载所有扩展并合并它们的配置。如果存在任何冲突，则以工作区配置为准。

¥When Gemini CLI starts, it loads all the extensions and merges their configurations. If there are any conflicts, the workspace configuration takes precedence.

扩展命令

¥Extension Commands

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

¥Extensions can provide custom commands by placing TOML files in a commands/ subdirectory within the extension directory. These commands follow the same format as user and project custom commands and use standard naming conventions.

例子

¥Example

名为gcp具有以下结构：

¥An extension named gcp with the following structure:

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

将提供以下命令：

¥Would provide these commands:

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

    ¥/deploy - Shows as [gcp] Custom command from deploy.toml in help

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

    ¥/gcs:sync - Shows as [gcp] Custom command from sync.toml in help

冲突解决

¥Conflict Resolution

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

¥Extension commands have the lowest precedence. When a conflict occurs with user or project commands:

  1. 无冲突：扩展命令使用其自然名称（例如，/deploy)

    ¥No conflict: Extension command uses its natural name (e.g., /deploy)

  2. 有冲突：扩展命令使用扩展​​前缀重命名（例如，/gcp.deploy)

    ¥With conflict: Extension command is renamed with the extension prefix (e.g., /gcp.deploy)

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

¥For example, if both a user and the gcp extension define a deploy command:

  • /deploy- 执行用户的部署命令

    ¥/deploy - Executes the user's deploy command

  • /gcp.deploy- 执行扩展的部署命令（标有[gcp]标签）

    ¥/gcp.deploy - Executes the extension's deploy command (marked with [gcp] tag)

安装扩展

¥Installing Extensions

您可以使用install命令。此命令允许您从 Git 存储库或本地路径安装扩展。

¥You can install extensions using the install command. This command allows you to install extensions from a Git repository or a local path.

用法

¥Usage

gemini extensions install <source> | [options]

¥gemini extensions install <source> | [options]

选项

¥Options

  • source <url> positional argument：用于安装扩展的 Git 仓库的 URL。该仓库必须包含gemini-extension.json文件位于其根目录中。

    ¥source <url> positional argument: The URL of a Git repository to install the extension from. The repository must contain a gemini-extension.json file in its root.

  • --path <path>：要作为扩展安装的本地目录的路径。该目录必须包含gemini-extension.json文件。

    ¥--path <path>: The path to a local directory to install as an extension. The directory must contain a gemini-extension.json file.

变量

¥Variables

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

¥Gemini CLI extensions allow variable substitution in gemini-extension.json. This can be useful if e.g., you need the current directory to run an MCP server using "cwd": "${extensionPath}${/}run.ts".

支持的变量：

¥Supported variables:

多变的

¥variable

描述

¥description

${extensionPath}

¥${extensionPath}

用户文件系统中扩展程序的完全限定路径，例如“/Users/username/.gemini/extensions/example-extension”。这不会解包符号链接。

¥The fully-qualified path of the extension in the user's filesystem e.g., '/Users/username/.gemini/extensions/example-extension'. This will not unwrap symlinks.

${/} or ${pathSeparator}

¥${/} or ${pathSeparator}

路径分隔符（因操作系统而异）。

¥The path separator (differs per OS).