agentleFS
Sirius-JiSirius-Ji/dsh-disciplinary-skills-for-greenhands/when-measurement-lies/SKILL.md

when-measurement-lies

Skill1 starsChanged 10 days agoMITView on GitHub

Use when measured numbers contradict expectations, code looks correct yet nothing changes, or an assertion always passes or always fails — a six-layer taxonomy of lying measurements, a toolbox for swapping measurement, plus target-only metrics and missing-precondition traps. 测量被骗、断言无效、灵敏度自证、换口径.

The file

Files
SKILL.md

SKILL:测量工具会骗人

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

适用症状

  • 报告的数字 / 结论与预期不符,但代码看起来是对的(反复读代码找不出毛病)
  • 反复改代码却"怎么改都一样"——量出来的数字纹丝不动
  • 断言 / 自检永远通过(改坏了也绿),或者永远失败(修好了还红)
  • 同一件事两种工具量出不同数字(谁对?)
  • 修完"数字变好了",但用户看到的现象没变(或反过来)

不适用

  • 测量工具本身就是被测对象(那时候要测的是它的契约,不是它给出的数)
  • 现象稳定复现且代码明显错(直接读代码更快,不必先怀疑测量)

快速判断(30 秒)

1. 你量的那个数,是"你以为的那个东西"吗?
       → 换一种口径再量一次(换工具 / 换层 / 换坐标系)
2. 两种口径的数不一样 → 先别下结论,把差异定位到"读数的那一步"
3. 你的断言,在"把修复去掉"之后还会绿吗?
       → 会绿 ⇒ 断言没有灵敏度,它没在测任何东西

判据一句话:数字不对时先怀疑尺子。改代码是成本最高的一种反应。


核心原则

原则 1:结论与预期不符 ⇒ 先验证测量本身

顺序永远是:测量可信吗 → 口径一致吗 → 再看代码。反过来做(先改代码)会让你在错误的战场上改很多轮, 且每一轮"看起来都有道理"(因为数字确实在动,只是动的是别的东西)。

原则 2:先确认"你量的东西就是你改的东西"(作用层)

最隐蔽的一类:探针挂在错误的层上,于是它量的永远不是你要改的那部分。 在这种状态下,"放宽/收紧判据"永远无效——因为你改的那个条件根本没被求值。

原则 3:量测区域必须与标注区物理分离

量像素/墨迹/包围盒时,任何为了给人看而画上去的东西(标签、参考线、水印、图例) 都会进入测量区,产出看起来很像真的假数字。

原则 4:断言必须在"修复前"能红(灵敏度自证)

一条断言如果在修复前也是绿的,它就没有测试任何东西。 断言的价值 = 它在坏状态下变红的能力,不是它在好状态下变绿。

原则 5:异步 / 缓存 / 渲染的"完成"不是"落盘"(时间层)

  • 任务"跑完" ≠ 结果"写盘完"
  • 渲染"调过了" ≠ 布局"算完了" / 缓存"生效了"
  • 长任务结束后去读产物,可能读到半成品(数字偏小、图不全) ⇒ 取证要么等落盘(按 mtime 确认最后一批文件),要么在同一次运行里串行取。

原则 6:集合类判定("可达 / 有效 / 在用")必须用严格口径

判"某个文件 / 分支 / 缓存条目还有没有用"时,"可达"只能按"当前代码真能产生的组合"定义 —— 不能把历史默认值、曾经传过的参数也算进"可达"。

本项目实测(2026-10-06,清理公式缓存):

  • 宽口径(把历史默认 wrap=493.0 / 465.74 / None 也算"可达")⇒ 把 801 个 wrap=493.0 的旧键副本误判为"活" ⇒ 只敢删 1160 个 ⇒ 清理不彻底;
  • 严格口径(只认 colour ∈ {FFA8CC,111111,FF0000,0000FF} × display ∈ {0,1} × wrap ∈ {_wrap_width_for(meta.font), inf},即当前源码里真会传出去的组合)⇒ 死 2005 / 活 671。

为什么"宽口径"更危险:它不报错,只是悄悄多保护了一批死物 —— 你会以为"我已经盘过了",其实盘的是另一套参数。(与原则 2 的"作用层"同源: 你以为你在数的集合,不是真正在用的集合。)

