Gemini CLI 扩展入门

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

先决条件

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

第一步：创建新扩展

最简单的入门方法是使用其中一个内置模板。我们将使用 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

第二步：理解扩展文件

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

`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: 此部分定义了一个或多个模型上下文协议 (MCP) 服务器。MCP 服务器是添加模型可使用的新工具的方式。
- command, args, cwd: 这些字段指定了如何启动服务器。请注意 ${extensionPath} 变量的使用，Gemini CLI 会将其替换为扩展安装目录的绝对路径。这使得您的扩展无论安装在哪里都能正常工作。

`example.ts`

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

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: '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();
    const response = { posts: posts.slice(0, 5) };
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(response),
        },
      ],
    };
  },
);

// ... (为简洁起见，省略了 prompt 注册)

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

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

`package.json` 和 `tsconfig.json`

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

第三步：构建和链接您的扩展

在使用扩展之前，您需要编译 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 工具将可用。您可以通过询问：“fetch posts” 来测试它。

第四步：添加自定义命令

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

创建一个 commands 目录和一个用于命令组的子目录：
bash
```
mkdir -p commands/fs
```
创建一个名为 commands/fs/grep-code.toml 的文件：
toml
```
prompt = """
Please summarize the findings for the pattern `{{args}}`.

Search Results:
!{grep -r {{args}} .}
"""
```
此命令 /fs:grep-code 将接受一个参数，使用该参数运行 grep shell 命令，并将结果通过管道传递给一个用于摘要的提示。

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

第五步：添加自定义 `GEMINI.md`

您可以通过在扩展的根目录中添加 GEMINI.md 文件来为模型提供持久的上下文。这对于向模型提供有关其行为方式或扩展工具信息的说明非常有用。请注意，对于旨在公开命令和提示的扩展，您可能并不总是需要此文件。

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

markdown

# 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.

更新您的 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 文件的上下文。

第六步：发布您的扩展

对扩展满意后，您可以与他人共享。发布扩展的两种主要方法是通过 Git 存储库或通过 GitHub Releases。使用公共 Git 存储库是最简单的方法。

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

结论

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

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

从这里开始，您可以探索更高级的功能，并在 Gemini CLI 中构建强大的新功能。

Gemini CLI 扩展入门 ​

先决条件 ​

第一步：创建新扩展 ​

第二步：理解扩展文件 ​

gemini-extension.json ​

example.ts ​

package.json 和 tsconfig.json ​

第三步：构建和链接您的扩展 ​

第四步：添加自定义命令 ​

第五步：添加自定义 GEMINI.md ​

第六步：发布您的扩展 ​

结论 ​