Gemini CLI 发布指南

发布节奏与标签

我们尽可能遵循 https://semver.org/ 的语义化版本规范，如需偏离会提前说明。每周例行发布会提升 次版本号，其间若发布修复或热修复，会在最近一次发布的基础上递增 补丁版本号。

每周二约 20:00 UTC 会同时产出新的 Stable 与 Preview 版本，流程如下：

代码合并进 main，并在每晚推送到 nightly；
在 main 上停留不超过 1 周后，代码会提升到 preview 渠道；
再过 1 周，最新的 preview 会提升为 stable；
根据需要对 preview 与 stable 生成补丁，并逐次递增补丁版本号。

Preview

Preview 版本尚未完全验证，可能包含回归或其他问题，欢迎协助测试，通过 preview 标签安装：

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

Stable

Stable 为上一周 Preview 的正式提升版，附带必要修复与验证，使用 latest 标签安装：

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

Nightly

每天 UTC 00:00 发布 Nightly，内容为当时 main 上的全部变更，默认认为仍有待验证的问题，使用 nightly 标签安装：

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

每周发布提升流程

每周二值班工程师会触发 “Promote Release” 工作流，此动作会自动完成整套周发布：

预览转 Stable： 找到最新 preview 版本并提升为 stable，这会成为 npm 上新的 latest。
Nightly 转 Preview： 最新 nightly 提升为新的 preview。
准备下次 Nightly： 自动创建并合并 PR，更新 main 中的版本号，为下一次 Nightly 做准备。

这一流程最小化人工操作，确保发布节奏稳定可靠。

版本权威来源

为保证可靠性，发布流程以 NPM 注册表为唯一权威 来确认各发布渠道（stable、preview、nightly）的当前版本：

从 NPM 获取： 首先查询 NPM 的 dist-tags（latest、preview、nightly），获取用户可用的精确版本号。
完整性校验： 对每个版本执行关键检查：
- 仓库内必须存在对应的 git tag；
- 必须存在对应的 GitHub Release。
发现不一致则停止： 若缺少 git tag 或 GitHub Release，工作流会立即失败，提醒值班工程师手动处理。
计算下一版本： 仅在全部检查通过后，工作流才会依据可信版本号计算下一语义化版本。

这种以 NPM 为先的策略结合完整性校验，避免仅依赖 git 历史或 API 输出导致的版本偏差。

手动发布

若需在 Nightly/周发布之外手动发布（且不属于补丁流程），可使用 Release: Manual 工作流，它允许从任意分支、Tag 或提交 SHA 发布指定版本。

手动发布步骤

打开仓库的 Actions 标签页。
选择 Release: Manual 工作流。
点击 Run workflow 下拉。
填写参数：
- Version：要发布的精确版本（如 v0.6.1），必须带 v 前缀并符合语义化规则。
- Ref：发布来源的分支、Tag 或提交 SHA。
- NPM Channel：发布到的 npm 渠道，可选 preview、nightly、latest（Stable）、dev，默认 dev。
- Dry Run：保持 true 可执行全流程但不发布，设为 false 则真正发布。
- Force Skip Tests：设为 true 跳过测试，正式发布不建议使用。
- Skip GitHub Release：设为 true 时仅发布到 npm，不创建 GitHub Release。
点击 Run workflow。

随后工作流会执行测试（若未跳过）、构建并发布。若在非 Dry Run 时失败，会自动创建包含错误详情的 GitHub Issue。

回滚 / 前滚

若发布后出现严重回归，可通过修改 npm dist-tag 快速回滚到旧版本或前滚到新的补丁版本。Release: Change Tags 工作流提供安全可控的实现方式，是推荐的回滚/前滚手段，无需完整发布流程。

修改发布标签

打开 Actions 标签页。
选择 Release: Change Tags 工作流。
点击 Run workflow 下拉。
填写参数：
- Version：想让标签指向的已发布版本（如 0.5.0-preview-2）。
- Channel：要更新的 npm dist-tag（如 preview、stable）。
- Dry Run：设为 true 可仅记录操作，false 则实际修改。
点击 Run workflow。

工作流会对 @google/gemini-cli 与 @google/gemini-cli-core 执行 npm dist-tag add，将指定渠道指向对应版本。

补丁发布

若某个关键缺陷已在 main 修复，需要回补到 stable 或 preview，补丁流程高度自动化。

补丁步骤

1. 创建补丁 PR

共有两种方式：

