openai-agents-python 贡献者指南：多智能体 SDK 的仓库工程规范、强制技能工作流与代码审查体系

openai-agents-python 贡献者指南：多智能体 SDK 的仓库工程规范、强制技能工作流与代码审查体系

【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python

本指南以仓库根目录 CLAUDE.md 为核心，系统梳理 OpenAI Agents Python SDK 仓库的贡献规范、强制性技能（skills）工作流、代码审查规则与日常操作流程。作为多智能体工作流框架的官方贡献入口，读者可以据此理解src/agents/运行时如何演进、如何安全地修改公共 API 与持久化契约、如何通过.agents/skills/与.agents/references/完成从实现、审查、验证到发布的全流程，并掌握Makefile、tests/README.md、PLANS.md等仓库级工具的正确用法。

仓库全景：一个 SDK、三套资产、一套运行时契约

OpenAI Agents Python 仓库不仅包含 Python Agents SDK 的核心实现，还同时承载示例与 MkDocs 文档站点。从仓库结构看（详见 CLAUDE.md），它由三大部分构成：

• src/agents/：核心库实现，是仓库的技术主体。运行时入口为src/agents/run.py（Runner、AgentRunner），新增运行时逻辑应放入src/agents/run_internal/并在run.py中仅保留编排与组合的"接线"代码。
• tests/：测试套件，快照（snapshot）相关指引见 tests/README.md。
• examples/：展示 SDK 用法的示例项目；docs/是 MkDocs 文档源，其中docs/ja、docs/ko、docs/zh为翻译生成产物，不应直接编辑。

配套的工程资产还包括：

• mkdocs.yml：文档站点配置；
• Makefile：常用开发命令（sync、lint、typecheck、tests、build-docs 等）；
• pyproject.toml 与 uv.lock：Python 依赖与工具配置；
• .github/PULL_REQUEST_TEMPLATE/pull_request_template.md：开 PR 时必须使用的模板；
• .agents/skills/：仓库技能（skill）集合，贡献者工作流的强制性入口；
• .agents/references/：SDK 维护者长期有效的架构参考文档，从 参考地图 进入，按受影响的运行时边界只打开相关文件；
• site/：构建后的文档输出目录。

仓库要求所有 Python 命令统一使用uv run python ...，以保证环境一致。

强制技能工作流：贡献的每一步都有明确路由

仓库将贡献流程拆分为一系列存放于.agents/skills/下的技能文件。当对应条件成立时，技能即被授权使用，无需单独手动调用；使用时先读取所选SKILL.md，再按需读取其路由所需的支持引用。用户指令与已批准的范围内优先级高于技能默认值，且已给出的本地实现、审查或验证批准无需重复申请。

当前仓库共包含 15 个技能目录，覆盖实现、审查、验证与发布全链路：

技能触发"停止"时，必须指出具体指令并说明缺失的决策，不得索要笼统的"继续"提示；同时严禁 push、开 PR 或以其他方式变更远端仓库。

工作状态汇报：RUNNING / COMPLETE / NEEDS_DECISION

贡献者与代码助手在汇报状态时必须使用三种固定标记：

• RUNNING：仅在注释中、自主工作仍在进行且无需用户操作时使用；不得以"任务仍在运行"的最终回复结束回合。
• COMPLETE：仅在请求的工作以及所有适用的审查、验证与本地交接步骤均完成时，在最终回复中使用。
• NEEDS_DECISION：仅在进展需要用户做出具体选择、扩展授权或存在未解决的外部条件时使用，并须陈述确切决策或条件，而不是让用户说"继续"。

Git Worktree 与分支安全

默认在用户当前 checkout 与当前分支上工作；若 Codex 任务已在选定的 Git worktree 中运行，直接使用该 worktree 而无需额外许可。不得创建或切换 Git worktree，也不得创建或切换分支，除非用户在本次会话中明确请求或批准了该操作——请求实现、调查、审查、测试或验证变更本身并不授权更改活动的 worktree 或分支。需要隔离或不同 checkout 时，先解释原因并征得用户同意，即使其他规则或工作流推荐关联 worktree，也应停下来请求批准，而非自动选择或创建。

