本文从零开始带你开发一个 Gemini CLI 扩展：用内置模板初始化项目，编写 MCP 服务器工具，添加自定义命令和 GEMINI.md 上下文，用 link 命令做本地调试，最后发布到扩展库。即使没有扩展开发经验，跟着 8 个步骤也能发布自己的第一个扩展。

创建 Gemini CLI 扩展

Gemini CLI 扩展将 MCP 服务器、自定义命令、GEMINI.md 上下文、Agent Skills 和 Hooks 打包成一个可安装分发的单元。本教程带你从模板到发布，完成第一个扩展。

---

准备工作

• 已安装 Gemini CLI（参见 安装指南）
• 基本了解 Node.js

---

功能选型

根据你的需求选择扩展提供哪些功能：

功能	说明	调用方	适用场景
MCP 服务器	暴露新工具和数据源给模型	模型自动调用	调 API、查数据库、控制本地应用
自定义命令	/my-cmd 快捷方式，执行预设 Prompt 或 Shell 命令	用户手动触发	重复性任务、复杂 Prompt 模板
GEMINI.md	每次会话自动加载的 Markdown 上下文	CLI 自动注入	设定扩展"个性"、定义规范、提供必要知识
Agent Skills	仅在需要时激活的专项能力包	模型按需激活	安全审计、PR 创建等偶发性复杂任务
Hooks	拦截 CLI 生命周期事件	CLI 自动触发	工具参数验证、行为日志、输入输出修改
自定义主题	定义 CLI UI 颜色方案	用户手动切换	品牌定制、高对比度主题

---

步骤 1：创建扩展模板

使用内置 mcp-server 模板初始化：

gemini extensions new my-first-extension mcp-server

生成的目录结构：

my-first-extension/
├── example.js
├── gemini-extension.json
└── package.json

---

步骤 2：理解核心文件

gemini-extension.json（manifest）

{
  "name": "mcp-server-example",
  "version": "1.0.0",
  "mcpServers": {
    "nodeServer": {
      "command": "node",
      "args": ["${extensionPath}${/}example.js"],
      "cwd": "${extensionPath}"
    }
  }
}

• name：扩展唯一标识，必须与目录名一致
• ${extensionPath} 变量：自动替换为扩展目录绝对路径，确保跨机器可移植
• ${/} 变量：平台专用路径分隔符

example.js（MCP 服务器）

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { z } from 'zod';

const server = new McpServer({
  name: 'prompt-server',
  version: '1.0.0',
});

// 注册一个名为 fetch_posts 的工具
server.registerTool(
  'fetch_posts',
  {
    description: 'Fetches a list of posts from a public 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: posts.slice(0, 5) }) }],
    };
  },
);

const transport = new StdioServerTransport();
await server.connect(transport);

---

步骤 3：添加 Extension Settings

如果扩展需要 API Key 等配置，在 manifest 中添加 settings：

{
  "name": "mcp-server-example",
  "version": "1.0.0",
  "settings": [
    {
      "name": "API Key",
      "description": "The API key for the service.",
      "envVar": "MY_SERVICE_API_KEY",
      "sensitive": true
    }
  ],
  "mcpServers": { ... }
}

用户安装时会收到输入提示。sensitive: true 将值存入系统 Keychain，MCP 服务器进程启动时自动以环境变量形式注入。

---

步骤 4：本地链接调试

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

link 命令创建符号链接，代码变更后重新构建+重启 CLI 会话即可立即测试，无需反复安装。

启动 Gemini CLI，测试：

fetch posts

---

步骤 5：添加自定义命令

1. 创建命令目录：

   mkdir -p commands/fs

2. 创建 commands/fs/grep-code.toml：

   prompt = """
   请总结以下代码搜索结果中的关键发现（搜索模式：`{{args}}`）。
   
   搜索结果：
   !{grep -r {{args}} .}
   """

   这个命令注册为 /fs:grep-code，接受参数后运行 grep，把结果送入 Prompt 请模型总结。

3. 重启 CLI 后运行：/fs:grep-code "TODO"

命令文件路径决定命令名：

• commands/deploy.toml → /deploy
• commands/gcs/sync.toml → /gcs:sync

---

步骤 6：添加 GEMINI.md 上下文

1. 在扩展根目录创建 GEMINI.md：

   # My First Extension Instructions
   
   You are an expert developer assistant. When the user asks you to fetch
   posts, use the `fetch_posts` tool. Be concise in your responses.

2. 更新 manifest 指定文件名：

   {
     "name": "my-first-extension",
     "contextFileName": "GEMINI.md",
     "mcpServers": { ... }
   }

重启后，每次会话 GEMINI.md 内容会自动注入模型上下文，无需用户重复说明。

---

步骤 7（可选）：添加 Agent Skill

Agent Skills 把专项能力打包，仅在需要时激活，避免常态占用上下文 Token。

1. 创建 Skill 目录：

   mkdir -p skills/security-audit

2. 创建 skills/security-audit/SKILL.md：

   ---
   name: security-audit
   description:
     Expertise in auditing code for security vulnerabilities. Use when the user
     asks to "check for security issues" or "audit" their changes.
   ---
   
   # Security Auditor
   
   You are an expert security researcher. When auditing code:
   
   1. Look for common vulnerabilities (OWASP Top 10).
   2. Check for hardcoded secrets or API keys.
   3. Suggest remediation steps for any findings.

Gemini CLI 自动发现扩展中的 Skills，当模型识别到相关任务时自动激活。

详见 Skills 工作流。

---

步骤 8：发布扩展

将扩展推到公开 Git 仓库，用户即可安装：

gemini extensions install https://github.com/your-org/my-first-extension

详细发布流程（Git 发布、GitHub Releases、扩展库收录）参见 发布扩展。

---

常见问题

Q: 必须用 JavaScript/TypeScript 写 MCP 服务器吗？

A: 不必须。MCP 是协议层，任何语言都可以实现，只要进程能通过 stdio 通信。但官方 SDK 主要支持 TypeScript/JavaScript，强烈推荐使用 TypeScript 以获得类型安全。

Q: 怎么知道扩展是否正确加载了？

A: 在交互模式中运行 /extensions list，或按 F12 打开调试控制台查看工具注册状态。

Q: 如何给扩展命令添加权限说明，让用户知道它做什么？

A: 在 gemini-extension.json 中填写 description 字段，这会显示在扩展库页面上。在 GEMINI.md 中提供工具使用说明给模型，在 TOML 命令文件中用注释说明命令用途。