商品归类台账核对 PerryLink/dsh-hs-classify

dsh-hs-classify — 商品归类登记册层级一致性检查

dsh-hs-classify 读取一份归类登记册——报关抬头加每项一行——检查其中记录的编号结构：商品编号是否为十位，章、品目、子目是否为该编号的连续前缀，层级是否逐级变细，每行是否记录归类依据，抬头是否声明编号所属的税则版本，项号在登记册内是否唯一，以及品名中是否残留未替换的占位符。

它能回答什么

| 你问 | 它回答什么 |
| 我们登记册里有些编号是八位，还有一个以字母结尾。检查会报出来吗？ | 会。HC-001 把每个已填写的 hsCode 与包里的 pattern（^[0-9]{10}$）比对，报出该行以及读到的值。它只检查位数和字符，从不判断货物是否该归入该编号。编号单元格为空则跳过，所以它报的是形状不对的编号，不是缺失的编号。十位是包设置：年度税则改了长度，就改 pattern，不要改编号。 |
| 某行的章、品目、子目与商品编号对不上，能抓到吗？ | 能。HC-002 按从粗到细的顺序读取层级列——章、品目、子目，在包自带示例里分别是两位、四位、六位——报出不是所读 hsCode 前缀的那一级，或没有比上一级更细的那一级。它只检查前缀关系和这个顺序：编号是否与货物相符属于海关认定，需要税则和归类决定，本插件不查阅这些。层级单元格为空则不比对。 |
| 有一行归类依据留空。 | HC-003 报出该行：凡是带 basis 列的行都必须填写。它只检查那里写了东西，不检查所引税则条款、章注、归类决定或预裁定是否存在、是否支持该归类——本插件一概不查。如果登记册根本没有 basis 列，HC-003 会列在 skipped 里，理由是该材料没有这一列，而不是悄悄放过。 |
| 抬头没有说明编号属于哪个税则版本。 | HC-004 要求抬头声明 tariffVersion，抬头留空就报出该登记册。它只检查声明是否存在，不检查所写版本是否就是这些编号所属的版本：该规则不读编号，而编号在不同版本之间会拆分和合并。它的 fields 列表是包设置——如果你的抬头记录了 declarant，就加上。 |
| 项号 5 出现在两行。 | HC-005 把后一行报为前一行的重复，因为 itemNo 在同一份台账内必须唯一；比较时忽略空白，所以 5 和 5 算同一个项号。它只检查唯一性。同一项货物分多行申报，比如规格不同，每行需要不同的项号。项号全都不同时，HC-005 仍留在 skipped：此时列出的原因是材料满足检查的前置条件、未发现不一致的条目——这与规则因列缺失而无法运行时给出的原因不同。 |
| 品名列仍保留模板里的 【】 或 待填。 | HC-006 报出该行和它匹配到的占位符。规则包查找 【、】、{{、}}、XXX、xxx、待填、待补充、TBD、todo 和 示例，terms 可以裁剪成你自己的模板。它只找未替换的占位符：不判断名称对不对，也不要求该列必须填写——description 单元格为空不会触发它，本规则包中也没有其他规则要求填写。 |

遵循的标准

| 文件 | 编号 | 引用它的规则 |
| 《中华人民共和国进出口税则》 | 现行版本本次未核实 | HC-001, HC-004, HC-005, HC-006 |
| 《商品名称及编码协调制度》 | 现行版本本次未核实 | HC-002 |
| 《中华人民共和国进出口关税条例》 | 国务院令第392号（2003年11月23日公布；根据2011年1月8日、2013年12月7日、2016年2月6日三次《国务院关于修改（废止）部分行政法规的决定》修订） | HC-003 |

边界： 本插件检查商品归类台账中记录数字的结构——商品编码是十位，其章、品目、子目是它的逐级前缀，层级逐级变细，记录了归类依据，声明了税则版本，项号唯一，且没有占位符残留。它不判定货物应归入哪个编码。

⚠️ 它检查编码的形状，从不检查编码对不对

归类是海关的认定，取决于货物的材料、功能、加工程度，以及税则的类注、章注和任何归类决定或预裁定。本插件不查阅税则，不查阅归类决定，不查阅裁定。 所以：

- 它能发现「本行编码与同一行声明的章、品目、子目不一致」；
- 它不能发现「本行编码与货物不符」，因为那需要税则本身。

