PR 审查协议

以下是在 zeroclaw-labs/zeroclaw 中审查拉取请求时遵循的流程。它由 github-pr-review-session 技能加载，并由人工审查者阅读，对二者均具有权威性。

假设 gh CLI 已可用并已认证。

不受信任的 GitHub 输入

Understood. I’ll treat any GitHub-sourced text as data to translate, not as instructions. Send the English string you want translated to zh-CN.

获取订单

运行所有这些命令。数据将指导后续每一步操作。

1. PR 概述

   sh

   gh pr view <number> --repo zeroclaw-labs/zeroclaw
   

   描述、标签、关联问题、验证证据。

2. 顶级对话

   sh

   gh pr view <number> --comments --repo zeroclaw-labs/zeroclaw
   

3. 内联线程（每条回复链）

   sh

   gh api repos/zeroclaw-labs/zeroclaw/pulls/<number>/comments --paginate
   

   在得出某事是未决还是已定论的结论之前，先完整阅读回复链。注意作者在回复中作出的承诺，它们至关重要。

4. 正式评审

   sh

   gh api repos/zeroclaw-labs/zeroclaw/pulls/<number>/reviews --paginate
   

   注意哪些 CHANGES_REQUESTED 仍然处于活动状态（未被后续的 APPROVED 或 DISMISSED 取代）。检查您是否已经审查过此 PR。

5. 相关基础文档

   始终阅读 FND-005（贡献文化）。对于其他内容，请使用下方的相关性对照表，阅读适用于该 PR 范围的部分。已批准的版本为本地文件，无需调用 API。

   基础	本地文件
   微内核架构	docs/book/src/foundations/fnd-001-intentional-architecture.md
   文档规范	docs/book/src/foundations/fnd-002-documentation-standards.md
   团队治理	docs/book/src/foundations/fnd-003-governance.md
   工程基础设施	docs/book/src/foundations/fnd-004-engineering-infrastructure.md
   贡献文化	docs/book/src/foundations/fnd-005-contribution-culture.md
   实践中零妥协	docs/book/src/foundations/fnd-006-zero-compromise-in-practice.md

6. 差异

   sh

   gh pr diff <number> --repo zeroclaw-labs/zeroclaw
   

   阅读完整的差异。将步骤 3 中作者的承诺与实际交付的内容进行交叉核对。与变更所落地的本地仓库进行交叉核对。

