企业官网建设流程全解析

CodeWhale 审查回执：如何用 --write-receipt 与 --check-receipt 在推送前确认 diff 未变

【免费下载链接】CodewhaleOpen-source coding agent for your terminal, built in Rust and on a journey of continuous community improvement. Issues and PRs welcome.项目地址: https://gitcode.com/GitHub_Trending/de/Codewhale

用codewhale review审查完本地 diff 之后，真正的问题往往是：从审查那一刻到执行git push之间，工作区又动了。CodeWhale 的 review 回执（review receipt）就是为这个窗口设计的：codewhale review --write-receipt在审查成功后把一份本地 JSON 回执写到 Codewhale 状态目录的review-receipts/子目录（可用--receipt-path <path>指定位置）；推送前再运行codewhale review --check-receipt，它会不调用模型，把当前 diff 的指纹与回执中的指纹做本地比对。这份机制的定义见 docs/RECEIPTS.md，实现位于 crates/tui/src/lib.rs 与 crates/tui/src/tools/review.rs。

审查回执记录了什么、不记录什么

回执是 pre-push handoff artifact：它只记录“审查的是哪份 diff、审查报告了什么”，本身不会 push、不会打 tag、不会开 PR，也不宣称替代维护者审查。

当前回执包含以下字段：

• diff_fingerprint：被审查 diff 的 SHA-256 指纹，是后续比对的核心；
• provider与model：本次审查实际路由到的 provider/model；
• checks_run：附加在回执上的本地检查。为空表示没有附加任何检查；有附加检查时，它们必须报告通过的 status；
• findings：结构化 issue/suggestion 计数及 issue 位置（当审查输出是结构化 JSON 时）；
• unresolved_risk：由未解决的 findings 推导出的保守摘要；
• review_content_sha256：审查文本的 SHA-256。

回执刻意不包含原始 diff 正文。这意味着回执是审计记录而不是 diff 的载体；跨机器交接时，审阅方拿到的是指纹和结论，diff 本身仍来自仓库。

第一步：审查成功后写出回执

在有未推送改动的仓库工作区内执行：

codewhale review --write-receipt

这条命令审查的是当前工作区 diff。--write-receipt的含义是“在成功的审查之后写出持久化 pre-push 审查回执”（见ReviewArgs中的参数注释）。几个要点：

• 必须有真实 diff。命令在取 diff 后若发现为空会直接报错No diff to review.，不会走到写回执这一步。
• diff 的范围由目标参数决定，与后续--check-receipt必须一致：--staged审查git diff --cached；--base <ref>（如origin/main）审查git diff <base>...HEAD；--path <file>把 diff 限定到某个路径。
• 模型路由可用--provider <name>与--model <name>覆盖，回执里记录的provider/model就是实际路由结果。
• 若--receipt-path没有提供，回执写入 Codewhale 状态目录的review-receipts/下；提供了则写入该路径（父目录不存在时会自动创建）。

成功信号：stderr 输出Review receipt written: <path>。加--json时，输出 JSON 中带receipt_path（回执文件路径）和receipt（回执内容）两个字段，便于脚本消费。

参数约束在 crates/tui/src/lib.rs 的validate_review_receipt_args中硬性校验：--receipt-path必须与--write-receipt或--check-receipt二选一搭配；--write-receipt与--check-receipt互斥，不能同时给。

第二步：推送前运行 --check-receipt 门禁

codewhale review --check-receipt

这是纯本地门禁，不调用模型，不产生模型费用。它的逻辑是：按与审查时相同的参数重新收集 diff，计算指纹，然后与回执中的diff_fingerprint比较。回执来源二选一：

• 显式指定：codewhale review --check-receipt --receipt-path <path>；
• 缺省时：在review-receipts/目录里找与当前 diff 指纹匹配的最新一份本地回执。找不到时命令报错并提示：No review receipt found for the current diff. Run codewhale review --write-receipt first, or pass --receipt-path.。

关键前提：check 收集 diff 用的目标参数要和 write 时一致。如果你写回执时用的是--base origin/main，check 时也要带同样的--base；--staged、--path同理。参数不一致时两边计算出的 diff 不同，指纹必然对不上，得到的diff_mismatch反映的是“比对了不同范围的 diff”，而不是你真正的改动。

检查通过时，命令以 0 退出并输出：

Review receipt valid: <path>

这是可以直接接在git push前面的门禁：

codewhale review --check-receipt && git push

检查失败时如何读输出

检查不通过时命令以非零退出码结束，并打印Review receipt check failed: <reason>。按 docs/RECEIPTS.md 与 crates/tui/src/lib.rs 中run_review_receipt_check的实现，失败原因分四类：

1. diff 已变化（diff_mismatch）：当前 diff 指纹与回执不符。正确动作是重新运行codewhale review --write-receipt审查新 diff；文档同时要求，在 PR 交接中复用回执前，先比较diff_fingerprint。
2. 回执有未解决风险（unresolved_risk）：写回执的那次审查报告了结构化 issue（unresolved_risk.unresolved为真）时，check 会直接失败，reason 是回执里的风险摘要。也就是说，想让门禁通过，审查输出本身必须没有未解决的 issue——“审查过了”不等于“审查干净了”。
3. 回执 schema 不受支持（unsupported_schema）：schema_version与当前版本不匹配。
4. 附加检查未通过（check_failed）：checks_run中某项检查的 status 不是通过状态，reason 形如review receipt check '<name>' did not pass: <status>。

需要机器可读结果时，对 check 加上--json：

codewhale review --check-receipt --json

输出形如（字段值来自实际回执）：

{ "mode": "review_receipt_check", "success": true, "validation": { "passed": true, "status": "valid", "diff_fingerprint": "sha256:…", "receipt_fingerprint": "sha256:…", "unresolved": false, "risk_level": "none" } }

validation.status的取值固定为valid、diff_mismatch、unresolved_risk、unsupported_schema、check_failed、invalid之一，可直接作为 CI 判断分支的依据。

边界与限制

• --check-receipt不调用模型，因此它验证的是“diff 未变 + 回执本身无未解决风险/失败检查”，不是“代码现在一定正确”；代码变了，指纹就对不上，这是它的设计边界。
• 回执不携带原始 diff 正文，只带diff_fingerprint与审查结论摘要；交接场景下 diff 仍需要从仓库获取。
• checks_run为空是合法状态，表示没附加任何本地检查；一旦附加，检查项的 status 必须是通过状态，否则 check 门禁失败。
• 回执写在本地状态目录，属于本机产物；换机器后要么拷贝回执文件并用--receipt-path指过去，要么在目标机器上重新--write-receipt。

当 check 返回Review receipt valid（退出码 0）时，就可以执行git push；若非零退出，按上面四类原因处理——最常见的是第 1 类：diff 又改了，重新写一份回执再查一次。

【免费下载链接】CodewhaleOpen-source coding agent for your terminal, built in Rust and on a journey of continuous community improvement. Issues and PRs welcome.项目地址: https://gitcode.com/GitHub_Trending/de/Codewhale