发票提取对账 yuehancn/dsh-tool-invoice

发票提取器 —— 让 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 插件的命令行即可，两者串起来就是「扫描件 → 文本 → 结构化发票」。

安全说明

- 只用 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