扩展发布指南

向用户发布扩展主要有两种方式：

• 通过 Git 仓库发布
• 通过 GitHub Releases 发布

使用 Git 仓库发布通常最简单、最灵活；而 GitHub Releases 会打包为单个归档文件，相比直接 git clone（逐个下载所有文件）初次安装更高效。如果需要针对不同平台分发二进制文件，也可以在 Release 中附加对应平台的归档。

通过 Git 仓库发布

这是最灵活且简单的方案。只需创建一个公开可访问的 Git 仓库（例如 GitHub 公共仓库），用户即可通过 gemini extensions install <your-repo-uri> 安装。若是 GitHub 仓库，则可使用简写格式 gemini extensions install <org>/<repo>。用户还可以使用 --ref=<some-ref> 指定依赖的引用（分支/标签/提交），默认值为默认分支。

当依赖的引用有新的提交时，用户会收到更新提示。由于 HEAD 提交始终被视为最新版本，与 gemini-extension.json 中声明的版本无关，因此也便于回滚。

在 Git 仓库中管理发布通道

用户可以依赖仓库中的任意引用（分支或标签），从而实现多发布通道管理。

例如，你可以维护一个 stable 分支，并通过 gemini extensions install <your-repo-uri> --ref=stable 提供稳定版本。或者将默认分支视为稳定分支，把开发工作放在其他分支（例如 dev）。你可以根据需要维护任意数量的分支或标签，为用户提供最大灵活性。

需要注意，ref 参数既可以是标签、分支，也可以是具体提交，这意味着用户可以固定到扩展的任意版本。如何管理标签与分支取决于你。

Git 仓库发布流程示例

虽然存在多种 Git 流程管理方式，我们推荐将默认分支作为 “稳定” 分支。这样当用户执行 gemini extensions install <your-repo-uri> 时，默认就安装到了稳定版本。

假设你希望维护 stable、preview、dev 三个渠道：

1. 在 dev 分支进行日常开发；
2. 需要发布预览版时，将 dev 合并到 preview；
3. 准备提升为稳定版时，再将 preview 合并到 stable（该分支可与默认分支相同或不同）。

如果需要，也可以使用 git cherry-pick 在分支间挑选提交。但要注意，这会让分支之间的历史产生差异；除非每次发布后都强推以恢复整洁历史（默认分支可能有仓库策略限制，禁止强推）。若计划频繁 cherry-pick，建议将默认分支与稳定分支分离，以避免对默认分支进行强制推送。

通过 GitHub Releases 发布

Gemini CLI 扩展也可以通过 GitHub Releases 分发。这样用户首次安装时更快、更稳定，因为无需克隆整个仓库。

每个 Release 至少包含一个归档文件，内含对应标签下的全部内容。如需构建步骤或分发特定平台的二进制文件，也可以附加自定义预构建归档。

检查更新时，默认会获取最新（标记为 “latest”）的 Release；如果用户在安装时传入 --ref=<some-release-tag>，则会锁定到指定 Release。

通过 --pre-release 参数可以安装最新的预发布版本，即便它未被标记为 latest。这样你可以先行测试，再推送给所有用户。

自定义预构建归档

自定义归档需作为 Release 附件上传，并且必须自包含完整扩展（详见归档结构）。

若扩展与平台无关，只需提供一个通用资源（保证 Release 中仅存在这一项即可）。

若扩展位于更大的仓库内，也可以构建与仓库结构不同的归档（例如仅打包某个子目录）。

针对平台的归档

为确保 Gemini CLI 能自动识别正确的资源，需要遵循以下命名规则。CLI 会按顺序查找：

1. 特定平台与架构： {platform}.{arch}.{name}.{extension}
2. 仅指定平台： {platform}.{name}.{extension}
3. 通用归档： 若仅上传一个资源，则视为通用回退。

• {name}：扩展名称。
• {platform}：操作系统，支持 darwin（macOS）、linux、win32（Windows）。
• {arch}：处理器架构，支持 x64、arm64。
• {extension}：归档后缀，例如 .tar.gz、.zip。

示例：

• darwin.arm64.my-tool.tar.gz（Apple Silicon 专用）
• darwin.my-tool.tar.gz（全平台 macOS）
• linux.x64.my-tool.tar.gz
• win32.my-tool.zip

归档结构

归档必须包含完整扩展，且标准文件（尤其是 gemini-extension.json）需位于归档根目录。其余结构应与常规扩展一致，参见 extensions.md。

GitHub Actions 工作流示例

以下示例展示了一个针对多平台构建并发布 Gemini CLI 扩展的 GitHub Actions 工作流：

name: Release Extension

on:
  push:
    tags:
      - 'v*'

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Set up Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm ci

      - name: Build extension
        run: npm run build

      - 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

      - name: Create GitHub Release
        uses: softprops/action-gh-release@v1
        with:
          files: |
            release/darwin.arm64.my-tool.tar.gz
            release/linux.arm64.my-tool.tar.gz
            release/win32.arm64.my-tool.zip