final-release-review

最终发布审核

目的

以两种模式之一审核 BASE_TAG...TARGET：

• 发布前规划： 用户要求规划下一次发布，或在 Changesets 版本 PR 尚未创建时审核 origin/main，使用此模式。根据 TARGET 中的有效 changeset 确定计划发布类型。不要将软件包版本未变化视为阻碍。
• 最终候选版本： 用户要求做出最终候选版本决策，或 TARGET 中包含由 Changesets 生成的版本提交时，使用此模式。根据已消费的 changeset 确定候选版本类型，然后核实生成的软件包版本和变更日志。

将 Changesets 视为 patch 与 minor 的判断依据。由 $changeset-validation 判断每个 changeset 对其软件包差异是否使用了正确的版本提升；不要在本次审核中根据语义化版本自行将有效的已声明版本提升类型替换为其他类型。独立审核运行时兼容性、回归问题、打包和发布风险。文档准备情况应与发布门槛分开处理。

快速开始

1. 确保仓库根目录为 openai-agents-js。
2. 同步远程标签并选择上一个版本：

   BASE_TAG="$(.agents/skills/final-release-review/scripts/find_latest_release_tag.sh origin 'v*')"
   

3. 刷新并解析目标，默认为 origin/main：

   git fetch origin main --prune
   TARGET="$(git rev-parse origin/main)"
   

   将明确指定的标签或引用解析为剥离后的提交，使用 git rev-parse "${TARGET_REF}^{commit}"；在报告和比较 URL 中使用提交 SHA，而不是带注释的标签对象。
4. 独立确定审核模式和发布类型：
   1. 遵循用户明确提出的发布前规划或最终候选版本审核要求。
   2. 否则，当 TARGET 包含由 Changesets 生成的版本提交，或软件包版本已高于 BASE 时，使用最终候选版本模式。
   3. 否则，使用发布前规划模式。