判据:写下"可达"的定义时,逐项对着当前源码的调用点核,不要凭印象加历史值; 每加一个历史值,都要问"现在还有谁传它"(本项目答案:没有 ⇒ 不该算可达)。

(对应下节 §六层分类 的 ⑥ 集合层;它与 ② 作用层的区别: 作用层是"判据没被求值",集合层是"判据被求值了、但口径太宽" ⇒ 修法不通用。)


六层分类(症状 → 换什么口径)

层病根典型症状换什么口径本项目案例(带 commit / 文件)
① 工具层shell / 编码把数据搞坏同一文件两种工具读出不同行数 / 不同长度换显式编码的 API;用字节级/repr() 核对source-code-recovery-from-pyc 反模式节:Get-Content 读本文件 195 行 vs ReadAllLines 264 行(差 69 行,无任何报错);bbc6388 把"PowerShell 吃反斜杠/中文"写进反模式(+33 行)
② 作用层探针挂在错误的层判据"放宽了却没有效果";结论"某方案能修"实际不能把探针下移/上移到真正被求值的那一层;先打印"这一层看到的是什么"某次改动 第一次实现(run 扫描 + 事后回填):在 region 级判"无中文"必然为假 ⇒ 结论"放宽判据能修"实际不能;设计稿首行记"架构错误,已回滚(HEAD 回到 23b6a5e)";重写时改成"在 region 内部再用 _MATH_LIKE_RUN_RE 切一层"才生效(bbe6a00)
③ 量测区层量到了区域外的像素数字"很像真的"但对应的是别的东西把标注移到测量区之外;测区先裁干净docs/screenshots/s2_diag/README.md:第一版把行标注画在最左 30px 内 ⇒ 纯公式行的"CJK 墨迹"扫到的是标签文字;第二版又扫到图里自带的中文标签 ⇒ 那两行改成只比"两变体是否相同"
④ 断言层断言恒真 / 恒假门禁全绿但线上还是坏的做灵敏度自证(把修复去掉,断言必须变红);用"能被区分的量"做断言改动 M 的第二坑:哨兵值 NO_WRAP_LIMIT 被翻译成 None,"不限宽"退化成"按默认算"⇒ 三条对照用例的宽都恰好 481.23、看不出区别(081ab05 的注释里写明);改动 O:delete_* 在旧实现下"删成功的返回 0",于是"删不存在的返回 0"这条断言无论修没修都绿 ⇒ 必须加"删存在的返回 ≥1"才有区分度(e2d3838)
⑤ 时间层异步 / 缓存 / 渲染的完成时点错位数字随"跑第几次"变化;产物不全等落盘(mtime)/ 同一次运行内串行取 / 把缓存清掉再量windows-path-damage-diagnosis 附录:验收测出 157s(全量重编译),真因是预热作业的最后一批文件写到 21:52:29 才结束,而验收跑在 21:51–21:52(磁盘上只有约 81/241 个公式);改动 L 的 _all_math_render 验收必须"先渲染再取",否则同一批片段会被量两遍(缓存时序);改动 M 的 PageTemplate 6pt 内边距是布局期才体现的(第一版钳到 493.23 后仍越界 6.00pt)
⑥ 集合层判"哪些还在用"时口径太宽(把历史值算进"可达")判据跑得好好的,但"活"的集合比实际大 ⇒ 清理不彻底 / 该删的没删;不会报错按当前源码枚举可达值(逐条对着调用点核,非凭印象)⇒ 见原则 62026-10-06 清理公式缓存:宽口径把 801 个 wrap=493.0 旧键副本误判"活" ⇒ 只敢删 1160;严格口径 ⇒ 死 2005 / 活 671(data/tmp/deleted_cache_20261006.txt)

上手核对清单(第一次怀疑测量时逐条过)

□ 1  这条数字是"哪个进程/哪次运行"产生的?(长任务:等落盘了吗)
□ 2  读它的工具,编码是否显式?(shell 默认可能是 GBK)
□ 3  它量的是"最终产物"还是"中间态"?(中间态可能还没提交/还没渲染)
□ 4  它的测区里,有没有"为了给人看"而画上去的东西?
□ 5  同一个量,换一种工具/口径再量一次,两个数一样吗?
□ 6  我这条断言,把修复去掉之后还会绿吗?
□ 7  探针自己有没有失败?(stdout 之外,stderr / 退出码 / 日志看了吗)

七条里任一条答不上来,就先别下结论——把"答不上来的那一条"当成待办的侦察任务。


