1. 引言

在前面的博客中，博主已经对 Gemini 做了一些简单的总结，有兴趣的同学可以阅读：

• 《Gemini 3 完整指南（一）：免费订阅、CLI 安装到 Agent 开发一次搞懂》
• 《Gemini 3 完整指南（二）：CLI 官方文档导航与速查索引》
• 《Gemini 3 完整指南（三）：CLI 功能特性及架构解密》
• 《Gemini 3 完整指南（四）：彻底拆解CLI 配置》
• 《Gemini 3 完整指南（五）：CLI 命令、无头模式、主题与快捷键》
• 《Gemini 3 完整指南（六）：Checkpoint、Sandbox 与可观测性》
• 《Gemini 3 完整指南（七）：Agent Skills 深度解析与最佳实践》
• 《Gemini 3 完整指南（八）：Tools 深度解析》
• 《Gemini 3 完整指南（九）：Hooks 机制详解与 Agent 生命周期拦截》

通过 Gemini CLI 扩展，可以将提示词（Prompts）、MCP（模型上下文协议）服务器、Agent 技能（Agent Skills）和自定义命令打包成一个用户友好的格式。无论你是想为团队内部构建特定的工作流，还是想向开源社区分享你的 AI 工具，Gemini CLI 扩展都能轻松满足。

本文将基于官方文档，详细介绍 Gemini CLI 扩展的工作原理、开发流程、最佳实践以及如何发布你的扩展。

2. 什么是 Extensions？

简单来说，Gemini CLI 扩展（Extensions）是一个包含配置和代码的目录，用于扩展 CLI 的原生能力，它的核心功能包括：

• MCP 服务器集成：允许模型调用外部工具（如读取文件、调用 API、查询数据库）。
• 自定义命令 (Custom Commands)：为常用的复杂 Prompt 创建快捷指令（如 /fs:grep-code）。
• Agent 技能 (Agent Skills)：提供按需触发的专家能力和专门的工作流程。
• 生命周期钩子 (Hooks)：在 CLI 的特定生命周期事件中拦截和自定义行为。

2.1 扩展的工作原理

启动时，Gemini CLI 会在 ~/.gemini/extensions/ 目录下查找扩展，每个扩展的核心是 gemini-extension.json 配置文件。如果存在冲突（例如扩展命令与用户命令同名），扩展命令会自动添加扩展名前缀进行冲突解决（例如 /gcp.deploy）。

---

3. 快速入门

从零开始，创建一个包含 MCP 服务器和自定义命令的扩展。

3.1 前置准备

确保已经安装了 Gemini CLI 以及 Node.js / TypeScript 环境。

3.2 初始化扩展

Gemini CLI 提供了现成的模板，运行以下命令，使用 mcp-server 模板创建名为 my-first-extension 的扩展：

gemini extensions new my-first-extension mcp-server

这会生成一个包含 gemini-extension.json、package.json 和 TypeScript 源码的目录结构。

3.3 理解核心文件 gemini-extension.json

这是扩展的“身份证”，定义了扩展如何被加载：

{
  "name": "my-first-extension",
  "version": "1.0.0",
  "mcpServers": {
    "nodeServer": {
      "command": "node",
      "args": ["${extensionPath}${/}dist${/}example.js"],
      "cwd": "${extensionPath}"
    }
  }
}

小贴士：使用 ${extensionPath} 变量可以确保扩展无论安装在何处，路径都能正确解析。

3.4 编写 MCP 工具代码 (example.ts)

在 example.ts 中，可以注册自定义工具。例如，注册一个获取网络数据的工具 fetch_posts：

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
// ... 省略 imports
const server = new McpServer({ name: 'prompt-server', version: '1.0.0' });

server.registerTool('fetch_posts', {
  description: '从公共 API 获取帖子列表。',
  inputSchema: z.object({}).shape,
}, async () => {
  const apiResponse = await fetch('https://jsonplaceholder.typicode.com/posts');
  const posts = await apiResponse.json();
  return { content: [{ type: 'text', text: JSON.stringify(posts.slice(0, 5)) }] };
});

3.5 构建与本地链接