文档发布时机：行为未发布前，文档不随功能 PR 走

当功能或缺陷修复引入的行为尚未在最新发布版本中可用时，不要在功能或缺陷修复 PR 中包含描述该未发布行为的docs/变更，也不要将其作为该 PR 的期望交付物。这类文档应放入独立的 docs-only PR，由维护者协调其合并时机与发布节奏，确保文档始终对最新发布版本准确。此例外仅适用于文档会对最新发布版本产生错误的情况；对已发布行为本就准确的文档仍属于正常变更范围。判断是否需要文档，与决定由哪个 PR 携带文档，是两个独立的问题。

文档验证分级：Editorial / Content / Structural

提交文档变更前，先对 diff 分类，使用覆盖完整 diff 的最窄等级，任一文件或声明需要更高等级时整体升级：

• Editorial（编辑级）：术语、拼写、标点、格式或链接标签变更，不改变文档行为、可运行代码、导航、链接目标、锚点或生成的引用内容。检查 diff、对修正文本做定向搜索并运行git diff --check；仅在编辑可能影响链接/锚点时直接检查之。此等级可跳过implementation-final-review、跨语言审查与make build-docs。
• Content（内容级）：新增或实质重写的行为指导、迁移说明或可运行片段，不改变文档结构或工具链。需对照实现与权威来源核实声明，尽量执行或验证变更片段，做要求的聚焦跨语言审查，并在内容与审查稳定后运行一次make build-docs。
• Structural（结构级）：新增、删除、重命名或移动页面，或修改mkdocs.yml、生成式 API 引用输入、文档脚本、插件或构建配置。需在结构稳定后运行相关生成器/聚焦工具检查与make build-docs；变更文件属于该技能覆盖的构建或测试配置时应用code-change-verification。

文档构建成功时已存在的警告不算无关文档变更的发现项；应评估退出状态并识别 diff 引起的新错误、失效引用或警告，而不是逐行审查整个警告流。make build-full-docs与生成式翻译输出仅保留给翻译工具链变更、明确的本地化工作或被明确要求的广泛本地化审计。

范围纪律与复杂度重置

实现最小的受支持行为，复用现有真源（source of truth）；每个新抽象、状态字段、兼容分支或测试排列都需要需求、已发布契约、持久边界或经核实风险的支撑。仅凭"可构造性"和"已发布版本可复现"不足以确立支持。

当相关发现反复扩大同一设计时，停止叠加条件，归并根因并对照原始需求重新评估完整 diff。第二个把另一兼容场景或协议跳数加入同一抽象的相关发现即触发重置：优先删除不受支持的分支局部机制，或用现有替代方案拒绝不支持的输入。详细重置流程遵循implementation-strategy，同时保留已发布契约与无关的用户变更。

ExecPlans：多步骤工作的活文档

当工作多步骤、横跨多文件、涉及新功能或重构、或预计超过约一小时时，应使用 ExecPlan。模板与规则定义在 PLANS.md：

• 何时使用：多步骤/多文件工作、新功能、重构或预计超过一小时的必需；简单修复可选，但跳过重大任务时须在回复中说明理由。
• 必备要素：自包含且面向新手（定义每个术语、包含所需仓库知识）；持续更新的活文档（Progress、Surprises & Discoveries、Decision Log、Outcomes & Retrospective 四节必须存在并随执行更新）；以结果为导向（描述用户变更后能做什么、如何看到效果）；明确验收（给出可证明成功的命令与可观察输出）。
• 格式化：默认用单个md代码围栏包裹，内部不得嵌套其他三重反引号；无其他内容时省略围栏。
• 里程碑：每个里程碑按"目标→工作→结果→证明"叙事，可独立验证且递进推进；范围漂移时重写受影响章节保持自洽。

公共 API 兼容性：参数顺序即契约

导出运行时 API 的参数顺序与 dataclass 字段顺序被视为兼容性契约：

