Community编程与开发github.com

3D 建模助手

通过规范驱动的方式,在 Blender 或 FreeCAD 中创建和编辑 3D 模型。将所有模型文件统一保存在 models/<name>/ 目录下,记录规范文件,逐一提问澄清,并保存所有决策和假设。

3D 建模助手 是什么?

该技能实现了一种规范驱动的 3D 建模工作流,首先编写详细的规范(spec)文件,然后通过一问一答的方式澄清所有模糊点,记录每个决策和假设。对于建筑模型,还会绘制每层的 SVG 平面图供用户审批。最后,通过 Blender/FreeCAD 的 MCP 服务器或自动生成的 Python 脚本构建模型,并将所有输出文件(包括 .blend/.FCStd、glb/fbx 导出文件)保存到同一目录。 技能支持 Blender 和 FreeCAD 两大工具,并能智能选择:对于需要精确尺寸的功能性零件推荐 FreeCAD,对于有机形状、渲染或游戏资源推荐 Blender。支持从零创建新模型,也支持编辑现有模型——编辑时会先读取现有文件,确保修改基于实际几何体。 工作流严格按照“规范 → 提问 → 平面图(仅建筑)→ 建模”的顺序执行,避免在规范明确之前就打开建模工具。每次请求对应一个独立的规范文件,完整保留修改历史。最终还会对模型进行验证,确保所有尺寸、特征和导出要求都符合规范。

兼容平台~Claude Code~Codex CLI~Cursor
Part ofMobile
npx skills add https://github.com/thanikc/3d-builder/tree/HEAD/skills/3d-builder

Installed? Explore more 编程与开发 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

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:编写规范

  1. 选取模型的<名称>。对于新模型,检查 models/<名称>/ 是否已存在,若不存在则创建它及其 specs/ 文件夹。
  2. 从系统时钟获取时间戳(例如使用 date +%Y-%m-%d-%H%M%S),而不是自行编造。
  3. 使用 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 并遵循以下步骤:

  1. 与用户讨论平面图,使用上述提问规则:楼层、占地面积、房间、相邻关系、楼梯、门窗。
  2. 为每个楼层绘制矢量平面图。 编写 plans/layout.json,并使用附带的 scripts/draw_plans.py 生成 plans/floor-<id>.svg。
  3. 与用户一起审查平面图并修订,直到用户批准。在决策中记录批准。

批准的 layout.json 是模型墙壁、开口、房间和楼梯的权威来源。对于非建筑类模型,跳过此阶段。

阶段 4:建模

将结果保存到模型文件夹中的 <名称>.blend(Blender)或 <名称>.FCStd(FreeCAD)。对于游戏或网页资源,还要将其导出到源文件旁边(请参阅导出到引擎)。

选择工具

检查哪些 MCP 服务器已配置:查看您的可用工具中是否有 Blender 或 FreeCAD MCP 工具(名称通常包含 blender 或 freecad)。

  1. 记住的选择: 如果项目根目录存在 .3d-builder.json,则使用其 "tool"("blender" 或 "freecad"),除非用户要求其他工具。
  2. 仅配置了一个 MCP 服务器: 使用该工具。
  3. 两个都配置或都没配置: 询问用户使用哪个工具(一个多项选择问题)。对于需要精确尺寸的功能性零件(支架、外壳、任何需要打印或机加工的物品),推荐 FreeCAD;对于有机形状、雕刻或装饰性物体、任何需要渲染的物品以及游戏或网页资源(FreeCAD 的曲面细分网格不适合实时使用),推荐 Blender。
  4. 通过写入 {"tool": "blender"} 或 {"tool": "freecad"} 到 .3d-builder.json 来记住选择。同时在规范中记录所用工具。

通过 MCP 构建(首选)

  1. 先进行一次低开销调用(例如获取场景/文档信息)。如果调用出错或在 10 秒内无响应,则将服务器视为不可用,并切换到脚本后备方案。用一句话向用户说明原因。
  2. 根据规范逐步构建模型。在构建过程中检查尺寸(查询边界框或对象属性),而不是相信代码按预期执行了操作。
  3. 保存到上述路径。

脚本后备方案

当没有可用的 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、UnrealFBX(如果用户的管线可以导入 glTF,也可使用 .glb)<名称>.fbx

引擎是实时渲染的,因此资源必须遵循规范的预算:检查三角形数量、应用变换、将枢轴放在规范要求的位置、匹配引擎的比例和轴。导出设置和注意事项:请参阅 references/blender.md 中的“游戏和网页资源”部分。

此技能交付资源文件。将其加载到场景、编写引擎脚本或构建 three.js 页面不属于本技能范围;如果用户也需要这些,请在此工作流完成之后作为单独的步骤进行。

完成

  1. 对照规范验证模型:整体尺寸、列出的每个特征是否存在,以及任何配合或间隙要求。对于游戏/网页资源,还要检查三角形数量是否在预算内,以及导出文件的边界框是否符合引擎单位。对于建筑,还要对照批准的平面图进行检查:整体尺寸、墙壁位置、每个门窗以及楼层高度。
  2. 更新规范:将状态设置为 done,填写输出(包括导出文件和平面图的文件路径、所用工具、MCP 或脚本),并记录任何与计划不同的内容。
  3. 向用户简要报告:构建了什么、文件在哪里,以及用户可能想要重新审视的主要假设(其余内容请参见规范)。

如果用户之后要求更改,将其视为新的编辑请求(阶段 1,“编辑现有模型”)。同一对话中的小后续问题(如“再厚一点”)可以放在同一个规范的修订部分中。

相关技能