集装箱装柜测算 · 一柜能装多少箱

定位与服务边界

这个 Skill 只回答一个问题：这批货用一个柜能装下多少、装到什么程度、还剩多少。

不报价，不排船期，不推荐箱东，不算运费。
它做的是：你已经有了每种货的外箱尺寸和件数，现在需要知道
「到底要不要加柜、这柜装得亏不亏、会不会超重」。

两件事必须说在前面，否则这份报告会被误用：

1. 摆放方案是可行解，不是数学最优解。
   真实三维装箱是 NP-hard。本报告给的是可核对的下限——
   按这个方案一定装得下这么多件；实际装柜师傅可能还能多塞，
   但不要拿它给客户承诺。
2. 箱型内尺寸与载重是 ISO 常见参考值，各箱东、各年份略有差异。
   报告里会原样打印出来，也允许 --spec / --max-payload 覆盖。
   本工具不会把它说成权威数据。

三分钟上手

第一步：先确认脚本本身是好的

python scripts/container_load.py --selftest

实测输出 selftest 43/43 通过，退出码 0。
它同时验证换算常数、别名匹配、装柜算法、超重判定、报告章节编号、退出码封闭。

第二步：跑内置 demo，看清报告长什么样

python scripts/container_load.py --demo --container 40HQ --out ./out

会在 ./out 下造 2 种示例货（120 件主机箱 + 300 件配件箱）并出报告。

第三步：跑自己的货

一货一个文件，放进同一个目录：

Name: 主机箱
Length: 60
Width: 40
Height: 40
Dim Unit: cm
Unit Weight: 18
Weight Unit: kg
Pcs: 120

python scripts/container_load.py --path ./货 --container 40HQ --out ./out

支持 .txt / .md / .markdown / .csv / .json / .ini / .properties；
中文键名与中文单位同样认，实测 品名 / 长 / 宽 / 高 / 尺寸单位: 厘米 / 单件重量 / 重量单位: 公斤 / 件数 可正常解析且 0 阻断。

字段名不要求统一写法，下面这些都能认：

数字后面带单位也能剥掉（18kg、60cm 都认）；千分位逗号会去掉。

别名字段按三级匹配：原名精确 → 归一化精确 → 子串（且要求别名归一化后不少于 4 字）。
第三级设长度门槛是必要的——单字别名会去抢别的键
（「单件重量」里的「重」会把它认成重量单位字段）。

箱型

--container 必填，不给就报错退出（不替你猜柜型）。可选：

• --spec 1203,234,269：用自己的内尺寸覆盖（三个正数，单位 cm）
• --max-payload 21000：用自己的限重覆盖（kg）

输出契约

每次运行产出两份同前缀文件，写到 --out 指定的目录：

• 集装箱装柜测算报告-<YYYYmmdd-HHMMSS>.md——给人看
• 集装箱装柜测算报告-<YYYYmmdd-HHMMSS>.json——给程序消费

md 报告章节（编号连续，条件章节自动顺延）

摆放方案里末层不满会标出来（如 20×5×2 配 120（末层 20 件）），
因为只放 120 件时占的是 200 件的两层，不标就会看起来像算错。

JSON 产物字段（给程序消费，逐字段固定）

顶层：generated_at / input / container / inner_cm / payload_kg / counts / aggregate / rows / issues

• counts：block warn info skus skipped
• aggregate：box_vol used_vol vol_rate total_kg wt_rate pcs_total pcs_placed
  —— total_kg 在任一货没填重量时为 null，不会假装算出来
• rows[]：rel name pcs placed left dims(cm 三元组) vol(cm³)
• issues[]：固定 6 键 scope level cat line snippet fix；
  level 取值封闭为 阻断 / 警告 / 提示

issues 一律是 6 元组、级别取值封闭，已由自检结构不变式断言兜住——
数据结构不统一时下游解包不报错、只静默取错值，比崩溃更难查。

检查项清单

一、阻断级（算不出来或装了要出事）

缺项绝不静默成 0：自检有专门断言 缺项不静默成 0。

二、警告级（装得下，但有剩余）

三、提示级（省钱线索）

触发与不触发

会触发

• 「一柜能装多少箱」「这批货 40HQ 装不装得下」
• 「装柜怎么排」「装箱方案怎么出」
• 「装载率多少」「柜子还剩多少空间」
• 「要不要加柜」「超重了怎么办」
• 「20GP 和 40HQ 差多少」

不会触发（非触发边界）

• 「哪家货代便宜」「这一柜运费多少」——本工具不算运费、不比价，属报价比价类工具
• 「报关单证齐不齐」「发票箱单怎么开」——属出口单证体检
• 「关税多少、到岸成本多少」——属到岸成本测算
• 「选哪个国家出海」——属出海准备度诊断
• 「订舱、拖车、报关执行」——属执行动作，不是计算问题

扫描范围与漏检边界

会读的

