maintainer-review

维护者评审

目标

做出维护者决策，而不是泛泛的代码评审总结。请分别回答以下问题：

1. 所声称的行为是否真实存在？
2. 是否存在独立于报告者所提议 API 或修复方案的用户结果或约束？
3. 现有受支持的功能能否通过合理的组合或配置实现该结果？
4. 如果仍存在缺口，所提议的方案是否是最佳的设计与实现层级？
5. 普通用户是否有可能触及该缺口？触及后会发生什么？
6. 是否重要到需要立即处理？
7. 如果此 PR 尚不存在，维护者是否会选择开启并实现同样的工作？
8. 对于一个 PR，此方案是否值得合并并长期维护？
9. 重叠或过时的操作是否可能破坏共享状态，或清理由仍然存活的工作所拥有的资源？
10. 如果存在相互竞争的 PR，维护者应当推进哪一条单一实现路径？
11. 哪些模糊的范围或语义选择属于维护者负责的产品/API 决策，贡献者应当实现的具体方向是什么？
12. 什么样的简洁维护者消息能够清晰且礼貌地传达关闭或变更请求？

将 issue 中请求的字段、回调、标志、类或实现策略视为一种拟议机制，而不是已被接受的需求。不要一开始就讨论如何实现它。首先需要证明：具体的用户结果并未被现有功能支持，并且所提议的机制优于可用的其他替代方案。

先说明当前的评审状态。在仍有影响决策的证据待定时使用 Preliminary assessment；只有在可以结束评审时才使用 Maintainer decision。应将 diff、issue 叙述或贡献者投入的工作量作为证据使用，而不应将其直接等同于影响力。

工作流程

1. 确定准确的目标

• 以 GitHub issue 或 PR 的 URL 作为主要输入。在评审前解析其所有者、仓库、条目类型和编号。
• 对于 issue，阅读完整报告、评论、复现步骤、环境信息、关联材料以及维护者的回复。
• 对于 PR，检查当前远程的 base 与 head、完整补丁、相关时的提交历史、测试、关联 issue 以及评审讨论。不要用当前本地检出代替所评审的远程变更。
• 用一句可证伪的陈述表述该声称。区分报告的症状与报告者提议的原因或修复方案。
• 当兼容性或回归性声称重要时，确定已发布的行为边界。
• 当某项拟议变更移除、重新排序或重新解释了既有的可观察行为或明确的现有测试预期时，在做任何正面评估之前，检查引入该行为的提交、blame 信息以及原始测试。即使不构成永久性的公开契约，有意保留的已发布覆盖内容也属于兼容性风险证据。
• 验证关联证据是否与 PR 的确切运行时变体、提供方或工具类型、触发条件以及用户结果相匹配。通用的 issue 标题、概念上的相似性或 Related to 之类的措辞，都不能将需求证据转移到相邻的扩展上。如果所报告的场景已被修复，则应将其他变体视为需要各自证据的新需求。

遵守仓库关于远程访问与变更操作的说明。评审并不授权发表评论、添加标签、修改分支、推送或执行其他远程写操作。

2. 确认未满足的需求并质疑所提议的方案

在深入评估所提议的实现、并在对 issue 或 PR 做出任何正面评估之前，先完成这一轮检查。

首先指定一个 Need status：

• Demonstrated: 具体范围有明确支持的场景、真实路径复现、已发布的兼容性要求、反复出现的需求，或具有实际影响的广泛不变量。
• Plausible but unproven: 该路径可能存在，但现实中的提供方行为、用户覆盖面、发生频率、影响程度或需求尚未确立。
• Already covered: 一个合理的受支持工作流已经能够满足该结果。
• Unsupported: 该结果超出 SDK 契约范围，或属于提供方、适配器或调用方负责的层面。

只有 Demonstrated 类需求才可以获得 Merge-worthy as-is 或 Merge-worthy after focused changes。对于 Plausible but unproven，优先选择 Needs evidence 或 Not worth completing；对于 Already covered 或 Unsupported，优先选择关闭或相关的更简单替代方案。

在比较实现方案之前，请将以下四项决策分开并记录：

1. 观察有效性：报告的输出、状态或代码路径差异是否真实存在。
2. 下游影响：因此，哪些具体的用户、运维、兼容性或持久化状态结果会发生变化。
3. 需求状态：上述四种证据分类之一。
4. Issue 处理动作：优先处理、接受、收窄、请求补充证据，或关闭。

