发票提取器 —— 让 dsh 把发票读成能对账的数字

提取字段 + 验算 + 汇总台账 —— 把发票里的号码、日期、购销方、金额、税额 抽成结构化字段，同时替你检查 金额 + 税额 = 价税合计 到底成不成立。

给 DeepSeek Harness 用的自建工具插件：3 个工具，把「读发票」从猜数字变成可审计。

Compatibility: built and tested against dsh 0.2.0-rc.2 (preview). The apply(ctx) plugin spec is stable; verify against your own dsh version if needed.

---

一行安装

dsh plugin --profile desktop add github:yuehancn/dsh-tool-invoice

支持的 profile：desktop（桌面版）/ web（Web 版）。装完重启 dsh 即可用。

---

为什么需要它

让模型「看一下这张发票」，你得到的往往是一串看着合理、但没有验算过的数字。 而发票的全部可信度就在于一条恒等式：

金额 + 税额 = 价税合计

这个插件做三件普通正则做不到的事：

1. 验算，而不是抄写 —— 每条检查都同时给出「应该是什么」和「读到了什么」， 差了多少。对不上就是能行动的线索，而不是一个可疑的数字。
2. 给每条字段留下证据 —— 每个值都带着匹配到的标签（销售方名称） 和原句。会计可以复核，而不是盲信。
3. 不乱猜 —— ¥1130.00 单独出现时可能是金额、税额或合计。 所以每条规则都要求自己的标签在场，没有标签就报「未识别」， 而不是挑一个看着像的。

不 mock 一个字节：288 条断言对着真实 @deepseek-ai/dsh-tools 与真实子进程跑过。

---

三个工具

invoice_status

探本插件能不能自己读文件（有没有配文本提取命令），并列出它能识别的全部字段名。

invoice_extract(path | text)

从一份发票里提取字段并验算。可以直接给文件路径，也可以给你已经拿到的文本。

识别的字段：

字段	中文标签	英文标签
code / number	发票代码 / 发票号码	Invoice Code / No.
date	开票日期	Date of Issue
seller / buyer	销售方 / 购买方	Seller / Buyer
sellerTaxId / buyerTaxId	纳税人识别号	Tax ID
amount	金额（不含税）	Amount Excluding Tax
tax	税额	Tax Amount
total	价税合计（小写）	Total Amount
totalInWords	价税合计（大写）	Amount in Words
checkCode	校验码	Check Code
remark	备注	Remarks

返回的三条检查：

检查	含义
amount + tax == total	基本恒等式（容差可配：默认 ±2 分或 ±0.5%）
digits agree with 大写 amount	小写数字与大写金额是否一致 —— 扫描件出错时这一条最先报警
implied tax rate is a standard bracket	反推税率是否落在 0/1/3/5/6/9/13% 这些标准档位上

还有一个 faithful 布尔值：所有检查通过 且 号码/日期/合计都在 → true。 绝大多数调用只需要看这一个字段。

invoice_ledger(paths, groupBy, outputName)

把多张发票汇总成台账：总计、按字段分组的小计，并标出 没验算过的行、读不出来的行、以及重复的发票号码（重复报销的经典事故）。 加 outputName 会把台账写成 JSON。

---

容错到什么程度

真实发票文本很脏，所以解析器刻意宽松：

脏法	处理
全角数字 １２３４	折叠成半角
全角标点 ￥ １，０００．００	折叠成 ¥ 1,000.00
OCR 把 0 认成 O、1 认成 l	仅在数字串内部修复（不会碰公司名里的 O）
千分位 1,234.56 / 空格分隔 1 234.56	都认
日期 2026年10月02日 / 2026-10-02 / 2026/10/2 / 20261002	统一成 YYYY-MM-DD
标签和值不同行（两栏排版）	支持（标签独占一行时读下一行）
发票号码: 后为空、值在下一行	支持（不会把自己的冒号当成值）
红字发票 (1234.56)	识别为负数
大写金额 壹仟贰佰叁拾肆元伍角陆分	解析成 1234.56，并交叉验证
英文发票（Stripe 收据等）	同样支持

标签必须出现在行首。这是刻意的：Tax 会出现在 Amount Excluding Tax 里面，如果允许任意位置匹配，就会把「不含税金额」 当成税额读走 —— 这是实测踩到过的坑，有专门的回归用例。

---

配置

# ~/.dsh/profiles/<profile>/cordis.patch.yml
- id: tool-invoice
  config:
    outputDir: C:/Users/you/Documents/invoice-output
    # 想让插件自己读 PDF/图片，就配一个「文件转文本」命令
    textCommand: C:/poppler/Library/bin/pdftotext.exe
    textArgs: ["-layout", "{input}", "{output}"]
    toleranceCents: 2

配置项	默认	说明
outputDir	invoice-output	产物目录（中间文本、台账 JSON）
timeoutMs	600000	单次调用预算（10 分钟）
textCommand	空	留空则只接受文本输入；invoice_extract 仍可用
textArgs	["-layout","{input}","{output}"]	占位符 {input} / {output}
tolerancePercent	0.5	恒等式的百分比容差
toleranceCents	2	恒等式的分容差
status / extract / ledger	true	按需关掉某个工具

不配 textCommand 也完全可用 —— 只要你能拿到文本（比如先用 dsh-tool-ocr 插件、或从邮件正文里复制），invoice_extract 就直接可用。 textCommand 只是让你少一步手工。

接 dsh-tool-ocr：把 textCommand 指向 ocr 插件的 CLI 即可，两者串起来 就是「扫描件 → 文本 → 结构化发票」。

---

安全说明

• 只用 spawn(command, argsArray) —— 不拼 shell 字符串， 路径里有空格、引号、中文都不会出事（有专门的中文带空格用例）。
• 只读写你指定的输入文件与 outputDir，不上传、不联网。
• 文本提取命令是你自己配置的可执行文件，插件不下载、不安装任何东西。

---

跑测试

mkdir -p node_modules/@deepseek-ai
cp -r "$HOME/.dsh/profiles/desktop/node_modules/@deepseek-ai/." node_modules/@deepseek-ai/
node _test/run-all.mjs

三个套件，288 条断言全绿（对着真实 @deepseek-ai/dsh-tools 跑，不 mock）：

套件	断言	内容
test-logic.mjs	159	全角折叠与 OCR 混淆修复、金额解析（货币符号/千分位/负数/尾随噪声）、中文大写金额解析（含万/亿/角/分）、日期四格式、税号、标签锚定与特异性、三条验算、文档分类、台账汇总/分组/去重
test-integration.mjs	73	模块导出、注册数量、defineTool schema 归一化、三个开关、12 条错误路径、卡片标题、输出渲染
test-e2e.mjs	56	真的起子进程当文本提取器 → 真写文本 → 真提取；提取器退出非零/静默无输出的诊断；4 张发票的台账（含重复号与对不上的行）；脏输入（全角+OCR混淆+两栏排版）；英文发票；篡改大写金额的交叉验证

test-e2e.mjs 用自带的替身提取器 _test/fixtures/mock-text.mjs， 不需要装 poppler、不需要联网就能跑。

---

许可

MIT