出口单证齐套与一致性体检

定位与服务边界

这个 Skill 只做一件事——在把一批出口单据交给货代、报关行、银行或客户之前，把单证之间对不上的地方一次挑干净。

它不做报关申报、不算税、不查汇率、不解释贸易术语的法律含义。出口单证事故里有很大一类根本不是「哪张单错了」，
而是两张单各自都没错，但彼此对不上：发票金额 46,800、投保单写 46,000；提单 118 件、装箱单 120 件；
产地证 HS 写 10 位、发票写 7 位。放行前没人交叉核一遍，这些就是退单或事后被追责的起点。

它也不判断商业条款是否合理，不替代货代、报关行、银行或律师的审核。它只做确定性的字符串与数值比对。

三分钟上手

第一步：把单据放进一个目录

支持文本类：.txt .md .csv .json .ini .properties。
pdf / xlsx 不解析——先把内容导成文本（或另存为 .txt）再跑。

第二步：先跑 demo，看清它长什么样

python scripts/doc_audit.py --demo --out ./out

会生成一套示例单证（含刻意埋进去的问题）并出报告。用它先知道报告长什么样，再换成自己的单据。

第三步：跑自己的单据

python scripts/doc_audit.py --path ./单证目录 --out ./out

指定必须齐备的单证类型（可选，但建议）：

python scripts/doc_audit.py --path ./单证目录 --out ./out --require invoice,packing_list,bill_of_lading,origin_certificate

单据字段叫法跟内置别名不一样时，传一份映射（不要改脚本）：

python scripts/doc_audit.py --path ./单证目录 --out ./out --field-map my_fields.json

my_fields.json 长这样：

{
  "seller_ref": ["客户参考号", "cust ref", "客户号"],
  "no_of_packages": ["箱数", "总箱量"]
}

打印一份模板看格式：python scripts/doc_audit.py --template

第四步：接进流水线（可选）

python scripts/doc_audit.py --path ./单证目录 --out ./out --fail-on-block

有阻断级问题时退出码返回 2，可以直接当 CI / 交付前卡点。

输出契约

命令结束时 stdout 两行：

单证 5 份，问题：阻断 2 / 警告 2 / 提示 0；跳过 0 份
已出报告：C:/out/单证齐套与一致性报告-20261003-094414.md

产出两个文件（文件名带时间戳，多次跑不会互相覆盖）：

问题分三级，含义固定：

报告章节编号按实际内容动态生成：某章没有内容就不出现，编号不会出现断档。

退出码封闭为三个值：

--fail-on-block 且存在阻断时，退出码为 2。

检查项清单

单证内（逐份）

• 必填字段缺失——按单证类型判定（发票要有发票号/总额/币种/开票日/发货方/收货方/品名/HS 编码；提单要有起运港/目的港/件数/毛重/收货人/提单日……）
• 同一逻辑字段在同一份单证里出现两个不同值 → 阻断（最常见也最致命：两页纸自己跟自己打架）
• 金额 / 毛重 / 净重 / 体积 / 件数为零或为负
• 净重大于毛重；净重占毛重低于 50% 时给警告（多半是毛重漏填了整柜或整托）
• 币种符号与 ISO 代码混用；多种符号 / 多种币种代码并列（RMB 与 CNY 会先归一再比，否则比不出来）
• 占位符残留（TODO TBD FIXME XXX 待补充 待定 ***）——否定语境自动降级
• 残留的 ** 加粗标记（排版没改完）
• UTF-8 BOM 残留
• 跨单证日期逻辑：开票日晚于装运日（警告）；装运日晚于最迟装运期（阻断）

跨单证

• 发票号、合同号、币种、件数、毛重、净重、体积、起运港、目的港、收货人、柜号、HS 编码、付款方式、贸易术语 —— 同一字段值不一致

分级规则（这一条是有讲究的）：

齐套性

• --require 指定的单证类型是否齐备
• 单证类型识别不出来的，会在报告里单列，提示用 --field-map 补别名

触发与不触发

会触发

