利用技能加速开源软件维护
我们使用 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 是报告优先的工作流：它们检查当前的差异或覆盖率工件，优先处理重要的内容，并在进行编辑之前请求批准。在 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/ 发生变化时，模型必须做的不仅仅是运行测试。它必须创建或更新正确的变更集、验证版本号提升级别，并确认变更集确实与差异匹配。
该技能做的远不止检查文件是否存在。它要求 Codex 判断 git 差异，并将验证规则保存在共享提示中，以便本地运行和 GitHub Actions 使用相同的逻辑。它还编码了仓库特定的策略，例如：
- 当已存在分支变更集时，使用现有的而不是创建另一个
- 将摘要保持为符合 Conventional Commit 风格的单行，以便它能兼作提交标题
- 在 1.0 之前，避免对常规功能工作进行主版本号提升，并将明确标记为仅预览的新增内容视为补丁变更，前提是它们不改变现有行为
- 根据实际的包变更验证所需的提升级别
这使得 Codex 必须在声称工作完成之前，验证它自己创建的发布元数据。
使用最新文档
两个仓库还要求在工作涉及 OpenAI API 或平台集成时使用 $openai-knowledge。
该技能是官方 OpenAI Docs MCP 的一个薄封装。它不让模型凭记忆回答，而是告诉 Codex 使用 OpenAI 开发者文档 MCP 服务器来查找 Responses API、工具、流式传输、Realtime 和 MCP 等领域的最新文档。
如果本地 Codex 环境中尚未配置 MCP 服务器，该技能会指引维护者前往 Docs 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 字段是路由契约的一部分。
这是结构性的，而非风格性的。Agent Skills 规范 将 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 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 中的技能还建议将技能脚本设计成微型 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 交接现在都遵循相同的可重复流程。