Gemini CLI 发布置信度策略：三层质量门禁与 go/no-go 决策机制

Gemini CLI 团队将“这个版本是否真的可以交付给用户”拆解为一套可执行的发布置信度策略（Release Confidence Strategy）：Level 1 自动化门禁（CI/CD、E2E、冒烟测试）、Level 2 人工验证与 dogfooding（preview 通道试用、关键用户旅程检查清单、重大发布 bug bash）、Level 3 遥测与数据复盘（监控面板与离线模型评测），最终以一份 go/no-go 清单触发 Release: Promote 工作流完成 preview 到 stable 的晋升。本文以 docs/release-confidence.md 为主体，结合仓库中真实的 workflow 定义、发布脚本与集成测试配置，逐层还原这套策略的落地细节，帮助读者掌握一个 AI CLI 产品从“代码合并”到“面向全量用户发布”的完整质量门禁体系。

一、策略目标：用三层信号回答“是否可以发布”

发布置信度策略的定位是发布管理者的检查清单和质量门（checklist and quality gate）。其核心目标是基于三类证据的综合评估——自动化信号、人工验证、线上数据——以高置信度回答：Is this release truly ready for our users?

三个层级的分工如下：

层级	名称	性质	未通过的后果
Level 1	自动化门禁	必须通过（must pass）	直接 no-go
Level 2	人工验证与 dogfooding	发布管理者手动执行	阻塞晋升 stable
Level 3	遥测与数据复盘	数据回归检查	阻塞晋升 stable

只有三层全部通过，才允许触发 Release: Promote 工作流把 preview 版本提升为 stable。下文按原文档的脉络逐层展开，并给出仓库中对应的实现证据。

二、Level 1：自动化门禁（必须通过）

原文档明确：Level 1 是基线要求，任何一项失败，发布即告吹（"If any of these fail, the release is a no-go"）。它由三道关卡组成：CI/CD 健康、端到端（E2E）测试、发布后冒烟测试。

2.1 CI/CD 健康检查：.github/workflows/ci.yml

文档要求 .github/workflows/ci.yml 中的工作流在 main 分支（针对 nightly）或 release 分支（针对 preview/stable）上全部通过，且测试必须在 Linux 和 macOS 上通过。当前仓库中的 ci.yml 定义名为 Testing: CI，触发条件覆盖 main、release/** 的 push、pull_request、merge_group 以及手动 dispatch——与文档描述一致，并且从实际作业定义看，测试矩阵还覆盖了 Windows。

检查项与实现细节（对照文档要求的 Linting / Typechecking / Unit Tests / Build 四类检查）：

• Lint 作业（ci.yml#L49-L125）：依次执行 ESLint、actionlint、shellcheck、yamllint、Prettier（均通过 scripts/lint.js 统一调度），并额外校验 NOTICES.txt 许可声明一致性、lockfile 完整性（npm run check:lockfile）、设置文档与源码同步（npm run docs:settings -- --check）、敏感关键字与 GitHub Actions 动作 pinning。
• 类型检查：npm run build 之后执行 npm run typecheck，确保无 TypeScript 错误。
• 单元测试：test_linux 作业（ci.yml#L141-L235）采用 node-version × shard 二维矩阵——Node.js 20.x / 22.x / 24.x 三个版本 × cli 与 others 两个分片。cli 分片运行 npm run test:ci --workspace "@google/gemini-cli"；others 分片显式列出 @google/gemini-cli-core、@google/gemini-cli-a2a-server、gemini-cli-vscode-ide-companion、@google/gemini-cli-test-utils 等包并追加 npm run test:scripts。test_mac（macos-latest-large）与 test_windows（Slow Test - Win）使用同样的分片策略，保证文档要求的"Linux 与 macOS 双平台通过"，并额外提供 Windows 覆盖。
• 构建与打包验证：每个测试分片在跑完单测后都会执行 npm run bundle，然后进行两级冒烟——先运行 node ./bundle/gemini.js --version 验证单文件 bundle 可执行，再把项目 npm pack 成 tarball 移入隔离目录执行 npx "./$TARBALL" --version，验证 npx 安装路径可用（ci.yml#L197-L214）。
• 安全与体积：codeql 作业对 JavaScript 做静态安全分析；bundle_size 作业用 compressed-size-action 监控 ./bundle/**/*.{js,sb} 体积变化，超过 1000 字节阈值即提示，防止 bundle 无节制膨胀。
• 聚合判定：最终的 ci 作业汇总 lint、link_checker、test_linux、test_mac、test_windows、codeql、bundle_size 七个作业的结果，任一非 success（且非 skipped）即整体失败（ci.yml#L485-L518）。

