snapmaker-2

这是一款专为 Snapmaker 2.0 3D 打印机设计的本地网络控制工具，基于官方 HTTP API 构建，提供从设备发现到打印完成的全流程管理能力。

核心用法方面，该技能支持通过 UDP 广播或 HTTP 探测自动发现局域网内的打印机设备，用户只需配置 IP 地址和 API Token 即可建立连接。功能涵盖实时状态监控（温度、进度、坐标位置）、完整的打印作业生命周期管理（发送 G-code 文件、启动、暂停、恢复、停止）以及持续性的进度追踪。所有操作均通过 Python 脚本封装，支持 JSON 格式输出，便于与其他自动化工具集成。

显著优点体现在其完善的安全设计上。首先，具备活跃打印保护机制，防止在打印过程中误操作发送新文件；其次，所有破坏性操作（如停止打印）都强制要求用户确认，并提供 --yes 和 --force 标志供脚本化场景使用；再者，文件传输支持严格的扩展名白名单（.gcode、.nc 等）和目录沙箱限制，有效防止路径遍历攻击。此外，实时监控功能可以检测打印完成、断料、舱门开启等事件，适合无人值守场景。

潜在缺点主要包括来源可信度限制（T3 级个人社区项目），虽然代码质量达到 A 级，但长期维护稳定性存在不确定性。功能上仅限局域网使用（LAN-only），无法跨网络远程控制，且依赖的 requests 库版本未锁定，可能因依赖更新引入兼容性问题。另外，API Token 以 URL 查询参数形式传输，虽受设备限制但存在潜在泄露风险。

适合的目标群体主要是拥有 Snapmaker 2.0 打印机的个人爱好者、小型工作室以及教育机构的 3D 打印实验室。特别适合需要自动化打印流程、批量监控多台设备或将打印任务集成到现有工作流中的技术型用户。

使用风险方面，除常规的网络连接稳定性问题外，需特别注意 Token 的安全保管，避免配置文件泄露导致打印机被未授权控制。由于技能具备直接控制物理设备的能力，误操作可能导致正在进行的打印任务失败、材料浪费甚至设备损坏，建议在正式使用前充分测试命令行为。此外，该技能仅支持 Snapmaker 2.0 系列，不兼容其他品牌或型号的 3D 打印机。

核心用法

Snapmaker-2 是一个面向 Snapmaker 2.0 系列 3D 打印机的本地控制 Skill，通过 HTTP API 实现与打印机的双向通信。用户需先在 ~/clawd/snapmaker/config.json 中配置打印机 IP、端口（默认 8080）及从 Luban 应用获取的认证 Token。

主要功能模块：

• 状态监控：实时获取喷嘴/热床温度、打印进度（0.0-1.0）、当前 G-code 行号、剩余时间、XYZ 坐标位置、耗材耗尽及舱门状态
• 任务管理：发送文件（.gcode/.nc/.cnc/.stl 等白名单格式）、启动/暂停/恢复/停止打印任务
• 设备发现：UDP 广播自动发现局域网内打印机（端口 20054），支持跨子网指定 IP 探测
• 事件监听：通过轮询检测打印完成、耗材断料、舱门打开等状态变化

典型工作流：discover 发现设备 → send 上传文件 → watch 实时监控 → 任务结束自动通知。

显著优点

1. 安全设计周到：强制确认机制（--yes 绕开）、活动打印保护（禁止冲突操作）、状态校验前置，有效防止误操作损坏正在进行中的打印任务
2. 输入严格受限：文件扩展名白名单 + 路径沙箱（仅限工作区和 /tmp），杜绝路径遍历攻击
3. 零依赖风险：仅依赖 requests 库，无 CVE 漏洞历史，无恶意供应链包
4. 隐私零侵入：不收集用户敏感数据，Token 由用户主动配置，符合 GDPR/CCPA
5. 硬件原生适配：完整封装官方 API v1，支持所有 Snapmaker 2.0 机型（A250/A350 等）

潜在局限

• HTTP 明文通信：打印机固件不支持 HTTPS，Token 通过 URL 参数传递，存在局域网嗅探风险（需依赖网络隔离防护）
• T3 来源可信度：个人开发者维护（odrobnik），虽代码质量优秀但存在账号被盗、供应链攻击的理论风险
• 无云端能力：纯局域网方案，不支持远程监控（需配合 VPN/SSH 隧道）
• 轮询式监控：watch 命令固定 5 秒间隔，非 WebSocket 实时推送，高频率监控可能增加网络负载

适合人群

• 拥有 Snapmaker 2.0 打印机、希望自动化打印工作流的个人创客与小型工作室
• 需要将打印状态集成到本地监控系统（Home Assistant、Prometheus 等）的技术用户
• 注重数据隐私、拒绝云服务的「离线优先」3D 打印爱好者
• 具备基础网络知识、能配置静态 IP/VLAN 隔离的安全意识用户

常规风险

| 风险类型 | 说明 | 缓解措施 |

|---------|------|---------|

| 局域网中间人攻击 | HTTP 明文传输 Token 与 G-code | 部署独立网段/VLAN，禁止打印机外联 |

| Token 泄露 | 配置文件明文存储 | 改用电环境变量/密钥管理服务，定期轮换 |

| 恶意 G-code 执行 | 白名单仅校验扩展名，不解析内容 | 建立人工审核流程，限制文件大小 |

| 供应链攻击 | T3 来源，更新可能引入恶意代码 | 锁定版本使用，审查变更历史后更新 |