Gemini CLI的扩展管理系统

内容已过时： 请查看最新文章：Gemini CLI 扩展系统升级：Gemini CLI v0.4.x 核心变化

核心概念

Gemini CLI 的扩展管理系统是一个强大的插件架构，允许用户通过安装、配置和管理扩展来定制 CLI 的功能。这个系统基于 MCP (Model Context Protocol) 协议构建。

简单介绍

1. 扩展存储位置

在启动时, Gemini CLI从以下2个位置查找扩展:

工作区扩展: <workspace>/.gemini/extensions/
全局扩展: ~/.gemini/extensions/
如果同名扩展存在于两个位置，工作区扩展优先

在每个位置中，单个扩展作为一个目录存在，该目录包含一个gemini-extension.json文件。

例如:

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

2. 配置文件结构

每个扩展目录包含 gemini-extension.json 配置文件：

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

name：扩展的名称。用于唯一标识扩展，并在扩展命令与用户或项目命令同名时进行冲突解决。
version：扩展的版本。
mcpServers：要配置的 MCP 服务器。键是服务器的名称，值是该服务器的配置。这些服务器会在启动时加载，就像在 settings.json 文件中配置的 MCP 服务器一样。如果扩展和 settings.json 文件同时配置了同名的 MCP 服务器，则以 settings.json 文件中的配置为准。
contextFileName：包含扩展上下文的文件名。系统会用它从工作区加载上下文。如果未使用该属性，但扩展目录中存在 GEMINI.md 文件，则会加载该文件。
excludeTools：要从模型中排除的工具名称数组。也可以为支持的工具指定命令级的限制，例如 run_shell_command 工具。例如：
```
"excludeTools": ["run_shell_command(rm -rf)"]
```
将会阻止执行 rm -rf 命令。

示例

.gemini/extensions/maps/gemini-extension.json:

{
  "name": "amap-maps",
  "version": "1.0.0",
  "mcpServers": {
      "amap-maps": {
        "command": "npx",
        "args": [
          "-y",
          "@amap/amap-maps-mcp-server"
        ],
        "env": {
          "AMAP_MAPS_API_KEY": "<AMAP_MAPS_API_KEY>"
        }
      }
    },
  "contextFileName": "GEMINI.md",
  "excludeTools": []
}

~/tmp gemini
Loaded cached credentials.

╭─────────────────╮
│  > /extensions  │
╰─────────────────╯


ℹActive extensions:

    - amap-maps (v1.0.0)


╭───────────────╮
│  > /mcp list  │
╰───────────────╯


ℹConfigured MCP servers:

  🟢 amap-maps (from amap-maps) - Ready (12 tools)
    Tools:
    - maps_around_search
    - maps_bicycling
    - maps_direction_driving
    - maps_direction_transit_integrated
    - maps_direction_walking
    - maps_distance
    - maps_geo
    - maps_ip_location
    - maps_regeocode
    - maps_search_detail
    - maps_text_search
    - maps_weather


  💡 Tips:
    • Use /mcp desc to show server and tool descriptions
    • Use /mcp schema to show tool parameter schemas
    • Use /mcp nodesc to hide descriptions
    • Use /mcp auth <server-name> to authenticate with OAuth-enabled servers
    • Press Ctrl+T to toggle tool descriptions on/off

扩展命令(Extension Commands)

扩展可以通过在扩展目录下的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"

支持的变量:

variable	description
`${extensionPath}`	扩展在用户文件系统中的完整路径，例如：`/Users/username/.gemini/extensions/example-extension`。此路径不会解析符号链接（symlinks）。

`${/} or ${pathSeparator}`	路径分隔符（因操作系统而异）。

参考

Gemini CLI Extensions