跟大多数开发者一样，我做 release 的方式一直很”野生”。改完代码，跑一遍 CI，看一眼 diff，标签一打就推上去了。如果手滑改了 public API，那只能等用户报 bug 才知道。
这套流程放在个人项目还行，放到 openai-agents-python 这种 SDK 上就是玩火。任何一个签名变更、任何一个依赖版本跳动，都可能炸掉下游几百个项目。
所以当我看到 OpenAI 在 Smithery 上放了一个专门的 release review skill 时，第一个反应不是”这东西有用”，而是”真有那么复杂吗，至于做成一个工具”。
我花了一下午仔细翻完它的 prompt 和 checklist 之后，改主意了。这个 skill 不是锦上添花，是把发布流程里最容易漏掉的环节做成了强制执行。说真的，这篇文章想跟你聊聊这个 skill 到底怎么做发布审查，它的判定逻辑为什么比普通 CI 更有价值，以及它的设计哲学对你自己的发布流程有什么实质启发。顺带也看下 OpenAI 内部是怎么做 release review 的，毕竟把自己的流程做成可复用的 prompt，这事本身就值得琢磨。
工作流拆解
这个 skill 的核心逻辑很简单：拿当前版本和上个 release tag 做 diff，然后逐个维度审查。但真正有意思的是它如何处理”人”的不确定性。
第一步先把远程 tags 拉下来，用 shell 脚本自动找到最近的 release tag。这一步看起来不起眼，实际上消除了手动挑 tag 的出错空间。你不需要记住上一版是 v1.2.3 还是 v1.3.0，脚本替你决定。
git fetch origin --tags --prune
BASE_TAG="$(.agents/skills/final-release-review/scripts/find_latest_release_tag.sh origin 'v*')"
tag 定好了，接下来是拉取目标分支的 diff 快照。skill 一次性把所有变更信息抓出来，从文件变动统计到提交记录再到具体的增删改。
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}"
然后走两个关键分支：预发布规划模式和最终候选模式。这两个模式的区别不是表面上”一个给建议一个做决定”，而是背后的责任边界完全不同。
预发布规划模式里，skill 不会因为 pyproject.toml 里的版本号还没改就报错。它的态度是”版本号是发布流水线的事，我只告诉你 diff 里有什么”。这个设计决策挺聪明的，把审查和发布解耦了。
最终候选模式就不一样了。如果 diff 里翻了 public API，但你声明的是 patch 版本，skill 直接给你一个 🔴 BLOCKED。没有任何商量余地。这不是不近人情，是版本号是 SDK 对下游的契约，这个责任没法商量。
在后面还有个容易忽略的步骤：文档覆盖审查。skill 不直接说”你没有更新文档”，而是先去 GitHub 上找有没有相关的 open PR。如果找到 PR 覆盖了改动，就标记为”已覆盖”而不是”缺失”。这种先查后审的做法，比大多数人类 reviewer 严谨。
架构解析
这个 skill 的架构不算复杂，但职责切分得很干净。三个文件构成骨架：
-
脚本层只有一个 find_latest_release_tag.sh，做的事极其单一。Skills 目录下通常容易把所有逻辑塞进一个 prompt 里，但这个 skill 把 tag 匹配这类确定性操作留在 shell，把需要判断的部分留给 prompt。 -
引用层是 review-checklist.md，提供了具体的审查信号表。每个检查项不是”请检查 API 变更”这种废话，而是对比 BASE 和 TARGET 在以下几个维度的差异：-
exports 和 identity 的变更 -
signatures 和 positional order 的调整 -
defaults 和 enums 的修改 -
documented behavior 的偏离 -
package metadata（Python 版本、依赖、extras）的变动
-
这种颗粒度只有看过无数次 release 翻车现场才写得出来。
prompt 本体把整个决策流程写成了一套状态机。读起来不像 prompt，更像内部的操作手册。每种模式、每种版本意图的组合都有明确的输出格式和判定标准。
比较让我意外的是 gate policy 的设计。默认 🟢 GREEN LIGHT TO SHIP，只有当找到”被证实的 blocker”才变红。“diff 很大””改动文件很多”这些直觉上的危险信号明确标注为不阻塞。这个设计哲学跟大多数 safety-first 的 CI 工具完全相反，它假设你是成年人，只在你真的踩线时才拦住你。
skill 还要求输出一份结构化的审查报告，格式是写死了的。从 diff 概览到风险评估到文档覆盖，每个部分都有固定的 markdown 模板。这意味着无论谁跑这个 skill，产出都是一致的。
使用场景
最常见的场景是 patch release。改动通常集中在几个文件里，修个 bug 或者改个内部实现。skill 走一遍 diff，确认 public contract 完好，打出 compatible plan。整个过程三分钟搞定。不需要手动翻 changelog，不需要肉眼对比两个版本的 exports 列表。
场景二是 minor release 规划期。你开始设计一个 feature，还没有实际合并代码，只是想确认方向是否符合版本策略。这时候 skill 切换到预发布规划模式，从当前 main 分支的 diff 推导出建议的版本类型，而不是要求你已经改好版本号。
有意思的是 blocked 场景的处理方式。skill 不是甩一句”under-versioned”就完了，而是要给出确切的 unblock checklist。比如某个 public API 新增了一个必选参数，skill 会具体到”这个参数需要提供一个默认值或 fallback 路径在哪一段代码，否则就不能作为 patch 发布”。
blocking 的触发条件只有几个，每个都有明确的证据标准：
-
确认的回归 bug（不是”可能”，是”已确认”） -
public API、协议、config 或持久化状态的 breaking change，且没有可用的迁移路径 -
数据丢失、损坏或安全影响的改动，且没有解决方案 -
release-critical 的打包、构建或运行时路径被 diff 破坏
有意思的是，很多直觉上的”危险信号”被明确排除了。diff 很大、改了很多文件、大规模重构这些都不会触发 block。skill 的文档里特意列了一节叫”never blocking”的内容，把这个边界划得很死。
还有个容易被忽略的场景：文档审查。skill 把文档覆盖单独抽出来作为非阻塞项。即便某个 breaking change 的迁移指南没写，也不会挡住 release。这是我见过最有分寸的处理方式，照顾了”尽快发布”和”完整文档”之间的实际矛盾。
洞察与反思
我拆完这个 skill 之后有几个想法，不一定对，但值得说道。
第一个：大部分 release review 工具都在追求自动化，但这个 skill 反其道而行。它没有试图自动跑测试、自动检查类型、自动做 benchmark。它专注于一件事：比较两个版本之间的 contract。这个边界感在今天的 AI 工具里很少见。
第二个：默认”放行”而不是”拦截”的策略，其实是对人类工程流程的一个深刻观察。如果一个 release 审核工具动不动就对大量 diff 亮红灯，开发者会麻木，然后不看报告直接跳过。相反，只在真的有证据证明会出问题时才拦截，这个工具的可信度反而更高。这东西跟安全告警一个道理，误报率太高等于没有告警。
第三个想法可能有点争议：这个 skill 暴露了一个尴尬的事实，就是大多数团队的 release review 流程根本不存在，或者只存在于某个高级工程师的脑子里。OpenAI 把这个流程变成了可复用的 prompt，本质上是在说”你需要的不是更好的 CI，是更好的判断框架”。
从版本策略的设计来看，这个 skill 还有一层隐含的哲学：它区分了”预发布建议”和”最终候选检验”两个阶段。前者的产出是推荐，后者是判定。两个阶段对相同条件的处理方式完全不同，这不是 bug，是刻意设计。
说实话，如果这个 skill 能支持多语言仓库、不只是 Python 的版本策略，它的实用范围会大得多。目前它绑定在 openai-agents-python 的上下文里，别的项目想用需要大量适配。但换个角度，它的审查方法论是通用的，把”检查清单”和”判定规则”这两层从代码中抽离出来，你自己的项目完全可以复制这套思路。
资源地址
| 资源 | 链接 |
|---|---|
| Smithery 页面 | https://smithery.ai/skills/openai/final-release-review |
| openai-agents-python | https://github.com/openai/openai-agents-python |
| Smithery | https://smithery.ai |
总结
这个 skill 做对了一件事：把 release review 从一个”凭经验”的软流程变成了一个”有证据”的硬流程。不是靠堆检查项，而是靠清晰的判定逻辑。
如果你维护的是面向公众的 SDK 或库，自己搭一套类似机制确实值得。但如果你只是想借鉴它的审查思路，光是 review-checklist.md 里的信号定义表就值一个 star。
问题是这种高门槛的 skill，到底有多少人会用。毕竟 release review 这事，大部分人要的不是复杂，是省心。但这个 skill 恰好说明了一个反直觉的结论：真正的”省心”不是跳过审查，而是把审查做到足够好，好到你不需要凭直觉判断任何事。也许过两年回头看，这种把 release review 做成可执行 prompt 的思路，会比自动跑测试的 CI 工具更有生命力。