Blender Ai Mcp

blender-ai-mcp

警告

项目已停止 — 此仓库不再维护。 blender-ai-mcp 将不再继续开发。它将由一个全新的、显著更好的解决方案取代：具备强得多的 3D 场景理解能力，与 Blender 的协作更深入可靠，工作流控制也出色得多，等等。新的插件即将发布。

面向生产环境的 Blender MCP 服务（已归档）。

blender-ai-mcp 让 Claude、ChatGPT、Codex 及其他 MCP 客户端通过稳定的工具 API 控制 Blender，而不必临时生成 Python 代码。这样能为实际建模工作提供更安全、更精简、更可靠的操作界面：目标优先的路由、精心筛选的公开工具、确定性的检查，以及无需猜测的验证。

为何创建此项目

大多数“AI + Blender”方案仍要求模型编写原始 bpy 脚本。而在生产工作变得复杂时，这种做法恰恰会遇到问题：

1. Blender API 会随着版本变化。
2. 如果活动对象、模式或选区不正确，依赖上下文的操作器就会失败。
3. 原始脚本出错时提供的反馈很有限。
4. 视觉模型可以描述结果，但不能将其作为最终依据。

blender-ai-mcp 采用了相反的做法：将 Blender 控制视为产品能力，而不是代码生成把戏。

为何选择此 MCP 服务，而非原始 Python

• 稳定的契约，而非脚本合成。 模型使用经过验证的参数调用工具，而不是临时编写 Blender 代码。
• 目标优先的编排。 常规引导式会话从 router_set_goal(...) 开始，因此系统在调用底层操作前，就知道模型要构建什么。
• 精简的公开接口。 默认的 llm-guided 配置仅开放精简的、以搜索为先的引导层，而不是将整个运行时工具清单都交给模型。
• 事实优先的验证。 检查、测量和断言工具负责确定 Blender 中的实际状态。
• 安全的执行边界。 Blender 插件在 Blender 主线程上执行操作，而 MCP 服务负责路由、验证、发现和结构化响应。

产品方法

TASK-113 中明确提出的业务理念很简单：

• 原子工具是实现基础。它们保持小巧、精准，通常不会出现在常规的公共界面中。
• 宏工具是面向大模型、用于执行有意义的任务级工作的首选层。
• 工作流工具是范围明确的多步骤流程工具，带有明确的报告机制，而不是开放式的“什么都能做”端点。
• 目标优先的编排让会话围绕当前意图展开，而不是让模型在每一轮都重新发现上下文。
• 视觉辅助理解，而确定性测量和断言则提供最终的事实依据。
• 可插拔视觉运行时现在支持本地 MLX，以及外部 OpenRouter 和 Google AI Studio / Gemini 提供方路径，并针对不同模型系列提供外部契约配置文件，以处理提示词、架构和解析器行为。

这些特性让项目从“通过 MCP 暴露 Blender 工具”转变为适用于建模流水线的实用 AI 控制产品。

面向 LLM 的引导式公共界面

llm-guided 是默认的、面向生产环境的界面。它有意保持精简、以搜索为先，并围绕目标感知型会话进行设计。

常规引导流程：

1. router_set_goal(...)
2. browse_workflows、search_tools 或 call_tool
3. 使用分组式公共工具，例如 check_scene、inspect_scene 或 configure_scene
4. 通过检查以及 scene_measure_* 和 scene_assert_* 进行验证

提示规则：

• 使用 _docs/_PROMPTS/README.md 中的提示词库资源，作为规范的引导式操作说明
• 如果客户端偏离流程，先添加 guided_session_start，作为通用的、以搜索为先的稳定器
• 如果某个工具当前尚未直接显示在当前界面／阶段中，请先使用 search_tools(...)，再调用 call_tool(...)

当某个范围明确的建模意图与宏层匹配时，默认的公共工作层应为宏层：

• macro_cutout_recess 用于创建凹槽、开口和由切割体驱动的切口
• macro_relative_layout 用于对齐、放置和设置部件布局中的接触间隙
• macro_attach_part_to_surface 用于将一个部件置于另一对象的表面或实体上
• macro_align_part_with_contact 用于对几乎贴合的部件对进行最小幅度的修正
• macro_place_symmetry_pair 用于围绕明确指定的镜像平面放置或修正镜像部件对
• macro_place_supported_pair 用于将镜像部件对放置或修正到同一个支撑面上
• macro_cleanup_part_intersections 用于在不进行自由形式碰撞求解的情况下，有界地清理部件之间的重叠
• macro_adjust_relative_proportion 用于在相关对象之间有界地修正比例
• macro_adjust_segment_chain_arc 用于有界地调整有序线段链中的弧线
• macro_finish_form 用于通过预设驱动的倒角、细分和实体化完成造型
• reference_images 用于在进行有界视觉比较前，按目标收集参考图像
• reference_guided_creature_build 是一项原生提示词资源，用于在 llm-guided 上分阶段进行通用生物建模
• recommended_prompts 现在可以利用当前目标／会话上下文，引导面向生物建模的引导式会话使用该提示词路径
• router_set_goal、router_get_status 和分阶段参考图比较／迭代载荷现在提供 guided_reference_readiness，让客户端了解基于参考图的阶段工作是否已就绪
• reference_compare_stage_checkpoint 用于在手动迭代过程中，根据附加参考图确定性地进行多视图阶段比较
• reference_iterate_stage_checkpoint 用于执行具备会话上下文的分阶段修正循环，能够记住之前的关注点；当相同修正重复出现时，可升级为检查／验证；现在还可针对单个对象、多个对象、集合或完整组装后的轮廓
• 阶段比较／迭代现在还会提供确定性的 silhouette_analysis 指标、带类型的 action_hints，以及仅供参考的 part_segmentation 占位项；除非明确启用单独的边车，否则该占位项保持禁用
• scene_scope_graph 用于生成一个明确的只读结构范围产物，其中包含锚点／核心／附件的角色提示
• scene_relation_graph 用于生成一个明确的只读成对关系产物，该产物基于当前事实层生成
• scene_view_diagnostics 用于生成一个明确的只读视图空间产物，其中包含投影范围、画面覆盖率、居中情况，以及针对命名相机或 USER_PERSPECTIVE 的可见／部分可见／遮挡／画面外判定
• 这些空间图／视图诊断工具现在已纳入默认可见的 llm-guided 支持工具集，使模型能够始终使用一个明确的 3D 定向层，而不是仅根据名称、截图或不完整的循环载荷来推断空间状态

