Amagine3D双Skill机制揭秘:text-a3d与text-a3d-color如何协同完成单色与多色CAD

原创2026-09-22 20:58:171,353 阅读

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 目录都是自包含的:一份 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 的流程核心是“先立标,后做模型”,每一步都有脚本背书:

  1. 开立可追溯的运行:用 freshness_check.py 打时间标记,解析固定的 Bambu 机器/喷嘴/工艺档案(bambu_profile.py),有参考图时先跑 reference_analyze.py 提取哈希、边界与像素证据;
  2. 写意图契约:按 skills/text-a3d/references/evidence-contract.md 生成 intent.json(尺寸来源、隐藏面假设、关键特征 ID、支撑策略),用 intent_contract.py 校验——契约先于几何,且不许事后弱化;
  3. 参数化建模:用 build123d 写完整脚本,所有关键尺寸通过 parameter() 暴露成工作区滑块,切割/圆角等操作走 fail-closed 封装(cad_helpers.py);
  4. 几何与外观双重证明:qa_check.py 做网格审计、打印床适配、壁厚、悬垂检查;需要外观还原时,用 skills/cpu_z_buffer.py 纯 CPU 渲染四视图并做哈希绑定,无需 GPU;
  5. 按失败证据类修复:尺寸失败改参数、轮廓失败改包络、薄壁加厚、悬垂改朝向——最多三轮修复,且禁止调低打印档案极限来“蒙混”QA;
  6. 新鲜度门禁 + 交付: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 闭环。

登录后查看全文
Amagine3D