此外，仓库还有 merge_queue_skipper 机制：无实质变更的合并队列事件可跳过 CI/E2E 重跑，降低门禁噪音。

2.2 端到端（E2E）测试：.github/workflows/chained_e2e.yml

文档要求 chained_e2e.yml 工作流全部通过，平台覆盖 Linux、macOS、Windows，并且 Linux 上必须在 sandbox:none 与 sandbox:docker 两种沙箱模式下都通过。当前仓库的 Testing: E2E (Chained) 工作流与之一一对应：

• 触发方式：push 到 main、merge_group、由 Trigger E2E 工作流完成后级联触发（workflow_run），以及手动 dispatch（需传入 head_sha 与 repo_name）。这种"chained"设计让 PR 侧的触发工作流先跑快速检查，再级联拉起重量级 E2E，并把状态回写到对应 commit 的 E2E (Chained) 上下文上。
• Linux 双沙箱矩阵：e2e_linux 作业以 sandbox: [sandbox:none, sandbox:docker] × node-version: [20.x] 为矩阵（chained_e2e.yml#L128-L181）。sandbox:docker 分支会先 docker/setup-buildx-action 搭建 Docker 构建环境，再执行 npm run test:integration:sandbox:docker；sandbox:none 分支执行 npm run test:integration:sandbox:none。
• npm 脚本映射：根 package.json 中可以看到这两个命令的实质——test:integration:sandbox:none 即 cross-env GEMINI_SANDBOX=false vitest run --root ./integration-tests，test:integration:sandbox:docker 即 cross-env GEMINI_SANDBOX=docker npm run build:sandbox && ... vitest run --root ./integration-tests，测试根目录正是仓库的 integration-tests/（包含 hooks、browser-agent、policy、shell-background、checkpointing 等数十组集成场景）。也就是说，E2E 门禁直接验证了 CLI 在"裸跑"与"Docker 沙箱"两种执行模式下的行为，这正是一个会执行 shell 命令的 AI agent 所必需的双模验证。
• macOS / Windows：e2e_mac 与 e2e_windows 分别以 GEMINI_SANDBOX=false（环境变量写作 SANDBOX: 'sandbox:none'）运行同一集成套件；Windows 侧还额外确保 Chrome 可用（浏览器 agent 场景需要），并配置 Windows Defender 排除与 Node 内存上限以稳定长跑。
• 聚合判定：最终 e2e 作业要求 e2e_linux、e2e_mac、e2e_windows 与 evals 四个作业全部 success（chained_e2e.yml#L361-L387）。

值得一提的是，chained E2E 中还内置了一个 Evals 作业（chained_e2e.yml#L306-L351）：先用 scripts/changed_prompt.js 判断本次改动是否影响提示词，若相关则以 EVAL_SUITE_TYPE=behavioral 运行 npm run test:always_passing_evals。这为 Level 3 的"模型评测"提供了仓库内落点，详见第四节。

2.3 发布后冒烟测试：smoke-test.yml

文档要求：版本发布到 npm 之后，smoke-test.yml 必须通过，以确认包可安装、二进制可执行；验证命令是 npx -y @google/gemini-cli@<tag> --version 能无错返回正确版本号，当前运行在 ubuntu-latest 上。

