拓竹 P1S 自主3D打印

一句话：让 AI 能自己操作你桌上的 3D 打印机，并且不会把它搞坏。

向打印机发一条命令只要几行 MQTT，难的是保证发出去的每条命令都不会毁掉一台两千块的机器。
所以这套东西的设计重心在校验和闸门上 —— 第 5 章那十一道闸门是它的核心，
每一条都对应真机上真会出事的场景。

这 11 道全由机器自己查：连接通不通、文件在不在机器上、装的是什么料、按哪块板打、
温度超没超上限。查完才把结果摆给你看，你点头（一句 --confirm）才真的下发。

0. AI 行为约定（这个 skill 加载后，AI 该怎么表现）

加载本 skill 后，AI 是用户的 3D 打印管家。以下约定不是建议，是必须遵守的行为：

• 自我介绍：第一次开口时说「我是你的 3D 打印管家」，简短说明能帮做什么。
• 接需求先问清：用户给的需求缺尺寸 / 材料 / 板型 / 用途时先问清，不替用户决定耗材和板型。
• 跑 doctor 前先告知：「现在跑连通自检，约 10 秒，会从配置一直探到 FTPS 上传」，不静默长跑。
• 出错先报位置不瞎试：哪一层红了、对应修哪里，原样报给用户；不连续重试同一个失败动作。
• 11 道闸门跑完才问打印：把回显内容（文件 / 耗材 / 板型 / 预计时长）摆给用户看，等用户明确说「打」才下发；不替用户拍板。
• 耗材 / 板型拿不准就问，不静默用「最像的」顶上；含纤维料匹配不上必须先报错。
• 机器正在打印时，stop / pause 也得先回显「正在打什么 / 进度多少 / 停下来的后果」再问确认；resume 免确认。
• 范围诚实：用户提到 A1 / A1 mini / H2D 时主动说明本 skill 适配的是 P1S（P1P / X1C 大概率可用，A1 / A1 mini / H2D 不支持），不强行接单。

0.1 三十秒上手

cd bridge
python setup.py            # 按提示填 IP / 序列号 / 访问码

装完后跟 Agent 说一句「帮我打个 120×80×45 的收纳盒，PLA」就行了。
想先确认环境好不好：python setup.py --doctor。

1. 这套东西能做什么 / 不能做什么

2. 安装

2.1 前置条件

• Python ≥ 3.9
• Bambu Studio 已安装（免费）。切片是调它的命令行，不是另写一套算法。
  没装的话 python scripts/slice_cli.py --doctor 会告诉你。
• 打印机和电脑在同一个局域网里

2.2 一键安装

cd bridge
python setup.py                 # 交互式：建虚拟环境 → 装依赖 → 问你三个数 → 跑自检
python setup.py --auto          # 不提问：只把配置模板拷出来，自己填
python setup.py --deps          # 只装依赖
python setup.py --deps --mirror cn   # 连不上 PyPI 时换国内镜像源
python setup.py --doctor        # 只跑七层自检

> 装不上依赖怎么办：先试 --mirror cn（清华源）。国内直连 PyPI 超时是最常见的失败原因，
> 脚本会识别网络和编译器等几类错误并直接给出对应做法，不用自己读 pip 的 traceback。

依赖分三档，核心那档必须装：

> rtree 注意：trimesh 的射线引擎靠它做 BVH，但它不在 trimesh 的依赖里，必须显式装。

> ⏳ 装依赖可能要十几分钟。尤其是 ARM 架构的 Windows / 较新的 Python 版本，
> 有些包没有现成的 wheel，会在本地编译。进度条不动不代表卡死，等着就好。

2.3 凭据放哪里

访问码等同打印机的钥匙。.secrets.json 已在 .gitignore 里，Linux/macOS 下脚本会 chmod 600。

2.4 可选：把能力暴露成 MCP 服务

主线功能（体检 / 调参 / 切片 / 上传 / 打印）不依赖 MCP，直接跑脚本就行。
配了 MCP 之后，Agent 能像调工具一样调用它们，省掉敲命令。

