PerryLink/dsh-einvoice

dsh-einvoice

官方仓库。 本包唯一官方仓库，由 PerryLink 维护；其他账号下的同名仓库与本项目无关。Apache-2.0。

文件级中国电子发票（OFD/XML）入库、解析、去重与本地归档。

状态：alpha / 公开合成 / partial / not counted / 非 GA。 不含客户证据、客户数据，也不作生产可用声明。

English · 简体中文 · Español · Português · हिन्दी

dsh plugin --profile <profile> add dsh-einvoice

⭐ 如果它帮到了你，点个 star 会让下一个人更容易找到它；没有任何功能被 star 解锁。

工作流：本地输入 → 插件 → 本地输出；不需要调用模型。

本地真实测试运行；不调用模型或网络。

快速了解（3 分钟）

一句话：把本地 OFD/XML 电子发票解析成八个字段并查重，全程留在本机。

适合：报销前几十到几百张电子发票的自查；同一张发票被两个主体重复提交的排查；把票据按期间归集。 不适合：需要税局验真、抵扣勾选的场景（本包不联网、不调税局接口）；扫描件/图片发票（不做 OCR）；PDF 发票。

输入：本地 .ofd（数电票 Tags/CustomTag.xml 或旧版 Attachs/original_invoice.xml）或 .xml 电子发票；UTF-8；单文件 ≤50 MB；来自开票方下载或财务系统导出。 自带样例：samples/quickstart/input/invoice-a.xml 与 invoice-a-copy.ofd（合成：发票号自造、税号 91330106TESTBUYER0 / 91310115TESTSELLER 明显为假值）。

输出：发票号、开票日期、购销方、金额/税额/价税合计（整数分）、明细行、字段证据与未知字段；重复分组与查询结果。原件与索引写在 $DSH_HOME/storages/dsh-einvoice，不改原文件。

示例：把这句话直接发给助手：

我把同一张电子发票分别报给了两家主体（invoice-a.xml 和 invoice-a-copy.ofd），帮我入库解析后查重，告诉我发票号和价税合计。

预期输出（真实运行结果）：samples/quickstart/expected/result.json。同一份样例的真实运行截图：

权限：

读：用户指定的 .ofd/.xml 电子发票文件；不读其他目录
写：$DSH_HOME/storages/dsh-einvoice（原件、索引与归档）；不改原文件
联网：否
外部系统：无（不调税局/发票查验平台，不做验真）

以上与源码一致：apply() 只从 DSH_EINVOICE_HOME（缺省 $DSH_HOME/storages/dsh-einvoice）取写入目录，源码里没有 fetch/http.request 等网络调用。会写盘的工具（invoice.ingest、invoice.review_queue、invoice.record_receipt、invoice.redlink、invoice.archive、invoice.restore）标 R1 本地写，只读工具（invoice.parse、invoice.query、invoice.dedup、invoice.check、invoice.tax_id_check、invoice.code_check）标 R0。

FAQ

1. 装不上怎么办？ 先看 node --version 是否 ≥24.9、dsh --version 是否在 >=0.2.1-rc.3 <0.4.0；再跑 dsh plugin --profile <profile> add dsh-einvoice。
2. 结果不对怎么办？ 先看 field_evidence（每个字段来自哪个部件/节点）与 unknown_fields；解析前必须 invoice.ingest。本包不做验真，金额勾稽只校验 价税合计 = 金额 + 税额。
3. 能处理我的发票吗？ 能处理标准 OFD/XML 电子发票；全程本机运行、不联网、不上传。PDF、扫描件、图片发票不支持。
4. 同一张发票为什么解析两次会报 E_INV_DUP_CONFLICT？ 同一主体下发票号唯一；这是防重复入池的保护。要保留两边记录，请用不同 entity_id（自带样例就是这样演示跨主体查重的）。

