我们正在用 Codex 改进 OpenAI Agents SDK 代码仓库的维护方式。通过代码仓库内的技能、AGENTS.md 和 GitHub Actions,我们把验证、发布准备、示例集成测试和 PR 审查等日常工程任务整理成了可重复执行的工作流。即使配置相当简单,这套做法也提高了这两个活跃代码仓库的开发吞吐量。2025 年 9 月 1 日至 11 月 30 日,两个代码仓库共合并了 316 个 PR。随后三个月,即 2025 年 12 月 1 日至 2026 年 2 月 28 日,这一数字增至 457 个,其中 Python 从 182 个增至 226 个,TypeScript 从 134 个增至 231 个。
SDK 提供 Python 和 TypeScript 两个版本。它提供构建智能体应用所需的核心组件,也让开发者可以用简洁的方式基于 Realtime API 构建语音智能体,支持多个智能体协作、调用工具和人工介入。SDK 已得到广泛使用。截至 2026 年 3 月 6 日,在两个包各自最近的 30 天统计周期内,Python 包在 PyPI 上的下载量约为 1,470 万次,TypeScript 包在 npm 上的下载量约为 150 万次。
配置很简单:
- 在
AGENTS.md中写明代码仓库的规则 - 将代码仓库专用的技能放在
.agents/skills/中 - 按需在技能中附上脚本和参考资料
- 需要在 CI 中运行同一工作流时,使用 Codex GitHub Action
这样一来,Codex 就能持续获得有关代码仓库运作方式的上下文,更快、更准确地完成重复性工程任务。
如果您维护公开的开源项目,请参阅 Codex 开源项目支持计划。符合条件的维护者可以申请包含 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 兼容性规则:保持导出的构造函数参数和数据类字段在各个位置上的含义不变,尽可能将新的可选参数或字段追加到末尾,如果确实需要调整顺序,就添加兼容性测试。把影响发布的关键兼容性规则和技能触发条件放在一起,也是值得沿用的做法。
验证规则
以 $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 代码仓库还有一项必做步骤:运行 $changeset-validation。这个技能基于 Changesets。
只要 packages/ 下的任何内容发生变化,或 .changeset/ 有改动,模型除了运行测试,还必须创建或更新相应的变更集,验证版本升级级别,并确认变更集与实际改动一致。
这个技能不只检查文件是否存在,还要求 Codex 分析 Git 差异。验证规则写在一份共享提示词中,因此本地运行和 GitHub Actions 使用相同的逻辑。技能中还写明了代码仓库专用规则,例如:
- 如果当前分支已有变更集,就复用它,避免重复创建
- 按约定式提交的风格将摘要写成一行,以便同时用作提交标题
- 在 1.0 版本之前,常规功能改动应避免升级主版本号。明确标为仅供预览的新增功能,如果不改变现有行为,则按补丁级改动处理
- 对照包的实际改动,验证所需的版本升级级别
这样,Codex 必须先验证自己创建的发布元数据,才能宣布工作完成。
使用最新文档
两个代码仓库都要求使用 $openai-knowledge 来处理涉及 OpenAI API 或平台集成的任务。
这个技能对官方 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 就成了顺理成章的最后一步。这样可以统一交接格式,也省去了编码完成后的重复撰写工作。
写清楚技能描述
技能的 description 字段位于 SKILL.md 的文件头元数据中,也是决定何时选用该技能的依据。
这关系到技能的运行机制,而不只是写作风格。智能体技能规范规定,name 和 description 是 SKILL.md 文件头的必填字段。按照规范的渐进披露机制,启动时会加载所有技能的这两个字段。只有当某个技能真正启用后,才会加载完整的 SKILL.md 正文,以及相应的 scripts/、references/ 或 assets/。
在 Codex 技能文档和自定义文档中,同一机制体现为:Codex 首先通过各个技能的元数据发现可用技能,选中某个技能后才加载其 SKILL.md,并且只在需要时读取参考资料或运行脚本。OpenAI API Cookbook 中的技能指南也明确说明了托管式 Shell 中的行为:OpenAI 先读取各个技能的 name、description 和路径,模型再据此决定何时读取完整的 SKILL.md。其中的 SKILL.md 文件头元数据一节说得更直接:name 和 description 是发现和选择技能的重要依据。
因此,在 Agents SDK 代码仓库中,description 是 Codex 选择技能的主要依据之一,此时它还没有读取技能的其余内容。
以 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 的内容,除了文字摘要,还包含 PR 草稿
我们从这两个代码仓库中得到的一条经验是,值得花时间写好 description。如果 Codex 经常在不合适的时候选用技能,先改进元数据,再考虑添加代码。
将固定操作写成脚本
接下来要决定哪些工作交给模型,哪些适合写进脚本。
一种可靠的分工方式是:
- 由模型负责解读、比较和报告
- 将结果确定、需要重复执行的 shell 操作放进
scripts/
这也符合公开文档的指导。Codex 自定义文档指出,技能可以为可重复执行的工作流提供更详细的指令、脚本和参考资料,又无需在一开始就占用大量上下文。这适合由模型主导的工作方式:让 Codex 处理依赖上下文的部分,在需要时再调用脚本完成确定性操作。OpenAI API Cookbook 中的技能指南还建议将技能脚本设计成小型 CLI:从命令行运行,向标准输出写入确定的结果,失败时明确提示用法或错误原因,必要时将输出写到预先约定的文件路径。
在 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,分别记录每个示例的日志,并支持重跑。
为了提高验证质量,运行器负责执行示例,并将标准输出和标准错误保存在对应示例的日志中。技能随后要求 Codex 逐一查看日志,对照源代码检查:
- 阅读示例的源代码和注释
- 推断预期执行流程
- 打开对应的日志
- 将预期行为与实际的标准输出和标准错误进行比较
- 对每个成功运行的示例都执行上述检查,不能只抽查一个
与在脚本中写死用于判定正确性的断言相比,这种方式更准确,也更灵活。成功退出的状态码是有用的信息,但对于会调用真实 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、提交、议题或评论的提示词输入,保护好 OPENAI_API_KEY(使用 drop-sudo 或以无特权用户身份运行),并将运行 Codex 放在作业的最后一步。
如果工作流具有写入权限,同时又接受不受信任的公开输入,风险通常来自技能的触发条件、输入处理方式和运行时权限。
在 PR 审查中使用 Codex
技能是提高这两个代码仓库开发效率的一种方式,Codex 对 GitHub PR 的自动审查是另一种。
自从 Codex 支持自动审查 GitHub PR 以来,它一直在这两个代码仓库的大多数代码改动中发挥审查作用。我们已将它纳入常规审查流程。
对于容易判断的程序错误、回归问题和遗漏的测试,根据我们的实践,把 Codex 审查作为必经步骤已经足够可靠。它能反复按一致的标准检查同类正确性问题,让小修复和日常改进少了一道主要瓶颈。
另一类改动仍然需要同行审查。
当核心问题从“这段代码是否正确”转为“几个可行方案中应该选哪个,又该如何发布”时,人工审查仍然不可或缺。例如:
- API 或架构改动有多种合理设计,需要维护者明确选择
- 行为改动会影响用户对产品的预期、向后兼容承诺或上线策略
- 决定如何命名、迁移或传达发布信息时,难点在于判断哪种做法最便于用户和贡献者理解
- 改动需要维护者或团队之间达成一致,例如确定工作范围、安排先后顺序,或决定哪些内容现在发布、哪些留到以后
在这些情况下,Codex 仍然能提供有价值的意见,但直接讨论并由人来决策仍然很有帮助。
AGENTS.md 也可以写明这种分工:代码仓库可以告诉 Codex 在正确性审查中应重点关注什么,Codex 则可以始终按这套指导执行。
这种分工也显著提高了开发吞吐量。对于低风险改动,重复的审查和验证不再需要每次都等待审查者腾出时间,维护者也能专注于需要了解更多背景、更依赖人工判断的审查。这让我们能更快地修复积压的缺陷,完成较小的功能改进。
结语
在 OpenAI Agents SDK 代码仓库中,把技能纳入日常开发流程,最能发挥它们的作用。
AGENTS.md 告诉 Codex 哪些工作流必须执行。description 说明何时选用这些工作流。scripts/ 负责结果确定的步骤,模型负责需要结合上下文判断的部分。工作流在本地稳定运行后,就可以通过 Codex GitHub Action 将同一流程用于 CI。
这样一来,两个代码仓库的日常工程任务有了更明确、更可靠的执行方式。验证、发布审查和 PR 交接都有了可重复执行的流程,我们也能更快地发布小改进。