TbusOS 从工程 PDF 里查证事实
适用:芯片手册 / 寄存器表 / 时序规格 / 原理图 / 模组规格书。 核心不是"怎么把 PDF 变成文字",是什么时候不能相信变出来的文字。
§1 这是什么
一套查证纪律 + 两个体检脚本,防止把"文本提取失败"误读成"文档里没有"。
不是转换工具。要把整份文档转成 markdown 长期参考,用 doc-to-markdown。
本 skill 面向的是:读一两页,确认一个具体事实,然后据此下技术结论。
§2 没有它会怎样
pdftotext 对表格和图形会静默丢内容 —— 不报错、不警告、不留痕迹。
输出看起来完整、通顺,只是少了几行。于是:
| 你以为 | 实际 |
|---|---|
| "命令表里没有这个寄存器" | 表格提取时丢了半页 |
| "文档里搜不到这个参数" | 参数在图片式表格里 |
| "这两个网络没连" | 文本层本来就没有走线信息 |
| "文档是节选,缺的部分在后面" | 页脚是模板残留数字,文档是全的 |
这类错误不会报错、读起来完全通顺,能一路进对外材料和技术决策。
§3 为什么是这个设计
为什么不直接上 OCR / 视觉模型全文识别
替代方案:把每页都渲染成图,全部交给视觉模型读。没选,因为 一份 158 页的手册渲染 + 阅读的代价极高,而 95% 的查证只需要看 1-2 页。 先用文本层【定位页码】,再用视觉【确认内容】 —— 两步各用所长,代价最小。
为什么不做成"转 markdown"
替代方案:照 doc-to-markdown 的路子,先整份转好再查。没选,因为
转换本身也会丢内容,而且丢了同样不报错 —— 只是把问题往前挪了一步,
还多了一份可能过期的中间产物。查证要的是直接看原始页面。
为什么必须有体检脚本而不是写条注意事项
因为这条教训写进文档也会漏。长会话里早期读过的规矩会被上下文稀释,
执行时凭印象做。pdf_probe.py 把"哪些页文本层不可信"变成一条能跑的命令,
跑完直接告诉你必须去看哪几页。
§4 什么场景用
- 确认寄存器位定义、默认值、读写属性
- 确认时序最小值 / 最大值(复位宽度、上电间隔、建立保持)
- 确认某个命令/功能在不在这颗 IC 上
- 原理图上追某个网络的来源、确认器件贴不贴(NC)
- 给厂商/客户的材料里要引用手册页码和条款
不适用:通读学习一本书、把文档转成可编辑格式、生成 PDF。
§5 怎么做
第一步:体检(必做)
scripts/pdf_probe.py <file.pdf> -k 关键词1 关键词2
输出:实际页数、页脚标称页数(不一致会告警)、文本层稀薄的页码、
关键词命中页。退出码 1 = 文本层不可信,必须看渲染页面。
第二步:定位后用视觉确认
Read 工具,file_path=<file.pdf>,pages="95-97" ← 直接看渲染后的页面
一次最多 20 页。表格、寄存器位图、时序图一律走这条,不要用文本层的输出下结论。
第三步:原理图要放大看
scripts/pdf_render_page.sh <file.pdf> <页码> 300
# 输出 PNG 路径,再用 Read 打开;看不清就裁剪放大
原理图的文本层只有孤立字符串,没有走线,也分不清哪个标号连哪个器件。
NC(不贴)是最容易吃掉的信息 —— 同一个位号画在图上,贴与不贴电路完全不同,
而文本层里它只是个挨着的字符串。
§6 三条硬规矩
pdftotext的输出只配用来定位页码,永远不用来证明"没有"。 要下"文档里没有 X"的结论,必须在渲染页面上确认过。发现矛盾,先花最小代价证伪,再下结论。 典型矛盾:
pdfinfo报的页数 ≠ 页脚Page N of M里的 M。 别直接假设"文档是节选" —— 读一页目录就能判定: 目录若完整收尾(最后一章 + 修订历史),那 M 是模板残留数字,文档是全的。引用必须能点到出处:写"手册 p.156 §6.3.4 要求 ≥1ms",不写"手册要求 ≥1ms"。 页码和章节号是给对方复核用的,也是给三个月后的自己用的。
§7 真实教训(2026-08 两次)
其一:原理图。查某触控 IC 的 IO 供电来源,pdftotext -layout 的输出里
网络名、磁珠位号、两个候选电源挤在相邻几行,文本上完全看不出谁通谁断。
渲染成图一看就明白:一颗磁珠标着 NC 不贴,那条路断开,电源来自另一路。
项目原有的 IO 清单正是照文本层写的,那一条是错的。
其二:寄存器表。查某驱动 IC 的三个厂商私有寄存器。pdftotext 提出的
命令表止于某个命令,据此认定"表就这么长";又见页脚标称页数与实际不符,
便选了"文档是节选"的解释,结论"私有寄存器在缺失的部分里"。
改用视觉阅读后当场推翻两条:表格没断,后半页还有一批命令是提取时漏的; 文档不是节选,目录完整收尾,页脚那个数字是模板残留。
最终结论(那三个寄存器确实不在公开手册里)碰巧是对的,但依据全错 —— 属于蒙对,不算查证。
§8 同族 skill
| 场景 | skill |
|---|---|
| 整份文档转 markdown 长期参考 | doc-to-markdown |
| markdown 转 PDF | md-to-pdf |
| 产出 Word / Excel / PPT 交付件 | office-doc-delivery |
| 结论必须带出处的通用闸 | evidence-gate |