当前引导式引导启动工具集：

• router_set_goal
• router_get_status
• browse_workflows
• reference_images
• scene_scope_graph
• scene_relation_graph
• scene_view_diagnostics
• search_tools
• call_tool
• 当 MCP_PROMPTS_AS_TOOLS_ENABLED=true 时，可选的提示词桥接工具：
  • list_prompts
  • get_prompt

支持提示词的客户端应优先使用原生 MCP 提示词。提示词桥接层用于兼容仅支持工具的客户端；对于已使用原生提示词组件的 Streamable HTTP 配置，可将其禁用。

当前引导式实用工具准备路径：

• 引导／规划搜索现在可以调用：
  • scene_get_viewport
  • scene_clean_scene
• 这些实用操作始终有界，不会重新开放完整的旧版功能面
• 规范的引导式发现封装是 call_tool(name=..., arguments=...)
• llm-guided 上规范的清理参数形式是 keep_lights_and_cameras；较早的拆分标志仅用于兼容， 不应作为文档中的公开形式
• reference_images(action="attach", source_path=...) 每次调用仅处理一张参考图； 类似批处理的参数形式现在会给出引导式恢复建议，而不是原始的架构噪声
• collection_manage(action=..., collection_name=...) 仍是规范的 公开形式；旧版 name 仅是范围有限的兼容别名
• modeling_create_primitive(...) 仍仅支持 primitive_type、radius／size、location、rotation 和可选的 name； 不支持的快捷参数（例如 scale、segments、rings、subdivisions 或 创建图元时使用的 collection_name）现在会在直接和代理引导路径上 给出可执行的指导并报错
• 构建目标仍应从 router_set_goal(...) 开始，但截图／ 视口／场景重置请求应改用引导式实用工具路径
• 如果只有在进入引导式构建功能面后才发现过时的场景状态，那么那里也可以使用 scene_clean_scene(...) 作为有界的恢复入口；仍建议在设定目标前进行清理
• 需要恢复时，仍允许在构建阶段进行清理

llm-guided 上当前公开的别名：

内部工具	llm-guided 公开名称	公开参数更改
scene_context	check_scene	action -> query
scene_inspect	inspect_scene	object_name -> target_object
scene_configure	configure_scene	settings -> config
workflow_catalog	browse_workflows	workflow_name -> name，query -> search_query

这为何重要：

• 引导式配置文件从精简且可见的引导工具集开始，而不是从完整目录开始
• 分组／公开工具仍易于发现
• 隐藏的原子工具仍可作为基础设施使用，而非默认的公开使用认知模型
• 在宏观功能面更加完善之前，专业工具系列不会出现在常规引导入口层中

原子工具基础与文档

根目录的 README.md 不再是完整的工具目录，这一点是有意为之。

详细的工具清单和原子工具系列文档应放在文档中，而非首页。这是 TASK-113 之后正确的长期结构。

根据需求查阅以下文档：

• 工具分层策略
  • 关于 atomic / macro / workflow、隐藏的原子工具、目标优先用法以及视觉与断言边界的规范策略。
• MCP 服务文档
  • 界面配置、引导式别名、版本化契约以及运行时／平台指南。
• MCP 客户端配置示例
  • 可直接粘贴使用的本地 MCP 客户端配置示例，涵盖引导式／手动界面，以及 MLX、OpenRouter 和 Gemini 视觉变体。
• 视觉层文档
  • 运行时／后端、捕获包、参考图像、宏／工作流视觉集成说明，以及仓库中跟踪的真实视口评估包，涵盖直接用户视角和固定相机透视捕获。
• LLM 指南 v2
  • 面向引导式操作的策略文档，介绍类型化空间智能层、紧凑关系状态以及有界的后续步骤交接。
• 空间智能研究简报
  • 关于 LLM/VLM 空间推理、多视图推理和几何感知规划的外部研究交接文档。
• 空间智能升级提案
  • 基于研究的升级提案，介绍场景图、符号关系表示法以及配套几何库的选择。
• 可用工具摘要
  • 完整清单及分组／公开工具概览。
