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 评论请求一次新的审查:
PR 作者也可以使用 @clawsweeper re-run;具有仓库写入权限的用户可以对任何打开的项目使用任一命令。普通的 @clawsweeper review 命令仅限维护者使用。请耐心:在请求的更改尚未到位前再次询问只会增加队列噪音。
当 ClawSweeper 留下审查对话时,像对待普通审查反馈一样处理,并使用下面的后续检查清单。
如果人类贡献者或维护者已经接管 PR 并正在积极处理,请勿同时召唤 ClawSweeper 或以其他方式处理该 PR。先让人工审查或修复完成。如果活动停止,请检查作者是否被要求提供证据或进行其他更新。
在审查期间改进 PR¶
一旦 Barnacle、ClawSweeper 或维护者做出响应,就将该反馈用作 PR 的下一步检查清单。
- 将 ClawSweeper 的
Rank-up moves:和Proof guidance:作为该 PR 的行动列表来阅读。评分和标签是审查信号,而非固定的合并目标。 - 推送所请求的代码或文档更改,并在问题、解决方案、用户影响或证据发生变化时更新 PR 描述。
- 添加所请求的证据,使用与更改匹配的证据。
- 自行解决已处理的审查对话。仅在你需要维护者或审查者判断时回复并保持对话打开。
- 只有在分支、PR 描述、证据和相关 CI 结果都是最新时才请求重新审查。作者、维护者和 ClawSweeper 之间的多次更新和审查循环是正常的。
- 尽可能在 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