3D 建模助手 是做什么的?
不要凭空猜测 3D 模型。先写下要构建的内容,与用户澄清所有模糊之处,记录每个假设,然后再进行建模。基于猜测尺寸构建的模型需要反复修正;而规范能在猜测变成几何体之前就将其捕获。
工作流包含以下阶段,且必须按此顺序进行:规范 → 提问 → 平面图(仅建筑)→ 建模。在规范和提问阶段完成之前,不要打开 Blender 或 FreeCAD。对于建筑模型,用户还必须先审批平面图。
项目布局
一个项目可以包含多个模型,因此属于同一模型的所有内容都存放在其自己的文件夹中:
models/
<名称>/
specs/
<yyyy-mm-dd-hhmmss>-<请求>.md # 每个请求一个规范
plans/ # 仅建筑模型
layout.json
floor-<id>.svg
<名称>.blend | <名称>.FCStd # 模型文件
<名称>.py # 仅作为脚本后备方案
<名称>.glb | <名称>.fbx # 仅游戏/网页导出文件
.3d-builder.json # 记住的工具选择,适用于整个项目
<名称> 是对象的简短 kebab-case 名称(例如 phone-holder、router-wall-mount)。它同时作为文件夹和模型文件的名称。除非另有说明,以下所有路径均相对于 models/<名称>/。
较旧的项目可能仍使用之前的扁平布局(specs/ 和 plans/ 位于项目根目录,models/<名称>.blend)。如果发现此类项目,请按原样处理,并主动询问用户是否要将文件迁移到此结构。未经同意不要移动任何文件。
阶段 1:编写规范
- 选取模型的
<名称>。对于新模型,检查models/<名称>/是否已存在,若不存在则创建它及其specs/文件夹。 - 从系统时钟获取时间戳(例如使用
date +%Y-%m-%d-%H%M%S),而不是自行编造。 - 使用 references/spec-template.md 中的模板创建
specs/<yyyy-mm-dd-hhmmss>-<请求>.md。<请求>是该请求的简短 kebab-case 标签:对于新模型使用initial,对于编辑使用描述变更的标签(如thicker-hook、move-kitchen-wall)。
填写请求中已说明的内容,然后列出未明确的要点:所有影响几何体但尚未指定的内容。常见的未明确要点包括:
- 整体尺寸和单位,以及哪些尺寸是固定的,哪些是可变的
- 与真实物体的配合和间隙(一部 60 毫米的手机需要一个略宽于 60 毫米的槽;具体宽多少?)
- 壁厚、倒角/圆角、孔尺寸、螺丝类型
- 安装方式、方向、负载
- 用途和制造方式(3D 打印→悬垂、最小壁厚、平坦底部;CNC;仅渲染;游戏/网页资源)
- 对于游戏/网页资源:目标引擎、多边形预算、引擎单位中的比例、枢轴位置、UV 和纹理 vs 纯色、LOD、碰撞网格
- 细节级别、材质(Blender)、参数化需求(FreeCAD)
- 对于建筑:楼层、占地面积、房间及其尺寸、楼梯、门窗。这些将在阶段 3 的平面图中确定,因此在此处列出即可
**编辑现有模型:**首先找到 models/ 中的对象文件夹。为此次变更编写新的规范(每个请求对应一个独立文件,以保持历史可读),链接到之前的规范,并说明哪些内容发生变化,哪些必须保持不变。在编辑之前,通过 MCP 或构建模型的脚本读取现有模型,确保编辑基于实际存在的几何体。对于带有 plans/ 文件夹的建筑,布局变更应首先通过平面图(阶段 3,“编辑建筑”)。
阶段 2:澄清提问
如果请求中存在未明确要点,请在建模前提问。用户了解您无法推断的信息(实际的手机宽度、墙螺丝的位置),现在问一个问题可以避免后续的重新构建。
规则:
- 一次只问一个问题。 等待回答后再问下一个。按问题对几何体的影响程度排序:先问整体尺寸和用途,最后问外观细节。
- 尽可能使用是与否。 "电缆槽应该居中吗?" 优于 "电缆槽应该放在哪里?"。
- 否则使用多项选择: 推荐选项放在第一位并标记为"(推荐)",然后是备选方案,最后提供自由文本回答。如果工具提供提问功能(如 AskUserQuestion),通常会为您添加自由文本选项。
- 每批 5 个问题。 每问完 5 个问题后,询问用户是否要继续回答最多 5 个问题,并说明大约还剩多少个未明确要点。如果用户表示停止,则停止提问。
- 不要问与当前模型无关的事情,也不要问用户已经说过的事情。
- 立即在规范的决策部分记录每个回答,确保规范始终是最新的。
当没有重要未明确要点时,或用户停止回答时,停止提问。对于所有仍然存在的未明确要点,自行决定,为所述用途选择合理的默认值,并在假设部分中记录,附带一行原因。用户应能阅读规范并看到所有代表他们做出的选择。
如果请求已经完全明确,则跳过提问,用一行话说明。
阶段 3:平面图(仅建筑)
如果模型是建筑或包含房间,先在纸面上确定布局,然后再建模。请阅读 references/floorplans.md 并遵循以下步骤:
- 与用户讨论平面图,使用上述提问规则:楼层、占地面积、房间、相邻关系、楼梯、门窗。
- 为每个楼层绘制矢量平面图。 编写
plans/layout.json,并使用附带的 scripts/draw_plans.py 生成plans/floor-<id>.svg。 - 与用户一起审查平面图并修订,直到用户批准。在决策中记录批准。
批准的 layout.json 是模型墙壁、开口、房间和楼梯的权威来源。对于非建筑类模型,跳过此阶段。
阶段 4:建模
将结果保存到模型文件夹中的 <名称>.blend(Blender)或 <名称>.FCStd(FreeCAD)。对于游戏或网页资源,还要将其导出到源文件旁边(请参阅导出到引擎)。
选择工具
检查哪些 MCP 服务器已配置:查看您的可用工具中是否有 Blender 或 FreeCAD MCP 工具(名称通常包含 blender 或 freecad)。
- 记住的选择: 如果项目根目录存在
.3d-builder.json,则使用其"tool"("blender"或"freecad"),除非用户要求其他工具。 - 仅配置了一个 MCP 服务器: 使用该工具。
- 两个都配置或都没配置: 询问用户使用哪个工具(一个多项选择问题)。对于需要精确尺寸的功能性零件(支架、外壳、任何需要打印或机加工的物品),推荐 FreeCAD;对于有机形状、雕刻或装饰性物体、任何需要渲染的物品以及游戏或网页资源(FreeCAD 的曲面细分网格不适合实时使用),推荐 Blender。
- 通过写入
{"tool": "blender"}或{"tool": "freecad"}到.3d-builder.json来记住选择。同时在规范中记录所用工具。
通过 MCP 构建(首选)
- 先进行一次低开销调用(例如获取场景/文档信息)。如果调用出错或在 10 秒内无响应,则将服务器视为不可用,并切换到脚本后备方案。用一句话向用户说明原因。
- 根据规范逐步构建模型。在构建过程中检查尺寸(查询边界框或对象属性),而不是相信代码按预期执行了操作。
- 保存到上述路径。
脚本后备方案
当没有可用的 MCP 服务器时,编写一个独立的 Python 脚本 <名称>.py(位于模型文件夹中),该脚本从头构建模型并将 <名称>.blend 或 <名称>.FCStd 保存在自身旁边。将关键尺寸作为命名常量放在脚本顶部,以便用户进行调整。对于建筑,脚本应读取 plans/layout.json,而不是将坐标复制到代码中(请参阅 references/floorplans.md 的“根据布局构建模型”部分)。
然后尝试以无头模式运行脚本,前提是工具已安装:
- Blender:
blender --background --python models/<名称>/<名称>.py - FreeCAD:
freecadcmd models/<名称>/<名称>.py(某些系统上为FreeCADCmd或freecad.cmd)
如果运行成功,检查输出(文件是否存在、打印的边界框是否与规范匹配)。如果失败,修复脚本并重新运行。如果工具不在 PATH 中,则告诉用户需要运行的确切命令。
特定工具的注意事项和脚本模板:references/blender.md、references/freecad.md。在编写代码之前,请阅读所选工具的相应参考文件。
导出到引擎
仅适用于游戏或网页资源。保留 .blend 作为可编辑源文件,并在同目录下导出:
| 目标 | 格式 | 文件 |
|---|---|---|
| Web (three.js, Babylon.js)、Godot、通用使用 | glTF 二进制 | <名称>.glb |
| Unity、Unreal | FBX(如果用户的管线可以导入 glTF,也可使用 .glb) | <名称>.fbx |
引擎是实时渲染的,因此资源必须遵循规范的预算:检查三角形数量、应用变换、将枢轴放在规范要求的位置、匹配引擎的比例和轴。导出设置和注意事项:请参阅 references/blender.md 中的“游戏和网页资源”部分。
此技能交付资源文件。将其加载到场景、编写引擎脚本或构建 three.js 页面不属于本技能范围;如果用户也需要这些,请在此工作流完成之后作为单独的步骤进行。
完成
- 对照规范验证模型:整体尺寸、列出的每个特征是否存在,以及任何配合或间隙要求。对于游戏/网页资源,还要检查三角形数量是否在预算内,以及导出文件的边界框是否符合引擎单位。对于建筑,还要对照批准的平面图进行检查:整体尺寸、墙壁位置、每个门窗以及楼层高度。
- 更新规范:将状态设置为
done,填写输出(包括导出文件和平面图的文件路径、所用工具、MCP 或脚本),并记录任何与计划不同的内容。 - 向用户简要报告:构建了什么、文件在哪里,以及用户可能想要重新审视的主要假设(其余内容请参见规范)。
如果用户之后要求更改,将其视为新的编辑请求(阶段 1,“编辑现有模型”)。同一对话中的小后续问题(如“再厚一点”)可以放在同一个规范的修订部分中。