• 工具架构索引
  • 面向维护者的 MCP 界面底层工具系列图谱。

如果想查看此服务所基于的原子工具系列，请从这里开始：

• 场景工具架构
• 建模工具架构
• 网格工具架构
• 大型工具架构

建议按以下方式理解：

• 将 /_docs/TOOLS/ 保留为面向维护者的原子／分组架构图
• 保持 README.md 面向产品用户且简洁
• 将 /_docs/AVAILABLE_TOOLS_SUMMARY.md 保留为运行时清单

提供方说明

当前简要说明：

• 本地默认选项： mlx_local，使用 Qwen VL 4B 级模型路径；当前经仓库验证的基线为 mlx-community/Qwen3-VL-4B-Instruct-4bit
• 外部迭代比较候选项： OpenRouter 搭配 x-ai/grok-4.20-multi-agent
• 外部 Google 系列比较路径： 由 OpenRouter 托管的 Google 系列模型与 Google AI Studio / Gemini 现在通过解析后的 vision_contract_profile 路由，共用同一套精简的分阶段比较契约

外部视觉运行时说明：

• VISION_EXTERNAL_PROVIDER 用于选择传输／提供方分支
• VISION_EXTERNAL_CONTRACT_PROFILE 可选，用于覆盖外部比较流程的提示词／架构／解析器契约
• 如果未设置此覆盖项，运行时会自动匹配 gemma / gemini / learnlm 等 Google 系列模型 ID，然后回退到提供方默认值

各提供方的详细表格：

• 视觉层文档 -> 提供方说明

架构

系统采用有意的分层设计：

• MCP 服务端（server/）：FastMCP 接口层、公共工具定义、转换、发现和响应契约。
• 路由器（server/router/）：目标解读、安全与纠正策略、工作流匹配、会话上下文和引导式执行行为。
• Blender 插件（blender_addon/）：实际的 bpy 执行、RPC 处理程序，以及对 Blender 主线程安全的操作调度。

通信通过 TCP 套接字上的 JSON-RPC 实现。

更多详情：

• 架构文档
• 路由器文档
• 运行时职责边界
• 插件文档

结构化契约基线

服务端正推动关键接口改用机器可读的载荷，而不是充斥说明文字的 JSON 字符串。

当前结构化契约基线包括：

• macro_cutout_recess
• macro_finish_form
• macro_attach_part_to_surface
• macro_align_part_with_contact
• macro_place_supported_pair
• macro_cleanup_part_intersections
• macro_relative_layout
• scene_create
• scene_configure
• mesh_select
• mesh_select_targeted
• mesh_inspect
• scene_snapshot_state
• scene_compare_snapshot
• scene_measure_distance
• scene_measure_dimensions
• scene_measure_gap
• scene_measure_alignment
• scene_measure_overlap
• scene_assert_contact
• scene_assert_dimensions
• scene_assert_containment
• scene_assert_symmetry
• scene_assert_proportion
• router_set_goal
• router_get_status
• workflow_catalog

这对自动化、审计以及宏与工作流的组合至关重要。

接触判定语义

对于曲面或圆角形体的接触敏感检查，真值层现在会区分：

• 在存在有界网格感知路径时，使用网格表面接触／间隙语义
• 在不存在网格感知路径时，使用包围盒回退语义

这意味着一对对象即使显示包围盒接触，如果实际网格表面仍存在可见间隙，主要测量关系仍可能为 separated。引导式混合真值后续处理现在会在面向操作人员的摘要中保留这一区别，而不会将其简化为笼统的“接触通过／失败”判断。

如果网格感知路径检测到实际重叠，主要测量关系也会保持为 overlapping，因此 scene_assert_contact(...) 中的重叠拒绝仍作为单独的真值条件生效，而不会被简化为单纯的接触判断。

结构化澄清流程

引导式接口将缺失输入处理纳入产品契约，而非事后补充。

• 模型优先澄清是 llm-guided 模式下 router_set_goal(...) 的默认方式：缺少工作流参数时，会先向外部模型返回类型化的 needs_input 载荷。
• 类型化回退载荷让仅支持工具的客户端或兼容性客户端也能使用相同流程。
• 人工／原生澄清保留为后续或回退策略，而非工作流执行的默认首选步骤。
• router_set_goal(...) 可以请求受限选项、布尔值、枚举值或工作流确认。
• partial answers 会在后续轮次中保留。
• workflow_catalog 导入冲突也会使用相同的澄清模型。

引导式交接契约

现在，引导式界面将工作流回退视为明确的类型化契约，而不是隐藏在说明中的阶段副作用。

• 在 continuation_mode="guided_manual_build" 和 continuation_mode="guided_utility" 等受限的继续路径上，router_set_goal(...) 会返回 guided_handoff。
• guided_handoff 会为 llm-guided 上的下一步指定 target_phase、direct_tools、supporting_tools 和 discovery_tools。
• 在这些回退路径上，workflow_import_recommended 保持为 False，除非用户明确要求导入或创建工作流。
• router_get_status(...) 会在会话诊断信息中保留当前有效的 guided_handoff，以便客户端恢复预期的继续路径。

由服务器驱动的引导式流程状态

现在，除 guided_handoff 外，引导式界面还包含一个明确的、机器可读的 guided_flow_state 契约。

