PDF表格抢救器

目录

• 定位
• 触发方式（怎么开口）
• 四步工作流
• 能力边界（量化）
• 异常处理（四类）
• 国内适配
• 边界声明（重要）
• 双包说明
• 常见问题汇总（FAQ）与使用案例
• 引用文件

定位

把「锁在 PDF 里」的表格数据抢救回 Excel：财务对账单、银行流水、上级下发报表、论文附表……复制出来是乱码、错列、挤成一坨，本技能按页提取表格还原成规整的 xlsx，无表格的页面提取纯文本兜底，扫描件如实报告。
核心理念：抢得回来的规规矩矩抢回来，抢不回来的如实告诉你为什么——绝不硬凑、绝不编数。

触发方式（怎么开口）

对话触发——识别到「PDF 里的数据要进 Excel」意图自动进入四步工作流：
- 「这个 PDF 里的表格帮我转到 Excel」（发文件即可）
- 「银行流水是 PDF 的，帮我把每笔交易提出来」（流水/对账单场景，常衔接 Excel 对账通做二次对账）
- 「PDF 第三页到第七页的表提出来」（可指定页码范围）
- 只说「PDF 转 Excel」也算触发，助手会追问：是文字版还是扫描件（不知道就先跑一遍看报告）

意图含糊或冲突时：用户既想「转 Excel」又想「顺手改数/凑平」——先明确本技能只做忠实搬运，修改与核对数据属下游对账环节（转 Excel 报表对账通流程），确认后再开工；未附文件时先向用户要 PDF 文件，不凭空猜测处理对象。

命令行直跑——想自己复现：

python scripts/rescue_tables.py --input 报表.pdf --out 抢救.xlsx [--pages 1-3,5] [--merge 1,4]

回读口径：本工具输入为 PDF 文件（非 JSON/模板），页码范围/合并页/输出路径等参数均为命令行显式传入，不存在骨架回读——每次运行以命令行参数与内置默认为准（缺省全页处理、不合并），无隐藏回读状态。

输出预览（节选自夹具实际生成的 xlsx「抢救报告」sheet）：

项目｜结果
源文件｜夹具.pdf
PDF 总页数｜4
本次处理页｜4 页：[1, 2, 3, 4]
含表格页数｜2
表格总数｜2
数据行总数（不含表头）｜2
数字单元格转数值｜3
合并区域｜未使用（跨页表默认不拼合，确属同一张长表可用 --merge 指定页码）
无表格页(文本已兜底)｜2
疑似扫描/图片页｜3
页码覆盖核对｜处理 4 页全部有归属：含表格 2 + 无表格文本 1 + 疑似扫描 1（重叠页按多类留痕），无遗漏
注意事项1｜跨页表格默认不自动拼合；确属同一张长表时可用 --merge 指定页码纵向合并

使用前提（依赖）：Python 3.8+ 与 pdfplumber、openpyxl（pip install pdfplumber openpyxl -i https://pypi.tuna.tsinghua.edu.cn/simple）；报 ImportError 时按命令安装后重跑。
--merge：确认连续页属同一张长表后，指定页码纵向合并到「合并-P…」sheet（用户明确指定才拼，坚持不猜原则）。

四步工作流

第 1 步：文件接收与类型预判

• 接收 PDF 文件；询问或自测是否文字版（有文字层才能抢救，扫描件不行）
• 红线自查：涉密/含个人敏感信息的文件，提醒用户本地处理即可，脚本不上传任何数据

第 2 步：抢救执行（脚本自动）

