Fapiao

Invoice - 发票专用解析技能

依赖：pdfjs-dist (Mozilla PDF.js) - 提供坐标提取能力

注意：本技能专门用于发票解析，与通用 PDF 处理技能 (pdf) 分离，避免重型依赖影响通用场景性能。

工具

本技能提供 extract 工具，用于提取发票结构化数据。

extract - 提取发票数据

参数：

返回字段：

调用示例

// JSON 格式输出
fapiao__extract({
  path: "invoice.pdf",
  format: "json"
})

// Markdown 格式输出
fapiao__extract({
  path: "invoice.pdf",
  format: "markdown"
})

// 保存到文件
fapiao__extract({
  path: "invoice.pdf",
  format: "json",
  output: "invoice_result.json"
})

返回示例

成功示例：

{
  "success": true,
  "failure_reason": null,
  "message": null,
  "text_content_length": 1423,
  "extraction_status": "SUCCESS",
  "invoice_number": "26512000000351324826",
  "invoice_date": "2024年03月15日",
  "invoice_type": "电子发票（增值税专用发票）",
  "seller": {
    "name": "某某科技有限公司",
    "taxId": "91110108MA00XXXXXX"
  },
  "buyer": {
    "name": "某某集团有限公司",
    "taxId": "91110000123456789X"
  },
  "total_amount": 10000.00,
  "total_tax": 1300.00,
  "total_with_tax": 11300.00,
  "item_count": 5,
  "page_count": 1,
  "remarks": "",
  "field_sources": {
    "invoiceNumber": 1,
    "invoiceDate": 1,
    "buyer": 1,
    "seller": 1,
    "amount": 1
  },
  "content": "{...}",
  "format": "json"
}

扫描件示例：

{
  "success": false,
  "failure_reason": "NO_TEXT_LAYER",
  "message": "PDF has no text layer (scanned image). Use OCR or VL model first.",
  "text_content_length": 0,
  "extraction_status": "NO_TEXT_LAYER",
  "invoice_number": "",
  "invoice_date": "",
  "invoice_type": "",
  "seller": { "name": "", "taxId": "" },
  "buyer": { "name": "", "taxId": "" },
  "total_amount": 0,
  "total_tax": 0,
  "total_with_tax": 0,
  "item_count": 0,
  "page_count": 1,
  "remarks": "",
  "output_file": null,
  "content": "",
  "format": "json"
}

异常示例：

{
  "success": false,
  "failure_reason": "FILE_NOT_FOUND",
  "message": "Cannot read file: /path/to/missing.pdf",
  "error": {
    "code": "FILE_NOT_FOUND",
    "stage": "pdf_read",
    "message": "Cannot read file: /path/to/missing.pdf",
    "cause": "ENOENT: no such file or directory"
  }
}

商品明细结构

对于多页发票，商品明细按页分组，每页包含：

{
  "pageNumber": 1,
  "issuer": "张三",
  "itemCount": 3,
  "items": [
    {
      "category": "*软件*",
      "name": "企业管理软件",
      "model": "V3.0",
      "unit": "套",
      "quantity": 1,
      "price": 5000.00,
      "amount": 5000.00,
      "taxRate": "13%",
      "taxAmount": 650.00
    }
  ]
}

技术实现

坐标提取原理

本技能基于 pdfjs-dist 的底层 API 实现坐标提取：

const page = await pdfDocument.getPage(1);
const textContent = await page.getTextContent();

const items = textContent.items.map(item => ({
  text: item.str,
  x: item.transform[4],      // x坐标
  y: item.transform[5],      // y坐标
  width: item.width,
  height: item.height
}));

发票解析算法

1. 路径安全：使用 path.relative + .. 边界判断 + realpath 双端校验，防止前缀欺骗和软链绕过
2. 坐标聚类：按 y 坐标聚类识别文本行
3. 列边界检测：基于标准发票布局定义列范围
4. 字段定位：
   • 发票号码：支持 8/20 位数字 + "发票号码"标签邻域提取
   • 开票日期：支持 YYYY年MM月DD日、YYYY-MM-DD、YYYY.MM.DD、YYYY/MM/DD 及 token 拼接
   • 公司信息：基于"名称："标签定位，支持右列搜索
   • 金额信息：基于 ¥/￥ 符号 + "价税合计"/"小写"标签 + 合计行 + 一致性校验
5. 商品明细解析：基于列覆盖率和坐标聚类判行，不强制 * 起始，允许 category 为空
6. 多页策略：全页扫描候选字段打分，自动选取最优值，保留字段来源页映射
7. 异常模型：统一 { code, stage, message, cause } 结构化异常

支持的发票类型

限制与注意事项

1. 扫描版发票：本技能基于文本坐标解析。当 extraction_status === 'NO_TEXT_LAYER' 时表示没有文本层（纯图片扫描件），返回 success: false。建议先用 pdf 技能的 render 操作将页面转为图片，再使用 VL 模型识别。

2. 非标准布局：如果发票布局与标准增值税发票差异较大，解析结果可能不准确。

3. 坐标精度：PDF 坐标系原点在左下角，y 轴向上递增，与屏幕坐标系不同。

与其他技能的协作

// 场景：扫描版发票处理
// 1. 先用 fapiao 技能尝试提取（会返回 NO_TEXT_LAYER 状态）
const result = await fapiao__extract({ path: "scanned_invoice.pdf" });
if (result.extraction_status === 'NO_TEXT_LAYER') {
  // 处理扫描件...
}

// 2. 用 pdf skill 渲染页面
const renderResult = await pdf__read({
  path: "scanned_invoice.pdf",
  operation: "render",
  output_dir: "./invoice_images"
});

// 3. 将图片发送给 VL 模型识别文字

错误码参考

快速参考

更新日志

• 2026-05-30: 架构审计修复版本

  • 修复路径安全：path.relative + realpath 双端校验替代 startsWith
  • 增加扫描件显式分类：text_content_length + extraction_status（NO_TEXT_LAYER）
  • 修正 success 语义：失败返回 success: false + failure_reason
  • 强化发票号解析：支持 8/20 位 + "发票号码"标签邻域提取
  • 强化日期解析：支持 -、.、/ 及 token 拼接多格式
  • 强化金额解析：统一清洗 + 合计一致性校验
  • 强化明细解析：列覆盖率判行，允许 category 为空
  • 扩展发票类型识别：专票/普票/机动车/二手车等关键词集
  • 多页字段选取优化：全页候选打分，保留 field_sources 来源页
  • 异常模型结构化：统一 { code, stage, message, cause }

• 2026-03-31: 初始版本，支持中国增值税发票解析

  • 基于 pdfjs-dist 实现坐标提取
  • 支持单页/多页发票
  • 支持 JSON/Markdown 输出格式

本技能基于 pdfjs-dist (Mozilla PDF.js) 开发，遵循 Touwaka Mate Skill 规范。