• router_set_goal(...)、router_get_status(...)、 reference_compare_stage_checkpoint(...) 和 reference_iterate_stage_checkpoint(...) 可以为活跃的 llm-guided 会话提供 guided_flow_state
• guided_flow_state 会报告：
  • flow_id
  • domain_profile
  • current_step
  • completed_steps
  • active_target_scope
  • spatial_scope_fingerprint
  • spatial_state_version
  • spatial_state_stale
  • last_spatial_check_version
  • spatial_refresh_required
  • required_checks
  • next_actions
  • blocked_families
  • allowed_families
  • allowed_roles
  • completed_roles
  • missing_roles
  • required_role_groups
  • required_prompts
  • preferred_prompts
  • step_status
• 当前的领域覆盖项为：
  • generic
  • creature
  • building
• 早期的引导式构建会话现在会从受步骤门控的空间上下文阶段开始，而不是立即展示整个构建界面
• 如果尚无活跃范围，scene_scope_graph(...) 会绑定当前引导目标范围；空间刷新检查必须继续使用已绑定的目标范围，而不是重新绑定到不同的对象集合
• 无关的视图检查，例如 scene_view_diagnostics(target_object="Camera", ...)，本身不能满足生物或建筑的空间检查
• 如果当前引导目标附带了参考图像，应先将其视为主要的依据输入，再决定第一个躯干、头部、尾部体块及粗略轮廓
• 请使用 Body、Head、Tail、ForeLeg_L 和 HindLeg_R 等完整语义对象名称，而不要使用 ForeL / HindR 等不透明缩写，因为引导式接缝／角色启发式对可读名称更可靠
• 在 llm-guided 模式下，服务现在可以对较弱的角色相关名称发出警告；如果将明显不透明的占位名称（如 Sphere / Object）用作语义部件名称，则会阻止该操作
• 不要在未指定范围的情况下调用 scene_scope_graph(...)、scene_relation_graph(...) 或 scene_view_diagnostics(...)，并假定这表示“检查整个场景”
• 在活跃的引导式空间门控或空间刷新重新启用期间，这三个空间辅助工具都应视为需要显式范围的工具，而不是整个场景探测工具
• 只读空间辅助工具固定可在 llm-guided 模式下调用；引导式系列门控不得仅因为当前构建步骤的 allowed_families 不包含 spatial_context，就拒绝 scene_scope_graph(...)、scene_relation_graph(...) 或 scene_view_diagnostics(...)
• 在引导式门控之外，范围／关系图构建器仍需显式指定 target_object、target_objects 或 collection_name；现在裸调用会失败，而不会再静默返回空的 scene 范围
• 默认占位范围（例如默认的 Cube 或通用根 Collection）本身不再被视为有意义的引导目标／工作集绑定
• 但是，对于较早的“场景是否已经非空？”引导决策，Blender 默认的 Cube 加上默认相机／灯光辅助对象仍会进入空场景主工作集引导路径
• 启动后，这项非空判断有意不再过度依赖名称：由多个对象组成的真实粗略灰模，即使使用 Cube 或 Sphere 等默认图元名称，仍会被视为已有几何体；而仅含辅助对象的场景仍可进入 bootstrap_primary_workset
• 显式引导范围现在根据调用者意图绑定，而不是依赖名称启发式，因此，当操作员将名为 Cube、Sphere 或 Sunflower 的真实对象指定为目标时，它们仍可成为活跃引导工作集
• 在 scene_clean_scene(...)、scene_duplicate_object(...)、scene_rename_object(...)、modeling_create_primitive(...)、modeling_transform_object(...)、modeling_join_objects(...)、modeling_separate_object(...) 等实质性场景变更，或有界附件／对齐宏之后，引导式运行时可以将空间层标记为过时，并重新启用所需检查
• 同一脏状态更新现在会立即重新应用 FastMCP 可见性，因此客户端会在 spatial_refresh_required 持久化后立即看到所需的空间支持工具
• 在 Streamable HTTP 上，引导式脏状态和可见性收尾操作必须在当前工具响应返回前完成；会修改场景状态的路由同步工具会将这些收尾操作延后到 MCP 异步包装器中执行，而不是安排脱离请求的会话状态写入
• 异步包装器和原生异步建模辅助工具会继续在工作线程上执行阻塞的同步路由／RPC；只有引导式收尾操作会在 Streamable HTTP 响应完成前回到事件循环中运行
• macro_cutout_recess(...) 和 macro_finish_form(...) 等异步脏状态宏辅助工具会使用等待式异步路由路径，以便在 Streamable HTTP 响应完成前重新应用可见性
• scene_scope_graph(...)、scene_relation_graph(...) 和 scene_view_diagnostics(...) 等异步空间辅助工具会将依赖 Blender 的图表／诊断读取操作移出事件循环，然后再记录引导式空间检查的完成状态
• 成功的 scene_rename_object(...) 验证等异步引导式身份收尾操作，也会先将依赖 Blender 的场景查找移出事件循环，再更新引导部件注册表
• 使用路由执行报告的原生异步建模工具，仍必须通过活跃 MCP 上下文展示 guided_naming 警告；否则在 Streamable HTTP 上，较弱的语义名称可能会丢失面向模型的修正提示
• 原生异步建模和清理收尾操作会根据结构化的 report.steps 推导成功的场景变更，而不是根据渲染后的旧版路由文本；多步骤修正路由会给旧版行添加前缀，因此不是判断引导式脏状态或角色注册的可靠依据
• 异步引导角色注册会在持久化最终高级 guided_flow_state 后重新应用 FastMCP 可见性，确保 list_tools() 在 Streamable HTTP 响应完成前反映新的引导步骤
• 异步公共工具变体必须保留原始公共文档字符串，尤其是可见的引导式空间和建模辅助工具，其描述会说明必需的范围参数、工作流顺序和参数约束
• 当路由器将成功的 modeling_transform_object(...) 调用修正为另一个有效对象名称时，引导式空间脏状态和引导角色后续处理会使用最终建模步骤返回的变换对象名称，而不是调用者最初提供的名称
• mesh_extrude_region(...)、mesh_loop_cut(...) 和 mesh_bevel(...) 等引导式网格编辑工具现在归入 secondary_parts 系列，因此它们会在空间上下文门控期间被阻止，并在几何编辑成功后重新启用空间检查
• 完成一项必需的空间检查并推进引导流程时，服务现在会立即重新应用 FastMCP 可见性，而不是等待之后的状态／搜索刷新
• 支持／对称感知关系对即使与通用主目标对共享相同的 (from_object, to_object) 键，也会保留支持和对称标注，因此后续引导规划器仍能看到支持／对称语义，而不只是通用边
• 包含必需生物接缝的关系图仍会为请求范围内的非接缝对象添加后备 primary_to_other 对，因此未分类对象不会从混合引导诊断中消失
• 健康的支持／对称关系对不再仅仅因为中心不同或并非直接接触对就被判定为失败；只有 unsupported / asymmetric 支持／对称判定会在此处计为失败
• 当 guided_flow_state.spatial_refresh_required == true 时，应将 next_actions=["refresh_spatial_context"] 视为权威的服务端状态，而不是建议性文本；首先对已绑定的目标范围调用 scene_scope_graph(...) 刷新，然后在同一范围上重新运行其余必需的空间检查
• 只有当 scene_view_diagnostics(...) 返回真实可用的视图空间证据时，才计入引导式空间门控；无头／不可用的探测仍然只读，不能单独满足必需检查
• 如果阶段比较／迭代发现重要问题，但当前引导角色／工作集切片仍未完成，治理器现在可以让会话继续进行有界构建，而不是过早升级到 inspect_validate
• 当此未完成阶段的保持逻辑返回 loop_disposition="continue_build" 时，持久化的 guided_flow_state 会停留在同一当前步骤，并且不会将尚未完成的角色切片标记为已完成；应继续遵循 missing_roles，再依赖后续阶段的可见性
• 即使阶段迭代没有 correction_focus 或 action_hints，此未完成阶段的保持逻辑也会生效；对于仍缺少必需角色的引导式构建，无操作的比较结果不得将其推进到 finish_or_stop
• 流程进入 place_secondary_parts 等后续步骤后，如果缺失的主体体块仍属于同一个有界工作集，服务仍可保留它们，而不是强迫松鼠／建筑流程立即放弃尚未完成的核心体块
• 对于生物灰模接缝，嵌入式耳朵／头部或口鼻部／头部位置的 intersecting 仍可接受，但头部／躯干、尾部／躯干或四肢／躯干上的 floating_gap 仍需处理
• 如果某个所需工具系列被隐藏／被流程阻止，请检查 router_get_status().guided_flow_state，完成列出的 required_checks 并遵循 next_actions，不要猜测隐藏的工具名称并将其传给 call_tool(...)
• 如果显式引导目标停留在手动／无匹配路径上，强模式建议的工作流仍可展开；在此状态下仍会被抑制的是置信度较低的启发式重新开放路径
• 现在，引导界面上的精确工具名称搜索会返回更精简、范围更小的结果集，不再针对简单查找向模型倾泻完整的扩展载荷
• 对于角色敏感的构建步骤，应将 allowed_roles 和 missing_roles 视为执行约定的一部分，而不是建议性文本
• 即使对象的语义角色是在较早步骤中注册的，也应让 collection_manage(...) 等整理／工作集操作继续用于已创建的对象
• 会话进入下一步后，仍可对已注册的主对象进行有界细化；后续步骤并不意味着要完全冻结所有先前的体块
• 请使用 guided_register_part(object_name=..., role=...) 作为告知服务某个对象所代表语义部件的标准方式；构建工具上可选的 guided_role=... 提示仅为便捷功能
• 可选的 role_group=... 值必须与服务端的领域角色映射相符；调用者不能将 body_core、head_mass 或类似角色敏感的变更调用重新分类为 utility 或其他系列，以绕过当前引导阶段门控
• guided_register_part(...) 现在会验证指定的 Blender 对象是否实际存在，之后才能将其计入引导角色完成状态；拼写错误不会自行创建已完成角色
• 如果引导对象验证完全无法读取 Blender 场景，guided_register_part(...) 现在会明确失败，而不会根据未经验证的对象名称修改引导会话状态
• 传入 scene_scope_graph(...)／范围构建路径的显式目标名称，现在也会遵循相同的 Blender 实际状态验证规则，然后才能绑定引导范围
• 只有当活跃引导流程已存在时，这些可选的 guided_role=... 提示才会自动注册；在活跃引导流程之外，它们本身不会创建持久角色状态
• 创建调用失败时，引导角色状态现在也不会被修改：如果 modeling_create_primitive(...) 返回失败字符串，即使提供了语义 name，请求的角色也不会自动注册
• 对于 modeling_create_primitive(...)，guided_role=... 现在还要求提供显式语义 name；引导式创建不允许将 Blender 自动生成的名称注册为语义部件
• 当路由器在前面添加 scene_set_mode(...) 等修正步骤时，成功的引导式创建／变换调用仍会根据最终建模步骤注册相应角色，不会仅仅因为调用变成多步骤就丢失便捷注册
• 引导角色便捷注册现在也能处理包含撇号的有效对象名称（例如 King's Crown），不会截断存储的对象名称
• 引导式运行时的成功结果解析现在也会将引号内对象名称中的撇号视为名称的一部分，用于解析创建／变换／重命名／合并结果，因此成功变更后仍会执行过时状态标记和引导注册表同步
• ForeLeg_L、ForeLeg_R 和 ForeLegPair 等规范配对名称，现在会被视为 foreleg_pair / hindleg_pair 的强语义名称，在更严格的命名策略下不会触发警告或阻止操作
• 对于 modeling_create_primitive(...)，引导角色自动注册现在会绑定到 Blender 返回的实际创建对象名称，因此即使 Blender 为默认名称自动编号（例如 Cube.001）或使用了不同的默认对象名称（例如 Suzanne），角色状态仍会保持一致
• 对于 modeling_transform_object(...)，引导角色自动注册现在会绑定到最终路由步骤返回的实际变换对象名称，因此即使路由器修正了对象身份，也仍会重新启用空间检查，并更新实际发生变化对象的角色状态
• 成功的 scene_rename_object(...) 调用现在会使引导部件注册表与重命名后的 Blender 对象保持一致，因此后续角色敏感变换仍可恢复已注册角色，无需手动重新注册
• 成功的 scene_rename_object(...) 调用也会重新启用引导空间检查，因为已绑定目标范围的指纹基于名称
• 成功的 scene_duplicate_object(...) 调用也会重新启用引导空间检查，因为复制会改变可见工作集／范围的关系事实
• 对于 Object 'Missing' not found 等失败的纯字符串变更结果，引导会话状态现在不会被修改；不会仅仅因为包装器返回了字符串，就重新启用空间检查或改写引导角色注册
• scene_clean_scene(...) 现在会清除引导部件注册表，并将引导流程返回到 bootstrap_primary_workset，而不是在空场景中保留已完成的部件
• 在同一会话中开始不同的引导目标时，现在会重置新流程的引导部件注册，而不是从上一个对象沿用已完成的角色
• modeling_join_objects(...) 或 modeling_separate_object(...) 等破坏性身份／拓扑变更现在会移除过时的引导部件注册；如果生成的对象仍应计入引导角色完成状态，请显式重新注册它们
• 这些相同的破坏性拓扑变更也会重新启用引导空间检查，因为对象合并或拆分后，先前记录的范围／视图事实已不再可信
• 对于宏捕获／视觉产物，macro_attach_part_to_surface(...) 现在会在额外的网格表面微调后刷新其操作后捕获包，因此附加图像和真实性摘要描述的是最终贴合姿势，而不是微调前的中间姿势
• 路由宏报告可以是 partial 且仍携带 error；MCP 适配器会保留该结构化报告，包括 actions_taken、已修改对象、验证建议、捕获／真实性数据和后续指导，而不是将其强行转换为空的失败信封
• 如果运行时配置启用了可选分割旁路组件，但当前比较路径尚未执行该组件，分阶段比较／迭代响应现在会报告 part_segmentation.status="unavailable"，而不是静默保持为 disabled
• 如果服务对引导式命名发出警告或阻止操作，请使用建议的语义名称之一重命名或创建对象，而不要用相同的弱缩写重试
• 引导式命名和引导式空间角色推断现在使用基于词元边界的匹配，而不是原始子字符串匹配，因此 Heart 或 TruthBodyAnchorHead 等名称不会意外成为语义耳朵／躯干／头部角色
• guided_flow_state 中命名的 required prompt bundle 和 preferred prompt bundle 是提示词资源名称，不是服务器驱动流程的替代品；提示词用于支持流程，而不是成为流程本身

