前言¶
在 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
