text-to-blender

文本转 Blender 编排器

将通俗英文请求转化为 Blender 作品。你是指挥者：阅读请求，决定要串联加载哪些子技能，按正确顺序安排，并通过 Blender MCP 执行。

多技能协调

对于会触发多个 Blender 技能的复杂任务，尤其是参考图／模板／品牌相关工作，在选择执行顺序前先加载 blender-skill-harmonizer。它负责处理优先级、交接产物和冲突策略。

如果用户认为输出不够好、表示同一问题反复出现，或要求先改进技能栈再重试，则应在继续产品工作前加载 quality-refinement-autoloop。它会将证据转化为经过清理、可复用的经验；仅在用户明确要求时，才修补通用技能／文档／版本管理，然后再恢复 Blender 修复循环。

此技能的工作方式

用户会用任务描述提出需求（“渲染一张石头上的剑的主视觉图”）；你需要：

1. 识别意图 → 需要哪些能力（建模？材质？照明？渲染？导出？）。
2. 检查先决条件 → MCP 服务是否可连接、场景状态如何。
3. 重置世界为已知的良好基线（参见下文的世界重置）——防止先前运行遗留的损坏 HDRI／环境纹理节点破坏渲染。
4. 查询对象的现实尺寸（references/common-object-dimensions.md），然后再生成 Python。剑有特定的比例，椅子也有特定的比例；不要猜测。
5. 路由到子技能 → 通过 Read 加载相关技能，并遵循其说明。
6. 安排顺序 → 按照专业人士常用的顺序开展工作（参见 references/assembly-order.md）。
7. 执行 → 通过 mcp__blender__execute_blender_code 执行生成的 Python。
8. 验证 → 使用 mcp__blender__get_scene_info、get_object_info 和 get_viewport_screenshot——参见下文的视觉验证检查点。仅靠数值验证并不足够：即使几何体严重错误，API 仍可能报告成功。
9. 迭代 → 如果视觉检查发现明显问题（主体几乎不可见、比例错误、方向不对），应先修复并重新渲染，再报告成功。
10. 向用户汇报 → 提供具体数值，并给出可供用户查看的证明渲染文件路径。

世界重置（始终作为步骤 3，在任何构图之前执行）

先前的测试可能会让场景的世界处于损坏状态——特别是 Environment Texture 节点的 image=None，并连接到 Background 节点时，会导致渲染画面被洋红色淹没。每次构建场景时，都要在开始时将世界重置为中性基线：

def reset_world(scene, color=(0.04, 0.04, 0.05, 1.0), strength=0.4):
    world = scene.world
    world.use_nodes = True
    nodes = world.node_tree.nodes
    for n in list(nodes):
        nodes.remove(n)
    output = nodes.new('ShaderNodeOutputWorld')
    bg = nodes.new('ShaderNodeBackground')
    bg.inputs['Color'].default_value = color
    bg.inputs['Strength'].default_value = strength
    world.node_tree.links.new(bg.outputs['Background'], output.inputs['Surface'])

如果用户需要 HDRI 照明，请在此步骤运行后覆盖设置（加载实际的 .hdr 文件，并验证 env.image is not None）。

视觉验证检查点（始终在步骤 8 和 10 之间执行）

渲染后，务必：

1. 调用 mcp__blender__get_viewport_screenshot（或使用 Read 读取渲染文件）。
2. 根据用户的请求进行视觉验证。具体检查：
   • 主体清晰可见且易于辨认（不是一道细线、没有被洋红色淹没，也没有完全陷入阴影）
   • 比例符合该主体的现实尺寸参考
   • 构图合理（主体位于画面内、没有被边缘裁切，也没有缩在某个角落，显得微乎其微）
   • 材质呈现出可见的变化（表面不是完全平坦、像塑料一样）——对于达到生产质量的场景，应添加程序化纹理节点
3. 如果渲染明显有误，切勿报告成功。继续迭代：找出具体问题、进行修复、重新渲染并再次检查。

即使渲染通过所有数值检查（对象数量、顶点数量、文件大小、没有错误消息），画面看起来仍可能完全不对。用户看到的只有图像。宣布完成前，务必确保画面符合用户的请求。

将视口设为材质预览模式（汇报前的最后一步）