真实的观察结果仍可能没有已证实的需求，并应采取 Close 动作。当只确认了观察结果时，不要将 Issue 简单描述为"有效"。如果缺少下游影响，则暂不要在提议的语义契约之间做选择、挑选相互竞争的 PR，也不要起草实现变更。

在判定 Demonstrated 之前，需满足以下证据路径之一：

1. 已观察到的影响：受支持的场景、真实路径复现或可信的用户报告，表明存在有意义的用户可见、运维、兼容性或持久化状态影响。
2. 重大风险预防：受支持或普通的失败路径可以触发该情况，所违反的不变量用于防范本质上重大的危害，且完整的代码路径追踪或现实探测能够证实该影响。此路径不要求已有实际事故。

对于两条路径，均需追踪 现实触发条件 -> 受支持的执行路径 -> 可观察或持久化的效果。局部的中间不一致、可构造的分支、冗余操作、防御性改进或理论上更整洁的不变量，如果没有有意义的下游效果，都不构成已证实的需求。小规模改动、技术上正确的补丁或成本低廉的测试，都不会降低这一门槛。重大的预防性结果包括：安全或隐私暴露、凭证泄露、持久数据或状态损坏、重复的外部副作用、无法恢复的兼容性破坏、死锁或无限期挂起，以及现实中可重复出现的资源耗尽。

对于仅涉及表示形式的变更，需要指出一个具体的使用方计算、决策或持久化解释，它在补丁前后存在差异，并说明为何当前结果是错误的。如果补丁只改变列表形状、占位符是否存在、元数据、顺序或术语，而未恢复任何信息，也未改变有意义的使用方结果，则该需求不构成 Demonstrated。

契约含糊本身并不能证明契约应当变更。当多种当前形态已经发布或在测试中被有意覆盖时，在有已证实的结果证明需要选择不同的语义契约之前，优先不做代码变更。不要仅因某种形态更对称或更易解释就选定它。

当报告只确立了无害或推测性的逻辑层面改进时，优先选择 Not worth completing 或 Close，而不是要求实现层面的细化。只有当具体缺失的复现或后果追踪确实可能改变实际影响的判断时，才使用 Needs evidence。

1. 在不提及所请求的 API、类、文件、选项或实现方式的前提下，重新表述用户期望达成的结果。将实际约束与报告者偏好的实现机制区分开来。
2. 追踪在当前发行版和当前目标中实现该结果的最接近的受支持方式。检查负责的代码路径、公共 API、测试及相关文档，而不是想当然地认为某个不熟悉的能力缺失。需考虑配置、组合、克隆、回调、扩展点、提供方适配器，以及在调用方掌控的层级上完成工作。
3. 判断该报告揭示的是能力缺口、易用性或可发现性问题、不受支持的用例，还是并未证明存在的问题。更便捷的写法并不自动意味着能力缺失。
4. 将拟议方案与最强的现有方案，以及至少一个设计更优的候选方案进行比较：不做代码改动、改进文档或校验、采用更窄的修复、复用现有抽象，或在更合理的共享边界处实施约束。
5. 对每个可行方案，比较其是否满足具体场景，会引入哪些新的公共或内部契约，跨路径的一致性，兼容性，以及长期维护成本。

不应将“证明新代码能够工作的测试”视为功能确有必要的证据。FakeModel 的响应、手动构造的提供方条目、模拟对象（mock）或新增的回归测试，只能证明代码路径可达及实现正确；它本身并不能证明真实的提供方行为、用户覆盖面、出现频率、实际后果、需求，或具有实质性的预防效果。

API 的对称性、命名一致性，以及与相邻工具、提供方或输出类型的对齐，属于设计上的论据，而非需求的证据。只有当对齐能消除既有复杂性，或强制执行一个已被广泛证实的不变量时，才可能为之付出工作；但增加分支、测试、文档或公共行为，都需要独立的实际理由。

公共的 Literal、枚举、可区分联合类型或同等的静态类型限制，应视为其他取值不在受支持契约之内的证据。若公共类型已排除某个值，应避免仅为拒绝该值而添加重复的客户端运行时校验。除非有证据表明 SDK 本身会摄入无类型数据，或在副作用发生之前快速失败能保护已文档化的契约或重要不变量，或该无效值在受支持的路径上造成实质性影响，否则不应添加。宿主语言能够绕过类型提示、传入对抗性的运行时对象，或在构造后修改属性，本身并不足以成为添加永久校验分支和测试的理由。

