报关单证核对 PerryLink/dsh-customs-doc-check

dsh-customs-doc-check — 报关单证台账一致性检查

dsh-customs-doc-check 读取一份报关单证台账，台账本身的列名可能是中文，也可能是英文。它检查的是这份台账，而不是台账背后的报关单：每一行是否至少填了货物名称和金额中的一项，商品编码是否为十位、币制是否为三位字母代码，单证编号是否重复，毛重是否不低于净重，记录的申报日期能否解析、是否晚于检查日期，以及货物名称列里是否还残留未替换的模板占位符。

它能回答什么

| 你的问题 | 它给出的答案 |
| 某一行货物名称还写着 待填，金额单元格为空——会有任何报告吗？ | CD-001 不会报告：它只要求货物名称和金额至少填一项，而 待填 不算空白。报告这一行的是 CD-007，它在货物名称列里查找规则包列出的占位符词条（【、{{、XXX、待填、TBD 等）。CD-001 从不判断申报内容是否真实；CD-007 只在这一列里查找这些词条，词条列表可以按你自己的模板调整。 |
| 商品编码写成 84713000——八位。会报告吗？ | 会。CD-002 用十位数字匹配单元格，其他一律报告。它只检查位数和字符是否合法，从不判断编码选得对不对：同一批货物在不同归类决定下可以合法地使用不同编码。位数是规则的 pattern 参数，税则调整位数时可以改。 |
| 币制列一行写 RMB，另一行写 usd——报告哪一行？ | usd：CD-003 接受三个大写字母。RMB 符合这个形状，能通过，因为规则只做形状检查，不管条款的措辞——条款指向的代码表没有拿到，规则也刻意不对 CNY 与 RMB 这两种写法表态，海关实务中两种都在用；如果你的内部规范固定了一种，把 pattern 收紧即可。它不判断所选币制是否适合这笔结算。 |
| 同一个单证编号出现在两行——检查会说什么？ | CD-004 报告重复的编号；比较时忽略空白。规则只确认唯一性：命中通常意味着同一份单证登记了两次，或者编号是从另一份单证抄来的，究竟哪一处错了要人来确认。它不判定哪一次登记才是有效的。 |
| 毛重读数是 1,180，净重是 1,250——这能查出来吗？如果某一行没有净重呢？ | 前者会报出来：CD-005 比较这两个值，毛重低于净重时报告该行。只比较数字，允许带单位（12.5KGS），这条规则从不判断申报重量是否真实。任一字段缺失的行根本不参与比较；如果因此没有任何可比较的内容，规则会落入 skipped 并给出原因，而不是报告差异。 |
| 台账里完全没有申报日期，还有一行的日期是 2026-13-40。会报什么？ | 那个不可能的日期会报出来：CD-006 要求日期能解析，且不晚于校验日期。申报日期缺失不作为缺陷报告——申报时该栏免予填报，由海关计算机系统记录，而非由报关人填写，所以规则只检查确实存在的日期。无法解析的日期单独报告，绝不悄悄跳过，规则也不判断申报是否在法定期限内完成。 |

遵循的标准

| 文件 | 编号 | 被哪些规则引用 |
| 《中华人民共和国海关进出口货物报关单填制规范》 | 海关总署公告 2019 年第 18 号（本次未取得条文） | CD-001, CD-002, CD-005, CD-007 |
| 《表示货币的代码》 | GB/T 12406—2022（表示货币的代码；2022-12-30 发布并实施；全部代替 GB/T 12406—2008（该版名称为「表示货币和资金的代码」）——注意旧版名称含"资金"；修改采用 ISO 4217:2015，非等同采用；条号本次未取得） | CD-003 |
| 《中华人民共和国海关进出口货物申报管理规定》 | 海关总署令（现行令号本次未核实） | CD-004, CD-006 |

边界： 这个插件检查报关单证台账中台账能被机械核查的部分——关键栏是否填写、商品编码和币种是否符合各自格式、单证编号是否唯一、毛重是否不低于净重、日期能否解析、模板占位符是否残留。它不判断申报是否真实、是否构成申报不实、是否影响税款、货物是否应查验或处罚。这些判断属于海关，同一批货物在不同归类决定下可以合法地使用不同编码。这个插件从不判断归类。

⚠️ 引用依据来自哪里

《中华人民共和国海关进出口货物报关单填制规范》已完整取得并逐条阅读（49 条加末尾定义），rules/evidence/clause-verification.md 记录了引用了哪些内容：第 34 条（商品编码为 10 位）、第 5 条和第 6 条（日期为 8 位，年月日，而且——值得知道——申报日期「在申报时免予填报」，所以台账缺少它是正常的）、第 39 条（币种取自《货币代码表》）、第 24–26 条（件数、毛重和净重）以及第 38 条。发布事实已对照官方公告确认：《海关总署公告 2019 年第 18 号》，日期 2019-01-22，自 2019-02-01 起施行，并废止了海关总署 2018 年第 60 号公告，所以引用那一个这根本就是错的。《进（出）境货物备案清单》是比照这份规范填写的。

由此更正了两处说法。 CD-003 原先说货币「应为三个字母」——而条文只说「按海关规定的《货币代码表》选择相应的货币名称及代码填报」，且那份代码表并未取得，所以「三个字母」是对代码表形态的推断，不是条文原话。CD-006 现在改为陈述上述豁免，不再暗示缺少申报日期就是缺陷。

每条 excerpt 仍写着「本次未取得」，每条规则也仍是 warn 或 info——这是有意为之。该规范管的是报关单各栏怎么填，而本插件检查的是企业的随附单证登记簿。登记簿不是报关单，把某条规则提到 direct，等于把登记簿的缺口包装成海关义务。《申报管理规定》以及各类代码表（关区、运输方式、监管方式、货币、国别、港口等）均未取得，这正是没有内置任何代码表的原因。规范正文本身读的是某地方贸促会的转载版，因为官方附件是 .doc，本工具无法解析二进制 Office 文件。

有两项检查值得单独说明。商品编码检查只核对十位数字，别的都不管——位数来自现行税则，这项检查从不说某个编码是不是正确的编码。货币检查核对三个大写字母，并且有意不对 CNY 与海关实务同样在用的 RMB 写法表态；如果你的内部规范只认其中一种，把匹配模式收窄即可。

兼容性

| 层面 | 状态 |
| Harness | 对等版本范围 >=0.1.2-rc.1 <0.2.0 \|\| >=0.2.0-0 <0.3.0——已验证可接受 0.2.0-rc.2 和 0.2.1-alpha.1。有意不声明 engines.dsh：它没有读取方，也无法拒绝宿主 |
| Node | ^22.19.0 || >=24.0.0 |
| 平台 | 全部（纯 ESM；无原生代码，无网络，不调用模型） |
| 工具模式 | 在 native、ptc 和 both 下均可工作；处理一批报关单时用 ptc |

功能

注册 customs_doc_check 工具。它读取一份报关登记簿——用单据自身的列名，中文或英文皆可——套用带版本的规则包，返回报告。

| 规则 | 检查内容 | 严重级别 | 依据类型 |
| CD-001 | 登记簿记录了货物名称和金额 | warn | 原则 |
| CD-002 | 商品编码为十位数字 | warn | 原则 |
| CD-003 | 货币为三字母代码 | warn | 原则 |
| CD-004 | 单证编号在登记簿内唯一 | warn | 原则 |
| CD-005 | 毛重不低于净重 | warn | 原则 |
| CD-006 | 申报日期可解析且不在未来 | warn | 原则 |
| CD-007 | 货物名称不含未替换的占位符 | warn | 原则 |

安装

dsh plugin --profile <name> add dsh-customs-doc-checkbash
dsh --profile <name> --dump-config | grep 'dsh-customs-doc-check'

配置

| 键 | 类型 | 默认值 | 说明 |
| rulesFile | string | rules/customs-doc-check.yaml | 规则包路径，相对于包根目录 |
| disabledRules | string[] | [] | 要停止运行的规则 id；每个都会出现在 skipped 里 |
| onlyRules | string[] | [] | 只运行这些规则 id；留空则运行全部规则 |
| skipNotes | string | "" | 追加到每条 skipped 原因后面的备注 |
| timeoutMs | number | 120000 | 协作式工具超时预算 |

几个值得了解的规则级参数：

- CD-002 pattern —— 商品编号的形态；默认要求十位数字。税则号列位数变了就改它。
- CD-003 pattern —— 币制的形态；默认要求三个大写字母。如果内部规范固定了一种写法，就把它收紧成当地币制的唯一拼写。
- CD-005 relation —— 毛重与净重之间的比较关系，默认 gte。
- CD-007 terms —— 要查找的占位符。

材料格式

工具接受 JSON 或 YAML： yaml declarationNo: '530120260310000001' consignee: 某某进出口有限公司 contractNo: SC-2026-018 rows:
- { 单证种类: 发票, 单证编号: INV-2026-0001, 商品编号: '8471300000',
商品名称: 便携式自动数据处理设备, 数量: '100', 总价: '45000.00', 币制: USD, 毛重: '1250.5', 净重: '1180.0', 申报日期: 2026-03-10 }

列名匹配不区分大小写，并忽略空格、下划线和连字符，所以 商品编号 和 hsCode 会解析到同一个字段；登记簿自己的列名会保留下来，因此每条发现都会指明它读的是哪一列。数字单元格可以带单位和千位分隔符（12.5KGS、1,250.5）。

规则来源

规则数据放在 rules/customs-doc-check.yaml。规则包的头部完整说明了引用缺口，每条规则的 note 会重复该规则相关的部分。加载时的守卫通常会强制「摘录必须是至少八个字符的真实引文」，但它分不清引文和描述——所以这个规则包靠头部、每条规则的 note，以及一个断言每条 excerpt 都承认该缺口的测试来兜底。

故障排查

- CD-002 在我明知有效的编号上报错。 单元格不是正好十位数字——可能带尾部空格、点号，或子项后缀。把导出数据规范化，或者改 pattern。
- CD-003 在 RMB 上报错。 默认 pattern 接受任意三个字母，所以这说明单元格不是三个字母——RMB￥、人民币，或小写代码都会失败。规范化，或者收窄 pattern。
- CD-006 在未来日期上报错。 这正是检查本身：申报日期晚于审核日期，意味着要么日期错了，要么审核基准错了。
- 读取器拒绝了一份它以前接受的登记簿。 它没找到任何已知列名；错误信息会列出它看到的列。
- 插件装上了，但工具始终不出现。 检查 main 是否解析到 lib/index.mjs，并且
pnpm run build 生成了它；main 写错会让加载器静默跳过入口。
- dsh plugin add 拒绝该包，报不兼容。 peer 范围覆盖 0.1.x 和 0.2.x；如果你的运行时不在这个范围内，显式授予豁免：
dsh plugin --profile <name> allow-version dsh-customs-doc-check@0.1.0 --dsh-version <runtime> --accept-risk
- check 报告 manifest-peers 失败。 静态检查器比对的是硬编码的 peer 范围，早于 0.2 系列。运行时在安装时强制执行 peer 兼容性，所以声明的范围才是正确的；这是 dsh-plugin-dev 中已知的上游问题。

开发 sh
pnpm install
pnpm run typecheck # tsc --noEmit
pnpm test # vitest, the shared table-plugin suite plus paired fixtures
pnpm run build # tsdown -> lib/index.mjs + lib/index.d.mts
node ../scripts/sync-shared.mjs dsh-customs-doc-check # refresh src/shared from ../_shared

插件是纯数据的：src/model.ts 声明表结构，共享套件提供读取器和检查引擎，规则包声明每一项检查。如果某项检查符合已有的类型，只需改规则包，别的什么都不用动。

许可证

Apache License 2.0 © 2026 dsh-customs-doc-check contributors。