用户通常看到的是 Blender 的视口，而不是渲染出的文件。Blender 默认将视口设为实体着色模式，该模式会忽略所有材质，并将所有内容显示为纯灰色。场景组装完成后，将视口切换到材质预览模式，让用户实际看到所获得的材质：

import bpy

for area in bpy.context.screen.areas:
    if area.type == 'VIEW_3D':
        for space in area.spaces:
            if space.type == 'VIEW_3D':
                space.shading.type = 'MATERIAL'           # or 'RENDERED' for full quality
                space.shading.use_scene_lights = True
                space.shading.use_scene_world = True

仅当用户明确要求不要更改视口时才跳过此步骤。

真实世界尺寸查询

在根据自然语言为任何主体设定尺寸之前，请先查阅 references/common-object-dimensions.md。其中列出了常见需求的现实比例：

主体	总尺寸	备注
单手剑	长约 95-100 cm	剑刃 78cm × 4.5cm × 0.8cm；护手 20cm × 2.5cm；握柄 13cm；剑首 5.6cm
椅子	座面约 45cm × 45cm × 4cm	座面高度 45cm；靠背高约 45cm
瓶子	高 25-30cm	瓶身 ø8-10cm；瓶颈 ø2-3cm

完整参考列表见 references/common-object-dimensions.md。不要猜测。

前置条件 — 务必先检查

开始任何工作之前，请确认：

1. Blender MCP 可访问。调用 mcp__blender__get_scene_info。如果返回错误 "Could not connect to Blender"：

   "Blender 的 MCP 插件未运行。请启动 Blender，启用 BlenderMCP 插件（默认端口为 9876），然后重新运行。"

   停止操作并请用户解决此问题。

2. 场景状态。get_scene_info 会返回当前对象。判断：

   • 场景为空？ → 从头开始；使用基本体构建。
   • 存在对象？ → 在现有对象上操作；除非用户提出要求，否则不要删除。
   • 只有默认立方体？ → 通常可以安全删除（bpy.ops.object.delete()）。

3. 用户的实际需求。如果含义不明确，请提一个问题。否则采用合理的默认设置继续操作。

意图 → 子技能路由表

针对用户表达的每种意图，加载（通过 Read）对应子技能的 SKILL.md 并遵循其中的模式。涉及多种意图时，依次使用多个子技能。

用户意图（释义）	加载这些子技能	顺序
“制作一个 X 的 3D 模型”	blender-modeling	第 1 步
“根据这张线框图制作”	wireframe-to-3d	第 1 步
“使用这些材质 / 让它看起来像 X”	blender-materials	建模后
“打光 / 搭建摄影棚 / 营造电影感”	blender-lighting	几何体创建后
“主视觉镜头 / 相机角度 / 景深”	blender-cameras	灯光后
“渲染 / 生成图像”	blender-rendering	最后的视觉步骤
“制作动画 / 随时间移动 / 旋转”	blender-animation	几何体创建后
“导出为 glTF / FBX / OBJ / 用于 Web / 用于 Unity”	blender-export	最后一步
“搭建场景 / 制作专业品质的成果”	blender-pro-workflow	第 1 步 — 指导整体流程
“我是新手 / 不确定从哪里开始”	blender-pro-workflow	第 1 步
“质量不佳 / 还是不对 / 同样的问题又出现了”	quality-refinement-autoloop，然后是 blender-skill-harmonizer	第 1 步 — 学习、清理、修补，然后重试
“精确匹配这些模板 / 线框 / 纹理”	blender-skill-harmonizer，然后是特定参考对象的适配技能	第 1 步 — 建立事实依据关卡

多意图示例：“制作一把带材质的剑，使用戏剧性灯光，并导出为 glTF” →

1. blender-pro-workflow（流程排序策略）
2. blender-modeling（剑的几何结构）
3. blender-materials（钢材 + 皮革握柄）
4. blender-lighting（戏剧性的单点布光或轮廓光设置）
5. blender-export（glTF 设置）

专业装配顺序（不确定时）

此顺序可最大限度减少返工。用户提出多步骤请求时，请按此顺序执行：

