Datasheet Reading

---
name: datasheet-reading
description: >
  Reliably look up facts in engineering PDFs — chip datasheets, IC register tables,
  timing specs, and schematics. Use whenever you need to confirm a specific technical
  fact from a PDF: a register's bit definition, a timing minimum, a pin's power source,
  whether a component is fitted (NC), or "does this document even mention X".
  Trigger on: 查 datasheet · 芯片手册 · 寄存器定义 · 时序参数 · 原理图 · 看图纸 ·
  confirm from datasheet · what does register X do · is this pin connected to.
  Not for bulk format conversion — for turning whole documents into markdown for
  reading, use doc-to-markdown instead.
---

# 从工程 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 怎么做

### 第一步:体检(必做)

```bash
scripts/pdf_probe.py <file.pdf> -k 关键词1 关键词2
```

输出:实际页数、页脚标称页数(不一致会告警)、**文本层稀薄的页码**、
关键词命中页。退出码 `1` = 文本层不可信,必须看渲染页面。

### 第二步:定位后用视觉确认

```
Read 工具,file_path=<file.pdf>,pages="95-97"      ← 直接看渲染后的页面
```

一次最多 20 页。**表格、寄存器位图、时序图一律走这条**,不要用文本层的输出下结论。

### 第三步:原理图要放大看

```bash
scripts/pdf_render_page.sh <file.pdf> <页码> 300
# 输出 PNG 路径,再用 Read 打开;看不清就裁剪放大
```

原理图的文本层只有孤立字符串,**没有走线**,也分不清哪个标号连哪个器件。
`NC`(不贴)是最容易吃掉的信息 —— 同一个位号画在图上,贴与不贴电路完全不同,
而文本层里它只是个挨着的字符串。

## §6 三条硬规矩

1. **`pdftotext` 的输出只配用来定位页码,永远不用来证明"没有"。**
   要下"文档里没有 X"的结论,必须在渲染页面上确认过。

2. **发现矛盾,先花最小代价证伪,再下结论。**
   典型矛盾:`pdfinfo` 报的页数 ≠ 页脚 `Page N of M` 里的 M。
   别直接假设"文档是节选" —— **读一页目录**就能判定:
   目录若完整收尾(最后一章 + 修订历史),那 M 是模板残留数字,文档是全的。

3. **引用必须能点到出处**:写"手册 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` |