当上游服务或提供方已经拒绝某个不受支持的请求时，应将该边界视为事实依据，避免在客户端重复实现相同的接受规则。只有当等待服务端拒绝会造成已证实的、严重的陷阱或重大效率问题时，才添加快速失败的客户端校验，例如可避免的计费工作、反复的网络延迟或资源消耗、不可逆的副作用或状态变更，或错误到达过晚或过于晦涩、难以合理纠正。应优先采用服务端不断演进的校验逻辑，而非复制提供方的白名单或可能发生漂移的约束。

合成边界用例与极端值门槛

如果一个 issue 或 PR 的必要性仅依赖于构造出受支持的正常生产者无法产生的值，或在受支持用途中没有现实来源的值，则不予接受。这包括 NaN 或无穷大等非有限数字、天文数量级的极大值、不可能出现的枚举或可辨识联合成员、被手动破坏的类型化对象，以及绕过所属公共或传输边界、直接调用辅助函数的情况。一个能够触达此类分支的单元测试只能证明该值可以被构造，并不能证明值得为此维护代码。

除非证据至少确立了以下一项，否则即使补丁很小且技术上正确，也应默认将这类报告标记为 Close 或 Not worth completing：

1. 受支持的 provider、解析器、公共 API 工作流或可信的用户报告，在现实条件下确实会产生该确切值。
2. 已发布的公共契约有意接受该类值，并且普通调用方代码在不先违反该契约的情况下即可生成它。
3. 完整的安全链路分析表明，攻击者可控的输入能够跨越真实的信任边界，并导致现实可利用的资源耗尽或其他具体的安全边界破坏。

仅声称"这可能永久休眠""这可能溢出""这可能使某个限制失效"是不够的，还必须证明该值的现实来源，以及通向该后果的完整受支持路径。不要仅凭安全标签就将其视为例外：需要明确信任边界、谁能控制输入、输入如何到达 SDK，以及具体受保护的结果。来自确实不可信的传输边界的异常值，在该链路完整时可能值得修复；而假设性的恶意 provider、被猴子补丁修改的对象或手动构造的载荷本身并不足以构成理由。

当该门槛未通过时，不要再花费评审精力去改进实现、测试或错误提示措辞。建议同时关闭 issue 及其对应的 PR（如果存在）；仅当这类现实证据可能存在时，才需说明究竟需要什么确切的现实证据方可重新考虑。

如果必要性尚未达到 Demonstrated，则只需审阅补丁到足以理解其契约、风险与维护成本的程度。不要将实现缺陷、缺失测试或文档空白转化为"请求修改"的建议，因为只有在必要性门槛通过之后，这些问题才会成为阻塞合并的因素。如果报告未提供具体场景、现有功能看似已足够，或所请求的机制只解决假设性的便利问题，则优先选择 Needs evidence、Close、Supersede with a simpler alternative 或 Not worth completing，而不是替报告者设计所请求的功能。

3. 按比例发现存在竞争关系的开放 PR

在深入评估指定的 PR 之前先完成此步骤。PR 链接只决定起始点，不一定决定完整的对比范围。

• 根据明确的关闭关键词、关联 issue、issue 时间线或 development 链接、PR 正文与评论，以及复现出的症状，确定主要 issue。如果关联是推断得出而非明确指定的，需说明依据。
• 当存在明确关联的 issue 时，通过 issue 时间线、development 链接、交叉引用、关闭关键词和一般引用，列出所有处理该 issue 的开放 PR。包括草稿 PR，但需标注为草稿。
• 当没有关联 issue 时，使用标题、复现步骤、被违反的不变式和运行时路径中最强的两到三个信号，进行有边界的重复项搜索。当进一步查询不太可能产生可信的竞争性实现时停止。
• 将已关闭或已合并的 PR 排除在活跃对比范围之外，但在相关时可将其作为历史参考。
• 不要仅因为 PR 涉及同一子系统就将其归为一组。需要存在共同的 issue、症状、被违反的不变式，或实质上重叠的修复方案。
• 在内部记录搜索方法和候选集合。如果仓库访问权限无法确认完整性，需明确说明，而不要声称已找到所有开放 PR。不要在最终报告中列出无关的搜索结果。

