0. 一句话结论#

agent 不通过 UI、也不通过图形化 API，而是往 Blender 的 Python 里注入代码（blender_rt_do），配合一套判定/QC/交付算子（blender_rt_plan，28 family / 186 op）在 GUI 会话、独立无头进程、后台作业三种通路上跑。核心设计是”改一步看一眼 + 用数字验收，不靠肉眼”。

能做什么（实测过）：参数化硬表面件建模、网格体检、制造性（壁厚/悬垂）检查、多视角对照渲染、对象级与文件级回退、程序化材质、OBJ/MTL + manifest 交付与逐项校验、无头批处理与作业台账。

1. 环境与架构#

1
blender_viewport(op="who")                        # 看谁持有
2
blender_viewport(op="lease", holder="my-agent", ttl_ms=900000)
3
blender_viewport(op="release", holder="my-agent")
4
blender_viewport(op="lease", force=true)          # 抢占（默认 false）

2. 开工前自检（照抄即可）#

1
# ① 后端在不在
2
curl -sS -m 5 -o /dev/null -w "%{http_code}\n" http://127.0.0.1:9877/health   # 期望 200
3

4
# ② Blender 在不在（看 9876 有没有人听）—— 没有就一键拉起
5
ss -tln | grep 9876 || echo "addon 未连"

1
# ③ 一键拉起 GUI Blender 并自动 Connect addon（幂等，不必有人点面板）
2
blender_viewport(op="launch", wait_ms=120000)
3

4
# ④ 三级体检（真跑一次 bpy 往返）
5
blender_viewport(op="doctor")
6

7
# ⑤ 命令清单 + 集成开关状态
8
blender_rt_commands
9

10
# ⑥ 算子目录（本地直出，不占 Blender 往返）
11
blender_rt_plan(op="catalog")

本次实测输出（可作为对照）：

1
LAUNCH ok · 已 spawn pid=297893 · addon 端口 9876 · 等待 2012ms
2
启动后体检：通道健康：TCP + ping + bpy 往返都通
3
blender_rt_commands → 场景 Scene · 未保存文件
4
                     可用命令 19 条；被集成开关挡住 15 条
5
                     集成：polyhaven=off · hyper3d=off · sketchfab=off · polypizza=off · hunyuan3d=off
6
blender_rt_plan(op="catalog") → 28 个 family / 186 个 op
7
                                 loaded engine.mjs c8f256a06bf2 · 磁盘 c8f256a06bf2 · 一致

⚠ 没启动 Blender 时 blender_rt_commands 直接失败：COMMANDS 失败 · connect ECONNREFUSED 127.0.0.1:9876。先 launch 再干活。

3. 算子全貌：28 个 family#

从 blender_rt_plan(op="catalog") 抄录（未标 ✅ 的家族本次未逐个实测）：

4. 实操：五步做出一个参数化齿轮（全部实测）#

目标：12 齿 / 模数 2 / 齿宽 6 mm / 中心孔 ⌀8 mm 的直齿轮，并给出客观验收指标。

1
import bpy, bmesh, math
2

3
for ob in list(bpy.data.objects):            # 清场
4
    bpy.data.objects.remove(ob, do_unlink=True)
5
for me in list(bpy.data.meshes):
6
    if me.users == 0:
7
        bpy.data.meshes.remove(me)
8

9
N, m, W, RB = 12, 2.0, 6.0, 4.0             # 齿数/模数/齿宽/孔半径
10
RP, RA, RF = m*N/2, m*N/2 + m, m*N/2 - 1.25*m   # 分度圆/齿顶圆/齿根圆 = 12/14/9.5
11
P, SEG = 2*math.pi/N, 24                     # 每齿 24 段采样
12

13
def r_of(t0):
14
    t = (t0 % P) / P
15
    f = t/0.18 if t < 0.18 else (1.0 if t < 0.82 else (1.0-t)/0.18)
16
    return RF + (RA-RF) * max(0.0, min(1.0, f))
17

18
bm, n = bmesh.new(), N*SEG
19
vo = [bm.verts.new((r_of(2*math.pi*i/n)*math.cos(2*math.pi*i/n),
20
                    r_of(2*math.pi*i/n)*math.sin(2*math.pi*i/n), 0.0)) for i in range(n)]
21
vi = [bm.verts.new((RB*math.cos(2*math.pi*i/n), RB*math.sin(2*math.pi*i/n), 0.0)) for i in range(n)]
22
bm.verts.ensure_lookup_table()
23
for i in range(n):
24
    j = (i+1) % n