换口径工具箱

目的别这么干改成
数行数(Get-Content $f).Count[System.IO.File]::ReadAllLines($f, <UTF8 no-BOM>).Count
看字符串真身直接打印(控制台会按 GBK 转身)repr() / 写文件再 read / 十六进制
核对字面量手抄 / -c 传参ast.literal_eval 对源码做字节级核对
量像素 / 墨迹目视 + 手工数程序裁测区 + 标注画在测区外 + 双工具交叉(如 pymupdf 抽取 vs 图像分析)
测"改好了没"只跑修复版去掉修复再跑一遍(灵敏度自证)
判"可达 / 还有没有用"凭印象 / 按标签(字段值、mtime、大小)分类逐条重建"当前代码会算出的键",反查是否命中;只用当前源码真能产生的参数组合(见原则 6)
读长任务产物任务一结束就读确认最后一批文件 mtime 已稳定;或改成同一次运行内串行

过滤 = 新测量:给输出加"形状假设",过滤本身就变成会骗人的尺子

核心口径:过滤不是"读取",是"新的测量"。 你写下的每一条过滤条件,都是给输出加了一个形状假设("标题长这样"、"失败长这样"、"这段应该含某个词")。 假设一旦错,你量到的就不是真相,而是"你以为的形状" —— 而且它不会报错, 只会安静地少给你几行,让你得出"少了 / 没跑 / 不存在"的结论。

判据(统计输出前先问这一句)

"我的过滤模式给输出加了什么形状假设?这个假设本身有没有验证过?"

三条配套铁律:

  1. 过滤是"提问",不是"取证" —— 可以用过滤来定位,但结论必须回到完整输出上验证;
  2. "没看到 X" ≠ "X 不存在" —— 在过滤结果里找不到,只说明"当前条件下没显示";
  3. 要断言"某段没跑 / 某分支没走",必须用"该段是否输出过标题 / 日志"来证明, 而不是"我没在过滤结果里看到它"。

本项目两个实例(同一个坑,隔一轮踩两次)

repr('== 气泡公式实时渲染冒烟(某次改动)==')
# startswith('== ') = True
# endswith(' ==')  = False     ← ★ 一个空格之差

⇒ 是我方比对方法错,不是代码问题。 且这是同一个坑第二次踩(离实例 1 只隔一轮)。

反模式

  • ❌ 用一个未经校验的过滤条件统计输出,然后据此下结论;
  • ❌ 把"过滤后为空"当成"不存在";
  • ❌ 正则 / 关键词 / 字段切分里隐含的格式假设,从不写出来、也从不验证;
  • ❌ 只在过滤结果里找"能支持我假设的行"(这已经是"先有结论再找证据")。

一句话:过滤让你看得更快,但也会让你更确信地看错 —— 下一次统计输出前,先把你的过滤条件当"被测对象"验一遍。


加探针会改变时序 —— 观测动作本身会改变被观测现象

"装个探针看看"不是中性的:探针会占时间、改 I/O、改调度顺序 ⇒ 被观测的偶发现象可能因此变形、变少、甚至消失。

条件耗时stderr 行数
探针开(qInstallMessageHandler 接管 Qt 消息)53s0
探针关66.3s123

⇒ 两个后果,都必须记住:

  1. 速度差 20%:探针吃掉了 123 行 stderr 写入(大输出重定向到文件很慢) ⇒ 不是"探针变快了",而是被观测系统的 I/O 形态变了;
  2. 现场形态变了:探针关时靠 stderr 找线索;探针开后那些线索只进日志, stderr 变干净 ⇒ 拿两次的 stderr 对比会得出错误的"变好了"。

判据:

  1. 探针只许"记录",不许"接管"(若必须接管默认输出,要在报告里写明);
  2. 同一现象在"探针开 / 关"两种条件下各测一次,把两次的耗时与输出形态都记下来;
  3. 报告里的数字必须标注它是哪种条件下测的 —— 否则前后两次不可比;
  4. 尤其对偶发 / 时序类问题:探针开久了抓不到,可能就是探针自己把它压住了。

同族:本 skill 的"时间层"(异步/缓存的"完成"不是"落盘")—— 本条是它的主动版: 不是"没等够",而是"我一等,它就不发生了"。


写/读两侧:PowerShell 重定向默认 UTF-16LE(写侧就出错,读侧才发现)

