拓竹 3D 打印全流程助手

技能文档

---
name: bambu-studio-ai
title: 拓竹 3D 打印全流程助手
description: 拓竹（Bambu Lab）3D 打印机控制与全流程自动化：模型搜索、AI 生成、分析与修复、上色、预览、切片确认、打印与实时监控，支持 A1 Mini/A1/P1S/P2S/X1C/X1E/H2C/H2S/H2D 全系打印机和 AMS 多色系统。当用户提到打印机状态、3D 打印、切片、分析模型、生成 3D 模型、AMS 耗材、打印监控等 3D 打印任务时触发。触发词：3D 打印、打印机状态、切片、打印模型、生成 3D、AMS、打印监控、拓竹。
category: 通用技能
---

# 拓竹 3D 打印全流程助手

请求 → 收集信息 → 搜索/生成 → 分析（11 项）→ [上色] → 预览（发到会话）→ 打开 BS → [用户在 BS 切片] → 确认 → 打印 → 监控

前置检查：若 `config.json` 不存在，先执行「首次配置」再进行任何操作。

**每轮开始处理打印请求时**：重读下方流水线清单与合规规则，确保不跳过任何 MUST 步骤。

## ⛔ 合规规则——严格执行

**每次操作前，确认没有违反以下规则：**

| 规则 | 含义 |
|------|------|
| **必须（MUST）** | 不可协商。跳过 = 失败 |
| **禁止（NEVER）** | 违反 = 失败 |
| **等待（WAIT）** | 用户回应前不得继续 |

### 禁止事项
- ❌ **禁止跳过信息收集** —— 必须询问：模型来源（搜索/生成）、尺寸（生成时）、单色/多色、材料
- ❌ **禁止无尺寸生成** —— 运行 `generate.py` 前必须询问「要做多大？比如高 80mm」
- ❌ **禁止跳过分析** —— 每个模型都必须经过 `analyze.py --orient --repair`
- ❌ **禁止跳过预览** —— 打开拓竹切片软件（Bambu Studio）前必须把预览图/GIF 发到会话，用户必须看到模型
- ❌ **禁止跳过 BS 确认** —— 必须在 BS 中打开，请用户检查，等待明确的「没问题」「打印吧」
- ❌ **禁止自动打印** —— 未经用户确认不得执行 `bambu.py print`，AI 生成的模型常有误差
- ❌ **禁止跳过模型来源选择** —— 必须询问用户：搜索 / 生成 / 不确定（默认先搜索）

### 必做事项（按顺序）
1. **收集信息** → 询问模型来源、尺寸（生成时）、颜色、材料
2. **获取模型** → 按用户选择搜索或生成
3. **分析** → 每个模型执行 `analyze.py --orient --repair`
4. **预览发到会话** → `preview.py --views turntable` → **把图片/GIF 发给用户**
5. **打开 Bambu Studio** → `open -a "BambuStudio" model.3mf`（或 .stl/.obj）
6. **用户在 BS 切片** → 请用户切片、检查并确认
7. **等待确认** → 用户确认就绪前不得继续
8. **打印** → 仅在确认后执行

> 说明：`slice.py`（OrcaSlicer 命令行切片）为**可选项**——仅当用户明确要求 CLI 切片时使用。默认流程是用户自己在 Bambu Studio 中切片，便于可视化调整支撑、填充等设置。

### 流水线清单（宣布完成前逐项核对）
```
[ ] 已收集信息（来源、尺寸、颜色、材料）
[ ] 已获取模型（搜索/生成/用户提供）
[ ] 已运行 analyze.py --orient --repair
[ ] 预览图/GIF 已发送到会话
[ ] 已在 Bambu Studio 中打开
[ ] 用户已在 BS 切片并检查
[ ] 用户已确认「没问题 / 打印吧」
[ ] 已开始打印（仅在确认后）
```

## 命令速查