• 「这批出口单据帮我查一下」「发票和提单对不上」
• 「报关资料体检」「交单前自检」「单证齐套性」
• 「装箱单和提单件数不一样」
• 「产地证 HS 编码和发票写的不一样」
• 「单据有没有漏填字段」

不会触发

边界原则：认不出的字段就报「未识别」，绝不猜。 猜错一次比漏报一次危险得多——
它会让使用者以为已经检查过了。

常见错误与应对

支持的日期写法

日期先归一化成 YYYY-MM-DD 再参与跨单证比对。认不出来的写法一律不参与比对——
按字符串比大小会把 9 月比成晚于 10 月，凭空造一条假告警，比判不出来更糟。

异常与兜底

自检：python scripts/doc_audit.py --selftest —— 80 项断言，覆盖编码兜底顺序、键名归一、别名映射不乱抢、
否定式上下文、数值合理性、跨单证分级、章节编号连续性、错误路径退出码封闭。

实战案例

案例一：五份单证，找出 2 个真问题

需求：客户说「系统里 HS 编码过不了」，但五份单证都在手上，不知道问题在哪。

选型：全量目录扫描 + --require 齐套校验。

数据：示例单证五份（发票、装箱单、提单、产地证、保单），埋在同一个目录。

命令：

python scripts/doc_audit.py --path ./单证 --out ./out --require invoice,packing_list,bill_of_lading,origin_certificate,insurance

实际产出（已跑通，真实输出）：

单证 5 份，问题：阻断 2 / 警告 2 / 提示 0；跳过 0 份

关键点：客户报的「HS 编码过不了」是跨单证问题，任何单份单证单独看都没错——
所以只审一份单据的工具在这里必然失手。

案例二：字段叫法不一样，不改脚本怎么接入

需求：车间的出厂单一律写「箱数」「总箱量」，没有一份写 No. of Packages。

错误做法：改脚本别名表。结果脚本一升级就丢，别的项目也跟着受影响。

正确做法：外部映射。

{"no_of_packages": ["箱数", "总箱量", "装箱数量"]}

python scripts/doc_audit.py --path ./单证 --out ./out --field-map my_fields.json

--field-map 的键会合并进内置别名表（用户叫法优先），不是替换。
这样脚本保持零修改、可复用，配置随单据走。

已验证清单

以下都是本机实跑结果，不是设计意图：

• --selftest 80/80 通过（2026-10-05 由 67 增至 80）
• 中文日期 2026年9月1日 归一为 2026-09-01；带空格的 2026 年 12 月 31 日 同样可解析
• 点分日期 2026.09.01 可解析；版本串 v1.2.3 不会被误读成日期
• 不存在的日期 2027-02-30 / 2027-02-29 判为读不出来；闰日 2028-02-29 按真实日历可用
• 开票 9-01 / 装运 10-01（中文写法）不再误报「日期逻辑倒挂」（v1.0.1 修）
• 开票 10-01 / 装运 9-01（中文写法）仍能正确报出倒挂——修的是假告警，不是把检查关掉
• 任一边日期没归一化时不参与比对，不造假告警
• 错误路径 11 条退出码全部正确（无参数 / 缺 out / demo 与 path 互斥 / 路径不存在 / require 未知类型 / require 路径注入 / field-map 不存在 / field-map 结构错 / 单文件 / template / help）
• --fail-on-block 在有阻断时返回 2
• --demo 跑出 5 份示例单证，稳定产出 2 阻断 + 2 警告
• 报告章节编号连续无断档（无跳过文件时不会出现缺「五」）
• 跨单证提示里文件名正确渲染（曾因键值用反渲染成空括号，已修）
• 币种 RMB 与 CNY 归一后可识别为同一币种
• contract 文件名不会被短词 co 误判成产地证（短词走词边界匹配）
• 否定语境中的 XXX 不误报为占位符残留；否定词超出 10 字窗口则照报
• 编码兜底 utf-8-sig 排第一（否则带 BOM 的文件会把 U+FEFF 留在串首，后续键名匹配全部偏移）
• 单份单证内同名字段矛盾、数值为零、净重>毛重均能检出