OpenAI 用 Codex skills 加速 Agents SDK 开源仓库维护

我们使用 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 运行所需的格式化、lint、类型检查和测试栈。
docs-sync 对照代码库审计文档，找出缺失、错误或过时的文档。
examples-auto-run 以自动模式运行示例，并带有日志和重跑辅助工具。
final-release-review 将上一个发布标签与当前候选版本进行比较，并检查发布就绪情况。
implementation-strategy 在编辑运行时或 API 变更之前，决定兼容性边界和实现方法。
openai-knowledge 通过官方 Docs MCP 工作流拉取当前的 OpenAI API 和平台文档。
pr-draft-summary 在交接时准备分支名称建议、PR 标题和草稿描述。
test-coverage-improver 运行覆盖率，找出最大的缺口，并提出高影响力的测试。

JavaScript 仓库遵循相同的一般模式，然后为其 npm monorepo 和发布流程添加了一些仓库特定的技能：

changeset-validation 检查 changesets 和版本提升级别是否与包差异实际匹配。
integration-tests 将包发布到本地 Verdaccio 注册表，并验证在受支持的运行时中的安装和运行行为。
pnpm-upgrade 以协调的方式更新 pnpm 工具链和 CI 固定版本。

比具体列表更重要的是模式。每个技能都有狭窄的契约、明确的触发条件和具体的输出。

一些最有用的技能并不是硬性关卡。docs-sync 和 test-coverage-improver 是报告优先的工作流：它们检查当前 diff 或覆盖率产物，对重要事项进行优先级排序，并在进行编辑前请求批准。在 Python 仓库中，docs-sync 还将源文档字符串和注释视为生成参考文档的事实来源，而不是手动修补生成的输出。仅限 JavaScript 的 pnpm-upgrade 技能是另一个狭窄维护工作流的好例子：它一起更新本地 pnpm 版本、packageManager 和工作流固定版本，而不是退回到大范围的搜索替换。

让工作流成为强制要求

当仓库在正确的时间要求使用技能时，技能会变得更有用。这就是 AGENTS.md 的用武之地。

AGENTS.md 指南将这些文件描述为随代码库一起移动、并在代理开始工作前应用的仓库级指令。它还建议保持它们精简。在 Agents SDK 仓库中，我们利用这一空间来放置 Codex 每次都应遵循的规则，并将最有价值的规则放在靠近顶部的位置。

在实践中，两个仓库都使用简短的 if/then 规则来强制使用技能。在编辑运行时或 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 仓库对包变更多了一个强制步骤：$changeset-validation，它围绕Changesets构建。

当packages/下的任何内容发生变化，或.changeset/发生变化时，模型不能只运行测试。它必须创建或更新正确的变更集，验证版本提升级别，并确认变更集确实与 diff 匹配。

该技能不只是检查文件是否存在。它要求 Codex 判断 git diff，并将验证规则保存在共享提示中，使本地运行和 GitHub Actions 使用相同的逻辑。它还编码了仓库特定的策略，例如：

当已存在变更集时，使用现有分支的变更集，而不是再创建一个
将摘要保持为 Conventional Commit 风格的一行，以便同时用作提交标题
在 1.0 之前，避免为常规功能工作做 major 版本提升，并将明确标记为仅预览的新增内容视为 patch 变更（如果它们不改变现有行为）
根据实际的包变更验证所需的版本提升级别

这使得 Codex 在声称工作完成之前，负责验证它创建的发布元数据。

使用最新文档

当工作涉及 OpenAI API 或平台集成时，两个仓库还要求使用$openai-knowledge。

该技能是官方OpenAI Docs MCP的轻量封装。它不让模型凭记忆回答，而是告诉 Codex 使用 OpenAI Developer Documentation MCP 服务器来查找 Responses API、工具、流式传输、Realtime 和 MCP 等界面的最新文档。

如果本地 Codex 环境中尚未配置 MCP 服务器，该技能会指引维护者查看Docs MCP 快速入门和官方 MCP 服务器端点。

