本地 PDF 表格提取（离线 · 带质量自检）
这个技能解决什么
从 PDF 里把表格抽成 CSV/JSON，并且告诉你哪几张表不能信。
同类技能的两个通病，本技能都绕开了：
| 通病 | 本技能的做法 |
|---|---|
| 要么内嵌付费网关/云 API/强制注册，要么输出乱码也不吭声 | 全本地、离线、零账号；乱码会被自动标记并在交付前拦住 |
| 表格解错了也照常交付，你事后才发现 | 逐表质量标记 + report.md 逐条列出「需要你处理的表」 |
何时触发
- 「把 PDF 里的表格提取成 Excel/CSV」「PDF 表格转 CSV」
- 「批量提取这个目录里的 PDF 表格」
- 「PDF 里的表格数据拿出来做统计」（先抽表，再交给别的工具）
- 需要离线处理、或不想把文件上传到云服务的场合
何时不触发（重要）
- 扫描件/图片型 PDF（表格是图片，选不中文字）→ 本地字体解析不适用，先走 OCR
- 「把数据生成 PDF 报表」→ 那是写 PDF，不是读
- 「编辑/合并/加密 PDF」→ 用 PDF 编辑类技能
- 「云端高精度表格识别（含手写体）」→ 那要云 OCR，本技能不联网
依赖
只依赖 pymupdf（本机通常已装）。缺失时脚本会打印可操作的安装命令：
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple pymupdf
pdfplumber 是可选的，只在 pymupdf 一张表都没找到时做交叉复核：
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple pdfplumber
工作流（按顺序执行，别跳步）
Step 1 · 提取
# 单文件
python3 scripts/extract_tables.py report.pdf --out ./build
# 整目录批量（递归找 *.pdf，单文件失败不影响整批）
python3 scripts/extract_tables.py ./pdfs --dir --out ./build
# 只要前 5 页和第 8 页
python3 scripts/extract_tables.py report.pdf --out ./build --pages 1-5,8
# 强制用 pdfplumber 复核（需要已安装）
python3 scripts/extract_tables.py report.pdf --out ./build --engine pdfplumber
Step 2 · 读报告，先看结论
必须打开 ./build/report.md，第一段就写着几张表不是「完整」。不要跳过这一步直接去用 CSV。
Step 3 · 处理被标记的表
report.md的「需要你处理的表」章节会逐条列出原因和内容预览- 标
失败/不适用的表不要用：要么换 OCR，要么人工录入 - 标
需复核的表：看预览判断结构是否切错（常见于复杂多栏排版）
Step 4 · 交付前自检
python3 scripts/extract_tables.py --check ./build
exit 0= 未发现解码失败痕迹，可以交付exit 1= 有乱码或仍有非「完整」标记的表 → 不要直接交付
输出契约（固定，可被下游程序直接读）
| 文件 | 内容 |
|---|---|
tables.csv |
固定 9 列：source,page,table_index,engine,row_index,cell_index,content,flag,remarks |
tables.json |
每张表一条记录：rows/cols/flag/reasons/bbox/data |
report.md |
人可核对的报告：结论、逐表清单、待处理表、页面情况 |
manifest.json |
汇总：输入清单、表格总数、标记统计、逐页元信息 |
质量标记取值（英文原值，不要翻译）：
| flag | 含义 | 可否直接交付 |
|---|---|---|
ok |
完整 | 可以 |
review |
需复核 | 人工看过再用 |
fail |
失败（整表解码失败等） | 不可以 |
not_applicable |
不适用（扫描件无文本层） | 不可以，需 OCR |
硬约束
- 不联网：脚本不 import 任何网络库（
requests/urllib/socket一个都没有），不上报，不读凭据环境变量 - 不要账号：没有 API Key、没有 Token、没有登录
- 不静默失败：解不出来的表进失败清单，不悄悄丢弃
- 不改原文件：只读 PDF，所有产物写在
--out - 批量安全：
--dir逐文件处理，单个文件出错只记错误、中断不了整批
已知边界（详见 references/failure-modes.md）
- 中文/日文 CID 字体若缺少 ToUnicode 映射，任何本地字体解析都会得到乱码 —— 本技能会标记并拦住，但拦住了不代表能修好，那种文件必须走 OCR
- 复杂多栏/旋转/嵌套表格可能被切错，标记为
需复核 - 无框线表格（靠空白分列）不一定能识别出来，可能返回 0 张表 —— 这不是 bug
- 完全没有文本层的扫描件：报
not_applicable，不做猜测
