发布渠道与维护流程
理解 npm 渠道、版本完整性检查、手动发布与 dry run 的作用。
本页描述 Gemini CLI 官方仓库的维护者发布流程。正式执行前需与 release manager 协调，并具备相应仓库、注册表与发布环境权限；普通使用者按安装指南选择渠道即可。
渠道与周期
| 渠道 | npm tag | 官方计划 |
|---|---|---|
| Stable | latest | 每周提升经过预览验证的版本 |
| Preview | preview | 每周从 nightly 提升，用于提早反馈 |
| Nightly | nightly | 每天约 UTC 00:00 发布 main 状态 |
官方发布时间表为每周二约 20:00 UTC 切 stable/preview。时间是流程计划，不保证每次自动发布准点成功；周版本通常增加 minor，期间修复增加 patch。
Promote Release 将当前 preview 提升至 stable/latest，再将 nightly 提升至 preview，并通过 PR 更新 main 的后续 nightly 版本。
版本来源与一致性
流程先查 npm dist-tags 的 latest、preview、nightly 实际版本，再核对每个版本的 Git tag 和 GitHub Release 是否存在。缺少任一对应记录就停止提升，避免在不完整的前次发布上继续计算版本。
Git 分支中的版本字符串不是唯一依据。修复发布状态时，应分别核对 npm、Git tag 和 Release。
dev 与 prod
dev 发布到私有 GitHub npm 注册表，使用 @google-gemini/ 范围；prod 发布到公共 npm，使用 @google/，由 Google 的发布授权流程管理。CLI、core 和 A2A server 分别有对应包。
环境与渠道是不同字段：不能因 NPM Channel 写了 dev，就忽略 Environment 的值。官方手动流程中 Environment 默认 prod，并要求发布管理员授权。
手动发布
Release: Manual 可指定分支、tag 或完整 commit SHA。官方列出的输入包括：
- Version：带 v 前缀的有效语义版本。
- Ref：待发布的分支、tag 或完整 SHA。
- NPM Channel：preview、nightly、latest 或 dev，默认 dev。
- Dry Run：默认 true，演练时跳过真正发布。
- Force Skip Tests：是否跳过测试，官方不建议在生产发布中使用。
- Skip GitHub Release：是否只创建 npm 发布。
- Environment：dev 或 prod。
非 dry run 失败时，流程会创建包含失败详情的 issue。正式发布的质量门槛见发布验收，补丁和标签回退见发布补丁。
检查打包产物
官方支持通过工作流 dry run 检查构建与打包日志，不执行 npm publish 或 gh release create。还提供本地 publish:npm 的 dry-run 示例，用于生成并检查 tarball。
dry run 会执行构建与预发布脚本，不是纯只读操作；应在适当源码工作区中检查产物。包概览与发布文档对 npm 是否单文件打包存在差异，已按固定提交的入口与依赖结构在架构说明注明。