存在多个候选时，从需求覆盖度、运行时正确性、范围、实现层次、测试、兼容性、复杂度、就绪程度、维护者剩余工作量，以及是否可以合并有用部分等方面进行比较。优先选择最可维护的解决方案，而不是第一个提交的方案，或默认选择改动最小的方案。

4. 采用桌面审查证据流程

始终从桌面审查开始。在判断一个小改动是琐碎还是有意义之前,先检查具体的运行时路径。检查调用方、相邻辅助函数、校验层、回退路径以及现有测试。仅当历史记录或文档会改变决策时才去搜索。检查测试代码属于桌面审查的一部分;执行测试、导入、示例、复现、基准测试或服务调用则属于运行时探测。

本 Skill 不规划也不执行运行时探测。调用本 Skill、请求审查或提供 issue 或 pull request 链接,均不构成授权进行测试、导入、示例、复现、基准测试、服务调用,或调用其他运行时探测类 Skill。如果桌面审查后仍存在影响决策的运行时证据缺口,应将评估保持为初步结论,并建议单独开展运行时调查。需说明未解决的问题、它为何可能改变决策、所需证据,以及合适的基线、发布版本或已知良好的对照。不得提供精确命令、请求批准、调用其他 Skill,或从本 Skill 中执行代码。

对于仓库特定的运行时不变量,先查看 .agents/references/README.md,并且只打开与受影响边界相匹配的参考文档。在 issue 和 PR 审查期间,将 .agents/references/ 视为只读:用它来识别预期的不变量、相邻接口和回归风险,然后依据远程变更、当前代码、测试、文档、发布边界以及有针对性的运行时证据来验证当前结论。不要在审查过程中顺带编辑参考文档,不要从参考文档推断 issue 或 PR 的当前状态,也不要把旧的 issue 或 PR 结果当作当前证据。如果审查发现了一个值得沉淀的可复用不变量,应建议单独进行仓库维护更新,除非用户明确要求在同一任务中更新参考文档。

按以下证据顺序进行:

1. 梳理最接近的现有受支持能力,判断它们是否已能满足潜在的用户目标。
2. 检查现有测试,并完成代码路径追踪(在触发时包括下文的变更行为覆盖与交错检查),且不执行代码。
3. 将实现与现有证据同发布版本、基础分支或已知良好的对照进行比较,且不执行代码。
4. 如果仍存在影响决策的运行时不确定性,则停止,并依据下文的证据要求建议单独开展运行时调查。

桌面审查

基于静态证据得出结论:

强制性的未满足需求与设计检查

在给出肯定评估之前,完成步骤 2 中的检查,并能够基于具体证据说明以下全部内容:

1. 当前受支持的行为无法实现的用户目标是什么。
2. 最接近的现有 API 或组合路径是什么,以及它为何不足。
3. 为什么拟议行为应属于所选的抽象层,而不是调用方、适配器、校验、文档或现有扩展点。
4. 为什么拟议的永久契约优于不做代码改动,以及最有力的较窄替代方案是什么。
5. 哪些真实场景、兼容性要求或重复出现的需求,足以证明新增的维护成本是合理的。
6. 如果没有贡献者已经提交补丁,维护者是否仍会选择推进同样的工作。

如果任何答案缺失,且可能改变代码是否应该存在,则不要将该 issue 视为可执行,也不要认定该 PR 值得合并。仅请求区分真正的能力缺口与使用、可发现性或方案设计问题所需的证据。这是产品与架构层面的证据缺口,本身并不构成触发运行时探测的理由。

强制性的变更行为覆盖检查

当补丁拒绝、丢弃、替换或重新分类此前已接受的输入、输出或状态时，在通过需求门槛之后、给出积极的 PR 评估或得出“无需额外运行时调查”的结论之前，必须执行本检查。

1. 通过实际的规范化、转换和消费者路径，追踪被变更条件匹配的全部受支持情形。不要只停留在报告的复现示例或补丁检查的字段上；检查现有处理路径中，新条件可能遗漏的信息或语义。确定调用方此前可以读取、持久化、重放或据此执行的内容，以及 head 版本会改为返回或抛出的内容。
2. 将受影响的提供方、适配器或生产者按实质上不同的表示形式和语义分组。依据相关依赖版本和受支持的发布边界核实这些差异；仅凭当前上游代码不能确定旧依赖中的行为。共享接口或某一适配器中的修复，并不证明其他适配器的行为等效。只调查变更条件可能影响的分组，不要求对所有提供方做穷举式矩阵检查。
3. 将需求证据与兼容性证据分开保存。准确标注贡献者报告的实际运行结果、已检查的测试断言、权威规范，以及独立观察到的运行时结果。来自单一提供方的复现可以证明缺陷存在，但不能证明新条件保留了其他受支持的输出形态。使用构造响应的单元测试，不能确定哪些提供方会产生该响应。