• 指定目录下所有 .txt / .md / .markdown / .csv / .json / .ini / .properties
  文本文件（子目录递归，跳过 __pycache__ / .git / node_modules 等）
• 也接受 --path 直接指向单个文件
• 编码按 utf-8-sig → utf-8 → gbk → utf-16 依次尝试，最后才 errors=replace

不读的（会计入「跳过」并列出，绝不静默吞掉）

• 其他扩展名的文件（如 .xlsx、图片、PDF）
• 空文件
• 解析不出任何字段的文件
• 多行数据行的 .csv（要求一货一文件）

判不了的（本工具明确不做，也不是缺陷）

• 不报价、不排船期、不推荐箱东、不算运费——只算装得下多少
• 箱型内尺寸与载重是 ISO 常见参考值，各箱东略有差异
• 摆放方案是可行解不是最优解；真实装载还受堆叠限制、重不压轻、
  托盘/缠膜、货物能否侧放（如向上箭头标识）影响，本工具一律不考虑
• 单件重量不填就不做超重判定，不会假装算出来
• 车轴限重、目的港限重通常比箱型载重更紧，需另行确认
• 不支持非长方体货物（桶装、异形件、裸装设备）

本报告 0 问题 ≠ 这柜一定能装，只代表上面的检查项没命中。

常见错误与应对

异常与兜底

退出码封闭为 0 / 2 / 3：0 成功、2 数据或参数问题、3 输出不可写。
main() 顶层显式捕获异常并转为退出码 2，不会把 traceback 抛给调用方；
SystemExit 单独放行，不会被 except Exception 吞掉。

所有参数校验前置到分支之前——--demo 走的是同一套装柜逻辑，
不会因为它带内置示例数据就绕过 --container 校验。

实战案例（真实跑通，数字为脚本实跑输出）

案例一：内置 demo，40HQ 装两种货

命令：python scripts/container_load.py --demo --container 40HQ --out ./out

结果：货物 2 种（跳过 0），问题：阻断 0 / 警告 0 / 提示 1

摆放方案：

手算复核：1203÷60 = 20（余 3 cm），234÷40 = 5（余 34 cm），269÷40 = 6 层；
每种货只放 2 层即够 → 20×5×1 + 20 件 = 120 ✓。
占用体积 120×0.096 + 300×0.036 = 11.52 + 10.80 = 22.32 CBM，
柜容 1203×234×269 = 75.72 CBM → 29.5% ✓。
总重 120×18 + 300×6 = 3960 kg，对常见载重 26500 kg → 14.9% ✓。

装载率只有 29.5%，所以报了一条「体积装载率偏低」——
这正是本工具最有用的地方：告诉你这一柜明显装亏了，该改小箱型或拼柜。

案例二：单 SKU 装满 40HQ

输入一种货 60×40×40 cm、单件 18 kg、件数 100000：

• 柜内放得下 600 件（1203÷60=20，234÷40=5，269÷40=6，20×5×6=600）
• 未装下 99400 件 → 报「装不下，有余数」
• 体积装载率 76.1%（600×0.096 = 57.6 CBM ÷ 75.72 CBM）
• 货物总重 600×18 = 10800 kg，载重利用率 40.8%

若把单件重量改成 100 kg，同样 600 件总重 60000 kg > 26500 kg
→ 报阻断「超过箱型常见载重」，--fail-on-block 时退出码 2。

已验证清单（全部 2026-10-05 实跑，未跑的不写）

• python scripts/container_load.py --selftest → 43/43 通过，退出码 0
• 内置 demo（40HQ，2 种货）→ 阻断 0 / 警告 0 / 提示 1；要装 420 装下 420，装载率 29.5%
• 单 SKU 60×40×40 cm 装 40HQ → 600 件，与手算 20×5×6 一致
• 只放 10 件（少于整层 100 件）→ 实装 10 件，不多装（有专门断言防止按整层占满）
• 英寸与厘米输入结果一致（23.622 in ≈ 60 cm，装柜数量差 ≤ 6 件）
• 超重（60000 kg > 26500 kg）→ 判阻断，报告给出总重
• 缺高 → 判阻断，且不输出任何 0.00 假装算出来的值
• 给重量不给单位 → 判阻断，不默认按公斤算
• 尺寸单位混用（cm + in）→ 判阻断
• 中文键名 + 中文单位（厘米 / 公斤）→ 正常解析，0 阻断
• 二进制-only 目录 → 不崩溃，退出码 2
• 空目录 → 退出码 2
• --out 指向已存在文件 → 退出码 3
• 缺 --out / 缺 --container / 未知箱型 / --spec 维度不对 / --max-payload 为 0 或非数字 → 退出码 2
• 换 --spec 结果必须变化 → 已断言，确认参数真被消费
• 有阻断加 --fail-on-block → 退出码 2；无阻断 → 退出码 0
• 报告章节编号连续、产物无 %% 转义残留 → 已断言