25
    bm.faces.new((vo[i], vo[j], vi[j], vi[i]))     # 外齿廓 ↔ 内孔 之间的环
26
bmesh.ops.recalc_face_normals(bm, faces=bm.faces[:])
27
ret = bmesh.ops.extrude_face_region(bm, geom=bm.faces[:])          # 挤出齿宽
28
bmesh.ops.translate(bm, vec=(0,0,W),
29
                    verts=[e for e in ret['geom'] if isinstance(e, bmesh.types.BMVert)])
30
bmesh.ops.recalc_face_normals(bm, faces=bm.faces[:])
31

32
me = bpy.data.meshes.new("SpurGear"); bm.to_mesh(me); bm.free()
33
ob = bpy.data.objects.new("SpurGear_12T_m2", me)
34
bpy.context.scene.collection.objects.link(ob)
35
K.gear = ob.name                                  # 存进持久内核，下次调用直接用

1
import bpy, math
2
ob = bpy.data.objects[K.gear]
3
r = [ob.matrix_world @ v.co for v in ob.data.vertices]
4
Rmax = max(math.hypot(p.x, p.y) for p in r)
5
Rmin = min(math.hypot(p.x, p.y) for p in r)
6
zmax, zmin = max(p.z for p in r), min(p.z for p in r)
7
print("最大半径 %.3f / 最小半径 %.3f / 高度 %.3f" % (Rmax, Rmin, zmax-zmin))

1
SPEC     : 齿顶圆半径 14.000 / 齿根圆半径 9.500 / 孔半径 4.000 / 齿宽 6.000
2
MEASURED : 最大半径 14.000 / 最小半径 4.000 / 高度 6.000
3
CHECK    : 齿顶 OK | 孔 OK | 齿宽 OK
4
VOLUME   : 3003.7 mm^3 (网格法)

1
blender_rt_plan(op="audit_mesh", args={"objects": ["SpurGear_12T_m2"]})

1
{ "ok": true, "clean": true, "state": "pass", "verdict": "pass",
2
  "totals": { "objects":1, "tris":2304, "boundary_edges":0, "nonmanifold_edges":0,
3
              "degenerate_faces":0, "loose_verts":0, "self_intersections":0,
4
              "normals_inverted":0, "normals_checked":1 },
5
  "objects":[{ "name":"SpurGear_12T_m2", "closed":true, "normals_outward":true,
6
               "signed_volume":3003.702415, "self_intersections_analyzed":true,
7
               "state":"pass" }] }

1
blender_rt_see(from="42,-42,34", look_at="0,0,3", max_size=640)

1
blender_rt_plan(op="qc_render_views", args={
2
  "views": [{"name":"hero","from":[42,-42,34],"look_at":[0,0,3],"lens":50},
3
            {"name":"front","from":[0,-70,3],"look_at":[0,0,3],"lens":50},
4
            {"name":"side","from":[70,0,3],"look_at":[0,0,3],"lens":50},
5
            {"name":"top","from":[0,0,70],"look_at":[0,0,3],"lens":50}],
6
  "res":[960,540], "samples":48, "outdir":"/home/zero/.dsh-blender-rt/out/doc_gear"})

5. 实操：回退（两种粒度，别用错）#

实测（破坏 → 回滚）：

1
# 1) 建回退点
2
blender_rt_txn(op="mark", label="before-move", objects="SpurGear_12T_m2")
3
# 2) 故意破坏
4
#    ob.location = (30,-12,5); ob.scale = (1.8,1.8,1.0)
5
#    → 破坏后 : loc=(30.0,-12.0,5.0) scale=(1.8,1.8,1.0) dims=(50.1,50.1,6.0)
6
# 3) 回滚
7
blender_rt_txn(op="revert", label="before-move")
8
#    → 回滚后 : loc=(0.0,0.0,0.0) scale=(1.0,1.0,1.0) dims=(27.8,27.8,6.0)   CHECK OK

文件级快照实测：TXN snapshot ok · 快照 gear-baseline · 124764B · 77ms · 1 对象 → snapshots/gear-baseline.blend。

6. 实操：交付（OBJ/MTL + manifest，逐项校验）#

1
blender_rt_plan(op="deliver_export", args={"objects": ["SpurGear_12T_m2"]})
2
blender_rt_plan(op="deliver_verify", args={"path_or_dir": "/home/zero/.dsh-blender-rt/deliver"})

实测：导出 model.obj(107989 B, md5 b376f0c24d13…) + model.mtl(287 B, md5 33fb7c7b17fb…) + model_manifest.json。

