方块工坊代理 yan-mc/blockbench-ysm-agent

DSH × Blockbench Agent

让 AI 真正走进 Blockbench：隐藏建模 · 无头渲染 · 像素贴图 · 动画 · YSM 游戏验证

📖 完整使用手册 · ⬇️ 下载 v0.4.0 ·工程状态 ·从零搭建 ·测试模型：大肥鱼

一句话：给 dsh 里的模型装上「Blockbench 的手和眼睛」——它能语义化建模、精确改贴图、无头渲染看结果、检查点回滚、保存/导出 YSM，最后在 Minecraft 里加载验证；需要人工时 /show 随时接管。

🎬 视频介绍

插件介绍视频

- B 站向介绍视频（2:46）：deepseek-blockbench-agent-intro.mp4
- 讲功能、使用与优势，不含制作过程；素材使用测试模型「DeepSeek 鲸鱼娘 / 蓝色大肥鱼」
- 封面与投稿文案：media/bilibili-upload.md、media/bilibili-cover.png

工程状态

已实现并验证：隐藏窗口 BAE、JSON-RPC bridge（WS + HTTP/SSE 双传输）、30 个 bb_ 工具、/show /hide 命令、Skill、YSM 创建/打开/保存/zip 导出、动画/贴图/图层/PBR/控制器绑定、检查点/回滚（内嵌贴图 + arm 快照）、增量保存与幂等、动画合并回写、渲染变化/空图检测、closeup/SSAA、watchdog-v2、512px 附件、GPU 降级、Client UI 状态 pill、游戏内加载验证、发布打包。当前版本 v0.4.0。

- 工程状态/实测数据：ENGINEERING.md
- 完整使用手册：MANUAL.md
- 目录地图：FOLDER-MAP.md
- 从零搭建：SETUP.md
- 实现包说明：packages/README.md
- 机器可读契约：spec/tool-manifest.json、spec/bridge-methods.json

设计文档：YSM × Blockbench 无头建模与贴图 Agent 插件

0. 先读结论（TL;DR）

| 问题 | 结论 |
| 怎么隐藏 Blockbench？ | 上游 electron/main.js 硬编码 win.show()，必须 fork 主进程（3 处小改：不 show、backgroundThrottling:false、注入 bridge 插件）；渲染层零改动。 |
| 怎么无头出图？ | 复用 Blockbench 内置离屏 Preview（MediaPreview/NoAAPreview）+ Screencam.advancedScreenshot(cb) + Blockbench.writeFile；renderer 已 preserveDrawingBuffer:true，全程无对话框。 |
| 怎么让 AI 不写原始 JSON？ | dsh 侧注册 bb_ 语义工具（建模 patch / 像素绘制 / 渲染 / 校验），底层 JSON-RPC 转给 Blockbench 插件；回执只给 changed ids + diff + 摘要，列表全部分页。 |
| 怎么让 AI「看见」？ | ctx.attachments.saveImage() + output.render() 返回 image block；全分辨率 PNG 落盘，模型按需 read_image；图片默认 512px、每轮 ≤4 张（图片会重复计费）。 |
| 怎么保证 YSM 能进游戏？ | YSM-Utils 是 UI 插件、无导出 API、只写 ysm.json；必须自研 YRL（规范化/骨架/导出编排），并强制 export_empty_groups=true（否则 30 根空定位骨骼被剪，进游戏缺手持物/鞘翅）。 |
| 怎么人机协同？ | dsh 原生 /show /hide 命令（ctx.commands.register），不消耗模型 token；GUI 期间冻结写操作，/hide 后 resync revision 并注入用户改动摘要。 |
| 通信走什么？ | 本地 WebSocket JSON-RPC 2.0（dsh 为 server，BBAR 为 client）；首包 token 鉴权；协议与传输解耦，可回退 HTTP+SSE / Python client。 |
| 最大的技术风险？ | 隐藏窗口下 WebGL 的稳定性（不同 GPU/驱动/远程桌面）。必须先用 M0 Spike 验证，再投入开发。 |

1. 交付物导航