准备 PR 交接

在实质性工作结束时，两个仓库都使用$pr-draft-summary。

该技能仅在任务实际完成或准备好审查，且变更涉及有意义的代码、测试、示例、影响行为的文档或构建/测试配置时触发。然后它会自动收集分支名称、工作树状态、更改的文件、diff 统计信息和最近的提交，并生成：

分支名称建议
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 frontmatter 中的description字段是路由契约的一部分。

这是结构性的，而非风格性的。Agent Skills 规范将name和description设为必需的SKILL.md frontmatter 字段，其渐进式披露模型表明，这些字段是在启动时为所有技能加载的内容。完整的SKILL.md正文以及任何scripts/、references/或assets/仅在稍后技能实际激活时才加载。

Codex skills 文档和自定义文档从 Codex 一侧描述了相同的行为：Codex 首先使用每个技能的元数据进行发现，只有在选择该技能时才加载 SKILL.md，并且仅在需要时读取引用或运行脚本。OpenAI API cookbook 中的 Skills同样明确地描述了托管 shell 一侧：OpenAI 首先读取每个技能的 name、description 和路径，模型利用这些信息来决定何时读取完整的 SKILL.md。其SKILL.md frontmatter 部分更直接地表达了同样的观点：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 的块，而不仅仅是散文式总结

从这些仓库中得到的一个实用经验是花时间在 description 上。如果路由感觉不可靠，先修复元数据，再添加更多代码。

把机制放进脚本

之后，下一个问题是什么应该属于模型，什么应该下推到脚本中。

一个可靠的划分是：

解释、比较和报告留给模型
确定性的、重复的 shell 工作放进 scripts/

这与公开指南一致。Codex 自定义文档将技能描述为一种为 Codex 提供更丰富指令、脚本和引用以支持可重复工作流的方式，而不会在一开始就膨胀上下文。这符合模型优先的设置：让 Codex 处理工作中依赖上下文的部分，仅在需要时引入脚本处理确定性部分。OpenAI API cookbook 中的 Skills还建议将技能脚本设计成小型 CLI：从命令行运行、打印确定性的 stdout、在使用或出错时大声失败，并在需要时将输出写入已知文件路径。

在 Agents SDK 仓库中，我们尝试在模型的智能真正有用的地方使用模型，例如：

阅读源代码以推断预期行为
将日志与该预期行为进行比较
判断发布差异是否包含真正的兼容性风险
生成维护者可以据此采取行动的解释

然后脚本处理围绕该工作的机制，例如：

按固定顺序运行仓库所需的验证命令
启动示例运行、收集每个示例的日志，并为失败写入重跑文件
在发布就绪审查之前获取上一个发布标签
暴露辅助命令，例如 start、stop、status、logs、tail、collect 和 rerun，以便同一工作流易于重复运行

如果模型每次都必须重新发现相同的 shell 配方，这通常表明该配方应该是一个脚本。如果任务依赖于上下文、权衡或解释，那部分应该留给模型。

自动化集成测试

这两个仓库中最有用的工作流领域之一是自动化集成测试。这里有两个相关的层次：在两个仓库中自动验证仓库内示例，以及在 JavaScript 仓库中单独验证已发布的包在用户安装方式下是否仍然可用。

在这套设置之前，验证示例部分是手动完成的。你可以运行示例，但最后一公里往往依赖于目视检查日志，或者靠人工判断输出看起来是否正确。对于一个示例来说这还可以应付。但在一个不断增长的 SDK 仓库中，这种方式难以扩展。

第一层是 examples-auto-run，但技能是在运行器之后才出现的。要实现示例验证的自动化，我们首先必须在两个仓库中构建非交互式示例执行的基础支持。这意味着要能够以自动模式运行示例脚本，包括那些通常涉及提示或审批的示例。

这些基础工作包括：

