扩展发布

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

• Git 仓库
• GitHub Releases

Git 仓库发布往往是最简单和最灵活的方法，而 GitHub releases 在初始安装时可能更高效，因为它们作为单个归档文件发布，而不需要 git clone 单独下载每个文件。如果你需要发布平台特定的二进制文件，GitHub releases 还可以包含平台特定的归档。

通过 Git 仓库发布

这是最灵活和简单的选项。你只需要创建一个可公开访问的 git 仓库（如公共 GitHub 仓库），然后用户可以使用 gemini extensions install <your-repo-uri> 安装你的扩展。他们可以选择使用 --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 流程管理发布有很多选项，但我们建议将默认分支视为"稳定"发布分支。这意味着 gemini extensions install <your-repo-uri> 的默认行为是在稳定发布分支上。

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

你也可以使用 git 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 工作流

这是一个为多个平台构建和发布 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