前言¶
在 DeepSeek Harness（DSH）里做外贸或物流相关的 Agent，常见需求是：这票货要几个柜、运费怎么估、多单能不能拼在一起省柜。若把体积粗算和真实排柜混用，网页算一套、会话里 Agent 算另一套，结论会对不上。boxfill 把装柜、运费、拼单等逻辑收在同一套引擎里，并通过 DSH 插件把其中一部分能力直接暴露给会话内的 Agent；H5 网页端与 MCP 服务端共用 h5/js/core/ 下的实现，DSH 插件同样跑这份代码，三端在相同输入下应对齐。
下面介绍插件定位、能调哪些工具、如何安装，以及和完整 MCP 服务的分工。
这是什么¶
boxfill（装柜数量计算器）由维护者 01men 开源，许可证 MIT。项目一句话定位是：集装箱装载方案测算，并附带 MCP 服务——算清楚要几个柜、运费多少、怎么拼单更省。社区目录分类为「客户端」，目录页见 skillhub.cn/plugins/01men/boxfill，源码在 github.com/01men/boxfill。
仓库 README 标明：H5 给人用，MCP Server 给 Agent 用；同一套装箱算法、两个入口。DSH 通过仓库内声明的 dsh.bundle（cordis.patch.yml）作为插件安装，会话里可用的是带 boxfill_ 前缀的一组工具，底层与网页、MCP 服务端一致。线上体验地址为 boxfill.ybkkasi.com，工具页在 boxfill.ybkkasi.com/app.html。
核心功能¶
装柜与约束¶
装箱引擎采用分层码放加矩形块，面向「从柜门往里码、一层铺满再往上堆」的真实操作，而非通用 3D Bin Packing。README 列出多起点策略（体积优先、重量优先、整除优先、混装亲和等）及门框、限重、配重等硬约束；限重取箱型、航线、船司、拖车四层最小值并在方案中留痕。
主入口工具 plan_containers（MCP）在 DSH 中对应 boxfill_plan_containers，返回柜型、柜数、每柜 SKU 分布、体积与重量利用率、甩单（spill）、违规（violations）等。单位约定为 cm / kg / CBM，与 H5 一致，不要自行换成 mm。
运费、拼单与校验¶
calc_freight→boxfill_calc_freight：四个重量、渠道比价、箱型比选、附加费等。suggest_consolidation→boxfill_suggest_consolidation：拼单建议与费用分摊。check_fits→boxfill_check_fits：箱规能否装进指定柜型、门框与超长等。list_containers→boxfill_list_containers：柜型库、内尺寸、限重等。
订单与箱规查询¶
list_orders→boxfill_list_ordersget_order_boxes→boxfill_get_order_boxes：订单展开为箱规清单，汇总体积与抛比。
完整 MCP 服务还提供 gen_docs（单据）、upsert_sku / import_pi（建档与 PI/CSV 导入）、list_skus、analyze_photo（实验性识图）等共 12 个工具；仓库测试为 299 条通过。DSH 插件只开放纯计算与查询的 7 个工具，不开放建档类：upsert_sku、import_pi 会写库，README 说明主数据应通过 MCP 服务端持久化，而不是在单次 DSH 会话里写入内存库后丢失。
安装与启用¶
DSH 生态理念是「一切皆插件」；skillhub.cn 上的插件目录是社区站点，与 DeepSeek / 幻方无官方从属关系。安装前建议浏览仓库源码与 MIT 许可证：插件以当前 DSH 进程权限运行，只安装你信任的来源。
官方安装命令（来自仓库 README「装进 DeepSeek Harness」一节）：
dsh plugin add github:01men/boxfill
若需本地跑完整 MCP 或 H5，README 要求 Node.js ≥ 22.5（使用 node:sqlite），在克隆后的仓库内：
npm install
npm test
npm start
npm start 后本地工具页为 http://localhost:5173/h5/app.html。MCP stdio 接入示例：
{"mcpServers":{"boxfill":{"command":"node","args":["<仓库绝对路径>/server/stdio.js"]}}}
装好后可用 npm run mcp:probe 自检 12 个 MCP 工具；远程或多端共享可用 npm run mcp:http（默认 127.0.0.1:8787/mcp）。
典型用法¶
在 DSH 会话中，可按 README 给出的 MCP 工作流程的查询与计算部分操作（建档与导入改走 MCP 服务端）：
- 先
boxfill_list_containers查柜型与限重。 - 再
boxfill_plan_containers排柜——柜数、利用率、甩单与违规以该结果为准。 - 需要运费时用
boxfill_calc_freight；合并订单用boxfill_suggest_consolidation。 - 已有订单数据时用
boxfill_list_orders、boxfill_get_order_boxes展开箱规。
plan_containers 类返回的结构在 README 中有实测 JSON 示例，包含 boxType、containers、strategy、totals、perContainer、spill、violations 等字段，便于 Agent 直接解析。
需要人类核对或演示时，可打开 H5「算 / 单 / 数」三屏流程（另有一屏实验性「测」）；拼单建议可一键跳回「算」做真实排布。Agent 侧与 H5 共用引擎，应避免在插件外再做一套体积估算替代 boxfill_plan_containers。
适用场景与注意¶
适合谁：在 DSH 里做装柜数量、利用率、运费粗算、拼单可行性、箱规是否可装等对话式测算的开发者；需要和 boxfill.ybkkasi.com/app.html 或自建 MCP 结论一致的场景。
注意：
- 尺寸或毛重缺失时，入口会拦截并提示补齐，不要猜测填入。
- 完整 MCP 里的
analyze_photo为实验能力，输出仅供人工核对，不宜作为结算依据；DSH 插件未暴露该工具。 - 主数据持久化、PI 导入、单据生成等，请使用仓库 MCP 服务端或 H5「数」屏，而非仅依赖 DSH 插件的 7 个工具。
- H5 为 ES 模块，不能用
file://直接打开；需npm start或静态服务器。
结尾¶
boxfill 把装柜测算收进同一套 h5/js/core/ 引擎，DSH 插件通过 dsh plugin add github:01men/boxfill 接入后，会话内 Agent 可调用 7 个 boxfill_* 工具完成排柜、运费、拼单与查询，并与网页端、MCP 服务端在相同约定下保持一致。更多说明与 12 个 MCP 工具表见 GitHub README，目录页见 skillhub.cn/plugins/01men/boxfill。