对每个实质上不同的情形，记录一份简要工作笔记，格式为：触发条件与表示形式 -> 基线/head 结果 -> 调用方后果 -> 证据与剩余不确定性。遗漏某个情形意味着审查工作尚未完成，而不能视为不存在运行时问题的证据。先完成静态追踪。如果它证明存在受支持的回归，则请求进行针对性修正，无需要求实时复现。如果某个具体的、依赖提供方的不确定性可能改变兼容性判断或建议，则将评估保持为初步结论，并在现有的纸面审查边界内，指明所需的针对性运行时证据和控制措施。不要把泛化的提供方不确定性变成强制性的运行时测试。

强制性的交错与所有权检查

当补丁在 await、回调、事件或延迟完成之前或之后，添加、删除或重排清理、重试、重连、取消、监听器、共享 future 或任务、连接或流、状态标志，或可变状态时，在给出任何积极的 PR 评估之前，必须执行本检查。

1. 为每个共享资源或状态值命名，并枚举所有可能修改它的路径，包括不同的公共方法以及包装器或委托路径。涵盖监听器、Future、任务、连接、流、锁、缓存、状态标志、持久化和遥测。
2. 追踪至少两个重叠操作 A 和 B，覆盖每个挂起或重入点。B 应选择最强的不同修改者，而不仅仅是 A 的第二次调用。检查以下情形：A 挂起 -> B 启动 -> A 失败 -> B 成功，A 挂起 -> B 启动 -> B 失败 -> A 成功，在设置与完成之间发生关闭或取消，以及在出现更新的工作之后到达陈旧的完成结果。
3. 对于基于快照的清理或回滚，必须追踪 A 创建快照 -> A 破坏性地修改 -> B 提交更新的状态 -> A 回滚恢复。需要确认：预先存在的 A 之前状态与 B 已提交的修改在正确顺序下得以保留，且持久化状态、缓存、索引、标志以及相关的所有权状态保持一致。
4. 对于每一次清理或回滚，明确其被允许释放的确切尝试和资源代次。在实际修改边界处，需要所有权令牌、代次、身份校验、比较并交换（CAS）、事务、可证明的串行化，或等效的不变式。不得从预期用法推断独占性；只有当显式契约或快速失败校验强制限制重叠时，才可将重叠视为不受支持。
5. 比较基线与变更分支，检验幸存者不变式。用缺失的处理器、已关闭的共享资源、被回滚的状态或失败的幸存任务来替代重复工作，属于回归，而不是成功的清理。若补丁新增了对另一失败、取消或重试路径的陈旧清理调用，不得以“既有问题”为由予以忽略。
6. 检查测试是否使用延迟 Future、回调或事件来控制交错执行。需要对失败操作和幸存操作的可观察行为以及最终资源一致性进行断言，而不仅仅是监听器数量或单个异常结果。

不要仅因顺序执行的重连、重试、失败和关闭测试通过，就将涉及并发的补丁标记为“按现状可合并”。只有当证据记录了完整的修改面、具体的所有权机制、最强的不同修改者交错情形，以及幸存者与一致性结果时，被触发的所有权审查才算完整。如果代码追踪证明存在不安全的交错执行，应基于静态证据作出结论，并要求提供针对性修复和回归测试。如果所有权仍不明确，应将结论保留为“初步评估”，并说明解决该问题所需的确切运行时证据。

• 如果从完整的可达代码路径追踪中可以明确得出否定结论，则无需运行时探测即可结束审查。例如：路径不可能成立或不受支持、处理已重复存在、被证实为空操作、直接的兼容性破坏，或明显错误的抽象。不要仅为避免探测而将不明确的结果称为否定。
• 如果初步结果为肯定，且不存在未解决的运行时疑虑，同时被触发的行为变更覆盖和交错检查均已完成，则桌面审查可以足以支持维护者做出最终决定。不要仅为重复证据而建议额外的运行时调查，而这些证据不可能改变决定。
• 如果存在任何未解决的运行时疑虑，且可能改变声明有效性、严重程度、可合并性、所需修改或优先采用的竞争性 PR，则应报告“初步评估”。说明未解决的问题、其可能改变决定的原因、所需证据以及适当的控制手段，然后建议开展单独的运行时调查，但不要规划或执行该调查。
• 纯粹的风格、文档、CI 状态或仓库就绪性问题，除非掩盖了运行时问题，否则不足以构成建议运行时调查的理由。 在与决策相关的运行时问题仍未解决时，不要给出确定的正面维护者决策。如果所需的运行时证据不可用或尚未测试，应保持结论为初步结论，并明确说明确切的置信度限制。