• 对公共构造函数（例如RunConfig、FunctionTool、AgentHookContext），保留既有位置参数语义；不得在既有公共顺序中间插入新构造参数或 dataclass 字段。
• 新增可选公共字段/参数时尽可能追加到末尾，并保持旧字段顺序不变。
• 若重排不可避免，须增加显式兼容层与回归测试，覆盖旧位置调用模式。
• 调用点优先使用关键字参数以降低意外破坏，但不能以此为由破坏公共 API 的位置兼容性。
• 预期的导入路径与__all__成员同样构成兼容契约：新增或移动公共符号时，更新属主模块、预期的顶层或子包再导出及导入回归测试；保持顶层导入不依赖可选依赖且无运行时副作用，必要时使用惰性导出。

平台、文档与安全审查要点

• 翻译安全英文：docs/下新增或实质重写的可翻译散文（排除生成的 API 引用页）中，凡影响含义的参与者、范围、属主、顺序、模态与生命周期边界必须显式陈述；使用精确 API 标识符，并在小段澄清即可避免重大翻译偏差时替换模糊代词与重载名词。变更仅限已变更英文句子的轻量跨语言审查（从日语、韩语、中文翻译视角），解决具体风险后复核一次修订行；不得为常规文档变更生成完整本地化页面。翻译工具或控制变更、明确本地化工作或明确请求的广泛翻译审计，才使用 docs/scripts/translate_docs.py 的完整模式与日韩中输出复核。
• 可运行片段即 API 兼容检查：添加 OpenAI API、provider、Responses、Realtime、WebSocket 或 SDK 构造函数示例前，须对照实际实现核实参数与调用形态；examples/或可运行文档片段中的装饰器一律从agents.decorators导入，优先tool而非function_tool。
• 沙箱与安全授权：不得让不受信任的沙箱 manifest 自行退出宿主机文件系统或基目录边界；本地源物化的逃生通道必须由调用点的可信应用代码控制，而非序列化 manifest 数据。记录沙箱/安全授权时须核实实际实现路径确实执行该授权或边界（如LocalDir、LocalFile、归档解压），否则不得声称适用。对 OpenAI/MCP/模型/provider 负载做脱敏时，须考虑 traceback 展示、异常链、__context__、日志与遥测。
• Realtime 追踪：Realtime 追踪相关变更先读 Realtime tracing architecture；Realtime API 服务端追踪与 Agents SDK 客户端追踪相互独立，group_id只用于关联而不会建立共享追踪层级。

代码审查规则

• 发现阈值与受支持范围：仅当变更代码在受支持路径上导致具体的不正确行为时才报告运行时缺陷，并给出触发场景与对调用方可见的后果；无法确立后果时不提发现。新抽象、状态、校验、兼容处理、回退行为、依赖或并行路径，仅当与任务、已发布契约、受支持持久状态或经核实的运行时/平台风险不对应时才视为可操作。
• 禁止重复客户端校验：对公共类型契约已排除或上游 provider 已权威拒绝的值，不做重复的客户端运行时校验；仅当延迟拒绝会在权威拒绝前造成 SDK 自有的具体问题（如不可逆副作用、持久损坏、安全/隐私暴露、可避免的计费、重复资源消耗或过迟过晦涩的错误）时才增加快速失败校验。仅"安全标签"不足以构成发现，须有从攻击者可控输入经真实信任边界到受保护结果的完整链路。
• 契约与生命周期覆盖：对每个新增或修改的公共字段、配置值、事件、序列化值或线值，检查所有受支持的构造、转发、适配与消费路径；对跨越await、回调、重试、重连、取消、清理或回滚边界的共享状态变更，检查存续工作是否会被覆盖/回退/丢弃，并报告具体交错与缺失的属主/代际/身份/事务/重验证/串行化不变量。
• 测试与文档证据：测试只有在其行使控制可观察结果的最高稳定调用方可见边界、且期望值源自需求/已发布行为/工作示例/基线等独立基准时才作为契约证据；不接受仅辅助调用形态的断言或按实现自身逻辑重算的期望值。仅当补丁使既有指引实质性错误/不安全/误导、正确使用依赖非显然的迁移/兼容边界/约束/操作警告、或已接受功能实际不可用时，才报告缺失的文档或示例。
• 审查范围：审查应从目标分支 merge base 或兼容性基线（最新发布标签）起的完整 diff，而非仅最新增量修复；发现仅限补丁引入、暴露或恶化的后果，不为顺带读到的无关清理、既有缺陷、可选重构或投机性扩展设障碍。