| 需求 | 命令 |
|------|------|
| 打印机状态 | `python3 scripts/bambu.py status` |
| 打印进度 | `python3 scripts/bambu.py progress` |
| 硬件信息 | `python3 scripts/bambu.py info` |
| 开始打印 | `python3 scripts/bambu.py print <file> --confirmed` |
| 暂停/恢复/取消 | `python3 scripts/bambu.py pause\|resume\|cancel` |
| 速度模式 | `python3 scripts/bambu.py speed silent\|standard\|sport\|ludicrous` |
| 灯光开关 | `python3 scripts/bambu.py light on\|off` |
| AMS 耗材信息 | `python3 scripts/bambu.py ams` |
| 相机快照 | `python3 scripts/bambu.py snapshot` |
| 发送 G 代码 | `python3 scripts/bambu.py gcode "G28"` |
| 通知 | `python3 scripts/bambu.py notify --message "done"` |
| 文生 3D | `python3 scripts/generate.py text "描述" --wait`（`--raw` 跳过自动增强） |
| 图生 3D | `python3 scripts/generate.py image photo.jpg --wait` |
| 下载模型 | `python3 scripts/generate.py download <task_id>` |
| 分析模型 | `python3 scripts/analyze.py model.stl --orient --repair --material PLA` |
| 只保留主体（去碎片） | `python3 scripts/analyze.py model.stl --repair --keep-main` |
| 多色处理 | `python3 scripts/colorize.py model.glb --height 80 --max_colors 8 -o out.obj`（可调 `--min-pct`、`--no-merge`、`--island-size`、`--smooth`、`--bambu-map`） |
| CLI 切片（可选） | `python3 scripts/slice.py model.stl --orient --arrange --quality fine` |
| 指定配置切片（可选） | `python3 scripts/slice.py model.stl --printer A1 --filament "Bambu PETG Basic"` |
| 列出切片配置 | `python3 scripts/slice.py --list-profiles` |
| 快速预览 | `python3 scripts/preview.py model.stl` |
| 高清预览（Blender） | `python3 scripts/preview.py model.stl --hq` |
| 搜索模型 | `python3 scripts/search.py "手机支架" --limit 5` |
| 监控打印 | `python3 scripts/monitor.py --auto-pause` |
| 依赖自检 | `python3 scripts/doctor.py` |

所有脚本均支持 `--help`。`generate.py` 会自动增强提示词并把尺寸限制在打印幅面内。

## 技能工作流

### 步骤1：信息收集

**门禁**：任何搜索/生成/下载之前必须完成本步。

收集内容：

**模型需求：**
- 打印什么（物体描述）
- 目标尺寸 —— 生成前必须询问（「要做多大？比如高 80mm」）
- 风格/外观（可选）

**打印参数：**
- 单色还是多色（AMS）
- 材料（默认 PLA）
- 质量：draft / standard / fine / extra（可选）
- 用途：功能件或装饰件（可选，影响壁厚与填充）

**模型来源——询问用户：**
> 「您希望：
> 1. 🔎 网上搜索 —— 现成模型，质量通常更高
> 2. 🎨 AI 生成 —— 从零定制模型
> 3. 🤷 不确定 —— 我先搜索，没有合适的再生成」

默认先搜索。常见物体（手机支架、挂钩、花瓶）网上几乎都有。

**决策流**：用户说「搜索 / 生成 / 不确定」→「不确定」则先搜索 → 无理想结果时提供生成选项。

### 步骤2：获取模型（决策点 1）

**门禁**：本步之前必须已询问用户「搜索、生成还是不确定」。默认先搜索。

**流程 A —— 网络搜索（优先）**

1. `search.py "关键词" --limit 5` → 覆盖 MakerWorld、Printables、Thingiverse、Thangs
2. 列出结果（名称、来源、URL）供用户选择
3. 用户选择 → 下载 → 校验格式（STL/OBJ/3MF）
4. → 进入模型处理

无理想结果 → 提供 AI 生成选项。

**流程 B —— AI 生成（单色）**

**生成前检查点**：是否已询问尺寸？没有就先问。