本项目第六次踩同一个坑(AI-1 / AI-1.5 / AJ-3c / 2026-10-21 连踩 3 次):用 PowerShell 的 > / *> 重定向 抓程序输出,默认写 UTF-16LE(带 BOM ff fe);按 UTF-8 读会得到空或乱码,且不报错。

版本相关:本机是 Windows PowerShell 5.1(默认 UTF-16LE);PowerShell 7 默认 UTF-8 无 BOM ⇒ 换到 PS7 上复现不出来,不代表规则过期,只代表你没在 5.1 上。

硬规则(动手前就该生效):要字节就别走 shell 重定向 —— 见 skill agent-execution-hygiene 规则 8 (还有 read_text() 归一 CRLF、Get-Content 走 GBK、cmd /c 吃 ^ 三种同族坑)。

凶案现场(AJ-3c):

按 utf-8 读 g_default_out.txt    ⇒ [OK]=0   · stderr 165 行 · QBasicTimer 0 次
按 utf-16-le 读(探测 BOM 之后)  ⇒ [OK]=378 · stderr  81 行 · QBasicTimer 2 次  ← 差之毫厘

⇒ 因为读错编码,我差点把"第二个 ① 现场"当成空文件跳过。

判据(照抄):

raw = p.read_bytes()
enc, skip = ("utf-16-le", 2) if raw.startswith(b"\xff\xfe") else ("utf-8", 0)
text = raw[skip:].decode(enc, errors="replace")

或者从源头避免:别用 shell 重定向 —— 在 Python 里 subprocess.run(..., text=True, encoding="utf-8") 拿到字符串再自己 write_text(..., encoding="utf-8")(本项目的采样脚本一直这么做; 只有"随手一条 PowerShell 命令"才会踩)。

为什么反复踩:read 工具读 UTF-16 文件会报 "invalid UTF-8"(会提醒你), 但用脚本按假设编码读不会报错(errors="replace" 还会把乱码变成 � 悄悄混进去) ⇒ 越是"自己写的读取代码",越要显式探编码。


文件复用 ≠ 单次运行 —— 别把"日志文件"当"一次跑"

同一个日志文件会被多次运行反复写入(轮转 / 截断 / 追加)⇒ 对着整个文件做统计,得到的不是"某一次运行"的数字。

判据:

  1. "一次运行的结果"只能来自该次运行自己的产物 (本项目的约定:data/tmp/aj*_runNN_stdout.txt / _stderr.txt / 对应的 qtmsg_*.log);
  2. 共享日志(agent.log)只用来"找人"(时间戳、线程名),不用来"计数";
  3. 若必须在共享日志上统计,先按"本次运行的起止时间"切片, 并在报告里声明切片依据;
  4. 尤其当结论是"某功能没生效 / 探针没工作"时:先排除"我读到的是旧记录"。

同族:本 skill 的"集合层"(我以为我测的集合 ≠ 我实际测的集合)—— 本条是它在时间维度上的版本:我以为的"一次" ≠ 文件里的"一次"。


截断的 dump 不能反推缺失的标签 —— faulthandler 的 Current thread

faulthandler 的 dump 里,标签本身就是证据:

  • 故障线程被标 Current thread 0x…;
  • 其它 Python 线程(含 Qt 建的线程,只要那一刻在跑 Python)标 Thread 0x…;
  • 打印顺序 = 解释器线程列表顺序 ⇒ 故障线程不一定排在第一个。
Windows fatal exception: access violation
Current thread 0x00006570 (most recent call first):    ← 故障线程(子线程),排第一块
  File ".../ctypes/__init__.py", line 525 in string_at
  File ".../aj11_ft_label.py", line 22 in child
  File ".../threading.py", line 1012 in run          ← …
Thread 0x000039c0 (most recent call first):            ← 主线程(也在跑 Python)⇒ 标 Thread
  File ".../aj11_ft_label.py", line 26 in <module>

凶案现场(AJ-11):第 6 次现场与采样 s run01 的 dump 都只落了第一个线程块 (结尾立刻又出现第二条 Windows fatal exception: access violation ⇒ dump 被第二次异常截断), 里面没有 Current thread 行。我据此推断"故障线程没有 Python 线程状态 ⇒ 崩在 native 层" —— 错。同一张卡里 sson 那次的 dump 完整(3 个线程块),显示:

Current thread 0x0000666c (most recent call first):
  File "<你的项目路径>\src\main.py", line 9095 in wait_until        ← loop.exec()
  File "<你的项目路径>\src\main.py", line 9237 in _smoke_note_classify
  …

⇒ 故障线程就是 MainThread,根本不是"native 线程"(与 AJ-6 的主线程栈同族)。

判据:

  1. 用 dump 下结论前,先确认它是不是完整的 —— 结尾有没有第二条 Windows fatal exception、有没有截断在行中间(帧缺 line N in func);
  2. 只有 Thread 0x… 块时,只能说"这次没照到 Current thread 块", 不能推"故障线程不是 Python 线程"—— 它可能只是排在后面、还没轮到就被截断了;
  3. 要断言"故障线程不在 Python 里",必须先排除截断(重跑取完整 dump,或换手段交叉验证)。

同族:本条与上面的"过滤 = 新测量"是同一个病的两种形态 —— "在(不完整的)观测里没看到 X" 被当成了 "X 不存在": 一个是我自己加的过滤丢了 X,一个是工具被截断丢了 X。


反模式

❌ 只看"过滤后的输出"就下结论(看哪部分的选择错)

不是工具错,是"我看哪一部分"的选择错 —— 过滤输出 = 主动丢弃信息, 而丢掉的往往正是反驳你结论的那一行。

[OK] 动画:进入 AWAKE 播放主坐姿 GIF(idle/default.gif,QMovie 在跑)
[OK] 动画:主坐姿 GIF 在 6 秒内解码完(帧数 564)      ← ★ 决定性线索

⇒ 段根本没被跳过;相反,"帧数 564"(= 真值)才是解释全局的关键(首次运行完整解码、 后续运行只到 37~52 帧)。我因为滤掉了 [OK],把最强证据亲手删掉了。

判据(照抄):

  1. 下结论前必须看"完整输出";确实需要过滤时, 先确认过滤条件不会丢掉"能反驳你假设的行"(尤其是 [OK] / 成功路径的行);
  2. 过滤是"提问",不是"取证" —— 过滤可以用来定位,但结论必须回到完整输出上验证;
  3. "没看到 X" ≠ "X 不存在":在过滤输出里找不到的东西, 只能说明"当前过滤条件下没显示",不能推论"没发生";
  4. 若结论是"某段没跑 / 某分支没走",必须用"该段是否输出过标题/日志"来证明, 而不是"我没在过滤结果里看到它"。

同族:本 skill 的六层分类(工具 / 作用层 / 物理分离 / 时序 / 严格口径)—— 本条属于**"看哪部分"的选择错**,是新的一层:观测范围(scope)层。

❌ 信 shell 的计数 / 编码

中文 Windows 上 shell 默认按 GBK 解码,UTF-8 无 BOM 文件会被拆坏:行数偏少、字被吃掉,且不报错。 (本项目同源事故三次:源码事故、Get-Content 行数、-c 传参吃反斜杠 ⇒ 见 recurring-root-cause-atlas 病根 ④)

❌ 在错误的层验证逻辑

"判据放宽了没效果"时,先问这个判据被求值了吗,而不是再放宽一次。 (某次改动 的教训:region 级判"无中文"必然为假 ⇒ 那一层的放宽永远不生效。)

❌ 量测区与标注区重叠

为了给人看而画上去的东西,会成为下一次测量的"数据"。标注一律离开测区。

❌ 写"永远为真"的断言当通过

绿 ≠ 有效。每条新断言都要回答"它在什么情况下会红";答不上来就补一个能红的。

❌ 用一个数字下结论

单点数字可能来自错的层 / 错的区域 / 错的时间。至少两种口径交叉,差异要能解释。

❌ 按标签分类删东西("看起来是旧的" ≠ "真的没用")

删除类操作里,绝不能按字段值 / mtime / 大小批量判死 —— 那些都是代理指标,不是"还有没有用"本身。

本项目实测(2026-10-06):按 meta.wrap_width_pt ∈ {493.0, null, 465.74} 一刀切, 会删掉 842 个活文件(493.0 801 + 465.74 38 + None 3)—— 它们全是当前代码仍会命中的条目。 正确做法:逐条重建"当前代码会算出的键"再反查(判活集合),只删判不出来的; 并在删除之前打印清单、在删除之后复核"残留判死 = 0"。

❌ 不看探针自己的失败信号


