Three.js 工作台 Elmeis/dsh-plugin-threejs-workbench

dsh-plugin-threejs-workbench — DeepSeek Harness 的 Three.js 工作台

DSH Web UI 里有两个界面，共用同一个主机路由前缀（/api/threejs）：

1. 实时预览会话工作区里的场景文件。 点击标题栏的 chip 会打开一个滑出式抽屉（shell.overlay），左侧是项目报告，右侧是 iframe。iframe 由主机作为真实页面提供：import map 把 three、three/webgpu、three/tsl、three/addons/ 和 three/examples/jsm/ 映射到项目自己安装的 three，或映射到本插件内置的副本（three 0.186.1 —— 包含 build/ 和完整的 examples/jsm/ 目录树，所以 three/addons/* 可以离线解析）；bootstrap 模块导入选中的文件，并调用它导出的入口点（init / start / createScene / setup / main / default）；错误/控制台桥接把每个页面错误、未处理的 rejection 和 console. 调用都镜像到抽屉的控制台条 —— 不用离开 harness 就能观察智能体写的代码。.html 目标按原样提供，只注入桥接和 import map。Reload 会重建 frame；「Open in tab」把同一页面放到普通浏览器标签页里打开（iframe 内允许 pointer lock、WebXR、gamepad 和全屏）。
2. 项目检查器。 每个会话扫描一次（缓存 20 秒，点 Rescan 重新扫描），报告：
- 解析出的 three 版本及其来源（项目安装、提升到祖先目录的安装，或内置副本），以及 package.json 里声明的版本；
- 声明的技术栈（@react-three/fiber、drei、postprocessing、Rapier、cannon-es、GSAP……）；
- WebGL 还是 WebGPU，以及排好序的场景入口候选 —— 即导入 three、创建渲染器、驱动帧循环并挂载 canvas 的文件；
- 新版本删除或改名的 three API，以 file:line:column 形式列出，并给出替代写法，例如 outputEncoding（r152）、sRGBEncoding（r152）、useLegacyLights（r186 已移除）、WebGL1Renderer（r163）、THREE.Geometry（r145）、three/examples/js/（r148）、WebGPURenderer 的 addon 路径（r167）、RGBELoader（r180）、PCFSoftShadowMap（r186）、写错的 tsl/display/ 文件名、PI2、applyGeometry、postprocessing → RenderPipeline；
- GLB/GLTF/HDR/KTX2/DRACO 资源的体积，90 MB 的模型在发布前就能看到。

数据从哪里来

主机侧在共享 web 服务器上注册一个前缀路由。每个路由都接收会话 id，并从主机会话存储（ctx.sessions.get(id).header.cwd）解析工作目录 —— 客户端从不提供路径根，未知会话返回 400，而不是回退。该根目录下的文件经过 realpath 包含性检查后，通过 token 绑定的字节路由（/api/threejs/r/<token>/…）提供，所以符号链接和 .. 都无法越界；three 包根目录（~three/、~addons/）会对照它们自己的目录。文件以流式传输，从不缓冲，所以几百 MB 的 GLB 也原样送出。主机上不写入任何内容，也不执行任何内容。

cwd=<absolute dir> 可作为回退根目录，供没有会话的调用方使用；它是唯一不来自会话存储的路由输入。

安装

DSH Desktop：Settings → Plugins → add plugin，输入包名。命令行方式：dsh plugin --profile <your-profile> add <name>，然后重启 harness。

name: dsh-plugin-threejs-workbench

检查

node test/smoke.mjs # host routes + containment + client render (react-dom/server)
node test/browser-check.mjs # real headless Chrome loads the preview page for test/fixture

浏览器检查会在回环端口上启动插件自己的 handler，让一个 stub 会话指向 test/fixture，再在无头 Chrome 中加载 /api/threejs/preview?session=fixture-session&path=src/scene.js（系统 Chrome 或 Playwright 无头 shell）。当桥接层报告 loaded scene.js / calling export init() 且没有出现错误行时，检查通过——也就是说，three 从插件 bundle 加载，fixture 场景在真实 WebGL 上下文中完成初始化。

限制

- 只运行 ES 模块。.ts/.tsx/.jsx 入口会被报告出来，并显示「build it first」提示，而不会编译；请把预览指向构建后的 .js 输出。
- 检查器是文本扫描，不是类型检查器：检查结果来自官方迁移指南的正则规则。当某个标识符只是与已移除的 API 同名时，结果可能是误报；three/addons/tsl/display 的文件名漂移只会对已知改名的名称做捕获。扫描会跳过本插件自己的包目录，因为 lib/index.js 里的规则表本身就包含它要查找的那些 API 名称。
- 项目没有安装副本时，使用随附的 three（0.186.1）；报告会说明这一点，抽屉标题栏会显示当前生效的是哪一份副本。
- 预览渲染取决于浏览器：软件 WebGL 很慢，WebGPU 场景需要支持 WebGPU 的浏览器（WebGPURenderer 会自行回退到 WebGL 2）。
- 抽屉是只读的：不能编辑场景，也不会在文件写入时热重载——请按 Reload（会话中的文件改动对下一次扫描可见）。