1. 首次使用时免责声明（一次）：「AI 模型质量取决于服务商与提示词，不能直接用于生产——务必在 Bambu Studio 中检查」
2. 确认尺寸 —— `generate.py text` 前**必须有**
3. `generate.py text "提示词" --wait` → 自动增强、自动限制在打印幅面内
4. `preview.py model.stl --views turntable -o preview.gif` → **把 GIF 发到会话**
5. → 进入模型处理

**流程 C —— AI 生成（多色）**

**生成前检查点**：是否已询问尺寸与颜色？没有就先问。

1. 同流程 B 的免责声明
2. 确认尺寸与期望颜色 —— `generate.py text` 前**必须有**
3. `generate.py text "提示词" --wait` → 输出带纹理的 GLB
4. `colorize.py model.glb --height <尺寸> --max_colors 8 --bambu-map` → 顶点色 OBJ + _color_map.txt（耗材建议）
   - 像素 HSV 分类 → 贪心面积选色 → CIELAB 匹配 → 顶点色
   - 无需去阴影——HSV 分类可绕过烘焙光照
5. **把量化后的纹理预览发给用户** —— colorize 会自动输出 `_preview.png`；同时运行 `preview.py model.obj --views turntable -o preview.gif`，**两张图都发到会话**
6. **分析结果并建议调参**（如有需要）：
   - 报告检测到的颜色（名称、十六进制、占比）
   - 若小而有意义的颜色丢失（如眼睛、配件 <1%）→ 建议 `--min-pct 0`（保留 0.1% 以上所有颜色）
   - 若相近颜色被错误合并（如黄色身体 + 棕色裤子）→ 建议 `--no-merge`（关闭同族互斥）
   - 若出现过多杂色 → 建议调高 `--min-pct` 或 `--island-size`
   - 若边界噪点过多或过度平滑 → 调整 `--smooth`（0=不平滑，5=默认，越大越平滑）
7. 用户要求调整 → 用新参数重跑 colorize → 展示新预览
8. 用户认可后 → 进入模型处理

**colorize 可调参数：**

| 参数 | 默认 | 作用 |
|------|------|------|
| `--max_colors N` | 8 | 最大颜色数（AMS 硬上限 ≤8） |
| `--min-pct X` | 0.1 | 最小色族占比阈值（0=全部保留，5=激进过滤） |
| `--no-merge` | 关 | 关闭色族组互斥（12 个色族全部独立） |
| `--island-size N` | 1000 | 移除小于 N 像素的孤立色块（0=禁用） |
| `--smooth N` | 5 | 多数投票边界平滑次数（0=原始，越大越平滑） |
| `--bambu-map` | 关 | 输出 _color_map.txt 拓竹耗材建议（CIELAB 匹配） |

**流程 D —— 用户提供文件**

1. 校验格式（STL/OBJ/3MF/GLB），必要时转换
2. → 进入模型处理

### 步骤3：模型处理

**门禁**：本步之前必须已有模型文件（搜索、生成或用户提供）。

所有模型必须经过本步，无一例外。**禁止跳过 analyze 或 preview。**

**分析（11 项检查）：**
```
analyze.py model.stl --orient --repair --material PLA --purpose functional
```
检查：尺寸公差、壁厚、受力方向、悬垂（>45°）、打印朝向、悬浮部件、层高、填充率、壁数、顶层数、材料兼容性。另含：水密性、流形、幅面适配。

**自动修复**：修法线、补孔、移除退化面。
**自动摆向**：最优稳定性，自动识别单位（米→毫米）。

**向用户报告（必须）：**
- 可打印性评分（X/10）
- 警告与问题
- 已执行的修复
- 推荐设置（层高、填充、壁数、温度、支撑）

示例：「评分 8/10。修复了 5.8 万条非流形边。壁厚 1.5mm ✅ 悬垂 3.2% ✅ 推荐：0.20mm 层高、20% 填充、PLA 210°C。」