1. 参考 + 计划 — 记录目标。
2. 粗模 — 基础几何体 + 摄像机 + 构图。迭代成本最低。
3. 锁定摄像机 — 选择焦距，构好画面。
4. 灯光 v1 — 在处理材质前先布置三点光（主光／补光／轮廓光）。灯光决定氛围。
5. 完善几何体 — 用真实模型替换基础几何体。
6. 材质 v1 — 先用纯色，确保明暗关系正确。
7. 灯光 v2 — 调整颜色 + 比例。
8. 细节处理 — 仅在上述内容正确后进行。
9. 最终渲染 — 使用生产级采样 + 降噪。
10. 合成 — 调色、辉光、暗角。
11. 导出 — 导出到目标平台。

来源：references/assembly-order.md（更深入的说明）。

代码执行规则——必须遵守

生成用于 mcp__blender__execute_blender_code 的 Python 代码时：

• 每次调用都会使用全新的命名空间。 只有 bpy 已预先导入；每次调用都要重新导入 math、bmesh、numpy 等。
• 使用稳定名称识别对象，绝不要使用 Python 变量。bpy.data.objects['GEO-sword'] 可跨调用使用；sword = ... 赋值则不行。
• 打印结构化输出，以便解析结果。每段代码末尾都要用 print(f"...") 报告变更内容（对象名称、顶点数、文件路径）。
• 分块处理。 每次调用的超时时间为 180 秒。不要一次塞入 500 行代码，应拆分为约 5–20 行的小段。
• 所有新建内容均使用 Blender Studio 命名规范： GEO-、MAT-、LGT-、CAM-、ARM-、COL-。绝不要保留 Cube.027 这样的名称。

每项操作的标准骨架

import bpy
# (re-import other modules here as needed)

# 1. Scope: identify or create objects by NAME
obj = bpy.data.objects.get('GEO-target') or bpy.data.objects.new('GEO-target', None)

# 2. Do the work
# ...

# 3. Report
print(f"done:GEO-target {len(obj.data.vertices) if obj.data else 0}")

命名规范（适用于所有新建内容）

前缀	含义
GEO-	几何体／网格对象
MAT-	材质
LGT-	灯光
CAM-	摄像机
ARM-	骨架（绑定）
COL-	集合
WGT-	自定义骨骼形状／控件

左右两侧使用后缀 .L / .R。示例：GEO-sword_blade、MAT-steel_brushed、LGT-key。

验证经验法则

完成重要工作后，调用 mcp__blender__get_scene_info 并确认：

• 预期对象均存在，且名称正确。
• 对象数量合理（没有失控地重复创建）。
• 多边形数量大致符合目标。

在报告渲染或导出成功前，确认文件确实存在（使用 Bash：ls -la /path/to/output）。

何时加载更深入的参考资料

• references/assembly-order.md — 标准场景装配顺序、时间预算和恢复模式。规划多步骤工作流或用户询问“正确顺序是什么？”时加载。
• references/intent-routing.md — 更完整的意图到技能映射及边缘情况。请求含糊、需要消除歧义时加载。
• references/code-execution-rules.md — 关于 execute_blender_code 的详细规则（命名空间、超时时间、标准输出捕获）。排查执行错误时加载。

向用户汇报

完成工作后，具体说明：

• ✅ 已创建：列出对象 + 多边形数量。
• ✅ 已布光：列出灯光 + 各自作用。
• ✅ 已渲染：文件路径 + 大小 + 尺寸 + 渲染耗时。
• ⚠️ 警告：自动简化、命名冲突、备用材质等情况。

示例：

已创建 GEO-sword_blade（1 240 个顶点）、GEO-sword_grip（320 个顶点）。
材质：MAT-steel_brushed、MAT-leather_dark。
使用 LGT-key（暖色 3200K）、LGT-fill（冷色 5500K）、LGT-rim（冷蓝色）布光。
已渲染至 /tmp/sword_hero.png（1920×1080，2.3 MB，使用 256 个采样并启用 OptiX 降噪，耗时 38 秒）。

故障模式——遇到以下情况时该怎么做……

