跳转至

PR 审查流程

本页说明在你打开或更新 OpenClaw PR 后的评审流程：Barnacle 和 ClawSweeper 的作用、如何根据它们的反馈改进 PR，以及当自动化保持安静时应检查什么。

Barnacle 和 ClawSweeper 帮助维护者保持评审队列可用。它们不会取代维护者的判断。

Barnacle

Barnacle 是确定性的 GitHub 分诊。它会查找已知的队列管理情况，并以标签、评论或关闭作为响应。

Barnacle 可能在以下情况采取行动：

  • PR 正文基本为空或缺少问题上下文；
  • PR 没有有用的证据；
  • 仅文档、仅测试、仅重构、仅 CI 或基础设施变更缺少关联的维护者上下文；
  • 变更看起来应属于 ClawHub 或插件，而不是核心；
  • 分支包含无关工作；
  • 作者有超过 20 个未关闭的 PR。

Barnacle 从受信任的仓库工作流代码运行。它不会检出或运行贡献者代码。

大多数路由标签是维护者或自动化信号，因此贡献者不需要自己添加标签。

ClawSweeper

ClawSweeper 是 OpenClaw 仓库的 AI 辅助评审与维护机器人。它可以评审 PR、评估证明、留下持久评审评论，并帮助维护者进行受保护的修复或自动合并流程。

ClawSweeper 的正面结果是支持性证据，而非维护者批准。维护者仍然决定 PR 是否以及何时准备好合并。

ClawSweeper 基于队列。当你打开非草稿 PR 或将草稿标记为可评审时，它会立即发布一条简短的回执评论，但评审本身仍需等待队列槽位。不要期望在打开 PR、推送提交或添加评审请求后立即获得评审。ClawSweeper 运行后的标签更新也可能需要时间。

新 PR 会进入 ClawSweeper 评审队列。维护者也可以通过标签或命令将评审、修复或自动合并流程加入队列。对于普通贡献者更新，只有在更新分支、PR 描述、证明或代码后，才请求 ClawSweeper 再次评审。然后通过新的 PR 评论请求一次新的评审：

@clawsweeper re-review

PR 作者也可以使用 @clawsweeper re-run；具有仓库写权限的用户可以在任何未关闭项上使用任一命令。普通的 @clawsweeper review 命令仅限维护者使用。请保持耐心：在请求的变更尚未存在时再次请求只会增加队列噪音。

当 ClawSweeper 留下评审对话时，请将其视为普通评审反馈，并使用以下后续检查清单。

如果人类贡献者或维护者已接手 PR 并正在积极处理，请不要同时召唤 ClawSweeper 或以其他方式处理该 PR。先让人工评审或修复完成。如果活动停止，检查作者是否被要求提供证明或进行其他更新。

评审期间改进 PR

一旦 Barnacle、ClawSweeper 或维护者作出响应，请将反馈作为 PR 的下一步检查清单。

  1. 将 ClawSweeper 的 Rank-up moves: 和 Proof guidance: 视为该 PR 的行动清单。评分和标签是评审信号，而非固定的合并目标。
  2. 推送请求的代码或文档变更，并在问题、解决方案、用户影响或证据发生变化时更新 PR 描述。
  3. 添加请求的证明，使用与变更相匹配的证据。
  4. 自行解决已处理的评审对话。只有当需要维护者或评审者判断时，才回复并保留对话打开。
  5. 只有在分支、PR 描述、证据和相关 CI 结果均为最新后，才请求重新评审。作者、维护者和 ClawSweeper 之间多次更新与评审循环是正常的。
  6. 尽可能将讨论保留在 PR 上。只有当 PR 需要维护者协调、自动化似乎被阻塞，或下一步决定难以在 GitHub 评论中解决时，才转到 Discord 的 #clawtributors。包含 PR 链接、当前状态以及具体问题或剩余证据。

保持 PR 正文最新。评论有助于讨论，但 PR 描述是维护者和自动化会反复查看的持久摘要。

status: ⏳ waiting on author 表示下一步操作由 PR 作者负责：在请求再次评审之前，更新分支、PR 描述、证明，或回复缺失的上下文。

有用的证据包括聚焦的测试输出、CI 结果、截图、录屏、终端输出、实时观察、脱敏日志或工件链接。对于视觉变更，在可行时包含前后截图。对于证明文件，优先链接 CI 工件、GitHub 上传的截图或录屏，或简短的脱敏日志摘录。除非生成的证明文件是实际文档、测试或产品变更的一部分，否则不要提交它们。

脱敏敏感数据是贡献者的责任。在发布证明之前，移除密钥、Token、私有 URL、用户数据以及无关日志。