边界

能识别

  • 数字口径不一致(换工具即暴露)
  • 作用层错(判据改了没效果 ⇒ 先怀疑层)
  • 量测区污染(测区裁干净即暴露)
  • 断言无灵敏度(修复前去跑一次即暴露)
  • 时间层错位(同一次运行内串行即排除)

不能识别

  • 工具完全不可用(比如日志根本没写)—— 这时只能靠间接证据,且必须声明证据不足
  • 被测对象本身是非确定性的(如真实网络 / 并发调度)—— 只能靠重复采样

需要人工裁决

  • 两种口径都"说得通"时取哪个(这是业务判断,不是技术判断)
  • "数字差多少算噪声"(取决于量纲与用途)

一句话

数字不对先怀疑尺子:换工具、换口径、换层,最后让断言在修复前自己红一次。


本技能的价值全在"承认自己的数字可能是假的"——藏起来的假数字会让后面每一步都建在沙子上。

把无关信号算进阈值,指标就会持续误报或漏报。

  • 反例:用"孤立括号行数 = 0"当验收,把中文全角 ) 因排版折行单独成行也算了进去 ⇒ 永远不为 0, 于是反复判定"没修好",去改本来正确的代码。
  • 正确做法:让指标只对目标形态敏感(例如"矩阵里的数字是否还出现在文本层"—— 数字消失 = 已渲染成图;这类指标既正向、又不可伪造)。
  • 自检:给指标喂一个已知合格样本和一个已知不合格样本,两者必须给出相反结论。 只对"不合格"有反应、对"合格"也报警的指标,是坏指标。

原则 8:前置条件缺失 = 假通过

一个"全绿"的结果,可能只是因为你根本没测到目标路径。

  • 反例:渲染开关由 config 决定(默认关闭),测试脚本没传 config ⇒ 整份输出走"纯文字回退" ⇒ 图数 = 0 却判定通过;第二次补上 config 才发现真实情况完全不同。
  • 正确做法:测完核对"目标侧确实被触发了"(图数 > 0、日志里出现该分支、计数器非零)。
  • 通用句式:"这个通过的测试,能证明它真的执行了被测代码吗?" 答不上来 ⇒ 结果不算数。

原则 9:只查一个方向的差量断言(单向断言)

凡是 delta = now - t、a - b 这类差量比较,只断言一侧,就等于把另一半交给运气。

  • 反例:新鲜度检查只写 age_days = (now - updated_at) / 86400 > 30 ⇒ 过期。 有人把 updated_at 手写成 31 分钟后的未来时间,age_days 变成负数,> 30 永远为假 ⇒ 这条检查对任何"手写未来时间"的文件永久通过。不是偶尔失灵,是"愿意就能关掉"。
  • 正确做法:双边断言 —— 太旧要红,太新也要红。容忍度只用来吸收时钟抖动(本例 ±10 分钟), 并且写死在代码里,不做成可配置项(可配置就等于留了一个开关)。
  • 自检句式:"喂它一个未来值 / 上限外的值,它会红吗?" 不会红 ⇒ 它就是单向断言。
  • 推广:不止时间。分数(只查 ≥60、不查上限溢出的 120)、计数(只查非零、不查重复计数)、 哈希(只比前缀、不比全串)都是同款写法。任何比较都要问:上下界都断言了吗。
  • 更根本的一层:这次的真正根因不是"断言少写了一个方向",而是输入源由人手填。 人能随手填的字段没有测量价值。所以正确修法是两步 —— 加双边断言(拦住错误输入),且把输入源改成机器生成(datetime.now(),不给手动参数)。 只做第一步,等于给一个本不该存在的输入加了个检查。
  • 本技能对应的真实产物:tools/check_handoff.py 第 8 条断言(exit 8)
    • tools/bump_handoff.py(updated_at 只许机器生成)。