引导式参考就绪状态

参考驱动的分阶段工作现在采用明确的就绪状态约定，不再依赖隐含的顺序假设。

• router_set_goal(...) 和 router_get_status(...) 会公开 guided_reference_readiness。
• 该载荷会报告 attached_reference_count、pending_reference_count、 compare_ready、iterate_ready，以及可供机器读取的 blocking_reason 和 next_action。
• reference_images(action="attach", source_path=...) 可以保持待处理状态，直到引导式 目标会话实际就绪，然后自动采用。
• 如果同一目标已有活动引用图像，而在 needs_input 期间又暂存了新图像，那么在就绪状态恢复前， 暂存图像会与该目标已有的活动引用图像保持分离。
• 如果就绪会话仍带有明确指定给另一目标的待处理引用图像， reference_images(action="list"| "remove"| "clear", ...) 现在会一致地处理合并后的可见集合， 不再留下损坏的待处理记录。
• 如果会话尚未就绪，reference_compare_stage_checkpoint(...) 和 reference_iterate_stage_checkpoint(...) 现在会立即失败，并回显相同的 guided_reference_readiness 载荷。
• 如果 reference_iterate_stage_checkpoint(...) 返回 loop_disposition="inspect_validate"，请立即停止自由建模，改为检查、测量和断言。
• 如果它返回 loop_disposition="continue_build"，但 guided_flow_state.missing_roles 仍非空，请继续当前角色切片；即使比较结果本身没有产生可执行的 修正提示，服务也会有意保留当前引导步骤，而不推进到下一阶段。
• router_set_goal(..., gate_proposal={...}) 可以接受可选的、源自模型或引用图像的门控提案，用于当前活动的引导目标。服务会将其规范化为 active_gate_plan，把每个门控的初始状态设为 pending，并在 gate_intake_result.policy_warnings 中返回被丢弃的隐藏工具名称、不支持的门控类型、原始 Blender/Python 指令、目标接收阶段无法获得的必需引用图像/感知证据，或客户端提供的完成声明（例如 passed）。
• router_get_status(...)、router_set_goal(...) 和暂存的引用图像比较/迭代载荷可以公开 active_gate_plan；LLM、 reference_understanding、轮廓、分割、分类和 VLM 检查点来源可以提议或辅助门控，但场景/空间/网格和断言证据仍是判定通过/失败状态的权威依据。
• 暂存的引用图像比较/迭代载荷还会将活动门控计划投影到顶层的 gate_statuses、completion_blockers、 next_gate_actions 和 recommended_bounded_tools，因此客户端无需从嵌套计划结构中推断即时修复路径。
• scene_relation_graph(...) 会使用权威证据引用、状态原因、完成阻碍项和有界修复工具提示，更新 required_part、attachment_seam、support_contact 和 symmetry_pair 的首个确定性门控切片；后续的引导式场景变更会通过现有的空间脏标记路径，将受影响的验证器支持状态标记为 stale。
• 活动门控阻碍项会将引导可见性/搜索范围缩小到现有的验证和修复工具；接缝门控失败时，应使用关系图/测量/断言/宏修复工具，而不是宽泛的目录或重置目标。
• 暂存迭代响应中尚未解决的 completion_blockers，现在也会触发 loop_disposition="inspect_validate"，即使比较循环没有重复相同的仅视觉修正重点。
• 如果暂存比较结果变差，但仍存在强有力的确定性事实发现，应使用相同的检查/测量/断言交接，而不是即兴进行另一轮大幅自由修正。
• 错误阶段的迭代交接若将状态转为 inspect_validate 或 finish_or_stop，也会在返回前重新应用引导可见性。
• 对于暂存的比较/迭代，goal_override 不再能替代会话；请改用活动的引导目标会话。
• 对于集合或多对象的暂存捕获，如果未提供明确的 target_object，捕获焦点现在会回退到已组装目标范围的主目标。
• 对于请求的 target_view，确定性轮廓指标优先使用目标/焦点捕获，而不是范围更广的 context_wide 捕获。
• reference_compare_current_view(..., persist_view=True, view_name=..., orbit_horizontal=..., zoom_factor=...) 会保留捕获的用户视图，并且不会在紧凑视图诊断期间再次应用相同的视图调整。

