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.pyRunner、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.lockPython 依赖与工具配置.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 个技能目录覆盖实现、审查、验证与发布全链路技能触发条件与职责implementation-strategy修改或审查 SDK 运行时行为、公共 API、配置、持久化 schema 或线协议前使用记录必要行为、兼容性、不支持场景与现有替代方案implementation-final-review聚焦检查后用于运行时代码、测试、示例、构建/测试行为及影响行为的文档负责普通/高风险分级code-change-verification修改src/agents/、tests/、examples/、共享运行时工具或 SDK 构建/测试配置如 pyproject.toml、Makefile、mkdocs.yml、docs/scripts/、CI 工作流时运行最终 SDK 验证栈openai-knowledge需要 OpenAI API/平台行为的权威外部证据时使用SDK 自身行为应检查本地代码pr-draft-summary审查与验证通过后生成本地 PR 草稿草稿绝不授权创建分支、提交、推送或 PRrelease-candidate-prep仅在显式指定版本号时使用走专用 worktree 工作流与final-release-review门禁其余 9 个docs-sync、examples-run-analysis、final-release-review、implementation-kickoff、maintainer-review、runtime-behavior-probe、sensitive-logging-audit、test-coverage-improver等按各自适用场景使用技能触发停止时必须指出具体指令并说明缺失的决策不得索要笼统的继续提示同时严禁 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 architectureRealtime API 服务端追踪与 Agents SDK 客户端追踪相互独立group_id只用于关联而不会建立共享追踪层级。代码审查规则发现阈值与受支持范围仅当变更代码在受支持路径上导致具体的不正确行为时才报告运行时缺陷并给出触发场景与对调用方可见的后果无法确立后果时不提发现。新抽象、状态、校验、兼容处理、回退行为、依赖或并行路径仅当与任务、已发布契约、受支持持久状态或经核实的运行时/平台风险不对应时才视为可操作。禁止重复客户端校验对公共类型契约已排除或上游 provider 已权威拒绝的值不做重复的客户端运行时校验仅当延迟拒绝会在权威拒绝前造成 SDK 自有的具体问题如不可逆副作用、持久损坏、安全/隐私暴露、可避免的计费、重复资源消耗或过迟过晦涩的错误时才增加快速失败校验。仅安全标签不足以构成发现须有从攻击者可控输入经真实信任边界到受保护结果的完整链路。契约与生命周期覆盖对每个新增或修改的公共字段、配置值、事件、序列化值或线值检查所有受支持的构造、转发、适配与消费路径对跨越await、回调、重试、重连、取消、清理或回滚边界的共享状态变更检查存续工作是否会被覆盖/回退/丢弃并报告具体交错与缺失的属主/代际/身份/事务/重验证/串行化不变量。测试与文档证据测试只有在其行使控制可观察结果的最高稳定调用方可见边界、且期望值源自需求/已发布行为/工作示例/基线等独立基准时才作为契约证据不接受仅辅助调用形态的断言或按实现自身逻辑重算的期望值。仅当补丁使既有指引实质性错误/不安全/误导、正确使用依赖非显然的迁移/兼容边界/约束/操作警告、或已接受功能实际不可用时才报告缺失的文档或示例。审查范围审查应从目标分支 merge base 或兼容性基线最新发布标签起的完整 diff而非仅最新增量修复发现仅限补丁引入、暴露或恶化的后果不为顺带读到的无关清理、既有缺陷、可选重构或投机性扩展设障碍。运行时核心指南按边界阅读参考文档仓库把运行时的长期契约沉淀在.agents/references/共 17 个参考文件入口见 参考地图。修改对应边界前必须阅读属主参考Agent 定义与运行上下文agent-definition-and-run-context.mdAgent 字段、克隆、动态指令、启用的工具或 handoff、输出 schema、运行上下文包装器、用量聚合与公共/内部 Agent 身份。Runner 生命周期runner-lifecycle.md回合记账、guardrail 排序、handoff、中断、取消、hooks 与流式行为且流式/非流式路径须行为对齐。Run item 生命周期run-item-lifecycle.md新模型输出、工具调用、审批或 run item 变体须更新每个适用的处理、事件、重放、持久化、追踪与序列化面。函数与输出 schemafunction-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.mdMCPServerManager、请求串行化、工具缓存/过滤、传输重试、取消与清理。追踪生命周期tracing-lifecycle.mdtrace/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 syncPython 命令用uv run可用make执行仓库任务。开发工作流除非显式授权否则留在当前 checkout 与分支。全新 checkout 或依赖变更后用make sync对应uv sync --all-extras --all-packages --group dev安装依赖实现请求的行为、添加有意义的回归覆盖并按上述技能流程走完最终交接。仅在被授权时提交提交信息简短、使用祈使语气偏好小而聚焦的提交。测试与自动化检查提供者无关的 Agent 工作流测试优先使用agents.testing的ScriptedModelRealtime 会话测试用agents.realtime.testing的ScriptedRealtimeModelVoice 管线测试用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-snapshotstests/README.md 中的make snapshots-fix与make snapshots-create可分别修复与创建快照完成后重新运行make tests。文档类命令集中在 Makefilemake 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.jsonmake 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
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.pyRunner、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.lockPython 依赖与工具配置.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 个技能目录覆盖实现、审查、验证与发布全链路技能触发条件与职责implementation-strategy修改或审查 SDK 运行时行为、公共 API、配置、持久化 schema 或线协议前使用记录必要行为、兼容性、不支持场景与现有替代方案implementation-final-review聚焦检查后用于运行时代码、测试、示例、构建/测试行为及影响行为的文档负责普通/高风险分级code-change-verification修改src/agents/、tests/、examples/、共享运行时工具或 SDK 构建/测试配置如 pyproject.toml、Makefile、mkdocs.yml、docs/scripts/、CI 工作流时运行最终 SDK 验证栈openai-knowledge需要 OpenAI API/平台行为的权威外部证据时使用SDK 自身行为应检查本地代码pr-draft-summary审查与验证通过后生成本地 PR 草稿草稿绝不授权创建分支、提交、推送或 PRrelease-candidate-prep仅在显式指定版本号时使用走专用 worktree 工作流与final-release-review门禁其余 9 个docs-sync、examples-run-analysis、final-release-review、implementation-kickoff、maintainer-review、runtime-behavior-probe、sensitive-logging-audit、test-coverage-improver等按各自适用场景使用技能触发停止时必须指出具体指令并说明缺失的决策不得索要笼统的继续提示同时严禁 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 architectureRealtime API 服务端追踪与 Agents SDK 客户端追踪相互独立group_id只用于关联而不会建立共享追踪层级。代码审查规则发现阈值与受支持范围仅当变更代码在受支持路径上导致具体的不正确行为时才报告运行时缺陷并给出触发场景与对调用方可见的后果无法确立后果时不提发现。新抽象、状态、校验、兼容处理、回退行为、依赖或并行路径仅当与任务、已发布契约、受支持持久状态或经核实的运行时/平台风险不对应时才视为可操作。禁止重复客户端校验对公共类型契约已排除或上游 provider 已权威拒绝的值不做重复的客户端运行时校验仅当延迟拒绝会在权威拒绝前造成 SDK 自有的具体问题如不可逆副作用、持久损坏、安全/隐私暴露、可避免的计费、重复资源消耗或过迟过晦涩的错误时才增加快速失败校验。仅安全标签不足以构成发现须有从攻击者可控输入经真实信任边界到受保护结果的完整链路。契约与生命周期覆盖对每个新增或修改的公共字段、配置值、事件、序列化值或线值检查所有受支持的构造、转发、适配与消费路径对跨越await、回调、重试、重连、取消、清理或回滚边界的共享状态变更检查存续工作是否会被覆盖/回退/丢弃并报告具体交错与缺失的属主/代际/身份/事务/重验证/串行化不变量。测试与文档证据测试只有在其行使控制可观察结果的最高稳定调用方可见边界、且期望值源自需求/已发布行为/工作示例/基线等独立基准时才作为契约证据不接受仅辅助调用形态的断言或按实现自身逻辑重算的期望值。仅当补丁使既有指引实质性错误/不安全/误导、正确使用依赖非显然的迁移/兼容边界/约束/操作警告、或已接受功能实际不可用时才报告缺失的文档或示例。审查范围审查应从目标分支 merge base 或兼容性基线最新发布标签起的完整 diff而非仅最新增量修复发现仅限补丁引入、暴露或恶化的后果不为顺带读到的无关清理、既有缺陷、可选重构或投机性扩展设障碍。运行时核心指南按边界阅读参考文档仓库把运行时的长期契约沉淀在.agents/references/共 17 个参考文件入口见 参考地图。修改对应边界前必须阅读属主参考Agent 定义与运行上下文agent-definition-and-run-context.mdAgent 字段、克隆、动态指令、启用的工具或 handoff、输出 schema、运行上下文包装器、用量聚合与公共/内部 Agent 身份。Runner 生命周期runner-lifecycle.md回合记账、guardrail 排序、handoff、中断、取消、hooks 与流式行为且流式/非流式路径须行为对齐。Run item 生命周期run-item-lifecycle.md新模型输出、工具调用、审批或 run item 变体须更新每个适用的处理、事件、重放、持久化、追踪与序列化面。函数与输出 schemafunction-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.mdMCPServerManager、请求串行化、工具缓存/过滤、传输重试、取消与清理。追踪生命周期tracing-lifecycle.mdtrace/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 syncPython 命令用uv run可用make执行仓库任务。开发工作流除非显式授权否则留在当前 checkout 与分支。全新 checkout 或依赖变更后用make sync对应uv sync --all-extras --all-packages --group dev安装依赖实现请求的行为、添加有意义的回归覆盖并按上述技能流程走完最终交接。仅在被授权时提交提交信息简短、使用祈使语气偏好小而聚焦的提交。测试与自动化检查提供者无关的 Agent 工作流测试优先使用agents.testing的ScriptedModelRealtime 会话测试用agents.realtime.testing的ScriptedRealtimeModelVoice 管线测试用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-snapshotstests/README.md 中的make snapshots-fix与make snapshots-create可分别修复与创建快照完成后重新运行make tests。文档类命令集中在 Makefilemake 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.jsonmake 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
)
)
