woda-print-mcp

本地打印 MCP + CLI —— 接收 agent 转交的打印数据（take_waybill 返回的完整契约），经平台打印组件（localhost WebSocket）在本机出纸。

• 形态：Node ESM，两种调用入口共用同一套核心逻辑（src/）：
  • stdio MCP server（bin/woda-print-mcp.mjs）—— 被 WorkBuddy 等支持 MCP 的 Agent 拉起
  • one-shot CLI（bin/woda-print.mjs，命令名 woda-print）—— 供不连 MCP 的 Agent（如 woda-cli 技能流程）以命令方式触发打印
• 依赖：Node ≥ 21（用原生 WebSocket，无 ws 依赖）、@modelcontextprotocol/sdk
• 支持平台：快手（ws://localhost:16888/ks/printer）、小红书新版（ws://localhost:10818，printPlugin=xhsnew）

CLI 形态（woda-print）

npm install -g woda-print-mcp

woda-print list_printers [--platform kuaishou|xhsnew]
woda-print print_documents --file <take_waybill完整返回.json> [--printer 打印机名]
woda-print preview_waybill --file <take_waybill完整返回.json> [--printer 打印机名]

• stdout = JSON 数据，stderr = 日志；退出码 0 成功 / 1 失败（详情见 stdout JSON 的 error）
• 打印数据必须走 --file（take_waybill 返回整体落盘），禁止精简字段
• Agent 侧的完整打单技能（woda-print-guide）随 woda-cli npm 包发布，从那里复制到 Agent 的 skills 目录使用

环境要求

• 商家打单电脑上已安装并启动对应平台的打印组件：
  • 快手打印组件（监听 ws://localhost:16888/ks/printer）
  • 小红书新版打印组件（监听 ws://localhost:10818）
• 物理打印机已连接（组件里能看到打印机）

启动 / 配置（WorkBuddy）

mcp.json 增加一条 stdio 连接器（与 woda-edge-mcp 并列，不需要 key）：

{
  "mcpServers": {
    "woda-print-mcp": {
      "command": "node",
      "args": ["D:/GitPorjects/edge-ai/woda-print-mcp/server.js"],
      "disabled": false
    }
  }
}

WorkBuddy 启动时自动拉起本进程；商家无需手动开。

工具

| 工具 | 用途 | | --- | --- | | list_printers | 查询指定平台打印组件的打印机列表。platform: kuaishou(默认) / xhsnew | | print_documents | 打印快递单。payload = take_waybill 返回的完整契约（{ template, successTrades, standardTemplateUrls, tmsUrl, ... }）或 filePath = 本地保存该完整返回的 JSON 文件路径（推荐大数据用），printer 可选（缺省用模板绑定打印机）。按 payload.template.printPlugin 自动路由到对应平台组件 | | preview_waybill | 预览快递单（preview:true）。payload 或 filePath（同 print_documents）。快手返回 previewImage 图片数组；小红书新版可能返回 previewURL（PDF） |

payload 入参（已定义 schema）：工具定义里 payload 只声明最外层 4 个字段 template / successTrades / standardTemplateUrls / tmsUrl，每个字段 description 醒目标注必须从 take_waybill 完整返回原样透传、禁止精简/删字段/重编码加密数据（尤其 successTrades 里的 thermalExdata.printData（encryptedData）、trades[].orders、shippingInfo、buyerNick、tradeCount 等）。schema 用 .passthrough() 保留未知字段（绝不 strip），template/successTrades 是宽松 any（不误伤，靠运行时组装兜底），缺失关键字段返回清晰错误。

调用日志（排查用）

每次工具调用的完整入参 + 返回都会追加写入 logs/print-mcp.log（默认在项目根 logs/ 目录，可用 config.json 的 logDir 覆盖）。每条一行 JSON： {time, tool, args(含完整 payload), result}。

• 亮点：记录 agent 实际传给工具的 payload，排查"为什么面单缺项/自定义区没渲染"等 Agent 转手问题最有用——能直接看到 agent 传进来的 template.details / itemType / successTrades 长什么样。
• print_documents/preview_waybill 的返回里还带 diagnostics（含 template.pageDetails、每项 pageDetailItems 的 itemTypeType、customData.itemCount、tmsUrl 等），一眼定位数据是否被精简或类型被字符串化。
• 敏感长串（encryptedData/printData/signature/key 等）自动截断为前 120 字符 + [截断, len=N]，避免日志膨胀；日志只写文件，绝不写 stdout（stdio 协议通道）。

打印协议组装

快手（src/assemble.js → assembleKuaishouTask）

参照 edge-front 的 KuaishouCloud.groupPrintWayBillArray + hxTemplate.getPrintJson + Tds.getTemplateUrl 另写一套，与浏览器行为对齐：

• standardData = thermalExdata.printData 解析 + 发货人 altData/addData 覆盖 + 脱敏
• 标准模板 URL：按 expressCode 查 standardTemplateUrls，查不到保留 printData 自带 templateURL
• customData = 自定义区 getPrintJson（文本/二维码/条码；表格为简化版）
• customTemplateUrl = tmsUrl + '/ca?m=ksxd&tid=...&num=0&splitable=false&time=<unix秒>'
• document 带 ksOrderFlag

小红书新版（src/assemble.js → assembleXhsTask，src/xhsnew.js）

参照 edge-front 的 XhsCloudNew.groupPrintWayBillArray，与快手的差异：

• 标准模板 URL：按 template.memo 在 standardTemplateUrls 数组里查 standardTemplateUrl（/express/xiaohongshu?ver=2 返回的列表，data 是数组），查不到保留 printData.templateURL
• standardData.addData 恒为 {sender:{address:{city,detail,district,province,town}, name, mobile, phone}} 结构
• 自定义区 key 是 data（快手是 customData）
• customTemplateUrl = tmsUrl + '/ca?m=xhs&tid=...&noSplit=1&num=0&time=<unix秒>'
• document 无 ksOrderFlag；预览可能返回 PDF（previewURL）

本期范围：快递单、单页、快手 + 小红书新版。表格同款合并、自动翻页（含 xhs 底单拼接）后续按需补充。

验证

本机打印组件在线 + WorkBuddy 已连上连接器后，让 agent 走完整流程：list_printers → take_waybill(取号) → print_documents(payload=take_waybill 完整返回, printer?) → 组件出纸 → 返回 {success, printed, failed}（含 diagnostics 供排查）。每次调用的完整入参见 logs/print-mcp.log。

小红书新版的面单模板必须是新版电子面单（旧版模板组件会拒绝：旧版模板无法在新版小红书打印组件使用）。