会话诊断

引导式／运行时负载现在会公开明确的 MCP 会话元数据：

• router_set_goal(...) 包含 session_id 和 transport
• router_get_status(...) 包含 session_id 和 transport
• reference_compare_stage_checkpoint(...) 包含 session_id 和 transport
• reference_iterate_stage_checkpoint(...) 包含 session_id 和 transport

当前运行时指南：

• 对于较长的引导式运行，以及调试支持会话的参考／检查点工作流，建议使用有状态的 streamable HTTP 传输
• 最近的引导式会话加固移除了已知的路由器记账路径，该路径可能在路由工具执行期间覆盖活跃的目标／参考会话状态
• 如果要调查未来的状态丢失事件，请先比较 session_id 和 transport，以区分：
  • 传输／会话重新连接
  • 应用级目标重置
  • 常见的引导式就绪阻碍因素，例如缺少目标或参考

服务端采样助手基线

MCP 服务现在在活跃请求中提供一个有界的分析助手层。

当前用例：

• 在 scene_snapshot_state、scene_compare_snapshot、scene_get_hierarchy、scene_get_bounding_box 和 scene_get_origin_info 等检查密集型路径上提供可选的 assistant_summary
• 在 router_set_goal、router_get_status 和 workflow_catalog 上提供有界的 repair_suggestion

