⚠️ 本内容仅供一般信息参考，不构成法律、财务、税务、投资或医疗建议。 涉及合同签署、报税、投资、诊疗等专业决策时，请务必咨询持证专业人士，并由使用者自行承担决策后果。

本内容由 AI 生成，仅供学习参考

PDF 发票解析器（pdf-invoice-parser）

一、能力边界与适用对象（速查卡）

本 Skill 专注于从 PDF 格式的发票文件中提取关键业务字段，并执行基础的一致性校验。它面向财务人员、数据分析师、自动化流程开发者，以及任何需要将纸质或电子发票信息快速转化为可编辑数据的个人或团队。

适用对象：需要处理月度报销单、供应商对账单、电子发票归档的财务专员；需要从历史发票中构建数据集的审计人员；正在搭建 RPA 或低代码自动化流程的开发者。

二、触发方式与场景映射

当你的指令包含以下关键词或意图时，本 Skill 将被激活。请直接使用自然语言描述任务，无需记住特定命令。

三、标准执行流程

前置条件（输入准备）

文件可访问性：确保本地文件路径正确，或远程 URL 可直接下载（无防火墙拦截）。
文件有效性：PDF 文件未损坏，且非扫描图片（若为扫描件，需先进行 OCR 预处理，本 Skill 不内置 OCR 功能）。
环境依赖：Python 3.8+ 环境，已安装 pdfplumber 和 pandas 库（用于 CSV 输出）。

执行步骤（分步编号）

步骤 1：初始化与自检

运行以下命令检查环境是否就绪：

pdf-invoice-parser --selftest

若输出 Environment OK，则继续。若提示缺少依赖，请先安装：

pip install pdfplumber pandas

步骤 2：单文件解析（JSON 输出）

使用 --input 参数指定 PDF 文件路径，--output 指定结果文件（可选，默认输出到终端）。

pdf-invoice-parser --input ./invoice_sample.pdf --output ./result.json --verbose

步骤 3：批量解析（CSV 输出）

当需要处理多个文件时，使用 --batch 参数并指定一个包含所有 PDF 文件路径的文本文件（每行一个路径），或直接传入文件夹路径。

pdf-invoice-parser --batch ./invoices_folder/ --output ./all_invoices.csv

步骤 4：远程文件解析

处理网络上的 PDF 文件时，务必设置合理的超时时间，避免长时间挂起。

pdf-invoice-parser --input "https://example.com/invoice.pdf" --timeout 60 --output ./remote_result.json

输出规范

JSON 格式：输出一个包含所有提取字段的扁平 JSON 对象。字段名遵循 camelCase 规则。
CSV 格式：第一行为表头，包含所有字段名。后续每一行对应一个发票文件。
日志输出：使用 --verbose 参数时，会在 stderr 输出详细的处理日志（如 [INFO] Parsing file: xxx.pdf），便于排查问题。

JSON 输出示例（字段说明）：

{
  "invoiceNumber": "INV-2023-00125",
  "invoiceDate": "2023-10-26",
  "sellerName": "某某科技有限公司",
  "buyerName": "某某贸易有限公司",
  "totalAmountIncludingTax": 1130.00,
  "totalAmountExcludingTax": 1000.00,
  "taxAmount": 130.00,
  "taxRate": 0.13,
  "invoiceType": "增值税专用发票"
}

四、置信度门控与数据占位

当解析器遇到以下情况时，不会猜测或编造数据，而是输出特定的占位符，确保下游流程不会因错误数据而崩溃。

字段缺失：若 PDF 中找不到发票号码，则输出 [需核实:invoiceNumber]。
格式异常：若日期格式无法识别（如 2023/10/26 或 26-Oct-2023），则输出 [需核实:invoiceDate]，并附带原始文本到日志。
校验失败：若金额勾稽关系不匹配（如税额 ≠ 未税金额 × 税率），则所有金额字段均输出 [需核实:amount]，并在日志中标记 [WARN] Amount mismatch detected。

处理原则：占位符 [需核实:字段名] 是强制性的，任何情况下都不得用 null、0 或空字符串替代。这保证了数据审计的可追溯性。

五、错误码体系

当解析失败或异常时，程序会返回非零退出码，并输出错误信息。下表列出了常见错误及应对策略。

六、FAQ 与反模式对照

以下是使用过程中常见的误区及正确做法，帮助你避免踩坑。

七、渐进式阅读路径

本 Skill 文档信息量较大，可根据你的角色选择阅读重点。

新手快速上手（5 分钟）：
1. 阅读【一、能力边界】了解能做什么。
2. 直接跳到【三、标准执行流程】的步骤 1 和步骤 2，完成第一次解析。
3. 遇到问题再查阅【五、错误码体系】。
进阶用户（深度集成）：
1. 通读【三、标准执行流程】全部步骤，重点理解批量处理和远程文件参数。
2. 仔细阅读【四、置信度门控】，了解如何设计下游数据校验逻辑。
3. 参考【六、FAQ 反模式】，优化你的自动化脚本健壮性。
开发者（二次开发）：
1. 关注 CLI 接口的 --version 和 --selftest 参数，确保环境一致性。
2. 理解 JSON 输出结构，设计数据模型映射。
3. 关注错误码体系，编写针对性的异常处理分支。

用户协议

使用本 Skill 即表示您同意以下条款：

责任承担：使用者应自行承担因使用本 Skill 进行发票解析所产生的一切后果。对于因数据提取错误、数据丢失或任何直接、间接损失，本 Skill 的开发者及贡献者不承担任何责任。
合法用途：本 Skill 仅可用于合法目的，不得用于伪造、篡改或欺诈性处理发票。
禁止反向工程：使用者不得对本 Skill 的底层算法、核心代码进行反向工程、反编译或试图提取源代码（除非适用法律允许）。
无担保：本 Skill 按“现状”提供，不附带任何形式的明示或暗示担保，包括但不限于适销性、特定用途适用性和非侵权性。

许可证（License）

本项目采用 MIT 许可证授权。

MIT License

Copyright (c) 2024 LingDataWorks

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.