多 Agent 并行建模最佳实践:dsh-blender-plugin 冻结规格与写作用域协议详解
多 Agent 并行建模最佳实践:dsh-blender-plugin 冻结规格与写作用域协议详解
dsh-blender-plugin(DSH × Blender 直连实时插件)用 15 个模型工具让 AI 直连驱动 GUI Blender,在真实会话里完成建模、检查、验收与导出。当一个大项目拆分给多个 AI Agent 并行建模时,如何避免"各自发明常量"和"两只手抢同一个对象"?答案是它的两个核心机制:冻结规格(spec 冻结)与写作用域协议(write-scope protocol)。本文带你一步步搭起一条可复现的多 Agent 并行建模流水线。
先认识 dsh-blender-plugin:让 AI 在真实 Blender 里建模
- GUI 优先:AI 对着你正在看的场景"看一眼 → 改一步 → 再确认",无头 worker 作为备用路径;
- 15 个模型工具:交互回路(
rt_see/rt_do/rt_watch)、规划契约层blender_rt_plan(33 family / 217 op)、无头批处理与长任务、事务回滚、写租约协调等; - v2.5 起:活动状态置顶、可一键暂停 AI,Blender 原生选中/集合/子元素可直送 DSH 草稿;
- 随包
blender-modeling建模 skill,支持 WSL / Windows / macOS。
新手不用手写 bpy:先 blender_rt_plan(op="catalog") 查能力目录,有 op 就用 op。
为什么多 Agent 并行必须先上协议
并行建模的收益来自"同时做几件独立的事",而不是"让几个模型自由发挥"。没有协议时,项目实测会踩这些坑:
| 症状 | 根因 |
|---|---|
| 合并后件对不上 | 各 Agent 自造常量,没有共享口径 |
| 穿模 / 悬空被放过 | 用"看起来接上了"代替数字门 |
| 结果无法复现 | 规格没冻结,缺 manifest / md5 |
| 两个会话写同一个 .blend | 未声明写作用域、未拿写租约 |
所以第一步不是开工,而是冻结合同。
第一步:冻结规格,再分头写
所有人只读同一份 spec.py / manifest.json,不许各自定义常量。规格至少要冻结四类内容:
- 对象清单:每个件的尺寸 / 位置 / 朝向 / 材质槽;
- 接口表:谁和谁相接、接口平面、公称间隙、允许交叠(
nominal_mm/tol_mm/allow_overlap_mm); - 单位与坐标系:场景单位默认 1 BU = 1 m = 1000 mm,尺寸一律用毫米写,前向轴 -Y、上轴 +Z;
- 验收门:
audit_mesh阈值、asm_gate要跑哪些门、允许的hidden_ok交叠量。
⚠️ 关键点:规格是"只读"的。并行中任何人想改接口,必须写回 spec / manifest——不允许口头约定。
这条范式完整写在随包 skill 的 §0.5"多 Agent 并行建模的分工范式":SKILL.md §0.5。
第二步:写作用域协议——谁写哪个文件
2.1 对象前缀 + 文件隔离
- 每个 builder 只写自己的 .py 文件和对象前缀(如
COL_Geo_/COL_Lights_/COL_Camera_); - 装配前用
K.route_collections按前缀把对象归位; - 不要让两个 Agent 同时写同一个 .blend 或同一批对象。
2.2 写租约:blender_viewport lease / who / release
插件后端内置写租约机制,仲裁"谁有权写这个 Blender":
- 只读 op 豁免,写 op 必须过租约门:别人的租约生效时返回
409 {error:"leased", holder, expiresInMs},并提示等待或抢占; - 并行开始前,各会话用
blender_viewport op=lease声明自己的 collection / prefix 作用域,op=who查询当前持有者; - 持有者探活:持有者进程消失时租约自动回收,避免死锁;确需接管才用
force:true抢占; - 干完活主动
op=release,不要占着租约阻塞其他会话。
实现可对照:runtime/server.mjs(POST /lease 路由、409 回执与探活回收)。
七角色并行分工模板(skill 默认模板)
| 角色 | 只管什么 | 可写范围 |
|---|---|---|
| Lead / 架构 owner | 冻结 spec.py / manifest、选路线、分配写作用域、最后跑 asm_gate |
规格与清单(其余人只读) |
| Reference builder | img_digest/probe/measure/calib → 尺寸表 → 回写 spec |
不写几何 |
| Blockout builder | blockout_base/batch 出白模 + 3 视图 |
只写自己前缀的对象 |
| Shape / vehicle / human builder | 按 spec 生成主形体,输出 bbox / 截面对照 | 只写自己前缀 |
| Detail builder | 硬表面细节 / 布尔 / 阵列 / 扫掠,改拓扑前 checkpoint | 只写自己前缀 |
| Assembly owner | asm_manifest → asm_scan → asm_repair(policy=safe) → asm_gate |
只做装配层 |
| Verifier | 独立跑 audit / asm / visualreport / eval,不采信 builder 的结论 | 只读 |
完整分工与装配协议见 SKILL.md §10.8。
并行期的固有代价:单件自证 + 装配后复检
并行期间各件无法互测,这是并行的固有代价,按两段消化:
并行中——单件自证
audit_mesh网格审计;- 尺寸 / bbox 数字对照 spec;
- 单件渲染留视觉证据。
装配后——复检消化
asm_manifest校验清单(id / 文件 / md5 / 接口帧 / allow 列表);asm_scan全对全分类:clash / hidden_ok / contact / gap / float / contained / unresolved;asm_repair(policy="safe")只做低风险平移 / 吸附;布尔、缩放等高风险动作交人工确认;asm_gate用 manifest 连接图判浮空 / 接口偏差,export_allowed只在 pass 时为 true;asm_export导出 GLB / FBX / OBJ + manifest + 合并账本(merge ledger)。
📌
hidden_ok(设计内隐藏交叠)不是穿模,修之前先读 manifest 的 allow 列表;更不要为了让 scan 变绿而乱扩 allow,否则真穿模会被藏起来。
四个并行反模式:出现就返工
| 反模式 | 为什么错 | 正确做法 |
|---|---|---|
| 各 Agent 自造常量、自写验收判据 | 合并时件对不上,且没人能复现 | 只读冻结的 spec |
| 用"看起来接上了"代替数字 | 穿模 / 悬空被眼睛放过 | 数字门 + 同机位 visualreport |
| 未判连接关系直接 Boolean / Weld | destructive_guard 会拦,拓扑易损坏 |
先注册连接 / 接口再改 |
把 hidden_ok 当穿模修 |
设计内交叠被当成缺陷 | 先读 manifest 的 allow 列表 |
回执阅读纪律:先看 verdict,再看 ok
所有 gate / audit / asm / visualreport / eval 回执都是 pass / fail / degraded 三态:
ok只表示"跑完了",不代表通过;degraded≠ pass,要补证据并显式说明,不能静默变绿;- 门里出现
skipped,等于没检查,不能当通过。
这正是多 Agent 验收的分界:Verifier 独立复跑数字门,不采信任何 builder 的"我做完了"。
相关文档与模块路径
想深入,可按这份索引阅读仓库文件:
- 多 Agent 分工范式与写作用域协议:skills/blender-modeling/SKILL.md(§0.5)、§10.8 七角色分工;
- 写租约实现:runtime/server.mjs(
POST /lease路由与 409 语义); - 验收清单:skills/blender-modeling/references/验收清单.md;
- 假设驱动建模(区间 / 证据 / 三态判定):docs/假设驱动建模-cookbook.md;
- 操作教程(从零上手 → 连通 → 工具 → 配方 → 排错):docs/操作教程.md;
- 中文 README(安装步骤与验收判据):README.zh-CN.md;
- Blender 侧桥接 addon(原生选中、活动状态、暂停 AI):addon/dsh_blender_bridge.py。
小结
dsh-blender-plugin 的多 Agent 并行建模可以浓缩成一句话:先冻结合同(spec / manifest),再声明写作用域(lease / prefix);并行期做单件自证,装配后用 asm_* 复检消化,门不 pass 不导出。 把这四步走顺,多 Agent 协作才不会退化成"自由发挥建模"。