openai-agents-python 高风险变更独立评审协议implementation-final-review 技能的完整实战指南【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python本指南以 openai-agents-python 仓库中implementation-final-review技能的高风险评审规程为核心系统讲解其不可协商保证、21 步评审工作流、双评审者并发机制、六大评审维度、复杂度重置规则与机器可读输出协议。读完本文你将掌握如何在多 Agent 开发流程中为安全、持久化、并发、协议与发布兼容等高风险变更建立可验证的独立评审闭环并能直接使用仓库提供的review_state.py与review_protocol.py辅助脚本产出可审计的评审证据。一、技能定位与评审分级在 openai-agents-python 仓库中implementation-final-review是AGENTS.md规定的高风险独立评审工作流入口其职责是在最终验证$code-change-verification之前对已完成实现的变更进行独立评审。该技能不负责规划、调研或报告类任务只针对真实改动过运行时代码、测试、示例、构建/测试行为或影响行为的文档的变更。技能根据变更的语义影响而非行数、扩展名或文件位置来划分评审等级对应SKILL.md中的表格等级边界要求Lightweight轻量仅拼写、注释或格式改动不改变执行、公开契约、测试预期、配置或文档含义自查完整 diff 并运行适用聚焦检查独立评审可选Ordinary普通既有契约内的局部行为变更、普通测试新增、无高风险边界的行为文档一个无历史上下文的独立评审者High risk高风险安全、凭据、敏感数据处理、信任、持久化/恢复、持久状态、并发/取消/共享生命周期所有权、发布兼容、包/运行时导出、协议所有权、跨 Provider 生命周期以及任何产生已验证 P0/P1 的评审周期两个互补专业方向的独立评审者必须遵循high-risk-review.md需要注意一行条件修复至少也是 Ordinary 级公开注解和生成 schema 的类型可能改变契约删除测试或改变测试预期、CI/构建配置、策略变更都不是轻量级改动。普通评审结论不能替代高风险评审所需的双评审者组合普通周期升级到高风险时消耗的修订次数与未解决根因必须带入高风险流程且不能重新分配一个全新的六轮预算。高风险规程的完整定义位于high-risk-review.md它依赖reviewer-brief.md定义评审者简报模板以及scripts/review_state.py与scripts/review_protocol.py两个辅助脚本。轻量级与普通变更不需要准备这些严格协议产物。二、不可协商保证Non-negotiable Guarantees高风险评审协议以一组不可协商保证为底线任何环节都不能突破。它们是评审可信度的根基可归纳为以下核心类别1完整性与冻结性。评审必须覆盖任务的完整最终内容包括已提交、已暂存、未暂存以及任务自有的未跟踪交付物。唯一例外是步骤 20 中经过严格验证的最终门类型擦除与基准前移两种封闭closure它们通过显式身份证据保留既有清洁信用但仍需在结果指纹上运行完整最终验证栈。任务自有内容在评审者检查指纹期间必须冻结仓库状态在捕获期间发生任何变化都必须失败关闭fail closed。2基线正确性。patch 归属必须使用 merge-base 的三点 diffmerge-base...HEAD而发布兼容性必须单独使用最新 release tag 作为边界。目标分支在 merge base 与 HEAD 之间的独占提交绝不能当作 patch 引入的删除或回归。3路径权威性。任务清单与组件清单中的精确规范化文件路径具有权威性即使 ignore 规则匹配该文件也依然有效已存在的精确文件优先于 Git pathspec 元字符需要模式语义时必须显式使用:(glob)magic目录或 glob pathspec 永远不能把被忽略的操作性文件提升进评审范围。4仓库状态卫生。指纹化之前仓库与每个已初始化子模块索引不得存在未解决的 merge stages每个已初始化子模块含嵌套子模块必须干净且检出在父索引记录的 commit 上。可评审的 gitlink 指针变更需在父仓库暂存脏工作树、隐藏索引标志assume-unchanged / skip-worktree、被忽略的嵌套变更、未跟踪的嵌入式仓库都要失败关闭递归检查前要拒绝循环或别名的子模块工作树图。5文件与身份真实性。packet、ledger、manifest、receipt、reviewer-output 与 evidence 路径必须解析为有限常规文件打开前先规范化路径打开后验证文件类型并从同一描述符读取——绝不能用stat授权路径后再重新打开。通过打开描述符的设备号与 inode 身份拒绝 evidence、receipt 与前后 ledger 的别名接受评审者输出或可复用 receipt 前必须重新读取 packet 与前后 ledger 并确认其已验证摘要未变化。设备、FIFO、socket 或生成流必须先物化为常规文件再验证。6摘要绑定与所有权。ledger 中每个规范根拥有的 evidence ID 与 inventory ID 都要用contract_evidence_sha256与inventory_sha256绑定跨轮次保留这些摘要绑定已存在的 ID 不能改变内容inventory 摘要仅排除 ID 自身因此重命名副本不构成新的语义 inventory。只有摘要不存在于该根先前所有权时才把 evidence 或 inventory 计为该规范根的新内容新根提案要求 evidence 摘要不存在于任何规范根及同一输出中提出的任何不同根中。每个获得信用的 receipt 必须有唯一的内容摘要与精确命令。7JSON 与 schema 严格性。每个 JSON 对象必须使用唯一键与标准有限数字重复键、JavaScript 风格NaN/infinity 常量、溢出为 infinity 的数值指数均无效。运行时数值大小与嵌套限制失败必须转换为协议错误而非泄漏解析器异常。验证 receipt、评审者输出、finding、根因证据、未检查 inventory 记录与兄弟场景扫描都使用精确 schema未知字段必须拒绝而不是忽略。8过程纪律。两位评审者的规范化主专业方向与高风险专业方向必须互不相同任何 receipt 声称前每个 preflight 命令必须唯一。manifests.dependency_map必须编码为把每个组件名映射到非空、精确pathspecreason记录数组的对象拒绝纯散文声明、缺失组件、空依赖集、重复 pathspec 与多余字段。每次指纹冻结前都要重复 commit-hook 检查、每个安全重写步骤、第二遍幂等性与生成来源验证packet preflight 证据中记录精确可执行的检查与重写命令及其结果散文标签不是可执行命令。独立评审者不得继承对话历史只有具体、patch 范围内的 finding 可以上报且必须有需求、发布行为、持久边界、显式维护者意图、用户依赖或基线回归作为支撑。最终仓库验证绝不削弱组件感知的评审失效只减少重复评审不减少必需的构建或测试门。整个任务必须维护一个跨暂停、压缩、交接、重命名、恢复工作与完成反馈的任务全局轮次 ledger每个活跃评审周期有界预算但不丢弃早期历史。实现控制面被信任记录真实的评审者调度、等待、输出与验证执行本地协议助手只验证这些记录不替代平台签发的加密执行证明。三、完成边界与反馈周期实现评审周期只有在以下全部完成后才算完成清洁评审门通过、强制验证完成、任何被请求的本地提交完成、最终面向用户的交接完成。周期在这个边界被封存sealed。暂停、压缩、上下文切换、完成前的 Agent 交接或要求继续未完成工作的普通请求都不会开启新周期或重置预算。后续包含具体可操作评审反馈的用户消息会开启完成后反馈周期post-completion feedback cycle。反馈消息本身即授权实现该反馈、运行仓库强制的聚焦测试、增量评审、验证以及任何为恢复任务完成状态所需的已授权本地提交或修正。反馈不独立授权提交除非任务原本允许。即使封存周期已耗尽预算也不应单独请求评审预算授权。新反馈周期沿用同一任务身份与 ledger保留其规范根因历史与未变更组件的清洁信用并追加默认两个指纹轮次的预算。仅当反馈实质性拓宽契约、改变发布或持久兼容边界、需要超出解决反馈范围的权限、或耗尽反馈周期预算时才再次询问用户。四、21 步高风险评审工作流工作流以当前组合内容指纹持久化为ledger.round_fingerprint并绑定到 packet 指纹开篇。同一轮重试仅在指纹与授权预算历史匹配不可变的前 ledger 快照时有效指纹变化或新授权预算则推进轮次。以下是完整步骤步骤 1 — 完成实现与格式对齐。完成初始实现与聚焦测试格式化可能在评审前改写 diff 时先做格式化。在冻结第一个评审指纹前检查实际最终 commit-hook 配置并对每个可能重写任务自有内容的 hook 步骤运行精确、安全、不提交的等价命令每个重写步骤运行到第二次执行内容幂等。计算内嵌哈希或来源前先规范化生成文件避免 hook 稍后使其失效。记录无法在评审前安全运行的 hook 步骤若该步骤后来改变任务内容无例外地适用常规失效规则。步骤 2 — 重读需求与契约。重读原始用户请求与当前实现范围契约。若不存在契约记录必需行为、兼容性要求、有意不支持的用例与失败行为、支持的替代方案或none。步骤 3 — 解析目标与 merge base。若提供的目标或 base 不是HEAD的祖先计算它们的公共 merge base将merge-base...HEAD视为任务自有 diff发布兼容性相关时单独使用最新 release tag。包含属于任务的已提交、已暂存、未暂存与未跟踪变更。步骤 4 — 阅读完整三点 diff。从解析的 merge base 读取完整任务自有三点 diff绝不把 merge base 与前进或分叉目标之间的目标独占提交当作 patch 引入的删除或回归相关时单独检查与当前目标的集成报告实际冲突或语义不兼容而非目标侧缺少变更。评审不限于最新修复或先前反馈中提到的文件。记录复杂度增量运行时行数变化、新状态字段、新同步或所有权机制、受影响子系统与测试排列。步骤 5 — 基线重置门。接受当前设计前运行基线重置门不引用分支局部辅助类型或状态地描述必需行为识别最近已拥有该行为的发布/基线管线对比patch 当前 diff与用基线实现的窄变更替换任务自有分支局部机制将未发布实现与测试视为可丢弃保留无关或用户自有变更。除非具体契约证据要求当前机制否则选择更窄的设计。步骤 6 — 选择评审维度与 preflight。从受影响的运行时边界与仓库架构参考中选择下方评审维度即使找到 blocker 也要完成每个选定维度——目标是完整最终评审而非首个有效评论。入口已把变更分类为高风险全程保持该分类并在机器可读 packet 中用既有协议值编码为task.risk_tier: elevated。运行最便宜、足够宽的受影响边界 preflight 以捕获依赖、包表面、生成工件或跨切面运行时变更的晚期连锁影响优先聚焦测试加窄范围导入/生成表面/静态检查。仅在变更直接影响类型边界且命令明显窄于仓库级make typecheck时运行定向类型检查。不要仅为进入或迭代评审门就运行仓库级 lint、typecheck、构建、集成套件、make tests-review或make tests。聚焦 preflight 对每个语义状态只跑一次修复后只重跑受影响检查。步骤 7 — 构建派发前证据。对每个变更的公开符号、配置字段、事件、序列化字段、线上值或文档化调用方可见行为建立契约表面清单producers 与构造函数、每个 consumer/转发分支/适配器、默认/缺失/无效值行为、包导出与生成公开表面、相邻文档与示例、调用方可见测试即使 diff 中没有也搜索相邻契约表面。对并发/取消/重入/共享生命周期状态/副作用前检查后 await建立 await 边界矩阵记录状态快照、阻塞点、挂起期间可能运行的事件与操作、保留的持久或单调证据、每个副作用前的重新验证、以及产生的取消/反馈/持久化/清理动作若正确性依赖某事是否曾发生当前活动状态不够除非序列化证明其不会丢失需要单调身份、代次、墓碑或等价持久证据。对协议/持久化/安全变更建立输入到验证、存储、重试/重放、输出、异常、日志、遥测与清理的权威/数据流清单。这些是机械覆盖工件而非实现结论实现者必须在评审前用代码与契约证据填写评审者对照完整 diff 与周边源码独立验证。步骤 8 — 产出可复现的 patch 内 finding。只产出能从代码、契约、文档或聚焦探测复现的具体 patch 内 finding不上报假设性可扩展性或无关清理。结论前必须覆盖契约表面、await 边界与权威/数据流清单的每一行、以及每个新增或修改的共享状态源。对必需行为之外的场景对照 merge base 或最新 release 做差异检查并给出支撑证据。仅凭公开方法可达、并发调用、重复调用、宿主语言协议或第三方行为可达不构成受支持契约。步骤 9 — 编辑前分类。每个 finding 在修改前分类必需行为缺陷发布兼容或持久边界缺陷缺失失败路径或对抗性覆盖应更早失败的邻近不支持用例不必要机制或重复事实源拒绝无关或不支持的提议。每个可操作 finding 记录支撑依据原始需求、发布文档/示例/类型/测试、持久边界、具体维护者意图或用户依赖、或基线成功而 patch 失败的同一受支持场景回归。若无依据不修复不阻塞标记为 unsupported/deferred。步骤 10 — 任务全局评审 ledger。有可用 Codex task/thread ID 时作为稳定任务身份否则生成一次身份精确持久化为ledger.task_id并要求与 packet 任务身份匹配。ledger 存储为稳定绝对路径下的被忽略操作性文件路径包含在每份评审者 packet 与交接中工作树迁移时保留同一文件暂停、压缩、交接、重命名、迁移或恢复上下文都不允许重新初始化计数器。仅当该任务无先前轮次时启动指纹轮 1同指纹、缺评审者字段的请求仍属当前轮。初始实现周期默认自主预算为六轮指纹。从普通评审升级时其消耗的修订数与未解决根因要保留在任务笔记中首个严格 ledger 预算初始化为剩余授权周期预算而非新的六轮严格指纹编号可从 1 开始但普通严格评审总数必须在原上限内。预算耗尽时先请求具体用户决策再派发。普通结论不获得严格清洁信用。完成后反馈周期将反馈消息本身视为授权在同一 ledger 追加默认两轮指纹预算不重置轮次计数器、规范根因历史或未变更组件的清洁信用。实现者用稳定规范 ID 为每个根因分配一次 ID并在后续每份 packet 中包含完整打开关闭根集合评审者必须复用提供的规范 ID 或提出NEW:slug并附内容全新契约证据只有实现者可提升该提案并在 ledger 分配规范 inventory。创建每个任务自有交付路径含重命名两侧与任务自有未跟踪文件的规范清单计划、评审 ledger、packet、trace、临时报告等工作流工件默认仅操作性除非原始需求或仓库策略明确要求其成为已提交交付物。按与 patch 匹配的最窄稳定语义边界划分清单本仓库优先组件如api-contract、runstate-persistence、security-sandbox、session-lifecycle、integration-runner、tests-examples、release-metadata不创建空组件不为保留信用拆分紧耦合文件。每个变更交付物必须恰好属于一个组件每个组件记录精确语义依赖输入 pathspec 集及原因不能用粗粒度目录或纯散文none。本技能资源可用时优先运行python scripts/review_state.py --repo worktree --base merge-base --pathspec-file task.paths --component-pathspec-file api-contractapi-contract.paths ... --complete-diff-output complete.diff小 diff 仍可用直接--pathspec与重复--component NAMEPATHSPEC。必须始终通过--complete-diff-output生成完整 diff 工件——独立git diff会遗漏普通未跟踪交付物。保留每个组件的content_fingerprint、组合content_fingerprint与repository_fingerprint仅当所有仓库变更都属于任务时才省略 pathspec。按稳定根因 ID 分组记录复杂度增量与 finding严重级、动作、是否新/重复/重新引入。步骤 11 — 准备自包含评审者 snapshot packet。可用时用reviewer-brief.md每轮准备一份自包含 packet共享证据只计算一次所有评审者复用同一需求、范围契约、target/base/head、清单、指纹 JSON、原始 status、完整 diff 命令、preflight 结果、契约表面清单、状态/数据流清单与选定的架构摘录给每个清单行与 evidence 项分配稳定 ID填充每种清单的每个字段纯摘要行不完整。把review_state.py的精确 JSON 存为role: review-state单一工件其--complete-diff-output原始输出存为role: complete-diff单一工件未过滤的git status --porcelainv1 -z --untracked-filesall输出存为role: repository-status单一工件其余标记role: supporting。packet 的review_state.evidence_id指向 review-state 工件而非复制指纹值repository.status_evidence_id指向 repository-status 工件。仓库指纹覆盖未过滤 status 加每个变更路径的内容身份含任务清单外路径。每个组件与三个控制工件分配给两位评审者。packet preflight 从 review-state 工件派生组合与组件指纹要求任务/组件清单与其 pathspec 精确匹配、complete_diff_paths与任务工作区完全相等、complete-diff 摘要匹配其complete_diff_sha256、status 摘要匹配未过滤状态指纹、repository.exclusions为任务清单外的每个变更路径提供具体原因。每个规范 ledger 契约证据 ID 必须解析到已索引 evidence 工件ledger 摘要映射必须精确绑定拥有的 evidence 与 inventory 内容。任务 ID、任务全局 ledger 路径与紧邻前轮不可变 ledger 快照及 SHA-256 摘要保持在 packet 外的活动控制面中绝不从待验证 packet 派生这些权威参数绝不用可变当前 ledger 充当自身前快照第 1 轮后每次验证器调用都要独立提供全部四项。验证器要求 packet/当前 ledger/前 ledger 身份与这些参数匹配只接受同轮重试或恰好推进一轮用追加式授权预算历史对账当前轮与剩余预算保留前预算前缀、规范根所有权与拥有的内容摘要并把每个 inventory ID 恰好分配给一个规范根。控制面简报以约 12 KB 为软目标更大的原始 diff、日志、矩阵与参考摘录放入索引 evidence 文件并给出精确路径与 SHA-256压缩会遗漏决策相关证据时超出目标并记录原因。每个模板字段要么填充要么显式none/not applicable不派发不完整 packet。派发前在 reviewer-brief 记录的机器可读 schema 中编码 packet 索引第 1 轮后运行python scripts/review_protocol.py packet --packet packet.json --task-id task-id --ledger ledger.json --prior-ledger prior-ledger.json --prior-ledger-sha256 sha256仅当其成功退出才派发用其输出的 packet 路径、字节大小、SHA-256、精确组合指纹、组件指纹、inventory ID 与评审者 ID 作为启动记录。每位评审者只给一个可直接运行的指纹重验证命令仅专业分配可不同。不要求评审者重新发现工作流技能、实现策略、内存、release tag、清单路径、助手位置或验证历史评审者可在证据不一致、看似错误或存在决策相关歧义时重开主源或发布证据但重开不能替代缺失的强制 packet 内容常规上下文重建是实现者工作。步骤 12 — 冻结并并发派发两位评审者。一轮评审者运行期间冻结任务自有内容同一指纹上并发派发两位独立评审者给予互补高风险专业方向每位评审者看到完整原始 diff 并可报告专业外 blocker。平台支持上下文分叉控制时以fork_turns: none派发绝不传递实现者累积对话或使用全历史分叉。先启动两位再等待等待期间不编辑便于把 finding 作为一批分组修复。使用一次事件驱动 240 秒等待或平台多目标首完成等待不用list_agents、分段短等待、进度提问或无操作followup_task轮询。超时后对未完成集合再发 240 秒等待一位完成后只对剩余者继续 240 秒等待。因启动、服务、内容过滤、上下文或工具基础设施失败而未能产出协议有效输出的评审者进程既不产生 finding 也不获得清洁信用不推进ledger.current_round也不消耗指纹轮次仅在相同冻结 packet 与分配上替换该评审者任务指纹、packet 与分配不变时已接受的对方协议有效输出仍可用。原始双评审者并发派发满足本轮并发要求接受的对方输出加同一 packet 与分配上的独立替换输出构成所需配对。独立替换不可用时上报门不可用不把基础设施失败计为评审证据。评审未完成或含 finding 时不启动任何宽最终仓库门在本仓库中make lint、make typecheck、make tests-review、make tests、仓库级构建、examples runner 与集成套件都推迟到步骤 19 确立清洁评审。评审等待时间用于不可变的证据整合、finding 分类准备、宿主容量检查或其他不改变冻结指纹的任务工作否则继续事件驱动等待。迭代评审轮中只运行针对变更边界的聚焦检查不运行make tests-review、make tests或仓库级make typecheck。优先复用已成功的同指纹聚焦检查绝不重放累积历史验证可复用聚焦成功表示为验证 receipt含精确命令、环境、退出状态、非变异依据与相同的前后组合/组件/仓库指纹其绝对路径与 SHA-256 加入verification.credited_receiptspacket preflight 验证每个信用 receipt。聚焦检查不获最终门信用精确清洁评审指纹仍必须通过完整仓库必需验证栈verification.eligible_concurrent_gates置为none每个推迟的宽门列在verification.deferred_gates。$pr-draft-summary推迟到清洁评审与最终门证据应用于最终指纹。不引入仓库锁、宿主机互斥、哨兵文件或用户触发的finalize步骤。步骤 13 — 验证指纹后接受评审者输出。若评审的运行时或契约承载内容变化丢弃受影响评审证据除非稍后符合步骤 20 的窄封闭仅repository_fingerprint变化时只对暂存/取消暂存/提交相同任务自有内容等无歧义非语义簿记接受评审。语义组件仅在指纹、需求行、运行时行为断言、依赖输入与风险等级全部未变除步骤 20 窄记录封闭外时保留清洁信用。其他每个变更或依赖失效组件加其与未变组件的相关边界要求两次并发独立增量评审。任何歧义使受影响清洁信用失效不因相邻文件或粗粒度目录变化而使无关组件失效。步骤 14 — packet 与输出接受门。计 finding 或清洁信用前验证每个强制 reviewer-brief 字段已填充或显式none/not applicable缺失 packet 证据不可由评审者重建不获清洁信用。要求一个符合文档化 schema 的结构化 JSON 对象verdict、精确组合与组件指纹、已检查/未检查 inventory ID、高风险维度、聚焦探测、剩余不确定性、findings、兄弟场景扫描、检查调用次数与适用时的检查预算原因。每个探测记录必须含实际运行的可执行命令或非 shell 探测的完整工具名参数拒绝散文标签、省略参数与focused probe占位符。第 1 轮后对每个输出运行python scripts/review_protocol.py reviewer-output --packet packet.json --reviewer reviewer-id --output output.json --task-id task-id --ledger ledger.json --prior-ledger prior-ledger.json --prior-ledger-sha256 sha256失败时不接受任何 finding 或清洁信用。验证器拒绝指纹漂移、缺失分配覆盖、畸形探测、未知裸根 ID、packet 索引 evidence/inventory 中缺失的根证据 ID、用重命名根或未知 inventory 的兄弟扫描、整数字段的 JSON 布尔、改变先前的 evidence/inventory 绑定、无内容全新证据或语义 inventory 就重开已关闭规范根、以及复用同一 evidence 摘要的不同新根。评审者派发后发现新证据时在冻结 packet 中添加并摘要同一指纹轮内重跑 packet preflight 再请求修正输出。裸clean、通用清单、畸形对象或未对账所分配契约/状态/数据流工件的响应不完整、不获清洁信用只请求同冻结指纹上的缺失字段或覆盖不重启整个评审。两位专家组合时合并声明的 ID 覆盖任何分配的 inventory 行或选中的高风险维度未被评审即拒绝本轮。每位评审者约 12 次源码检查工具调用为软预算决策相关不确定性需要更多证据时可超出但必须说明原因绝不为预算牺牲正确性。步骤 15 — 批量分类、验证与修复。编辑前分类并验证本轮全部 finding然后作为一批修复每个可操作 finding。修复前用发现的转移或表面更新完整相关清单/矩阵跨所有已填充行解决根因不只补丁报告的交错。$implementation-strategy归实现者所有并在 packet 中提供当前范围契约评审者继承该契约不重跑策略工作流。仅当修复改变支持行为、兼容性、状态、所有权、协议路径、测试排列或触发复杂度重置时才在实现者上下文中重跑否则记录scope contract unchanged避免重建同一策略。添加调用方可见回归覆盖而非只镜像辅助结构的测试只对受影响边界与依赖失效检查运行聚焦验证。步骤 16 — 第二相关 finding 即关闭门。同一根因组的第二个相关 finding 触发关闭门停止局部修补运行一次复杂度重置扫描完整清单的兄弟场景记录一个根级处置替换设计、收窄或拒绝不支持行为、或升级具体未解决契约决策。处置实现并评审后标记规范根因 ID 关闭没有内容全新契约证据或语义 inventory 不得仅凭局部补丁重开——拒绝别名、重命名/复制内容与裸未知 ID。无法连贯关闭时升级而非消耗更多轮次。步骤 17 — 推进指纹轮并重审。递增指纹轮从步骤 1 重复完整 commit-hook 对齐门用全新上下文评审完整修复后 diff。评审 → 验证全部 finding → 批量修复 → 聚焦验证 → hook 对齐 → 评审不等用户提示持续进行。步骤 18 — 非收敛防护。再次本地修复前应用复杂度重置后同一根因组再产生 P0/P1则回到 merge base用最窄连贯实现替换任务自有分支局部机制连续两轮运行时 diff 规模、状态字段、所有权模式或测试排列实质增长不因每个 finding 局部就称收敛重跑基线重置门同一根因组在三轮含 finding 轮中产生可操作 finding或更窄重实现仍产生同根因 P0/P1尽早升级而非消耗轮次预算四轮完成而 diff 未收缩或稳定、finding 严重度未下降尽早升级。步骤 19 — 清洁评审条件。仅在精确评审内容上满足所需清洁评审条件且每份必需评审者输出通过接受门后停止同轮基础设施替换原始双评审者并发派发接受配对 未变的协议有效对方输出 步骤 12 接受的一个独立替换输出高风险变更或产生过 P0/P1 的循环同一指纹两次独立清洁评审、互补高风险专业、并发启动组件后评审编辑每个未变组件清洁信用 覆盖全部变更组件及其运行时边界的两份并发清洁独立增量评审验证的最终门类型擦除封闭满足步骤 20 每项条件时不需新指纹轮或评审者派发保留先前清洁集然后在结果指纹上运行完整最终验证栈验证的基准前移封闭同上。步骤 20 — 清洁后的最终验证。清洁评审条件满足后确认 diff 与组件指纹稳定然后检查可观察宿主容量再启动仓库代码变更验证用只读任务/进程证据把同一宿主上已活跃的仓库级测试/typecheck/构建/examples runner/集成命令视为具体争用。可见争用时继续有用的非重型工作或事件驱动等待后再查不创建或等待仓库锁、宿主机互斥或哨兵文件不要求用户触发finalize。宿主遥测不可用时不能仅因容量不可测量而阻塞。容量可用后按仓库必需顺序对精确清洁评审指纹运行每个强制命令或对下面验证封闭的记录结果指纹运行最终栈前后立即记录组合/组件/仓库指纹。仅当每个命令成功、执行不改变最终内容或不产生歧义仓库状态变化、所有指纹仍匹配时接受最终验证。最终门重放或编辑先分类再使评审证据失效验证的基准前移封闭清洁评审后目标前移时仅当以下条件全部成立才保留既有清洁集、不新增指纹轮或评审者派发重放/变基无冲突且无需手动任务内容编辑新旧review_state.py工件的任务与组件workspace数组逐字节相同且tracked_diff_sha256相同直接比较这些字段因为内容指纹有意包含已解析 base原评审前每个组件记录了精确语义依赖输入 pathspec 与原因旧 base 到新 base 的完整上游增量不改变任何任务清单路径、依赖输入路径、选定架构参考、生成表面所有者或适用的构建/测试/lint/格式/hook/lockfile/包配置输入原始需求、范围契约、清单行、运行时行为断言、选定评审维度、风险等级与发布兼容边界未变受新 base 集成影响的聚焦检查通过。在任务全局 ledger 记录新旧 base/head、组合/组件/仓库指纹、精确上游变更路径列表与 diff 摘要、依赖输入 pathspec、比较命令与结果。此封闭不消耗指纹轮、不创建评审者 packet。任何路径重叠、配置或依赖输入变化、冲突、手动解决、diff 摘要变化、缺失先前依赖映射或不确定性都落入新 base 上的全新评审轮粗粒度目录不相交声明不够。验证的类型擦除封闭仅当以下条件全部成立才保留既有清洁集、无需独立增量评审编辑仅在最终栈报告 formatter/linter/静态类型检查失败后、且失败未揭示未解决运行时或契约不确定性精确 delta 限于从标准库typing直接导入cast、把一个未变的私有实现表达式包成cast(type, original expression)、以及 formatter 独有空白导入名未重绑定或他处使用编辑不改变表达式求值顺序或次数、异常传播、公开/导出注解或签名、装饰器、运行时分支、常量、测试断言、生成表面、文档、范围契约、清单行、组件依赖或风险等级。实现者记录前后指纹、精确 delta、原始最终门失败与typing.cast原样返回值这一运行时身份依据重启完整栈前定向格式化、lint、类型检查与受影响聚焦测试必须通过。任何额外 token 变化、超出此精确typing.cast形态的行为等价论证或上述条件的不确定性都落入常规运行时编辑规则需要适用的独立增量评审。运行时/公开 API/影响行为的文档/运行时行为断言/范围契约变化使适用清洁集失效重跑评审前验证用全新评审者重启评审再重跑每个必需最终门。仅测试或示例运行时指纹相同且 delta 不改变必需行为、兼容性、运行时行为断言或范围契约时保留清洁运行时证据按步骤 19 风险等级与清洁评审条件运行聚焦验证与组件增量评审覆盖测试正确性、意外契约扩展与运行时边界再重跑仓库必需门。除非具体证据表明相反示例或预期编辑视为影响行为。仅发布元数据指纹相同时保留运行时与测试证据重新验证元数据并独立评审任何变化的行为声明再重跑适用最终门。仅操作性工件从交付清单排除且不使评审证据失效。完成要求最终组合指纹恰好由组件指纹适用清洁/增量评审/验证的基准前移封闭/验证的类型擦除封闭证据组成且每个强制仓库门在该最终内容上通过。$pr-draft-summary最后调用仅在评审与验证证据应用于最终指纹之后。步骤 21 — 停止自主循环。活跃周期达到当前预算时停止初始实现周期六轮指纹完成后反馈周期两轮。这是活跃周期的绝对上限而非目标执行暂停或上下文变化不重置。不宣布实现完成总结剩余 blocker、反复根因、复杂度增长、尝试过的修复与重置、当前验证状态与用户可做的具体决策询问用户是否收窄范围、拆分变更、接受已知风险、重新设计或显式授权另一有界预算。封存周期后收到具体可操作反馈时在同一 ledger 追加反馈周期默认两轮预算无需再次授权提示。其他情况把用户授权预算追加到同一 ledger 而非替换其历史。工作流要求全程维护一个紧凑轮次 ledger并持久化为持久、任务全局工件Round | component fingerprints | root-cause groups | highest severity | complexity delta | action | clean credit持久化足够任务身份、已用与授权轮次预算、周期边界、指纹、根因关闭状态与清洁信用以便无需重建先前轮次即可恢复只在有意义状态转移时更新轮开始、接受的 finding 批、复杂度重置、清洁结果、验证结果、封存完成或反馈周期开始。评审者状态与仓库内容都未变化时不重复发送等待消息。五、独立评审者新鲜判断与纪律约束独立评审 无历史的新上下文没有实现过被指纹化内容也不被告知先前评审者 finding 或实现者结论。优先使用不同 Agent 并在平台暴露该控制时设fork_turns: none同上下文自审或全历史分叉不独立不能满足清洁评审门。给评审者的输入原始需求、实现范围契约、base 与 head 标识、规范组件清单与指纹、原始仓库状态、相关架构参考预计算的契约表面与 await 边界或权威/数据流清单——这些是覆盖图而非结论要求评审者对照原始 diff 与周边源码验证每一行明确告知哪个标识是目标并要求显式 merge-base 计算目标与 head 分叉时提供或请求三点 diff绝不把两点 target-to-head diff 当作 patch不提供实现者的结论、怀疑的 bug、意图修复或预期 finding 列表。单轮只读评审者不得编辑或暂存文件、递归运行自主评审循环、派生另一位评审者或执行最终仓库验证finding 验证、编辑、循环控制与最终验证归实现者。同一指纹与冻结 diff一轮的所有评审者共享同一 review-state 指纹全部完成前 diff 冻结拒绝从不同或变化状态产生的输出不跨修订合并部分观察。简报纪律给每位评审者紧凑自包含控制面简报、索引 evidence 路径与摘要、一个精确重验证命令任何强制 packet 字段未填充也未显式标记none/not applicable时评审者必须上报且不能返回可信用清洁 verdict。评审者不检查内存、不重新发现工作流技能、不重跑实现策略、不搜索指纹助手、不重新发现 release tag除非证据不一致或决策相关重开源码不能替代缺失 packet 内容。每轮全新评审者尽可能每轮使用全新评审者不透露先前轮次 finding 或结论只提供更新的需求、范围契约、原始最终 diff、组件清单与相关参考每轮使用两位并发全新评审者步骤 12 的高风险条件分配互补高风险专业并要求各自检查完整 diff同一未变 diff 的两位评审者计为一个指纹轮不重复宽测试执行。探测规则评审者可检查代码与测试只运行解决决策相关不确定性所需的聚焦探测探测必须可证明非变异或在隔离临时检出中运行任何对被审工作树变异使本轮失效不重跑仓库宽测试/typecheck/lint/构建/集成套件去重确认实现者证据——实现者在清洁评审门后运行一次完整栈。结构化输出要求 reviewer-brief 定义的结构化 JSON。clean单独永远不够必须返回精确 packet SHA-256 与指纹、已检查与未检查 inventory ID、检查过的高风险维度、探测或none、未解决不确定性或none、findings、兄弟场景扫描与检查预算对账。修复后重审修复后再次评审精确最终 diff仅在显式组件增量规则下保留先前清洁信用不因文件位置推断变更隔离。独立评审者不可用时从原始请求、范围契约、源码与完整 diff 重建上下文后做尽力而为自审显式丢弃增量评审假设、标记结果非独立、不计入清洁评审门并在交接时上报门不可用而非静默弱化。六、评审维度按受影响边界选择根据变更边界选择维度不机械为每个条目编造 finding。需求与范围验证最小必需调用方可见行为工作识别邻近可构造用例并确认其被有意支持或在副作用前拒绝把重复、并发、重入、畸形、包装或跨 Provider 组合当作 blocker 前要求契约证据声称回归时在基线上复现同一受支持场景检查测试是否意外把实现排列变成公开契约把每个新抽象、状态字段、分支、依赖与跨模块变更映射到需求、受支持契约或已验证风险。兼容性与身份对比发布公开签名、字段顺序、导入、名称、序列化值、配置与线上行为除非转换必需保留精确调用方可见身份或拼写区分未发布分支局部机制与发布/持久兼容边界对每个新/修改公开字段枚举全部构造、转发与消费分支验证常规、专用、默认、缺失值与错误路径要么遵循该字段要么按一致契约拒绝——不只验证动机分支搜索公开文档、示例、docstring、配置参考与发布元数据中被行为变更弄陈旧的声明缺失文档即使 diff 中无文档文件也可能是可操作遗漏按仓库 Documentation Release Timing 策略分类描述未发布行为的必需docs/内容是独立计时工作不是当前任务或 PR 的缺陷。生命周期与失败从获取到成功、失败、取消、重试、替换与清理追踪所有权共享生命周期状态变化时先建紧凑操作-状态矩阵再下结论覆盖每个受影响公开变异操作对未启动/部分失败/活跃/清理中/终止状态追踪重复顺序调用与每对重叠公开变异操作识别线性化点或管理器拥有序列化机制不单靠按资源去重推断安全检查重复取消、部分初始化、清理失败、每个受支持公开入口的重试与主异常保留陈述最终幸存者不变量——哪些任务、worker、进程、会话、监听器、文件或远程资源可能保留审查多个验证或清理可短路时的排序审计每个 check-await-side-effect 序列await 期间状态可能变化取消/反馈/持久化/清理前要求重新验证或证明管理器拥有序列化区分当前状态与历史证据——若陈旧结果保证依赖更新操作是否曾启动事后回到None的活动指针不能证明缺失除非操作被序列化否则使用或要求单调证据。安全、信任、持久化与协议追踪调用方控制数据经过日志、异常、cause、context、遥测、模型可见输出与持久状态仅当支持信任边界显式允许时才把序列化状态当权威畸形或歧义敏感输入的失败关闭行为不得返回或保留原值受影响时验证协议能力所有权、分页终止、缓存所有权、重试与重放安全、线上验证与工具或调用身份。行为对等需求跨越流式与非流式、同步与异步、初始与恢复、直接与包装、Provider 特定路径时做对比验证一路径不静默忽略、重塑或硬失败另一路径支持的数据。测试与生成公开表面优先公开边界或调用方可见对抗性测试在复现必需行为的最高稳定调用方边界练习——调用方在调用辅助函数前后转换输入、拥有生命周期或决定可观察结果时纯辅助测试不够期望值与失败信号必须来自契约、工作示例、基线或另一独立 oracle不接受用与实现相同逻辑重算期望值的断言生命周期、并发、Provider 线上或畸形流场景无法通过公开入口可靠控制时使用更窄内部边界并记录原因并发用受控交错而非只靠顺序测试测试必需行为、最近支持替代与每个不支持类别一个代表性输入传递的既有测试编码与实现相同假设时不作为证明公开包行为变化时经预期消费者入口导入并验证生成或分发工件——仅运行时测试不证明发布表面。七、复杂度重置停止逐个打补丁当相关 finding 不断扩张同一设计、窄需求需要递归或缓存分类、测试枚举机制、表示在多处被推断、或 diff 意外跨子系统扩散时运行复杂度重置停止逐条处理 finding。按根因分组并重述原始必需行为。对照 merge base 或发布边界比较完整 diff。删除非必需的 branch-local 机制。复用最近既有的事实源管线。收窄不支持行为并在副作用前以存在的支持替代拒绝。围绕调用方可见不变量与代表性负例重建测试。把替换方案的运行时与测试复杂度与上一轮及 merge base 比较——只重命名或重新分配增长状态机的重置不是重置。两个配套实现细节也值得注意review-state 工作区条目必须使用其file、symlink、gitlink、directory或missing种类发射的精确键集字段不完整或未知会在派发前失败可复用验证信用要求 receipt 命令与verification.preflight_results中的结构化命令精确匹配不同成功命令不能继承验证信用。八、评审输出单一结构化 JSON评审者必须严格返回reviewer-brief.md定义 schema 的恰好一个 JSON 对象verdict 放verdict每个可操作 finding 放入findings含优先级、标题、位置、具体失败场景、用户可见后果、支撑依据、适用时的基线对比 patch 证据、最小安全修正与稳定根因 ID。必须对账每个分配的 inventory ID显式保留未验证的运行时不确定性在两次结构化清洁评审与所需验证应用于精确最终状态前不得声称实现完成。clean结论要求unchecked_inventory_ids、remaining_uncertainty与findings均为空数组。九、配套脚本与测试的源码级佐证该协议的机器可验证性由两个脚本保障测试覆盖完整。从源码结构看review_state.py约 700 行负责生成确定性的内容与仓库指纹。其关键机制包括_read_regular_file用O_NONBLOCK打开并用os.fstat在打开后验证常规文件类型对应不可协商保证第 5 条_unsafe_index_paths用ls-files -v检测 assume-unchanged 与 skip-worktree、用ls-files --unmerged检测未解决合并_require_clean_submodules递归检查 gitlink 与嵌套子模块 HEAD 与父索引一致、拒绝循环工作树test_cyclic_gitlink_worktree_fails_closed与未初始化的物化 gitlink_complete_diff通过git diff --binary --full-index加对每个未跟踪文件的git diff --no-index /dev/null path拼接保证任务自有未跟踪文件进入完整 diff_capture_snapshot连续捕获两次快照final_snapshot ! snapshot时抛 Repository changed while review state was captured对应保证第 7 条_content_fingerprint对{base, workspace}的规范 JSON 做 SHA-256_repository_fingerprint额外混入 head、status、tracked/complete diff 与未过滤状态摘要。测试test_review_state.py验证了 FIFO 失败关闭、非 UTF-8 文件名稳定指纹、pathspec 元字符精确性:(glob)语义、--complete-diff-output必须在仓库外、组件指纹只使变更内容失效等行为。review_protocol.py约 1360 行是验证器暴露packet、reviewer-output、receipt三个子命令。从源码结构看其核心保证包括_json_bytes用object_pairs_hookunique_object拒绝重复键、用parse_constant/parse_float拒绝非有限数字对应保证第 7 条_read_bytes强制绝对路径、打开后验证常规文件、返回(st_dev, st_ino)身份元组_evidence_artifacts用该身份拒绝证据文件别名测试test_packet_rejects_aliased_evidence_pathsREQUIRED_PACKET_TEXT强制 packet 必须包含任务 ID、原始需求、风险等级、范围契约四要素、仓库四标识、清单路径、evidence ID 等字段validate_packet校验 budget 历史对账、current_round恰好推进一轮、前 ledger 快照摘要绑定、规范根不得重叠/不得重开、eligible_concurrent_gates必须为none、deferred_gates必须列出推迟的宽门validate_reviewer_output校验评审者输出精确字段集合、inventory 对账、探测命令不含占位符、finding 的根因 ID 必须是规范 ID 或NEW:slug且附内容全新证据、clean结论必须零不确定性零 finding。测试test_review_protocol.py覆盖了同轮重试指纹绑定、前 ledger 追加式历史、硬链接别名拒绝、布尔当整数拒绝、依赖映射精确 schema、评审者专业不重叠等关键路径。十、在本仓库中的落地建议在 openai-agents-python 中应用本协议时建议结合AGENTS.md的仓库规则涉及src/agents/运行时、公开 API、配置、持久化 schema 或线上协议的变更先运行$implementation-strategy记录范围契约评审通过后由$code-change-verification拥有最终 SDK 验证栈的命令顺序、沙箱执行与重试规则docs/变更按编辑/内容/结构三级分类并用翻译安全英语撰写公开构造函数与 dataclass 字段顺序、__all__成员与预期导入路径均视为兼容契约。实际执行时用uv run python ...保证环境一致聚焦测试优先使用agents.testing的ScriptedModel等确定性测试替身把脚本放到技能目录解析scripts/review_state.py与scripts/review_protocol.py的相对路径。这套协议的价值在于把评审从主观意见变成可验证的证据链每一次派发、每一份 finding、每一轮预算都与 SHA-256 摘要绑定任何篡改、别名、重开或跳过都会在review_protocol.py验证器中失败关闭。对于安全、持久化、并发与发布兼容这类代价极高的缺陷它提供了工程化的防线——而这正是 openai-agents-python 这类多 Agent 工作流框架自身开发流程的示范。【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考