OpenClaw 还使用独立的过期自动化。未分配的 issue 和 PR 可在 14 天不活动后标记为过期，再经过 7 天闲置后关闭。已分配的 PR 会在打开 27 天后标记为过期，无论之后是否有更新，然后在 7 天无活动的过期状态下关闭。如果已分配的 PR 仍然活跃，请与正在处理它的维护者协调。

维护者评审工件

scripts/pr review-artifacts-init <PR> 会为当前已评审的 head 写入 .local/review.json。其默认值在结构上有效且明确未完成：NEEDS WORK、performed: false、空证据数组，以及 tests.result: "not_run"。初始化会保留已为同一 PR 和 head 标记的现有工件，因此不会重写较旧或部分填写的评审。

用评审发现和证据填写 JSON，然后运行 scripts/pr review-validate-artifacts <PR>。JSON 拥有评审；验证会打印其摘要，现有的 .local/review.md 不具有权威性。保持枚举值裸露，不要添加诸如 (allowed: ...) 之类的注释：

字段 可接受的值
recommendation READY FOR /prepare-pr, NEEDS WORK, NEEDS DISCUSSION, NOT USEFUL (CLOSE)
findings[].severity BLOCKER, IMPORTANT, NIT
nitSweep.status (optional sweep) none, has_nits
issueValidation.source linked_issue, pr_body, both
issueValidation.status valid, unclear, invalid, already_fixed_on_main
behavioralSweep.status pass, needs_work, not_applicable
behavioralSweep.silentDropRisk none, present, unknown
tests.result pass, fail, not_run
docs up_to_date, missing, not_applicable
changelog required, not_required

nitSweep 是可选的，并且从新模板中省略。如果提供，它需要 performed: true、与 NIT 发现一致的状态，以及非空的 摘要。必需的问题摘要和行为摘要也必须非空，并且每个 发现都需要一个严重级别。结构有效性不会授权准备： READY FOR /prepare-pr 仍然需要已完成的问题和行为审查、 已解决的实质性发现，以及适用的运行时证明。

自动化保持静默

当维护者已在处理该事项、审查或修复请求仍在排队、事件是常规操作，或者 ClawSweeper 通道未针对所请求的操作配置时，自动化可能会保持静默。

它也可能避免采取行动，如果受信任的工作流需要运行不受信任的 贡献者代码。在这种情况下，维护者改用常规审查或更安全的 工作流。

故障排除

维护者可以将 OPENCLAW_PR_TOOLING_ROOT 设置为此仓库的完整检出， 以便独立于停放在其他分支上的规范检出，获取已物化的 scripts/pr 依赖。该环境变量设置优先于规范检出中的 git config openclaw.pr.toolingRoot /path/to/tooling-checkout；如果两者均未设置，依赖获取方式保持不变。版本必须 与包装器的信任锚清单匹配。如果不匹配，会获取一个单独的干净 main 工具检出，执行快进，并使用 pnpm install --frozen-lockfile 安装一次，然后重新检查。脏或非 main 的工具 检出会被拒绝，并附带修复指导；规范检出永远不会 被刷新。该设置适用于两个依赖物化交接点； 就地包装器保留其检出的依赖上下文。包装器代码选择 和信任保持不变。

如果主机的默认 Git 损坏，请将 OPENCLAW_PR_GIT 设置为绝对 Git 可执行文件路径。包装器会以 10 秒截止时间检查 Git，并在失败时打印所选路径和 Xcode 恢复提示。API 速率限制失败会标识所使用的资源，并显示 GraphQL 和 REST 核心余额以及重置时间。

如果 ClawSweeper 没有立即响应，请在重试前等待。该服务基于队列，重复的评论或标签更改可能会使线程更难审查，而不会让队列更快。

在寻求帮助之前，请检查：

  • PR 描述是最新的；
  • 最新提交包含所请求的更改；
  • CI 已完成，或者 PR 正文解释了任何剩余失败为何与 PR 无关；
  • 最新审查请求已作为 PR 评论发出： @clawsweeper re-review；
  • 没有维护者或贡献者正在积极处理该 PR；
  • 最新请求已不在正常的 ClawSweeper 队列延迟范围内。

如果 PR 已是最新状态数小时后仍没有 ClawSweeper 响应， 或者 PR 似乎被自动化阻塞，请在 Discord 的 #clawtributors 中提问。 包括 PR 链接、你的预期、你提问的时间，以及自上次机器人评论以来发生了什么变化。

分叉自动化

希望拥有类似审查自动化的项目可以研究或分叉 ClawSweeper：

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw