Metadata

name: idempotent-rebuild-verification
version: 2.0.0
description: 哈希钉扎的 agent 工作区重建验证：纯标准库、离线、确定性 CLI。分类"良性质漂移 vs 真损坏" （$(cat) 尾部换行剥离 / CRLF / 截断粘贴 / HTML 错误页 / 同尺寸改动），批量清单校验， runbook 钉扎提取，CommonMark 正确的步骤提取（内嵌围栏不再静默截断），快照擦除后状态判定与步骤路由。JSON 机器可读输出，每条带 next_action。不修改任何被验证文件。
author: orionshaowswmw
license: MIT
tags: ["rebuild","idempotency","sha256","sandbox","snapshot","agent-workspace","verification"]
metadata: {"openclaw":{"emoji":"🔁"}}

idempotent-rebuild-verification v2.0.0

一句话：runbook 重建/快照擦除后出现"哈希不符/产物消失"时，先用本工具分类（良性=重跑 writer；损坏=整块重贴/重下），再动手 —— 盲目重贴大 heredoc 本身就会制造损坏。

何时使用

重放哈希钉扎的 runbook 后，某个 sha256 must be: 不符 → verify 先分类。
一批钉扎文件 → manifest 批量校验（每行 path sha256 [size]）。
想知道 runbook 里钉了哪些文件 → pins。
要从 markdown runbook 程序化执行步骤 → extract-steps（suspect 步骤按显式行范围切割）。
快照擦除后判断"哪些步骤要重跑" → wipe-audit。
需要确定性测试夹具 → gen-fixtures。

加载地图（token 经济）

场景	读什么
直接用工具	本文 + `python3 scripts/rebuild_verify.py --help`
追问某类漂移的根因/处置	`references/drift_classes.md`
步骤提取/内嵌围栏疑问	`references/runbook_extraction.md`
快照排除清单/擦除后判定	`references/snapshot_semantics.md`

命令契约

python3 scripts/rebuild_verify.py verify FILE --want HEX [--want-size N]
python3 scripts/rebuild_verify.py manifest MANIFEST [--root DIR]
python3 scripts/rebuild_verify.py pins RUNBOOK.md
python3 scripts/rebuild_verify.py extract-steps RUNBOOK.md [--lang bash|sh|shell|python|text|all] [--write-steps DIR]
python3 scripts/rebuild_verify.py wipe-audit DIR
python3 scripts/rebuild_verify.py gen-fixtures DIR
python3 scripts/selftest.py                # 全部自检（应 100% PASS）

命令	输出（stdout 单行 JSON）	退出码
verify	`{status: ok/benign/warn/error, class, next_action, detail{size,got_sha256,want_sha256,…}}`	0 ok · 2 输入错 · 3 漂移/不符
manifest	`{total, n_ok, n_drifted, n_missing, ok[], drifted[{rel,class,next_action}], missing[]}`	0 全 ok · 2 · 3
pins	`{n_pins, pins[{line,sha256,heading,referenced_file,in_code_fence,raw}]}`	0 · 2
extract-steps	`{n_steps, suspect[], steps[{index,lang,start_line,end_line,bytes,heredocs,status,sha256}]}`；行号=内容行（开栏=start_line-1，闭合围栏=end_line+1）；`--lang` 精确匹配（未标注块计 text）；`--write-steps` 额外写字节精确步骤+steps.json	0 · 2
wipe-audit	`{verdict: clean/normal_post_wipe/pre_wipe_or_full/scripts_missing_too, next_action, next_actions[], present{…}}`	0 · 2 · 3(脚本缺失异常)
gen-fixtures	确定性夹具（canonical 1116B + 7 种漂移形态 + manifest + 6 步 runbook）	0 · 2

漂移分类 class 全集：ok trailing_newline_drift(benign) crlf_drift(benign) html_error_page truncated_paste content_change unknown size_ok size_mismatch。 值类型：数字=JSON number；哈希=64 位小写 hex 字符串；行号=1-based int。错误：stderr 单行 JSON {"status":"error","tool":…,"error":…}。

硬规则（不可违反）

先分类，后动手：任何"哈希不符"先跑 verify；benign → 重跑 writer 步骤， 勿盲目重贴 heredoc（重贴本身是损坏源）；error 类才按 next_action 重贴/重下。
只读：verify/manifest/pins/extract-steps/wipe-audit 绝不修改被验证文件；写盘只发生在 --write-steps DIR 与 gen-fixtures DIR 显式指定处。
不联网：所有命令离线。
确定性：gen-fixtures 与 steps.json 的 sha256 相同输入→相同字节（无时间戳/随机）；清单/钉扎校验结果可复现。
suspect 步骤不自动执行：extract-steps 标记 suspect（未闭合/内嵌围栏切断 heredoc）的步骤必须按显式行范围人工切割后确认 EOF 标签再执行。
判定边界：wipe-audit 的排除目录清单默认 SNAPSHOT_EXCLUDED 常量，可用环境变量 RV_SNAPSHOT_EXCLUDED（空白/逗号/分号/冒号分隔）按所在环境文档覆盖；它给出的是"要重跑哪类步骤"的建议，不是重建执行器。

自检

python3 scripts/selftest.py：12 组检查（夹具确定性、提取器字节精确、7+ 分类逐一、 manifest/pins/wipe-audit 语义、退出码纪律、CRLF/空文件/多尾换行边界、仅标准库、 SKILL 幻影扫描、JSON 契约）。任何 FAIL 先修工具再交付。

边界外（明确不做）

不执行 runbook 步骤（只提取/校验/分类）。
不做增量/全量 diff 报告（同尺寸改动请对新鲜写出做 diff）。
不处理非文本二进制语义（图像/模型内容正确性不校验，只校验字节完整性）。
快照排除清单是环境相关的，跨环境使用先核对 references/snapshot_semantics.md。

idempotent-rebuild-verification

安装技能