从当前仓库的 workflow 定义看，smoke-test.yml（名为 On Merge Smoke Test）在推送至 main 或 release/** 分支时触发，流程为：npm ci → npm run bundle → node ./bundle/gemini.js --version（smoke-test.yml#L29-L41），与 CI 中的 bundle 冒烟同源；若在非 dry-run 下失败，会自动创建带 priority/p0 标签的 issue 并附上运行链接（smoke-test.yml#L42-L52）。而文档中面向发布管理者的 npx -y @google/gemini-cli@<tag> --version，则是发布到 npm 后对线上产物做同样验证的手动命令——两者共同构成"发布的包真的能用"这道底线关卡。

三、Level 2：人工验证与 dogfooding

自动化测试无法覆盖一切，尤其是体验类问题（UX issues）。Level 2 要求维护者亲自使用待发布的版本，由三部分组成。

3.1 通过 preview 通道 dogfooding 至少一周

原文档描述了每周发布节奏：代码从 main -> nightly -> preview -> stable 逐级晋升，且 preview 版本必须由维护者至少使用一周 才能晋升 stable。安装命令：

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

目标是在回归和体验问题触达更广泛用户之前，在日常使用中把它们暴露出来。

这套节奏在 docs/releases.md 中有完整定义：每周二约 20:00 UTC 切出新的 Stable 与 Preview 发布；代码每晚推送到 nightly；代码在 main 上不超过一周后晋升 preview；preview 满一周后晋升 stable；补丁按需同时打到 preview 与 stable。与 release-confidence.md 构成互补：前者定义"如何发布"，本文档定义"凭什么判定可以发布"。

从源码看，晋升动作由 release-promote.yml（Release: Promote 工作流）自动化，其关键设计值得发布管理者借鉴：

• NPM 注册表是版本的单一事实来源。calculate-versions 作业（release-promote.yml#L39-L131）调用 scripts/get-release-version.js，该脚本通过 npm view @google/gemini-cli version --tag=latest|preview|nightly 从 npm dist-tags 读取当前各渠道版本（get-release-version.js#L87-L97），并结合 git tag -l 与 semver 排序解析上一个发布 tag（get-release-version.js#L59-L85）。docs/releases.md 强调，对每个从 NPM 取回的版本，工作流都会交叉校验对应的 git tag 与 GitHub Release 是否存在，任一缺失立即失败——防止从一个损坏或不完整的先前发布继续晋升。
• 发布前再跑一次测试：test 作业按 stable / preview / nightly 三个渠道的 SHA 分别检出代码到 release/ 目录并执行共享的 run-tests action（除非显式 force_skip_tests），即"晋升什么，就实测什么"。
• 顺序发布与失败告警：先 publish-preview（npm-tag preview）再 publish-stable（npm-tag latest）；任何一步在非 dry-run 下失败都会自动创建 release-failure,priority/p0 的 issue。
• 为下一个 nightly 铺路：nightly-pr 作业自动创建并合并一个版本号 bump 的 PR（chore/nightly-version-bump-<version> 分支），保证下一轮 nightly 有干净基线。

因此 Level 1 的"CI 绿色"与 Level 2 的"晋升"之间，实际上还有一层工作流内建的重验证；而 go/no-go 清单正是人工侧对这些自动关卡的确认。

3.2 关键用户旅程（CUJ）检查清单

在把 preview 晋升为 stable 之前，发布管理者必须手动完成以下检查清单（完整继承自原文档）：

Setup（环境准备）：

• [ ] 卸载已有的全局版本：npm uninstall -g @google/gemini-cli
• [ ] 清空 npx 缓存（可选但推荐）：npm cache clean --force
• [ ] 安装 preview 版本：npm install -g @google/gemini-cli@preview
• [ ] 校验版本：gemini --version

Authentication（认证）：

• [ ] 交互模式下运行 /auth，验证所有登录流程可用：
  • [ ] Sign in with Google
  • [ ] API Key
  • [ ] Vertex AI

Basic prompting（基础提示）：

• [ ] 运行 gemini "Tell me a joke"，验证得到合理回复
• [ ] 运行交互模式 gemini，追问一个后续问题以测试上下文保持

Piped input（管道输入）：

• [ ] 运行 echo "Summarize this" | gemini，验证其处理 stdin

Context management（上下文管理）：

• [ ] 交互模式下用 @file 将本地文件加入上下文，并针对它提问

Settings（设置）：

• [ ] 交互模式下运行 /settings 并做修改
• [ ] 验证设置确实生效

Function calling（工具调用）：

• [ ] 交互模式下要求 Gemini "create a file named hello.md with the content 'hello world'"，验证文件被正确创建

原文档的结论很硬性：任何一项 CUJ 失败，发布即为 no-go，直到 preview 通道打上补丁。这条清单的价值在于它恰好覆盖了 agent 型 CLI 的核心能力面——认证多路径（Google 账号 / API Key / Vertex AI）、非交互与交互两种入口、stdin 管道、@file 上下文引用、设置持久化、以及真实落盘的工具调用——每一项都是自动化 E2E 难以穷举、却直接决定用户首日体验的路径。

3.3 Pre-Launch Bug Bash（Tier 1 与 Tier 2 发布）

对高影响发布，要求组织一场集中的 bug bash，以更高标准覆盖更广的环境与用例。原文档给出发布分级定义：

• Tier 1：Industry-Moving News（行业级大事）
• Tier 2：Important News for Our Users（对用户重要的消息）
• Tier 3：Relevant, but Not Life-Changing（相关但非颠覆性）
• Tier 4：Bug Fixes（缺陷修复）

硬性要求：任何 Tier 1 或 Tier 2 发布，bug bash 必须至少提前 72 小时排期。

经验法则：只要发布涉及以下任一情形，就应考虑安排 bug bash——配套博客文章、协调式社媒官宣、媒体关系或新闻通稿、"Turbo" 发布活动。

从机制上看，bug bash 与 Level 1 的自动化门禁形成互补：前者保证"基线正确"，后者在发布声量最大的窗口期投入更多人力去捕捉跨环境、跨用例的长尾问题。

四、Level 3：遥测与数据复盘

4.1 Dashboard health（监控面板健康度）

原文档的检查项：

• [ ] 打开 go/gemini-cli-dash（内部快捷入口）
• [ ] 进入 "Tool Call" 标签页
• [ ] 验证待晋升发布在工具调用维度上没有错误尖峰（error spikes）

Gemini CLI 的遥测体系在 docs/cli/telemetry.md 中有说明：遥测默认开启（仅收集匿名性能与错误信号，可通过设置中的 telemetry 项关闭），并提供了预配置的监控面板，覆盖概览、指标与日志视图。下面的面板截图即来自该文档，对应发布复盘时"查看指标是否有回归"的实际界面：

对发布管理者而言，这一步的意义是：preview 版本在被维护者 dogfooding 的一周里已经在收集真实信号，晋升 stable 前必须确认这些信号没有恶化——尤其关注工具调用（tool call）错误率，因为它直接反映 agent 执行 shell、读写文件等核心动作的可靠性。

4.2 Model evaluation（模型评测）

原文档检查项：

• [ ] 打开 go/gemini-cli-offline-evals-dash（离线评测面板）
• [ ] 确认待晋升发布的周期性评测运行（recurring run）处于平均评测运行的正常区间内

仓库内对应的是行为评测（behavioral evals）体系：所有评测用例存放在 evals/ 目录（40 余个 *.eval.ts 文件），docs/behavioral-evals.md 介绍了其 Eval Development Kit（EDK）——评测断言的是 agent 的行为（调用了哪些工具、调用顺序、是否规避破坏性命令），而非最终文本输出，因为模型回复具有非确定性，逐字匹配过于脆弱。每个评测声明一个策略标签：ALWAYS_PASSES / USUALLY_PASSES / USUALLY_FAILS，并提供三个本地命令：

npm run eval:inventory   # 静态扫描 evals/ 下的全部评测，生成结构化清单（可 --json）
npm run eval:validate    # lint 式结构校验，错误会阻断 CI
npm run eval:report      # 聚合 vitest report.json，按模型汇总通过率

与前文呼应：chained E2E 中的 evals 作业只运行 test:always_passing_evals（EVAL_SUITE_TYPE=behavioral，模型 gemini-3-pro-preview），即把已被历史数据证明稳定的评测作为发布链路内的硬关卡；而离线面板上的周期性 recurring runs 则承担趋势监控职责。二者结合，Level 3 的"模型评测无回归"就从一句口号变成了可核查的数据行为：单次发布内跑稳态评测（CI 内），跨版本比较均值区间（离线面板）。

五、go/no-go 决策：触发晋升前的最终确认

在触发 Release: Promote 工作流把 preview 提升为 stable 之前，发布管理者必须逐项确认：

1. [ ] Level 1：当前 preview tag 对应 commit 的 CI 与 E2E 工作流全部绿色。
2. [ ] Level 2：preview 版本已上线满一周，发布管理者已完成 CUJ 检查清单且无阻塞性问题上报。
3. [ ] Level 3：Dashboard Health 与 Model Evaluation 检查完成且无回归。

三项全部通过，即执行晋升。从 release-promote.yml 的参数看，触发者还可传入 dry_run（默认 true，安全演练）、ref（发布来源，默认 main）、stable_version_override / preview_version_override（人工纠偏版本号）与 environment（prod/dev）——这意味着 go/no-go 决策的"最后一下"也被设计成可先演练、可纠偏、失败自动告警的操作。

需要强调的是 no-go 的另一半：如果 stable 已经发布后出现关键回归，docs/releases.md 给出的补救手段是通过 Release: Change Tags 工作流调整 npm dist-tag 做回滚或前滚（rollforward），无需完整发布周期；而 preview/stable 的补丁则通过 /patch 评论触发的自动化 cherry-pick 流水线完成（Release: Patch (1) Create PR → 人工评审合并受保护分支 → Release: Patch (2) Trigger → Release: Patch (3) Release）。发布置信度策略因此构成一个闭环：事前门禁（Level 1-3）→ 晋升 → 事后回滚/补丁通道。

六、小结：三层信号如何拼成发布置信度

层级	关卡	仓库内证据	判定
Level 1	CI/CD 健康	ci.yml：Lint/类型检查/单测（Node 20/22/24 × cli/others 分片，Linux/macOS/Windows）+ CodeQL + bundle 体积监控 + bundle 与 npx 冒烟	必须全绿
Level 1	E2E	chained_e2e.yml：Linux 双沙箱矩阵（GEMINI_SANDBOX=false/docker）、macOS、Windows、行为评测	必须全绿
Level 1	冒烟测试	smoke-test.yml：bundle --version 冒烟，失败自动开 priority/p0 issue；npm 发布后执行 npx -y @google/gemini-cli@<tag> --version	必须通过
Level 2	preview dogfooding	release-promote.yml + scripts/get-release-version.js：NPM 为版本事实源、晋升前重测、失败自动告警	满一周 + 无阻塞问题
Level 2	CUJ 清单	原文档 6 大项（Setup / Auth / Prompting / Piped input / Context / Settings / Function calling）	逐项通过
Level 2	Bug bash	Tier 1/2 发布提前 ≥72h 排期	完成
Level 3	Dashboard health	docs/cli/telemetry.md 的预配置监控面板，重点看 Tool Call 错误尖峰	无回归
Level 3	Model evaluation	evals/ 行为评测 + EDK 命令 + 离线评测面板 recurring runs	处于均值区间

这套策略对任何 agent 型 CLI 项目都有参考价值：把"能不能发"从主观判断转化为可审计的三层证据链——自动化门禁保证基线，人工 dogfooding 与 CUJ 保证体验，遥测与评测保证趋势；并用 NPM dist-tag 作为版本事实源、dist-tag 变更作为回滚杠杆，让门禁既能拦下问题版本，也能快速撤掉问题版本。