方式 A：在 GitHub 评论中触发（推荐）

修复 PR 合并后，维护者可在同一 PR 评论：

/patch [channel]

channel（可选）：
- 省略参数 —— 同时补丁 stable 与 preview（默认，推荐）
- both —— 同上
- stable —— 仅补丁 stable
- preview —— 仅补丁 preview

示例：

/patch（默认：补丁 stable 与 preview）
/patch both（显式补丁两个渠道）
/patch stable
/patch preview

Release: Patch from Comment 工作流会自动找到合并提交 SHA 并触发 Release: Patch (1) Create PR。若 PR 尚未合并，会留言提示失败。

方式 B：手动触发工作流

在 Actions 中运行 Release: Patch (1) Create PR，填写：

Commit：希望 cherry-pick 的 main 上提交 SHA。
Channel：目标渠道（stable 或 preview）。

工作流会自动：

获取该渠道最新发布 Tag；
如不存在，基于该 Tag 创建 release 分支（例如 release/v0.5.1-pr-12345）；
基于 release 分支创建新的 hotfix 分支；
将指定提交 cherry-pick 进 hotfix；
从 hotfix 向 release 分支创建 PR。

2. 审核并合并

检查自动生成的 PR，确认 cherry-pick 成功且内容正确，通过后合并。

安全提示： release/* 分支受保护，需至少一名 code owner 审核后才能合并，避免未授权代码发布。

2.5. Hotfix 合并多个提交（高级用法）

如需在一次补丁发布中包含多项修复，可在初始补丁 PR 创建后向 hotfix 分支添加更多提交：

先处理核心修复： 对最重要的 PR 使用 /patch（或 /patch both）创建初始 hotfix 分支与 PR。

切换到 hotfix 分支：

git fetch origin
git checkout hotfix/v0.5.1/stable/cherry-pick-abc1234  # 使用 PR 中实际分支名

逐个 cherry-pick 额外提交：

git cherry-pick <commit-sha-1>
git cherry-pick <commit-sha-2>

推送更新：

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

测试与评审： 原补丁 PR 会自动更新。由于同时发布多个改动，请充分测试。
更新 PR 描述： 建议修改标题与描述，说明包含多项修复。

该方式允许在确保可控的前提下，将相关修复集中到单次补丁发布中。

3. 自动发布

补丁 PR 合并后会自动触发 Release: Patch (2) Trigger，进而启动 Release: Patch (3) Release，执行：

构建并测试补丁代码；
将新补丁版本发布到 npm；
创建带补丁说明的 GitHub Release。

整个流程自动化，确保补丁可靠一致。

故障排查：旧分支的工作流

问题：若补丁触发工作流失败，提示 “Resource not accessible by integration” 或引用不存在的工作流（如 patch-release.yml），多半是 hotfix 分支包含了旧版工作流文件。
原因：PR 合并时，GitHub Actions 执行的是 源分支（hotfix）的工作流定义；若该分支基于较早的 release 分支创建，就会使用旧逻辑。

解决方案：

方案 1：手动触发（快速解决）
使用包含最新工作流代码的分支手动触发：

# Preview 渠道且跳过测试
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

# Stable 渠道
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

# 常见情况：直接使用 main
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：更新 hotfix 分支
将最新的 main 合并进 hotfix：

git checkout hotfix/v0.6.0-preview.2/preview/cherry-pick-abc1234
git merge main
git push

然后关闭并重新打开 PR，触发新的工作流。

方案 3：直接触发发布
跳过触发工作流，直接运行发布工作流：

gh workflow run release-patch-3-release.yml --ref main \
  --field type="preview" \
  --field dry_run=false \
  --field force_skip_tests=true \
  --field release_ref="release/v0.6.0-preview.2"

Docker

我们还会运行 Google Cloud Build 配置 release-docker.yml，为发布匹配的 sandbox 镜像。待服务账号权限整理完成后，该流程也会迁移至 GitHub 并与主发布流程整合。

发布验证

新版本发布后，应进行冒烟测试，确认包能正常使用，可按以下步骤：

npx -y @google/gemini-cli@latest --version 验证推送是否成功（不适用于 rc/dev Tag）。
npx -y @google/gemini-cli@<release tag> --version 验证指定 Tag。

注意：以下操作会修改本地环境

npm uninstall @google/gemini-cli
npm uninstall -g @google/gemini-cli
npm cache clean --force
npm install @google/gemini-cli@<version>

建议进行基础的 LLM 命令与工具冒烟测试，后续会进一步规范。

本地测试与验证：包装与发布流程变更

若需测试发布流程而不真正发布到 NPM 或创建公开 GitHub Release，可在 GitHub UI 中手动触发工作流：

访问仓库的 Actions 页面。
点击 “Run workflow” 下拉。
保留 dry_run=true。
点击 “Run workflow”。

这样会运行完整发布流程，但跳过 npm publish 与 gh release create，可通过日志检查流程是否健康。

在提交前务必本地验证对打包与发布流程的修改，以确保最终发布的包可用。可执行一次 Dry Run 来模拟发布：

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

该命令会：

构建所有包；
执行 prepublish 脚本；
生成将要发布的 tarball；
输出即将发布的包摘要。

随后可检查生成的 tarball，确认文件内容与 package.json 更新正确。tarball 会生成在各包目录下（如 packages/cli/google-gemini-cli-0.1.6.tgz）。通过 Dry Run 可以确信包装流程正确。

发布流程深度解析

发布流程会产出两类工件：面向 NPM 的标准包，以及在 GitHub Release 提供的单文件可执行体。

关键阶段如下：

阶段 1：预检与版本号更新

内容： 在移动任何文件前，执行测试、Lint、类型检查（npm run preflight），并更新根目录与 packages/cli/package.json 的版本号。

阶段 2：构建 NPM 所需源码

内容： 将 packages/core/src 与 packages/cli/src 中的 TypeScript 编译为标准 JavaScript。
文件流向：
- packages/core/src/**/*.ts → packages/core/dist/
- packages/cli/src/**/*.ts → packages/cli/dist/
原因： 开发阶段的 TypeScript 需转成 Node.js 可执行的 JavaScript。因 cli 依赖 core，会先构建 core。