**预览渲染（必须——禁止跳过）：**
```
preview.py model.stl --views turntable -o model_preview.gif
```
- 单色：默认蓝色材质渲染 STL/3MF
- 多色：以顶点色渲染 colorize 后的 OBJ
- **必须把预览图/GIF 发到会话** —— 用户没看到就不能继续
- 转台太慢时用 `--views perspective` 出单张图
- **检查点**：预览是否已随消息附上？没有就在打开 BS 前完成

**可选 CLI 切片**（仅用户明确要求时）：
```
slice.py model.stl --orient --arrange --quality standard
```
自动识别打印机与喷嘴。质量：draft(0.24) / standard(0.20) / fine(0.12) / extra(0.08)。输出含 G 代码的 .3mf。

### 步骤4：用户确认

⛔ **必须——禁止跳过**

**门禁**：本步之前必须已把预览发到会话。

1. 在 Bambu Studio 中打开：`open -a "BambuStudio" model.3mf`（或 .stl/.obj）
2. 请用户检查并切片：
   > 「模型已在 Bambu Studio 中打开。请检查：
   > - 外形是否正确？有无缺失或变形？
   > - 有无悬浮/断开的部件？
   > - 尺寸是否正确？（看底栏尺寸）
   > - 在 Bambu Studio 中**切片**（Ctrl+R / Cmd+R），核对预计用时、耗材用量与支撑。
   > 准备好了告诉我！」
3. 等待明确确认。

⛔ 禁止自动打印。AI 模型常有分析无法完全发现的问题。

4. 询问打印方式：
   - 直接自动打印 → 流程 E（仅开发者模式，不推荐）
   - 在 Bambu Studio 手动打印 → 流程 F

### 步骤5：执行打印（决策点 2）

**流程 E —— 自动打印（仅开发者模式，不推荐）**
⚠️ 需开启开发者模式。Bambu Studio 与 Bambu Handy 会断开连接。
1. `bambu.py print model.3mf --confirmed`
2. 确认：「打印已开始！」
3. → 进入监控

**流程 F —— 手动打印**
- 模型已在 Bambu Studio 中打开
- 用户自行调整设置并从 BS/Handy 打印

**打印检测——两种方式：**

1. **主动监听（模型交付后）**：助手在 BS 中打开模型后（流程 B/C/D），立即启动后台 MQTT 监听（30 分钟窗口）。打印机状态变为 RUNNING → 通知用户并提供监控选项。
   - 实现：后台 `exec` 运行 paho-mqtt 订阅循环，每 30 秒轮询状态变化
   - 30 分钟无打印则自动停止
   - 检测到时：「🖨️ 看到你开始打印 [文件名] 了！需要我实时监控并发送快照吗？」

2. **心跳兜底**：常规心跳时检查打印机 MQTT 状态。RUNNING 且未在监控 → 通知用户。

- 用户接受 → 开始监控（步骤6）

### 步骤6：打印监控

触发：自动打印（流程 E）、手动打印（流程 F）或用户要求。需 LAN 模式。

⚠️ 先询问：「需要我监控吗？出现严重问题自动暂停？」

**监控方式**：通过 paho-mqtt 直接订阅 MQTT（不用 bambulabs_api——它有 SSL 问题）。连接 `{打印机IP}:8883`，订阅 `device/{serial}/report`，解析 `print` 消息。

**监控期间相机快照是必须的：**
- 通过 RTSP 抓取：`bambu.py snapshot`（ffmpeg → rtsps://bblp:{码}@{ip}:322/streaming/live/1）
- 每次进度更新都随附快照
- 异常告警中包含快照

**默认监控计划（按里程碑，每次打印约 5 条消息）：**

| 事件 | 触发条件 | 动作 |
|------|---------|------|
| 打印开始 | 状态 → RUNNING | 通知 + 📸 快照 |
| 25% 进度 | mc_percent ≥ 25 | 状态 + 📸 快照 |
| 50% 进度 | mc_percent ≥ 50 | 状态 + 📸 快照 |
| 75% 进度 | mc_percent ≥ 75 | 状态 + 📸 快照 |
| 打印完成 | 状态 → FINISH/IDLE | 完成通报 + 📸 最终快照 |
| 异常 | 任意时刻 | 立即告警 + 📸 快照 + 自动暂停（如启用） |

