dsh-blender-plugin 是一个让 AI 直接驱动 GUI Blender 的实时插件：它把 DSH（DeepSeek Harness）通过 TCP 直连通道接进 Blender，提供15 个模型工具，覆盖看画面、改场景、参数搜索、无头批处理、装配验收与交付导出。本文逐个讲清这 15 个工具的用途和典型用法，帮你快速建立「该用哪个工具」的判断力。

🧭 先花 30 秒建立心智模型

用这 15 个工具之前，只需记住三件事：

1. GUI 优先：默认路线是打开 Blender GUI 并 Connect 随包 addon（addon/dsh_blender_bridge.py），AI 对着你正在看的场景「看一眼 → 改一步 → 再确认」。
2. 无头备用：没有窗口时，blender -b持久会话（worker）提供同样的交互闭环，也能出图，AI 不会「失明」。
3. 验收只认一条：/doctor返回kind=ok（或工具里blender_viewport(op="doctor")），其它自检只用于定位单项问题。

装完后的两条自检命令（详细安装步骤见 docs/给第三方的安装清单.md 和 docs/操作教程.md）：

curl -sS http://127.0.0.1:9877/health # 后端活着 curl -sS http://127.0.0.1:9877/doctor # kind=ok 才算 Blender 也连上了

📋 15 个工具速查总表

当前版本 v2.6.0，工具面固定为 15 个（更多判定/验收/导出操作都收在blender_rt_plan目录里，共 33 family / 217 op，避免工具列表膨胀）：

👀 第一组：交互与控制（看、做、观察）

blender_rt_see —— 最便宜的「眼睛」

50–160 ms 回一帧图，是所有工作流的第一步。三种「看」：

• 视口帧（默认）：就是用户正在看的角度，含视口着色与覆盖物；
• 自定义视角：给from+look_at指定相机位置与注视点，不动用户视口，零场景改动，同一组参数重复出图 md5 相同，可当「验收指纹」；
• 整窗截图：full=True截取整个 Blender 窗口，看 UI 面板时用。

常用写法：

blender_rt_see(max_size=560) blender_rt_see(from="9,-9,6", look_at="0,0,1", lens=35)

注意：viewport模式出的是「视口观感」，不是 Cycles 成品图；要成品图走blender_rt_headless。

blender_rt_do —— 改一步 + 顺手看一眼

在 Blender 主线程执行 Python，预置bpy / math / mathutils / Vector。两个关键约定：

• 持久内核K：每次执行都是全新命名空间，跨调用要保留的状态必须挂在K上（比如K.n = K.n + 1）；
• see=True（默认）改完顺带回一帧，GUI 整步约 105 ms，这就是「改一步看一眼」的节奏。

blender_rt_do(code="bpy.data.objects['Cube'].location.z += 0.05", see=True)

经验：连续做 10–30 步再停下来看整体；每一步都取帧会占满主线程。

blender_rt_watch —— 判断「动没动 / 对不对」

采样一个时间窗或帧区间，返回 ≤6 帧 +逐帧 hash。hash 全相同 = 画面没变（动画没跑起来或参数没生效）。fps别开太高，每帧占主线程 55–100 ms。

blender_rt_worker —— 无 GUI 时的持久会话

常驻的blender -b进程，省掉每次冷启动。同一name复用同一进程，K持久保留：

blender_rt_worker(op="start", name="s1", preload="audit,assembly") blender_rt_worker(op="see", name="s1", from="7,-7,5", look_at="0,0,1")

细节：preload失败会直接报错（不静默少模块）；空闲 15 分钟自动回收（DSH_WORKER_TTL_MS可调）；rt_do/rt_see/rt_watch传session="s1"时都自动复用这套 worker。

🧠 第二组：规划与运维（核心入口）

blender_rt_plan —— 不确定用什么时先查它

这是整个插件的「能力目录 + 执行入口」：建模、审计、装配、交付、评估操作全在这里。第一条建议永远是：

blender_rt_plan(op="catalog") # 浏览 33 family / 217 op

高频 op 举例：

• 网格体检：audit_scene（全场景哪几个对象最脏）、audit_mesh（单件自交/法线深挖）；
• 参考图量测：img_digest（轮廓/对称/孔/可读性数字表）、img_measure、img_calib（没有标尺就只给像素，绝不编毫米）；
• 装配闭环：asm_scan（穿模/浮空/包含全分类）→asm_repair（安全修复）→asm_gate（不过门不导出）→asm_export（GLB/FBX/OBJ + manifest + 合并账本）；
• 白模参考包：blockout_base/blockout_refsheet（4 视图 PNG + 拼图 + 可选转台 MP4）；
• 多视角 QC：qc_render_views（一条命令出 N 张 + 计时 + 预算判定）；
• 强制门：gate_preflight/gate_checkpoint/gate_deliver（verdict 不是 pass 就不写盘）。

无头执行：blender_rt_plan(op="asm_scan", session="auto", args={...})会自动起 worker 并同步返回，不依赖 GUI。

blender_viewport —— 通道运维与多会话协调

并发语义很简单：写操作受租约保护，别人持有时会拿到409 leased（只读操作不受限）；收到 409 先用who看持有者，别急着force强抢。

⚙️ 第三组：自动化与长任务（不占 GUI）