阶段 3：发布标准包到 NPM

内容： 对 @google/gemini-cli-core 与 @google/gemini-cli 执行 npm publish。
原因： 通过 npm install -g @google/gemini-cli 安装时，会自动拉取这些包并安装依赖。这些包不会被打包成单一文件。

阶段 4：组装 GitHub Release 工件

该阶段在 NPM 发布之后，用于生成可直接通过 GitHub 使用的单文件可执行体。

创建 JavaScript Bundle：
- 内容： 将 packages/core/dist、packages/cli/dist 以及第三方依赖通过 esbuild 打包为单一可执行文件（如 gemini.js），其中 node-pty 因包含原生二进制而被排除。
- 原因： 生成一个包含全部应用代码的优化单文件，方便用户无需完整 npm install 即可运行。
组装 bundle 目录：
- 内容： 在项目根目录创建临时 bundle 文件夹，将 gemini.js 与必要文件放入其中。
- 文件流向：
  - gemini.js → bundle/gemini.js
  - README.md → bundle/README.md
  - LICENSE → bundle/LICENSE
  - packages/cli/src/utils/*.sb → bundle/
- 原因： 提供一个整洁、可独立运行的目录，包含运行 CLI 所需文件及相关授权信息。
创建 GitHub Release：
- 内容： 将 bundle 目录中的文件（含 gemini.js）作为附件上传至新的 GitHub Release。
- 原因： 让单文件版 CLI 可供直接下载，并支持命令 npx https://github.com/google-gemini/gemini-cli。

工件摘要

NPM： 发布标准、未打包的 Node.js 包，核心工件是依赖 @google/gemini-cli-core 的 packages/cli/dist。
GitHub Release： 发布包含所有依赖的单文件 gemini.js，便于通过 npx 快速使用。

双重工件确保无论是传统 npm 安装还是偏好 npx 的用户，都能获得最佳体验。

通知

若发布工作流失败，会自动创建带 release-failure 标签的 Issue，并在维护者聊天频道中推送通知。

修改聊天通知

通知依赖 GitHub for Google Chat。如需调整，在聊天空间中使用 /github-settings。

[!WARNING] 以下是基于聊天应用 UI 内部结构的临时方案，未来更新可能失效。

当前标签列表未完整显示。如需添加未列在前 30 个中的标签，可借助浏览器开发者工具手动修改 UI：

打开浏览器开发者工具（如 Chrome DevTools）。
在 /github-settings 对话框中检查标签列表。
找到代表标签的 <li> 元素。
将该元素的 data-option-value 属性修改为目标标签名（如 release-failure）。
在 UI 中点击修改后的标签并保存设置。