前言¶
在 DeepSeek Harness（DSH）里做智能体，模型往往只能改文本、调通用 API，很难直接「看见」并操作一个可预演、可出片的 3D 场景。单独跑 three.js 编辑器再让 Agent 对接，又要自己维护进程、端口和数据目录。下面介绍 Haitang-Hub 维护的 dsh-3d-director-desk：以 DSH Desktop 右侧栏标签形式嵌入 3D 导演台，并通过 MCP 把摆场、运镜、时间轴预演、导出视频等能力注册为 mcp__director-desk__* 工具，供会话中的 Agent 调用；本地数据落在 $DSH_HOME/3d-director-desk/，桥进程由插件拉起并监管。
这是什么¶
dsh-3d-director-desk 是接入 DSH Desktop 的插件包（npm 包 + cordis.patch.yml bundle + 客户端注入）。同一仓库 npm pack 即可得到可安装的 .tgz。它在右侧栏注册「3D 导演台」标签页，并在 Harness 中注册指向本地桥 /mcp 的 MCP 客户端条目，工具名前缀为 mcp__director-desk__stage_*、camera_*、preview_* 等。
维护者：Haitang-Hub。分类：客户端。许可证：MIT（见仓库 package.json）。社区目录页：SkillHub 插件页；源码与说明：GitHub 仓库。
架构与数据流¶
会话里模型调用 mcp__director-desk__* 时，链路如下：
DSH 会话（模型调用 mcp__director-desk__*）
▼
dsh-mcp-client（Harness 进程，streamable-http → 127.0.0.1:17372/mcp）
▼
director-mcp 桥（dsh/index.js spawn；数据目录 dshHomePath('3d-director-desk')）
│ SSE tool_call
▼
executor = 右侧栏「导演台」标签 iframe 内的编辑器（用户可同步看到摆场/运镜/出片）
要点：
- 桥的生命周期归插件：停用、卸载或 Harness 重启时桥随之退出；卸载插件不删除已落盘数据。
- 面板是 DSH 右侧栏标签，不是工作台分栏；导演台画布在右侧标签里，可拖动、拆分、全屏；从右侧栏「开始」引导页点「3D 导演台」打开。
- 标签顶部提供「新窗口 / 重启服务 / 刷新」；「重启服务」会重建本地桥，无需重启整个 Desktop。
- 默认端口 17372，单一来源为环境变量
DIRECTOR_DESK_PORT；改端口时只需在 Harness 进程环境中设置，例如DIRECTOR_DESK_PORT=18000。
数据目录对应环境变量 DIRECTOR_STORE_DIR，默认在 $DSH_HOME/3d-director-desk/。
核心功能（已核实能力）¶
| 能力 | 说明 |
|---|---|
| 右侧栏 UI | 经 sidebarRightTabs.register() 与 dsh.client.inject（@deepseek-ai/dsh-client-ui-sidebar-right）注入「3D 导演台」标签 |
| 桥与站点 | 插件服务端拉起 director-mcp 桥，并伺服 site/ 构建产物；iframe 经 GET /api/director-desk.bridge-info 发现桥地址 |
| MCP 工具 | patch 中 dsh-mcp-client 将 http://127.0.0.1:<port>/mcp 注册为原生工具；验收文档示例：mcp__director-desk__stage_place_character |
| 宿主 API | GET /api/director-desk.bridge-info 返回 { ready, host, port, supervised, restarts, error? }；POST /api/director-desk.restart-bridge 强制重建桥 |
| 桥鉴权 | /bootstrap 向回环 Origin 下发 token；数据端点需 x-director-token 或 ?token=；/health、/mcp 与静态站点豁免 |
| 场景编排 | 简介与 README 表述：摆角色、设镜头、时间轴预演、导出视频（经 MCP 与 iframe 内编辑器执行） |
诚实边界（README「阶段状态」）：会话仍由宿主渲染，插件不自建聊天界面；iframe 内仍保留直连模型配置的 AI 助手，与原生会话并存；端口或包更新后需完整退出并重新打开 Desktop；若 17372 已被全量版 start.bat 起的桥占用，插件会复用该桥（数据可能落在仓库 data/）。
安装与启用¶
安装命令须使用官方 README 中的形式，从 .tgz 安装：
# 从 .tgz 安装（npm pack 或 GitHub Release 产物）
dsh plugin --profile web add /绝对路径/dsh-3d-director-desk-<版本>.tgz
从 GitHub Releases 下载 dsh-3d-director-desk-<版本>.tgz 后，同样执行：
dsh plugin --profile web add /绝对路径/dsh-3d-director-desk-<版本>.tgz
资料中当前包版本为 0.3.6（以 Release 页实际文件名为准）。安装或替换包后，需完整退出并重新打开 Desktop，新 JS 模块才会载入。
可选自检（README 验收项）：
dsh --profile web --dump-config中应出现本包相关条目（仅证明配置写入，不代表 UI 已加载）。- Desktop 插件市场「已安装」中出现条目且运行中；右侧栏「开始」引导页出现「3D 导演台」，点开可见导演台标签。
- 在原生会话中调用 MCP 工具（如
mcp__director-desk__stage_place_character）跑通全链路。
市场按包名 dsh plugin add dsh-3d-director-desk 的分发依赖 npm registry 上的同名版本；本地开发也可在仓库根目录 npm pack 后按绝对路径安装（README 说明 main 分支已含 bridge/、site/ 产物）。
典型用法¶
- 按上一节安装并重启 Desktop，从右侧栏「开始」打开「3D 导演台」，确认 iframe 内编辑器可用（若桥未就绪，标签页会根据
bridge-info显示离线引导）。 - 在同一会话中让 Agent 使用 director-desk 系列 MCP 工具编排场景；README 验收示例为调用
mcp__director-desk__stage_place_character，在面板中应能看到对应变化。 - 桥异常时，在标签顶栏点「重启服务」，对应
POST /api/director-desk.restart-bridge，无需重启 Harness。 - 需要改监听端口时，在启动 Harness 前设置
DIRECTOR_DESK_PORT，与 patch 内 MCP URL、插件Config.port一致生效。
桥协议细节见仓库 docs/ 目录。
适用场景与注意¶
适合谁：需要在 DSH Desktop 里把 3D 导演工作流和 Agent 会话并排使用、且希望工具调用走原生 MCP 而非自写 HTTP 胶水的前端或智能体开发者。
使用前注意：
- 插件以当前 DSH 进程权限运行，安装前应阅读源码与 MIT 许可证，自行评估安全与合规。
- 社区目录 SkillHub 为独立站点，与 DeepSeek / 幻方无官方从属关系；DSH 生态遵循「一切皆插件」，本包为社区贡献的客户端类插件。
- 已知限制：包或端口变更需重启 Desktop；与全量开发版共用 17372 时可能复用外部桥，数据路径行为见 README「已知限制」表。
结尾¶
dsh-3d-director-desk 把 3D 导演台、本地桥与 MCP 工具收进一个可 dsh plugin add 的 Desktop 插件包：右侧栏可视化编辑，会话里 Agent 经 mcp__director-desk__* 驱动同一场景，数据默认落在 $DSH_HOME/3d-director-desk/。
- 目录页：https://www.skillhub.cn/plugins/Haitang-Hub/dsh-3d-director-desk
- GitHub：https://github.com/Haitang-Hub/dsh-3d-director-desk