运行时核心指南：按边界阅读参考文档

仓库把运行时的长期契约沉淀在.agents/references/（共 17 个参考文件，入口见 参考地图）。修改对应边界前必须阅读属主参考：

• Agent 定义与运行上下文（agent-definition-and-run-context.md）：Agent 字段、克隆、动态指令、启用的工具或 handoff、输出 schema、运行上下文包装器、用量聚合与公共/内部 Agent 身份。
• Runner 生命周期（runner-lifecycle.md）：回合记账、guardrail 排序、handoff、中断、取消、hooks 与流式行为，且流式/非流式路径须行为对齐。
• Run item 生命周期（run-item-lifecycle.md）：新模型输出、工具调用、审批或 run item 变体，须更新每个适用的处理、事件、重放、持久化、追踪与序列化面。
• 函数与输出 schema（function-and-output-schema.md）：函数工具参数 schema、Annotated/Field元数据、严格 JSON schema 转换与结构化输出。
• 工具身份与路由（tool-identity.md）：工具命名、命名空间、查找、审批、追踪与 call ID，使用 src/agents/_tool_identity.py 的规范辅助函数而非自行添加局部规范化规则。
• 工具执行生命周期（tool-execution-lifecycle.md）：工具规划、审批排序、工具 guardrail、并发、取消、超时、hooks 与失败转换。
• 本地 MCP 服务器生命周期（local-mcp-server-lifecycle.md）：MCPServerManager、请求串行化、工具缓存/过滤、传输重试、取消与清理。
• 追踪生命周期（tracing-lifecycle.md）：trace/span 上下文、处理器、导出、flush、shutdown、恢复与敏感数据。
• Realtime / Voice / 会话 / 模型 / 沙箱边界：分别对应 realtime-session-lifecycle.md、voice-pipeline-lifecycle.md、conversation-state-ownership.md、session-persistence.md、model-provider-boundaries.md、runstate-schema.md 与 sandbox-runtime-boundary.md。
• RunState 序列化：若序列化RunState形状变化，必须遵循其 schema 版本的发布边界、向后读取与回归测试规则。

操作指南：从环境准备到最终验证

前置条件

• Python 3.10+；
• 安装uv（依赖管理用uv sync，Python 命令用uv run）；
• 可用make执行仓库任务。

开发工作流

除非显式授权，否则留在当前 checkout 与分支。全新 checkout 或依赖变更后用make sync（对应uv sync --all-extras --all-packages --group dev）安装依赖；实现请求的行为、添加有意义的回归覆盖，并按上述技能流程走完最终交接。仅在被授权时提交，提交信息简短、使用祈使语气，偏好小而聚焦的提交。

测试与自动化检查

