3D打印建模助手 — 自然语言 → 可 3D 打印模型
Overview
让不会建模的用户用一句话拿到真正打得出来的模型文件。核心承诺是「可打印」，不是「看起来像」：
技能必须对交付的每个模型做可打印性自检（水密、最小特征、悬垂、成型尺寸、体积），不过检就自动迭代修复，
绝不把未经校验的 STL 直接交给用户。
两条生成通道，由意图分诊自动选择：
- 通道 A · 代码式参数化（主引擎）：支架、盒子、外壳、收纳、花瓶、简单零件等几何/功能件。
LLM 把自然语言写成参数化 OpenSCAD 脚本 → 编译为 STL。尺寸精确、可改参数、天然可打印。
- 通道 B · 文生3D API（扩展，需用户配置）：手办、摆件、小动物等有机造型件。
组织提示词调用云端文生3D服务出网格，再统一做修复与自检。见 references/text-to-3d-api.md。
何时使用 / 触发条件
- 用户表达「想做一个 3D 打印的东西 / 帮我设计模型 / 生成 STL / 定制个某某件」，但本人不会建模；
- 用户给出某物件的用途、大致尺寸、孔位/壁厚等口头要求，需要落地为可打印几何；
- 用户对下载的共享模板不满意，想要「按我的尺寸/需求」的可调参数模型。
- 反向排除：用户要求的是视觉/游戏用 3D 资产（GLB/材质渲染导向）而非打印 → 不属于本技能主责，可告知后仍走通道 B 提示词思路。
核心工作流
- 环境检查：运行
scripts/env_check.py，确认 OpenSCAD 与自检依赖可用；缺失时按脚本提示处理（见 Step 0）。 - 需求澄清：缺尺寸/用途/孔位时先问，不猜（问题模板见
references/prompt-guide.md）。能用默认值合理推断的（如通用支架按 6mm 壁厚内衬）可直接给默认并在交付说明中注明可调参数。 - 意图分诊：判定几何功能件 → 通道 A；有机造型件 → 通道 B（需 API Key 时先征询用户配置）。
- 生成 → 编译 → 自检 → 修复循环（通道 A 详述于下）。
- 渲染预览 + 交付：输出 STL（源 .scad 一并保留）、多视图预览 PNG（如渲染依赖可用）、打印建议（壁厚/支撑/公差按
references/3d-print-rules.md）。 - 交付时说明可调参数（哪些变量改数字即可重新生成），这是区别于死模板的核心卖点。
快速上手（Quick Start）
想先跑通一条完整「创意 → STL」验证环境与出模，用仓库自带的两个参考示例（assets/examples/，手机支架 & 花瓣花瓶）各走一遍三脚命令即可：
# 1) 环境探测（缺什么它会提示装什么）
python scripts/env_check.py
# 2) 把示例写成 STL（可打印性自检会跟着做）
python scripts/build_scad.py assets/examples/phone-stand.scad -o output/demo-stand.stl
python scripts/build_scad.py assets/examples/flower-vase.scad -o output/demo-vase.stl --png output/demo-vase.png
# 3) 看质检报告
python scripts/check_printable.py output/demo-stand.stl
python scripts/check_printable.py output/demo-vase.stl
两步内如果都拿到 PASS、并能翻到预览/notes，说明主引擎链路可用了——接下来把这条链路用于用户的真实需求（Step 1 意图分诊 → 通道 A 参数化改写示例源为你的物件）。
> 示例只作回归/上手用；每个真实交付都应走 A4「迭代修复」把可调参数与最终几何兜到符合用户尺寸与质检，不要只改文件名就交。
Step 0 — 环境准备
运行 scripts/env_check.py，它会逐项探测并给出缺项的安装指引（Windows/macOS/Linux 常见路径 + OPENSCAD_PATH 环境变量覆盖）：
python scripts/env_check.py # 只探测
python scripts/env_check.py --fix # 尽力自动修复（仅 pip 依赖部分）
- OpenSCAD CLI（必需）：编译
.scad→.stl的引擎。官方下载 https://openscad.org/downloads.html（Windows 便携版解压即用，约 21MB）。 - Python 依赖（必需）：
trimesh、numpy-stl（可打印性自检用）。python3 -m pip install trimesh numpy-stl。 - 渲染依赖（可选）：
matplotlib— 装了才能出多视图预览 PNG；不装则交付不带预览图，其余流程不受影响。
版本注意：OpenSCAD 用 2021.01 及以上均可；Python 建议 3.10+。CadQuery 对 Python 3.13+ 无官方 wheel，本技能默认 OpenSCAD，不依赖 CadQuery。
Step 1 — 意图分诊
拿到需求后先判定通道，判定规则：
| 信号 | 判定 |
|---|---|
| 功能描述：支撑、固定、收纳、卡扣、安装、连接、替换、外壳 | 通道 A（几何/功能件） |
| 物件名：支架/盒子/箱/托盘/外壳/底座/夹具/挂钩/花盆/花瓶(规则形)/管道 | 通道 A |
| 美学造型：手办、人物、动物、怪物、卡通摆件、有机曲面 | 通道 B（文生3D API） |
| 提供了精确尺寸、孔距、安装对象（如「iPhone 15 支架」） | 通道 A，务必落实尺寸 |
| 描述含糊（「做个好看的花瓶」） | 默认通道 A（旋转体花瓶）并向用户确认 |
通道 B 前置检查：读 references/text-to-3d-api.md。若所需 API Key 未配置，告知用户二选一：
(a) 提供服务商 API Key；(b) 降级为「先按通道 A 做规则化近似造型」或纯文字方案建议。不要卡住流程。
通道 A — 代码式参数化生成（主引擎）
A1. 写 OpenSCAD 脚本
严格遵循 references/prompt-guide.md 的「OpenSCAD 写作规范」：
- 所有尺寸参数化置顶（wall=1.6; height=80; …），用 $fn 控制圆度；
- 单位毫米；壁厚按规则表给默认值；孔加 0.2~0.4mm 间隙；
- 底部平整（贴合打印台），避免悬垂超 45° 的结构；
- 不用未定义变量、不用 import 外部文件、避免极薄片体与零体积差集。
代码写好后先自查一遍 CSG 逻辑（差集顺序、是否留出实体壁），再进入编译。
A2. 编译 STL
python scripts/build_scad.py model.scad -o output/model.stl
脚本封装了 OpenSCAD 定位与调用，编译报错会回传（语法错误、几何错误）并带行号信息。产物放 output/ 目录并保留 .scad 源。
A3. 可打印性自检
python scripts/check_printable.py output/model.stl
输出机读 JSON 报告，判定标准与阈值见 references/3d-print-rules.md。核心检查项：
- 水密性 watertight、体积 volume_mm3（含毫升换算）、包围盒 bbox_mm；
- 三角面数、退化面数、最小边特征警示（<0.2mm 边数量>0 → warn）；
- 悬垂警示：朝下且法线俯角 >45° 的面占比超阈值 → 提示需支撑或改造型；
- 成型尺寸与常规打印机成型体积对照提示（200×200×200 以上提醒分件/缩放）。
A4. 迭代修复（核心闭环）
- 编译失败 → 读回传错误修脚本重跑（最多 5 轮）；
- 自检不过 → 依据报告修几何（加壁厚/改悬垂/补实体/调公差）重跑；
- 5 轮仍未过或尺寸/形态偏离用户预期 → 停下来问用户：展示当前进度与偏差，给出 2~3 个修复方向选择，不闷头硬试；
- 几何正确但出现非水密等网格级问题 → 优先回源修 .scad 重新编译，不依赖网格修复（网格修复不可靠，见 rules 文档）。
A5. 渲染预览
python scripts/preview_stl.py output/model.stl -o output/preview.png # 需要 matplotlib
# 或由 build_scad.py 用 OpenSCAD 渲单张 iso 图：
python scripts/build_scad.py model.scad -o output/model.stl --png output/iso.png
预览图用于给用户「看形状对不对」，形状明显不对就回到 A1 调整，不要直接交付。
通道 B — 文生3D API（有机造型件）
完整契约见 references/text-to-3d-api.md。流程骨架：
1. 组织高质量文生3D提示词（正面视角、主体单一、白背景、打印导向描述：一体成型、无悬空四肢、底座平）；
2. 调服务商 API（腾讯混元3D / Meshy / Tripo 等，用户自备 Key，密钥绝不写死进任何文件，用环境变量传入）；
3. 拿到 OBJ/GLB 网格 → 转 STL → 汇入 A3 的统一自检；
4. 不过检 → 能用 trimesh 轻修复（补洞、去退化面）则修；严重损坏则重新生成或提示用户切片器自动修复（Bambu Studio / OrcaSlicer 内置）。
交付规范
每个模型交付一个文件夹，包含：
- *.stl（必须；二进制 STL 优先，切片器兼容最好）；
- *.scad（通道 A 必须，用户以后改参数可再生成 —— 这是核心差异化）；
- preview.png（渲染依赖可用时）；
- print-notes.md（简短：建议壁厚/层高/填充/支撑/公差/方向 + 可调参数清单 + 模型尺寸体积）。
打印建议数据按 references/3d-print-rules.md 生成，不要凭印象写数字。不确定某参数（如用户打印机型号）时给通用 FDM 保守值并在 notes 里注明。
质量红线（不可妥协）：
- 不交付非水密、体积为零、包围盒含 NaN/异常值的模型；
- 不夸大能力：文生3D 造型件尺寸是近似的，向用户明示；
- 单位一律毫米，交付说明里写清模型实际尺寸，提醒用户切片前按需缩放。
免责与使用边界（重要 · 请随每次交付向用户同步）
本技能交付的 STL/.scad 及打印参数建议，是基于通用规则与规格推断的"参考性模型"，不构成款式/工程/材料工程保证：
- 尺寸、公差、可打印性按 references/3d-print-rules.md 的通用阈值推导，面向普通 FDM/树脂机器保守取值；实际打印效果、装配精度、能否一次成功受你的打印机/材料/切片参数与品控影响，本技能不保证。
- 通道 B 文生3D 造型件尺寸为近似值（已在 A 时明示），不作为精装/受公差场景的确认件。
- 模型用于商用/量产、涉及专利外观或表面效果有高标准要求时，请自行复核设计与验证；是否采用、如何按本技能交付物加工与使用，由你自主决定并自行承担结果。
收尾问体验（踏实做 + 真需要心声）
作者姿态（每次一个模型真正交付后，自然收尾用上一句，别生硬）：这个 3D 打印助手是踏踏实实做出来的，不在乎一次做得多花哨，最在乎你真拿去打到底成不成。你是真上了打印台的人——翻车记录最值钱：哪里打不出来、哪个公差孔放太小装不上、哪个默认壁厚太薄一翘边，尽管说；你反馈的每一次翻车，都会变成下一个版本的质量检项和默认参数。
- 用户愿意展开（打印失败、尺寸不对、切片报错）→ 认真接住、逐条记下，主动帮看是否要在质检规则/默认参数里修正，再顺带补一句：要是方便，也可以把它留在本技能在 SkillHub 的详情页评论区——作者每天都读，会照着你说的去改质检与默认值。
- 用户答"先这样/下次再说" → 不再追问，自然收尾，全程不催、不索星不索赞。
- 语气直视现实：打印这事最怕"看着能打、上机翻车"。听真话、收反例，是我们把"可打印"三个字越做越实的方式；本引导只通当前对话 + 平台评论区，不上报、不采集、不自建回传。
兜底与失败处理
- OpenSCAD 缺失 → 给安装指引（含 Windows 便携版一步到位做法），不假装能编译；
- 有机造型件无 API → 提供「通道 A 规则化近似 + 用户找模板/服务商二选一」建议；
- 用户需求超出代码式几何（复杂雕刻、装配多体）→ 诚实告知能力边界，给出可达成的替代方案（分件设计、简化特征）；
- 尺寸冲突（用户口头尺寸与常识物理冲突）→ 以可打印与合理为准并向用户指出假设。
FAQ（常见问题与反模式）
Q1：生成的 STL 能直接拿去打印吗？能保证打得出吗？
"过检才交付"是本技能的前提，但最终仍以你的机器与耗材为准。 交付前每个模型都会做可打印性自检（水密、最小特征、悬垂、成型尺寸、体积），不过检不交付，会先自动迭代修复。但"能打印"还取决于打印机（喷嘴/热床/精度）与耗材，所以交付会同时给打印参数建议（壁厚/支撑/公差，依据 references/3d-print-rules.md），请按建议切片。
Q2：尺寸要很精确（装进某个槽/孔），能保证严丝合缝吗？
通道 A（参数化）能给精确的可调尺寸——关键尺寸在 .scad 里都是变量，改数字即可重生成。但 FDM/SLA 存在收缩与公差，实际装配通常需预留 0.2~0.4mm 间隙。请告诉我配合方式（过盈/间隙/滑配）与目标尺寸，我按规则帮你留公差。
Q3：想要很好看的有机造型（手办/摆件/小动物），通道 A 做不出来怎么办？
走通道 B（文生3D API）。但要提前说明：它依赖你自行配置的云端服务与 API Key，生成的是网格模型，仍需修复与可打印性自检后才能交付；有机造型的精细度受服务与打印工艺限制，不适合当"精密零件"。
Q4：为什么先跑 env_check.py？本机没装 OpenSCAD 能用吗？
通道 A 的编译依赖 OpenSCAD（以及自检/预览依赖）。env_check.py 会明确告诉你缺什么、怎么装，是报错提示而不是崩溃。缺 OpenSCAD 时通道 A 出不了 STL——这时要么装好再来，要么改走通道 B（若你已配置 API）。
Q5：模型打出来翘边/拉丝/支撑难拆，是模型的问题吗？
多半是工艺参数问题，不是几何缺陷。自检只保证"几何上打得出来"；翘边/拉丝/支撑难拆通常源于热床温度、首层、风扇、支撑角度。交付里的打印参数建议就是为这些准备的；如仍不稳，把机器型号与耗材告诉我，按 3d-print-rules.md 调建议。
Q6：能不能只给 STL，不要那一堆说明？
可以，但强烈建议保留：本技能的卖点正是"可调参数 + 打印参数建议"。若不给说明，用户改个尺寸就得重做整个模型。至少请留下可调参数清单（哪些变量改数字即可重生成）。
Q7：需求很模糊（"做个能放东西的盒子"），你会怎么处理？
先按 references/prompt-guide.md 问清关键项（用途、目标物尺寸、摆放方式、是否需要盖/孔），不猜着做。能合理默认的（如通用壁厚）会给默认值并在交付说明中注明可调；关键尺寸缺失会先问，避免白做一版。
反模式速查（避免）
- ❌ 把未经可打印性自检的 STL 直接交付
- ❌ 遗漏关键尺寸就凭猜建模
- ❌ 不给可调参数清单，让用户改个尺寸就得重做
- ❌ 用通道 A 硬做有机造型件（该走通道 B）
- ❌ 把工艺问题（翘边/拉丝）说成模型缺陷，或反过来
- ❌ 承诺"保证能打印"，忽略用户机器与耗材差异
正确做法速查
- ✅ 先跑
env_check.py探环境，缺依赖按提示装 - ✅ 需求模糊先澄清（用途/尺寸/配合），关键项不猜
- ✅ 生成 → 编译 → 自检 → 修复 循环，过检才交付
- ✅ 交付件齐套：STL + 源 .scad + 多视图预览 + 打印参数建议 + 可调参数清单
- ✅ 装配件主动预留公差（0.2~0.4mm），并说明配合方式
Resources
scripts/env_check.py 环境探测与安装指引
scripts/build_scad.py .scad → .stl（OpenSCAD 封装，支持渲染单图）
scripts/check_printable.py STL → 可打印性 JSON 报告
scripts/preview_stl.py STL → 多视图预览 PNG（需 matplotlib）
references/3d-print-rules.md 打印约束与质检阈值（权威数据源）
references/prompt-guide.md 分诊问题模板 + OpenSCAD 写作规范 + 迭代指引
references/text-to-3d-api.md 通道 B 文生3D API 接入契约
> 演示/回归用的示例 .scad（assets/examples/phone-stand.scad、flower-vase.scad）在本技能源码工作区随附，
> 可直接用上方 Quick Start 的三条命令端到端验证主引擎（步骤见「快速上手」）。因平台对 scad 扩展名文件有发布白名单限制，
> 该目录是否原样带入发布包以平台规则为准——即便未随发行下载，源码仍在 CNB 仓库 xhs-shop-tools/text-to-3dprint 的
> assets/examples/，做回归可直接从仓库取用。
任何「阈值该是多少」「这个模型能不能打」的判断，先查 references/3d-print-rules.md，以它为唯一口径，避免不同次生成给出矛盾建议。