明确的助手终止状态：

• success
• unavailable
• masked_error
• rejected_by_policy

规则很严格：助手可以帮助总结或提供建议，但不得覆盖场景事实或路由器策略。

版本化接口基线

公共接口的演进通过显式版本控制：

接口配置	默认契约版本
legacy-manual	legacy-v1
legacy-flat	legacy-v1
llm-guided	llm-guided-v2

兼容性说明：

• llm-guided-v1 仍可选作回滚版本
• workflow_catalog、scene_context 和 scene_inspect 均参与引导式接口的演进

代码模式决策

当前基准版本：

• legacy-flat
• llm-guided
• code-mode-pilot

当前决策：

• Go 决策：将 code-mode-pilot 保留为实验性只读接口
• 不要将代码模式设为 Blender 中写入密集型或会破坏几何体的工作的默认路径

支持矩阵

• Blender：端到端测试覆盖已在 Blender 5.0 上验证；插件最低版本仍为 Blender 4.0+，尽力提供支持。
• Python：3.11+
• FastMCP 任务运行时：fastmcp 3.2.4 + pydocket 0.19.x
• 代码模式沙箱附加依赖：pydantic-monty 0.0.11
• 操作系统：macOS / Windows / Linux
• 内存：路由器语义功能依赖本地 LaBSE 模型及相关向量基础设施