5. 确定 Changesets 发布状态和类型：
   1. 在规划模式下，检查 TARGET 中所有有效的 .changeset/*.md 文件，但排除 .changeset/README.md。
   2. 在最终候选版本模式下，找出版本提交，并从其第一父提交中读取该提交删除的每个 changeset。还要检查生成的 packages/*/package.json 和 packages/*/CHANGELOG.md 变更。
   3. 记录每个源 changeset、软件包条目和已声明的版本提升类型。
   4. 将发布级别类型设为有效的已声明版本提升中最高的一项：minor 高于 patch。考虑 .changeset/config.json 中的固定软件包组；不要根据单个软件包的版本推断较低的类型。
   5. 将包含 major 条目、格式错误的 frontmatter、混合的有效与已消费发布集，或没有适用 changeset 的软件包变更，视为无效发布状态。不要将其强行归为 patch 或 minor。
6. 对发布差异进行快照：

   git diff --stat "${BASE_TAG}"..."${TARGET}"
   git diff --dirstat=files,0 "${BASE_TAG}"..."${TARGET}"
   git log --oneline --reverse "${BASE_TAG}".."${TARGET}"
   git diff --name-status "${BASE_TAG}"..."${TARGET}"
   

7. 使用 references/review-checklist.md 审核差异，并根据已发布的契约证明或排除每个候选问题。
8. 使用当前只读 GitHub 状态，查找并审核相关的未关闭文档 PR。不要根据本地分支、标题或历史背景推断文档覆盖情况。
9. 报告 Changesets 发布状态、发布/阻止门槛、风险评估、文档覆盖情况，以及有条件的 minor 发布版 Key Changes 草稿。

Changesets 发布策略

• 在预发布规划中，以启用状态的 changeset frontmatter 为准；在生成的最终候选版本中，以已消费的 changeset frontmatter 为准，作为权威的发布类型声明。
• 除非当前证据另有说明，否则假定 CI 中所需的 changeset 验证已通过。如果无法获取其状态，请明确说明；不要在此技能中悄悄重新运行语义版本升级分类。
• 如果当前证据表明 changeset 缺失、格式错误、过时或不一致，请报告发布准备缺陷。在规划模式下，给出确切的修正方式，但不要假装候选版本已存在。在最终候选版本模式下，必须先确保 Changesets 输入与生成的输出一致，否则予以阻止。
• 如果目标中没有可发布的包变更，也没有 changeset，则发布类型为 none。不要凭空指定补丁版本发布。
• 在规划模式下，包版本仍可能与 BASE 相同。后续版本升级由 Changesets 工作流负责。
• 在最终候选版本模式下，请核实已消费的发布类型、生成的包版本、固定组传播、更新日志和版本提交是否一致。不一致即为阻止发布的理由。
• 用户提供的 patch 或 minor 标签只是背景信息，不能覆盖仓库中的 Changesets 状态。请报告两者不一致，并以仓库声明为准。
• 区分未记录的迁移与缺少可用迁移或兼容路径。缺少文档不构成阻止发布的理由；但如果实际破坏了受支持路径，且没有可用迁移或回退方案，则无论声明的版本升级类型如何，都可能阻止发布。

确定性门禁策略

• 默认使用 🟢 GREEN LIGHT TO SHIP，除非有证据证实至少一项阻止发布的条件。
• 只有在有具体的发布阻止证据且有明确可执行的解除条件时，才使用 🔴 BLOCKED。
• 阻止发布的条件：
  • 已确认存在由 BASE_TAG...TARGET 引入的回归或缺陷。
  • 在最终候选版本模式下，Changesets 状态无效，或已消费的 changeset 与生成的版本、更新日志或固定组更新不一致。
  • 已确认公共 API、协议、配置或持久状态发生破坏性变更，且没有可用迁移、回退方案或兼容路径。
  • 存在具体的数据丢失、损坏或安全影响，且尚未解决缓解措施。
  • 此差异导致发布关键的打包、构建或运行路径失效。
• 以下情况本身绝不构成阻止发布的理由：
  • 差异规模大、大范围重构或涉及许多文件。
  • 没有证据支持的“可能导致回归”猜测。
  • 未在本地重新运行 CI 检查。
  • 文档缺失、不完整、未合并、过时或在发布后补充。
  • 预发布规划模式下包版本元数据未变化。
• 文档审查可能揭示潜在的运行时或兼容性缺陷。应针对该缺陷阻止发布，而不是针对文档状态。
• 即使门禁结果为绿色，也仍须说明对用户有重要影响的发布内容。

工作流

准备并梳理差异

• 获取最新的远程标签和目标引用。比较时排除工作树中的更改。
• 优先使用用户指定的基础标签，但仍须刷新远程标签。
• 除非另有说明，否则假定目标已通过仓库 CI，包括 $code-change-verification 和 $changeset-validation。默认不要重新运行常规单元测试、lint、格式化、类型、覆盖率或 changeset 检查。
• 使用差异统计、目录分布、提交顺序和名称状态来识别高风险区域。将已更改的测试作为行为证据阅读，但不能仅凭测试本身认定问题已得到证明。

审计契约并验证发现

• 比较 BASE 和 TARGET，而不是孤立地审查 TARGET。
• 对于公共 API，比较导出项、标识、TypeScript 签名、参数顺序、默认值、枚举和文档所述行为。
• 对于软件包，比较支持的 Node.js 和 TypeScript 版本、依赖项、对等依赖项、可选依赖项、软件包导出项、发布内容、版本元数据，以及 ESM/CJS/类型行为。
• 对于持久化状态、架构、协议、配置和环境变量，明确已发布的持久化边界，并验证向后读取能力或可行的迁移路径。
• 通过 .agents/references/README.md 中对应的参考文档跟进运行时变更，并追踪必要的使用方和对称性维度。
• 只有当差异证明存在契约违规、可触达的受支持路径回归，或具体的用户可见发布事项时，才将候选项列为风险。
• 当静态证据无法解决影响决策的问题时，使用最小化且完全相同的 BASE 与 TARGET 公共路径或打包产物探测。
• 将已验证的安全事项标记为 🟢 LOW，将具体但尚未解决的回归信号标记为 🟡 MODERATE，将已确认的阻碍项标记为 🔴 HIGH。
• 每项风险都必须包含 Evidence、Impact、Files 和 Action。对于安全的发布事项，不要凭空要求测试或代码工作。

审查文档覆盖情况

• 首先根据运行时审计整理文档义务清单：破坏性变更、迁移、默认值、选择加入或退出、主要功能、公共 API、提供方和依赖项兼容性、持久化架构，以及用户工作流变更。
• 在报告任何义务未覆盖之前，先通过获准的只读 GitHub 访问检查当前未合并的 PR。切勿在此仓库中使用 gh，也不得修改 GitHub。
• 根据 Changesets 发布类型、可能的版本、功能名称、关联的实现 PR、分支名称和已更改的文档路径查找候选 PR。不要只依赖 PR 标题。
• 对每个候选项，记录其 PR 编号或 URL 以及最新的 head SHA，然后审查其完整的当前差异，以及任何会实质影响覆盖判断的讨论。多个 PR 可以共同覆盖清单中的义务。
• 将发布目标差异与文档 PR 差异分开。不要暗示尚未合并的文档 PR 已包含在发布目标中。
• 将总体覆盖情况分类为 covered、partially covered、not covered、stale/conflicting 或 unverified。
• 如果无法进行当前的只读 GitHub 访问，则使用 unverified，说明搜索限制，且不得声称不存在文档 PR。
• 对于每项无法证明已覆盖的义务，建议发布后应修改的确切文件、章节、示例或说明，并给出所需的迁移或兼容性表述。覆盖情况未验证时，将建议标记为暂定。
• 将尚未合并的文档 PR 视为可接受的发布后交接方案。若应等到 SDK 发布后再合并，请注明。

起草次要版本的关键变更

• 当权威 Changesets 发布类型为 minor 时，提供一份可直接复制的关键变更草稿。除非用户提出要求，否则 patch 或 none 不提供。

• 根据已验证的面向用户的契约和 changeset 摘要来撰写草稿，而不是依据原始提交数或目录摘要。

• 遵循既定的 JS 发布格式：

  ## Key Changes
  
  ### <User-facing theme>
  
  <A concise paragraph describing the behavior, exact public names, and migration or fallback when applicable.>
  

• 如果只有一个主要主题，则使用一个章节；范围更广的次要版本通常使用两个到七个章节。不要添加虚构的 Highlights 列表。

• 首先说明破坏性行为，以及受支持的迁移方式或回退方案。如果次要版本没有破坏性变更，请在相关介绍章节或第一个主题中说明。

• 涵盖主要发布主题，但不要复述生成的 ## What's Changed 列表。保留准确的公开名称、默认值、版本范围、退出选项和兼容性限定条件。

• 仅使用稳定的已发布文档 URL。不要包含开放分支链接；在“文档覆盖”部分单独提及开放的文档 PR。

• 即使发布受阻，也要提供草稿，但不要让润色过的发布文案掩盖阻碍因素。

形成建议

• 说明 BASE_TAG、TARGET 提交、审查模式、Changesets 状态及来源、权威发布类型，以及已知时的候选版本号。
• 概述关键目录和文件数量，但不要把每次提交都变成报告条目。
• 仅列出有依据的阻碍因素，以及最重要的已验证发布注意事项，通常按用户影响分组为两到五项。
• 将文档覆盖情况单独列为非阻塞章节。
• 如果受阻，请提供精确的解除阻塞清单和通过条件。如果没有具体的解除阻塞操作，则不要标记为受阻。
• 不要包含常规命令结果、通过数量、跳过项、取消选择项或验证状态清单。

输出格式（必需）

使用英文，并按照仓库 AGENTS.md 中的 “GitHub-ready Output” 章节，按以下结构生成报告。默认将完整报告（包括任何关键变更草稿）放入一个可复制的 markdown 代码块中；下方模板是该代码块的字面内容。若明确要求提供不带围栏的原始文本，则遵照要求。

在报告中，将固定的比较 URL https://github.com/openai/openai-agents-js/compare/<tag>...<target-commit> 作为裸 URL 使用。文档和版本 PR 使用 GitHub 原生引用格式，例如 #123。不要创建 Markdown 链接，也不要重复包装已经渲染的链接。文件证据使用仓库相对路径并置于行内代码中，绝不使用本地绝对路径或本地文件链接。如果用户要求不提供文件路径，则在 Changesets 来源和风险字段中使用受影响的组件或文档章节名称。将特定于宿主的引用和注释放在报告代码块之外。

发送前，检查可复制的源内容，确保其中只有一个完整的比较 URL、包含原生 PR 引用、使用可移植的文件证据，并且没有嵌套链接包装或特定于宿主的标记。仅修正格式时，保留原审查的证据和范围。

### Release readiness review (<tag> -> TARGET <ref>)

This is a release readiness report done by `$final-release-review` skill.

### Diff

https://github.com/openai/openai-agents-js/compare/<tag>...<target-commit>

### Release intent

- Review mode: <pre-release planning | final candidate>
- Changesets state: <active | consumed | none | invalid>
- Changesets source: <repository-relative changeset paths or version commit; use a release-set description when paths are excluded; include validation limitation when material>
- Release type: <patch | minor | none | invalid>
- Candidate version: <version when generated, or not yet generated in planning mode>
- Versioning verdict: <declared plan | generated candidate consistent | correction required | invalid candidate>

### Release call

**<🟢 GREEN LIGHT TO SHIP | 🔴 BLOCKED>** <one-line rationale>

### Scope summary

- <N files changed (+A/-D); key areas touched: ...>

### Risk assessment (ordered by impact)

1. **<Finding or release consideration title>**
   - Risk: **<🟢 LOW | 🟡 MODERATE | 🔴 HIGH>**. <Impact statement.>
   - Evidence: <specific BASE-versus-TARGET evidence>
   - Files: <repository-relative paths, or affected components when paths are excluded>
   - Action: <next step and pass condition>

### Documentation coverage (non-blocking)

- Coverage source: <native PR reference and head SHA, multiple PRs, none found after a successful search, or search unavailable or partial>
- Status: <covered | partially covered | not covered | stale/conflicting | unverified>
- Covered obligations: <concise list or none>
- Gaps or post-release suggestions: <exact files, sections, claims, or none>
- Publication timing: <merge after release when docs describe unreleased behavior, or not applicable>

### Unblock checklist

1. [ ] <required only when blocked>
   - Exit criteria: <what must be true>

### Key Changes draft

<Include the copy-ready `## Key Changes` block only for a Changesets-declared minor release.>

### Notes

- <Material assumptions only>

• 如果发布状态为绿色，则省略 Unblock checklist。
• 对于 patch 或 none，除非用户提出要求，否则省略 Key Changes draft。
• 对于会影响行为的绿色发布，至少保留一项 🟢 LOW 注意事项；不要只写“No material risks identified”。
• 对于没有可报告的面向用户契约的纯元数据发布，可以简洁说明风险为空。

资源

• scripts/find_latest_release_tag.sh：刷新远程标签并返回最新匹配的发布标签。
• references/review-checklist.md：详细说明 Changesets 解析、发现信号、文档覆盖审查和证据要求。