跳转至

PR 审查流程

本页说明你在打开或更新 OpenClaw 拉取请求后的审查流程: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 的截图或录屏,或简短脱敏的日志摘录。除非生成的文件是实际文档、测试或产品变更的一部分,否则不要提交生成的证明文件。

对于行为更改,请使用边界证明指南来审查生产路径、提供者请求和失败/重建证据。

脱敏敏感数据是贡献者的责任。在发布证明之前,移除机密、令牌、私有 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(可选扫描) 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 发现一致的状态,以及非空的 摘要。必需的 issue 和 behavior 摘要也必须非空,并且每个 finding 都需要 severity。结构有效性不会授权准备: READY FOR /prepare-pr 仍然要求已完成 issue 和 behavior 审查、 已解决的实质性发现,以及适用的运行时证明。

当有界调查无法为本地 测试失败建立或完成一个安全修复时,保留 tests.result: "fail" 并记录 tests.investigatedLocalFailures。其 head 必须是确切审查过的提交。 其非空 failures 数组记录每个原始 failure、reproductionAttempts 和 evidence 的非空字符串 数组,以及非空的 remainingUncertainty。描述命令和观察到的结果,并引用 PR 中记录的证据。通过的重放不能证明修复。

这项已完成的调查可以伴随 READY 推荐,而不会 将失败的证明变成通过。实质性发现、行为审查、 必需的 CI、安全检查以及强制审查仍然是独立关卡。 仅将 tests.preExistingCi 用于其独立的、可归因的 CI 失败工作流; 本地调查不会授权 CI 例外。

当自动化保持静默时

当维护者已经在处理该事项、审查或修复请求仍在队列中、事件是常规事件,或 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