DSH AI 工作室

把 DSH 的插件与模型调用过程可视化成 3D 数字办公室——插件即员工、工位即岗位、调用即任务。

六名员工各有固定岗位，谁在干活、在干什么、为什么这么干、最后交付了什么，一眼看得见。

实机画面（暗色主题 · 真实调用驱动 · 六名员工各就各位）：

安装（一条命令）

前置：官方宿主 @deepseek-ai/dsh@0.1.5-rc.1（宿主 React 18.3.1）。已经装过 DSH 就不用再装。

多数人是用 npx @deepseek-ai/dsh web 启动 DSH 的，那就用同样的形式装插件：

# 1) 装插件：一条命令，从 npm 装，不需要任何授权（包里没有安装期脚本）
npx -y @deepseek-ai/dsh plugin --profile web add toolfolk-for-dsh

# 2) 启动（就是你平时那条命令）
npx @deepseek-ai/dsh web --no-open

全局装过 dsh 的（npm i -g @deepseek-ai/dsh），把命令里的 npx -y @deepseek-ai/dsh 换成 dsh 即可，其余一字不差。

dsh web 与 npx @deepseek-ai/dsh web 是 --profile web 的硬编码别名，所以插件命令里的 --profile web 指的就是同一个 profile。 -y 只是让 npx 不弹确认。

然后用启动输出里带 ?token= 的完整地址打开， 在视图切换器的「对话 / 轨迹」旁边切到 「3D 工作室」（标签就叫这个名，便于第一次找到）。

首次打开可能是空房间：Web profile 下工具插件要等会话的 agent 启动才加载——在对话里发一条消息，员工就上岗了。

卸载：npx -y @deepseek-ai/dsh plugin --profile web remove toolfolk-for-dsh（全局安装版把前缀换成 dsh）

其它安装方式

安装注意

• ⚠️ 用本地文件路径安装时，路径不要含空格：dsh plugin add 会把路径按空格切开（实测 L:/Toolfolk for DSH/… 会被截成 L:/Toolfolk）。用 ./文件名 这种相对路径最稳；github: 形式不受影响。
• 插件只读宿主事件，不联网、不上传任何数据；状态只写到本机（见下「许可、隐私与兼容」）。
• 实测（独立 profile，非本机默认 profile）：add → 不带 --patch 启动即自动加载、资源从安装位置解析 → remove。

它长什么样

中央机器人气泡修复：早期 v2 资产将机器人合并进桌子，导致 Coordinator 节点缺失，动作和气泡都无法绑定。修复需要更新 studio.glb；只更新客户端代码无效。新资产保留独立机器人节点，并有浏览器回归检查。

员工干活时头顶冒泡，气泡第二行就是这次任务对应的模型推理原文（实机截图中两个工位正在同时干活）：

更多截图见 docs/assets/。

文档

• 接入能力验证结论 —— 官方接口实测：可用接口、关键约束、已知差异与每项证据
• 开发规划与里程碑 —— 任务拆分、验收标准、收尾记录
• 打包清单 —— 打包/分发/验收细节
• 产品构想与技术路线
• 资产说明 · 资产清单

许可、隐私与兼容