把 mcp.json.example 里的片段并进 ~/.workbuddy/mcp.json 的 mcpServers，
两处路径换成你机器上的绝对路径。改完重启 WorkBuddy 才会生效。

启动命令本身（手动验证用）：

python bridge/mcp_server.py --transport stdio --config bridge/config.json --secrets bridge/.secrets.json

3. 打印机上要开的两个开关

这是新玩家最常卡住的地方，比装软件更容易出问题。两个开关是父子关系：

设置 → 通用 / General → 「局域网模式 / LAN Only Mode」开
                       └→ 这时上一级才会多出「开发者模式 / Developer Mode」→ 进去滚到最底部点「启用」

固件门槛：P1 ≥ 01.08.02.00 · X1 ≥ 01.08.03.00 · A1 ≥ 01.05.00.00 · H2D ≥ 01.01.00.01。
低于门槛菜单里根本没有这一项，要先升级固件。

> ⚠️ 开了开发者模式以后，FTPS 服务不会立刻就位，要等一两分钟，或者重启一次打印机。
> 不然自检会在第 6 层报红叉，看起来像配置错了，其实只是服务还没起来。

4. 七层自检：失败必须能定位

python bridge/p1s.py doctor

> 第 6 层是硬门槛。 前五层全绿也不过是「看得到、打不了」—— 能读温度和进度，
> 但一个文件都传不上去。

5. 🛑 十一道安全闸门（最重要的一章）

每一条都对应真机上真会出事的场景，不是理论风险。

> 下表前 11 条是硬闸门（拦死），最后一条是告警（只提醒不拦）。
> 分开算是因为一致性问题机器扛得住、只是件会废，不该因此卡住你；
> 而前 11 条一旦放行就会伤到机器或浪费几小时打印。

第 6 条管绝对值（切完读产物），第 8 条管调参阶段就别让脏参数出门，
告警那条管张冠李戴。

> 第 10、11 条挡住的是「件能正常打完、但完全是废品」这一类事故：
> 用错料和板型不符都不会让机器报警，件也会顺顺当当打完，
> 只有拿在手里才发现废料（或温度差太多直接堵头）。
> 想走外挂料架就把情况说明白：printer_print(external_spool=true)，这道核对会跳过。

配套：板型必须与切片时一致。P1S 没有 X1C 那种板型自动检测，
打印侧写 auto 会落到别的板上，首层温度不对就会掉件、翘边。

5.1 启动打印前的唯一人工环节：--confirm

11 道闸门全部由机器自己查，查完才轮到人。人只需要做一件事：确认这次要打。

python bridge/p1s.py print x.gcode.3mf --confirm

MCP 里对应 printer_print(file=..., confirm=true) —— confirm 没给就是 false，
一律拦下。这一条同时是第 1 道闸门：AI 说自己确认不算，得是你在场点头。

下发之前，屏幕上会先把这次的关键信息回显出来：打哪个文件、机器上装的是什么料、
按哪块板打。核对一遍再回车，比打完发现用错料省事得多。

6. 标准流程

① 体检 → ② 调参 → ③ 切片 → ④ 校验产物 → ⑤ 上传 → ⑥ 确认 → ⑦ 打印 → ⑧ 收尾

6.1 体检

python scripts/analyze_geometry.py model.stl --json jobs/x/geo.json

输出 fit_build_volume / positive_quadrant / on_bed / floating_mm / wall_thickness 等。
R002 硬拦超界，R003~R005 只告警（这几类情况切片器会自动摆正救回来，拦死反而误伤）。

6.2 调参

python scripts/apply_rules.py --geometry jobs/x/geo.json --material PLA \
        --purpose functional -o jobs/x/overrides.json

--purpose decorative 才走外观件规则（层高分档不同）。

想手工改参数就加 --set 键=值（例如 --set nozzle_temperature=225）。
它会先过 7.2 的物理学硬约束再落盘 —— 越界 / 非数字直接拒绝产出，
不会把脏参数一路带到切片器。

6.3 切片 + 校验

切片出 .gcode.3mf，然后必须拆开它核对。.gcode.3mf 其实是个 zip：

