BLENDER插件

Blender 桥接（voiceassistant_blender）

通过 TCP 接收语音助手指令并在 Blender 主线程执行 bpy.ops

版本：1.0.0

一、插件简介

------------------------------------------------------------------------

voiceassistant_blender 是语音助手（VoiceAssistant）的 Blender 桥接

插件（addon，插件内名称「语音助手桥接」）。它在本机监听 TCP 端口，

接收语音助手经规则表发送的 bpy.ops 指令，并在 Blender 主线程执行，

实现语音控制 Blender。

处理链路为：

    语音指令 -> 规则引擎匹配（规则表 value=json）

      -> JSON 报文（target_ip:port）-> 桥接 TCP 接收

      -> 主线程执行 bpy.ops -> 状态栏提示

主程序无需任何改动：纯靠规则表配置 + 本插件即可工作。发送为

fire-and-forget，插件收到后立即回 {"status":"ok"}。

二、核心功能

------------------------------------------------------------------------

1. bpy.ops 指令执行

   - 接收语音助手 rule name 命中的 bpy.ops 路径并执行；

   - 未注册（脚本自定义）的 bpy.ops 路径自动解析并执行；

   - 纯文本参数按 name -> filepath -> text 顺序路由到对应参数

     （如 object.select_by_name 用 name、导入导出用 filepath）。

2. 模态指令支持

   - transform.*、view3d.zoom/move/rotate/dolly/zoom_border、

     mesh.loopcut/bevel/inset/knife_tool/spin/offset_edges/

     extrude_region_move、curve.extrude/pen、object.duplicate_move

     等白名单算子自动以 INVOKE_DEFAULT 启动模态；

   - 带参数指令（如 transform.translate {"value":[1,0,0]}）直接一步

     执行，不进入模态；

   - 模态启动前自动切到 3D 视图区域、把鼠标 warp 到视口中心，

     避免 region 绑定错误导致拖拽无效；不在编辑模式时自动切换。

3. 视图指令兼容

   - view3d.view_axis / view_persportho / view_camera / localview /

     view_all / view_selected / snap_* 等依赖 3D 视图上下文的指令，

     当前激活区域非 3D 视图时自动构造 context override 重试。

4. 侧栏面板与自测

   - 侧边栏「语音助手」面板（N 面板）查看运行状态、手动启停；

   - 「最近指令」查看区：最多 50 条，展示 5 条可滚动，每条带复制

     按钮可一键复制完整报文；

   - 「自测（本地执行）」按钮绕过网络直接执行

     mesh.primitive_cube_add 验证执行链路。

三、引擎与技术实现

------------------------------------------------------------------------

  执行线程     Blender 主线程（bpy.app.timers 调度），不阻塞 UI

  网络层       common/net_server：TCP 服务器（默认端口 2457，可配），

               单连接单次 recv，FIFO 事件分发

  报文协议     common/dispatcher 解析 VoiceAssistant Bridge 协议：

               {"event":"json_rule_matched","timestamp":...,"data":{...}}

  上下文重试   Blender 4.0+ 用 context.temp_override(**override)；

               4.0 以下版本回退位置参数调用（旧接口兼容）

  模态修复     _warp_to_3d_viewport 用 Win32 SetCursorPos 设置屏幕绝对

               坐标（规避 Blender 4.x cursor_warp 坐标 bug，devtalk

               issue #151064）+ 延迟一帧再 INVOKE_DEFAULT

  日志         写入 Blender 临时目录 voice_bridge_blender.log

               （Blender 4.x 在 %TEMP%\blender_<随机>\）

四、配置面板

------------------------------------------------------------------------

Blender 偏好设置 -> 插件 -> 语音助手桥接（启用后即生效）：

  监听端口     默认 2457（与语音助手规则表 meta.port 一致）

  自动启动     勾选后 Blender 启动即监听

侧边栏 N 面板 -> 语音助手（运行期）：

  状态 / 启停   查看服务器状态、手动启动/停止

  最近指令     最近接收 50 条（时间 / cmd / 参数 / 成功失败 / 结果）

               每条含复制按钮，可一键复制完整报文排查

  自测         本机直接执行 mesh.primitive_cube_add 验证执行链路

语音助手段（无需改源码，纯配置）：

  规则表       data/tables/blender.json / blender_va.json（已随主程序

               分发：86 条快捷键 + 130 条 bpy.ops 指令）

  表 meta      target_ip:127.0.0.1、port:2457、「搅拌器VA」表

               target_window:blender（前台窗口自动切表）

五、入口

------------------------------------------------------------------------

  语音规则      说出规则表的规则名（如「立方体」「平移」「渲染」）——

                规则 value=json、cmd=bpy.ops 路径 → 本插件执行

  面板自测      侧栏「语音助手」->「自测（本地执行）」按钮

  热键          无（模态指令启动后可配合鼠标/键盘继续操作，Esc 取消）

  自动切表      语音助手 focus_switcher 按前台窗口 blender 自动切换到

                blender_va 规则集

六、依赖与资源

------------------------------------------------------------------------

  运行环境     Blender 3.x / 4.x / 5.x（Windows；模态修复依赖 Win32

               user32.SetCursorPos / EnumWindows）

  网络         仅 Python 标准库 socket / threading / json，无第三方依赖

  端口         2457（与语音助手表级 meta.port 保持一致；冲突时可改）

  分发方式     zip 单顶层目录 VoiceAssistant_blender/ 或整目录复制到

               %APPDATA%\Blender Foundation\Blender\<版本>\scripts\addons\

               安装后 偏好设置 -> 插件 -> 搜索「语音助手桥接」启用

  语音助手段   主程序零改动，仅需分布式规则表 + 2457 端口

七、系统要求

------------------------------------------------------------------------

  操作系统   Windows 10 x64 及以上

  内存       4GB 及以上

  软件       Blender 3.6+（3D 视图模态修复按 Blender 4.x/5.x 行为实现）

八、关于

------------------------------------------------------------------------

  所属软件   语音助手（VoiceAssistant）

  插件 ID    voiceassistant_blender（addon 目录名 VoiceAssistant_blender）

  插件名称   Blender 桥接（Blender 偏好设置内显示「语音助手桥接」）

  版本       1.0.0

  协议接口   VoiceAssistant Bridge 协议（PROTOCOL.md，TCP/JSON）

  作者       研道人-江小东

  官网       https://3daoshan.com

  B 站主页   https://space.bilibili.com/3493128858241731

  邮箱       1719262421@qq.com

  版权信息   © 2026 研道人-江小东

  版权说明   本软件仅供学习交流使用。