# PITFALLS 索引（自动生成，勿手改）

> 由 `/tmp/vi-agents/PITFALLS.md` 压成的一行一条索引。**用途**：续跑任务不必读全文 109KB——
> 先读这份索引，**再回原文读与本任务相关的条**。
> ⚠️ **索引只用于决定「回原文读哪几条」，不能替代读原文。**

> ✅ **规程实测（2025-??-??）**：用本索引＋定向精读 11 条的任务**跑通了**，
> 而前三次同任务全部死在「打开渲染图」那一步。**但 n=1，且该任务另有两个优势**
> （范围已缩小、关键结论已由父会话给出），**不能断言是索引单独起的作用。**

> ⚠️ **索引的已知事故**：曾有一条**活着的规则埋在已推翻的条目里**（反向检索，原第 77 条内），
> 按标题索引时指向了无关条目，执行者靠 `grep` 才找到。现已提升为独立条目 **103**。
> **这类事故会重演**——凡按行号回原文时发现「索引说的那条不是我要的那条」，**以原文为准，并回来补索引。**

| 行 | 标题 |
|---:|---|
| 3 | 一、页码偏移不能推导 |
| 29 | 二、目录不可信 |
| 33 | 三、文件身份的三重陷阱 |
| 35 | 陷阱 1：同一文件被重复收录 |
| 55 | 陷阱 1b：md5 查不出的两类重复（必须三路交叉去重） |
| 74 | 陷阱 1c：文件所有权错位（最严重） |
| 82 | 陷阱 2：文件名与内容无关 |
| 90 | 陷阱 3：版本号与元数据矛盾 |
| 96 | 四、必须判断文件性质 |
| 108 | 本批次实测：叫「品牌手册」的多半不是 VI 手册 |
| 120 | 五、"对不上"不能直接下结论 |
| 128 | 反向也要注意：记对了位置，也可能记错了内容 |
| 136 | 已确认的「引用指向另一份文件」 |
| 142 | 六、元数据检查命令 |
| 156 | 七、渲染建议 |
| 166 | 八、中文条款必须 200dpi 复核（实测误读案例） |
| 177 | 九、版本号陷阱的又一种形态 |
| 183 | 十、页码偏移会分段漂移，且新版本会推翻旧版本的偏移表 |
| 196 | 十一、性质判定的两条新捷径 |
| 201 | 十二、⚠️ 双页跨页合并：会让全库页数统计系统性偏低，且无法用元数据识别 |
| 217 | 十三、文件名与元数据 Title 互相矛盾时，两个都不可信 |
| 228 | 十四、命名不指示层级，只指示来源 |
| 242 | 十五、⚠️ 第 4 路去重：改版会被前三路全部漏判 |
| 259 | 十六、L2 单资产层的资产类型极度单一（实测） |
| 267 | 十七、⚠️ 「主动声明放弃」几乎不存在——用沉默定义的变量要警惕 |
| 281 | 十八、麦当劳 104 页件偏移存疑（按纪律 #5 不下结论） |
| 289 | 十九、Spotify 有两份页数相同但内容不同的文件 |
| 300 | 二十、⚠️⚠️ 最高危：pdftoppm ... - 不写 stdout，图像比对会静默返回空 |
| 336 | 二十一、⚠️ 文本层可能是替换密码，数值会静默出错 |
| 354 | 二十二、⚠️ 子 agent 的「实测值」也会错，必须抽验 |
| 364 | 二十三、⚠️⚠️ 「全量检索零命中」可能是纯故障——必须报告有效产出量 |
| 392 | 二十四、⚠️ 单页「中缝纯白」不能证明是跨页合并 |
| 426 | 二十五、⚠️⚠️ 合理的数字会填掉难辨的数字 |
| 445 | 二十六、⚠️ 「无文本层」不等于「没有内容」——它只等于「检索不到」 |
| 457 | 二十七、⚠️ macOS xargs 没有 -d，整条命令静默失败 |
| 469 | 二十八、⚠️ pdftotext 非空 ≠ 内容有效 |
| 479 | 二十九、⚠️ 装饰排版页在 100dpi 下错得最离谱 |
| 494 | 三十、⚠️ 小数点是本项目丢过最贵的字符 |
| 506 | 三十一、⚠️ 六轮变量判决的共同死法 |
| 525 | 三十二、⚠️⚠️⚠️ 找到文件 ≠ 找到正本 |
| 550 | 我在同一张 40dpi 联络表上同时读错了三处 |
| 562 | 两条延伸教训 |
| 567 | 附带取证纠正 |
| 573 | 三十三、⚠️ 子 agent 推翻父会话结论时，不要要求它「谨慎」——要保护它推翻的权利 |
| 583 | 三十四、⚠️⚠️ 页脚小字最危险：错在语义补全，不是乱码 |
| 606 | 三十五、⚠️ 并行会话会对同一文件给出互相矛盾的结论 |
| 624 | 三十六、⚠️⚠️ 关键词零命中可能是术语换了，不是内容没了 |
| 634 | 三十七、⚠️⚠️ 枚举足够多的切分，总会找到一个「显著」的 |
| 644 | 三十八、⚠️ 统计函数返回「所有 p 都是 0.0000」一定是实现有 bug |
| 654 | 三十九、⚠️⚠️ 容器指纹（Producer／Creator）不等于内容造假——按容器判会造出 2/3 假阳性 |
| 674 | 四十、⚠️⚠️ 找「不可能存在」的东西，不要只找「可疑」的东西 |
| 687 | 四十一、⚠️⚠️ 纵向对读的前提本身要先被检验——「同一个品牌的不同版本」经常根本不是同一本书 |
| 705 | 四十二、⚠️ 转交型出口：子文档版本号可能高于母手册 |
| 713 | 四十三、⚠️⚠️⚠️ 同一个标题在 30 / 200 / 600dpi 下被读错三次 |
| 733 | 四十四、⚠️ 任务前提里的「版本关系」可能根本不存在 |
| 743 | 四十五、⚠️⚠️ 批量抽取语料必须先验证产出，再相信「零命中」 |
| 756 | 四十六、⚠️ 关键词计数只能作召回，不能作证据 |
| 766 | 四十七、⚠️⚠️⚠️「agent 主动纠正」本身是需要复核的断言 |
| 786 | 四十八、⚠️ 断链有三态，最危险的一态是「检索成功但链接仍断裂」 |
| 802 | 四十九、⚠️⚠️ Agent 可能做完全部取证却没写报告——任务仍被标记 succeeded |
| 817 | 五十、⚠️⚠️ 分类失效的根因往往是「行定义不干净」，不是粒度太大 |
| 833 | 五十一、⚠️ 分类建完之后必须做留出检验 |
| 845 | 五十二、⚠️ 页码偏移不要照抄任务书，必须自己实测 |
| 857 | 五十三、⚠️⚠️⚠️「用后果句替代不可证伪」是一个恒真的门槛，不是修法 |
| 875 | 五十四、⚠️⚠️ 分类留出检验的三个必查项（本项目固化） |
| 885 | 五十五、⚠️ 反面教材：零命中最常见的成因是工具故障 |
| 895 | 五十六、⚠️⚠️⚠️「缺失型断言」的抽样区不只在页码里，还在「章节类型」里 |
| 915 | 五十七、⚠️ 用「证据类型」检查主张，别只检查证据 |
| 927 | 五十八、⚠️⚠️⚠️ 三次同类事故：agent 报告转述未经复核就写进仓库 |
| 948 | 五十九、⚠️「工艺名替代了数值」是错的——真正的零参数在金属侧 |
| 959 | 六十、⚠️ 免责条款的锚点可能不在你以为的地方 |
| 967 | 六十一、⚠️⚠️ 一个判据在 27 份样本里只命中 1 次——那是未经检验，不是「有效」 |
| 982 | 六十二、⚠️「不可证伪」的替换物必须能拒绝点什么 |
| 994 | 六十三、⚠️ 文本层可以是纯符号密文，连「密度」这个指标本身都是假的 |
| 1003 | 六十四、⚠️⚠️⚠️ 网络中断已四次吞掉已完成的工作——收尾必须与取证交替 |
| 1021 | 六十五、⚠️ 已出版手册里会有低级复制粘贴残留 |
| 1031 | 第 66–70 条（本轮新增，2026-10-14） |
| 1033 | 66 · net::ERR_CONNECTION_CLOSED 第 5 次吞档 —— 骨架必须先行 |
| 1041 | 67 · 200dpi 读对了，读法仍然不合规 —— 「读对」不能追认「读法」 |
| 1049 | 68 · 「有几个字重」有两个答案 —— 正文计数 ≠ 版面计数 |
| 1057 | 69 · 手册的字面会拼错，而且错得与对处无法区分 |
| 1064 | 70 · 分母不可比：-layout 的字节数 ≠ 字符数 |
| 1072 | 71 · 「跨页换算式」不能是全局式 —— 常数是每份文件各自的前置页数 |
| 1084 | 72 · 订正链会自我继承 —— 第二轮订正仍然错在同一个字上 |
| 1093 | 73 · 同一页上并存两个同类值时，小的那个会被当成全品类值 |
| 1104 | 74 · 同名不同物：.375"（Siren）与 50×50px（Wordmark 件）不是同一条规定 |
| 1109 | 75 · ⚠️ 一个不存在的错误，经过两轮审计被放大成需要「订正」的事实 |
| 1134 | 76 · 有些「错误形态」和「正确形态」是同一个字符串 —— 检索无法区分，这类订正从一开始就不可自动化核验 |
| 1150 | 77 · ⚠️ 本条已被推翻。原文描述的那个案例是伪造的。保留原文供追溯。 |
| 1183 | 78 · ⚠️ 渲染机缺字体 → 我们自己的目视验证会看到豆腐块，而我们会把它当成「这份件坏了」 |
| 1200 | 79 · 🔴 「X 份里 Y 份」的分母，是当初被送进裁决集的那批，不是全库 —— 而且那批本身就漏了 |
| 1218 | 80 · 「可打印率」这个指标测不出它被设计来测的东西 |
| 1231 | 78 · ⚠️ 修正：判据不是 emb=no，是字体形态 |
| 1252 | 81 · find -name ".pdf" 会静默漏掉大写扩展名 |
| 1259 | 82 · 一个判据「稳定」的真正原因，可能是它几乎不触发 |
| 1274 | 83 · 「空着的审批栏」会稳定命中设计为留空的模板 |
| 1285 | 84 · 有一层规定不以陈述句形式出现——漏扫时不会留下任何「我查过了」的痕迹 |
| 1299 | 85 · 🔴 「穷尽性」必须显式标记，因为它改变禁止力，而版面没有提示 |
| 1319 | 86 · 🔴 找到两处条款层与禁例层的真冲突——手册与自己冲突 |
| 1348 | 87 · 同一条规定被写两遍且详略不同——韩束的字号 |
| 1353 | 88 · 🔴 200dpi 不只漏字，还会补出限定语——风险是污染不是丢失 |
| 1375 | 89 · 引文里的转写约定会被下游当成原文去检索 |
| 1385 | 90 · 🔴 排版元素的位置必须先用 -bbox 定——猜位置比读错字更危险 |
| 1396 | 91 · 落库脚本用 index() 取第一个匹配，落在同名骨架段上 |
| 1409 | 92 · 🔴 反向检索只管「搜不到」，管不了「搜到了却扔掉」 |
| 1436 | 93 · 🔴 difflib 在大段移动上会给出与事实相反的结论——必须配第二个口径 |
| 1465 | 94 · 🔴 被引用最多的样本，会在记忆里冒充成唯一 |
| 1488 | 95 · 「CI 通过」是有分母的断言——本项目自己的检查器只覆盖 52.4% |
| 1518 | 96 · 🔴 扫描器必须先在已知阳性上灌测，否则会以「零误报」的样子交差 |
| 1537 | 97 · 文本层对排版元素的零差异率是 86.7%——而差异全部是空白类 |
| 1569 | 98 · 「数目相等」太容易成立，因此不能当判真依据 |
| 1578 | 99 · 🔴 同一会话内两个 agent 以完全相同的错误死在同一步——那不是巧合，是操作模式 |
| 1601 | 100 · 🔴 「把护栏提到前面」解决不了「读到但不评估」 |
| 1629 | 101 · 「代价」「警告」「免责声明」是三样东西，混在一栏里会让验收去找不存在的东西 |
| 1644 | 102 · 🔴 「订正栏」可以订正一个不存在的原值——而整行读起来仍然自洽 |
| 1675 | 103 · 宣布空白之前先跑反向检索：搜「谁写了这一条」 |
| 1697 | 104 · 🔴 HTTP 200 不携带「指针存在」的信息——而「检查链接是否可用」正是很多条款的核心动作 |
| 1716 | 105 · 「代价」栏测的是执行之后——样本停在执行之前时，你测到的 0 次触发不是「代价被避免」 |