Gemini CLI 扩展系统升级：Gemini CLI v0.4.x 核心变化

核心概念

Gemini CLI 0.4.x 中的扩展管理系统是一个重新设计的插件架构，它将提示(prompts)、MCP服务器和自定义命令打包在一起，使得扩展更容易安装、共享和管理。这个系统基于 MCP (Model Context Protocol) 协议构建。

主要更新

1. 扩展存储位置变更

在 v0.4.x 中，扩展存储位置进行了简化：

仅全局扩展: ~/.gemini/extensions/
不再支持工作区扩展，统一管理在用户主目录

2. 新增扩展管理命令

v0.4.x 引入了完整的扩展管理命令。

从github安装扩展：

# 安装扩展
gemini extensions install https://github.com/google-gemini/gemini-cli-security


# 安装扩展的目录结构
tree ~/.gemini/extensions/gemini-cli-security
~/.gemini/extensions/gemini-cli-security
├── commands
│   └── security
│       └── analyze.toml
├── CONTRIBUTING.md
├── gemini-extension.json
├── GEMINI.md
├── LICENSE
├── README.md
└── SECURITY.md

# 卸载扩展
gemini extensions uninstall gemini-cli-security

# 禁用/启用扩展

# 用户范围内禁用/启用扩展(scope的默认值是User)
gemini extensions disable gemini-cli-security --scope User
gemini extensions disable gemini-cli-security
gemini extensions enable gemini-cli-security  --scope User
gemini extensions enable gemini-cli-security
# 工作空间的范围内禁用/启用扩展
gemini extensions disable gemini-cli-security --scope Workspace
gemini extensions enable gemini-cli-security  --scope Workspace
# 注意: 扩展禁用和启用的配置存储在`.gemini/extensions/extension-enablement.json`配置文件中


# 更新扩展(更新时需要确保扩展时enable的) gemini extensions update [--all] [name]
gemini extensions update gemini-cli-security
gemini extensions update --all

从本地目录安装扩展:

gemini extensions install --path ~/my-gemini-extensions/xxx
Extension "xxx" installed successfully and enabled.

3. 配置文件结构

每个扩展目录包含 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 服务器实例
contextFileName: 包含扩展上下文的文件名
excludeTools: 要排除的特定工具或命令

4. 扩展命令系统

扩展可以通过在扩展目录下的 commands/ 子目录中放置 TOML 文件来提供自定义命令。

目录结构示例:

~/.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

5. 冲突解决机制

扩展命令优先级最低，冲突时自动重命名：

无冲突: 使用原始名称 (如: /deploy)
有冲突: 添加扩展前缀 (如: /gcp.deploy)

6. 变量替换系统

支持动态变量替换：

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["${extensionPath}${/}server.js"]
    }
  }
}

支持的变量:

变量	描述
`${extensionPath}`	扩展在文件系统中的完整路径
`${/}` 或 `${pathSeparator}`	操作系统特定的路径分隔符

v0.4.x 的主要优势

统一管理: 扩展管理命令让安装、更新、禁用更简单
集中存储: 统一在 ~/.gemini/extensions/ 管理，避免工作区冲突
打包概念: 将prompts、MCP服务器和命令打包为一个扩展
易于分享: 扩展更容易打包和分发
智能冲突处理: 自动处理命名冲突，确保所有命令可用

参考

Gemini CLI Extensions Documentation