scripts/rescue_tables.py 按页处理：
- 有表格的页：每页一个 sheet（第1页、第2页…），页内多张表依次堆叠，每张表前有「第N页 表M（R行×C列）」标题行
- 无表格的页：正文提取进「无表格页文本」sheet（页码/内容两列），保证数据不丢
- 抢救报告 sheet（置首）：源文件、总页数、处理页、含表格页数、表格总数、数据行总数、数字转数值数、合并区域、无表格页清单、疑似扫描件页清单、四条注意事项
- 统计口径：数据行总数按每张表剔除首行（首行视为表头）计，无表头表以 sheet 内实际行数为准；--merge 合并 sheet 的行不重复计入报告统计——完整口径见 references/pdf-boundaries.md
- 数字自动转数值：纯数字单元格（含千分位/小数/负号）自动转数值类型，下游对账直接可算，只改存储类型不改数值
- 跨页长表合并：默认不拼（报告明示）；用户确认属同一张长表后用 --merge 页码 纵向合并，自动去重跨页重复表头（仅当后续表首行与首表表头逐格相同时才删，去重行数在合并 sheet 标题注明），列数不一致时短行右侧补空并在表头注明
- 页码覆盖核对：报告核对「处理页 = 含表格页 ∪ 无表格文本页 ∪ 疑似扫描页」——任何一页都至少归入一类并留痕（短文字页会同时出现在文本兜底与疑似扫描两个清单里），不存在既无表格也无兜底记录的漏网页
- 疑似扫描件检测：无表格页且提取文字过少即列入清单，有表格的页不因文字少误列——判定阈值与边界原理见 references/pdf-boundaries.md；如实报告，本技能不做 OCR，不假装能抢

• 自动恢复：结果文件先写临时文件再原子改名——中断/失败/超时后直接重跑同一条命令即可；超时看门狗强制退出和输出被占用两种路径都会清理残留临时文件，不会留半截文件。无自动重试与断点续跑（超长 PDF 建议按 --pages 分批，天然可断点）

脚本退出码：0 成功｜10 输入文件问题（不存在/非 PDF/页码非法）｜11 PDF 无法解析（加密/损坏）｜12 无可提取内容｜14 输出被占用｜15 运行超时（300 秒，重跑同一条命令）｜20 未预期｜21 缺依赖（提示安装 pdfplumber/openpyxl 后重跑）。对照 references/error-playbook.md 话术转述，不念退出码。

🛑 人工卡点：交付前两件事

1. 对照抽查：让用户抽 1–2 页，把抢救出的行数和 PDF 原页肉眼对一下——表格线识别偶有串行，抽查比全查省时间
2. 跨页表确认：报告里注明「跨页表格默认不拼合」——如果确认连续页属同一张长表，用 --merge 页码 合并后再抽查一次行数合计

第 3 步：交付

• 命名：抢救-原文件名.xlsx（用户可改）
• 交付话术带上报告要点：抢回几张表、几行数据、哪几页没抢到及原因

第 4 步：衔接下游（组合卖点）

• 抢救出的两表数据 → 可直接衔接 Excel 报表对账通做对账
• 抢救出的流水数据 → 衔接科室月报/报表生成流程
• 主动问一句「数据要不要顺手做下一步处理」，把单点技能串成流水线

能力边界（量化）

异常处理（四类）

详细话术见 references/error-playbook.md。

国内适配

• 输出 xlsx 兼容 WPS 表格；sheet 命名避开 Excel/WPS 保留字符
• 报告与提示全部中文；日期时间本地格式
• 本地处理：PDF 内容不外传不上云，脚本只读写用户指定文件

边界声明（重要）

• 只搬运数据，不修改、不凑数、不补数
• 抢救结果须经人工抽查核对后才用于对账/上报
• 扫描件与加密文件如实报告能力之外，不假装成功

双包说明

同办公技能矩阵：源码唯一底稿（office-skills/pdf-table-rescue/），双包同步，版本一致，评测驱动升版。定价与上架信息见 CHANGELOG.md 与发布平台。

常见问题汇总（FAQ）与使用案例

• FAQ 10 条：assets/faq.md（扫描件怎么办/跨页长表/串行/和对账通怎么配合等）
• 反模式集中清单：assets/anti-patterns.md（8 条数据误判类反模式：错误用法→会发生什么→正确做法）
• 使用案例：assets/examples.md（银行流水 PDF 抢救+对账的完整过程）

引用文件

• scripts/rescue_tables.py（按页抢救表格→xlsx+抢救报告+跨页合并+数字转数值，本技能核心脚本）
• references/error-playbook.md（异常处理话术+退出码映射）
• references/pdf-boundaries.md（表格识别原理、扫描件与跨页表边界说明、统计口径唯一来源）
• assets/faq.md（常见问题汇总）
• assets/anti-patterns.md（反模式集中清单，v1.4.5 新增）
• assets/examples.md（使用案例）