发票 PDF 字段提取

> **本地运行，零网络、免 API Key、数据不出电脑。**
> 四项诚实承诺：① 算不出就说算不出，绝不编造数字；② 高危动作强制人工确认；③ 幂等断点，绝不重复副作用；④ 全程留痕可审计。

# 发票 PDF 字段提取

发票 PDF 是最没结构的数据。它像一张表格，其实是印刷品——文字位置由排版决定，字段靠"左边写着发票号码，右边写着那串数字"这种距离关系定义。

本包用纯标准库把 PDF 内容流解压出来，按顺序还原文本，再按字段关键词抽取。**它只做抽取，不做识别**：抽不到就是抽不到，宁可空着也不猜。扫描件（图片型的 PDF）没有文本层，本包明确告诉你抽不到，不会返回一堆空值假装成功。

## 输出四件套（每次运行必有）

| 文件 | 内容 |
|---|---|
| `pdf_主表.csv` | 每个文件一行：文件名 + 各字段 + `低置信字段` 标记 |
| `pdf_异常表.csv` | 抽取失败的文件与原因（无文本层 / 结构不符 / 必填字段缺失） |
| `pdf_校验表.csv` | 抽取字段清单、置信度、原文字片段样本、人工复核声明 |
| `fin-log.jsonl` | 处理日志（追加） |

## 环境准备

```bash
PY="<python 3.8+ 路径>"   # 纯标准库，无需 pip
"$PY" <skill目录>/scripts/pdf_extract.py <文件.pdf 或 目录> [参数]
```

## 用法

### 单文件

```bash
pdf_extract.py 发票_2026.pdf
```

真实输出：

```
方案：发票_2026.pdf | 页数=1 | 文本片段=47
  发票代码    =(未抽到)
  发票号码    24312000000000012345
  开票日期    2026-09-08
  购买方名称  深圳市某某科技有限公司
  销售方名称  广州某某物资有限公司
  金额        (未抽到)
  税率        13%
  税额        (未抽到)
  开票金额    22600.00
  校验码      0
  ⚠ 未抽到字段：金额、税额  —— 版面可能不标准，请人工核对
```

### 批量目录

```bash
pdf_extract.py ./发票目录 --out-dir _out
```

目录下所有 `.pdf` 一并处理，子目录用 `--recursive` 开启。

### 只要某些字段

```bash
pdf_extract.py ./发票目录 --fields 发票号码,开票日期,开票金额,销售方名称
```

## 抽取规则

| 字段 | 关键词 | 形态 |
|---|---|---|
| 发票代码 | 发票代码 | 10–12 位数字 |
| 发票号码 | 发票号码 / 电子发票号码 | 15–20 位数字 |
| 开票日期 | 开票日期 | `2026年09月08日` / `2026-09-08` / `20260908` |
| 购买方名称 | 购买方名称 / 购方名称 | 其后同一行的文本 |
| 销售方名称 | 销售方名称 / 销方名称 | 同上 |
| 税率 | 税率 / 征收率 | 数字或百分数 |
| 税额 | 税额 | 两位小数 |
| 开票金额 | 小写金额 / 合计金额 | 两位小数 |

**字段名与值之间隔了很远的排版距离**——本包按"关键词之后最近的一个数字/文本块"取值。这在标准版式下可靠，在自定义模板下会错。所以凡是关键字段没抽到，一律标记为「未抽到」而不是就近抓一个。

## 扫描件怎么处理

扫描 PDF 里全是图像，没有文本流。本包检测到这种情况会：

```
【算不出】发票_扫描件.pdf 没有可提取的文本流（很可能是扫描件或图片型 PDF）
建议：用带文本层的 PDF；或用 OCR 工具先转文本层。本包不做 OCR，也不会返回空字段冒充成功。
```

## 安全与边界（拒绝权）

- **文件零改动**：只读取，不写回
- **不做 OCR**：图片型 PDF 拒绝，转交专业工具
- **不猜字段**：抽象不到就写「未抽到」，绝不就近抓数字凑数
- **可核对**：校验表里附上抽取到的原始文本片段，你能直接比对

## 人工复核（必读）

- 抽取结果**必须与原票核对**再做台账，尤其是金额与税额
- 自定义模板的发票错误率会明显上升，建议先跑 3–5 张人工核对再批量
- 发票涉及税务合规，任何字段存疑都应退回原件确认

## 相邻路线转交

| 用户要做的事 | 转交给 |
|---|---|
| 扫描件转文本 | 外部 OCR 工具（本包不做） |
| 抽完批量改名 | `invoice-batch-rename` |
| 抽完查重 | `invoice-duplicate-check` |
| 抽完做台账汇总 | `invoice-book` |

## 可直接复制的说法

```text
把这个目录下的发票 PDF 都抽一遍字段，号码、代码、开票日期、购方、销方、金额、税率、税额。
拿到数字就行，版式不对没抽到的直接标"未抽到"，别就近抓一个数字凑上。
扫描件（没有文字的那种）单独列出来告诉我抽不了。
```

## 做完怎么算完成

- [ ] 每张票的关键字段都有值，或明确标了「未抽到」
- [ ] 数字字段与原票逐张核对过
- [ ] 扫描件已在异常表里列出
- [ ] 异常表里没有"原因不明"的空缺

---

本 Skill 采用 BUSL-1.1 许可（源码可见，可自由使用）。

版权所有 © 2026 律令科技（深圳）有限公司（@lexord-technology）。
本技能由律令科技（深圳）有限公司开发，**财友云（caiyouyun.cn）**发布与展示。

允许个人及企业内部免费使用、复制、修改，包括内部生产环境。
未经书面许可，不得将本 Skill 或其修改版作为商业服务对外销售、转售或提供托管服务。
各版本发布之日起 4 年后自动转为 Apache License 2.0。详见随包 `LICENSE.md`。