release-openspec

发布 OpenSpec

将 OpenSpec 发布工作流作为可恢复的状态机运行。每次调用时都检查 GitHub 实时状态，并且只执行下一步安全操作。不要假设先前的调用已完成。

原则

• 将 Fission-AI/OpenSpec 和 origin/main 视为发布的事实来源。
• 用户询问状态、准备情况或建议时，默认只进行只读审计。
• 用户要求发布、准备发布、继续或恢复时，视为已授权执行适用的发布操作。
• 保留用户的检出状态。绝不丢弃无关更改，也绝不只是为了准备变更集而切换用户当前分支。
• 如果检出状态有未提交更改，或当前不在 main 分支上，则从当前 origin/main 创建临时工作树，用于提交发布相关更改。
• 绝不批准自己的 PR。人工审核是一个有意设置的关卡。
• 将进入合并队列视为中间状态，而非已合并。只有 GitHub 报告 mergedAt 且该提交已出现在 main 上之后，才继续推进。
• 绝不手动创建自动生成的 Version Packages PR。该 PR 由 Changesets 操作负责。
• 绝不为了重新触发 CI 而推送空提交。应先诊断运行失败或缺失的原因。
• 暂停时，报告 URL、当前达到的状态以及所需的具体人工操作。

了解两种 PR 类型

在输出和决策中明确区分：

