我们使用 Codex 改变维护 OpenAI Agents SDK 代码仓库的方式。代码仓库内的技能、AGENTS.md 和 GitHub Actions 让我们能将验证、发布准备、示例集成测试和 PR 审查等反复进行的工程工作转化为可重复执行的工作流。即使配置相当简单，也帮助我们提高了这些活跃代码仓库的开发吞吐量。2025 年 12 月 1 日至 2026 年 2 月 28 日，这两个代码仓库共合并了 457 个 PR，高于此前三个月（2025 年 9 月 1 日至 2025 年 11 月 30 日）的 316 个（Python：182 -> 226，TypeScript：134 -> 231）。
先简单介绍一下背景：该 SDK 提供 Python 和 TypeScript 版本。它提供了构建智能体应用的核心组件，也让开发者能以简洁的方式在 Realtime API 之上构建语音智能体，支持多个智能体、工具以及人工介入控制。它的使用规模相当可观：截至 2026 年 3 月 6 日，按近期各自的 30 天统计窗口计算，Python 包在 PyPI 上的下载量约为 1470 万次，TypeScript 包在 npm 上的下载量约为 150 万次。
配置很简单：
- 在
AGENTS.md中记录代码仓库规则 - 在
.agents/skills/中存放代码仓库本地技能 - 根据需要在这些技能中加入脚本和参考资料
- 需要在 CI 中运行同一工作流时，使用 Codex GitHub Action
这套配置为 Codex 提供了关于代码仓库运作方式的稳定上下文，从而提高日常重复工程工作的速度和准确性。
如果您维护公开的开源项目，请参阅 Codex for OSS。符合条件的维护者可以申请包含 Codex 的 ChatGPT Pro、 API 额度，以及有条件的 Codex Security 访问权限。
将工作流保存在代码仓库中
在这些代码仓库中，我们用技能来记录各自特有的工作流。技能是一个小型操作知识包：包含一份 SKILL.md 清单，以及可选的 scripts/、references/ 和 assets/。Codex 自定义文档解释了这种做法为什么有效：技能可以承载更丰富的指令、脚本和参考资料，又不会在一开始就占用智能体的大量上下文，因此很适合可重复执行的工作流。
这与技能采用的渐进式披露机制一致：
- 智能体首先看到
name和description等元数据 - 只有选中技能后，才加载
SKILL.md - 只在需要时读取参考资料或运行脚本
两个 SDK 代码仓库都将这些工作流与代码放在一起：
Python 代码仓库提供了一个较简单的基础配置：
code-change-verification在代码或构建行为发生变化时，运行必需的格式化、代码检查、类型检查和测试流程。docs-sync对照代码库审查文档，找出缺失、错误或过时的内容。examples-auto-run以自动模式运行示例，并提供日志和重新运行的辅助工具。final-release-review比较上一个发布标签与当前候选发布版本，检查是否已准备好发布。implementation-strategy在着手修改运行时或 API 之前，确定兼容性边界和实现方式。openai-knowledge通过官方文档 MCP 工作流获取最新的 OpenAI API 和平台文档。pr-draft-summary在交接时准备分支名称建议、PR 标题和描述草稿。test-coverage-improver运行覆盖率检查，找出最大的覆盖缺口，并提出最有价值的测试建议。
JavaScript 代码仓库采用相同的总体模式，并针对其 npm 单体代码仓库和发布流程增加了几个专用技能：
changeset-validation检查变更集和版本升级级别是否与包的实际差异相符。integration-tests将包发布到本地 Verdaccio 注册表，并验证它们在各个受支持运行时中的安装和运行行为。pnpm-upgrade协同更新 pnpm 工具链和 CI 中锁定的版本。
比具体技能清单更重要的是这套模式。每个技能都有范围明确的职责约定、清晰的触发条件和具体的输出。
一些最有用的技能并不是强制关卡。docs-sync 和 test-coverage-improver 采用先报告、后修改的工作流：检查当前差异或覆盖率产物，确定重要事项的优先级，并在修改前请求审批。在 Python 代码仓库中，docs-sync 还将源代码中的文档字符串和注释作为生成参考文档的权威来源，而不是手动修补生成的内容。仅用于 JavaScript 代码仓库的 pnpm-upgrade 技能也是一个职责明确的维护工作流范例：它一并更新本地 pnpm 版本、packageManager 和工作流中锁定的版本，而不是依赖大范围的搜索替换。
将工作流设为必需步骤
当代码仓库要求在恰当的时机使用技能时，技能就能发挥更大的作用。这正是 AGENTS.md 的作用。
AGENTS.md 指南将这些文件描述为代码仓库级指令，它们随代码库一起维护，并在智能体开始工作前生效。指南还建议保持文件精简。在 Agents SDK 代码仓库中，我们用这些文件记录 Codex 每次都应遵循的规则，并将最有价值的规则放在靠前的位置。
实际使用中，两个代码仓库都通过简短的“如果……就……”规则规定何时必须使用技能。在着手修改运行时或 API 之前，先调用 $implementation-strategy，确定兼容性边界和实现方式。如果改动影响 SDK 代码、测试、示例或构建行为，就调用 $code-change-verification。如果 JavaScript 包的改动影响发布元数据，就调用 $changeset-validation。如果工作涉及 OpenAI API 或平台集成，就调用 $openai-knowledge。工作完成并准备好交接时，调用 $pr-draft-summary。
这种结构也符合 agents.md 的建议：将项目概览、构建和测试命令、代码风格、测试指南、安全注意事项及其他代码仓库专用规则集中放在一处。Agents SDK 代码仓库遵循这一结构，同时将日常工作中最重要的操作触发条件放在最前面。精简版本如下：
# AGENTS.md
## Project overview
- Core SDK code lives under `src/agents/` or `packages/*/src/`.
- Tests live under `tests/` or `packages/*/test/`.
- Sample apps and integration surfaces live under `examples/`.
## Mandatory skill usage
- Use `$implementation-strategy` before editing runtime or API changes that may affect compatibility boundaries.
- Run `$code-change-verification` when runtime code, tests, examples, or build/test behavior changes.
- Use `$openai-knowledge` for OpenAI API or platform work.
- Use `$pr-draft-summary` when substantial code work is ready for review.
## Build and test commands
- Python: `make format`, `make lint`, `make typecheck`, `make tests`
- TypeScript: `pnpm i`, `pnpm build`, `pnpm -r build-check`, `pnpm lint`, `pnpm test`
## Compatibility rules
- Preserve positional compatibility for public constructors and dataclass fields.实际文件在此基础上补充了各代码仓库特有的细节，例如 JavaScript 代码仓库中的 $changeset-validation，以及两个文件中更详细的运行时、文档和发布指南。如果您想查看完整示例，请参阅 openai-agents-python 中的 AGENTS.md 和 openai-agents-js 中的 AGENTS.md。
AGENTS.md 不仅用于记录技能触发条件。Python 代码仓库还在其中记录了一条公共 API 兼容性规则：保持导出的构造函数参数和 dataclass 字段按位置使用时的含义不变，尽可能将新增的可选参数或字段追加到末尾；如果无法避免重新排序，则添加兼容性测试。这也是一种好做法：将对发布至关重要的兼容性规则与技能触发条件放在同一处。
验证规则
$code-change-verification 就是一个很直观的例子。
两个代码仓库的规则都不是“始终运行一整套冗长的验证流程”，而是“当运行时代码、测试、示例或构建与测试行为发生变化时，运行验证；验证通过前，不得将工作标记为完成”。
按条件触发，让仅涉及文档的工作保持轻量；强制执行，则确保 SDK 代码改动经过代码仓库的标准验证步骤。
具体的验证流程写在技能本身中。
在 Python 代码仓库中，该技能要求运行：
make format
make lint
make typecheck
make tests在 JavaScript 代码仓库中，该技能要求严格按以下顺序运行：
pnpm i
pnpm build
pnpm -r build-check
pnpm -r -F "@openai/*" dist:check
pnpm lint
pnpm test技能明确了代码仓库对“已验证”的定义，而 AGENTS.md 让这一定义得到强制执行。
变更集验证
对于包的改动，JavaScript 代码仓库还有一个必需步骤：调用基于 Changesets 构建的 $changeset-validation。
当 packages/ 下的任何内容或 .changeset/ 发生变化时，模型不能只运行测试。它还必须创建或更新相应的变更集，验证版本升级级别，并确认变更集确实与差异相符。
这个技能不只是检查文件是否存在。它要求 Codex 判断 git diff 的内容，并将验证规则保存在共享提示中，让本地运行和 GitHub Actions 使用相同的逻辑。它还记录了代码仓库特有的规则，例如：
- 如果分支已有变更集，则使用现有变更集，不再另建一个
- 使用 Conventional Commit 风格，将摘要控制在一行内，使其也可用作提交标题
- 在 1.0 之前，普通功能开发应避免升级主版本号；明确标记为仅供预览的新增内容，如果不改变现有行为，则按补丁级别的改动处理
- 根据包的实际改动，验证所需的版本升级级别
这样，Codex 就必须先验证自己创建的发布元数据，才能宣布工作完成。
使用最新文档
当工作涉及 OpenAI API 或平台集成时，两个代码仓库还都要求使用 $openai-knowledge。
该技能对官方 OpenAI 文档 MCP 做了轻量封装。它不让模型凭记忆回答，而是指示 Codex 使用 OpenAI 开发者文档 MCP 服务器，查询 Responses API、工具、流式传输、Realtime 和 MCP 等功能的最新文档。
如果本地 Codex 环境尚未配置 MCP 服务器，该技能会引导维护者参阅文档 MCP 快速入门和官方 MCP 服务器端点。
准备 PR 交接材料
完成实质性工作时，两个代码仓库都会使用 $pr-draft-summary。
只有当任务基本完成或已准备好接受审查，并且改动涉及实质性的代码、测试、示例、影响行为的文档或构建与测试配置时，该技能才会触发。随后，它会自动收集分支名称、工作树状态、已更改的文件、差异统计和最近的提交，并生成：
- 分支名称建议
- PR 标题
- PR 描述草稿
输出格式有意作了严格规定。典型结果如下：
# Pull Request Draft
## Branch name suggestion
git checkout -b fix/tracing-lazy-init-fork-safety
## Title
fix: #2489 lazily initialize tracing globals to avoid import-time fork hazards
## Description
This pull request fixes import-time tracing side effects that could break fork-based process models by moving tracing bootstrap to lazy, first-use initialization.
It updates tracing setup so initialization happens once on first access while preserving the existing public tracing APIs.
It also adds regression tests for import-time behavior, one-time bootstrap, and custom provider handling.
This pull request resolves #2489.一旦您信任模型能够验证和总结自己的工作，让它生成 PR 草稿就自然成为最后一步。这样既能让交接材料保持一致，也能减少代码编写完成后的重复写作。
写好技能描述
技能的 SKILL.md 前置元数据中的 description 字段是路由约定的一部分。
这是结构上的要求，而非文风上的选择。智能体技能规范将 name 和 description 定为 SKILL.md 前置元数据中的必填字段，其渐进式披露模型规定，启动时会为所有技能加载这些字段。完整的 SKILL.md 正文以及任何 scripts/、references/ 或 assets/ 中的内容，都要等到技能实际激活后才会加载。
Codex 技能文档和自定义文档从 Codex 的角度描述了同样的行为：Codex 先通过各项技能的元数据发现技能，选中技能后才加载 SKILL.md，并且只在需要时读取参考资料或运行脚本。在 OpenAI API 中使用技能的 Cookbook对托管式 Shell 一侧的行为也有同样明确的描述：OpenAI 首先读取每项技能的 name、description 和路径，模型再根据这些信息决定何时读取完整的 SKILL.md。其中的 SKILL.md 前置元数据部分更直接地指出：name 和 description 对技能发现和路由很重要。
因此，在 Agents SDK 代码仓库中，Codex 尚未读取技能的其余内容时，description 就是主要的路由依据之一。
下面以 code-change-verification 为例具体说明。
过于笼统的写法：
description: Run the mandatory verification stack in the OpenAI Agents JS monorepo.更好的写法（实际使用的描述）：
description: Run the mandatory verification stack when changes affect runtime code, tests, or build/test behavior in the OpenAI Agents JS monorepo.较短的版本已经告诉 Codex 这项技能能做什么，但仍未说明它何时适用、哪些类型的改动应该触发它，以及这些检查是否可选。更具体的版本则向模型交代了这三点。
pr-draft-summary 也采用了同样的方式。
过于笼统的写法：
description: Create a PR title and draft description for a pull request.更好的写法（实际使用的描述）：
description: Create a PR title and draft description after substantive code changes are finished. Trigger when wrapping up a moderate-or-larger change (runtime code, tests, build config, docs with behavior impact) and you need the PR-ready summary block with change summary plus PR draft text.同样，实际使用的描述就是路由元数据。它告诉 Codex：
- 这是一项在任务结束时使用的技能
- 它适用于实质性改动，而非每一轮聊天
- 输出是可以直接用于 PR 的内容块，而不只是文字总结
这些代码仓库带来的一条实用经验是：值得花时间写好 description。如果路由不够可靠，请先完善元数据，再添加更多代码。
将机械性操作交给脚本
接下来的问题是：哪些工作应该交给模型，哪些应该交给脚本。
一种可靠的分工方式是：
- 解读、比较和报告仍由模型负责
- 确定性的、重复执行的 Shell 操作放入
scripts/
这与公开指南一致。Codex 自定义文档指出，技能可以为 Codex 提供更丰富的指令、脚本和参考资料，支持可重复执行的工作流，同时避免一开始就让上下文过于臃肿。这适合以模型为主的工作方式：让 Codex 处理需要结合上下文判断的部分，只在必要时引入脚本来完成确定性的部分。在 OpenAI API 中使用技能的 Cookbook还建议像设计小型 CLI 一样设计技能脚本：从命令行运行，向 stdout 输出确定性的结果，失败时通过用法说明或错误消息明确报错，并在需要时将输出写入已知文件路径。
在 Agents SDK 代码仓库中，我们尽量将模型用在其智能确实能发挥作用的地方，例如：
- 阅读源代码，推断预期行为
- 将日志与预期行为进行比较
- 判断版本差异中是否存在实际的兼容性风险
- 给出维护者可以据此采取行动的说明
脚本则负责这些工作中的机械性操作，例如：
- 按固定顺序运行代码仓库要求的验证命令
- 启动示例运行、收集每个示例的日志，并为失败的示例写入重跑文件
- 在审查是否具备发布条件之前，获取上一个版本的发布标签
- 提供
start、stop、status、logs、tail、collect和rerun等辅助命令，方便重复运行同一工作流
如果模型每次都要重新摸索同一套 Shell 操作步骤，通常意味着这些步骤应该写成脚本。如果任务需要结合上下文、权衡取舍或作出解释，这部分就应该继续交给模型。
自动化集成测试
自动化集成测试是这两个代码仓库中最有用的工作流领域之一。这里有两个相互关联的层次：一是在两个代码仓库中自动验证仓库内的示例；二是在 JavaScript 代码仓库中，另外验证已发布的软件包按用户的实际使用方式安装后是否仍能正常工作。
采用这套配置之前，示例验证有一部分依靠手动完成。您可以运行示例，但最后一步往往仍需要人工查看日志，或检查输出看起来是否正确。对于单个示例，这还应付得来；但随着 SDK 代码仓库不断增长，这种方式就难以扩展。
第一层是 examples-auto-run，不过先有运行器，后有技能。要实现示例验证自动化，我们首先必须在两个代码仓库中构建底层支持，使示例能够以非交互方式执行。也就是说，要让示例脚本可以在自动模式下运行，包括通常需要交互输入或审批的示例。
这些基础工作包括：
- 自动回答常见的交互式提示
- 在运行器支持的情况下，自动批准 HITL、MCP、
apply_patch和 Shell 操作 - 将仍不适合自动化的示例保留在自动跳过列表中，例如需要额外运行时配置的实时示例或 Next.js 应用示例
- 为每次示例运行写入结构化日志
- 生成重跑文件，以便仅重试失败的示例，无需全部重新运行
有了这些基础，我们再将其组织成技能，让工作流便于复用和调用。在 Python 代码仓库中，examples-auto-run 封装了 uv run examples/run_examples.py --auto-mode --write-rerun --main-log ... --logs-dir ...。在 JavaScript 代码仓库中，它封装了构建检查，随后以自动模式运行 pnpm examples:start-all，并支持按示例记录日志和重跑。
为了提高验证质量，运行器负责执行示例，并将每个示例的 stdout 和 stderr 保存在各自的日志中。随后，技能会让 Codex 逐一查看这些日志，并与源代码进行比较：
- 阅读示例源代码和注释
- 推断预期流程
- 打开对应的日志
- 将预期行为与实际的 stdout 和 stderr 进行比较
- 对每个成功运行的示例都执行这些步骤，而不只是抽查一个
与试图在脚本中用固定断言判断正确性相比，这种方式更准确，也更灵活。成功的退出码固然有用，但对于调用真实 API、使用工具或生成结构化输出的示例，仅凭退出码还不够。先记录实际输出，再对照源代码仔细检查，就能根据每个示例的实际意图进行验证。
JavaScript 代码仓库中还有第二层：独立的 integration-tests 技能。这项工作流不局限于直接在代码仓库中运行源代码示例。它会将软件包发布到本地 Verdaccio 注册表，并在多个环境中测试安装和运行，包括 Node.js、Bun、Deno、Cloudflare Workers 和 Vite React 应用。它能发现另一类问题：关注的不是“示例能否在代码仓库中运行”，而是“软件包经过发布、安装和运行时集成后，行为是否仍然正确”。
综合来看，这些工作流说明了将技能、脚本与模型判断相结合的价值。脚本让运行过程可重复，记录验证依据，并覆盖那些手动检查起来很繁琐的安装流程。随后，Codex 利用这些依据进行细致比较，比简单地用脚本判断通过或失败更为深入。
添加发布检查
发布准备是这种模式发挥作用的另一个领域。
两个代码仓库的发布审查工作流都会先找到上一个版本的发布标签，将其与最新的 main 比较，然后让 Codex 检查差异中是否存在以下问题：
- 公共 API 和面向用户的 SDK 行为中的向后兼容性问题
- 回归问题，包括预期行为的细微变化
- 需要迁移说明或发布说明更新的变更缺少相应说明
技能会根据这些发现，综合判断是否已做好发布准备。
openai/openai-agents-python#2480 就是一个具体示例：发布审查总体通过，但仍指出了停止支持 Python 3.9 的变更，以及需要为此补充的发布说明：
Release readiness review (excerpt)
Release call:
🟢 GREEN LIGHT TO SHIP. Minor-version bump includes expected breaking change
(Python 3.9 drop) with no concrete regressions found.
Scope summary:
- 38 files changed (+1450/-789); key areas touched: `src/agents/tool.py`,
`src/agents/extensions/`, `src/agents/realtime/`, `tests/`,
`pyproject.toml`, `uv.lock`.
Python 3.9 support removed
- Risk: 🟡 MODERATE. Users pinned to Python 3.9 will be unable to install the
0.9.0 release.
- Evidence: `pyproject.toml` now sets `requires-python = ">=3.10"` and drops
the Python 3.9 classifier; CI skip logic for 3.9 was removed.
- Action: Ensure release notes clearly call out the Python 3.9 drop and that
packaging metadata remains `>=3.10`.技能还定义了如何决定是否允许发布。审查以“可以安全发布”为初始判断，只有在差异中发现确实存在问题的具体证据时，才会改为阻止发布。每次判定阻止发布时，都必须附上解除阻碍所需完成的具体检查清单。这样的输出更便于使用：通过意味着在差异中未发现阻碍发布的问题；阻止发布则意味着确实存在问题，并且有明确的后续处理步骤。
这比泛泛地说“请审查此次发布”更有用。它要求模型针对具体差异进行推理，并以可操作的方式解释结果。如果可以安全发布，就明确说明；如果不能，就指出确切的证据和所需的后续处理。
在 CI 中运行工作流
当技能在本地发挥作用后，Codex GitHub Action 可以让您轻松地在 CI 中自动运行同一工作流。本地工作流已经稳定时，这样做效果最好，因为手动使用的过程正是您调试指令、完善脚本和发现实际边界情况的机会。
对于公共代码仓库，触发机制的设计与技能本身同样重要。GitHub Action 安全检查清单 建议：限制可以启动工作流的人员，优先采用可信事件或明确审批，对来自 PR、提交、议题或评论的提示输入进行安全过滤，通过 drop-sudo 或非特权用户保护 OPENAI_API_KEY，并将运行 Codex 作为作业的最后一步。
如果工作流具备写入能力，并接收不可信的公开输入，风险通常出在与技能配套的触发机制设计、输入处理和运行时权限上。
在 PR 审查中使用 Codex
技能是这些代码仓库提升生产力的一部分，Codex GitHub PR 自动审查 则是另一部分。
自 Codex GitHub PR 自动审查推出以来，Codex 在这些代码仓库的大多数代码变更中都发挥了有效的审查作用。我们将它作为日常审查的一部分，而不是仅在特殊情况下使用的工具。
对于简单直接的程序错误、回归问题和测试缺失，在实际工作中，将 Codex 作为必经的审查环节如今已足够稳妥。它能始终如一地反复检查同类正确性问题，消除了小修复和日常改进中的一大瓶颈。
同行审查依然重要，只是主要面向另一类变更。
当核心问题不再是“这段代码是否正确？”，而是“几个可行方案中应该选哪一个，又该如何发布？”时，人工审查仍不可或缺。这类情况包括：
- API 或架构变更存在多种合理设计，需要维护者明确做出选择
- 行为变更影响产品预期、向后兼容性承诺或推出策略
- 需要就命名、迁移和发布沟通做出决策，难点在于选择对用户和贡献者最清晰易懂的方案
- 变更需要维护者或团队之间达成共识，例如确定工作范围、安排先后顺序，或决定哪些内容现在发布、哪些留待以后
在所有这些情况下，Codex 仍能提供有价值的帮助，但由人来做决策并直接展开讨论依然有益。
AGENTS.md 也可以明确这种分工：代码仓库可以告诉 Codex，正确性审查应该重点关注什么，而 Codex 则可以始终如一地遵循这些指导。
这也显著提升了工程工作的吞吐量。重复的审查和验证工作不再需要为每项低风险变更等待审查者腾出有限的时间，维护者则可以专注于那些更依赖上下文、最需要他们做出判断的审查。这一转变帮助我们大幅加快了处理积压错误和小幅功能改进的速度。
结语
在 OpenAI Agents SDK 代码仓库中，将技能融入代码仓库的日常工作机制，最能发挥其作用。
AGENTS.md 告诉 Codex 哪些工作流必须执行，description 告诉它何时应进入这些工作流，scripts/ 负责处理确定性的部分，模型负责处理需要结合上下文判断的部分。一旦工作流在本地运行稳定，Codex GitHub Action 就可以将同样的流程带入 CI。
这让这些代码仓库的日常工程工作有了更明确的规范，也变得更加可靠。验证、发布审查和 PR 交接现在都遵循同一套可重复执行的流程，因此也更容易快速交付小幅改进。