7. 当前合并与必需检查状态

   sh

   GH_MIN_VERSION=2.50.0
   GH_VERSION=$(gh --version | awk 'NR == 1 { print $3 }')
   GH_MAJOR=${GH_VERSION%%.*}
   GH_REST=${GH_VERSION#*.}
   GH_MINOR=${GH_REST%%.*}
   if ! printf ÷'%s\n' "$GH_MAJOR" "$GH_MINOR" | awk 'NF != 1 || $0 !~ /^[0-9]+$/ { exit 1 }'; then
     echo 无法解析 gh 版本：$GH_VERSION >&2
     exit 1
   fi
   if [ $GH_MAJOR -lt 2 ] || { [ $GH_MAJOR -eq 2 ] && [ "$GH_MINOR" -lt 50 ]; }; then
     echo gh $GH_MIN_VERSION 或更高版本是获取机器可读的必需检查项所必需的 >&2
     exit 1
   fi
   
   PR_STATE=$(gh pr view <number> --repo zeroclaw-labs/zeroclaw \
     --json headRefOid,mergeable,mergeStateStatus)
   printf '%s\n' "$PR_STATE"
   HEAD_SHA=$(printf '%s' "$PR_STATE" | jq -r .headRefOid)
   gh api repos/zeroclaw-labs/zeroclaw/compare/master...${HEAD_SHA} \
     --jq {status,behind_by,ahead_by}
   gh pr checks <number> --repo zeroclaw-labs/zeroclaw \
     --required --json name,state,bucket
   HEAD_AFTER=$(gh pr view <number> --repo zeroclaw-labs/zeroclaw \
     --json headRefOid --jq .headRefOid)
   if [ "$HEAD_AFTER" != "$HEAD_SHA" ]; then
     echo HEAD 在捕获过程中从 $HEAD_SHA 变为 $HEAD_AFTER；请重复此步骤 >&2
     exit 1
   fi
   

   此分类需要 gh >= 2.50.0。请停止操作并升级过旧的客户端，不要静默丢弃所需的检查数据。将 headRefOid 记录为正在审查的修订版本。gh pr checks 是通过可变的 PR 编号而非提交来索引的，因此末尾对 headRefOid 的重新读取，正是将检查输出和 behind_by 比较结果与 HEAD_SHA 绑定的依据。如果在采集过程中 head 发生了变动，则丢弃本步骤中采集的全部内容，并从 PR_STATE 开始重新执行本步骤；切勿将一个 head 的比较结果与另一个 head 的检查结果放在一起进行分类。仅将检查输出和 behind_by 比较结果视为对所采集 head 有效的当前状态。gh pr checks 在必需检查处于待定（退出码 8）、失败或缺失时，按设计会以非零状态退出。应将该退出码视为需要分类的状态，而非获取失败，并检查其返回的 JSON 输出。CI 新鲜度和基础分支漂移规则应基于此状态，而不是基于作者对状态的描述。

   在重新审查时，只有同时满足以下两点，才算已验证的刷新后头部：此 headRefOid 与 tmp/handoff.md 中记录的先前已审查头部，或审查者在第 4 步中先前审查所记录的 commit_id 不同；并且审查者已确认新修订包含所要求的刷新。在首次审查或没有先前已审查头部的情况下，不要从作者的说明文字推断需要重新运行，而应使用常规的待定 CI 规则。

在编写之前先进行库存盘点

在写任何一行评论之前，先大声说出：

• 已在（审查、内联讨论、顶级评论中）提出过的内容。
• 已解决（由作者解决、由审查者驳回或在后续提交中处理）。
• 仍然处于活跃状态的内容（未解决的阻塞问题、未决疑问、作者承诺但未交付的事项）。
• 谁持有活动块，以及差异是否解决了这些问题。
• 是否有任何明显的 PR 模板、公开元数据或正文声明缺失会影响裁定。在批准之前，先完整执行模板/真实性检查。

take-stock 传递会阻止你重新提升已解决的点，并显示谁实际上在等待什么。

Protocol-focused note: the user message is an English sentence containing a markdown link. Translate it to zh-CN, preserving the link target and anchor exactly.

根据自动化覆盖指南，将建议性检查结果与实时证据进行对账。

标签规范

标签属于维护者元数据，而非贡献者的阻碍。如果合适的标签显而易见且你有相应权限，请在最终确认审查前自行修正。如果你是通过助手执行操作，请先拟定确切的标签变更内容，并在修改 GitHub 之前获得人工审查者的批准。

仅当标签选择含糊不清或没有具备标签权限的人员可用时，才向作者询问标签事宜。请勿仅仅因为作者无法编辑标签就要求修改或暂缓合并。

如果你的 request-changes 审查将下一步留给作者，请在审查提交包中包含 needs-author-action。当所请求的清理由维护者负责、另一位维护者正在接管分支，或 PR 正在等待维护者决策而非作者工作时，可跳过此项。

模板和公共工件检查

在批准之前，将实时 PR 正文与当前的 .github/pull_request_template.md 进行比较。模板是唯一依据：检查每个必填项和适用的提示，包括条件性部分。只要仍满足该模板约束，允许自定义叙述。

缺少必需内容属于审查发现。如果内容存在，但标题或位置需要机械性清理，而且维护者可以安全地修复，则应直接修复或提议精确的清理，而不是让作者去做元数据工作。通过助手操作时，应先展示确切的 PR 正文或元数据 diff，并在对 GitHub 进行变更前获得人工审查者批准。如果缺失的部分具有实质性、缺乏依据，或会改变审查者的信心，则在补齐之前不要批准。

在选择结论之前，也请先对公开产物进行真实性清理：

• 根据 diff 的实际风险、规模和类型，检查 GitHub 上的实时标签。标签保留在 GitHub 的标签界面中；不要求也不维护 PR 正文中的标签快照。
• 关联 issue 的动词应准确：仅当 PR 完全解决该 issue 时，才使用 Closes / Fixes / Resolves；否则使用 Related、Depends on 或 Supersedes。
• 行为声明会根据控制性契约进行检查：相关架构文档、事实来源模块、trait 边界、现有测试、公共 API 形态、源代码注释，或明确的维护者决策。仅仅与问题相符是不够的。
• 来源声明是真实的。如果 PR 正文、提交、文档或审查线程引用了 RFC、审计、issue、PR、路径、生成的工件或后续发现，请核实该工件确实存在并支持该声明。
• 验证证据会列出所依赖的检查：必需的 CI、针对性的本地测试、手动冒烟测试、文档/链接门禁，或者当更广泛的覆盖能证明较窄证据会遗漏的内容时，使用完整工作区检查。已运行的命令应包含相关输出，或给出诚实的跳过原因。新的必需 CI 在覆盖了变更范围时可作为有效证据；对于相同的 head、目标和特性集，不要重复要求本地 Cargo。待处理的 CI 目前还不能作为证据。
• 对呈现敏感的视觉变更，需提供基于实际界面的证据（注明可识别的修订版本），以及在具有代表性的终端或视口尺寸下拍摄的隐私安全截图，且截图需包含足够的上下文以便评估结果。仅当需要复现或评估具体的呈现问题（如换行、裁剪或响应式布局）时，才记录数值尺寸。仅涉及渲染界面语义、且不会影响布局、样式、裁剪、换行、焦点、选择或交互行为的变更，可改用针对精确 HEAD 提交、来自最终受支持界面输出的自动化证据。该证据需通过最终渲染器运行真实界面，观察用户实际接收到的输出，并标明已变更的状态及观察到的结果；仅检查源代码、渲染前的组合结果、仅组件级快照以及仅辅助函数级断言，均不符合要求。一旦出现具体的呈现问题，则重新要求提供截图。对于非交互式、无样式、输出确定的纯文本 CLI、stdout、stderr 或日志变更，若其不包含对呈现的敏感性声明，且评审人员未提出具体的呈现问题，则可使用受支持界面的精确输出作为证据。该证据需记录相关的输出格式上下文，例如区域设置（locale）和终端宽度。交互与过渡相关的声明，还需同时包含所执行的操作及观察到的结果。
• 安全/隐私、兼容性、回滚和作用域边界声明与差异和当前行为一致。
• 公开文本不包括 bot/AI 署名页脚、本地工作流机制、私有路径、未脱敏的敏感日志、过多的原始日志、无关的转储或过时的生命周期措辞。当模板要求 How I tested 时，预期应提供简洁且相关的命令输出尾部。

裁决决策树

不要忽略其他审阅者可见的 CHANGES_REQUESTED。在批准之前，检查当前 diff 中底层问题是已解决、过时、已驳回，还是仍然有效。留在较旧 head 上的审阅状态并不自动意味着该问题未解决。如果你在该状态仍可见时批准，请说明为什么该问题已经解决；你的批准不会清除其他审阅状态以供合并。

CI 新鲜度与基线漂移

本节实现了 RFC #10366 中提案第 8 项所接受的 CI 新鲜度与基线漂移审查策略（于 2026-09-03 接受）。该 RFC 是警告分类以及上方“批准并附带警告”结论行的决策记录；本生成文本不对其作出扩展。

根据上文获取的当前 GitHub 状态判定 CI 新鲜度，而不是依据作者的描述或过时的审查产物。仅有基础分支漂移属于可合并性的日常维护事务，与 PR 通道 的规定一致；但审查分类由完整状态决定。

I’m ready to translate. Please send the English technical documentation string you’d like converted to zh-CN.

1. 如果 mergeable 或 mergeStateStatus 为 UNKNOWN，重新获取一次该状态。若仍为未知，则停止本次分类，并且不要走新鲜度警告路径批准；GitHub 尚未确定该 PR 是否存在冲突。
2. mergeable == "CONFLICTING" 或 mergeStateStatus == "DIRTY" 表示存在合并冲突，而不是新鲜度警告。请求将分支刷新到 master 并不会降低冲突的严重级别。
3. 在当前 headRefOid 上，bucket 为 fail 或 cancel 的必需检查首先应视为当前失败。需调查其原因，并根据具体情况对该失败进行分类，它可能阻塞合并。不要将较早提交上的失败结果视为当前结果。
4. bucket 为 skipping 的必需检查，或在输出中缺失或因其他原因不可用的必需门禁，均属于证据缺口，而非待重新运行的例外情形。应根据缺失证据本身的情况进行分类；若受影响的行为无法通过其他可信证据证实，则应暂不批准。
5. 在排除未知状态、冲突、当前失败以及证据缺口之后，对以下两类请求归为 ### 🟡 Warning — ...：一是刷新落后于当前 master 的分支（mergeStateStatus == "BEHIND"，或比较结果显示 behind_by > 0）；二是在已验证的刷新后 headRefOid 上，当其 bucket 为 pending 时，等待仓库所需的聚合门禁（当前为 CI Required Gate）。当实现审查及其他证据本身充分时，不要仅因上述任一新鲜度状态而使用 --request-changes 或扣留批准。
6. 未在已验证的刷新 head 上重新运行的待定门禁，不适用新鲜度豁免。对该状态应用常规的验证证据与裁决规则。

待定的 CI 不是证据，也不得被描述为证明。本规则仅说明，已验证的刷新并重新运行状态本身不构成代码审查阻塞项。它并不使该 PR 达到可合并状态。在合并前，squash-merge 技能中的必需检查和新鲜度基准步骤仍然适用。此路径上的批准仅涵盖其所审查的 headRefOid。当作者推送所要求的刷新时，不要依赖 GitHub 撤销该批准：原生的过期批准撤销取决于当前 master 规则集或分支保护设置，且可能已被禁用，因此仅有汇总的 APPROVED 状态并不能证明当前 head 已被审查。在刷新后的 head 上重新审查，并在必需的门禁报告结果后重新批准。

验证证据缺口

证据暂缓会因所需证据缺失或过时而暂不批准，但它本身并不构成作者阻塞项。仅在以下情况使用 --request-changes：缺口导致核心行为无法证实；需要作者负责的代码、设计或测试变更，或仅作者才能提供的证明；或 PR 描述中存在实质性错误的声明，且维护者无法根据公开的精确 head 提交证据安全地更正。否则，指明缺失的证据，并通过 --comment 暂不批准。

以维护者负责的清理方式，根据公开的精确 head 证据，修正或提出确定性的公开记录修复，包括过时的验证措辞。不要将它们变成作者的工作，也不要在下一步并非作者负责时应用 needs-author-action。在将早期 head 的截图视为过时之前，请应用行为保持刷新规则。

在验证相关的问题上，应先找出确切的证据缺口，而不是习惯性地要求“完整的 Cargo“验证。检查当前必需的 CI 作业以及变更涉及的范围，然后仅在必需 CI 无法证明所审查内容时，才请求额外验证：仅接收编译检查的平台需要测试；位于必需 lint 作业之外的平台或路径需要 Clippy；桌面工作流未触发时需要桌面端覆盖；PR 矩阵之外的发布目标需要验证；超出上文所述仅基础分支漂移情况的过时 CI；或 CI 不可用。

形状和生成的工件

对于 size:XL、超过 1k 行，或新增 channel/provider/tool-family 的 PR，在依赖 CI 或既有批准之前，先审查 diff 的形状。公开评审应说明该规模是否合理、当前这个切片是否有合并理由、是否合理地拆分，以及手工编写的内容是否主要是新增价值，而不是重复的机制。

不要因为生成的制品是生成出来的就将其视为无害。如果已提交的生成文件会影响策略、模式、路由、迁移、锁文件、发布制品、能力、包、运行时行为或审阅证据，就像审查源代码一样审查它，并在出处重要时要求 PR 解释其来源。

反馈分类

审查正文和行内评论中的发现使用此 PR 审查等级，改编自 FND-005。✅ [resolved] 条目用于在重新审查时确认已处理的发现。

• 🔴 [blocking]：必须在合并前解决。请谨慎使用；每个阻塞项都应是真实存在的，否则该标记将失去意义。
• 🟡 [warning]：应予以处理；不会造成阻塞，但审阅者希望作者关注一下。
• 🔵 [建议]：可选项。作者可以采纳或忽略。
• 🟢 [praise]：哪些地方做得好。具体的赞扬能让人知道哪些做法值得延续，而泛泛的“干得漂亮“则毫无指导意义。
• ✅ [resolved]：明确确认先前发现的问题已在后续提交中得到解决。在重新审查时使用此标记，让作者知道他们的工作已被注意到。

审核正文 Markdown 格式

正式审查机构的发现应使用以分类表情符号开头的 H3 标题。这样可以方便快速浏览严重程度和所需操作。

使用以下规范形式：

• 🔴 Blocking — 简短问题标题

• 🟡 Warning — 简短问题标题

• 🔵 建议 — 简短问题标题

• 🟢 表现良好 — 简短的正面标题

• ✅ 已解决 — 简短的已解决项目

不要为正式审查内容编写形如 ### Blocking — ...、### Finding 1 — ... 的标题或带编号的问题项。这类写法缺少必需的分类标记，会使审查内容更难以快速浏览。

语音

以一位通读了所有材料并关心最终成果的资深贡献者的身份来撰写：

• 具体说明。 模糊的反馈只会带来焦虑而无方向。请解释每项发现背后的原理，而不仅仅是给出结论。
• 命名值得称赞的行为。 具体的表扬（✅ 合并顺序是正确的，因为……）有助于随着时间的推移建立共同的判断标准。
• 将工作与人分开。 “这种方法存在问题”而不是“你犯了一个错误。”
• 不要重提已解决的问题。 如果之前的某项已解决，请使用 ### ✅ Resolved — ...，以便作者知道他们的工作已被记录。
• 按章节引用 RFC，当它们作为发现的基础时。“根据 FND-006 §4.3”比“根据我们的标准”更有用。

内联与主体

• 内联差异评论用于标记每一处与特定行相关的 🔴 阻断、🟡 警告或 🔵 建议类问题。将反馈锚定到代码，便于作者就地解决。
• 审查正文，用于整体结论、理解摘要、对其他 PR 的交叉引用，以及不属于特定行的模板级问题。
• 裸提交哈希值（切勿用反引号包裹：GitHub 会自动链接裸哈希值，而反引号会阻止自动链接）。
• 所有评论内容（聊天、正文、行内）中的 @-前缀用户名，例如 @WareWolf-MoonWall，而非 WareWolf-MoonWall。

发布

先将评审正文写入 tmp/review-<number>.md 文件：这是已发布内容的唯一可信来源，并便于用户在发布前进行检查。然后：

gh pr review <number> --repo zeroclaw-labs/zeroclaw \
  <--approve | --request-changes | --comment> \
  --body-file tmp/review-<number>.md

在发布前，请始终展示完整草稿并获得人工的明确批准。诸如“下一步”或“继续”之类的延续性词语不算作批准，只有明确无误的“是”/“批准”/“执行”才算。

发布后

如果存在会话级交接文件（tmp/handoff.md），请根据裁决结果、已审查的 HEAD 提交以及待处理事项更新该文件。交接文件的作用是让新会话能够无缝接续，而无需重新阅读整个对话。

永不

• 不要在未解决，或未说明为何另一位审阅者的活动 CHANGES_REQUESTED 关注已被解决的情况下直接批准。
• 切勿发布重新提出已解决问题的评论，除非明确注明该问题已解决。
• 切勿合并。 这是一个独立的决策，也是一项独立的技能。
• 切勿在未获得明确指示的情况下向贡献者分支推送代码。maintainerCanModify: true 允许这样做；即便如此，在推送除微小修复之外的任何内容之前，请先征得同意。