blender_rt_headless —— 重活交给独立进程

独立blender -b进程，用于成品渲染、批量几何、数据校验，不占 GUI 通道、可与其他会话同时跑。要点：

• 脚本里print("HEADLESS {json}")，工具把最后一行解析成result；
• preload="audit,qc,qc_render"之类可把 runtime 模块注入K.dsh_*_api，直接调现成 API；
• shots=[...]多视角一体化出图，省掉自写相机/三点光的样板代码；
• 预计 >100 s 的活直接as_job=True：到点后台化、回jobId，超时 ≠ 失败。

blender_rt_job —— 结果永不丢的作业层

start / status / wait / collect / kill / list六个 op，参数与 headless 同形。核心价值：

• 作业不占客户端连接、不会被工具超时掐断；
• 后端重启后从磁盘台账恢复状态；
• wait阻塞等 /collect收集，kill幂等（已结束也回 ok）。

blender_rt_loop —— 把搜索放在 Blender 侧

模型回合（几秒）很贵，Blender 事件循环（160 tick/s）很便宜。所以几千次迭代级参数搜索放内环跑，决策与验收留模型侧：

blender_rt_loop(op="start", spec={ "setup": "K.ob = bpy.data.objects['Cube']", "step": "ns['params'] = {'sx': 1 + random.uniform(-0.2, 0.2)}", "measure": "ns['score'] = abs(bpy.data.objects['Cube'].dimensions.x - 2.0)", "iterations": 3000, "budget_ms": 20000, "top_k": 20}) blender_rt_loop(op="board") # 候选表 blender_rt_loop(op="stop") # 急停

纪律两条：必须给iterations或budget_ms安全阀；收敛后换一条通路复核（重新量一遍包围盒/体积），因为内环只优化你写的那个score。

🧰 第四组：场景工具（效率与保险）

blender_rt_txn —— 动手前先留回退点

• 文件级snapshot/restore：存/取整个 .blend，适合拓扑改动（Boolean、合并、删面）之前；
• 对象级mark/revert：记录并还原 transform/材质/可见性，但不含拓扑，Boolean 之后回不去。

blender_rt_preset —— 参数配方库

把「参数组合」变成可保存、可套用、可分发的资产（材质/对象/场景均可）：

blender_rt_preset(op="save", name="硬表面金属", kind="material", data='{"inputs.Metallic": 1.0, "inputs.Roughness": 0.25}') blender_rt_preset(op="apply", name="硬表面金属", targets="MAT:钢_外壳,MAT:螺栓") blender_rt_preset(op="export") # 导出 bundle 分享给别的机器

不给targets时只预览（dry_run），不实际写入。

blender_rt_perf —— 渲染慢时先量后调

status（现状基线）→analyze（每轮 CPU 同步 vs 每采样 GPU 成本的差分实测）→apply（persistent_data + 降噪 + 采样上限预设）→ 不满意revert。实测参考：2318 对象工程里，persistent_data 让重复渲染从 14.6 s 降到 0.79 s；砍采样对 CPU 侧几乎无帮助。

blender_rt_opt —— 对象精简

analyze找候选组 →join先dry_run空跑看报告 → 确认后再合并。合并规则很保守：同集合/同材质/同父级/无修改器/无动画/无形态键 →几何零损失（面数顶点数不变）。务必给save_before留快照。

🔌 第五组：addon 命令访问

blender_rt_commands —— 调命令前先问它

返回可用 addon 命令列表（常驻 + 受集成开关门控的）与 5 个集成状态。习惯：调rt_cmd之前先跑一次它。

blender_rt_cmd —— 透传任意 addon 命令

blender_rt_cmd(name="ping") blender_rt_cmd(name="get_object_info", params={"name": "Cube"})

注意按 addon 真签名传参（get_scene_info无参、get_object_info用name）——直连没有 schema 层替你改名，传错就是unexpected keyword argument。它也用于查活动状态：blender_rt_cmd get_activity_state返回idle/human/agent/both，AI 不会在你拖拽或刚撤销时把中间态当最终态。

🎯 三个最常用的组合工作流

1. 改一步看一眼（日常建模）：rt_do(see=True)连做 10–30 步 →rt_see自定义视角多角度验收（重复出图 md5 不变 = 真没变）。
2. 内环拟合 + 复核（尺寸调参）：rt_loop跑几千次迭代 →board看候选 → 换rt_do重新量一遍包围盒确认。
3. 装配交付闭环（大件项目）：asm_manifest校验清单 →asm_scan全分类 →asm_repair（safe 策略只做平移/吸附）→asm_gate→asm_export出 GLB/FBX/OBJ。

📚 延伸阅读

• 分步教程与全部参数表：docs/操作教程.md
• 配置项（工作目录/blender.exe/端口/TTL）：docs/配置参考.md
• 随包建模 skill（选形决策树 + 24 条配方 + 验收判据）：skills/blender-modeling/SKILL.md
• 假设驱动建模方法论（假设/区间/证据/三态判定）：docs/假设驱动建模-cookbook.md
• 版本演进与实测数据：CHANGELOG.md
• 项目总览：README.zh-CN.md

记住一句话：先查目录（rt_plan op="catalog"），写操作先留回退点（rt_txn），回执先看 verdict 而不是 ok——掌握这三条，15 个工具就都在你手边了。