codexhost 版本发布

目标：通过仓库既有 GitHub Actions 发布，不在本地执行 npm publish，不手动创建 GitHub Release，不绕过 CI。

必须先读

完整读取 发布提交指南。该参考收录用户提供的发布指南，并补充正式与预览发行的区别。

所有命令在仓库根目录执行。开始操作前核对当前的：

• AGENTS.md、package.json 和 scripts/release/prepare-version.mjs
• .github/workflows/release-packages.yml 与 .github/workflows/ci.yml
• packages/repository-automation/src/release.mjs
• docs/operations/repository-maintenance.md
• 涉及更新提示时：packages/update-manager/src/github-release.ts

源码和工作流是执行行为的依据。发现指南与当前实现不一致时，说明差异；不要假装已有不支持的发布能力。

1. 确认版本与渠道

先区分 npm 和 GitHub 两个渠道，不能把“预览版”一概等同于 npm next。

模式	版本例子	npm dist-tag	GitHub Release	普通用户更新提示
正式发布	0.12.2	latest	正式、latest	满足更新条件时提示
静默预览发行	0.12.2	latest	Prerelease、非 latest	不提示此版本
SemVer 预发布	0.12.2-rc.1	next	Prerelease	不提示此版本
npm 测试发行	0.12.2-test.1	test	当前工作流不创建 Release	不提示此版本

“正常发布”走正式发布。“用户能正常从 npm 下载新版，但不要更新提示”走静默预览发行：稳定 SemVer，手动运行工作流时 github_prerelease=true、skip_npm=false。

静默预览发行仍是公开发行，不是私有版，也不阻止用户通过 npm 更新。当前更新提示读取 GitHub 正式 latest Release，而不是 npm latest。

用户意图不清楚时，先问清两个渠道的目标。最终执行前明确报告版本、npm dist-tag、GitHub 状态与是否提示更新。

2. 检查现场与验证

1. 检查工作区、当前分支、远端与已有标签；快进同步 main，不覆盖无关修改。
2. 检查目标版本是否已存在于 npm 或 GitHub，是否有正在运行的发布。已推送标签不等于已发布；取消发布也不保证 npm 从未接受某个平台包。
3. 新版本用 npm run release:prepare -- <version> 同步四个版本文件，检查 diff。
4. 执行 npm run check。已有无关问题阻断时，报告具体文件、步骤和未执行检查，不顺手修复；不得声称全部通过。
5. 只提交四个版本文件，使用 chore: prepare v<version>，推送 main。
6. 确认标签目标 SHA 对应的 main push CI成功，包含四个基线 job。不能用另一提交的 CI、本地检查或 PR CI 代替。

CI 失败时查看失败 step 和原始诊断。不自动重试测试或放宽超时；只有核实为可重试的临时故障并获授权后才重跑失败 jobs。重跑完成前不得报告 CI 通过。

3. 文案与人工确认

从上一个实际 Release Tag 到目标提交梳理变化，核实已合入 PR 和真实贡献者。按参考指南编写 .git/release-notes-v<version>.md：

• 摘要先英文、后中文；英文 Features / Fixes 后放完整中文列表。
• 写用户可见结果，合并同类变化，不列内部 CI、测试、chore 或 docs 改动。
• Installation 和 Contributors 只用英文；PR 编号及贡献者用户名必须有证据。
• 预览发行的 Installation 增加实际安装渠道说明；静默预览版使用普通 npm 安装命令，rc 等使用 @next。

**向用户展示全文，并取得明确确认后才能创建或推送 Tag。**文案确认后有实质修改，需要再次确认。模糊回复、仅要求查看文案或准备 Skill，不是发布授权。

4. 触发发布

正式发布 / SemVer 预发布 / npm 测试发行

远端确切提交 CI 成功、文案确认后，在版本提交上创建 annotated Tag：

git tag -a v<version> <release-sha> --cleanup=verbatim -F .git/release-notes-v<version>.md
git show --no-patch v<version>
git push origin v<version>

Tag 推送触发自动发布，版本决定渠道。

静默预览发行：npm latest + GitHub Prerelease

不要先推送 Tag 再取消默认正式发布：这是竞态，可能来不及阻止 npm 或 GitHub 发布。

1. 核实默认分支工作流支持 github_prerelease。
2. 已存在且核实正确的远端 annotated Tag 可直接复用，不移动标签。
3. 新标签仍会触发默认正式发布，当前工作流没有仅推送预览标签的开关。先明确告知用户并取得临时禁用整个 Release packages 工作流的授权，核实没有其他发布需要触发；在 CI 和文案确认后，记录工作流原状态，临时禁用、创建并推送 annotated Tag、恢复工作流，再确认没有默认 tag push 发布 run。发生失败也要恢复原状态并报告。没有该授权就停在准备阶段，不推送新标签。
4. 从 main 手动运行 Release packages，输入：

tag=v<version>
github_prerelease=true
skip_npm=false

手动流程固定标签提交，并保留版本及确切提交 CI 校验。工作流的禁用、启用、dispatch 均可通过 gh workflow 或 GitHub Actions REST API 操作，先确认权限和原状态。

若权限不足、无法安全恢复工作流或有并行发布，停下并说明阻碍，不退回有竞态的“推送后取消”方案，也不假定用 Git refs API 创建标签一定不会触发工作流。未来若源码增加安全的 tag push 预览路由，优先使用经过验证的新入口并同步本指南。

5. 跟踪、暂停与恢复

• 检查实际 workflow run ID、事件、目标 tag / SHA 和输入，不只看工作流名字。
• 没有 gh 时可用 GitHub REST API；凭据只在进程内读取，不打印 Token，不写入日志或文档，不把凭据放到命令行参数中。
• 用户说“暂停”：取消本次发布 run，不默认禁用整个工作流。取消后核实各 job 与已发布包 / Release；GitHub Actions 不支持暂停后原地续跑。
• 恢复静默预览发行时，继续从 main 手动 dispatch 并显式传 github_prerelease=true。不要直接重跑原来的 tag push run，否则仍会按默认正式发行执行。
• 默认只重跑失败 jobs；npm 若已接受某个版本，先核实产物与重跑脚本的幂等性，不修改内容再发布同一版本。
• 不删除、移动或覆盖已推送 Tag；确需处理时必须取得针对该操作的明确确认。

6. 完成标准

分别核实并报告：

1. 确切发布 SHA 的 CI 结果。
2. npm 元包及全部目标平台包的版本、目标 dist-tag。
3. GitHub Release 的 prerelease 标记、正式 latest 是否符合预期及四个安装包。
4. 静默预览发行没有成为 GitHub latest；不能只凭 prerelease 输入推断成功。
5. 工作区状态、运行链接，以及实际执行 / 阻断 / 跳过的检查。

排队、构建中、等待 CI 都只能称为“已启动”，不能称为“发布完成”。只完成其中一个渠道时明确报告部分发布。