发票扫描

⚠️ 隐私声明

CLI 模式 将以 base64 编码的发票图像发送至 Anthropic 的 API（api.anthropic.com）。发票数据（供应商/买家名称、地址、IBAN、银行详情、金额等）将传输至第三方服务。请在使用前确认该行为符合您的隐私政策与合规要求。建议使用具备用量限制的专用 API 凭据。

Agent-native 模式 不对外发送任何数据——Agent 使用其内置视觉能力进行处理。formatOutput() 仅在本地调用，用于生成 CSV / Excel 输出。

安装配置

安装依赖项（首次使用前必需）：

cd {SKILL_DIR}/scripts && npm install --production

依赖项：sharp（图像处理）、xlsx（Excel 导出）。安装前请查阅 scripts/package.json 文件。

CLI 模式要求：设置环境变量 ANTHROPIC_API_KEY。
Agent-native 模式要求：无需任何配置——直接使用 Agent 内置视觉能力。

两种运行模式

模式 1：Agent-native（无需 API Key，无外部调用）

直接使用您内置的视觉能力查看发票图像。请勿调用 scanInvoice() —— 该函数需 API Key 且会对外发送数据。请按以下步骤操作：

1. 使用您的视觉能力查看图像
2. 将所有字段提取为一个 JSON 对象，结构须严格匹配 references/canonical-schema.md 中定义的规范 Schema
3. 识别并分类文档类型：invoice、credit-note、receipt、purchase-order、delivery-note、confirmation、statement、other-financial、not-financial
4. 依据 references/validation-rules.md 验证算术逻辑与业务规则
5. 呈现结果（参见下方“输出格式”）
6. 如需导出 CSV / Excel，请仅将您构建的规范 JSON 对象传入 formatOutput()：

const { formatOutput } = require('{SKILL_DIR}/scripts');
// invoiceData = 您通过视觉提取后构建的 JSON 对象
// 重要：必须包含 canonical-schema.md 中定义的所有字段，包括 charges[]
// 示例：invoiceData.charges = [{ type: 'shipping', label: 'P&P', amount: 5.99, vatRate: 20, vatAmount: 1.20 }]
const csv = formatOutput(invoiceData, 'csv');    // 字符串 —— 纯本地执行
const xlsx = formatOutput(invoiceData, 'excel');  // Buffer —— 纯本地执行

关键说明：formatOutput() 完全在本地运行——不发起网络请求，也无需 API Key。它仅将您提取的数据格式化为 CSV 或 Excel。

模式 2：CLI 独立运行（需 API Key）

适用于自动化流程或管道集成。需预先设置 ANTHROPIC_API_KEY 环境变量。

ANTHROPIC_API_KEY= node {SKILL_DIR}/scripts/cli.js scan  [--format json|csv|excel] [--output result.json]

支持选项：--provider claude、--accept strict|relaxed|any、--no-preprocess、--model

Agent-native 提取核对清单

必须完整提取以下全部字段：

页眉信息（Header）：invoiceNumber、invoiceDate（YYYY-MM-DD 格式）、dueDate、currency（ISO 4217）、supplierName、supplierAddress、supplierVatNumber、buyerName、buyerAddress、buyerVatNumber、paymentTerms、paymentReference、bankDetails（含 iban、bic、accountNumber、sortCode）

明细行项目（Line items）：description、quantity、unitOfMeasure、unitPrice、lineTotal、vatRate、sku、discount

关联单据引用（References）：PO（采购订单）、contract（合同）、GRN（收货单）、timesheet（工时表）、project（项目）、proforma（形式发票）、invoice（原始发票，若当前为贷记/借记凭证则必填）、credit-note、debit-note 引用。对于贷记/借记凭证，必须包含原始发票 reference。

合计金额（Totals）：netTotal、vatBreakdown（每档税率 + 金额 + 类型 —— 类型为税制标识，例如 "CGST"、"SGST"、"USt"、"НДС"、"IVA"）、vatTotal、grossTotal、amountPaid、amountDue、discount（整张发票级折扣金额）、discountRate（百分比）

元数据（Metadata）：paidDate（YYYY-MM-DD 格式，取自“PAID”盖章日期）、vatInclusive（true 表示 lineTotal 已含 VAT；false 表示为净额；null 表示未知）

附加费用（Charges）：非明细行项目的附加费用/手续费，例如 shipping（运费）、postage（邮费）、P&P（包装与运费）、delivery（配送）、freight（货运）、carriage（运费）、dispatch（发货）、handling（处理费）、insurance（保险）、eco-levy（环保税）、surcharge（附加费）等。每项须包含：type（shipping | handling | insurance | surcharge | discount | other）、label（文档中原始文本）、amount、vatRate、vatAmount。请勿重复提取已作为 line item 记录的项目。

文档类型（Document type）：documentType（invoice、credit-note、debit-note、receipt、purchase-order、delivery-note、confirmation、statement、other-financial、not-financial）

其他信息（Additional）：手写批注、印章/签章（type + text）、备注/评语、文档语言（ISO 639-1）

算术验证

1. quantity × unitPrice = lineTotal（逐行校验）
2. 所有 lineTotal 之和 = netTotal
3. netTotal + vatTotal = grossTotal
   （容差：±0.02，用于四舍五入误差）

本地化数字解析

自动识别区域数字格式：美式/英式（1,234.56）、欧洲式（1.234,56）、法式（1 234,56）、印式（1,23,456.78）。当格式存在歧义时，请结合 currency 或 country 上下文判断。

质量评分（Quality Score）

统计以下 9 个关键字段是否存在：invoiceNumber、invoiceDate、currency、supplierName、buyerName、supplierVatNumber、netTotal、vatTotal、grossTotal。
得分 = 存在字段数 ÷ 9。
good ≥ 0.8，partial ≥ 0.5，poor < 0.5。

输出格式

📄 发票 #{number} | {date}
   供应商：{name} → 买家：{name}
   净额：{currency}{net} | 增值税：{currency}{vat} | 含税总额：{currency}{gross}
   [如有附加费用] 📦 附加费用：{label} {currency}{amount} [逐项列出]
   [如 amountDue 非空] 应付金额：{currency}{amountDue} [如 amountPaid 存在]（已付：{currency}{amountPaid}）
   明细行数：{count} | 算术校验：✅/❌ | 质量评分：{rating}（{score}/9）

先列出所有警告/标记项，随后提示：“是否需要 JSON、CSV 或 Excel 格式？”

文件交付

• 输出目录：{WORKSPACE}/invoice-scan/output/（如不存在请自动创建）
• 命名规则：{supplierName}_{invoiceNumber}_{invoiceDate}.{ext}（空格与斜杠统一替换为短横线 `-`）
• 始终自动保存 JSON 文件；CSV / Excel 文件按需提供
• 以聊天附件形式发送文件，并确认完整路径

参考文档

• 完整 Schema 定义：references/canonical-schema.md
• 校验规则说明：references/validation-rules.md