workbuddy_skills/session-mechanism/references/00-动手前必过.md

动手前必过 · 六条（动手层）

pitfalls.md＝知识（47 条，问「为什么」时查）。 本档＝动作（开工前照做）。⛔ 别开工前通读 pitfalls。

同一天栽过四次，同一个形状：判据锚点自己没先验 ⇒ 推出了错结论。

⓿ 🔴🔴 说「会怎样」之前，先取证那个后果真的存在

这条是 2026-10-03 23:20 立的，当天我又犯了一次（10-04 17:1x）。

⛔ 不许把自己推测的后果写成事实。 否则「讲清后果」会退化成 「编一个后果、说得更像回事」——比原句更坏（原句至少只是啰嗦；编的后果是假情报， 会被当真话用）。

今天（10-04）栽的那次：我说「没启动脚本 ⇒ 常驻挂在会话进程树上 ⇒ 会话一关就被带走」。 实测：pid 19424 连跑 24.2 h / 8695 轮，父进程早已退出（孤儿进程）⇒ 不受会话结束影响。 ⇒ 我说的后果不存在。而正确答案早写在 supervise-persistence.md 里（还明写 「⛔ 不能用它论证这种起法也能长期」⇒ 我把它读反了）。

✅ 动手前问两句：

1. 我要写的这个后果，能不能拿一条读数证明？
2. 判据在哪？（先查判据 ⇒ 再写结论，⛔ 不是反过来）

📌 同源的第二条红线（也是 10-03 立的）： ⚠️ 改文案／解释改到第三轮还说不清 ⇒ 该问的是「这行要不要留」，⛔ 不是继续润色。 （「看不懂」往往不是措辞问题，是这行本身就不该在 —— 10-03 与 10-04 两天各撞一次。）

① 查状态 → 问那个程序自己

⛔ 不许用 glob／手拼路径证明"某文件不存在"（glob('**/x') 不穿透 .workbuddy 这类点目录 ⇒ 零命中 ≠ 不存在。今天就是这么把"常驻没跑"报错的）。

import collabd
ok, det = collabd.supervise_alive()   # ✅ 让它自己判
hb = collabd.SUP_HB                   # ✅ 路径问常量

东西	真身	程序自判
常驻心跳	<WS>/.workbuddy/collab/logs/supervise-heartbeat.json	collabd.supervise_alive()
停止标志	<WS>/tmp/supervise-inbox/guard.stop	collabd._guard_says_stop()
目标状态	<WS>/tmp/supervise-inbox/goal.json	collabd.goal_lifecycle()
台账四态	<WS>/tmp/supervise-inbox/tasks.json	⛔ 唯一权威，⛔ 别读 queue.json（已退役）
配置	<WS>/.workbuddy/collab/collabd.config.json	—

② 引用读数 → 先看它什么时候写的

台账 V5 写「PASS 48」，真跑 73；V1 写「pid 8024」，现活 19424。acceptance_state 每条带 _更新（本例停在 10-02 13:58）＝"当时验过"，不是"现在仍成立"。

凡带「现在／已／还差」的结论，读数一律现取。 pid · 心跳 · 计数 · pass 数 · 端口 · 排期状态——全都会随时间变。

③ 写判据 → 先让基线全绿，再谈抓得住

判据正则 width:\s*\d 误伤 CSS 里正当的 max-width:420px ⇒ 这条永远红 ⇒ 跑任何变异都"报红" ⇒ 5/5 全 ✅ 全是假象。

恒红比漏网更坏：它让所有变异都"红" ⇒ 验证作废，而表面看起来完美。 跑完变异先问「基线绿吗」，不是「几条报红」。

三条硬规矩：

1. 基线先全绿 —— 数 ✗ 且 ⛔ 排除「报告型」那些行（既有存量不计入成败）
2. 锚在「结构」或「唯一位置」 —— ⛔ 锚在"文本出现过"上（判 CSS 要剥注释＋只取那条规则块）
3. 变异脚本带两道护栏 —— ast.parse 判据源码 ＋ 必须真找到那条用例（否则"无输出"会被当成"全绿"）

④ 🔴 每个变异改完先验「被检对象真被改了」（长度差／md5）—— 今天栽过：脚本里锚点写错 ⇒ replace 什么都没改 ⇒ 变体被 ⏭ 跳过 ⇒ 汇总却按总数打"6/6 全 ✅" ⇒ 整轮验证作废。 ⇒ ⏭ 跳过必须计入失败，⛔ 不许从分母里去掉。

🔴🔴 写了一天纪律还是栽 ⇒ 那就上机器（2026-10-04 收口）

上面 ①～⑤ 是纪律。纪律拦不住 —— 我写完当天照样栽。根因收敛成两条（⛔ 不是六条各自独立的失误）：

根因	今天的表现（≥6 次）	机器抓手
A. 判据与被检对象之间的「连接」没被验证	判据里 lambda 自己重算；锚在「文本出现过」；夹具只覆盖顺带跑到的分支；锚点凭记忆写	judge_audit.py --audit selftest.py
B. 验证动作本身出错，而我不检查它	变异脚本自己 IndexError 却照样打 PASS；只重置一份文件 ⇒ 累积污染	judge_audit.py --mutate

⚠️ 两者的共同签名：判据绿灯与被检对象状态无关。所以解法不是「更小心」， 是让验证器自己的失败变成读数（rc≠0 且明说原因），⛔ 不许它输出得像结论。

# 🔴 每改完判据必跑（⛔ 别手写变异脚本 —— 手写的今天栽了三次）
python scripts/judge_audit.py --audit scripts/selftest.py     # 元体检：扫弱锚点写法
python scripts/judge_audit.py --mutate <被检文件> '旧文本' '新文本' -k <用例关键字>
#   ↳ rc=2 = 变异没生效／等价（⛔ 作废，⛔ 不许当通过）｜报红才算数｜自动核对还原 md5

⚠️ 元规则表也会假红：--audit 扫的是写法，分不清「引用教训」与「犯错误」 （实测把「自建夹具证明 glob 会漏」那条教训本身判成了错误用法）⇒ 误报要进 FALSE_POSITIVE 且写清为什么，⛔ 不许默默加。

④ 写沉淀 → 简明，判据要点一个不许丢

用户 2026-10-04 明令：「沉淀的经验不要记成流水账，要简明扼要有效」（这条本身也是经验）。 体检：pitfalls.md 47 条 140 KB，单条最长 11 KB；我当天新写的两条各 3 KB —— 比真复杂的 P0-41/22/23 还长 ⇒ 拿流水账充数。

单条上限 6 KB。超了就是流水账：论证过程、对比表格、逐条展开，⛔ 全删。 判据要点不许丢 —— 精简后必须关键词对账（长度达标但判据被删 ＝ 更坏，假绿）。

⚠️ 精简的顺序：先删论证 → 再压表格 → 最后才动措辞；⛔ 别一上来就重写（会把判据改丢）。

⑤ 报结论前 → 四问

1. 这个数字是现取的，还是从文档/台账抄的？
2. 我判"不存在/没在跑"时，问过程序自己了吗（还是只 glob 了）？
3. 判据改完了吗，基线绿吗（不是"几条报红"）？
4. 🔴 我写的每个「会怎样」，都有读数证明吗？（⛔ 拿不出读数的 ⇒ 删掉那句， 别让它"说得更像回事" —— 编出来的后果比原句更坏。10-03 立，10-04 又犯。）

---

🔴 读这份的时机：开工前 ｜ 报「已完成」之前。其余时候问「为什么」才去 pitfalls.md。