• Metadata/project_settings.config（JSON）→ filament_type / nozzle_temperature / textured_plate_temp
• Metadata/slice_info.config（XML）→ prediction（秒）/ weight（克）

> 两个文件格式不一样，别拿一个解析器通吃。

6.4 上传 → 打印

python bridge/p1s.py upload jobs/x/x.gcode.3mf
python bridge/p1s.py print  x.gcode.3mf --confirm

> subtask_name 传完整路径的话，打印机屏幕上会显示一长串东西，而且和 SD 卡上的文件名对不上。
> 所以打印时只发文件名，别发完整路径。

AI 走这条链路时的规矩：printer_print 缺 confirm 会直接返回「未确认，已拦下」。
必须先向你说明要打哪个文件、得到明确同意，再把 confirm 设为 true ——
不能替你决定、不能跳过。

7. 写死的硬约束

7.1 机器规格

7.2 参数硬约束（拦在调参出口）

apply_rules.py 写出 overrides 之前会跑 physical_limits()，一条越界就拒绝产出（失败关闭）：

单独验证这套闸门：

python bridge/test_physical_limits.py

它会同时造正常参数确认不误伤，和越界参数确认拦得住（14 条）。

8. 使用须知与已知陷阱

8.1 CLI 不认预设名，也不展开 inherits

bambu-studio --slice 的参数得自己从预设 JSON 里解析；预设里的 inherits 不展开的话，
平台会退化成默认的 200×200×100。而且预设里所有值都是字符串或字符串数组。

8.2 键名归属搞错会静默丢弃

curr_bed_type 在 machine / process 两个预设里都没有，必须显式注入。
写错归属时 CLI 不报错，只是悄悄不管你 —— 症状是「配置明明写了却没生效」。

8.3 🚨 材料有两处来源，只改一处会切出废件

这是整套东西里最隐蔽的一个坑。

材料在流程里经过两个环节：切片预设选料、调参查温度表。只改前者，产物会变成：

filament_settings_id = Bambu PLA Basic @BBL X1C   ← 对
filament_type        = PLA                        ← 对
nozzle_temperature   = 245                        ← 错，这是 PETG 的
textured_plate_temp  = 75                         ← 错，这是 PETG 的

所有硬闸门都拦不住它：245 离喷嘴上限 300 远得很，热床 75 也低于 100，
切片照样 ok=true，文件照样产出。只有拆开 3mf 对读数才看得见。
打 PLA 会过热烤料、拉丝，而且件能照常打完，所以极难被发现。

防法（三件都要做）：

1. 只留一个来源：材料默认值从配置反推，不在函数签名里另写一个
2. 内置一致性校验，容差喷嘴 ±25 / 热床 ±12
3. 已集成进自检，python bridge/test_material_sanity.py 可单独跑

8.4 开关开了，FTPS 却还没就位

见第 3 章。补充一句：FTPS 模式要用一次连接探测（连上去等 2 秒看有没有 220），
千万别写成「先试显式，超时了再试隐式」。真机上这么干会把第一次连接挂在 990 上干等，
打印机把它当异常，紧接着的第二次连接直接被拒 —— 于是你以为是通道坏了，其实是被自己那次探测搞死的。

8.5 AI 生成的粗模必须先过 heal_mesh.py

顺序有讲究：先减面再补洞（补洞走环检测，面数越多越慢）。
另外 split(only_watertight=False) 会顺手补洞并加面（78,656 面 → 81,856 面），
所以水密性只看 is_watertight，不要用面数变化判断对错。

8.6 --set 的脏参数会一路带到打印机上

手工改参数时，--set nozzle_temperature=350、--set hot_plate_temp=150、
--set layer_height=0.5、--set nozzle_temperature=abc 看起来都会落盘：
不报错、不警告，切片照样 ok=true，文件照样产出，
一路走到打印机上 —— 要么首层就废，要么烫坏热端。

现在 apply_rules.py 出口有 physical_limits() 兜底（见 7.2），一条越界就不产出 overrides。
层高那档是硬闸门不是告警：0.5mm 层高配 0.4 喷嘴出来的件层间完全不粘、一掰就断，
这不是「质量差点」，是整件报废。