自动回答常见的交互式提示
在运行器支持的情况下，自动批准 HITL、MCP、apply_patch 和 shell 操作
将仍不适合自动化的示例保留在自动跳过列表中，例如需要额外运行时设置的 realtime 或 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 进行 diff，然后让 Codex 检查该 diff 中是否存在：

公共 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`.

该技能还定义了门禁决策是如何做出的。审查从“可以安全发布”开始，只有当 diff 显示出真实问题的具体证据时，才会切换为阻止发布的结论。每个阻止发布的结论都必须附带一份具体的解除阻止清单。这使得输出更易于使用：绿灯结果意味着在 diff 中未发现阻止发布的问题，而阻止结果意味着存在真实问题且有明确的下一步。

这比泛泛的“请审查发布”更有用。它迫使模型基于具体的 diff 进行推理，并以可操作的方式解释结果。如果发布是安全的，就说明是安全的。如果不安全，就指出确切的证据和所需的确切后续跟进。

在 CI 中运行工作流

一旦某个技能在本地变得有用，Codex GitHub Action 就能轻松地在 CI 中自动化相同的工作流。当本地工作流已经稳定时，效果最好，因为手动使用正是你调试指令、完善脚本和发现真实边界情况的地方。

对于公共仓库，触发设计与技能本身同样重要。GitHub Action 安全清单建议限制谁可以启动工作流，优先使用受信任的事件或显式批准，清理来自 PR、提交、issue 或评论的提示输入，使用 drop-sudo 或非特权用户保护 OPENAI_API_KEY，并将 Codex 作为作业的最后一步运行。

如果工作流具有写入能力并接受不受信任的公共输入，风险通常在于触发设计、输入处理以及技能周围的运行时权限。

在 PR 审查中使用 Codex

技能只是这些仓库中生产力故事的一部分。Codex GitHub PR 自动审查是另一部分。

自从 Codex GitHub PR 自动审查可用以来，Codex 已成为这些仓库中大多数代码变更的有用审查者。我们将其作为审查的常规部分，而不是特殊情况的工具。

对于直接的程序错误、回归问题和缺失的测试，将 Codex 作为必需的审查路径在实践中已经足够安全。它能一致地反复检查相同的正确性模式，并且消除了小型修复和常规改进的主要瓶颈。

同行审查仍然重要，但针对的是另一类变更。

当主要问题不是“这段代码正确吗？”而是“在几个有效选项中我们应该选择哪一个，以及应该如何发布？”时，人工审查仍然至关重要。这包括：

API 或架构变更，存在多种合理设计，维护者需要做出明确选择
影响产品预期、向后兼容承诺或发布策略的行为变更
命名、迁移和发布沟通决策，其中困难的部分是选择对用户和贡献者最清晰的做法
需要维护者或团队之间协调一致的变更，例如界定工作范围、安排顺序，或决定哪些应该现在发布、哪些应该稍后发布

在这些情况下，Codex 仍然可以做出有用的贡献，但它们仍然受益于人类决策者和直接讨论。

AGENTS.md 也可以编码这种区分：仓库可以告诉 Codex 什么算作正确性审查中的重要内容，而 Codex 可以一致地应用这一指导。

这也是吞吐量的一个重要贡献因素。重复性的审查和验证工作不再需要为每一个低风险变更等待稀缺的审查者时间，而维护者可以专注于更高上下文的审查，在那里他们的判断最为重要。这种转变帮助我们更快地处理积压的 bug 和较小的功能改进。

最终思考

在 OpenAI Agents SDK 仓库中，当技能成为仓库正常工作设置的一部分时，它们的效果最好。

AGENTS.md 告诉 Codex 哪些工作流是必需的。description 告诉它何时路由到这些工作流。scripts/ 处理确定性部分。模型处理上下文部分。而且一旦某个工作流在本地稳定下来，Codex GitHub Action 就可以将同样的流程带入 CI。

这使得这些仓库中的日常工程工作更加明确、更加可靠。它也使得更快地交付小改进变得更容易，因为验证、发布审查和 PR 交接现在都遵循同样的可重复流程。