版本：0.2.0（alpha，counted=false，非 GA）。测试：node --test test/*.test.mjs 通过 32 项、跳过 6 项（公开样本缺失，属正常）、失败 0；验收见 ACCEPTANCE.csv。

安装

安装并验证：

dsh plugin --profile <profile> add dsh-einvoice
dsh --profile <profile> --dump-config | grep dsh-einvoice

卸载：

dsh plugin --profile <profile> remove dsh-einvoice

安装通道

推荐 npm；其他通道用于固定版本或离线。

• npm（推荐）: dsh plugin --profile <profile> add dsh-einvoice
• git 通道: dsh plugin --profile <profile> add github:PerryLink/dsh-einvoice
• tarball: pnpm pack then dsh plugin --profile <profile> add ./dsh-einvoice-<version>.tgz
• 1024 商店: npm i -g dsh1024 then dsh1024 plugin --profile <profile> add dsh-einvoice

它做什么

文件级中国电子发票（OFD/XML）入库、解析、去重与本地归档。 在 DeepSeek Harness 本地运行；下表就是实际工具面，示例使用真实命令面。

输入和输出都留在本地，不上传。

工具

工具名是稳定 API；说明已本地化。

工具	用途	风险
invoice.ingest	导入单个本地 OFD/XML，计算 SHA-256，保存原始文件，并以字节为准保证幂等	R1 本地写
invoice.parse	解析旧版 OFD 的 Attachs/original_invoice.xml 或数电票的 Tags/CustomTag.xml；返回八个字段、明细行、证据及未知字段	R0 只读
invoice.query	按主体、期间、生命周期或文本查询本地票据池	R0 只读
invoice.dedup	按发票号码或销售方 + 日期 + 总额对重复项分组	R0 只读
invoice.review_queue	将已解析发票排入本地人工复核队列；可选标记购买方税号不一致	R1 本地写
invoice.record_receipt	对本地回执计算哈希，追加该回执并推进生命周期；verification_source=local_receipt，tax_verified=false	R1 本地写
invoice.redlink	将负数红字发票与其蓝字发票绑定并保存差额	R1 本地写
invoice.archive	在本地归档目录下生成清单 + 原始文件 + 回执的 ZIP	R1 本地写
invoice.check	校验清单与成员哈希、缺失文件及路径穿越	R0 只读
invoice.restore	将已校验的归档恢复到本地恢复根目录	R1 本地写
invoice.tax_id_check	校验 18 位统一社会信用代码（GB 32100-2015 mod-31 校验位）	R0 只读
invoice.code_check	检查币种/国家/税类代码表（EN 16931）	R0 只读

快速开始

dsh plugin --profile <profile> add dsh-einvoice
dsh --profile <profile> --dump-config | grep dsh-einvoice

装上后，把上面「示例」里那句话发给助手即可。在仓库里也可以直接跑同一套工具：

pnpm build && node samples/quickstart/run.mjs

它会用 samples/quickstart/input/invoice-a.xml 与 invoice-a-copy.ofd 依次调用 invoice.ingest → invoice.parse → invoice.dedup → invoice.query，并打印结果。

示例

fixture 支撑的示例

输入: fixtures/public/mit/invoice-github-sample.xml

命令: pnpm test

验收行:

req_id	metric	threshold	actual	pass	source	counted
SKU-04-A01	八字段完整率（S1 合成样本）	>=0.98	1	true	public/synthetic	false

这是 fixture 支撑的验收行，不是客户运行；没有编造输出。

边界

• 仅公开/合成样例；不含客户数据或客户证据。
• alpha/partial、not counted，不作 GA 或生产可用声明。
• 除非工具明确说明，否则不调用模型、不联网。
• 每个工具的精确边界见工具表与 ACCEPTANCE.csv。

公开样例

公开/合成 fixture 在 fixtures/；ACCEPTANCE.csv 记录公开检查，全部 counted=false。

开发

pnpm install --frozen-lockfile
pnpm build && pnpm lint && pnpm typecheck && pnpm test

兼容性

维度	状态
Harness	dsh >=0.2.1-rc.3 <0.3.0
Node	>=24.9.0 <25
Platforms	All; local files only
数据	No network, no model call, no upload

权限与数据

• 本地运行；不联网、不调用模型、不上传。
• 只使用公开/合成 fixture；不含客户数据或客户证据。
• alpha/partial；not counted，不作 GA 或生产可用声明。

相关项目

兄弟包与家族索引： dsh-bankrec · dsh-ap-three-way · dsh-travel-recon · dsh-finops-suite

相关核查器（英文表）: Related checkers.

• 故障排查（英文）
• 领域索引
• Checker 家族
• 主线家族
• Scenario article

家族

Package	npm
dsh-einvoice	npm
dsh-docx-redline	npm
dsh-policy-ledger	npm
dsh-ghg	npm
dsh-bankrec	npm
dsh-ap-three-way	npm
dsh-ifc-qto	npm
dsh-qms-capa	npm
dsh-legal-intake	npm
dsh-legal-clause	npm
dsh-freight-audit	npm
dsh-hs-candidate	npm
dsh-travel-recon	npm
dsh-pim-lint	npm
dsh-eval-pack	npm
dsh-finops-suite	npm
dsh-contract-suite	npm

Package	npm
dsh-aqua-input-check	npm
dsh-archive-check	npm
dsh-bid-ca-precheck	npm
dsh-bid-qual-check	npm
dsh-contract-stance	npm
dsh-customs-doc-check	npm
dsh-demurrage-ledger	npm
dsh-drill-script-check	npm
dsh-eia-guide-check	npm
dsh-emergency-plan	npm
dsh-essay-rubric-check	npm
dsh-evidence-check	npm
dsh-export-ctl-check	npm
dsh-fmea-table-check	npm
dsh-forecast-penalty	npm
dsh-gongwen-flow-check	npm
dsh-gongwen-word-check	npm
dsh-guard-plan-qc	npm
dsh-hazchem-check	npm
dsh-hazplan-check	npm
dsh-hidden-risk-map	npm
dsh-hs-classify	npm
dsh-icd-rule-check	npm
dsh-lawcite-adapter	npm
dsh-lc-doc-check	npm
dsh-learning-gap-check	npm
dsh-medrec-qc	npm
dsh-nsfc-form-check	npm
dsh-nurse-record-check	npm
dsh-origin-rvc-check	npm
dsh-ota-review-check	npm
dsh-paper-doc-adapter	npm
dsh-permit-report-check	npm
dsh-pipeline-check	npm
dsh-pleading-draft	npm
dsh-policy-brief-draft	npm
dsh-power-loss-split	npm
dsh-power-ticket-check	npm
dsh-ppap-check	npm
dsh-protest-deadline	npm
dsh-railway-window	npm
dsh-repair-order-qc	npm
dsh-review-reply-check	npm
dsh-rulefile-check	npm
dsh-safety-brief-check	npm
dsh-site-log-check	npm
dsh-soe-decision-check	npm
dsh-soilwater-check	npm
dsh-sop-sync-check	npm
dsh-spc-gbt-adapter	npm
dsh-tender-extract	npm
dsh-tender-matrix	npm
dsh-warranty-calc	npm
dsh-auto-review	npm
dsh-autotier	npm
dsh-budget	npm
dsh-cert-mcp	npm
dsh-checkpoint-rewind	npm
dsh-claude-move	npm
dsh-click	npm
dsh-composer-history	npm
dsh-data-quality	npm
dsh-defend	npm
dsh-doublecheck	npm
dsh-draw	npm
dsh-fast	npm
dsh-fund-research	npm
dsh-industry-research	npm
dsh-laya	npm
dsh-library	npm
dsh-local-ai	npm
dsh-lsp-actions	npm
dsh-mask	npm
dsh-mcp-panel	npm
dsh-memento	npm
dsh-observe	npm
dsh-output-styles	npm
dsh-permission-rules	npm
dsh-plugin-guide	npm
dsh-plugin-upgrade	npm
dsh-reach	npm
dsh-research-report	npm
dsh-score	npm
dsh-session-sync	npm
dsh-talk	npm
dsh-test-drive	npm
dsh-translate	npm
	npm
	npm
	npm
	npm
	npm

许可证

Apache-2.0. See LICENSE, NOTICE, THIRD-PARTY-NOTICES.