• 许可：MIT（LICENSE，Copyright (c) 2026 浊客er）。
• 第三方声明：THIRD-PARTY-NOTICES.md。客户端产物内联了 three.js（MIT）， 而打包器会剥掉代码里的许可注释，所以分发时必须随包附带该文件（产物头部也留了指引）。
• 资产来源：assets/3d/v2/*.glb 由本项目脚本程序化生成；assets/art/studio-v1/*.png 为项目作者自制。不含第三方素材。
• 隐私：插件只读宿主事件（tools/execute、tools/result、session/event、agent/assistant-stream）， 不修改工具调用链、不拦截返回值；状态只写到本机文件，不发送任何数据到外部：
  • <用户目录>/.dsh/studio/state.json（可用 DSH_STUDIO_STATE 覆盖）；
  • 会话工作区里的一份 .dsh-studio/state.json——纯派生数据、可随时删除，是为了让浏览器端在任何机器上都找得到状态； 建议加进你项目的 .gitignore（本仓库已加）。
• 兼容：官方 @deepseek-ai/dsh@0.1.5-rc.1（宿主 React 18.3.1）。桌面端未验证。

开发

构建与测试

npm ci
npm test                  # 65 项：状态引擎 + 桥接核心 + 岗位 + 思维流 + 交付 + 状态路径
npm run client:build      # 源码 → 闭包工厂 bundle（three 内联；改完不用重启宿主）
npm run state:replay      # 纯逻辑回放（不连宿主）；可传 tests/fixtures/studio-replay.json
npm run assets:build      # 重新导出模型
npm run assets:verify     # 校验 GLB 结构与动作幅度
npm run preview           # 预览 3D 资产 → http://127.0.0.1:4173/?version=v2

开发态运行

宿主用官方发行包，不需要源码构建：

npx --yes @deepseek-ai/dsh@0.1.5-rc.1 \
  --profile web --patch "<仓库绝对路径>/src/host/cordis-dev.yml" \
  --port 3081 --no-open
# 用启动输出里带 ?token= 的完整地址打开，切到「3D 工作室」

两个实测出来的环境约束（踩过，别再踩）：

• 必须用 Node 22：系统 Node 24 实测会无输出挂住；
• 必须用默认 npm 缓存：--cache 指向项目 tmp 会生成含重复副本的模块树，宿主的 profile 软链会被带坏， 工具分发随之崩溃（agent-loop 与 tools 的 unique symbol 失配）——详见接入结论 §5.6。

环境约束：宿主 React 为 18.3.1，3D 依赖必须按此匹配；改客户端 bundle 由 HMR 自动重载，无需重启宿主； 改 src/host/* 或 src/shared/*（宿主侧）必须重启宿主（token 会变）。

数据通路

tools/execute + tools/result + session/event + agent/assistant-stream
  → src/host.mjs                          宿主：归约进状态引擎（热路径不写盘，防抖 250 ms）
  → <用户目录>/.dsh/studio/state.json     权威快照（原子替换）
  → <会话工作区>/.dsh-studio/state.json   同一份副本：客户端用**工作区相对路径**引导，
                                          换台机器/换账号也能找到（绝对路径是构建期算的，包不写死）
  → remote.workspaceFiles.readAll         客户端每 500 ms 读回（两端通用通道）
  → src/client/index.mjs → lib/client.js  按会话匹配 → 六岗位动作 + 气泡 + 交付纸 + 日志/汇报

目录

本仓库自身就是一个插件包（包清单 package.json 在仓库根，files 决定哪些文件随包分发）， 所以一条命令就能装；开发用的脚本、测试、文档则不进包。

归属分两层（见接入结论 §4.10）：官方目录 ∩ 已加载插件 是基线； ctx.tools.schemas() 有内容时再求交收紧。实测工具注册在 agent 作用域层，没有 agent 活动时工具名册为空—— 此时快照会带 attribution.mode = catalog-plugin，客户端把降级显示出来。基础设施包（如工具注册表 dsh-tools）不占工位。

打包与分发（维护者）

npm pack                # 在仓库根打包；files 决定内容，无需任何复制脚本
# → toolfolk-for-dsh-0.1.0.tgz（15.2 MB / 24 个文件）

包内容：src/host.mjs + src/shared/** + src/client/index.mjs、lib/client.js（含内联 three）、 assets/3d/v2/studio.glb 与 assets/art/studio-v1/**、cordis.patch.yml、README.md、LICENSE、THIRD-PARTY-NOTICES.md。 不含脚本、测试、文档、网站与开发工具。

包内没有 prepare 等安装期脚本，资源随包提交，所以 git 安装不需要任何授权（allowBuilds 不会触发）； 产物内也不含任何机器相关路径（客户端引导走会话工作区相对路径）。

尚未完成（不要当作已通过）

• 跨机器安装：未在另一台机器/账号上装过（本环境只有一台）。本机已实测：安装 → 不带 --patch 自动加载 → 卸载。
• github: 一条命令：本机网络到 github.com:443 时通时断，没能在真实 GitHub 上跑完整命令； 已用等价的本地 git 仓库（git+file://…，同一个代码路径）验证：免授权、装得上、能加载。
• 桌面端：从未验证（一直没有可用环境）。
• 性能：从未测量；资产里 95% 是未压缩几何（12.56 MiB / 13.21 MiB），是唯一值得优化的地方。
• 真人目视项：动作穿插（手/桌/椅/脸）、交付纸排版与字号、气泡避让的边界情况；10 分钟连续观察未做。
• 减少动态效果 / 性能模式：明确决定延后。