快速开始

以下说明适用于此项目的最终归档版本。此后不会再发布新版本、提供修复或支持。

1. 安装 Blender 插件

1. 从 Releases 页面下载 blender_ai_mcp.zip，或使用 python scripts/build_addon.py 在本地构建。
2. 打开 Blender -> Edit -> Preferences -> Add-ons。
3. 点击 Install... 并选择 zip 文件。
4. 启用插件。它会在端口 8765 上启动本地 Blender RPC 服务。

2. 在引导配置文件上运行 MCP 服务

推荐默认值：

• ROUTER_ENABLED=true
• MCP_SURFACE_PROFILE=llm-guided
• 如果希望输出的图像和文件在主机上可见，请映射 /tmp

Docker 命令示例：

docker run -i --rm \
  -v /tmp:/tmp \
  -e BLENDER_AI_TMP_INTERNAL_DIR=/tmp \
  -e BLENDER_AI_TMP_EXTERNAL_DIR=/tmp \
  -e ROUTER_ENABLED=true \
  -e MCP_SURFACE_PROFILE=llm-guided \
  -e BLENDER_RPC_HOST=host.docker.internal \
  ghcr.io/patrykiti/blender-ai-mcp:latest

docker run --rm \
  -p 8000:8000 \
  -v /tmp:/tmp \
  -e BLENDER_AI_TMP_INTERNAL_DIR=/tmp \
  -e BLENDER_AI_TMP_EXTERNAL_DIR=/tmp \
  -e ROUTER_ENABLED=true \
  -e MCP_SURFACE_PROFILE=llm-guided \
  -e MCP_TRANSPORT_MODE=streamable \
  -e MCP_HTTP_HOST=0.0.0.0 \
  -e MCP_HTTP_PORT=8000 \
  -e MCP_STREAMABLE_HTTP_PATH=/mcp \
  -e MCP_PROMPTS_AS_TOOLS_ENABLED=false \
  -e BLENDER_RPC_HOST=host.docker.internal \
  ghcr.io/patrykiti/blender-ai-mcp:latest

通用 MCP 客户端配置示例：

{
  "mcpServers": {
    "blender-ai-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v", "/tmp:/tmp",
        "-e", "BLENDER_AI_TMP_INTERNAL_DIR=/tmp",
        "-e", "BLENDER_AI_TMP_EXTERNAL_DIR=/tmp",
        "-e", "ROUTER_ENABLED=true",
        "-e", "MCP_SURFACE_PROFILE=llm-guided",
        "-e", "BLENDER_RPC_HOST=host.docker.internal",
        "ghcr.io/patrykiti/blender-ai-mcp:latest"
      ]
    }
  }
}

网络说明：

• macOS / Windows： 使用 host.docker.internal
• Linux： 建议使用 --network host，并设置 BLENDER_RPC_HOST=127.0.0.1
• MCP_TRANSPORT_MODE=stdio 保留当前的子进程/stdio MCP 模式
• MCP_TRANSPORT_MODE=streamable 启动有状态的 Streamable HTTP MCP 服务
• MCP_PROMPTS_AS_TOOLS_ENABLED=false 会为支持提示词的客户端停用兼容工具的提示词桥接功能；原生 MCP 提示词仍可用

更多配置文件和配置示例，请参阅：

• MCP 服务文档
• MCP 客户端配置示例
• .env.example，其中包含完整的受跟踪运行时/配置变量集

测试

单元测试：

PYTHONPATH=. poetry run pytest tests/unit/ -v

单元测试收集数量：

poetry run pytest tests/unit --collect-only

端到端测试：

python3 scripts/run_e2e_tests.py

端到端测试收集数量：

poetry run pytest tests/e2e --collect-only

Pre-commit：

poetry run pre-commit install --hook-type pre-commit --hook-type pre-push
poetry run pre-commit run --all-files

更多详情：

• 测试文档
• 开发文档

文档目录

• 架构
• MCP 服务文档
• 视觉层文档
• 路由器文档
• 路由器职责边界
• 插件文档
• LLM Guide v2
• 空间智能研究简报
• 空间智能升级提案
• 可用工具摘要
• 工具架构索引
• 提示词
• 任务

项目状态

本项目已停止维护，后续不会继续开发。它将由一个全新的解决方案取代，该方案在 3D 场景理解方面更强大，与 Blender 的协作更深入可靠，工作流控制也大幅提升。新的插件即将发布。

本仓库不再接受新的拉取请求、功能请求和问题报告。CONTRIBUTING.md、SUPPORT.md、SECURITY.md 和 CODE_OF_CONDUCT.md 仅供历史参考。

作者

Patryk Ciechański

• GitHub：PatrykIti

许可证

本项目采用 Apache License 2.0 许可。

请参阅：

• LICENSE.md
• NOTICE