前言¶
在 DeepSeek Harness（DSH）里用智能体改 Three.js 项目时，常见做法是反复在本地起 dev server、切浏览器看 canvas，或自己 grep 废弃 API 和模型体积。这些步骤和会话里的工作区是割裂的，Agent 写的场景代码也不容易在 Harness 内直接观测运行结果与控制台输出。
下面介绍的 dsh-plugin-threejs-workbench（维护者 Elmeis，分类为客户端插件）在 DSH Web UI 里提供两块能力：工作区场景文件的实时预览，以及针对当前会话工作目录的项目检查报告。宿主侧统一挂在 /api/threejs 路由前缀下，文件从会话 cwd 解析并提供给预览 iframe，不依赖 Agent 自行拼启动命令。
这是什么¶
插件全名 dsh-plugin-threejs-workbench，当前版本 0.1.0（MIT 许可证）。它面向在 DSH 会话中开发 Three.js（含 WebGL / WebGPU 相关栈）的场景：一边在抽屉里跑场景入口，一边汇总 three 版本来源、生态依赖、入口候选、迁移类 API 告警和资源体积。
核心功能¶
实时场景预览¶
Header 上的 chip 打开侧滑抽屉（shell.overlay）：左侧是项目报告，右侧是 iframe 内的 live preview。
预览页由宿主以真实页面形式提供：
- Import map 将
three、three/webgpu、three/tsl、three/addons/、three/examples/jsm/映射到项目已安装的 three，或映射到插件内置副本（three 0.186.1，含build/与完整examples/jsm/，离线可解析three/addons/**）。 - 引导模块 导入你指定的场景文件，并调用其导出入口（按顺序尝试
init/start/createScene/setup/main/default）。 - 错误与控制台桥接 把页面 error、未处理的 rejection 以及
console.*同步到抽屉内的控制台条，无需离开 Harness 即可观察 Agent 代码行为。
若入口是 .html，原样提供并在页面中注入桥接与 import map。Reload 会重建 iframe；「Open in tab」可在普通标签页打开同一页面（iframe 内仍允许 pointer lock、WebXR、gamepad、全屏等能力）。
项目检查器（Project inspector）¶
每个会话扫描一次，结果缓存 20 秒；可点 Rescan 重新扫描。报告内容包括：
- 解析到的 three 修订版本及来源（项目安装、向上 hoist 的安装，或内置 bundle），以及
package.json中声明的版本； - 声明的相关栈（如
@react-three/fiber、drei、postprocessing、Rapier、cannon-es、GSAP 等）； - WebGL 与 WebGPU 使用情况，以及按启发式排序的「场景入口候选」——导入 three、创建 renderer、驱动帧循环并挂载 canvas 的文件；
- 较新版本 移除或重命名 的
threeAPI，以file:line:column形式列出并给出替换说明（规则来自官方迁移指南，例如outputEncoding/sRGBEncoding（r152）、useLegacyLights（r186 前移除）、WebGL1Renderer（r163）、THREE.Geometry（r145）等）； - GLB / GLTF / HDR / KTX2 / DRACO 等资源体积统计，便于在提交前发现过大模型。
数据与安全边界¶
宿主在共享 Web 服务器上注册 /api/threejs 前缀。路由携带 session id，工作目录来自宿主会话存储（ctx.sessions.get(id).header.cwd）；客户端不能自行指定路径根，未知 session 返回 400。
工作区根下的文件经 token 绑定字节路由（/api/threejs/r/<token>/…）提供，先做 realpath containment 检查，避免 symlink 与 .. 逃逸；three 包根（~three/、~addons/）单独校验。大文件流式传输、不在宿主缓冲或执行。无 session 的调用方可使用 cwd=<absolute dir> 作为唯一非会话-derived 的根路径参数。
安装与启用¶
DSH Desktop：Settings → Plugins → add plugin，输入包名。
CLI：
dsh plugin --profile <your-profile> add dsh-plugin-threejs-workbench
安装后需 重启 harness。包名：
name: dsh-plugin-threejs-workbench
运行环境要求（来自 package.json）：Node >= 20，dsh >= 0.2.1-0 且 < 0.3.0。
插件以当前 DSH 进程权限运行；安装前建议阅读 GitHub 仓库 源码与 MIT 许可证。
典型用法¶
README 未给出单独的业务场景脚本；实际流程与会话工作区绑定：
- 在 DSH 中打开含 Three.js 项目的会话，确保工作区
cwd指向该项目根。 - 通过 Web UI header chip 打开 Three.js workbench 抽屉：左侧查看 inspector 报告（版本、栈、API 告警、资源体积），右侧 iframe 预览指定场景文件。
- 预览 URL 形态由宿主提供，例如测试中使用：
/api/threejs/preview?session=<session-id>&path=<相对工作区的场景文件>
- 修改工作区文件后，预览 不会 自动热更新；在抽屉中按 Reload。Inspector 需点 Rescan（或等待缓存过期）才能反映新扫描结果。
若场景入口是 .ts / .tsx / .jsx，插件会提示需先构建，预览应指向构建产出的 .js。
适用场景与限制¶
适合：在 DSH 会话里与 Agent 协作写 Three.js / R3F 项目，需要快速看 canvas、控制台和版本/API/资源清单，且希望无项目内 three 时仍能用内置 0.186.1 离线预览。
需注意：
- 仅支持 ES module 入口；TypeScript/JSX 需先编译。
- Inspector 为 文本正则扫描，非类型检查；可能与标识符同名的 API 产生误报；已知
three/addons/tsl/display文件名变更仅覆盖规则表中的名称。 - 扫描会跳过插件自身包目录（规则表在
lib/index.js中含被检索的 API 名）。 - 预览依赖浏览器：软件 WebGL 较慢；WebGPU 场景需要支持 WebGPU 的浏览器（
WebGPURenderer可自行回退 WebGL 2）。 - 抽屉 只读，不能编辑场景，也不监听文件写入事件。
仓库提供的自检命令（供维护者或本地验证插件行为）：
node test/smoke.mjs
node test/browser-check.mjs
后者在 loopback 端口启动插件 handler，用 headless Chrome 加载 test/fixture 下的预览页，验证内置 three 与 WebGL 初始化。
结尾¶
dsh-plugin-threejs-workbench 把 Three.js 场景预览与项目体检收进 DSH Web UI，减少在 Harness 外单独起服务、查迁移与估资源体积的来回切换。社区插件目录（与 DeepSeek / 幻方无官方从属关系）见 SkillHub 目录页；源码与 issue 见 GitHub：Elmeis/dsh-plugin-threejs-workbench。