实战案例与复盘

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

  • 实例 1(2026-10-10 卡片 AH 侦察):只筛含"帧数 / AWAKE"的行
  • ⇒ [OK] 行全被滤掉 ⇒ 我断言"动画段被整体跳过" —— 错。
  • 完整输出里 [OK] 动画:主坐姿 GIF 在 6 秒内解码完(帧数 564) 才是解释全局的关键行:
  • 段没跳,是解码推进不足(首次运行 564 帧、后续运行只到 37~52)。
  • ⇒ 我因为滤掉了 [OK],把最强证据亲手删掉了。
  • 实例 2(同日卡片 AI-1.5 侦察):用 re.fullmatch(r"== .+ ==") 判"段标题"
  • —— 该模式隐含要求"标题结尾是空格 + ==",而本项目有 4 个段标题结尾不带空格
  • (…(卡片 16)==、…(卡片 6/8)==、…(卡片 F:A/B-1/B-2/B-4)==)
  • ⇒ 我据此断言"5 段没跑" —— 错。实测:
  • 本项目实测(2026-10-10 卡片 AJ-3c):同一个 --smoke,只差一个环境变量:
  • 凶案现场(2026-10-10 卡片 AJ-7):我把 data/logs/agent.log 全量按 ident 分组,
  • 统计"每个 LLMWorker 走了几步探针",得出 "65 个块里 62 个只有 ENTER/EXIT、0 步",
  • 并据此怀疑探针坏了。实际是:该文件混着多个版本、多次运行的记录 ——
  • 那 62 个块来自探针还没加步骤打点的时候(旧代码没写 step=)。
  • 只看本轮的独立产物 ⇒ 3 个块全部是完整 8 步 ⇒ 探针一直是好的。
  • 实验坐实(2026-10-11 卡片 AJ-11,data/tmp/aj11_ft_label.py):让 Python 子线程触发访问违例 ⇒
  • 真实案例(2026-10-10 侦察卡片 AH):为查"动画断言该红未红",我把 --smoke 的
  • 输出只筛含"帧数 / AWAKE / idle-default"的行 ⇒ [OK] 行全被滤掉 ⇒
  • 我据此断言"动画段被整体跳过"—— 错。把完整输出打出来后才看到:
  • 探针挂了却只看它的 stdout:
  • 卡片 L 的现场验证里,A\cdot B\(尾随反斜杠)渲染失败,日志在 stderr——
  • 如果没看 stderr,会得出"降级在所有段都成功"的错结论(真相是 14 段生效、1 段退回)。
  • | ② 作用层 | 探针挂在错误的层 | 判据"放宽了却没有效果";结论"某方案能修"实际不能 | 把探针下移/上移到真正被求值的那一层;先打印"这一层看到的是什么" | 卡片 46c 第一次实现(run 扫描 + 事后回填):在 region 级判"无中文"必然为假 ⇒ 结论"放宽判据能修"实际不能;设计稿首行记"架构错误,已回滚(HEAD 回到 23b6a5e)";重写时改成"在 region 内部再用 _MATH_LIKE_RUN_RE 切一层"才生效(bbe6a00) |
  • | ④ 断言层 | 断言恒真 / 恒假 | 门禁全绿但线上还是坏的 | 做灵敏度自证(把修复去掉,断言必须变红);用"能被区分的量"做断言 | 卡片 M 的第二坑:哨兵值 NO_WRAP_LIMIT 被翻译成 None,"不限宽"退化成"按默认算"⇒ 三条对照用例的宽都恰好 481.23、看不出区别(081ab05 的注释里写明);卡片 O:delete_* 在旧实现下"删成功的返回 0",于是"删不存在的返回 0"这条断言无论修没修都绿 ⇒ 必须加"删存在的返回 ≥1"才有区分度(e2d3838) |
  • | ⑤ 时间层 | 异步 / 缓存 / 渲染的完成时点错位 | 数字随"跑第几次"变化;产物不全 | 等落盘(mtime)/ 同一次运行内串行取 / 把缓存清掉再量 | windows-path-damage-diagnosis 附录:验收测出 157s(全量重编译),真因是预热作业的最后一批文件写到 21:52:29 才结束,而验收跑在 21:51–21:52(磁盘上只有约 81/241 个公式);卡片 L 的 _all_math_render 验收必须"先渲染再取",否则同一批片段会被量两遍(缓存时序);卡片 M 的 PageTemplate 6pt 内边距是布局期才体现的(第一版钳到 493.23 后仍越界 6.00pt) |
  • repr('== 气泡公式实时渲染冒烟(卡片 16)==')
  • File "<你的项目路径>\src\main.py", line 9095 in wait_until ← loop.exec()
  • File "<你的项目路径>\src\main.py", line 9237 in _smoke_note_classify
  • (卡片 46c 的教训:region 级判"无中文"必然为假 ⇒ 那一层的放宽永远不生效。)

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.