| name | blender-modeling |
| description | 用 Blender 无头模式（bpy Python 脚本）程序化建模 3D 资产，通过"渲染 → 视觉看图 → 迭代"闭环验证效果，导出 glb 等格式，并把脚本、效果图、模型和 README 按约定归档。当用户要求建模 3D 模型（装置、道具、场景物件等）或导出 3D 资产时使用。项目特定的尺寸/朝向/归档路径约定由项目级 skill 补充。 |
Blender 无头建模
核心方法：建模完全程序化（bpy 脚本），每轮修改后无头渲染出图、用视觉能力检查、再改脚本，形成"渲染 → 看图 → 迭代"闭环。参考实现见 reference/make_belt.py（完整可跑的示例脚本）。
环境
- 先确认版本：
blender --version。一切通过 blender --background --python <script> 无头执行，不操作 GUI。
- 适合参数化、规则几何体（机械、建筑、道具）；有机形体雕刻是弱项，需用户给参考图并降低预期。
Blender 5.x 坑点（实测）
- Blender 是 Z-up，glTF/游戏引擎多为 Y-up：脚本内按 Blender 坐标建模，导出时用
export_yup=True 转换。
- 中文 locale 下节点显示名被翻译（如"原理化 BSDF"），按
bl_idname 查找：ShaderNodeBsdfPrincipled、ShaderNodeBackground。socket 输入名仍是英文（Base Color、Metallic、Roughness、Emission Color、Emission Strength）。
- EEVEE 引擎标识：
BLENDER_EEVEE_NEXT，try/except 回退 BLENDER_EEVEE。
- 需要精确角度的小零件（如拼箭头的方条）用欧拉角旋转容易出错且难排查——优先直接构造网格顶点（
mesh.from_pydata）。
- 硬表面风格：
BEVEL 修改器（width 0.01–0.03，segments 2）+ shade_smooth（圆柱）即可出效果。
工作流程
- 明确规格：向用户确认或在项目约定里查：占地/尺寸、朝向约定、风格、目标格式和接入位置。
- 写脚本：在
/tmp/<proj>_<name>/make_<name>.py 写完整脚本：清场 → 材质 → 建模 → 灯光（SUN 主光 + AREA 补光 + 微亮环境背景）→ 正交相机（斜 45°，TRACK_TO 约束对准模型中心）→ 渲染 → 导出。脚本内输出路径用绝对路径。
- 渲染-看图-迭代：跑脚本，用 ReadMediaFile 看渲染图，检查穿模/比例/朝向/光影/构图，改脚本重跑直到满意。要点：
- 四张图：斜 45°
preview.png（整体效果）+ 三视图（均正交）：front.png（沿主朝向轴正视）、side.png（侧视）、top.png（俯视，验证朝向与布局）。
- 细节存疑时用 ReadMediaFile 的 region 参数裁局部看原生分辨率。
- 每次生图后立即读回检查，不要假设效果。
- 导出：
bpy.ops.export_scene.gltf(filepath, use_selection=True, export_yup=True, export_apply=True)，只选中模型部件（排除灯光相机）。
- 接入验证：接入目标项目后，跑项目自身的测试/构建验证资产能正常加载。
产出归档约定
建模完成后，把产出整理到一个目录（位置由项目约定或用户指定，如 Obsidian Vault 的 Models/<中文名>/）：
Models/<名称>/
├── make_<name>.py # 建模脚本（最终版）
├── <name>.glb # 模型文件（与项目内使用的一致）
├── preview.png # 斜 45° 效果图
├── front.png # 正视图（正交）
├── side.png # 侧视图（正交）
├── top.png # 俯视图（正交，验证朝向与布局）
└── README.md
README 固定章节：
- 文件清单：表格列出各文件用途
- 效果图：嵌入 preview 和三视图全部四张图，以 2×2 网格展示（左上 preview、右上 front、左下 side、右下 top），网格下注明各格内容；支持表格的环境（Obsidian、标准 Markdown）用表格内嵌图片实现，不支持的用等效排版
- 用法：复现命令（
blender --background --python ...），提示脚本内绝对路径需按环境修改
- 模型描述：规格（尺寸/朝向）、结构分解（逐部件含材质参数）、风格
- 设计思路：对齐了哪些约定、设计取舍
- 迭代过程：逐轮记录"问题 → 修复"——这是最有价值的资产，供后续建模参考
- 验证：接入点、测试/构建结果
- 已知边界 / 后续可做
README 的格式和图片引用语法随归档位置的惯例而定，不假设是标准 Markdown：Obsidian Vault 用 ![[preview.png]] 嵌入；普通 Markdown 仓库用 ；其他环境（AsciiDoc、Typst 文档等）用对应语言的图片语法。
若归档目标是 Obsidian Vault，遵守该 Vault 的 AGENTS.md（AI 生成内容带 yyyy-mm-dd 标题 (tool, 完整模型名) 标记章节、日期章节降序、不擅自改写用户内容、不擅自 git 提交）。
