3D 工作室 zkl22492-star/Toolfolk-for-DSH

DSH AI 工作室

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

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

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

DSH 3D AI 工作室 · 实机

安装（一条命令）

前置：官方宿主 @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）

其它安装方式

| 方式 | 命令（npx 形式；全局安装版把 npx -y @deepseek-ai/dsh 换成 dsh） | 是否需要授权执行作者代码 |
| npm（上面那种，推荐） | npx -y @deepseek-ai/dsh plugin --profile web add toolfolk-for-dsh | 否 |
| git 一条命令（不依赖 npm，能跟源码） | npx -y @deepseek-ai/dsh plugin --profile web add github:zkl22492-star/Toolfolk-for-DSH | 否（包里没有 prepare 等安装期脚本，pnpm 不会拦；代价是 clone 整个仓库，比 npm 慢） |
| 下载附件（适合离线 / 网络极差） | 下载 toolfolk-for-dsh-0.1.0.tgz，在下载目录执行 npx -y @deepseek-ai/dsh plugin --profile web add ./toolfolk-for-dsh-0.1.0.tgz | 否 |
| 锁定版本（可复现） | npx -y @deepseek-ai/dsh plugin --profile web add "github:zkl22492-star/Toolfolk-for-DSH#" | 否 |

安装注意

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

它长什么样

| 能力 | 说明 |
| 六个固定岗位 | 工位 = 岗位：①资料检索 ②撰写修改 ③联网调查 ④会话记忆 ⑤命令执行 ⑥协作调度。插件是岗位里的「承包方」，不占座 |
| 「正在做某事」 | 主文案由真实参数推出（如 正在联网调查：），不是统计数字；未收录的工具另列"未归类"，不硬塞 |
| 思维流气泡 | 员工干活时头顶冒泡，第二行是这次任务对应的模型推理原文（先想后调，按调用归属）；干完停留一会儿淡出 |
| 交付纸 | 回答结束时一张微皱 A4 递到眼前（「老大请过目」+ 红章「已阅」）；可滚动看全文，点印章收起 |
| 员工日志 | 左下角，头部固定（收起按钮不会滚走）；按时间倒序列出调用事件与交付 |
| 汇报记录 | 右上角，默认收起；点开展开全部历史回答，含插件启动前就存在的历史（从会话完整日志回填） |
| 明暗主题 | 跟随宿主 body[data-ds-dark-theme]，颜色变量单一来源 |
| 总控台机器人 | 中央总控台上的 Coordinator 即模型本人，按阶段做程序化动作 |

中央机器人气泡修复：早期 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 决定哪些文件随包分发），所以一条命令就能装；开发用的脚本、测试、文档则不进包。

| 路径 | 内容 |
| src/host.mjs | 宿主入口（状态桥接）：订阅事件、归约进状态引擎、写快照/工作区副本 |
| src/client/index.mjs → lib/client.js | 客户端面板：视图注册 + 3D 场景（lib/client.js 是构建产物，含内联 three） |
| cordis.patch.yml | 发行用补丁层（用包名引用本插件） |
| assets/3d/v2/studio.glb、assets/art/studio-v1/ | 随包分发的模型与美术图 |
| src/host/studio-probe.mjs | 事件探针：只读记录 tools/execute / tools/result / session/event（回归/排查用，不进包） |
| src/host/bridge-selftest.mjs | 桥接自检驱动：合成调用 → 读回快照逐项核对，并验工作区副本相对路径可读（不进包） |
| src/shared/ | 纯逻辑：状态引擎、归属解析、六岗位、模型活动、路径约定、视觉层（可单测） |
| src/host/cordis.yml | 开发/回归覆盖层（不进包） |
| reference/deepseek-harness/ | 官方源码（已 gitignore，仅用于读契约，不装依赖） |

归属分两层（见接入结论 §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 分钟连续观察未做。
- 减少动态效果 / 性能模式：明确决定延后。