• 提供者无关的 Agent 工作流测试优先使用agents.testing的ScriptedModel，Realtime 会话测试用agents.realtime.testing的ScriptedRealtimeModel，Voice 管线测试用agents.voice.testing的脚本化工具，确定性 Sandbox 调用用agents.testing的scripted_sandbox_session()。仅在测试确实需要 provider 线转换、畸形流、受控挂起/并发或脚本化工具无法保留的精确取消/生命周期边界时才保留专用测试替身，并在测试中说明该边界。
• make tests先以 pytest-xdist 最多 9 个 worker 运行分片安全套件，再在所有 xdist worker 退出后运行标记serial的测试；可用PYTEST_XDIST_AUTO_NUM_WORKERS覆盖 worker 数与上限。serial标记意味着该测试需要在每个 xdist worker 退出后独占执行（共享外部资源、进程级状态或时序敏感生命周期），并非仅要求单 worker 内有序执行。
• make tests-review会省略review_optional标记的慢速子系统集成/子进程/多进程检查，但这些检查在最终make tests验证中仍为必选项。
• make typecheck并发运行 mypy（检查src）与 pyright（按 pyrightconfig.json 检查src与tests），默认 4 个分析线程，可用PYRIGHT_THREADS覆盖。
• 性能与确定性：优先等待可观察状态转换而非墙钟时间；用事件、确定性假件、即时异常与窄范围 mock 替代真实 sleep/退避；保留活跃、完成、失败、取消与清理覆盖，并在finally块释放阻塞任务与资源；并行测试须分片安全（避免共享可变全局状态、固定可写路径、顺序依赖与未协调的外部资源）。
• 快照测试使用 inline-snapshots：tests/README.md 中的make snapshots-fix与make snapshots-create可分别修复与创建快照，完成后重新运行make tests。
• 文档类命令集中在 Makefile：make build-docs（先跑 docs/scripts/generate_ref_files.py 再mkdocs build）、make build-full-docs（含翻译生成）、make serve-docs、make deploy-docs。
• 发布兼容性相关：make update-released-api-contract VERSION=<版本>冻结最新发布契约至 tests/fixtures/released_api_contract.json，make check-released-api-contract VERSION=<版本>检查漂移；prepare-prospective-released-api-contract/check-prospective-released-api-contract用于发布前前瞻校验。

GitHub-ready 输出

对发布就绪报告及要求粘贴进 GitHub 的文本（评论、审查、PR 描述、发布说明），在单个 Markdown 围栏代码块中交付完整可复制产物（外栏长于产物内任何围栏），保证复制动作保留字面 Markdown；不使用 Codex 专属 URI、UI 指令、引用标记或嵌套/双重转义链接标记；不包含绝对本地文件系统路径，文件证据用仓库相对路径的 inline code；同一仓库的 issue/PR 引用使用原生形式（本仓库#123，其他仓库owner/repo#123），切勿包装成 Markdown 链接。

PR 与提交指南

• 使用 .github/PULL_REQUEST_TEMPLATE/pull_request_template.md：包含 Summary、Test plan、Issue number 与 Checks 复选框（新增测试、运行code-change-verification脚本、确认验证通过、Codex 提交前运行/review）。
• 为已接受的新行为添加聚焦回归测试；仅当变更会使既有指引实质性错误/不安全/误导、正确使用依赖非显然的约束/迁移/兼容边界/操作警告或功能实际不可用时才更新文档或示例。
• docs/交付时机独立于文档必要性单独决定（见"文档发布时机"节）。

发布流程

发布标签由授权维护者手动创建，合并发布 PR 不会自动打标签。流程见 .github/RELEASING.md：记录合并 commit SHA → 核验 commit 与版本（git merge-base --is-ancestor、git show <commit>:pyproject.toml任一失败即停止）→ 在合并 commit 上创建并推送注解标签（标签已存在则停下调查，绝不覆盖/删除/移动既有标签）→ 基于该标签发布 GitHub Release 以触发.github/workflows/publish.yml→ 构建成功后由指定审查者确认标签与 commit 并批准 PyPI 部署（启用 Prevent self-review 时需另一位指定审查者批准）。发布 commit 仅包含pyproject.toml、uv.lock与tests/fixtures/released_api_contract.json。

总结

CLAUDE.md 所定义的贡献体系，其核心思想是把"SDK 演进"当作一组可验证的契约来管理：公共 API 参数顺序、序列化 RunState、文档发布时机、技能触发条件与审查发现阈值都是契约的一部分。实际贡献时，先按 参考地图 定位受影响的运行时边界，用implementation-strategy固化范围契约，迭代期用聚焦测试验证，收尾时按implementation-final-review与code-change-verification完成分级审查与完整 SDK 验证栈，最后以 PR 模板 交付。这一流程保证了多智能体运行时在流式/非流式、同步/异步、直接/包装、初始/恢复等路径上的行为一致性与向后兼容性，也是新贡献者理解仓库最快的地图。

【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python