在开发阶段，我们使用 link 命令将开发目录链接到 CLI 扩展目录，这样改动可以实时生效：

cd my-first-extension
npm install
npm run build
gemini extensions link .

重启 Gemini CLI 后，你就可以对 AI 说：“Fetch posts” 来测试你的新工具了。

---

4. 丰富扩展功能

4.1 添加自定义命令 (Custom Commands)

在扩展目录下创建 commands/fs/grep-code.toml：

prompt = """
请总结以下模式的搜索结果 `{{args}}`。
搜索结果：
!{grep -r {{args}} .}
"""

重启后，可以运行 /fs:grep-code "console.log"，AI 会自动帮你搜索并分析代码。

4.2 提供持久上下文 (GEMINI.md)

在根目录创建 GEMINI.md，并在 gemini-extension.json 中配置 "contextFileName": "GEMINI.md"。这里的文本会作为系统提示词加载，指导 AI 如何使用你的扩展。

4.3. 添加 Agent 技能 (Agent Skills)

在 skills/security-audit/SKILL.md 中定义安全审计技能。当用户询问“检查安全漏洞”时，CLI 会自动激活这个技能，而不需要常驻内存。

---

5. 最佳实践与用法指南

5.1 用户环境配置 (Settings)

如果扩展需要 API Key，不要硬编码。使用 gemini-extension.json 中的 settings 字段：

"settings": [
  {
    "name": "API Key",
    "description": "Your API key for the service.",
    "envVar": "MY_API_KEY",
    "sensitive": true
  }
]

安装时，CLI 会安全地提示用户输入，并保存在扩展目录下的 .env 文件中。

5.2 巧用变量

在配置和 Hook 中，善用以下变量：

• ${extensionPath}: 扩展安装路径
• ${workspacePath}: 当前工作区路径
• ${/}: 跨平台的路径分隔符

5.3 扩展管理日常用法

作为用户或开发者，你常用以下命令来管理扩展：

• 安装：gemini extensions install <github-url-or-local-path>
• 更新：gemini extensions update <name> (更新所有扩展可加 --all)
• 启用/禁用：gemini extensions disable <name> --scope workspace (支持工作区级别隔离)
• 卸载：gemini extensions uninstall <name>

---

6. 如何发布?

开发完成后，如何分享给全世界？Gemini CLI 支持两种发布模式：

6.1 通过 Git 仓库发布（推荐日常迭代）

最简单的方法。只需将代码推送到公开的 GitHub 仓库，用户即可通过 URL 安装：

gemini extensions install https://github.com/your-name/your-extension

Release Channels 管理：用户可以通过 --ref=stable 安装特定分支。你可以用 dev 分支开发，稳定后 Merge 到 stable 或默认分支。

6.2 通过 GitHub Releases 发布（适合生产环境）

对于包含编译步骤（如 TypeScript 构建）或特定平台二进制文件的扩展，GitHub Releases 是最佳选择。用户下载的是打包好的压缩文件，速度更快。

自动化发布最佳实践 (GitHub Actions)：
利用 GitHub Actions 自动构建多平台包。包的命名规范必须遵循：{平台}.{架构}.{扩展名}.{压缩格式}，例如 darwin.arm64.my-tool.tar.gz。

# 示例 GitHub Action 步骤片段
- name: Create release assets
  run: |
    npm run package -- --platform=darwin --arch=arm64
    npm run package -- --platform=linux --arch=x64
    npm run package -- --platform=win32 --arch=x64

当配置正确时，Gemini CLI 会自动检测用户的操作系统（macOS/Linux/Windows）并下载匹配的架构包。

---

7. 文末

Gemini CLI 的扩展机制极其灵活且对开发者友好。从简单的 Prompt 集合到包含复杂 MCP 逻辑的本地工具库，它都能轻松胜任，赶紧动手开发你的第一个扩展，打造属于你自己的超级 AI 命令行吧！

---

参考文档：

• Gemini CLI Extensions 概述
• Gemini CLI Extensions 入门教程
• Gemini CLI Extensions 发布指南

码字不易，如果本文对您有帮助，欢迎点赞、收藏并在评论区分享你的 Gemini CLI 扩展想法！