| 文件 | 内容 | 对应需求模块 |
| 系统开发与设计方案.md | 合并版主文档（推荐通读） | 全部 |
| docs/01-总体架构与数据流.md | 架构图、进程/生命周期、数据流、ADR、目录规范 | ① 系统架构与数据流 |
| docs/02-通信协议规范.md | WebSocket JSON-RPC 2.0 规范、方法目录、错误码、超时/幂等、示例 | ② 通信协议 |
| docs/03-Tool-API-清单.md | 21 个 bb_ 工具的参数/返回/错误/预算、Tool 设计原则 | ③ Tool API 声明 |
| docs/04-闭环状态机.md | 状态机、预算/收敛/回滚、VLM 评审协议、失败恢复、伪代码 | ④ 闭环工作流 |
| docs/05-工程难点与避坑指南.md | Electron/WebGL、启动/注入、Undo/保存、贴图/UV、YSM、Token、Windows、许可 | ⑤ 工程难点 |
| docs/06-实施路线图与验收.md | M0–M6 里程碑、测试策略、验收标准、发布与团队分工 | 落地计划 |
| spec/tool-manifest.json | 机器可读工具清单（JSON Schema） | ③ 契约 |
| spec/bridge-methods.json | 机器可读 JSON-RPC 方法/事件/错误码 | ② 契约 |
| spec/generate_spec.py | 契约生成器（改一处生成两份 JSON） | 工具链 |
| ENGINEERING.md | 工程实现状态/实测数据/DSH 端完成度/已知限制（设计不变，实现以此为准） | 落地状态 |
| packages/README.md | 两个实现包的构建、测试与运行命令 | 工程说明 |
| models/ | 测试模型仓库：DeepSeek 鲸鱼娘 YSM 模型、渲染/游戏内截图、BUG 与迭代记录 | 落地工程 |
| prototype/ | dsh 插件 + BAE 主进程/preload/bridge 插件骨架；WS 协议冒烟测试已通过 | 参考实现 |
| research/blockbench-core.md | Blockbench v5.2.2 源码级研究（847 行，文件:行号） | 事实依据 |
| research/ysm-format.md | YSM 格式/插件导入导出研究（999 行，文件:行号） | 事实依据 |
| research/dsh-integration.md | dsh 插件/Tool/多模态/命令研究（565 行，取证） | 事实依据 |

2. 系统一览

flowchart LR
M["主模型 / VLM"] --> D["DBA · dsh Host 插件bb_ 工具 + /show 命令"]
D -- "JSON-RPC 2.0 over WebSocket" --> B["BABP · Blockbench 插件renderer 侧"]
B --> C["Blockbench CoreProject/Cube/Texture/Undo/Preview"]
B --> Y["YRL · YSM 资源层骨架/规范化/导出"]
C --> R["离屏 PreviewMediaPreview.render()"]
R --> P["PNG 落盘 + 附件回灌"]
P --> D
D --> M
E["BBAR · 隐藏 Electron 进程"] --- B

三条关键链路：

1. 语义编辑：bb_apply_model_patch / bb_texture_patch → 一个 Undo 事务 → revision+1 → 有界回执。
2. 无头反馈：bb_render_views → 离屏 Preview 多机位渲染 → PNG 落盘 → 降采样 → ImageBlock → 模型视觉自检。
3. 人机协同：/show 显示同一进程窗口 → 冻结 AI 写操作 → 用户手改 → /hide → 重新同步 revision。

3. 已核实的事实基线（节选）

- Blockbench v5.2.2：Electron 43 + Vue2 + three.js r129；electron/main.js 在 loadURL().finally() 中 win.show()；窗口无 backgroundThrottling。
- Preview renderer：alpha:true、preserveDrawingBuffer:true；存在离屏 MediaPreview/Screencam.NoAAPreview；Screencam.advancedScreenshot(..., cb) 在传入 cb 时不弹 UI。
- 贴图：要刷新 3D，得用 Texture.getActiveCanvas() + updateChangesAfterEdit()；Undo aspects {textures:[t],bitmap:true}。
- 保存：Codecs.*.compile()/write()、Blockbench.writeFile 不弹对话框；export()/exportFile()/Action.trigger() 会弹 native 模态（桌面端把 window.confirm/alert 换成了同步 MessageBox，会卡死 renderer）。
- 插件：source:'file' 条目按绝对路径加载；可在主进程 did-finish-load 后用 executeJavaScript 执行 new Plugin().loadFromFile({path}, false) 注入并持久化。
- YSM：ysm.json spec 2；默认主模型 64 bones / 172 cubes / 30 空骨骼（26 个 Locator）；贴图 128×128 per-face UV；动画 Bedrock 1.8、控制器 1.19；YSM-Utils 是纯 UI 插件，只写 ysm.json。
- dsh：ctx.tools.register(defineTool(...))、ctx.commands.register(...)、ctx.attachments.saveImage()、ctx.effect() 清理；图片从产生起，每次请求都会重复计费。

