扩展发布

有两种主要方式将扩展程序发布给用户：

Git 仓库
GitHub 发布

Git 仓库发布通常是最简单和最灵活的方法，而 GitHub 发布在初次安装时可能更高效，因为它们作为单个存档传输，而不是需要通过 git clone 逐个下载文件。如果需要发布特定平台的二进制文件，GitHub 发布还可以包含特定平台的存档。

通过 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发布进行发布

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

每个发布至少包含一个归档文件，其中包含与链接标记相对应的仓库的完整内容。如果您的扩展需要某些构建步骤或附加了特定平台的二进制文件，发布还可能包括预构建的归档。

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

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

自定义预构建归档

自定义归档必须直接作为 github 发布的资产附件，并且必须是完全自包含的。这意味着它们应该包括整个扩展，请参阅归档结构。

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

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

平台特定归档

为确保 Gemini CLI 可以自动找到每个平台正确的发布资产，您必须遵循此命名约定。CLI 将按以下顺序搜索资产：

平台和架构特定： {platform}.{arch}.{name}.{extension}
平台特定： {platform}.{name}.{extension}
通用： 如果只提供了一个资产，它将被用作通用后备选项。

扩展名称：你的扩展的名称。
操作系统：支持的值包括：
- darwin（macOS）
- linux
- win32（Windows）
架构：支持的值包括：
- x64
- arm64
归档文件的扩展名（例如，.tar.gz 或 .zip）。

示例：

darwin.arm64.my-tool.tar.gz（特定于Apple Silicon Macs）
darwin.my-tool.tar.gz（适用于所有Macs）
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

归档结构

归档必须是完全包含的扩展，并拥有所有标准需求——特别是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