一份台账，编码结构完美但货物归错，能通过本插件。这是已记录的局限，写在文件头、HC-002 的注释和故障排查一节里。

规则包里的每一条 excerpt 都明确写着，条款原文未获取。 制度依据在《中华人民共和国进出口税则》——其编码为十位，前六位是 WCO 协调制度——以及《中华人民共和国进出口关税条例》。校验环节拿不到逐字条款原文，所以规则包在 excerpt 字段里直接写明这一缺口，并把每条规则都保持在 warn 或 info。拿到文本后，把每个 excerpt 换成真实条款，并把 kind 提升为 direct。 十位数的假设写在规则包的 pattern 里，所以年度税则调整只需改规则包，不用改代码。

兼容性

| 层面 | 状态 |
| 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 |

功能

注册 hs_classify 工具。它读取一份归类登记表——报关单表头加每项一行——套用带版本的规则包，返回报告。

| 规则 | 检查项 | 严重级别 | 依据类型 |
| HC-001 | 商品编号为十位 | warn | principle |
| HC-002 | 章、品目、子目是逐级前缀 | warn | principle |
| HC-003 | 记录了归类依据 | warn | direct |
| HC-004 | 声明了税则版本 | warn | principle |
| HC-005 | 项号唯一 | warn | principle |
| HC-006 | 描述里没有未替换的占位符 | warn | principle |

安装

dsh plugin --profile <name> add dsh-hs-classify
dsh --profile <name> --dump-config | grep 'dsh-hs-classify'

配置

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

值得了解的规则级参数：

- HC-001 pattern——编号的形状，默认十位。税则变化时改这里。
- HC-002 field / components / digits——编号列、由粗到细排列的层级列
（[chapter, heading, subheading]），以及期望的总长度。
- HC-004 fields——必须存在的表头字段，默认是税则版本。如果你的登记表记录了报关行，就加上 declarant。
- HC-006 terms——要查找的占位符。

材料格式

工具接受 JSON 或 YAML：

declarant: 某某报关行 tariffVersion: 2026 年版税则 rows:
- { 序号: '1', 品名: 便携式自动数据处理设备, 材质: 塑料外壳、金属结构件、电子元器件,
功能: 数据处理与显示，重量 1.2 千克, 章: '84', 品目: '8471', 子目: '847130', 商品编号: '8471300000', 申报日期: 2026-03-10, 归类依据：税则第八十四章章注及品目 8471 条文 }

列名匹配不区分大小写，并忽略空格、下划线和连字符；登记表自己的列名会保留，所以每条发现都会指明它读取的是哪一列。

规则来源

规则数据放在 rules/hs-classify.yaml。规则包的头部说明插件判断什么、不判断什么，每条规则的 note 会重复其中对该规则重要的部分。加载时的守卫通常要求「摘录必须是至少八个字符的真实引用」，但它分不清引用和描述——所以这个规则包靠头部、每条规则的 note，以及一个测试来兜底，该测试断言每个 excerpt 都承认这一缺口。

故障排查

- 它没有标记我明知对货物来说是错的编码。 它做不到：它检查编码的内部结构，不检查编码与货物是否匹配。归类需要税则和章注。
- 编码看起来没问题，HC-002 却触发了。 某个层级列与编码的前几位数字不一致。发现会指明是哪一层，并显示两个值。
- HC-001 在去年税则里的有效编码上触发了。 数字会随年度税则变化。改正编码，或者如果今年税则确实不同，就调整 pattern。
- HC-004 报告自己被跳过。 头部没有携带税则版本。编码属于哪一版税则很重要，因为编码会在不同版本之间拆分和合并。
- 插件装上了，工具却始终不出现。 检查 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-hs-classify@0.1.0 --dsh-version <runtime> --accept-risk
- check 报告 manifest-peers 失败。 静态检查器比对的是一个硬编码的 peer 范围，它早于 0.2 系列。运行时会在安装时强制校验 peer 兼容性，所以声明的范围才是正确的；这是 dsh-plugin-dev 里已知的上游问题。

开发

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-hs-classify # refresh src/shared from ../_shared

插件是纯数据的：src/model.ts 声明表结构，共享工具包提供读取器和检查引擎，规则包声明每一项检查。

许可证

Apache License 2.0 © 2026 dsh-hs-classify contributors.