Gemini CLI 发布说明

Gemini CLI 发布说明

dev 与 prod 环境

我们的发布流程支持 dev 和 prod 环境。

dev 环境会将包推送到私有的、由Github托管的NPM仓库，包名称以 @google-gemini/** 开头，而不是 @google/**。

prod 环境通过Wombat Dressing Room推送到公共的全球NPM注册表，这是Google用于管理 @google/** 命名空间中NPM包的系统。所有包的名称都是 @google/**。

关于这些系统的更多信息可以在maintainer repo guide中找到。

包作用域

包	prod (Wombat Dressing Room)	dev (Github Private NPM Repo)
CLI	@google/gemini-cli	@google-gemini/gemini-cli
Core	@google/gemini-cli-core	@google-gemini/gemini-cli-core A2A Server
A2A Server	@google/gemini-cli-a2a-server	@google-gemini/gemini-cli-a2a-server

发布节奏与标签

我们将尽可能遵循 https://semver.org/，但如果有必要偏离，我们会指出。我们每周的发布将是小版本递增，并且在发布之间的任何错误或热修复将以补丁版本的形式在最近的发布上推出。

每周二大约2000 UTC将推出新的稳定版和预览版。推广流程如下：

代码每晚提交至 main 分支并推送到 nightly 分支。

• 在 main 分支上不超过 1 周后，代码将升级到 preview 频道。
• 1 周后，最新的 preview 频道将升级到 stable 频道。
• 根据需要，将对 preview 和 stable 产生补丁修复，每次修复都会增加最终的 ‘patch’ 版本号。

预览

这些版本未经完全验证，可能包含回归或其他未解决的问题。请使用 preview 标签帮助我们测试和安装。

npm install -g @google/gemini-cli@preview

稳定

这将是上周发布的完全升级版，加上任何错误修复和验证。使用 latest 标签。

npm install -g @google/gemini-cli@latest

夜间

• 每天在 UTC 0000 发布新的版本。这将包括发布时 main 分支上的所有更改。应假定存在待定的验证和问题。使用 nightly 标签。

npm install -g @google/gemini-cli@nightly

每周版本升级

每周二，值班工程师将触发“升级版本”工作流程。这个单一操作自动化了整个每周发布流程：

1. 将预览升级到稳定版： 工作流程识别最新的 preview 发布并将其升级到 stable。这成为 npm 上的新 latest 版本。
2. 将夜间升级到预览版： 然后将最新的 nightly 发布升级为新的 preview 版本。
3. 为下一个夜间版本做准备： 自动创建并合并一个 pull 请求，以更新 main 中的版本，为下一个夜间发布做准备。

这个过程确保了持续一致且可靠的发布节奏，且人工干预最小。

版本控制的真相来源

为确保最高可靠性，发布升级流程使用NPM注册表作为确定每个发布渠道当前版本的唯一真实来源（stable，preview和nightly）。

1. 从NPM获取： 工作流程开始时，通过查询NPM的dist-tags（latest，preview，nightly）获取用户当前可用的软件包的确切版本字符串。
2. 交叉检查完整性： 对于从NPM检索的每个版本，工作流程执行一个关键的完整性检查：
   • 它验证仓库中是否存在相应的git标签。
   • 它验证是否已创建相应的GitHub发布。
3. 发现不一致时停止： 如果NPM上列出的某个版本缺少git标签或GitHub发布，工作流程将立即失败。这种严格的检查防止了从损坏或不完整的上一个版本进行升级，并提醒值班工程师必须手动解决的发布状态不一致问题。
4. 计算下一个版本： 只有在通过这些检查后，工作流程才会继续根据从NPM检索到的可信版本号计算下一个语义版本。

这种以NPM为先的方法，结合完整性检查，使得发布流程非常健壮，防止了仅依赖git历史或API输出可能出现的版本不一致问题。

手动发布

对于需要在常规夜间和每周升级计划之外进行发布的情况，且未被补丁过程覆盖，您可以使用Release: Manual工作流程。此工作流程提供了一种直接的方法，可以从任何分支、标签或提交SHA发布特定版本。

如何创建手动发布

1. 导航至仓库的 操作 选项卡。
2. 从列表中选择 发布：手动 工作流程。
3. 点击 运行工作流程 下拉按钮。
4. 填写所需的输入项：
   • 版本：要发布的确切版本（例如，v0.6.1）。这必须是一个带有 v 前缀的有效语义版本。
   • Ref：从哪个分支、标签或完整的提交 SHA 发布。
   • NPM 频道：要发布到的 npm 频道。选项有 preview、nightly、latest（用于稳定发布）和 dev。默认为 dev。
   • Dry Run：设置为 true 以运行所有步骤但不发布，或设置为 false 以执行实时发布。
   • 强制跳过测试：设置为 true 以跳过测试套件。这不推荐用于生产发布。
   • 跳过 GitHub 发布：设置为 true 以跳过创建 GitHub 发布，只创建 npm 发布。
   • 环境：选择适当的环境。dev 环境用于测试。prod 环境用于生产发布。prod 是默认选项，将需要发布管理员的授权。
5. 点击 运行工作流程。

工作流程将继续进行测试（如果没有跳过）、构建和发布。如果工作流程在非 Dry Run 模式下失败，它将自动创建一个 GitHub 问题，并包含失败详情。

回滚/前进

如果发布出现严重回归，您可以快速回滚到之前的稳定版本，或通过更改 npm 的 dist-tag 向前滚动到一个新的补丁。Release: Change Tags 工作流程提供了一种安全可控的方式来执行此操作。

这是回滚和前进的首选方法，因为它不需要完整的发布周期。

如何更改发布标签

1. 导航至仓库的 操作 选项卡。
2. 从列表中选择 Release: Change Tags 工作流。
3. 点击 运行工作流 下拉按钮。
4. 填写所需的输入项：
   • 版本：您希望将标签指向的现有软件包版本（例如，0.5.0-preview-2）。此版本必须已发布到 npm 注册表。
   • 通道：要应用的 npm dist-tag（例如，preview，stable）。
   • 干运行：设置为 true 以记录操作而不进行更改，或设置为 false 以执行实时标签更改。
   • 环境：选择适当的环境。dev 环境用于测试。prod 环境用于生产发布。prod 是默认选项，将需要发布管理员的授权。
5. 点击 运行工作流。

然后，工作流将针对适当的 gemini-cli、gemini-cli-core 和 gemini-cli-a2a-server 软件包运行 npm dist-tag add，将指定通道指向指定版本。

补丁

如果已在 main 上修复的关键错误需要在 stable 或 preview 发布上进行修补，现在这个过程已经高度自动化。

如何打补丁

1. 创建补丁拉取请求

有两种方法可以创建补丁拉取请求：

选项A：从 GitHub 评论（推荐）

在包含修复的拉取请求被合并后，维护者可以在同一 PR 上添加以下格式的评论：

/patch [channel]

• 通道（可选）：
  • 无通道 - 修补稳定和预览通道（默认，推荐用于大多数修复）
  • both - 修补稳定和预览通道（与默认相同）
  • stable - 仅修补稳定通道
  • preview - 仅修补预览通道

示例：

【翻译】

• /patch （默认情况下修补稳定版和预览版）
• /patch both （明确修补稳定版和预览版）
• /patch stable （仅修补稳定版）
• /patch preview （仅修补预览版）

Release: Patch from Comment 工作流将自动找到合并提交的 SHA 并触发 Release: Patch (1) Create PR 工作流。如果 PR 尚未合并，它将发表一条评论指明失败。

选项 B：手动触发工作流

导航到 Actions 选项卡，并运行 Release: Patch (1) Create PR 工作流。

• 提交：你希望在 main 上进行 cherry-pick 的完整 SHA 提交。
• 频道：你希望修补的频道（stable 或 preview）。

此工作流将自动执行以下操作：

1. 为频道找到最新的发布标签。
2. 如果不存在，则从该标签创建一个发布分支（例如，release/v0.5.1-pr-12345）。
3. 从发布分支创建一个新的热修复分支。
4. 将你指定的提交 cherry-pick 到热修复分支。
5. 从热修复分支向发布分支创建一个 pull 请求。

2. 审查和合并

审查自动创建的 pull 请求以确保 cherry-pick 成功且更改正确。一旦批准，合并 pull 请求。

安全提示：release/* 分支受到分支保护规则的保护。向这些分支之一提交 pull 请求需要至少一位代码所有者的审查才能合并。这确保不会有未授权的代码发布。

2.5. 向热修复中添加多个提交（高级）

如果你需要在单个补丁版本中包含多个修复，可以在初始补丁 PR 创建后向热修复分支添加额外的提交：

1. 从主要修复开始：使用 /patch （或 /patch both）在最重要的 PR 上创建初始热修复分支和 PR。

2. 在本地检出热修复分支：

   git fetch origin
   git checkout hotfix/v0.5.1/stable/cherry-pick-abc1234  # Use the actual branch name from the PR

3. 选择性拣选额外提交：

git cherry-pick <commit-sha-1>
git cherry-pick <commit-sha-2>
# Add as many commits as needed

4. 推送更新的分支：

git push origin hotfix/v0.5.1/stable/cherry-pick-abc1234

5. 测试和审查：现有的补丁PR将自动更新您额外的提交。由于您现在是一起发布多个更改，因此请彻底测试。

6. 更新PR描述：考虑更新PR标题和描述，以反映它包含多个修复。

这种方法允许您将相关的修复分组到单个补丁发布中，同时完全控制包含的内容以及如何解决冲突。

3. 自动发布

合并Pull请求后，将自动触发Release: Patch (2) Trigger工作流程。它将启动Release: Patch (3) Release工作流程，执行以下操作：

1. 构建并测试修补的代码。
2. 将新的补丁版本发布到npm。
3. 使用补丁说明创建新的GitHub发布。

这个完全自动化的流程确保了补丁的一致性和可靠性地创建和发布。

故障排除：较旧的分支工作流程

问题：如果补丁触发工作流程失败并出现错误，如“集成无法访问资源”或引用不存在的工作流程文件（例如patch-release.yml），这表明热修复分支包含过时的工作流程文件。

根本原因：当PR被合并时，GitHub Actions从源分支（热修复分支）运行工作流程定义，而不是从目标分支（发布分支）。如果热修复分支是从早于工作流程改进的旧发布分支创建的，它将使用旧的工作流程逻辑。

解决方案：

选项1：手动触发（快速修复） 从包含最新工作流程代码的分支手动触发更新的工作流程：

# For a preview channel patch with tests skipped
gh workflow run release-patch-2-trigger.yml --ref <branch-with-updated-workflow> \
  --field ref="hotfix/v0.6.0-preview.2/preview/cherry-pick-abc1234" \
  --field workflow_ref=<branch-with-updated-workflow> \
  --field dry_run=false \
  --field force_skip_tests=true

# For a stable channel patch
gh workflow run release-patch-2-trigger.yml --ref <branch-with-updated-workflow> \
  --field ref="hotfix/v0.5.1/stable/cherry-pick-abc1234" \
  --field workflow_ref=<branch-with-updated-workflow> \
  --field dry_run=false \
  --field force_skip_tests=false

# Example using main branch (most common case)
gh workflow run release-patch-2-trigger.yml --ref main \
  --field ref="hotfix/v0.6.0-preview.2/preview/cherry-pick-abc1234" \
  --field workflow_ref=main \
  --field dry_run=false \
  --field force_skip_tests=true

注意：将<branch-with-updated-workflow>替换为包含最新工作流程改进的分支（通常是main，但也可能是测试更新的功能分支）。

选项2：更新热修复分支 将最新的主分支合并到您的热修复分支中，以获取更新的工作流程：

然后关闭并重新打开 PR 以重新触发具有更新版本的工作流程。

选项3：直接触发发布 完全跳过触发工作流程，直接运行发布工作流程：

Docker

我们还运行一个名为 release-docker.yml 的 Google 云端构建。该构建会将沙箱 Docker 发布以匹配您的发布。一旦服务账户权限解决，这也将移至 GitHub 并与主发布文件合并。

发布验证

推送新版本后，应进行冒烟测试以确保软件包按预期工作。这可以通过在本地安装软件包并运行一系列测试来确保它们正常工作。

• 如果您没有进行 rc 或 dev 标签，使用 npx -y @google/gemini-cli@latest --version 验证推送是否按预期工作
• 使用 npx -y @google/gemini-cli@<release tag> --version 验证标签是否正确推送
• 这会在本地销毁 npm uninstall @google/gemini-cli && npm uninstall -g @google/gemini-cli && npm cache clean --force && npm install @google/gemini-cli@<version>
• 建议进行冒烟测试，执行一些简单的 llm 命令和工具操作，以确保软件包按预期工作。我们将在未来对此进行编码。

本地测试和验证：打包和发布流程的更改

如果您需要测试发布过程而不实际发布到 NPM 或创建公共 GitHub 发布，可以从 GitHub UI 手动触发工作流程。

1. 转到仓库的 操作标签。
2. 点击“运行工作流程”下拉菜单。
3. 保持 dry_run 选项选中（true）。
4. 点击“运行工作流程”按钮。

【翻译】 这将运行整个发布过程，但会跳过 npm publish 和 gh release create 步骤。您可以检查工作流日志以确保一切按预期工作。

在提交之前，在本地测试打包和发布过程中的任何更改至关重要。这确保了软件包将正确发布，并且当用户安装时它们将按预期工作。

为了验证您的更改，您可以执行发布过程的试运行。这将模拟发布过程，而实际上不会将软件包发布到 npm 注册表。

npm_package_version=9.9.9 SANDBOX_IMAGE_REGISTRY="registry" SANDBOX_IMAGE_NAME="thename" npm run publish:npm --dry-run

此命令将执行以下操作：

1. 构建所有软件包。
2. 运行所有预发布脚本。
3. 创建将发布到 npm 的软件包压缩包。
4. 打印将要发布的软件包的摘要。

然后，您可以检查生成的压缩包，确保它们包含正确的文件，并且 package.json 文件已正确更新。压缩包将在每个软件包目录的根目录中创建（例如，packages/cli/google-gemini-cli-0.1.6.tgz）。

通过执行试运行，您可以确信对打包过程的更改是正确的，并且软件包将成功发布。

发布深入探究

发布过程为不同的分发渠道创建了两种不同的工件：适用于 NPM 注册表的标准化软件包和 GitHub 发布的单个自包含可执行文件。

以下是关键阶段：

阶段 1：预发布健全性检查和版本控制

• 发生的事情： 在移动任何文件之前，过程会确保项目处于良好状态。这包括运行测试、代码风格检查和类型检查（npm run preflight）。根目录中的 package.json 和 packages/cli/package.json 的版本号更新到新的发布版本。

阶段 2：为 NPM 构建源代码

，以下代码块将不会执行。请确保在运行代码之前删除此行。

// 请在此处编写代码

• 如果您有任何问题或需要帮助，请随时提问。

祝您编程愉快！这段话的翻译：

请在此处编写代码，以下代码块将不会执行。请确保在运行代码之前删除此行。

// 在此编写代码

• 如果您遇到任何问题或需要帮助，请随时提出。

祝您编程愉快！简体中文翻译：

请在下面编写代码，当前的代码块不会执行。在运行代码之前，请确保删除这一行。

// 在这里编写代码

• 如果您遇到任何问题或需要帮助，请随时发问。

祝您编程愉快！

2. 组装 bundle 目录：

   • 发生的情况： 在项目根目录下创建了一个临时的 bundle 文件夹。单个 gemini.js 可执行文件以及其他必要文件都放置其中。
   • 文件移动：
     • gemini.js (来自 esbuild) -> bundle/gemini.js
     • README.md -> bundle/README.md
     • LICENSE -> bundle/LICENSE
     • packages/cli/src/utils/*.sb (沙盒配置文件) -> bundle/
   • 原因： 这样创建了一个干净、自包含的目录，其中包含了运行 CLI 以及了解其许可和用法所需的一切。

3. 创建 GitHub 发布版本：

   • 发生的情况： bundle 目录的内容，包括 gemini.js 可执行文件，作为资产附加到新的 GitHub 发布版本中。
   • 原因： 这样可以让 CLI 的单文件版本直接下载，并启用 npx https://github.com/google-gemini/gemini-cli 命令，该命令下载并运行这个特定的打包资产。

工件概要

• NPM: 发布标准的、未打包的 Node.js 包。主要工件是 packages/cli/dist 中的代码，它依赖于 @google/gemini-cli-core。
• GitHub 发布版本： 发布一个单一、打包的 gemini.js 文件，其中包含所有依赖项，便于通过 npx 执行。

这种双工件流程确保了既满足传统 npm 用户的需求，也让偏好 npx 便捷性的用户获得优化体验。

通知

失败的发布工作流将自动创建一个带有 release-failure 标签的问题。

当创建这类问题时，将在维护者的聊天频道中发布通知。

修改聊天通知

通知使用 适用于 Google Chat 的 GitHub。 若要修改通知，请在聊天空间内使用/github-settings。

[!警告] 以下说明描述了一个依赖于聊天应用程序 UI 内部结构的脆弱解决方案。 它可能会在未来更新时失效。

当前可用的标签列表并未正确填充。如果您想添加一个在仓库前30个按字母顺序排列的标签中未出现的标签，您必须使用浏览器的开发者工具手动修改 UI：

1. 打开您的浏览器开发者工具（例如，Chrome 开发者工具）。
2. 在/github-settings对话框中，检查标签列表。
3. 找到一个表示标签的<li>元素。
4. 在 HTML 中，修改该<li>元素的data-option-value属性，将其更改为所需的标签名称（例如，release-failure）。
5. 在 UI 中点击您修改的标签以选择它，然后保存您的设置。