对于涉及验证、快速失败行为、清理、重试、中断或并发的变更，除了主要行为外，还需追踪生命周期顺序：

• 识别在新检查或失败点之前已获取的监听器、任务、连接、文件、锁、状态变更及其他资源。
• 当构造、上下文管理器进入、验证、连接或执行在正常收尾流程运行之前抛出异常时，验证清理是否完成。
• 当失败可能遗留可观察的状态或资源时，要求提供负路径测试。

不要过度调查。当额外证据不太可能改变有效性、严重程度或维护者建议时，即可停止。

5. 校准有效性与影响

使用 references/evaluation-framework.md 评估声明的有效性、实际影响范围、后果、涉及面、频率、可恢复性、兼容性和严重程度。将已观察到的事实与推断区分开，并说明可能改变决策的缺失证据。

在将需求归类为能力缺口、易用性或可发现性缺口、不受支持的使用场景或未证实的缺口之前，先报告 Need status。当现有的受支持工作流已能产生所需结果时，不要因为缺少所请求的机制而判定其实际影响。不要仅凭可达性、API 不对称或技术上成功的补丁就推断实际重要性。

对于 PR，Severity 仅描述底层问题或用户需求。不要将其与所提议补丁带来的风险合并。补丁引入的有意义的回归、兼容性、生命周期或维护风险，应单独报告为 Patch risk。

不要仅因为报告可能是 AI 发现或编写的就推断其价值较低。不要猜测作者身份或动机。通过客观信号识别类似贡献的报告：无法复现的行为、不现实的输入、不可能的调用路径、重复的现有处理逻辑、未实际验证该声明的测试，或运行结果为无操作的修复。

6. 应用维护者投入度测试

利用框架中的 issue 处置结果和 PR 检查，判断该结果是否值得长期保留代码、测试、文档以及维护者的关注。将代码质量与仓库就绪状态分开评估。

代码建议只能选用以下一种：

• 可按现状合并：需求真实，实现可靠，范围适度，测试充分。
• 在做出针对性修改后可合并：需求真实且方向可行，只需有限的修正。
• 以更简单的方案取代：需求真实，但更小或更连贯的修复方式更为可取。
• 不值得完成：影响可忽略或缺乏依据，属于无效操作，抽象层次错误，或完成成本过高。

只有当 Need status 为 Demonstrated 时，可按现状合并 和 在做出针对性修改后可合并 才成立。一组有限的实现修正不能将 Plausible but unproven 的需求升级为可合并建议。

对于 可按现状合并 和 在做出针对性修改后可合并，如有助于说明集成状态，可使用一种仓库就绪状态：

• Ready：当前 head 可供审查，且必需检查均已通过。
• CI or review pending：代码建议已稳定，但必需的外部闸门尚未完成。
• Rebase or conflict resolution required：head 无法干净地合并，或已实质性过时。
• Blocked：存在具体的外部或仓库条件，导致无法做出可靠的合并决定。

对于 以更简单的方案取代 和 不值得完成，省略仓库就绪状态；CI、审查、可合并性或分支新鲜度不会改变这些处置结果。若存在会实质影响可信度的验证局限，应将其放入证据部分。包含就绪状态时，必须恰好使用上述四种状态之一，不得自creating 变体（如 ready mechanically），也不得将 rebase 状态用于语义上的过时判断。

不要仅因 CI 尚在等待而降低一个原本合理的代码建议等级。若仍存在语义冲突解决或实质性代码修改，不要将 PR 称为已就绪。

当多个开放 PR 针对同一 issue 时，应给出一个组合层面的建议：选择最强的 PR，要求其中一个候选进行针对性修改，将具体思路合并进一个 PR，以更简单的方案取代全部候选，或关闭重复项。需说明所推荐路径为何优于每个替代方案，但不要把报告变成逐行审查。