8.7 含纤维耗材不会被降级成纯料

材料名是按别名模糊匹配查表的。PETG-CF 如果库里没有，就会命中 PETG ——
单看结果每一步都"合理"：温度 245/75 正是 PETG 的正常值，退出码 0，没报错也没告警。

但含纤维耗材有独立属性：abrasive。丢掉它意味着三件事同时失效：

所以带纤维标记却只能匹配到纯料版本时直接报错，而不是猜 ——
报错比给一套看着合理但错误的基线安全。

8.8 材料查不到预设时，不会静默回落到 PETG

同一套降级逻辑在切片侧同样危险：

它比报错危险得多：产物 filament_type 写的是 PETG、温度看着也像样，
ok=true、文件正常产出，没有任何一道闸门会响。

现在切片侧是精确查表：带纤维标记的一律不许由纯料顶替，
完全不认识的直接报错并把可选清单列给你。

8.9 材料库：含纤维耗材基线取自官方一手数据

材料库含纤维耗材共 11 种，数值取自 Bambu Studio 内置官方预设（与切片器一致的实机值）
和 官方 TDS / Filament Guide（权威边界）两处交叉校验，实机值落在官方区间内才会入库：

python bridge/test_material_data.py 会重新对撞一遍这两个来源（56 条）。

9. 排错表

10. 文件清单

bridge/                    连通层 + 打印控制
  setup.py                 一键安装引导
  p1s.py                   doctor / status / upload / print / control
  mcp_server.py            MCP 服务入口（见 2.4，配了 Agent 才能直接调）
  discover.py              局域网找打印机（SSDP + ARP + 端口三条路）
  mock_printer.py          假打印机：不用真机也能验证全链路
  practice.py              离线一键自检（起假打印机，跑完回收）
  selftest.py              连通层用例（28 条）
  mcp_selftest.py          MCP 层用例（C/D 段需夹具，见 11 章）
  safety_audit.py          专找「不该放行的放行了吗」（9 条）
  test_material_sanity.py  材料-温度闸门反向验证
  test_gcode_gate.py       G-code 白名单（含多行注入）反向验证
  test_material_fiber.py   含纤维耗材识别反向验证
  test_physical_limits.py  参数物理硬约束反向验证
  test_print_safety.py     打印前闸门反向验证：stop/pause 确认、耗材核对、板型核对
  test_material_data.py    材料库数据自检 + 材料规则正反两面
  test_bug_regressions.py  历史 bug 台账：一条编号一条断言，改完代码跑它查老问题有没有复活
  stage4_demo.py           自制零件逐个走完 体检→调参→切片→上传
  parts.py                 生成样例零件，**输出到当前目录**（先拿它练手）
  config.example.json      配置模板（IP/序列号，可入库）
  config.mock.json         假打印机配置：自检靠它，不用插真机
  .secrets.mock.json       假访问码：同上。真访问码另存 .secrets.json（自己生成，不进包）
scripts/                   模型与参数层
  analyze_geometry.py      几何体检
  apply_rules.py           规则引擎
  slice_cli.py             Bambu Studio 无头切片封装
  filament_presets.py      材料 → Studio 耗材预设（切片与 MCP 两侧共用同一份）
  heal_mesh.py             AI 粗模修复
  calibrate.py             标定登记
references/
  materials.json           材料基线
  rules.json               几何规则 → 参数覆盖
  param-keys.md            参数键名对照
_verify/                   测试夹具（cube50.stl / fixture_hollow_tall.stl）
                           ⚠️ SkillHub 在线版不含（平台禁 .stl 二进制），本地交付包含，
                           故 mcp_selftest.py 的 C/D 段会自动跳过（详见第 11 章）

改完代码先跑这三套：python bridge/selftest.py / mcp_selftest.py / safety_audit.py。
不需要插打印机 —— 它们会自动起一台假机器，跑完回收。

改完闸门相关的代码，再跑一次 python bridge/test_bug_regressions.py：
它把每个历史 bug 编号对应到一条断言，绿了说明老问题没复活，红了会直接指出是哪一条。
加 --full 会连带跑完上面那几套端到端。

