扩展发布

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

• Git 仓库
• Github Releases

Git 仓库发布是最简单、最灵活的方法，而 GitHub Releases 在首次安装时可能更高效，因为它们以单个压缩包的形式分发，而不是需要 git clone 下载每个文件。如果需要分发特定平台的二进制文件，GitHub Releases 也可以包含特定平台的压缩包。

通过 Git 仓库发布

这是最灵活、最简单的选项。您只需要创建一个公开可访问的 Git 仓库（例如公开的 GitHub 仓库），然后用户就可以使用 gemini extensions install <your-repo-uri> 命令安装您的扩展，或者对于 GitHub 仓库，可以使用简化的 gemini extensions install <org>/<repo> 格式。用户还可以使用 --ref=<some-ref> 参数选择性地依赖特定的 ref（分支/标签/提交），该参数默认为默认分支。

当提交被推送到用户依赖的 ref 时，系统会提示用户更新扩展。请注意，这也允许轻松回滚，HEAD 提交始终被视为最新版本，而与 gemini-extension.json 文件中的实际版本无关。

使用 Git 仓库管理发布频道

用户可以依赖您的 Git 仓库中的任何 ref，例如分支或标签，这允许您管理多个发布频道。

例如，您可以维护一个 stable 分支，用户可以通过 gemini extensions install <your-repo-uri> --ref=stable 命令安装。或者，您可以将默认分支视为稳定发布分支，并在另一个分支（例如名为 dev）中进行开发，从而使其成为默认行为。您可以维护任意数量的分支或标签，为您和您的用户提供最大的灵活性。

请注意，这些 ref 参数可以是标签、分支，甚至是特定的提交，这允许用户依赖您的扩展的特定版本。如何管理标签和分支由您决定。

使用 Git 仓库发布的示例流程

虽然管理 Git Flow 发布有很多选项，但我们建议将默认分支视为“稳定”发布分支。这意味着 gemini extensions install <your-repo-uri> 的默认行为是使用稳定发布分支。

假设您想维护三个标准的发布频道：stable、preview 和 dev。您将在 dev 分支中进行所有标准开发。当您准备好进行预览发布时，将该分支合并到您的 preview 分支。当您准备好将预览分支提升为稳定版时，将 preview 合并到您的稳定分支（可能是您的默认分支或其他分支）。

您还可以使用 git cherry-pick 命令将更改从一个分支挑选到另一个分支，但请注意，这会导致您的分支具有略微不同的历史记录，除非您在每次发布时强制推送更改以恢复历史记录的干净状态（这可能取决于您的存储库设置，对于默认分支可能无法实现）。如果您计划进行 cherry pick，您可能希望避免将默认分支设为稳定分支，以避免对默认分支进行强制推送，这通常应该避免。

通过 GitHub Releases 发布

Gemini CLI 扩展可以通过 GitHub Releases 进行分发。这为主用户提供了更快、更可靠的首次安装体验，因为它避免了克隆仓库的需要。

每次发布至少包含一个压缩包文件，其中包含与该压缩包关联的标签处的仓库的全部内容。如果您的扩展需要构建步骤或附带特定平台的二进制文件，发布还可以包含 预构建的压缩包。

在检查更新时，gemini 将只查找 GitHub 上的“最新”发布（您在创建发布时必须将其标记为最新），除非用户通过传递 --ref=<some-release-tag> 安装了特定版本。

您还可以使用 --pre-release 标志安装扩展，以获取最新的发布版本，无论它是否被标记为“最新”。这允许您在实际将发布版推送给所有用户之前对其进行测试。

自定义预构建压缩包

自定义压缩包必须直接作为资产附加到 GitHub 发布，并且必须是完全独立的。这意味着它们应该包含整个扩展，请参阅 压缩包结构。

如果您的扩展与平台无关，您可以提供一个通用的压缩包。在这种情况下，发布中应该只有一个资产。

如果您想在更大的仓库中开发扩展，也可以使用自定义压缩包，它可以具有与仓库本身不同的布局（例如，它可能只是包含扩展的子目录的压缩包）。

特定平台的压缩包

为确保 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 Mac)
• darwin.my-tool.tar.gz (适用于所有 Mac)
• linux.x64.my-tool.tar.gz
• win32.my-tool.zip

压缩包结构

压缩包必须是完全包含的扩展，并具有所有标准要求 - 特别是 gemini-extension.json 文件必须位于压缩包的根目录。

其余的布局应与典型扩展完全相同，请参阅 extensions.md。

GitHub Actions 工作流示例

这是一个 GitHub Actions 工作流示例，用于为多个平台构建和发布 Gemini CLI 扩展：

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