deliver_verify → passed=18 / failed=0，逐项核对：md5、字节数、三角面数、g/usemtl 计数、法线行数、bbox 与清单一致性、最长边归一化、单位说明、归一化可反推性。

两个必须知道的交付语义：

1. 默认做单位盒归一化（target_half_extent=1），并给出还原公式： p_orig = p_out / scale + center（本次 scale=0.071855651, center=[0,0,3]）
2. 对象没材质时，MTL 的 Kd 用名字 md5 派生的确定性灰阶，并在 guessed_colors 里点名——“不是真值”会被明确写出来。

7. 实操：制造性检查（print_report）#

先把单位设对（我按”毫米数值”建模，所以让 1 场景单位 = 1 mm）：

1
import bpy
2
bpy.context.scene.unit_settings.system = 'METRIC'
3
bpy.context.scene.unit_settings.length_unit = 'MILLIMETERS'
4
bpy.context.scene.unit_settings.scale_length = 0.001     # 1 单位 = 1 mm

1
blender_rt_plan(op="print_report", args={"objects":["SpurGear_12T_m2"],
2
                                          "min_mm":1.2, "max_angle_deg":45})

实测：walls_ok=true、overhang_ok=true，最薄处 4.887 mm、p05 4.9827、中位 6、最大 9.9994；超 45° 悬垂面积 0 mm²；贴床面 500.62 mm²（占全表面 23.4%）。

并且它主动否证了我给的阈值：

1
warning: min_mm=1.200 低于本网格的测量分辨率 1.354 mm：
2
         几何本身分辨不出这么薄的壁，结论不可信（先细化/降 voxel_size）

这是这套工具最有价值的行为之一：测不出来就说测不出来，不给假通过。resolution_mm / ray_precision_mm 都会一并给出。

8. 实操：材质与参数化复用#

1
blender_rt_plan(op="material_build", args={"name":"M-gear","preset":"metal_brushed",
2
                                           "params":{"base_color":[0.72,0.74,0.78],"scale":30}})
3
# → ok · 7 nodes / 7 links · ms=3
4
blender_rt_plan(op="material_apply", args={"material":"M-gear",
5
                                           "objects":["SpurGear_12T_m2"], "replace":True})
6
# → slots_before=0 → slots_after=1

1
blender_rt_plan(op="generator_save", args={"name":"sprocket",
2
    "params":{"n":12,"m":2.0,"w":6.0,"bore":4.0},
3
    "code":"<一段用 PARAMS 的 bmesh 代码>"})
4
# → ok · path=/home/zero/dsh_generators/sprocket.py · sidecar=.json · hash=42b3c3f6d0d6

1
PARAMS = {"n": 16, "m": 2.0, "w": 5.0, "bore": 4.5}
2
ns = {"PARAMS": PARAMS, "__name__": "__main__"}
3
exec(compile(open("/home/zero/dsh_generators/sprocket.py").read(), "sprocket.py", "exec"), ns)

9. 无头批处理与作业台账#

1
blender_rt_headless(engine="none", script='''
2
import json, bpy
3
out = {"ok": True, "blender": ".".join(map(str, bpy.app.version)),
4
       "file": bpy.data.filepath or "(factory startup)",
5
       "objects": len(bpy.data.objects)}
6
print("HEADLESS " + json.dumps(out, ensure_ascii=False))
7
''')

契约：脚本里 print("HEADLESS " + json.dumps(obj))，必须是单行 JSON，会被解析进 resultJson。

实测：status=finished · exit=0 · 431ms，resultJson={"ok":true,"blender":"5.2.2","file":"(factory startup)","objects":3}。

• 产出物在 outdir，日志在 logs.stdout/stderr，过程用 DSH_STAGE 打点（boot → engine-prelude → preload-done → script-end → done）
• runId 可追溯：blender_rt_job(op="status", id="run-mvbcrpjhn6kp") → status=done, exit=0, ms=431（run 与 job 同一 id 空间）
• 预期 >100 s 的活：rt_headless(as_job=true) 或 rt_job(op="start")，用 op=wait/collect 回收；超时 ≠ 失败
• 参数细节：blender_rt_plan(op="catalog", args={"tool":"rt_headless"})

无头是独立会话：看不到 GUI 里那个齿轮（实测 file="(factory startup)"）。要基于同一场景干活就传 file=<.blend>。

10. 关键坑（本次实测，10 条）#

