发布渠道与维护流程
理解 npm 渠道、版本完整性检查、手动发布与 dry run 的作用。
This page has not been translated into English yet. The original Chinese version is shown below.
本页描述 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 是否单文件打包存在差异，已按固定提交的入口与依赖结构在架构说明注明。