text-to-cad 实战指南Bambu Lab 真实打印机实机启动前的 Real Printer Checklist 全解析【免费下载链接】text-to-cadA library of agent skills for CAD, CAE and CAM项目地址: https://gitcode.com/GitHub_Trending/tex/text-to-cad导读在 text-to-cad 开源项目中bambu-labs技能见 skills/bambu-labs/SKILL.md负责把已经生成并验证过的 plain.gcode文件通过 Bambu 局域网 FTPS/MQTT 交接handoff到真实的 Bambu Lab 打印机。其中 skills/bambu-labs/references/real-printer-checklist.md 是任何一次--execute实机运行之前的强制检查清单它把「凭据与网络」「任务与交接模式」「物理打印机状态」「首次实机启动序列」「失败恢复」五类检查固化为一套可复盘的流程。读完本文你将掌握如何在触发真实打印动作前完成系统性的安全校验、如何按 6 步序列从 dry-run 稳妥推进到首层观察以及如何依据源码级证据排查print_error/HMS 等实机故障。适用前提本清单面向「本地局域网内的物理 Bambu Lab 打印机」它不负责切片只处理已存在且已通过$gcode技能验证的 plain.gcode文件。Bambu 未向本项目提供稳定的公开本地打印 API 契约相关 FTPS/MQTT 行为均为实测观察结果见 skills/bambu-labs/references/local-lan-protocol.md。一、检查清单的定位实机命令的唯一闸门在 skills/bambu-labs/scripts/bambu_lan_print.py 的 CLI 设计中所有网络动作都遵循「dry-run 优先」原则--execute是执行真实网络动作的开关--confirm-start-print是启动打印的二次确认。从源码可以清晰看到这套闸门机制send_main中--execute与--action plan组合会直接报错--execute has no effect with --action planbambu_lan_print.py#L1468-L1469对start/upload-start动作--execute必须搭配--confirm-start-print否则抛出Starting a print requires --confirm-start-printbambu_lan_print.py#L1470-L1471实机启动前还会强制校验 printer serial因为它决定 MQTT 请求主题device/{serial}/requestbambu_lan_print.py#L1472-L1473。real-printer-checklist.md 正是这道闸门的人工核对环节先由 Agent 对照清单逐项确认再执行携带--execute的命令。任何「跳过清单、直接--execute」的做法都不符合该技能的预期工作流。二、凭据与网络检查Credentials And Network在把任何字节发送到打印机之前必须先确认网络与凭据环境是可信、可达且配置正确的。清单要求核对以下内容IP/主机名在可信局域网内确认打印机 IP/hostname 位于受信任的本地网络。这与脚本的validate_local_host逻辑一致——源码在 bambu_lan_print.py#L329-L341 中会解析主机地址若解析结果落在私有/链路本地/回环范围之外默认直接拒绝执行除非显式传入--allow-nonprivate-host该参数出现在send、status、clear-error、pause/cancel等所有涉及网络的子命令中如 bambu_lan_print.py#L1736-L1740。LAN Only / Developer Mode当打印机提供这两个选项时必须开启尤其是A1 / A1 Mini。如果 Developer Mode 未开启本地启动常常失败或打印机进入只读状态修改后应断电重启power-cycle再继续。访问码access code写入本地配置使用config set将访问码保存在工作区根目录的bambu-printers.json中不要在任何最终回复消息里打印访问码。源码中sanitized_printer_entry会在展示配置时剔除access_code字段bambu_lan_print.py#L182-L183config show子命令同样不打印访问码bambu_lan_print.py#L1568-L1570。该配置文件属于本地配置应被 Git 忽略。serial 的获取与缓存通过serial子命令或config set --fetch-serial从打印机 TLS 证书中抓取并缓存序列号默认不要求用户提供。状态联通性验证运行status --push-all确认目标打印机确实响应。--push-all会在订阅 report 主题后发布pushing.pushall请求全量状态见 skills/bambu-labs/references/local-lan-protocol.md。LAN 设置变更后的恢复如果此前 LAN 设置修改导致启动失败应先清除过期错误clear-error并断电重启打印机后再重试不要带着脏状态反复触发启动。对应的status命令实测示例来自 skills/bambu-labs/SKILL.mdpython skills/bambu-labs/scripts/bambu_lan_print.py status \ --printer a1-mini \ --push-all \ --wait-seconds 10status子命令还支持--max-messages默认收集 1 条 report 后返回、--timeout默认 20 秒、--mqtt-port默认 8883等参数bambu_lan_print.py#L1591-L1615。首次配置打印机时可参照 skills/bambu-labs/references/new-printer-onboarding.md 中的分机型触屏步骤A1/A1 Mini、P1P/P1S、X1/X1C/X1E、H2D 各家族获取 IP 与 LAN 访问码并用以下命令写入配置python skills/bambu-labs/scripts/bambu_lan_print.py config set \ --printer a1-mini \ --host 192.168.1.34 \ --access-code 12345678 \ --model a1-mini \ --fetch-serial手动编辑的配置 JSON 形状如下bambu-printers.json位于工作区根目录{ printers: { a1-mini: { host: 192.168.1.34, access_code: 12345678, model: a1-mini } } }三、任务与交接模式检查Job清单要求在实际发送前确认「这份任务文件本身」是否正确G-code 来源可靠确认$gcode技能已经生成并验证过 plain.gcode本技能不做切片切片由 OrcaSlicer 等完成。打印参数正确确认比例scale、方向orientation、支撑supports、材料 profile、喷嘴nozzle与底板类型bed type与目标打印机匹配。交接模式与任务匹配三种--handoff模式各有严格适用范围详见 skills/bambu-labs/SKILL.md 与 skills/bambu-labs/references/local-lan-protocol.md交接模式上传目标MQTT 命令适用场景template-projectFTPS 根目录print.project_fileurl: ftp:///name.gcode.3mfA1 Mini 本地 LAN 实测验证过的首选路径以已知可用的同机型.gcode.3mf模板为基底替换Metadata/plate_N.gcode并更新对应 MD5plaincache/name.gcodeprint.gcode_file仅限诊断场景或gcode_file已被验证可用的打印机/固件在实测 A1 Mini 上plain G-code 虽能上传成功但gcode_file启动失败或被忽略bambox-projectFTPS 根目录print.project_file仅当脚本启用了确切打印机/喷嘴 profile 时目前仅启用p1s-0.4支持 PLA、ASA、PETG-CFa1-mini-0.4、a1-0.4、x1c-0.4、p1p-0.4因缺乏已验证 profile 而保持禁用见源码 bambu_lan_print.py#L84-L125项目类交接必须走 FTPS 根目录上传到根目录并使用ftp:///name.gcode.3mf形式的 URL不要把项目文件放进cache/也不要使用file:///sdcard/cache/...或本地 HTTP URL 形式——这些形式在实测中会出现「看似被接受但实际不启动」的问题。A1 Mini 模板项目交接的推荐命令dry-run 先行bambu_lan_print.py#L1702-L1756 定义了完整参数python skills/bambu-labs/scripts/bambu_lan_print.py send \ --printer a1-mini \ --gcode /tmp/job.gcode \ --handoff template-project \ --template-project /path/to/same-printer-template.gcode.3mf \ --action upload-start四、物理打印机检查Physical Printer这是清单中最「非技术」却最关键的一环。只有当用户当前请求明确要求打印或启动任务时该请求才被视为本次实机启动的授权Agent 需要在实机命令之前口头陈述这些物理检查项并在自动化校验与打印机状态健康的前提下继续推进。只有当请求意图含糊、或某项校验/状态检查引起担忧时才需要再向用户索取一次确认。逐项核对底板build plate已安装、干净无遮挡且与所用材料适配打印机内无上次失败打印的残留物、散落的工具、胶带碎屑或其他杂物耗材filament已装载且与切片文件匹配操作员在附近可观察加热heat-up、回零homing与首层first layer有摄像头或可直接目视观察的手段。这套物理检查与 skills/bambu-labs/SKILL.md 中「Safety Rules」的要求一致实机启动前必须陈述——底板干净、底板/耗材/喷嘴正确、周围环境安全、操作员就近并且「发布 MQTT 只是发起一个开始请求」最终必须以打印机状态/UI 与实际观察来确认被接受。五、首次实机启动序列First Live Sequence清单给出了严格的 6 步递进序列每一步都比上一步更「接近真实打印」任何一步失败都应停下排查而不是继续运行精确的send命令不带--execute并检查计划plan此时输出的是 JSON 计划包括 FTPS 远程路径、MQTT 主题与载荷、dry_run: true等字段用于人工确认将要发生什么。先运行send --action upload --execute只上传、不启动。对项目类交接这一步还会触发模板打包或 bambox 打包逻辑见 bambu_lan_print.py#L1487-L1500template-project在临时目录中复制模板并替换Metadata/plate_N.gcodebambox-project则调用 bambox pack/validate。如有可能检查打印机状态/UI/存储确认文件确实到达了打印机端FTPS 根目录或cache/。重新运行 dry-run 的send --action upload-start计划在真实启动前再看一遍最终载荷。当用户明确要求打印/启动或意图不明时经确认后运行send --action upload-start --execute --confirm-start-print这一步才真正向device/{serial}/request发布启动请求。轮询状态并目视观察打印机直到首层明显正常。执行版命令skills/bambu-labs/SKILL.mdpython skills/bambu-labs/scripts/bambu_lan_print.py send \ --printer a1-mini \ --gcode /tmp/job.gcode \ --handoff template-project \ --template-project /path/to/same-printer-template.gcode.3mf \ --action upload-start \ --execute \ --confirm-start-print从源码角度看execute_sendbambu_lan_print.py#L1503-L1526在执行后会输出executed列表upload、publish_start_request并附带执行注记「MQTT start was published as a request; this helper does not confirm printer acceptance or print progress.」——这再次印证第 4 步与第 6 步的必要性发布启动请求 ≠ 打印已开始必须靠status轮询与物理观察来闭环。六、启动失败的恢复print_error 与 HMS如果状态返回print_error或 HMSHealth Management System错误立即停止不要继续循环重试。正确顺序是停下并定位根因物理问题、存储问题、Developer Mode 未开、交接载荷错误等修复根因后可选执行clear-error --execute清除打印机端错误再次轮询状态确认gcode_state/HMS 恢复正常后再重试。clear-error子命令从源码看是发布print.clean_print_error消息它不会启动任何运动见 skills/bambu-labs/references/local-lan-protocol.md。命令形态python skills/bambu-labs/scripts/bambu_lan_print.py clear-error \ --printer a1-mini \ --execute清空过期错误后如果此前修改过 LAN Only/Developer Mode务必断电重启打印机再重试——状态可能残留过期的FAILED/HMS 值skills/bambu-labs/references/local-lan-protocol.md 的 Observed Failure Modes 明确记录了这一现象。七、调试期间的诊断手段清单与配套文档共同建议在排查「打印机是否收到并接受请求」时使用以下增强参数组合python skills/bambu-labs/scripts/bambu_lan_print.py send \ --printer a1-mini \ --gcode /tmp/job.gcode \ --handoff template-project \ --template-project /path/to/same-printer-template.gcode.3mf \ --action upload-start \ --execute \ --confirm-start-print \ --mqtt-qos 1 \ --wait-after-publish 10--mqtt-qos 1将 MQTT 发布 QoS 从默认 0 提升为 1确保请求被交付源码定义见 bambu_lan_print.py#L1743-L1749--wait-after-publish 10发布后保持连接 10 秒并捕获 report 消息用于观察打印机立即回传的状态bambu_lan_print.py#L1750-L1755。serial 获取命令从打印机 TLS 证书读取序列号用于 MQTT 主题device/{serial}/requestpython skills/bambu-labs/scripts/bambu_lan_print.py serial \ --printer a1-mini \ --json八、运行中的打印控制pause 与 cancel对正在运行的打印应使用专用的打印控制命令而不是临时拼写 MQTT 片段。这些命令只发布控制请求不上传文件、不启动新任务执行后需读取状态确认打印机状态确实发生变化见 bambu_lan_print.py#L1443-L1463。暂停先 dry-run 看载荷再执行python skills/bambu-labs/scripts/bambu_lan_print.py pause \ --printer a1-mini python skills/bambu-labs/scripts/bambu_lan_print.py pause \ --printer a1-mini \ --execute \ --mqtt-qos 1 \ --wait-after-publish 10取消Bambu LAN 实际发送的命令是stop执行取消必须带--confirm-cancel-print仅当用户明确要求停止打印、或意图不明时经确认后执行python skills/bambu-labs/scripts/bambu_lan_print.py cancel \ --printer a1-mini python skills/bambu-labs/scripts/bambu_lan_print.py cancel \ --printer a1-mini \ --execute \ --confirm-cancel-print \ --mqtt-qos 1 \ --wait-after-publish 10源码中print_control_main对cancel的--execute强制要求--confirm-cancel-printbambu_lan_print.py#L1445-L1446与send的--confirm-start-print形成对称的双重确认体系。九、常见失败模式速查把清单与协议文档skills/bambu-labs/references/local-lan-protocol.md中的实测失败模式整理为速查表现象判断处置gcode_file返回result: fail或打印机停在IDLEplain G-code 上传成功但固件拒绝/忽略直接本地启动改用template-project项目交接项目上传到cache/后启动失败print_error: 83935248/0500-C010项目文件放错了位置清错后把项目上传到 FTPS 根目录用ftp:///name.gcode.3mffile:///sdcard/cache/...或本地 HTTP URL 看似被接受但无动作该 URL 形式不被本工作流支持停止使用这些 URL 形式macOS 上 Bambu Studio / OrcaSlicer 工程导出崩溃GUI 后端AppKit/BambuStudio不稳定不要反复重试 GUI 导出用 OrcaSlicer 出 plain.gcode再用本技能交接开启 Developer Mode 后仍残留gcode_state: FAILED或 HMS打印机状态脏清除错误并断电重启后再试FTPS 登录成功但上传报553或提示缺cache/打印机存储/SD 卡异常先检查打印机存储状态再发 MQTT 启动MQTT 状态正常但启动不生效serial/访问码/Developer Mode/LAN Only/载荷任一环节不符逐一核对后再重试结语real-printer-checklist 的价值在于把「真实打印机」这一高风险动作拆解为可验证、可回滚、可监督的阶梯网络凭据 → 任务交接 → 物理检查 → 6 步启动序列 → 失败恢复。它与bambu_lan_print.py的 dry-run 优先设计、--confirm-start-print/--confirm-cancel-print双重确认、私有地址校验、MQTT 发布仅代表「请求」等机制相互印证。在新机型上首次实机使用前建议依次通读 skills/bambu-labs/references/new-printer-onboarding.md新机配置、skills/bambu-labs/references/local-lan-protocol.md协议细节与本清单skills/bambu-labs/references/real-printer-checklist.md再按照本文第五节序列谨慎推进。【免费下载链接】text-to-cadA library of agent skills for CAD, CAE and CAM项目地址: https://gitcode.com/GitHub_Trending/tex/text-to-cad创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考