完整证据（文件:行号、官方文档链接）见三份 research 报告与各章末尾的引用。

4. 如何阅读

| 你的角色 | 建议顺序 |
| 架构/负责人 | 本 README → 01 → 04 → 06 |
| dsh / Agent 工程师 | 01 → 02 → 03 → prototype/dsh-plugin/ |
| Electron / 渲染工程师 | 01 §4 → 05 §1/§2 → 06 M0 |
| YSM / 建模工程师 | 03 → 05 §3/§4/§5 → research/ysm-format.md → prototype/blockbench-agent/ |
| QA | 06 §3–§5、04 §12 |

5. 原型状态（诚实声明）

| 项 | 状态 |
| 传输层（WS 握手/鉴权/双向请求/事件/并发/超时） | ✅ 已用本机 Node 24 跑通 prototype/dsh-plugin/ws-smoke-test.mjs |
| 原型所有 JS 文件语法 | ✅ node --check 全部通过 |
| Electron 隐藏窗口 + WebGL 真实出图 | ❌ 未在本机运行（需按 M0 构建 BAE） |
| YSM 默认包创建/导入/导出 | ❌ 骨架未实现完整 YRL（见 research/ysm-format.md §8.4 清单） |
| dsh 插件安装/启用 | ❌ 未安装、未修改当前 profile |
| 视觉闭环端到端（VLM） | ❌ 设计完成，待 M5 验证 |

6. 下一步（M0，1–3 天）

1. 构建 BAE：node prototype/blockbench-agent/build.mjs（需 Node ≥20、npm、网络）。
2. 启动隐藏窗口，用 executeJavaScript 对 MediaPreview 做 5 机位渲染 → 检查 PNG 非空/尺寸/alpha。
3. 连续 50 次渲染 + show/hide 往返 + 无 GPU（--disable-gpu）三组测试。
4. 结果写入 docs/M0-report.md；未通过不进入 M1。
5. 详见 docs/06 的 M0 清单。

7. 目录

F:\Deepseek_harness\blockbench\
├─ README.md # 门面：封面 / 快速链接 ├─ MANUAL.md # 完整使用手册 ├─ ENGINEERING.md # 工程状态/实测数据/已知限制 ├─ 系统开发与设计方案.md # 合并版设计主文档 ├─ docs\ # 01–06 分章 + test-evidence + assets(封面) ├─ spec\ # 机器可读契约 + 生成器
├─ packages\
│ ├─ bb-agent-runtime\ # BAE 组装/bridge/测试脚本 │ └─ dsh-blockbench-agent\ # dsh Host 插件 + Client pill + Skill ├─ models\ # 测试模型仓库 │ └─ deepseek-fish\ # 鲸鱼娘 YSM pack / 截图 / 导出 zip ├─ media\ # 介绍视频、幻灯片、构建脚本 ├─ prototype\ # 早期骨架代码（历史参考） ├─ research\ # Blockbench / YSM / dsh 研究证据 ├─ vendor\blockbench\ # 上游 v5.2.2（只读） ├─ vendor\YSM-Utils-Plugins\ # 上游 v2.6.0（只读） ├─ dist\bb-agent-app\ # 组装后的 BAE（本地运行） ├─ release\ # 发布 zip（gitignored） └─ game-test\ # 可选隔离 Forge/YSM 验证环境（gitignored）

8. 许可与声明

- 本方案与原创代码/文档：按项目需要授权；引用第三方内容遵循其原许可。
- Blockbench：GPL-3.0-or-later。BAE 是衍生发行版，发布时必须随包提供对应源码/修改说明与许可证；不得暗示官方背书。
- YSM-Utils-Plugins：MIT；复用其规范化规则/代码需保留版权与许可声明。
- YSM 默认模型：官方文档注明以 CC 0 发布（可修改分发）；用户提供的参考图/皮肤版权由用户负责。
- Minecraft：遵守 Mojang EULA，不分发原始游戏资产。