agentleFS
Sirius-JiSirius-Ji/dsh-disciplinary-skills-for-greenhands/change-verification-with-evidence/SKILL.md

change-verification-with-evidence

Skill1 starsChanged 10 days agoMITView on GitHub

Use when you must prove a change is safe, when the user asks how you know, or before claiming a task is done — seven evidence classes, four evidence chains, the four-part definition of done, A/B metrics as target + cost + regression, content fingerprints not totals, recycle-bin deletion. 改动验证、证据、回归、A/B、回收站删除、完成定义.

  • Deletes or force-pushes

The file

Files
SKILL.md

SKILL:改动的验证要有证据

⚠️ 使用前提:如实报告失败(见 `你项目的状态文档 项目规范 §诚实报告失误)。

示例说明:文中出现的目录名(如 data/tmp/)、命令(如 --selftest / --smoke)、截图路径与 commit 号,都是某个项目里的示例,请替换成你自己项目的约定;若与本项目事实不符 —— 改模板,不要改事实。

适用症状

  • 改完"看起来对了",但不确定(说不出"如果我没改会怎样")
  • 门禁全绿但心里没底(绿的是老断言,新行为没人测)
  • 用户问"你怎么证明"时只能复述改动内容,给不出对照
  • 修好一处、别处坏了(后来才发现)
  • 提交之后才想起"当时那个数字是多少来着"

不适用

  • 纯文档 / 纯注释改动(跑一次 ast.parse 或打开看一眼即可)
  • 改动不可观测(没有可对比的产物或数字)——此时先解决"可观测",再谈验证

快速判断(30 秒)

1. 这条改动,"不做"与"做"的差别在哪个数字/产物上?
       → 答不出 ⇒ 你还没有验证方案
2. 那个数字/产物,在"把改动去掉"之后会变吗?
       → 不会变 ⇒ 它不是证据
3. 受影响的面有多大?(只改一点,还是改了判据/口径/公共入口)
       → 面大 ⇒ 必须全库回归,不能只看一个点
4. 这条改动**删掉了什么**?"这次删除,除了回收站,还有别的路能拿回来吗?"
       → 没有别的路 ⇒ **必须走回收站**(见 §删除也是一种改动)

判据一句话:每条证据都要能回答"如果没改会怎样"。


七类证据(清单)

#证据判据(可执行)本项目案例
1灵敏度自证把修复去掉 / 反向,断言或数字必须变改动 G:把 valign 去掉,下移量必须 > 2px(a056a2e / 863ee21);改动 O:猴补 _execute_rowcount 成"永远返回 0"(= 修复前行为)⇒ note_links 与 qa_sessions 两个自检都变红(e2d3838)
2新旧对拍新旧实现同输入、输出逐字比某次改动:重写 tokenizer 时保留旧实现不动,tokenize() 与 split_bare_math() 同输入逐字比(设计稿 §3.3 "对拍是本次的关键安全网")
3守恒断言"".join(输出) == 输入(逐字符,不丢不增)某次改动 首次引入(抓到过真 bug):改动 H2a 的新分支漏了 lead/trail 还原 ⇒ 空格发了两遍,被守恒断言当场抓住(aa16c1f);改动 L:全库 15/15 守恒(acefa66)
4A/B 对照同输入两版产出可并排看的产物(截图 / PDF)某次改动(f9fc5bd 笔记+某个资料库模块对照)、改动 D(49675e0 段间距)、改动 K(6e02c0d 6 档对照)、改动 L(docs/screenshots/l_demote/ A/B 各含 PDF+PNG)
5全库回归整个语料跑一遍,看面而不只看点某次改动:4 条笔记 / 43 个非空段对拍(设计稿 §3.3.2);改动 L:15 段触发(14 生效 / 1 退回)、守恒 15/15(acefa66);改动 M:5 条笔记最大右越界 0(081ab05)
6生产接线断言走真实调用链,断言依赖真的传对了某次改动:录入时断言 note_meta.tex 的源哈希 == PDF 里的 marchnote 标记(145e390);状态文档 "测试与验证" 注意事项:注入路径过了不算,必须另走一次真实接线(否则 pet_window 漏传 config 完全测不出)
7度量口径一致"量的口径" == "用的口径"改动 A:_build_tex 的度量与渲染必须同一个盒(ht+dp == 页高−4,cde6422);改动 M:USABLE_WIDTH_PT 必须按"框内边距之后的真实内容宽"算(493.23 → 481.23,081ab05)

删除也是一种改动

删除是改动里最不可逆的一种 —— 它没有"改前"可对比,唯一的回退能力就是回收站 (或 git 历史 / 备份)。所以它也要证据,只不过证据的形式是"能拿回来"。

判据:除了回收站,还有别的路能拿回来吗?

有(git 追踪 / 可重建 / 一次性探针)⇒ 直接删 没有(用户数据 / 未追踪产出)⇒ 必须走回收站

这条判据的好处:它不靠"这东西重不重要"这种主观判断(那必然吵), 只问一个可验证的事实 —— 有没有第二条恢复路径。

边界表

类别走回收站?理由现场例子
用户数据(沙箱 note/ 该业务模块/ files/ code/)✅ 走用户唯一副本、重建成本高笔记 PDF、题目 PDF
项目的非 git 追踪产出(docs/screenshots/、data/*.db、导出物、备份目录)✅ 走未入库 ⇒ git 救不回matrix_prefix/、*_v2.pdf、旧 A/B 产物
git 已追踪的文件❌ 直接删git 历史就是它的回收站 —— 判据问"还有别的路吗"⇒ 有源码、文档
临时探针 / 工作目录(data/tmp/*.py、data/tmp/*_work/)❌ 直接删一次性、可重建recon_*.py、spacing_work/
可重建缓存(data/tmp/math_cache/)❌ 直接删删了自动重建(代价 = 重编译)公式 PNG
测试残留(selftest_*、smoke_*)❌ 直接删每次门禁自己清selftest_app.db 等
回收站装不下的大目录(数 GB)❌ 直接删 + 先备份回收站占等量磁盘备份目录(如需删)

技术:PowerShell Microsoft.VisualBasic.FileIO(零依赖,已实测)

Add-Type -AssemblyName Microsoft.VisualBasic

# 删文件
[Microsoft.VisualBasic.FileIO.FileSystem]::DeleteFile(
  "D:\path\to\file.pdf", 'OnlyErrorDialogs', 'SendToRecycleBin')

# 删目录(带走内容)
[Microsoft.VisualBasic.FileIO.FileSystem]::DeleteDirectory(
  "D:\path\to\dir", 'OnlyErrorDialogs', 'SendToRecycleBin')

三个注意点(都是实测踩出来的):

  1. OnlyErrorDialogs 必须用这个 —— 它"不弹确认框、只弹错误框"; 用 AllDialogs 会弹确认框把自动化挂死;
  2. 删目录用 DeleteDirectory(它带走内容);删完只留下空的父目录, 要连父目录一起清就再删一次(或事先把要删的都放进同一个待删目录);
  3. 回收站占用等量磁盘 ⇒ 删大目录前提醒用户"定期清空回收站"(否则白占空间)。

为什么不用另外两条路:send2trash 未安装(且不在 requirements.txt)—— 不擅自装包; win32com 的 SHFileOperation 虽然可用(pywin32 已在 requirements),但它的 pFrom 要写成 path\0\0 的双重转义,比 PowerShell 一行调用更容易写错。

★ 验证:删完报告"已送回收站"(用户可核对)

删完必须报告:删了哪些路径、已送回收站(不是"永久删除")。 用户能自己去回收站核对 —— 这就是删除类改动的"可恢复性证据"。

⚠️ 只报告"删完了"是不够的 —— 要区分"送回收站"与"永久删除"; 若某次确实用了永久删除(如大目录),必须写明理由(回收站装不下 + 已备份)。

★ 脚本里的删除动作,标签必须与真实行为一致(2026-10-12 现场): 同一次回退里,命令打印的是"送回收站",而实际执行的是 Remove-Item -Recurse -Force (永久删除)—— 被删的只是几秒前自己造的假归档,没造成损失,但标签成了假证据: 事后回看日志的人会以为"东西还在回收站里"。⇒ 打印文案要么与实现一致,要么不给"可恢复"的暗示; 写"送回收站"就必须真的走回收站(src/app/recycle.py::send_to_recycle_bin)。

★★ 但"已送回收站"可能是假的:回收站不可写 ⇒ 静默硬删(2026-11-02 受控实验)

这是本节最危险的一条 —— 它让上面"删完报告已送回收站"变成假证据的源头。

DeleteFile(..., 'SendToRecycleBin') 的语义是"尽量送回收站",不是"保证送回收站": 回收站写不进去时(沙箱限制 / 权限不足 / 跨卷 / 回收站被关闭),它不抛异常、不返回失败, Windows 直接降级为永久删除。

受控实验(本机 DSH 沙箱 workspace-write,2026-11-02):

探针结果
往 C:\$Recycle.Bin\<SID>\ 写临时文件访问被拒绝(工作区外不可写)
工作区内建文件 → DeleteFile(...,'SendToRecycleBin')调用成功、异常无、磁盘上已消失
同一次删除前后数 $I 元数据条目12 → 12,增量 0

⇒ API 说成功 + 文件确实没了 + 回收站查无此物 = 永久删除。 实测损失:两个一次性脚本,无可挽回(全盘按名搜 0 命中、全回收站扫 $I 0 命中)。 别拿沙箱模式当判据:2026-11-06 在 danger-full-access 下再次复现静默硬删($I 8→8)。 唯一可信的判据是同卷 $I 条目增量,可执行模板见 agent-execution-hygiene 规则 17。

硬规则:不信 API 返回值,数 $I 条目增量。

$sid    = (Get-ChildItem 'C:\$Recycle.Bin' -Force -Directory |
           Where-Object Name -like 'S-1-5-21-*' | Select-Object -First 1).FullName
$countI = { @(Get-ChildItem -LiteralPath $sid -Force -File |
              Where-Object { $_.Name -like '$I*' }).Count }

$before = & $countI
[Microsoft.VisualBasic.FileIO.FileSystem]::DeleteFile($f, 'OnlyErrorDialogs', 'SendToRecycleBin')
if ((& $countI) - $before -ne 1) { throw "没进回收站(实为硬删): $f" }

配套三条:

  1. 先探一次再删:删之前往回收站目录写个临时文件 —— 能写才走 SendToRecycleBin; 不能写就整批换 danger-full-access 执行,别在原地反复试;
  2. $I 才是"从哪拿回来"的唯一凭据:它记 UTF-16 原路径 + 原始大小 + 删除时间, 与 $R<id> 一一对应。报告里给这个,而不是"我记得删了什么";
  3. C:\$Recycle.Bin 这个路径自己就带坑:PowerShell 双引号会把 $Recycle 当变量吃掉 (本轮就因此把 --- C:\.Bin --- 打到了屏幕上),拼这个路径必须用单引号。

反事实:只信 API 返回值 ⇒ 这条纪律每轮都报假绿,而且只在真正需要回滚那天才暴露 —— 那时东西已经不在了。删除类改动,"绿"必须是回收站里数出来的。

⚠️ git 侧的两条禁令

  1. git clean 不删未追踪产出:git clean -fd 删的正是"未追踪文件"—— 按边界表那属于"必须走回收站"的类别 ⇒ 禁止用它删未追踪产出, 要删就逐个走回收站;
  2. 未追踪文件一律走回收站,不走 git 命令:git checkout -- <file> / git restore <file> 对未追踪文件无效(git 里根本没有它);若有人为了"恢复" 先 rm 再 checkout,那等于绕过回收站(git 也拿不回来 ⇒ 永久丢失)。

一句话:git 能救的只有它追踪过的东西;未追踪的一律走回收站。


A/B 指标 = 目标项 + 成本项 + 回归项

A/B 只测"目标项"会误导决策 —— 你必须同时量"这个改动可能损害什么"。

做法:出 A/B 之前,先写两列 ——

  1. 它可能改善什么(目标项);
  2. 它可能损害什么(成本项)—— 逐条列出,每条都要有可量的数字。

典型案例(2026-10-08,笔记预览 22 处渲染失败):

  • 目标项:预览失败数(22 → 0)、切分片数、碰撞、页数 —— 都测了;
  • 漏掉的成本项:出图数(每段 <img> 计数)。 结果 A/B 报告只写"失败 27 → 5、三角形 22 → 0",看起来是纯赚; 实际代价是"全库 22 段少出图(−59 片)"(A^T=-A / x^TAx=0 这类裸算式退回文字)。 用户按那份 A/B 拍板后,落地时才发现代价 ⇒ 返工。
  • 教训:判据选得对不对,取决于成本项有没有进指标; 只测目标项等于只量收益不量代价。

指标清单模板(照抄):

类别要测什么
目标项这次改动声称要改善的那个数字
成本项★ 它可能损害的:出图数 / 内容量 / 页数 / 耗时 / 观感 / 可搜性…
回归项全库其它语料逐项对比(必须"零变化"才算过)
不变量守恒断言、灵敏度自证(改前必须红)

另一条同源教训:A/B 的 A 必须是"真基准" —— git stash 对已提交的改动无效(checkout 不回退 commit)⇒ "我在 HEAD 上测过了"这句话要用可验证的方式说(例:断言 A 态里那个修复不存在, 如"白名单里没有 cdots、_merge_incomplete_runs 不存在")。 2026-10-08 那次我两次把 A 搞错(一次开着部分修复、一次混入已提交的修复), 两次都是靠**主动核对"修复是否真的不存在"**才发现的。

① 现场取证:把用户那条真实数据取出来,量"修前"的数字
     文字层 62 字、图 3 张、图宽 521.85pt、右越界 +34.62pt
② 根因定位:证明"哪条代码路径"(不是猜)
     用探针打印分流结果:split_bare_math → 1 片 math ⇒ 走"整段一张图"
③ 实现 + 灵敏度自证:让"不修"能红
     去掉修复 ⇒ 文字层回到 62 字(断言必须能区分)
④ 现场重跑:同一条真实数据,量"修后"的数字
     文字层 141 字、图 13 张、图宽 ≤221.57pt、右越界 −7.04pt
⑤ 全库回归:15 段触发 → 14 生效 / 1 退回;守恒 15/15;护栏违规 0
⑥ 门禁:--selftest 34 OK / --smoke 441 OK
⑦ 留档:A/B 截图(A_修前 / B_修后)入 docs/screenshots/l_demote/
① 反例先行:写出"能区分修复前后"的断言
     delete_note_meta(存在的 hash) == 1      ← 只有这条能区分(旧实现返回 0)
     delete_note_meta(不存在的 hash) == 0    ← 旧实现也绿,单独用它等于没测
② 灵敏度自证(猴补模拟修复前):
     把 _execute_rowcount 换成"永远返回 0" ⇒ 两个自检**都必须变红**
③ 恢复后复跑:必须回到全绿(证明猴补没留痕)
④ 影响面核对:所有调用点是否忽略返回值(忽略 ⇒ 零改动)
① 口径写清楚:可用宽 = A4 − 2×18mm − 2×框内边距 = 481.23pt(不是 493.23)
② 换算式核对:(454.31 + 2×2.0) × 1.05 == 481.23  ✓
③ 边界值:刚好放得下(29.45 不折行)/ 超宽(785.45 → 481.23 必须折行)
④ 全库回归:5 条笔记最大右越界 **0**

链 4:删除 / 迁移"判死"的东西(以清理公式缓存为例,2026-10-06)

① 判活集合:只按"当前代码真能产生的组合"重建键(见 when-measurement-lies 原则 6)
② 逐条反查:残留的每一个,都必须能被某个可达组合命中(判死残留必须 = 0)
③ 证据一:判据有区分度 —— 用"错参数"真跑,结果**必须不同**
     · 错颜色(0000FF/FF0000)真渲染 ⇒ 与缓存**全部不同** ✓
     (若"错参数"也相同 ⇒ 你的判据根本没在区分参数,后面的等价结论也不可信)
④ 证据二:内容等价 —— 用"推出来的参数"真跑,与旧产物**字节相同**
     · 12/12 逐字节一致(含 display=0/1 与两种颜色)
     · 6/6"真正待迁移"的候选(旧键在、新键无)逐字节一致
     · 对照组:自然宽 > 阈值的宽公式**不同**(521.85×49.7 vs 481.23×62.3)
       ⇒ 证明阈值确实会改变输出,所以"等价"是**逐条判出来的**,不是一刀切的假设
⑤ 影响面核对:死者里"内容另有活副本"的占比(本项目 1501/2005 ⇒ 删了不触发重编译);
     其余逐个核对"是否仍在用"(504 个的公式已不在 qa_history ⇒ 代价 0 秒)
⑥ 删除前后都做复核:删前打印清单 + 断言每个都判死;删后复核"剩余全活 + 抽 5 条命中"
⑦ 留档:已删清单(含 stem / mtime / 字节 / 字段 / 公式)落 `data/tmp/`,可追溯
⑧ 门禁:--selftest 34 OK / --smoke 441 OK(覆盖非缓存路径)

★ "删除类"比"修改类"更需要这两条链:改坏了能再改回来;删错了不可逆。 所以判死必须有两个独立方向的证据(区分度 + 等价),缺一个都不能删。

四条链的共同点:先量"不修"时的数字,再量"修了"的数字 —— 只报后一个数字,等于没有证据。


比"总数"会骗人 —— 要比"内容指纹"

"总数不变"不等于"内容不变" —— 集合类改动(图 / 文件 / 元素)必须比内容指纹。

典型案例(2026-10-09「全1矩阵的幂」重生成):

  • 我的重生成报告写"图数 17 → 17 不变",据此宣布"没有损失";
  • 用户打开 PDF 看到图少了;
  • 逐张按内容指纹对比后真相:

    旧版新版
    张数1717
    内容含 2 张整页宽大图(493.2\u00d7181.6pt / 493.2\u00d7343.8pt,原题照片)那 2 张没了,换成 2 张 82\u00d716pt / 43\u00d713pt 的小公式图

    \u21d2 总数持平掩盖了"整页宽的原始材料被小图替换" —— 净损失 2 张原题照片 (重生成时我传了 images=[]:note_meta 不存 images,照片必须手工补)。

判据(照抄):

  1. 涉及"图 / 文件 / 元素集合"的验证 \u21d2 比内容指纹,不只比总数;
  2. 指纹 = 内容 hash(首选)/ 尺寸 / 位置 —— 越全越好 (本案例用 md5(extract_image 的原始字节) \u21d2 同一张图换到别的页/位置也能认出"是同一张");
  3. 报告格式(三行,缺一不可):

    旧有 \u2192 新有(命中):N 种
    \u2605\u2605 旧有 \u2717 新无(丢失):M 种   \u2190 必须为 0 才算过
    \u2605  新有 \u2717 旧无(新增):K 种   \u2190 允许,但要能解释来源

为什么"总数"特别容易骗人:集合类改动往往是"删一批 + 加一批", 总数恰好可能持平 —— 那是巧合,不是"没有变化"。 \u21d2 只要报告里出现"数量不变",就该追问一句:"那内容呢?"


按改动类型选证据组合

改动类型最少要有的证据
纯逻辑(判据 / 切分 / 解析)守恒断言 + 反例集(正反例都要)+ 全库回归
视觉 / 版面A/B 对照(改前与改后都要有)+ 灵敏度自证("不做"时数字必须变)
管线 / 接线生产接线断言 + 全库回归(走真实语料,不用构造样本)
口径 / 度量度量口径一致(两条路径量出来必须相等)+ 边界值(刚好放得下 / 刚好放不下)
返回值 / 契约断言正反两侧(存在的返回 ≥1、不存在的返回 0)+ 灵敏度自证(旧实现下必须红)
紧急修复以上任意一条 + 现场数据重跑(用出问题的那条真实数据,不用构造样本)
删除文件回收站可找回(删完报告"已送回收站")+ 删除清单(删了哪些路径、为什么这一类可以删)

证据链(本项目实测形状,可直接照搬)

只报后一个数字,等于没有证据。


证据留档(否则等于没有)

产物放哪规矩
A/B 截图 / PDFdocs/screenshots/<改动名>/文件名带方向(如 A_修前 / B_修后),并在同目录留一句话结论
一次性探针data/tmp/(gitignore)结论写进 commit 消息或 状态文档;探针本身不必入库
长期断言src/main.py 的 --selftest / --smoke临时探针必须沉淀成持久断言,否则下次没人跑它
数字commit 消息 + 状态文档写清量纲与口径("521.85pt → 481.23pt,右越界 +34.62 → +0.00")

测试环境未就绪 ⇒ 断言会"空过"

病根:测试夹具 / 临时库 / 子进程没初始化 ⇒ 被测动作静默失败 ⇒ 断言查"没变化" ⇒ 空过(永远绿)。

检查动作:

  1. 每条"没变"的断言,必须配一条"正向证据"(如"备份目录出现"/"日志出现"/"行数增加");
  2. 夹具就绪性:临时库建完 ⇒ 先断言"能写进去"(写一个探针行 + 读回)⇒ 再做被测动作。

反模式

❌ 门禁绿就当验证完

门禁绿只能证明"老行为没坏",不能证明"新行为对了"。 (改动 O 的教训:旧实现下"删不存在的返回 0"也绿 ⇒ 必须加"删存在的返回 ≥1"。)

❌ 只测"改的那一点",不做全库回归

修好一处、坏掉十处是常态(尤其改判据 / 口径 / 公共入口时)。 面大的改动必须全库跑:改动 L 就是靠全库回归发现"15 段里有 1 段必须退回"(A\cdot B\ 渲染失败)。

❌ 基线取错 ⇒ 空过的绿

"改动 0 行、六项全绿"有时候不是修好了,而是基线取的就是修好后的版本 (现场:cmd /c "git show 88f22a6^:…" 的 ^ 被吃掉 ⇒ 取到当前版本 ⇒ 自己比自己)。 判据 =「改前必红」:拿不到"改前那版该有的失败信号"(那次是 799 个 □)就说明基线不对; "0 行"要当成取错基线的警报,不是通过。

❌ A/B 只有"改后"没有"改前"

没有改前版就不是对照。改前版可以"现场造"(如 replace(' valign="middle"', "")), 但必须注明是怎么造的(见 docs/screenshots/s2_diag/README.md 的做法)。

❌ 证据只在对话里,不留档

对话会丢、会压缩、会跨会话忘记。结论 + 数字 + 对照物必须落到 git 里(文档/截图/commit 消息)。

❌ 临时探针当长期断言

探针写在 data/tmp/ 是一次性的,下次没人跑它 ⇒ 同类 bug 会复发。 验证通过后要把它沉淀成 selftest / smoke 断言。

❌ 拿"注入路径"证明生产可用

冒烟里显式传 config 通过,不代表生产里 pet_window 传了 config。 必须另走一次真实接线并断言(本项目已踩过:漏传 self._config ⇒ 表现为"未配置 API Key")。

❌ 批量删除没有"等价"证据

"这批看起来是旧的 / 键对不上 / 很久没访问" —— 都不是等价证据。 删之前必须有两条:① 判据有区分度(错参数真跑必须不同); ② 内容真等价(对参数真跑、与旧产物字节相同)。 只有①没有② ⇒ 你可能在删"结果不同"的活数据;只有②没有① ⇒ 你的判据可能根本没区分参数 ("什么都等价"等于没测)。

❌ 删完不复核

删除不可逆。删完必须复核:剩余集合全部判活(残留判死 = 0)+ 抽样命中 + 门禁。 (本项目实测:删 2005 对后剩 671,全部判活、抽 5 条命中、门禁 34/441 全绿。)

❌ 拿 API 的"成功返回"当删除证据

DeleteFile(..., 'SendToRecycleBin') 成功返回 ≠ 进了回收站(回收站不可写时会静默硬删)。 删除类改动的证据只能是回收站里 $I 条目的增量与原路径,不是"调用没报错"。 (2026-11-02 亲历:两个文件报"已移入回收站",实际永久删除,无法找回。)


边界

能证明

  • 行为(输入 → 输出的对应关系)
  • 数字(尺寸 / 行数 / 越界量 / 耗时)
  • 守恒(不丢不增)
  • 回归(现有语料上不退化)

不能证明

  • 主观观感("看起来舒服吗")⇒ 只能交 A/B 图给人判,不要把"我觉得好了"写成结论
  • 未覆盖语料(全库回归只覆盖现有数据;新语料可能触发新路径)
  • 并发 / 时序(除非专门做竞态测试)

需要人工裁决

  • "数字好了多少才算好"(阈值是业务判断)
  • 两个证据冲突时信哪个(通常信"更接近用户可见行为"的那个)

通道改动的必测项(AGENTS.md / 指令注入)

任何涉及 AGENTS.md 通道的改动,必须包含 user 角色验证与压缩存活测试。 缺任一项即视为未完成 —— 这两项是「文件看着对、运行时却丢了纪律」的唯一探针。

#必测项判据
1user 角色验证最新 source.kind=agent-instructions 记录满足:role="user"、changes[0].digest == sha1(磁盘 AGENTS.md)、正文逐字符包含磁盘全文
2压缩存活测试触发一次 /compact 后,compaction/end 之后必须出现新的 baseline=true 注入记录,且内容与磁盘逐字节相同

一键跑:node tools/verify_discipline_channel.mjs --cross-session

退出码:0 = 通过 / 1 = 失败 / 2 = 无法判定。2 绝不当绿 —— 没压缩过就是没测过。

两个踩过的坑:

  • 只看文件哈希一致就宣布"纪律没事" —— 那证明的是磁盘,不是注入通道;
  • 去 request/header 找基线 —— 那里只有 config + tools,消息不在里面。 基线是 user/message 记录(data.source.kind == "agent-instructions")。

一句话

没有对照就不叫验证:让断言在修复前红一次、新老对拍一次、全库跑一遍、真实接线走一趟。


验证最怕的不是"没验证",而是"验证了但把红的写成绿的"。

"改完了"不是一个状态,而是一组断言。缺任何一段,都只能叫"改动了"。

  1. 目标断言:新行为在你写的检查里改前必红、改后必绿(能红的才叫断言,否则是装饰)。
  2. 回归断言:改动前已经绿的检查,改后仍然绿(且是同一批,不是挑了 3 条跑)。
  3. 证据强度:给出外部可复核的物证——文本层提取结果、图像、计数、哈希、日志行; 而不是"我读了一遍代码,逻辑是对的"。
  4. 提交后复跑:把改动提交后,在干净状态再跑一次同一批断言,确认入库版本本身是绿的 (防止"用工作区里未提交的文件"骗过了门禁)。

配套硬规则:

  • 一个提交只做一件事,门禁红了能立刻定位;
  • 证据要能证伪:报告里写清"如果我没改会怎样"(对照组),只有实验组数字不算证据;
  • 删除也是改动:删除类操作必须走可恢复路径,并在报告里写"从哪里能拿回来"。

实战案例与复盘

以下为该项目当时的一手记录,保留原始术语(项目名 / 模块名 / 改动编号),仅作方法论的实证注解。

  • 链 1:修一个"用户报的现象"(以卡片 L "笔记 PDF 乱码"为例)
  • 链 2:修一个"契约 / 返回值"(以卡片 O 为例)
  • 链 3:改"口径 / 度量"(以卡片 M 为例)
  • 同族教训(同一轮一起踩到的):
    • A/B 指标 = 目标项 + 成本项 + 回归项(见上一节);
    • "文件存在性对齐"不等于"内容恢复"(卡片 AA:重生成了一份替代品,原件内容无法恢复)。
  • 本项目实例(回归-4,2026-10-12):
  • 受控子进程首版 Database(path) 没 .initialize() ⇒ 三次"编辑"静默全败 ⇒
  • 差点让"标签没变"空过;靠正向证据(jiti_backup_* 备份目录出现)抓到。
  • | 1 | 灵敏度自证 | 把修复去掉 / 反向,断言或数字必须变 | 卡片 G:把 valign 去掉,下移量必须 > 2px(a056a2e / 863ee21);卡片 O:猴补 _execute_rowcount 成"永远返回 0"(= 修复前行为)⇒ note_links 与 qa_sessions 两个自检都变红(e2d3838) |
  • | 2 | 新旧对拍 | 新旧实现同输入、输出逐字比 | 卡片 46c:重写 tokenizer 时保留旧实现不动,tokenize() 与 split_bare_math() 同输入逐字比(设计稿 §3.3 "对拍是本次的关键安全网") |
  • | 3 | 守恒断言 | "".join(输出) == 输入(逐字符,不丢不增) | 卡片 46c 首次引入(抓到过真 bug):卡片 H2a 的新分支漏了 lead/trail 还原 ⇒ 空格发了两遍,被守恒断言当场抓住(aa16c1f);卡片 L:全库 15/15 守恒(acefa66) |
  • | 4 | A/B 对照 | 同输入两版产出可并排看的产物(截图 / PDF) | 卡片 42(f9fc5bd 笔记+集题本对照)、卡片 D(49675e0 段间距)、卡片 K(6e02c0d 6 档对照)、卡片 L(docs/screenshots/l_demote/ A/B 各含 PDF+PNG) |
  • | 5 | 全库回归 | 整个语料跑一遍,看面而不只看点 | 卡片 46c:4 条笔记 / 43 个非空段对拍(设计稿 §3.3.2);卡片 L:15 段触发(14 生效 / 1 退回)、守恒 15/15(acefa66);卡片 M:5 条笔记最大右越界 0(081ab05) |
  • | 6 | 生产接线断言 | 走真实调用链,断言依赖真的传对了 | 卡片 40:录入时断言 note_meta.tex 的源哈希 == PDF 里的 marchnote 标记(145e390);HANDOFF "测试与验证" 注意事项:注入路径过了不算,必须另走一次真实接线(否则 pet_window 漏传 config 完全测不出) |
  • | 7 | 度量口径一致 | "量的口径" == "用的口径" | 卡片 A:_build_tex 的度量与渲染必须同一个盒(ht+dp == 页高−4,cde6422);卡片 M:USABLE_WIDTH_PT 必须按"框内边距之后的真实内容宽"算(493.23 → 481.23,081ab05) |
  • | 用户数据(沙箱 note/ jiti/ files/ code/) | ✅ 走 | 用户唯一副本、重建成本高 | 笔记 PDF、题目 PDF |
  • | A/B 截图 / PDF | docs/screenshots/<卡片名>/ | 文件名带方向(如 A_修前 / B_修后),并在同目录留一句话结论 |
  • (卡片 O 的教训:旧实现下"删不存在的返回 0"也绿 ⇒ 必须加"删存在的返回 ≥1"。)
  • 面大的改动必须全库跑:卡片 L 就是靠全库回归发现"15 段里有 1 段必须退回"(A\cdot B\ 渲染失败)。

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.