青蛙小白
博客 / 2025/10

Gemini CLI 扩展系统升级：Gemini CLI v0.9.x

2025/10/15 · — 字 · 阅读约 — 分钟 ·
#gemini cli
目录

Gemini CLI发展到v0.9.x后，继续跟进一下其扩展系统的更新。

扩展系统概述

Gemini CLI 的扩展系统将提示（prompts）、MCP 服务器和自定义命令打包成熟悉且用户友好的格式。通过扩展，可以扩展 Gemini CLI 的能力，并与他人分享这些能力。扩展系统被设计为易于安装和分享。

想要浏览现有的扩展示例，可以访问 Gemini CLI extensions，那里汇集了各种实用的扩展。

扩展开发工具

Gemini CLI版本提供了一系列命令来简化扩展开发流程。

创建样板扩展

Gemini CLI 提供了几个示例扩展供开发者参考，包括：

  • context - 上下文管理扩展
  • custom-commands - 自定义命令扩展
  • exclude-tools - 工具排除扩展
  • mcp-server - MCP 服务器扩展

这些示例可以在 GitHub 仓库 中查看。

使用 gemini extensions new 命令可以快速将这些示例复制到你的开发目录中：

gemini extensions new path/to/directory custom-commands

这个命令会将指定类型的示例扩展复制到目标目录，提供一个开箱即用的起点。

链接本地扩展

开发扩展时，频繁运行 gemini extensions update 来测试修改会很繁琐。gemini extensions link 命令解决了这个问题。

该命令会在扩展安装目录和开发路径之间创建符号链接：

gemini extensions link path/to/directory

这样一来，对扩展代码的任何修改都会立即生效，无需每次都重新安装或更新扩展，大大提高了开发效率。

快速上手指南

下面通过一个完整的示例，演示如何创建第一个 Gemini CLI 扩展。

前置要求

开始之前，需要确保：

  • 已安装 Gemini CLI
  • 具备 Node.js 和 TypeScript 的基础知识

步骤 1：创建新扩展

使用模板命令快速创建扩展脚手架：

gemini extensions new my-first-extension mcp-server

这个命令会生成包含以下文件的目录结构：

  • example.ts - MCP 服务器源代码
  • gemini-extension.json - 扩展清单文件
  • package.json - 项目依赖配置
  • tsconfig.json - TypeScript 编译配置
my-first-extension
├── example.ts
├── gemini-extension.json
├── package.json
└── tsconfig.json

步骤 2：理解扩展文件

gemini-extension.json:

这是扩展的清单文件，告诉 Gemini CLI 如何加载扩展。关键字段包括：

  • name: 扩展的唯一标识符
  • version: 扩展版本号
  • mcpServers: 定义模型上下文协议（MCP）服务器，用于暴露工具
{
  "name": "mcp-server-example",
  "version": "1.0.0",
  "mcpServers": {
    "nodeServer": {
      "command": "node",
      "args": ["${extensionPath}${/}dist${/}example.js"],
      "cwd": "${extensionPath}"
    }
  }
}

配置文件使用 ${extensionPath} 等变量进行路径解析，确保扩展在不同环境下的可移植性。

example.ts:

包含使用 @modelcontextprotocol/sdk 实现的 MCP 服务器。模板中包含一个示例工具 fetch_posts，它从公共 API 获取数据并返回格式化的结果。

/**
 * @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',
});

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),
        },
      ],
    };
  },
);

server.registerPrompt(
  'poem-writer',
  {
    title: 'Poem Writer',
    description: 'Write a nice haiku',
    argsSchema: { title: z.string(), mood: z.string().optional() },
  },
  ({ title, mood }) => ({
    messages: [
      {
        role: 'user',
        content: {
          type: 'text',
          text: `Write a haiku${mood ? ` with the mood ${mood}` : ''} called ${title}. Note that a haiku is 5 syllables followed by 7 syllables followed by 5 syllables `,
        },
      },
    ],
  }),
);

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

步骤 3：构建和链接扩展

准备扩展需要三个步骤：

# 1. 安装依赖
npm install

# 2. 编译 TypeScript
npm run build  # 输出到 dist/example.js

# 3. 链接用于开发
gemini extensions link .

link 命令创建符号引用，使得代码修改能够立即生效，无需重新安装。

步骤 4：添加自定义命令

自定义命令可以为复杂的提示创建快捷方式。首先，建立命令目录结构：

mkdir -p commands/fs

然后创建 commands/fs/grep-code.toml 配置文件：

prompt = """
Please summarize the findings for the pattern `{{args}}`.

Search Results:
!{grep -r {{args}} .}
"""

这个命令的工作原理是：接受一个参数，使用它运行 grep shell 命令，然后将结果通过管道传递给提示进行总结。

重启 CLI 后，就可以通过 /fs:grep-code "some pattern" 调用这个命令。

步骤 5：添加持久化上下文

通过创建 GEMINI.md 文件，可以为模型提供持久化的指导信息。这个文件会在扩展激活的所有会话中持续提供上下文。

在 gemini-extension.json 清单文件中添加配置：

"contextFileName": "GEMINI.md"

然后在扩展根目录创建 GEMINI.md 文件，写入你希望模型始终了解的上下文信息。模型将在所有使用该扩展的会话中参考这些内容。

扩展发布指南

完成扩展开发后，需要选择合适的方式发布和分发扩展。Gemini CLI 提供了两种主要的发布方法。

方法 1：Git 仓库发布

这是更简单、更灵活的方式。用户可以通过以下命令安装扩展：

gemini extensions install <your-repo-uri>

用户还可以通过 --ref=<some-ref> 参数指定特定的版本或分支，默认使用仓库的默认分支。当依赖的 ref 有新的提交推送时，用户会收到更新提示。

Git 仓库最佳实践

建议将默认分支作为稳定发布渠道。推荐的工作流程包含三个分支：

  • dev - 活跃开发分支，用于日常开发
  • preview - 发布候选分支，用于预发布测试
  • stable（或默认分支）- 生产发布分支，用于稳定版本

这种结构允许用户默认安装稳定版本，同时也能让希望使用新功能的用户通过指定不同的 ref 来安装其他版本。

方法 2：GitHub Releases 发布

这种方法通过将扩展打包成单个归档文件进行分发，提供了更快的初始安装速度，避免了 git clone 的开销。

系统会自动检测最新的标记发布（marked release），用户也可以通过 --pre-release 标志选择安装预发布版本。

GitHub Releases 配置要求

归档文件必须遵循特定的命名约定以支持平台检测：

  • 平台和架构特定：{platform}.{arch}.{name}.{extension}
  • 平台特定：{platform}.{name}.{extension}
  • 通用回退：当只有一个资源文件时使用

支持的平台包括：

  • darwin - macOS
  • linux - Linux
  • win32 - Windows

支持的架构：

  • x64 - 64位 x86 架构
  • arm64 - 64位 ARM 架构

所有归档文件都必须在根目录包含 gemini-extension.json 文件，符合标准的扩展结构要求。

示例归档命名：

linux.x64.my-extension.tar.gz
darwin.arm64.my-extension.tar.gz
win32.x64.my-extension.zip

总结

通过以上内容，学习了创建 Gemini CLI 扩展的完整流程，包括：

  • 使用自定义工具（MCP 服务器）
  • 创建命令快捷方式
  • 提供上下文指导
  • 发布和分享扩展

这些能力让你可以扩展 Gemini CLI 的功能，并与社区分享你的创新。

参考

TAGS # gemini cli
评论