Gemini CLI 扩展入门

本指南将引导你创建第一个 Gemini CLI 扩展。你将学习如何设置新扩展、通过 MCP 服务器添加自定义工具、创建自定义命令，以及使用 GEMINI.md 文件为模型提供上下文。

前提条件

在开始之前，请确保你已安装 Gemini CLI 并对 Node.js 和 TypeScript 有基本了解。

步骤 1：创建新扩展

最简单的开始方式是使用内置模板之一。我们将使用 mcp-server 示例作为基础。

运行以下命令创建一个名为 my-first-extension 的新目录，其中包含模板文件：

bash

gemini extensions new my-first-extension mcp-server

这将创建一个具有以下结构的新目录：

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

步骤 2：了解扩展文件

让我们看看新扩展中的关键文件。

`gemini-extension.json`

这是扩展的清单文件。它告诉 Gemini CLI 如何加载和使用你的扩展。

json

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

name：扩展的唯一名称。
version：扩展的版本。
mcpServers：此部分定义一个或多个 Model Context Protocol (MCP) 服务器。MCP 服务器是你为模型添加新工具的方式。
- command、args、cwd：这些字段指定如何启动服务器。注意使用 ${extensionPath} 变量，Gemini CLI 会将其替换为扩展安装目录的绝对路径。这允许你的扩展无论安装在哪里都能工作。

`example.ts`

此文件包含 MCP 服务器的源代码。它是一个使用 @modelcontextprotocol/sdk 的简单 Node.js 服务器。

typescript

/**
 * @license
 * Copyright 2025 Google LLC
 * SPDX-License-Identifier: Apache-2.0
 */

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

// ...（为简洁起见省略提示注册）

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

此服务器定义了一个名为 fetch_posts 的工具，用于从公共 API 获取数据。

`package.json` 和 `tsconfig.json`

这些是 TypeScript 项目的标准配置文件。package.json 文件定义依赖项和 build 脚本，tsconfig.json 配置 TypeScript 编译器。

步骤 3：构建和链接扩展

在使用扩展之前，你需要编译 TypeScript 代码并将扩展链接到 Gemini CLI 安装以进行本地开发。

安装依赖：
bash
```
cd my-first-extension
npm install
```
构建服务器：
bash
```
npm run build
```
这将把 example.ts 编译为 dist/example.js，这是 gemini-extension.json 中引用的文件。
链接扩展：
link 命令从 Gemini CLI 扩展目录创建到开发目录的符号链接。这意味着你所做的任何更改都会立即反映，无需重新安装。
bash
```
gemini extensions link .
```

现在，重启 Gemini CLI 会话。新的 fetch_posts 工具将可用。你可以通过询问"获取帖子"来测试它。

步骤 4：添加自定义命令

自定义命令提供了一种为复杂提示创建快捷方式的方法。让我们添加一个在代码中搜索模式的命令。

创建 commands 目录和命令组的子目录：
bash
```
mkdir -p commands/fs
```
创建名为 commands/fs/grep-code.toml 的文件：
toml
```
prompt = """
请总结模式 `{{args}}` 的查找结果。

搜索结果：
!{grep -r {{args}} .}
"""
```
此命令 /fs:grep-code 将接受一个参数，使用它运行 grep shell 命令，并将结果传递到提示中进行总结。

保存文件后，重启 Gemini CLI。你现在可以运行 /fs:grep-code "some pattern" 来使用新命令。

步骤 5：添加自定义 `GEMINI.md`

你可以通过向扩展添加 GEMINI.md 文件来为模型提供持久上下文。这对于给模型关于如何行为的指令或关于扩展工具的信息很有用。请注意，对于构建用于公开命令和提示的扩展，你可能并不总是需要这个。

在扩展目录的根目录创建名为 GEMINI.md 的文件：

markdown

# 我的第一个扩展指令

你是一个专业的开发者助手。当用户要求你获取帖子时，使用 `fetch_posts` 工具。在回复中保持简洁。

更新 gemini-extension.json 以告诉 CLI 加载此文件：

json

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

再次重启 CLI。模型现在将在扩展活动的每个会话中拥有来自 GEMINI.md 文件的上下文。

步骤 6：发布扩展

一旦你对扩展满意，就可以与他人分享。发布扩展的两种主要方式是通过 Git 仓库或通过 GitHub Releases。使用公共 Git 仓库是最简单的方法。

有关两种方法的详细说明，请参阅扩展发布指南。

结论

你已成功创建了一个 Gemini CLI 扩展！你学会了如何：

从模板引导新扩展。
使用 MCP 服务器添加自定义工具。
创建便捷的自定义命令。
为模型提供持久上下文。
链接扩展以进行本地开发。

从这里，你可以探索更多高级功能，并为 Gemini CLI 构建强大的新功能。

Gemini CLI 扩展入门 ​

前提条件 ​

步骤 1：创建新扩展 ​

步骤 2：了解扩展文件 ​

gemini-extension.json ​

example.ts ​

package.json 和 tsconfig.json ​

步骤 3：构建和链接扩展 ​

步骤 4：添加自定义命令 ​

步骤 5：添加自定义 GEMINI.md ​

步骤 6：发布扩展 ​

结论 ​