用户可调整频率。记录已上报的里程碑避免重复。

**异常检测：**

| 异常 | 严重度 | 动作 |
|------|--------|------|
| 进度停滞 >10 分钟 | 警告 | 告警用户 + 快照 |
| 温度异常 | 严重 | 告警 + 快照 + 自动暂停 |
| 打印失败/报错 | 严重 | 告警 + 快照 + 自动暂停 |
| 异常暂停 | 警告 | 告警用户 + 快照 |
| 模型离床 | 严重 | 自动暂停 + 告警 + 快照 |
| 拉丝乱线（spaghetti） | 严重 | 自动暂停 + 告警 + 快照 |

**状态报告格式（发给用户）：**
```
🖨️ 打印更新 —— {文件名}
📊 进度：{百分比}% | 层 {当前}/{总层数}
⏱️ 剩余：{时间}
🔥 喷头：{温度}°C | 🛏️ 热床：{温度}°C
📸 [随附快照]
```

### 步骤7：首次配置

`config.json` 不存在时触发，以对话方式完成：

1. **打印机型号** —— A1 Mini、A1、P1S、P2S、X1C、X1E、H2C、H2S、H2D
2. **连接方式** —— 局域网（推荐：IP + 序列号 + 访问码）或云端（邮箱 + 密码，功能受限）
3. **打印模式** —— 必须向用户讲清：
   - **方案 A：推荐（安全）** —— 助手生成模型 → 在 Bambu Studio 打开 → 用户自行切片、检查并手动打印。无需特殊打印机设置。
   - **方案 B：全自动打印** —— 助手直接控制打印机（经 MQTT 启停/监控）。需要：
     - ⚠️ **开启开发者模式**（打印机触屏 → 设置 → 仅局域网模式 → 开启 → 开发者模式 → 开启）
     - ⚠️ Bambu Studio 与 Bambu Handy 将**完全断开**（无云端、无远程监控）
     - ⚠️ 仅限局域网访问（同一网络）
     - 助手打印前仍必须展示预览（未经确认绝不自动打印）
   - 将选择以 `print_mode: "manual"` 或 `"auto"` 存入 config.json
4. **3D 生成**（可选）—— Meshy、Tripo、Printpal、3D AI Studio 及 API Key
5. **通知** —— macOS 系统通知（自动）；会话内通知由助手自身消息能力处理
6. **保存** —— `config.json` + `.secrets.json`（chmod 600，已 git-ignore）
7. **验证**（征得同意）—— 测试连接、相机、AMS
8. **汇总**

## 环境与依赖

**必需**：`python3`、`pip3`（推荐 macOS；核心脚本跨平台可用）
```bash
pip3 install bambulabs-api bambu-lab-cloud-api requests trimesh numpy Pillow ddgs pygltflib cryptography paho-mqtt
```
**可选（macOS）**：`ffmpeg`（相机快照）、Bambu Studio（预览 + 切片）、Blender 4.0+（多色 + 高清预览）、OrcaSlicer（CLI 切片）

**环境变量**（覆盖 config.json）：`BAMBU_MODE`（local 默认/cloud）、`BAMBU_MODEL`、`BAMBU_EMAIL`（云）、`BAMBU_IP`（局域网）、`BAMBU_SERIAL`（局域网）、`BAMBU_ACCESS_CODE`（局域网访问码）、`BAMBU_VERIFY_CODE`（云端一次性验证码）、`BAMBU_3D_PROVIDER`（meshy/tripo/printpal/3daistudio/rodin）、`BAMBU_3D_API_KEY`

**敏感信息**（`.secrets.json`，chmod 600）：`password`、`access_code`、`3d_api_key`。全部由用户提供，包内不含任何凭证。令牌缓存 `.token_cache.json`（90 天，可删除以强制重新登录）。所有网络调用、文件写入、打印机操作和监控都需用户明确同意。

## 常见错误自查

