文档结构化提取助手｜PDF·扫描件·表格
把「这堆 PDF」变成「能用的数据」。本技能的核心是一条确定性提取路径：内置脚本 scripts/extract_doc.py 逐页判定文字层、提取正文、还原表格，输出结构化文件——同样的输入给同样的结果，不靠临场发挥。
工作原则两条：
- 先判定、再提取：有没有文字层决定走哪条路。判定结论会写进结果，来源可追溯。
- 提取不到就明说：无文字层的扫描页会明确标注「需 OCR」，绝不返回空结果、也绝不凭印象补内容。
适用场景
- PDF 提取文字：合同、报告、说明书、论文等含文字层 PDF 的正文提取
- PDF 提取表格：把表格还原成行列结构，输出 Markdown 或 Excel
- 批量文档数字化：成批 PDF 统一转成可检索、可编辑的结构化数据
- 递交前自检：先跑一次类型判定，快速看出哪些页是扫描件、需要另行处理
触发词：PDF提取、提取表格、PDF转文字、文档结构化、PDF转Word、文档数字化、PDF转Markdown、批量提取。
不适用场景
- 纯扫描件 / 图片的文字识别（OCR）：脚本不做图像识别。无文字层的页面会被明确标注，需要 OCR 时请使用具备视觉识别能力的工具，或先做 OCR 得到文字版
- 手写体识别：准确率有限，本技能不做承诺
- 需要公证或法律效力的提取物证：输出仅供辅助参考
- 音频视频转写：不在本技能范围
- 加密或带密码的 PDF：需要用户提供密码，本技能不做任何密码破解
依赖与安装
脚本按以下优先级自动探测后端，装哪个用哪个，无需配置：
| 后端 | 能力 | 安装 |
|---|---|---|
pdfplumber |
正文 + 表格结构还原（推荐） | pip install pdfplumber |
pypdf |
仅正文 | pip install pypdf |
pdfminer.six |
仅正文 | pip install pdfminer.six |
导出 xlsx 另需 pip install openpyxl。三者都没有时脚本会打印安装指令并退出，不会静默失败。
首次使用建议先装齐：
pip install pdfplumber openpyxl
> 脚本全程本地运行、不联网、不上传文件内容。
工作流程
提取进度：
- [ ] 1. 类型判定：跑 --probe，确认文字层分布与表格数量
- [ ] 2. 提取正文与表格：有文字层的页用脚本产出结构化结果
- [ ] 3. 处理无文字层页：按「扫描件分支」明确告知或转 OCR
- [ ] 4. 核对关键字段：金额、编号、日期 100% 核对
- [ ] 5. 交付：结果文件 + 类型判定说明 + 待人工确认清单
第 1 步 类型判定（必须先做，结论决定后续全部路径）：
python scripts/extract_doc.py --input 合同.pdf --probe
输出总页数、有文字层页数、无文字层页数、表格数与所用后端。
第 2 步 提取（有文字层的页）：
python scripts/extract_doc.py --input 合同.pdf --out 提取结果.md
python scripts/extract_doc.py --input 报告.pdf --format xlsx --out 提取结果.xlsx
python scripts/extract_doc.py --input 报告.pdf --format json --out 提取结果.json
脚本会自动完成：正文提取、表格行列还原、逐页类型标注、待人工确认清单生成。
第 3 步 扫描件分支（无文字层的页）：
- 若当前环境有 OCR / 视觉识别工具：逐页识别，按 提取操作指南 第三节的置信度规则标注不确定内容
- 若当前环境没有：明确告知用户——"第 X-Y 页无文字层，属于扫描件，本技能无法提取文字，建议先做 OCR 或提供含文字层的版本"。绝不静默跳过、绝不返回空结果、绝不凭上下文补内容
第 4 步 核对：金额、编号（合同号/单号/证件号）、日期三类字段 100% 核对，口径见 质量核对指南。
第 5 步 交付：结构化结果文件 + 类型判定说明 + 待人工确认清单。
交付物
提取结果.md/提取结果.xlsx/提取结果.json：按用途选格式- 正文为主、供阅读归档 →
.md - 表格为主、需继续计算 →
.xlsx - 需程序二次处理 →
.json - 结果文件内含四段结构：文件类型判定 / 正文（按页）/ 表格（按页，Markdown 表格）/ 待人工确认清单
- 文件名用「内容+日期」，如「采购合同-提取结果-2026-09-15.md」
- 用户未指定输出目录时先询问，不擅自决定
使用示例
示例一：文字层 PDF 提取表格
输入：「把这份销售报告 PDF 的表格提出来，要能继续算。」
动作：--probe 确认 12 页均有文字层、含 3 个表格 → --format xlsx 输出 → 打开核对行列。
输出：xlsx（含类型判定表 + 3 个表格工作表），类型判定注明「12 页全部有文字层」。
示例二：含扫描件的混合 PDF
输入：「这份合同扫描件帮我提取一下。」
动作：--probe 发现 20 页中第 15-20 页无文字层 → 提取前 14 页 → 对第 15-20 页明确告知「无文字层，需 OCR」，并列入待确认清单。
输出：md（前 14 页正文 + 表格）+ 说明「第 15-20 页为扫描件，未做识别，建议 OCR 后重跑或单独提供文字版」。
示例三：批量数字化
输入：「这 30 份 PDF 都转成 Markdown。」
动作：先抽 1 份 --probe 看类型分布并向用户说明节奏 → 逐份 --out 落盘 → 汇总每份的页数与无文字层页数。
输出：30 个 md + 一份汇总说明（含哪些文件存在扫描页）。
审核口径
- 不臆造：脚本提取不到的内容一律标注，绝不生成「看起来合理」的值
- 类型判定结论必须出现在结果里（各多少页有/无文字层）
- 无文字层的页必须出现在待人工确认清单中，且向用户明确告知
- 金额、编号、日期字段 100% 核对；修正必须有依据（字段格式、词义、大小写互证），并记入结果说明
- 表格行列与原文不一致时保留页码说明，不强行凑结构
- 脚本报错（缺依赖、文件损坏、加密）时如实转述并给出下一步建议，不掩盖
限制与注意事项
- 本技能不做 OCR：无文字层的扫描页无法提取，这是能力边界而非缺陷；需要识别扫描件请另配 OCR 工具
- 表格结构还原依赖
pdfplumber；用pypdf后端时不含表格，脚本会在结果中注明 - 文字层本身是坏 OCR 结果的 PDF（文字层为乱码），脚本会标记「文字层疑似异常」，建议以页面视觉核对
- 无边框表格、多栏排版、跨页表格的结构还原存在误差，需按质量核对指南抽查
- 加密或带密码的 PDF 需用户提供密码，脚本不做破解
- 数百页以上大批量任务先说明处理节奏，避免长时间无反馈
判定决策树、文字层提取要点、表格还原细节与常见坑见 提取操作指南；抽检方法、待确认清单模板与交付自检标准见 质量核对指南。
