Amagine3D双Skill机制揭秘:text-a3d与text-a3d-color如何协同完成单色与多色CAD
Amagine3D双Skill机制揭秘:text-a3d与text-a3d-color如何协同完成单色与多色CAD
Amagine3D 是一个开源的参数化 CAD 能力层,能从产品描述和参考图生成可编辑的 3D 设计。本文揭秘它的双 Skill 机制:text-a3d 负责单色 CAD(单材料输出,导出 STEP/STL),text-a3d-color 负责多色 CAD(颜色区域 + 彩色 3MF),并解释 Agent 如何在这两个 Skill 之间路由,用同一套“证据驱动”闭环保证模型可打印、可追溯。
一个项目,两套 Skill 的分工
Amagine3D 把“生成一个能打印的 CAD 模型”拆成两份可执行的作业指导书(SOP),分别放在:
- 单色 Skill:skills/text-a3d/SKILL.md
- 多色 Skill:skills/text-a3d-color/SKILL.md
每个 Skill 目录都是自包含的:一份 SKILL.md 流程文档 + 一组 Python 工具脚本 + references/ 参考规范 + examples/ 示例契约。3D Agent 拿到任务后,先读对应的 SKILL.md,再按流程逐个调用脚本。仓库结构概览见 README.md,中文文档见 docs/README.zh-CN.md。
| 对比维度 | text-a3d(单色) | text-a3d-color(多色) |
|---|---|---|
| 适用场景 | 单材料模型、颜色只是照片偶然差异 | 屏幕、按键、Logo、镶件、身份配色区 |
| 产出文件 | STEP + STL | 各颜色区域 STL + 彩色 3MF + STEP 装配 |
| 独有工具 | 轮廓比对 compare_silhouette.py |
palette_plan.py、export_3mf.py、assembly_check.py |
| 质检重点 | 网格拓扑、打印床适配、悬垂 | 区域拓扑 + 合并 STL 制造检查 + 3MF 颜色读回 |
| 共同底座 | 意图契约、Bambu 打印档案、新鲜度校验、CPU Z-buffer 渲染 | 同左 |
单色还是多色?Agent 遵循的路由规则 🎯
两个 SKILL.md 都规定了第一步不是建模,而是路由(route before modeling)。规则很直白:
- 如果对象自带有意义的颜色——屏幕、控制按键、文字/Logo、材料边界、镶件、整体识别色盘——即使用户没提“3MF”或“AMS”,也走
text-a3d-color; - 如果颜色只是光照、反射、背景或照片色差,属于“偶然颜色”,走
text-a3d; - 用户明确要求单色时,单色请求优先。
这套路由写在 skills/text-a3d/SKILL.md 与 skills/text-a3d-color/SKILL.md 中,保证两个 Skill 互斥不冲突、不会各做一半。
text-a3d:单色 CAD 的六步闭环
单色 Skill 的流程核心是“先立标,后做模型”,每一步都有脚本背书:
- 开立可追溯的运行:用
freshness_check.py打时间标记,解析固定的 Bambu 机器/喷嘴/工艺档案(bambu_profile.py),有参考图时先跑reference_analyze.py提取哈希、边界与像素证据; - 写意图契约:按 skills/text-a3d/references/evidence-contract.md 生成
intent.json(尺寸来源、隐藏面假设、关键特征 ID、支撑策略),用intent_contract.py校验——契约先于几何,且不许事后弱化; - 参数化建模:用 build123d 写完整脚本,所有关键尺寸通过
parameter()暴露成工作区滑块,切割/圆角等操作走 fail-closed 封装(cad_helpers.py); - 几何与外观双重证明:
qa_check.py做网格审计、打印床适配、壁厚、悬垂检查;需要外观还原时,用 skills/cpu_z_buffer.py 纯 CPU 渲染四视图并做哈希绑定,无需 GPU; - 按失败证据类修复:尺寸失败改参数、轮廓失败改包络、薄壁加厚、悬垂改朝向——最多三轮修复,且禁止调低打印档案极限来“蒙混”QA;
- 新鲜度门禁 + 交付:
freshness_check.py证明所有交付物都属于本次运行,最终输出print preflight passed / with warnings / failed三档结论。
text-a3d-color:把颜色当可制造几何 🎨
多色 Skill 的理念一句话:颜色是几何与装配决策,不是渲染装饰(见 skills/text-a3d-color/references/color-architecture.md)。它在单色流程之上多做了四件事:
- 颜色语义解析:契约中每个区域必须声明名称、HEX、用途、几何边界、光学材料(opaque/translucent/transparent)——3MF 里存的 RGB 不能证明透光性,透光区域还要生成材料计划;
- 调色板降维:参考图颜色超过可用耗材时,
palette_plan.py做确定性降色;但稀有 Logo 色、按键色等语义色可用--keep保留,不允许为了省换料次数而合并; - 区域架构:按父体分割、嵌入式、凸起覆层、独立插件四种界面模式建模;区域可以共面但体积严禁重叠,合并导出的制造 STL 会剔除内部材料界面;
- 3MF 读回校验:
export_3mf.py写入共享调色板并读回 3MF XML,assembly_check.py再交叉核对区域名/颜色与构建报告一致——“对象数量对”不等于“颜色对”。
质检也分层:每个区域 STL 只做拓扑审计,Bambu 制造检查只在合并 STL 上跑一次;彩色四视图渲染仍是强制项,因为存档正确也发现不了“颜色放错位置”。
仓库内置的示例 bundled-projects/amagine3d-pomodoro/ 就是一个多色工程:外壳、灰色/橙色按键、LED 面板与橙/白像素各为独立 STL,另有 focus-bar-logical-assembly.3mf 彩色装配,可直接在工作台里预览参数。
两个 Skill 如何“协同”而不是“二选一”
它们的协同体现在三层共享底座:
- 同一套意图契约体系:
intent_contract.py、evidence-contract.md在两个 Skill 中结构一致,多色版只是多了color_regions与调色板字段(示例见 skills/text-a3d-color/examples/intent.example.json); - 同一套打印证据:两者都用
bambu_profile.py锁定机器档案哈希,禁止“为过 QA 换档案”; - 同一套验证引擎:
qa_check.py、freshness_check.py、render_preview.py、compare_silhouette.py与 skills/cpu_z_buffer.py 在两个目录中复用,保证单色与多色走同一个证据标准。
于是“协同”的实际形态是:路由阶段二选一,执行阶段共享工具链与验收口径;若单色模型后期发现颜色有语义(比如屏幕区该独立上色),Agent 会整体转入 text-a3d-color 重开证据运行,而不是给旧网格“刷层颜色”。
快速上手:自己跑一遍双 Skill 🖨️
环境要求 Node.js 20.19+ 与 Python 3.10–3.13:
git clone https://gitcode.com/gh_mirrors/am/Amagine3D
cd Amagine3D
npm install
cp .env.example .env
npm run dev
打开 http://127.0.0.1:6160 即可在 CAD 工作台里对话式生成单色/多色模型,关键尺寸会以滑块形式出现在工作区,修改后写回源码重建几何。想深入机制,建议按顺序阅读 skills/text-a3d/SKILL.md、skills/text-a3d-color/SKILL.md 和 skills/text-a3d-color/references/color-architecture.md,再看 tests/python/ 中对共享工具与多色护栏的测试,就能完整理解这套双 Skill 闭环。