1. 异常也回传 partial stdout —— 这条极其有用。我写错 is_manifold 时，报错回执里先给出了出错前已打印的验收结果，不用重跑就能看到进度。写脚本别怕中途抛错，前面 print 的信息不会丢。
2. Blender 的 --python 抛异常时退出码仍是 0 —— 只看 exit 会漏判。generator_run 自己就是用「回执 + stderr 异常标记」判的，并明确写 verdict: "refuted"。自己写批处理时务必也检查 stderr。
3. 参数名写错会回 did_you_mean + 完整签名 —— 别猜，直接按它重发。实测两次踩到：
   • audit_mesh(name=...) → 参数不匹配: unexpected keyword argument 'name'，回执给出 audit_mesh(objects|scope, envelope, eps_area, self_intersect)
   • deliver_verify(dir=...) → 正确是 path_or_dir
   • material_apply(objects=...) → 少了必填的 material
4. montage family 本机是坏的 —— blender_rt_plan(op="montage", ...) 和 op="montage_help" 都抛内部 TypeError: can only concatenate str (not "dict") to str（dsh_blender_bridge.py:2135 → 生成的代码里）。要用拼图就自己用 PIL 做。
5. generator_run 缺共享内核 —— 报 RuntimeError: generator 需要共享内核 K.dsh_kit（由 KERNEL_BOOTSTRAP 注入）。有意思的是几何代码本身跑成功了（stdout 有 GEN n=20 m=1.5 -> 外径 33.0 齿宽 4.0），只是包装层起不来。变通：直接 exec 配方文件（见 §8.2）。
6. 不要用 AABB 验收旋转对称体 —— 见 §4 Step 2，误差可达 0.6%。
7. MeshEdge 没有 is_manifold —— 那是 bmesh 的 BMEdge 才有的属性。bpy.data.meshes[].edges[] 上取会 AttributeError；非流形检查要 bm = bmesh.new(); bm.from_mesh(me)。
8. mm 口径的检查先设 scene.unit_settings.scale_length —— 否则 print_* / audit_* 的 mm 阈值全是错的（默认 1 单位 = 1 m，我的 28 单位齿轮会被当成 28 米）。
9. 阈值低于网格分辨率时结论不可信 —— print_report 会主动报 min_mm=1.200 低于本网格的测量分辨率 1.354 mm。要么细化网格（降 voxel_size），要么别用这么严的阈值。
10. 无头会话与 GUI 会话是两个世界 —— 变量、场景、甚至 bpy.data 都不共享。blender_rt_do 的 K 只在 GUI 会话里持久；rt_worker 里的 K 只在那个 worker 里持久。

11. 从零复现清单（可直接粘贴）#

1
# ── A. 确认 Blender 存在 ────────────────────────────────────────────
2
ls -d /home/zero/.local/opt/blender-*/
3
/home/zero/.local/opt/blender-5.2.2-linux-x64/blender --version    # 期望 Blender 5.2.2 LTS
4

5
# ── B. 后端在不在 ───────────────────────────────────────────────────
6
curl -sS -m 5 -o /dev/null -w "%{http_code}\n" http://127.0.0.1:9877/health   # 期望 200
7
ss -tln | grep 9876 || echo "addon 未连 —— 需要 launch"

1
# ── C. 拉起 + 体检 ──────────────────────────────────────────────────
2
blender_viewport(op="launch", wait_ms=120000)   # 期望：LAUNCH ok · addon 端口 9876 · ~2s
3
blender_viewport(op="doctor")                   # 期望：TCP + ping + bpy 往返都通
4
blender_rt_commands                             # 期望：19 条常驻命令可用
5
blender_rt_plan(op="catalog")                   # 期望：28 family / 186 op
6

7
# ── D. 建一个 12 齿齿轮 ─────────────────────────────────────────────
8
blender_rt_do(code="<§4 Step 1 的代码>", see=false)         # 期望 ACT ok · ~40ms
9
blender_rt_do(code="<§4 Step 2 的半径验收>", see=false)      # 期望 最大半径 14.000 / 孔 4.000 / 齿宽 6.000
10

11
# ── E. 体检 ────────────────────────────────────────────────────────
12
blender_rt_plan(op="audit_mesh", args={"objects":["SpurGear_12T_m2"]})
13
#   期望：clean=true / state=pass / boundary_edges=0 / nonmanifold_edges=0
14

15
# ── F. 看一眼 ──────────────────────────────────────────────────────
16
blender_rt_see(from="42,-42,34", look_at="0,0,3", max_size=640)   # 期望 ~300ms 出图
17