• Changeset PR：由人员正常创建的 PR，其中添加一个或多个 .changeset/*.md 文件。优先在功能或修复 PR 中添加变更集；仅当已合并的工作应纳入发布时，才创建补充变更集 PR。
• Version Packages PR：自动生成的 changeset-release/main PR，标题为 chore(release): version packages。合并更改集或向 main 添加更改集，都会更新同一个 PR。合并此 PR 即会发布稳定版。

存在尚未关闭的 Version Packages PR，并不妨碍创建补充变更集 PR。这意味着只有审计发现了尚未纳入发布、且值得发布的工作时，补充 PR 才有用。该 PR 合并后，等待现有 Version Packages PR 更新。

从发布审计开始

1. 验证仓库和工具：

   • 使用 gh repo view --json nameWithOwner,url 确认 GitHub 仓库。
   • 执行写入操作前，确保已通过 gh、git 和 pnpm 完成身份验证。
   • 如果规范仓库不是 Fission-AI/OpenSpec，则停止所有发布变更操作。

2. 刷新信息，但不要修改工作树：

   git fetch origin main
   

   不要不加区分地获取所有标签。此仓库可能存在冲突的历史本地标签，导致 git fetch --tags 失败，即使 origin/main 已成功获取也是如此。

3. 找到最新的稳定版 GitHub Release。排除草稿和预发布版本；不要使用 git describe，因为 beta 标签可能比稳定版基线更新。

   gh release list --repo Fission-AI/OpenSpec \
     --exclude-drafts --exclude-pre-releases --limit 100 \
     --json tagName,publishedAt \
     --jq 'max_by(.publishedAt) | {tagName, publishedAt}'
   

   确保该稳定标签在本地可解析，然后再将其用作 git log 的边界。如果缺少该标签，只获取该标签。如果同名本地标签与规范远程标签不一致，请报告差异并单独解析规范提交；审计过程中绝不要强制改写用户的标签。

4. 查找未关闭的发布相关 PR：

   gh pr list --repo Fission-AI/OpenSpec --state open \
     --head changeset-release/main \
     --json number,title,headRefName,baseRefName,url,reviewDecision,statusCheckRollup
   

   根据 headRefName == "changeset-release/main" 识别 Version Packages PR，而不只看标题。另行列出可能的 changeset PR 并检查其文件；必须确认 .changeset/*.md 中有新增内容。不要把 Version Packages PR 删除的 changeset 误认为作者编写的 changeset，也不要仅凭标题判断，因为功能或修复 PR 也可能添加发布跟踪信息。

5. 阅读实时发布策略 .changeset/README.md、origin/main 上待处理的 .changeset/*.md 文件，以及存在时的 Version Packages PR 正文和文件。

6. 列出自最新稳定标签以来的第一父级提交：

   git log --first-parent --date=short \
     --pretty=format:'%h%x09%ad%x09%s' <stable-tag>..origin/main
   

7. 将值得发布的已合并 PR 与现有 changeset 对应起来。使用 PR 文件和 changeset 历史；不要仅凭措辞相似就推断已覆盖。

8. 将审计分类为：

   • missing-tracking：计划在本次发布中包含的面向用户的工作缺少 changeset；
   • awaiting-changeset-review：已有合适的 changeset PR；
   • awaiting-merge-queue：已批准的 changeset 或 Version Packages PR 正在合并队列中，但尚未进入 main；
   • awaiting-version-update：所需 changeset 已在 main 上，但 Version Packages PR 尚未纳入这些 changeset；
   • awaiting-version-review：Version Packages PR 已是最新，但尚未获批；
   • ready-to-publish：Version Packages PR 已是最新、已获批且检查通过；
   • publishing：Version Packages PR 已合并，但发布产物尚未齐备；
   • needs-finalization：npm 包、标签和 GitHub Release 均已就绪，但发布说明仍是原始内容；
   • complete：包、标签、GitHub Release 和润色后的发布说明一致。

提供一份简洁的审计结果，包含稳定版基线、拟议版本、已覆盖内容、可能的遗漏、有意跳过的内部工作或文档工作、未关闭的 PR，以及下一步操作。

判断 changeset 覆盖范围

遵循 .changeset/README.md，不要假设每个已合并 PR 都需要 changeset。

纳入选定用于发布跟踪的工作，尤其是：

• 面向用户的新功能或命令；
• 重要修复或热修复；
• 破坏性变更或弃用；
• 用户可见的性能改进。

通常跳过仅涉及文档、测试、CI 或工具，以及内部重构的工作。对于面向用户与否存在歧义的变更，应予以标记，不要默默排除。只有当歧义会实质性改变发布范围或语义化版本时，才询问用户；否则自行判断，并通过 PR 审查作为审批关卡。

创建或继续变更集 PR

仅对 missing-tracking 执行此操作。

1. 如果已有开放的变更集 PR 涵盖了缺失的工作，请复用该 PR。检查其 headRefName、头部分支所属仓库和 maintainerCanModify；从其所属仓库将确切的头部分支拉取到临时工作树，在那里进行更新，并推送回同一个 PR 的头部分支。如果该分支不可写，则停止。不要创建重复 PR 或替代分支。

2. 编写前立即阅读 .changeset/README.md。

3. 仅当不存在合适的 PR 时，才从当前的 origin/main 创建一个简短的 changeset-<scope> 分支。使用临时工作树，以免改动操作员的检出目录。

4. 每个连贯的发布单元优先使用一个变更集。单个补齐变更集可以概述为同一发布选择的多个小项。

5. 使用准确的包名 "@fission-ai/openspec"、所需的最高语义化版本更新级别、仅包含相关标题，以及面向用户的描述。

6. 推送前进行验证：

   pnpm exec changeset status
   

7. 提交、推送并创建 PR；PR 正文须列出所涵盖的已合并 PR，并说明为何需要补齐变更集。

8. 返回 PR URL 并请求人工批准后即停止。不要自行批准。

后续调用时，如果 PR 已获批准且检查均通过，则仅当用户要求继续或完成发布时，才合并或加入队列。如果 GitHub 使用合并队列，请检查 mergeQueueEntry、队列检查和 mergedAt；在 PR 确实合入 main 之前，保持 awaiting-merge-queue 状态。然后等待 Changesets action 更新 main 上现有的 Version Packages PR。简要汇报进度并轮询；不要推送空提交或再次更新分支，因为这可能撤销批准并使队列重新开始。

验证 Version Packages PR

确认其已就绪前：

1. 确认该 PR 的目标分支是 main、来源分支是 changeset-release/main，并且由预期的自动化流程生成。
2. 枚举当前 main 上所有待处理的 .changeset/*.md 文件，排除 .changeset/README.md。验证 PR 已消耗全部这些文件，并包含对应的变更日志内容。如果任何待处理变更集应推迟处理，则停止：通过单独审核的更改移除或修订它，并等待自动化流程重新生成 Version Packages PR 后再继续。
3. 使用 gh pr view 获取 baseRefOid 和 headRefOid，要求 baseRefOid 与当前的 origin/main 一致，并为两个修订版本创建干净的分离式临时工作树。如果本地缺少头部对象，先拉取不可变的 pull/<number>/head 引用。切勿在操作员当前的工作树中进行验证。
4. 在基础版本的工作树中运行 pnpm exec changeset status --output changeset-status.json，并从该文件读取预期的包和版本。如果临时工作树中没有可用的 Changesets CLI，先安装锁定的依赖项。
5. 比较基础版本的状态和完整的待处理变更集集合与头部工作树：package.json、CHANGELOG.md、已移除的变更集文件、PR 正文和拟议版本必须全部一致。这是基础版本到头部的比较，因为头部已消耗这些变更集，无法自行计算待发布内容。
6. 验证后移除临时工作树，然后使用 gh pr view / gh pr checks 检查所有必需的检查和审核状态。

如果内容是最新的但尚未获批，返回 URL 并等待人工批准。如果已获批且检查通过，则仅当用户要求发布或继续时，才合并或加入队列。启用合并队列时，不要将批准、启用自动合并或进入队列视为稳定的发布触发条件；等待 mergedAt，并确认合并已进入 main。

验证稳定版发布

Version Packages PR 合并后：

1. 找到对应合并提交的发布工作流运行记录，并等待其完成。
2. 分别验证以下 3 项：
   • npm view @fission-ai/openspec@<version> version
   • 远程标签 v<version> 指向预期的提交；
   • gh release view v<version> 存在，且不是预发布版本。
   • 发布版本的资源中包含 8 个 openspec-* 独立二进制文件和 SHA256SUMS。这些资源由 Binaries 工作流（binaries.yml）在发布版本发布约 10 分钟后附加。在 SHA256SUMS 就绪之前，安装脚本会继续安装上一个发布版本，因此用户始终有可用版本。
3. 如果只有部分资源存在，请报告当前状态，并在重试任何发布操作之前继续验证。绝不要重新发布已在 npm 上发布的版本。缺少二进制文件时无需执行 npm 操作：使用 workflow_dispatch 和发布标签重新运行 binaries.yml，以附加这些文件。
4. 所有资源就绪后，阅读 references/release-notes.md，润色 GitHub Release，并验证已保存的标题和正文。

发布 Beta 版

仅在用户明确要求 Beta 版或预发布版本时进入此流程。

1. 执行相同的审核，并确认待处理的 changeset 会生成下一个稳定版本。
2. 说明发布 Beta 版不会消耗 changeset，也不会取代稳定版 Version Packages PR。
3. 在 main 上触发现有的 release-prepare.yml 工作流；不要在本地计算或设置 Beta 版版本号。
4. 验证工作流选定的版本、npm beta dist-tag、远程标签和预发布版 GitHub Release。
5. 用户要求发布 Beta 版时，不要合并稳定版 Version Packages PR。

处理失败

• 对于 CI 失败，先检查失败的检查项和日志，再提议重新运行或更改代码。
• 对于过期的 Version Packages PR，先确认在最新 changeset 到达 main 后，release-prepare.yml 已成功运行 push。
• 对于分支分歧，让 Changesets 操作更新其分支。不要强制推送 changeset-release/main。
• 对于排队中的 PR，检查合并组检查和队列状态。如果进展正常，不要重新入队、更新分支或重新运行无关检查。
• 对于已存在于 npm 上的版本，请停止操作并协调标签/GitHub Release，而不是隐式递增版本号或重新发布。
• 对于缺少 GitHub 权限或必需审核的情况，报告具体门槛和 URL；保留检测到的状态，以便下次调用时可以通过检查继续处理。

完成报告

报告以下内容：

• 已发布的版本及稳定版/Beta 版渠道；
• changeset PR 和 Version Packages PR 的 URL（如适用）；
• 发布工作流结果；
• npm 包、标签和 GitHub Release 的验证结果；
• 发布说明的最终定稿状态；
• 有意延后的任何更改。