> 关于测试夹具：mcp_selftest.py 的 C/D 段（调参 + 切片的 12 条回归）需要
> _verify/ 下两个真值已知的 STL 夹具。SkillHub 在线版因平台不允许上传
> .stl 二进制文件，故不含夹具——此时自检脚本会自动跳过 C/D 段，只跑
> A/B 段（连通 + 安全闸门，14 条），并打印「完整夹具在本地交付包」的提示，
> 这不是报错。想跑全量 26 条回归用本地交付包；日常打印、调参、切片不受任何影响
> （拿自己的 STL 走 MCP 工具即可）。

11. 使用前请知悉

• 首次打印请在场。闸门能保证「不乱来」，保证不了「不出意外」。
• 多材料、远程云打印、自动支撑材料这些没做 / 没测，不要指望。
• AI 生成的三维模型必须先跑 heal_mesh.py，直接扔去切片大概率会得到一个怪东西。
• 支撑料（AMS 里常见名为 PLA-S）是故意做成层间粘不牢以便拆支撑的，
  拿它打主体会得到发脆、易分层的件。

SkillHub 在线版与本地交付包的区别

> 在线版不是为了阉割能力，而是 SkillHub 不允许上传 .stl 二进制（服务端硬限制），
> 测试夹具只能随本地交付包走。核心的打印、调参、切片代码两版完全一致，
> 在线版拿任意一个自己的 STL 就能完整体验全部能力。

12. 付费说明（Pay Skill · 支付宝 AI 付）

本技能为 SkillHub 按次付费 Skill，由平台通过「支付宝 AI 付」在对话流内代收，
用户确认支付后继续执行，无需跳出页面。

计费方式：按调用量计费（每次成功完成一件模型从文件到开打的全流程 计 1 次）。

单次价格：¥9.90 / 次（发布时以 SkillHub 上架表单填写的单价为准；
技能内声明 / 平台登记 / 上架表单三处单价须完全一致）。

收款通道：支付宝 AI 付（平台代收，个人开发者无需自行申请支付宝商户号，
实时结算至收款账户）。

适用前提：个人实名 + 已开通 SkillHub 收款能力。

单次覆盖范围：一次付费 = 完成一件模型从文件到开打的全过程：

批量场景怎么算：

• 一个模型文件 = 一次调用。传 3 个 STL 分别打印 = 3 次。
• 同一模型重试（切片失败后改参数重切、打印中途失败重打）不重复计费，
  凭同一 orderId 复用授权。
• 一次调用内对同一模型做的多轮调参、多次试切，算在同一次里。

不含：耗材与机器损耗、模型设计本身、AI 生成三维模型、多材料打印（未实测，不提供）。

退款：打印未按约定产出（切片失败、产物校验不通过）不计费；
已成功切片并开始打印的，因耗材/机器/模型问题导致的成品瑕疵不在计费争议范围内。

付费调用编排（支付宝 AI 付 六步协议）

本技能作为按次付费 Skill 对外提供服务时，遵循以下支付宝 AI 付六步协议。
Agent 只负责编排，不代付、不接触密钥。

① 402 账单下发（probe → bill）
平台在收到调用且未检测到有效付款时，返回 HTTP 402 与 Payment-Needed 账单
（含 orderId、金额、支付入口）。收到 402 即暂停交付，保存账单与订单号，
等待用户完成支付。

② 支付确认（pay）
用户在支付宝收银入口完成支付后，平台确认收款。

③ 验付（payment.verify）
服务端调用支付宝 OpenAPI payment.verify 做五重校验
（订单状态、金额、签名、appId、收款方），确认支付真实有效后才放行后续流程。

④ 履约（fulfill）
验付通过后，平台放行本次调用，技能继续执行体检 → 调参 → 切片 → 上传 → 开打全流程。

⑤ 履约确认（fulfillment.confirm）
资源生成完成后，调用 fulfillment.confirm 回执确认交付。
回执成功才置本次调用为已完成，否则不计费。

⑥ 幂等复用（retry）
同一 orderId 在有效期内可复用授权，重试不重复计费。