问题	操作
MCP 超时	将失败的部分拆分成更小的部分
Code execution error: <line>	查看错误；修复对应的那一行；重试
下一次调用中找不到对象	你使用了 Python 变量，而不是 bpy.data.objects['name']
渲染耗时过长	减少采样数，启用自适应采样，降低分辨率
文件不在预期路径	使用绝对路径；用 Bash ls 验证
导出后材质看起来不对	你使用了非 Principled-BSDF 节点；仅使用 Principled 重建材质
'Action' object has no attribute 'fcurves'	Blender 5.x 使用分层 Actions；改为遍历 action.layers[].strips[].channelbags[].fcurves。兼容性辅助函数见 blender-animation Recipe 3。
BLENDER_EEVEE_NEXT 被拒绝	Blender 5.x 将其名称改回了 BLENDER_EEVEE。带有 try/except 回退的代码见 blender-rendering Recipe 3。
KeyError: 'Subsurface IOR'（或其他输入名称）	Blender 5.x 将某些 BSDF 输入标记为 enabled=False（目前包括 Weight、Subsurface IOR）；这些输入可以通过遍历访问，但无法通过字符串键查找。set_input 辅助函数见 blender-materials Recipe 9。
Error: Cannot render, no camera	scene.camera is None。任何渲染前都务必运行 ensure_camera() 保护检查——参见 blender-rendering Recipes 5 / 6。即使用户的提示词没有明确要求相机，编排器在衔接到渲染前也必须进行此检查。
用户查看 Blender 视口时报告“场景是灰色的／看不到材质”	Blender 视口默认使用 Solid 着色模式，该模式会忽略材质。渲染结果是正确的；只有视口看起来是灰色的。每次组装场景后，都将视口设置为材质预览：space.shading.type = 'MATERIAL'; space.shading.use_scene_lights = True; space.shading.use_scene_world = True
用户报告“材质看起来很平／没有纹理”	平坦的 PBR 颜色缺少表面变化。添加程序化纹理（Noise/Voronoi → ColorRamp → Roughness 或 Bump），用于表现钢材划痕、锤纹金属、皮革纹理等。模式参见 blender-materials Recipe 12（程序化木材）。
主体比例看起来不对（例如刀刃太短、椅子太窄）	编排器跳过了尺寸查询。生成建模代码前，务必先阅读 references/common-object-dimensions.md。不要猜。
用户要求制作“人类”／“角色”／“面孔”／“人物”	纯配方基元只能生成可辨认的轮廓，无法生成真正的人脸。建议选择以下方案之一：(a) 使用 mcp__blender__download_polyhaven_asset / download_sketchfab_model / generate_hyper3d_model_via_text 获取真实的人体基础网格，然后衔接材质、灯光和渲染；(b) 聘请 Blender 角色艺术家（参见 prompts/04-blender-workflow.md）。不要假装带有五官的球体看起来像人——它并不像。参见 references/common-object-dimensions.md 中的“Characters / avatars”部分。
细长主体渲染成细杆，而不是可辨认的形状	相机正对着细长物体的细轴。旋转物体，使其宽轴朝向相机。参见 blender-modeling 中的“Critical: axis orientation for elongated objects”。
刀刃／尖刺的尖端是“凿平的”，而不是尖的	顶部顶点缩放到了接近零，但没有合并。使用 blender-modeling 中正确的收尖配方（“Critical: tapering to a point”）——将顶部顶点合并到中心线上，并执行 remove_doubles。
彩色玻璃渲染成平坦的金属质感，而不是“玻璃质感”	只在 Principled BSDF 的 Base Color 上设置了色调。真实的彩色玻璃需要使用 Volume Absorption 实现基于深度的色调。参见 blender-materials Recipe 6b。另外：Roughness=0.0 会产生镜面般平坦的高光，看起来像金属——请改用 0.02–0.05。
玻璃内部渲染为黑色	transmission_bounces 设置得太低。默认值 12 对厚玻璃或多层玻璃来说不够。设置 scene.cycles.transmission_bounces = 24。

此技能不适用于

• 大量自定义 GPU 工作／编写渲染引擎（请使用 Blender 现有的引擎）
• 实时游戏逻辑（请直接使用 Unity／Unreal）
• 根据自然语言进行雕刻（雕刻是手势操作；请交互式地使用笔刷）
• Blender 能力范围之外的事项（CAD 精密建模——请使用 FreeCAD；CFD 仿真——Blender 的 Mantaflow 仅适用于 VFX 级效果，不适用于工程用途）

遇到用户提出这些需求时，请礼貌地引导他们选择其他方案并作出说明。