| 错误做法 | 正确做法 |
|---------|---------|
| 跳过「搜索还是生成」的询问 | 必须先问用户，默认搜索 |
| 未问尺寸就生成 | 必须先问「要做多大？比如高 80mm」 |
| generate.py 后直接开 BS | 中间必须跑 analyze.py 和 preview.py |
| 说「模型已备好」却不发图 | 必须把预览 GIF/图片附在消息里 |
| 用户没看预览就开 BS | 打开 BS 前用户必须先在会话中看到预览 |
| 没等到「没问题」就开始打印 | 必须等用户明确确认 |
| 认为「搜索来的不用分析」 | 所有模型都要 analyze，搜索结果也可能有问题 |
| 模型有 68 个碎片就直接重新生成 | 先看预览——AI 网格常误报多个「实体」，视觉上没问题就别用 `--keep-main` |

## 常见问题

| 问题 | 解决 |
|------|------|
| 局域网 SSL 握手错误 | 正常（自签证书），已自动处理 |
| API 方法找不到 | `pip3 install --upgrade bambulabs-api`（v2.6.6+） |
| 局域网连不上 | 开启 LAN 模式 + IP 正确 + 同一网络 |
| 云端验证码 | 等邮件，输入一次即可，令牌缓存 90 天 |
| 相机超时 | 唤醒打印机（点屏幕），检查 IP |
| AI 模型有孔洞/悬浮件 | 正常现象，务必运行 `analyze.py --repair` |
| Tripo/Meshy 报告 68+ 个「实体」 | 通常无害（非流形拓扑，非真碎片），先看预览，视觉完好就别用 `--keep-main` |

## 已知限制

| 功能 | 状态 |
|------|------|
| 单色流水线 | ✅ 稳定 |
| 多色（colorize） | ✅ 自动识别 ≤8 色，顶点色 OBJ → BS 色合并对话框 |
| CLI 切片 | ✅ OrcaSlicer 后端（BS CLI 在 v2.5.0 段错误） |
| 端到端自动打印 | ✅ 开发者模式下可用（X.509 签名 MQTT + FTP 上传） |

## 参考文档

- [references/model-specs.md](references/model-specs.md) —— 全部 9 款打印机规格
- [references/bambu_filament_colors.json](references/bambu_filament_colors.json) —— 拓竹 43 色色板（参考，colorize v4 使用纹理原生色）
- [references/bambu-mqtt-protocol.md](references/bambu-mqtt-protocol.md) —— MQTT 协议
- [references/bambu-cloud-api.md](references/bambu-cloud-api.md) —— 云端 API
- [references/3d-generation-apis.md](references/3d-generation-apis.md) —— 3D 生成服务商接口
- [references/3d-prompt-guide.md](references/3d-prompt-guide.md) —— 3D 提示词工程

使用说明

# 拓竹 3D 打印全流程助手

拓竹（Bambu Lab）3D 打印机控制与自动化：搜索/生成模型 → 分析修复 → 多色上色 → 预览确认 → 切片打印 → 实时监控，支持全系 9 款打印机与 AMS 多色系统。

## 适用场景

- 查询打印机状态、打印进度、控制打印（暂停/恢复/取消）
- 搜索或 AI 生成 3D 模型并完成可打印性分析
- 多色模型上色与 AMS 耗材匹配
- 打印实时监控与异常自动暂停

## 使用方式

对 AI 助手说：

```text
帮我打印一个手机支架
用 AI 生成一个高 80mm 的花瓶，多色打印
看看打印机现在什么状态
监控这次打印，出问题自动暂停
```

## 前置条件

- `python3` + 依赖：`pip3 install -r requirements.txt`
- 打印机连接信息（局域网 IP/序列号/访问码，推荐；或云端账号）
- 首次使用会自动进入对话式配置，生成 `config.json`

## 安全约定

- 默认「用户在 Bambu Studio 手动切片打印」，自动打印需开启开发者模式且必须逐次确认
- 包内不含任何凭证，敏感信息存本地 `.secrets.json`（chmod 600）

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。