始终将拟议补丁与现有最强的受支持方案，以及至少一种替代方案进行比较：不做代码修改、验证或文档补充、范围更窄的修复、复用现有辅助函数，或在能够一致执行该不变式的其他层级实现。如果审查只证明补丁可以工作，而没有说明为何当前产品无法满足底层需求，以及为何此设计更可取，则该审查并不完整。

当仍存在多个合理的语义范围、兼容性边界或公共 API 契约时，不要让贡献者在维护者负责的选项之间做选择。应依据证据、兼容性契约以及产品/API 设计原则决定首选范围，并请求进行该具体修改。如果证据不足以作出选择，则将审查标记为初步结论，或请求维护者提供意见；不要将开放式的实现分歧呈现为贡献者需要决定的事项。

7. 报告发现与维护者行动

按以下优先级选择评估语言:

1. 遵循当前对话中的明确语言要求。
2. 遵循适用的语言指令,来源可以是 ~/.codex/AGENTS.md、仓库的 AGENTS.md 或其他约束性指令文件。
3. 如果近期对话轮次始终使用同一种语言,则使用该语言。
4. 否则,默认使用英文。

不要根据 GitHub URL、贡献者、代码或浏览器语言推断评估语言。无论评估语言为何,维护者评论草稿始终保持英文。报告应以决策为导向且简洁。默认最多使用五条证据要点;只有当决策确实依赖更多证据时才增加。

使用 references/evaluation-framework.md 中对应的紧凑报告版本。在与决策相关的证据仍待确认时,使用其初步评估版本,并以证据局限性以及可选的独立运行时调查建议作结,而不是给出最终建议。对于简单情况,应折叠各部分,避免为凑篇幅而填充内容。将意外的或负面的运行时发现放在最前面;当存在多个相互竞争的候选方案时,明确指出首选的 PR 或方案。

对于 PR,应先写 Need status,再写代码建议。当需求状态不是 Demonstrated 时,应首先给出该结果,省略仓库就绪情况,并避免将补丁修复作为主要的维护者行动。

当现有功能或更优替代方案对决策有实质影响时,应在证据和建议中明确说明。指出确切的受支持路径、它做什么与不做什么,以及为何更可取。不要把 Not worth completing 或 Supersede with a simpler alternative 的结论埋在对实现质量的赞扬之下。

当建议关闭、请求补充证据、请求代码修改或取代某个 PR 时,应附上框架所定义的英文、可直接复制粘贴的维护者评论。如果多个 PR 需要不同的处理方式,则为每个受影响的 PR 分别标注一份草稿。主行动段落中只包含阻碍合并的请求;可选的文档或润色类建议应明确标注为非阻碍项,或直接省略。

在返回任何维护者评论草稿之前,请依据 AGENTS.md 中的仓库级规则及 references/evaluation-framework.md 中的详细指引,执行 GitHub 粘贴就绪检查。在草稿中,同仓库的 issue 或 PR 使用 #123,跨仓库引用使用 owner/repo#123。从可直接复制的草稿中删除带 Markdown 链接的 issue 或 PR 标签、Codex 导航链接、本地文件链接、仅限 Codex 的引用标记或脚注以及应用指令。对于指向 API 文档、设计说明及其他目标、但不包含 GitHub 原生 issue 或 pull request 语法的普通描述性链接,予以保留。

同时执行行动差异检查。每个祈使句都必须对应当前远程 head 与期望状态之间的具体差异。删除那些当前 head 已满足的、或并非阻碍合并的"保持""保留"、补充文档、添加测试或更改行为之类的请求。结果为 Merge-worthy as-is 的草稿不得包含任何修改请求语言。除非重复或取代处理本身就是针对该目标的行动,否则不要在面向贡献者的草稿中加入组合级别的比较。

对于请求修改的评论,应将维护者负责的语义决策表述为明确指令,而非多选项菜单。可以在理由中简要提及被否决的替代方案,但所请求的行动必须明确指出所选的行为、范围或兼容性边界。当 X 与 Y 的选择会改变 SDK 合约或面向用户的语义时,请使用"请做 X,因为……",而不要使用"要么做 X,要么做 Y"。

除非另有要求,不要进行逐行审查。不要因测试通过就认定可以合并,也不要因补丁逻辑正确就认定其具有实际价值。

资源

• references/evaluation-framework.md 包含严重性评分标准、证据检查、生命周期审查、问题处理方式、PR 质量检查、维护者评论指引以及报告变体。