18
# ── G. 制造性（先设单位！）──────────────────────────────────────────
19
blender_rt_do(code="<§7 的 unit_settings 三行>", see=false)
20
blender_rt_plan(op="print_report", args={"objects":["SpurGear_12T_m2"],
21
                                         "min_mm":4.0, "max_angle_deg":45})
22
#   期望：walls_ok=true / overhang_ok=true / min_mm≈4.9
23
#   注：阈值别低于网格 resolution_mm，否则工具会判"结论不可信"
24

25
# ── H. 多视角 QC ───────────────────────────────────────────────────
26
blender_rt_plan(op="qc_render_views", args={"views":[{"name":"hero","from":[42,-42,34],
27
    "look_at":[0,0,3],"lens":50}], "res":[960,540], "samples":48,
28
    "outdir":"/home/zero/.dsh-blender-rt/out/mygear"})
29
#   期望：ok=true + 逐张 md5 + render_views.jsonl
30

31
# ── I. 交付 + 校验 ─────────────────────────────────────────────────
32
blender_rt_plan(op="deliver_export", args={"objects":["SpurGear_12T_m2"]})
33
blender_rt_plan(op="deliver_verify", args={"path_or_dir":"/home/zero/.dsh-blender-rt/deliver"})
34
#   期望：passed=18 failed=0
35

36
# ── J. 无头通路自检 ────────────────────────────────────────────────
37
blender_rt_headless(engine="none", script='import json,bpy;print("HEADLESS "+json.dumps({"ok":True,"v":".".join(map(str,bpy.app.version))}))')
38
#   期望：runId + resultJson.ok=true + exit=0

回退点建议：动手改几何前先 rt_txn(op="snapshot", label="...")；改 Boolean/合并/删面之后只能用文件级 restore。

12. 证据清单（本次真实输出汇总）#

13. 未验证 / 已知受限#

未验证（不要当成已验证）：

• 5 个集成开关全为 off：polyhaven / hyper3d / sketchfab / polypizza / hunyuan3d（15 条命令被挡）。文档里列出的相关 op 一律未测。
• sculpt / sweep / shape / vehicle / clearance / human / face / img / calib / gate / pipe / plan / contract / uv / fix / ext / motion / render_guard / render / gui / qc(比对) / img(量图) 家族本次未逐个实测，§3 的说明来自 catalog 自述。
• blender_rt_loop（内环参数搜索）、rt_worker（热会话）、rt_preset（配方库）、rt_watch、rt_pick、rt_opt、rt_perf 未测。
• audit_gate / audit_connectivity / audit_interference / audit_drift 未测（多零件装配门）。

已知坏/受限：

• montage family 报内部 TypeError（§10.4）
• generator_run 报缺 K.dsh_kit（§10.5），变通是直接 exec 配方
• 对象级 revert 不含拓扑/UV/顶点级改动（Boolean、合并、删面之后回不去）
• qc_render_views 三点光打在无材质白模上会过曝（尤其俯视）
• 无头进程看不到 GUI 场景（本该如此，但脚本容易写错）

14. 下载与安装清单（含链接 · 2026-10-17 实测可达性）#

本机访问国际站点必须走代理 http://127.0.0.1:7897：实测 Blender 的 tar.xz 直连 403、走代理 206。下面所有 curl 都带 -x。 表中「实测」列是本次 curl 的真实 HTTP 码，未实测的一律标注。

1
mkdir -p ~/.local/opt && cd ~/.local/opt
2
curl -x http://127.0.0.1:7897 -sSL -o blender.tar.xz \
3
  https://download.blender.org/release/Blender5.2/blender-5.2.2-linux-x64.tar.xz
4
tar xf blender.tar.xz && rm blender.tar.xz
5
mkdir -p ~/.local/bin
6
ln -sf ~/.local/opt/blender-5.2.2-linux-x64/blender ~/.local/bin/blender
7

8
# 验收
9
/home/zero/.local/opt/blender-5.2.2-linux-x64/blender --version   # 期望 Blender 5.2.2 LTS

1
cd <解包后的 dsh-blender-plugin>/
2
bash scripts/build.sh        # 链接依赖 + 编译 lib/（需 bash + node/npm 在 PATH）
3

4
# 再按 bundle 方式装进 profile：
5
#   1) node_modules/@dsh-external/dsh-blender-plugin 建软链
6
#   2) profile 的 package.json：dependencies 加 "link:" + dsh.profile.bundles 各加一行
7
dsh --profile <profile> --dump-config      # 预演，确认没配错
8
# 最后重启 DSH

附：与 ComfyUI 侧的分工#