前言¶
在 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。
