@haitang-hub/dsh-3d-director-desk 0.3.13 → 0.3.20
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -21
- package/README.md +141 -141
- package/bridge/index.js +80 -80
- package/bridge/skills/director-desk/SKILL.md +42 -42
- package/bridge/src/schema/tools.js +290 -290
- package/bridge/src/server/bridge.js +190 -190
- package/bridge/src/server/http.js +432 -409
- package/bridge/src/server/mcp.js +145 -145
- package/cordis.patch.yml +26 -26
- package/dsh/index.js +632 -592
- package/dsh/shared-settings.js +1 -1
- package/lib/client.js +54 -2
- package/package.json +1 -1
- package/site/assets/editor-page-DQfRuAlQ.js +531 -0
- package/site/assets/{index-BMzlZBG5.js → index-8Z0rEin5.js} +210 -210
- package/site/assets/index-BGaYavDD.css +1 -0
- package/site/config.js +2 -2
- package/site/icons/linuxdo.svg +9 -9
- package/site/index.html +24 -24
- package/site/local-assets/guo-3d-assets/guo-mounted-props-200/README.md +3 -3
- package/site/local-assets/guo-3d-assets/guo-mounted-props-200/manifest.json +3111 -3111
- package/site/local-assets/guo-3d-assets/guo-skeleton-models/README.md +5 -5
- package/site/local-assets/guo-3d-assets/guo-skeleton-models/build-report.json +41 -41
- package/site/local-assets/guo-3d-assets/guo-skeleton-models/manifest.json +943 -943
- package/site/local-assets/mixamo/SOURCES.md +34 -34
- package/site/models/ue-mannequin-retopology.license.txt +8 -8
- package/site/assets/editor-page-V4JLC_BO.js +0 -531
- package/site/assets/index-DgYQ1oik.css +0 -1
package/LICENSE
CHANGED
|
@@ -1,21 +1,21 @@
|
|
|
1
|
-
MIT License
|
|
2
|
-
|
|
3
|
-
Copyright (c) 2026 Haitang-Hub
|
|
4
|
-
|
|
5
|
-
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
-
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
-
in the Software without restriction, including without limitation the rights
|
|
8
|
-
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
-
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
-
furnished to do so, subject to the following conditions:
|
|
11
|
-
|
|
12
|
-
The above copyright notice and this permission notice shall be included in all
|
|
13
|
-
copies or substantial portions of the Software.
|
|
14
|
-
|
|
15
|
-
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
-
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
-
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
-
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
-
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
-
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
-
SOFTWARE.
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Haitang-Hub
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,141 +1,141 @@
|
|
|
1
|
-
# dsh-3d-director-desk(DSH Desktop 插件包)
|
|
2
|
-
|
|
3
|
-
把 3D 导演台接入 DeepSeek Harness(DSH Desktop)的插件包。本仓库就是插件包本身:
|
|
4
|
-
`npm pack` 直接出可安装的 `.tgz`。main 分支 `bridge/` 与 `site/` 产物已入库,克隆即打包;
|
|
5
|
-
full 分支(全量源码)上这两目录由 `npm run sync` 生成(gitignore 排除),先 build 再打包。
|
|
6
|
-
|
|
7
|
-
一个包同时是:
|
|
8
|
-
|
|
9
|
-
- **npm 包**:`dsh plugin add` 可安装的 `.tgz`;
|
|
10
|
-
- **DSH 插件(bundle)**:`cordis.patch.yml` 把服务端入口插入 Harness 插件树;
|
|
11
|
-
- **Desktop 右侧栏标签**:客户端经 `sidebarRightTabs.register()` 在右侧栏注册「3D 导演台」标签页;
|
|
12
|
-
- **MCP 工具来源**:patch 里的 `dsh-mcp-client` 条目把桥的 `/mcp` 门面注册为
|
|
13
|
-
`mcp__director-desk__stage_* / camera_* / preview_*` 原生工具。
|
|
14
|
-
|
|
15
|
-
## 架构
|
|
16
|
-
|
|
17
|
-
```
|
|
18
|
-
DSH 会话(模型调用 mcp__director-desk__*)
|
|
19
|
-
▼
|
|
20
|
-
dsh-mcp-client(harness 进程,streamable-http → 127.0.0.1:17372/mcp,持续重连)
|
|
21
|
-
▼
|
|
22
|
-
director-mcp 桥(由 dsh/index.js spawn 并监管;数据目录 = dshHomePath('3d-director-desk'))
|
|
23
|
-
│ SSE tool_call
|
|
24
|
-
▼
|
|
25
|
-
executor = 右侧栏「导演台」标签 iframe 里的导演台编辑器(用户实时看到摆场/运镜/出片)
|
|
26
|
-
```
|
|
27
|
-
|
|
28
|
-
- 桥进程生命周期归插件所有:插件停用/卸载/Harness 重启时随之退出;
|
|
29
|
-
- 数据落 `$DSH_HOME/3d-director-desk/`(`DIRECTOR_STORE_DIR`),卸载插件不删数据;
|
|
30
|
-
- 面板形态是 **DSH 右侧栏标签**,不是工作台分栏:会话保持整页宽度(宿主自己的布局
|
|
31
|
-
不动),导演台画布停靠在右侧栏的一个标签页里,可拖动、可拆分、可全屏;从右侧栏
|
|
32
|
-
「开始」引导页点「3D 导演台」打开,之后作为普通标签保留;标签顶部有
|
|
33
|
-
「新窗口 / 重启服务 / 刷新」快捷操作(重启服务重建本地桥,无需重启应用);
|
|
34
|
-
- 客户端外壳只用宿主基线 React(18.x);React 19 + three.js 的应用跑在 iframe 里,
|
|
35
|
-
桥地址经 `/api/director-desk.bridge-info` 动态发现;
|
|
36
|
-
- 端口单一事实来源:环境变量 `DIRECTOR_DESK_PORT`(默认 17372),
|
|
37
|
-
`dsh/index.js` 的 `Config.port` 与 patch 里 mcp 条目的 `url` 都读它;
|
|
38
|
-
- 复用已有桥前先探测**站点能力**(`GET /` 必须是含 `id="root"` 的 HTML),
|
|
39
|
-
spawn 时显式传 `DIRECTOR_SITE_DIR`,不再赌桥内部按相对路径上溯的猜测。
|
|
40
|
-
|
|
41
|
-
## 目录
|
|
42
|
-
|
|
43
|
-
```
|
|
44
|
-
(仓库根 = 插件包根)
|
|
45
|
-
├── package.json # npm 与 dsh.bundle.patch / dsh.client 声明
|
|
46
|
-
├── cordis.patch.yml # 工作台条目 + dsh-mcp-client 条目
|
|
47
|
-
├── dsh/index.js # 服务端入口:拉起桥 + bridge-info / restart-bridge + 8s 心跳守护
|
|
48
|
-
├── lib/client.js # 客户端单文件(右侧栏「导演台」标签:引导入口 + 快捷操作 + iframe)
|
|
49
|
-
├── bridge/ # 桥运行时(director-mcp 快照,已入库)
|
|
50
|
-
├── site/ # 导演台前端构建产物(web/dist 快照,含本地 3D 资产库,已入库)
|
|
51
|
-
└── docs/ # 桥协议文档
|
|
52
|
-
```
|
|
53
|
-
|
|
54
|
-
## 安装与更新
|
|
55
|
-
|
|
56
|
-
```bash
|
|
57
|
-
# 从 .tgz 安装(npm pack 或 GitHub Release 产物)
|
|
58
|
-
dsh plugin --profile web add /绝对路径/dsh-3d-director-desk-<版本>.tgz
|
|
59
|
-
|
|
60
|
-
# 从本仓库直接打包
|
|
61
|
-
git clone https://github.com/Haitang-Hub/dsh-3d-director-desk.git
|
|
62
|
-
cd dsh-3d-director-desk && npm pack # 产出 .tgz,再按上行安装
|
|
63
|
-
```
|
|
64
|
-
|
|
65
|
-
**更新**:发布新版本只需改 `package.json` 的 `version` 并重新打包安装;
|
|
66
|
-
接入市场的分发(按包名 `dsh plugin add dsh-3d-director-desk`)依赖 npm registry
|
|
67
|
-
上的同名版本,`npm publish` 即可被市场索引与自动更新。安装/替换包后需完整退出
|
|
68
|
-
并重新打开 Desktop(新 JS 模块代要重启才载入)。
|
|
69
|
-
|
|
70
|
-
改端口时只设一处:`DIRECTOR_DESK_PORT=18000`(Harness 进程环境),patch 的 url 与
|
|
71
|
-
插件 `Config.port` 同步生效。
|
|
72
|
-
|
|
73
|
-
## 宿主接口
|
|
74
|
-
|
|
75
|
-
| 接口 | 用途 |
|
|
76
|
-
| --- | --- |
|
|
77
|
-
| `GET /api/director-desk.bridge-info` | `{ ready, host, port, supervised, restarts, error? }`,标签页据此决定显示 iframe 还是离线引导 |
|
|
78
|
-
| `POST /api/director-desk.restart-bridge` | 强制杀掉插件托管的桥子进程并重建,面板「重启服务」按钮用 |
|
|
79
|
-
| `sidebarRightTabs.register({ id, kind, title, guide })` | 声明「导演台」标签类型,并在右侧栏「开始」引导页放入口 |
|
|
80
|
-
| `slots.register({ name: 'sidebar.right.pane.tab', key })` | 标签正文:快捷操作行 + 导演台 iframe |
|
|
81
|
-
|
|
82
|
-
右侧栏形态下会话由宿主直接渲染,插件不自建聊天界面。
|
|
83
|
-
|
|
84
|
-
## 发布(CI/CD)
|
|
85
|
-
|
|
86
|
-
发布由 GitHub Actions 全自动完成,本地只需三步:
|
|
87
|
-
|
|
88
|
-
1. 改 `dsh-plugin/package.json` 的 `version`;
|
|
89
|
-
2. 在 `CHANGELOG.md` 补一节变更记录;
|
|
90
|
-
3. 提交并推送 `full` 分支。
|
|
91
|
-
|
|
92
|
-
推送后两条流水线并行工作(`.github/workflows/`):
|
|
93
|
-
|
|
94
|
-
- **CI**:每次 push / PR 到 `full` 都会跑 `web` 的 typecheck + build 和 `dsh-plugin sync`,不发布;
|
|
95
|
-
- **Release**:读取 `dsh-plugin/package.json` 的版本号,若远端不存在 `v<版本>` tag 则自动构建、把
|
|
96
|
-
`dsh/ lib/ bridge/ site/ cordis.patch.yml package.json` 同步到 main 分支根目录、打 tag 并创建
|
|
97
|
-
GitHub Release(附 `.tgz`,见 Releases 页)。版本号没变时只跑 CI,不会重复发版。
|
|
98
|
-
|
|
99
|
-
发布产物下载:
|
|
100
|
-
|
|
101
|
-
```bash
|
|
102
|
-
# GitHub Releases 页下载 dsh-3d-director-desk-<版本>.tgz 后:
|
|
103
|
-
dsh plugin --profile web add /绝对路径/dsh-3d-director-desk-<版本>.tgz
|
|
104
|
-
```
|
|
105
|
-
|
|
106
|
-
## 全量版本(可找回)
|
|
107
|
-
|
|
108
|
-
历史上本项目是独立全量工程:`web/`(Vite + React + three.js 源码,端口 5080)、
|
|
109
|
-
`director-mcp/`(常驻桥服务源码)、`start.bat/ps1` 一键启动等。这些**已归档**,
|
|
110
|
-
随时找回并继续开发:
|
|
111
|
-
|
|
112
|
-
```bash
|
|
113
|
-
git switch full # full 分支(= full-v1.0 tag),全量布局
|
|
114
|
-
# 开发迭代后重新出包:
|
|
115
|
-
# cd web && npm install && npm run build
|
|
116
|
-
# cd ../dsh-plugin && npm run sync && npm pack # sync 从 director-mcp/ 与 web/dist 同步生成 bridge/ 与 site/
|
|
117
|
-
```
|
|
118
|
-
|
|
119
|
-
全量版本的演进历史见 `CHANGELOG.md`。main 分支只保留插件包本体;
|
|
120
|
-
若全量侧有新迭代,把重新生成的 `bridge/`、`site/` 拷回 main 提交即可发布新版插件。
|
|
121
|
-
|
|
122
|
-
## 阶段状态(诚实边界)
|
|
123
|
-
|
|
124
|
-
| 能力 | 状态 |
|
|
125
|
-
| --- | --- |
|
|
126
|
-
| 包格式(第 3 节必须项) | 已实现:`dsh.bundle.patch` / `dsh.client.platform` / `dsh.client.inject` / `exports["./client"]` / 官方包仅在 peerDependencies |
|
|
127
|
-
| 服务端拉起桥 + bridge-info | 已实现;路由纳入 `ctx.effect`;复用前校验站点能力,不可用则报出可操作原因 |
|
|
128
|
-
| 面板形态 | DSH 右侧栏标签:与会话并排的「导演台」标签页(`dsh.client.inject` = `@deepseek-ai/dsh-client-ui-sidebar-right`) |
|
|
129
|
-
| 会话归属 | 右侧栏下会话由宿主渲染,插件不自建聊天(session-ownership 接口未实现,README 早期版本误标为已接) |
|
|
130
|
-
| 桥鉴权 | 已实现:/bootstrap 仅向回环 Origin 下发随机 token,数据端点要求 `x-director-token` 或 `?token=`;/health、/mcp 与静态站点豁免 |
|
|
131
|
-
| MCP 工具注册(streamable-http) | 配置已写;`reconnect` 放宽到近似无限(5s 退避 ×86400),桥晚于 Harness 就绪也能接上 |
|
|
132
|
-
| 桥伺服站点 + 标签 iframe | 已实现:显式 `DIRECTOR_SITE_DIR`,静态优先、无扩展名路径回退 index.html |
|
|
133
|
-
| iframe 内建 AI 助手 | 仍存在(页面直连模型配置),与原生会话并存;后续收敛到只保留一条 |
|
|
134
|
-
| 已知限制 | 端口/包更新需重启;17372 若被全量版 start.bat 起的桥占用,插件会复用它(数据落在仓库 `data/`) |
|
|
135
|
-
|
|
136
|
-
## 验收(按官方第 8 节,逐项留证据)
|
|
137
|
-
|
|
138
|
-
1. `npm pack` 后 `tar -tzf dsh-3d-director-desk-<版本>.tgz` 核对 `package.json`、`dsh/`、`lib/`、`bridge/`、`site/`、`cordis.patch.yml`;
|
|
139
|
-
2. `dsh --profile web --dump-config` 出现本包两层条目(只证明配置,不代表界面已加载);
|
|
140
|
-
3. Desktop 插件市场「已安装」出现条目且运行中,右侧栏「开始」引导页出现「3D 导演台」入口,点开即见导演台标签;
|
|
141
|
-
4. 真实业务面板打开 + 原生会话里调用 `mcp__director-desk__stage_place_character` 全链路跑通。
|
|
1
|
+
# dsh-3d-director-desk(DSH Desktop 插件包)
|
|
2
|
+
|
|
3
|
+
把 3D 导演台接入 DeepSeek Harness(DSH Desktop)的插件包。本仓库就是插件包本身:
|
|
4
|
+
`npm pack` 直接出可安装的 `.tgz`。main 分支 `bridge/` 与 `site/` 产物已入库,克隆即打包;
|
|
5
|
+
full 分支(全量源码)上这两目录由 `npm run sync` 生成(gitignore 排除),先 build 再打包。
|
|
6
|
+
|
|
7
|
+
一个包同时是:
|
|
8
|
+
|
|
9
|
+
- **npm 包**:`dsh plugin add` 可安装的 `.tgz`;
|
|
10
|
+
- **DSH 插件(bundle)**:`cordis.patch.yml` 把服务端入口插入 Harness 插件树;
|
|
11
|
+
- **Desktop 右侧栏标签**:客户端经 `sidebarRightTabs.register()` 在右侧栏注册「3D 导演台」标签页;
|
|
12
|
+
- **MCP 工具来源**:patch 里的 `dsh-mcp-client` 条目把桥的 `/mcp` 门面注册为
|
|
13
|
+
`mcp__director-desk__stage_* / camera_* / preview_*` 原生工具。
|
|
14
|
+
|
|
15
|
+
## 架构
|
|
16
|
+
|
|
17
|
+
```
|
|
18
|
+
DSH 会话(模型调用 mcp__director-desk__*)
|
|
19
|
+
▼
|
|
20
|
+
dsh-mcp-client(harness 进程,streamable-http → 127.0.0.1:17372/mcp,持续重连)
|
|
21
|
+
▼
|
|
22
|
+
director-mcp 桥(由 dsh/index.js spawn 并监管;数据目录 = dshHomePath('3d-director-desk'))
|
|
23
|
+
│ SSE tool_call
|
|
24
|
+
▼
|
|
25
|
+
executor = 右侧栏「导演台」标签 iframe 里的导演台编辑器(用户实时看到摆场/运镜/出片)
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
- 桥进程生命周期归插件所有:插件停用/卸载/Harness 重启时随之退出;
|
|
29
|
+
- 数据落 `$DSH_HOME/3d-director-desk/`(`DIRECTOR_STORE_DIR`),卸载插件不删数据;
|
|
30
|
+
- 面板形态是 **DSH 右侧栏标签**,不是工作台分栏:会话保持整页宽度(宿主自己的布局
|
|
31
|
+
不动),导演台画布停靠在右侧栏的一个标签页里,可拖动、可拆分、可全屏;从右侧栏
|
|
32
|
+
「开始」引导页点「3D 导演台」打开,之后作为普通标签保留;标签顶部有
|
|
33
|
+
「新窗口 / 重启服务 / 刷新」快捷操作(重启服务重建本地桥,无需重启应用);
|
|
34
|
+
- 客户端外壳只用宿主基线 React(18.x);React 19 + three.js 的应用跑在 iframe 里,
|
|
35
|
+
桥地址经 `/api/director-desk.bridge-info` 动态发现;
|
|
36
|
+
- 端口单一事实来源:环境变量 `DIRECTOR_DESK_PORT`(默认 17372),
|
|
37
|
+
`dsh/index.js` 的 `Config.port` 与 patch 里 mcp 条目的 `url` 都读它;
|
|
38
|
+
- 复用已有桥前先探测**站点能力**(`GET /` 必须是含 `id="root"` 的 HTML),
|
|
39
|
+
spawn 时显式传 `DIRECTOR_SITE_DIR`,不再赌桥内部按相对路径上溯的猜测。
|
|
40
|
+
|
|
41
|
+
## 目录
|
|
42
|
+
|
|
43
|
+
```
|
|
44
|
+
(仓库根 = 插件包根)
|
|
45
|
+
├── package.json # npm 与 dsh.bundle.patch / dsh.client 声明
|
|
46
|
+
├── cordis.patch.yml # 工作台条目 + dsh-mcp-client 条目
|
|
47
|
+
├── dsh/index.js # 服务端入口:拉起桥 + bridge-info / restart-bridge + 8s 心跳守护
|
|
48
|
+
├── lib/client.js # 客户端单文件(右侧栏「导演台」标签:引导入口 + 快捷操作 + iframe)
|
|
49
|
+
├── bridge/ # 桥运行时(director-mcp 快照,已入库)
|
|
50
|
+
├── site/ # 导演台前端构建产物(web/dist 快照,含本地 3D 资产库,已入库)
|
|
51
|
+
└── docs/ # 桥协议文档
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
## 安装与更新
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
# 从 .tgz 安装(npm pack 或 GitHub Release 产物)
|
|
58
|
+
dsh plugin --profile web add /绝对路径/dsh-3d-director-desk-<版本>.tgz
|
|
59
|
+
|
|
60
|
+
# 从本仓库直接打包
|
|
61
|
+
git clone https://github.com/Haitang-Hub/dsh-3d-director-desk.git
|
|
62
|
+
cd dsh-3d-director-desk && npm pack # 产出 .tgz,再按上行安装
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
**更新**:发布新版本只需改 `package.json` 的 `version` 并重新打包安装;
|
|
66
|
+
接入市场的分发(按包名 `dsh plugin add dsh-3d-director-desk`)依赖 npm registry
|
|
67
|
+
上的同名版本,`npm publish` 即可被市场索引与自动更新。安装/替换包后需完整退出
|
|
68
|
+
并重新打开 Desktop(新 JS 模块代要重启才载入)。
|
|
69
|
+
|
|
70
|
+
改端口时只设一处:`DIRECTOR_DESK_PORT=18000`(Harness 进程环境),patch 的 url 与
|
|
71
|
+
插件 `Config.port` 同步生效。
|
|
72
|
+
|
|
73
|
+
## 宿主接口
|
|
74
|
+
|
|
75
|
+
| 接口 | 用途 |
|
|
76
|
+
| --- | --- |
|
|
77
|
+
| `GET /api/director-desk.bridge-info` | `{ ready, host, port, supervised, restarts, error? }`,标签页据此决定显示 iframe 还是离线引导 |
|
|
78
|
+
| `POST /api/director-desk.restart-bridge` | 强制杀掉插件托管的桥子进程并重建,面板「重启服务」按钮用 |
|
|
79
|
+
| `sidebarRightTabs.register({ id, kind, title, guide })` | 声明「导演台」标签类型,并在右侧栏「开始」引导页放入口 |
|
|
80
|
+
| `slots.register({ name: 'sidebar.right.pane.tab', key })` | 标签正文:快捷操作行 + 导演台 iframe |
|
|
81
|
+
|
|
82
|
+
右侧栏形态下会话由宿主直接渲染,插件不自建聊天界面。
|
|
83
|
+
|
|
84
|
+
## 发布(CI/CD)
|
|
85
|
+
|
|
86
|
+
发布由 GitHub Actions 全自动完成,本地只需三步:
|
|
87
|
+
|
|
88
|
+
1. 改 `dsh-plugin/package.json` 的 `version`;
|
|
89
|
+
2. 在 `CHANGELOG.md` 补一节变更记录;
|
|
90
|
+
3. 提交并推送 `full` 分支。
|
|
91
|
+
|
|
92
|
+
推送后两条流水线并行工作(`.github/workflows/`):
|
|
93
|
+
|
|
94
|
+
- **CI**:每次 push / PR 到 `full` 都会跑 `web` 的 typecheck + build 和 `dsh-plugin sync`,不发布;
|
|
95
|
+
- **Release**:读取 `dsh-plugin/package.json` 的版本号,若远端不存在 `v<版本>` tag 则自动构建、把
|
|
96
|
+
`dsh/ lib/ bridge/ site/ cordis.patch.yml package.json` 同步到 main 分支根目录、打 tag 并创建
|
|
97
|
+
GitHub Release(附 `.tgz`,见 Releases 页)。版本号没变时只跑 CI,不会重复发版。
|
|
98
|
+
|
|
99
|
+
发布产物下载:
|
|
100
|
+
|
|
101
|
+
```bash
|
|
102
|
+
# GitHub Releases 页下载 dsh-3d-director-desk-<版本>.tgz 后:
|
|
103
|
+
dsh plugin --profile web add /绝对路径/dsh-3d-director-desk-<版本>.tgz
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
## 全量版本(可找回)
|
|
107
|
+
|
|
108
|
+
历史上本项目是独立全量工程:`web/`(Vite + React + three.js 源码,端口 5080)、
|
|
109
|
+
`director-mcp/`(常驻桥服务源码)、`start.bat/ps1` 一键启动等。这些**已归档**,
|
|
110
|
+
随时找回并继续开发:
|
|
111
|
+
|
|
112
|
+
```bash
|
|
113
|
+
git switch full # full 分支(= full-v1.0 tag),全量布局
|
|
114
|
+
# 开发迭代后重新出包:
|
|
115
|
+
# cd web && npm install && npm run build
|
|
116
|
+
# cd ../dsh-plugin && npm run sync && npm pack # sync 从 director-mcp/ 与 web/dist 同步生成 bridge/ 与 site/
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
全量版本的演进历史见 `CHANGELOG.md`。main 分支只保留插件包本体;
|
|
120
|
+
若全量侧有新迭代,把重新生成的 `bridge/`、`site/` 拷回 main 提交即可发布新版插件。
|
|
121
|
+
|
|
122
|
+
## 阶段状态(诚实边界)
|
|
123
|
+
|
|
124
|
+
| 能力 | 状态 |
|
|
125
|
+
| --- | --- |
|
|
126
|
+
| 包格式(第 3 节必须项) | 已实现:`dsh.bundle.patch` / `dsh.client.platform` / `dsh.client.inject` / `exports["./client"]` / 官方包仅在 peerDependencies |
|
|
127
|
+
| 服务端拉起桥 + bridge-info | 已实现;路由纳入 `ctx.effect`;复用前校验站点能力,不可用则报出可操作原因 |
|
|
128
|
+
| 面板形态 | DSH 右侧栏标签:与会话并排的「导演台」标签页(`dsh.client.inject` = `@deepseek-ai/dsh-client-ui-sidebar-right`) |
|
|
129
|
+
| 会话归属 | 右侧栏下会话由宿主渲染,插件不自建聊天(session-ownership 接口未实现,README 早期版本误标为已接) |
|
|
130
|
+
| 桥鉴权 | 已实现:/bootstrap 仅向回环 Origin 下发随机 token,数据端点要求 `x-director-token` 或 `?token=`;/health、/mcp 与静态站点豁免 |
|
|
131
|
+
| MCP 工具注册(streamable-http) | 配置已写;`reconnect` 放宽到近似无限(5s 退避 ×86400),桥晚于 Harness 就绪也能接上 |
|
|
132
|
+
| 桥伺服站点 + 标签 iframe | 已实现:显式 `DIRECTOR_SITE_DIR`,静态优先、无扩展名路径回退 index.html |
|
|
133
|
+
| iframe 内建 AI 助手 | 仍存在(页面直连模型配置),与原生会话并存;后续收敛到只保留一条 |
|
|
134
|
+
| 已知限制 | 端口/包更新需重启;17372 若被全量版 start.bat 起的桥占用,插件会复用它(数据落在仓库 `data/`) |
|
|
135
|
+
|
|
136
|
+
## 验收(按官方第 8 节,逐项留证据)
|
|
137
|
+
|
|
138
|
+
1. `npm pack` 后 `tar -tzf dsh-3d-director-desk-<版本>.tgz` 核对 `package.json`、`dsh/`、`lib/`、`bridge/`、`site/`、`cordis.patch.yml`;
|
|
139
|
+
2. `dsh --profile web --dump-config` 出现本包两层条目(只证明配置,不代表界面已加载);
|
|
140
|
+
3. Desktop 插件市场「已安装」出现条目且运行中,右侧栏「开始」引导页出现「3D 导演台」入口,点开即见导演台标签;
|
|
141
|
+
4. 真实业务面板打开 + 原生会话里调用 `mcp__director-desk__stage_place_character` 全链路跑通。
|
package/bridge/index.js
CHANGED
|
@@ -1,80 +1,80 @@
|
|
|
1
|
-
#!/usr/bin/env node
|
|
2
|
-
/**
|
|
3
|
-
* director-mcp:3D
|
|
4
|
-
*
|
|
5
|
-
* node index.js 常驻 HTTP 服务:本地文件存储(/kv、/assets)+ 导演台桥(/events、/director/*)
|
|
6
|
-
* node index.js mcp stdio MCP 门面(DeepSeek harness 经此接入,工具调用转发到常驻桥)
|
|
7
|
-
* node index.js doctor 自检:桥端口、executor 在线数、data 目录可写、协议版本
|
|
8
|
-
*/
|
|
9
|
-
|
|
10
|
-
import fs from "node:fs";
|
|
11
|
-
import http from "node:http";
|
|
12
|
-
import { join, resolve, dirname } from "node:path";
|
|
13
|
-
import { fileURLToPath } from "node:url";
|
|
14
|
-
|
|
15
|
-
import { DIRECTOR_PROTOCOL_VERSION, SERVER_NAME, SERVER_VERSION } from "./src/protocol.js";
|
|
16
|
-
|
|
17
|
-
const DATA_DIR = resolve(process.env.DIRECTOR_STORE_DIR?.trim() || join(dirname(fileURLToPath(import.meta.url)), "..", "data"));
|
|
18
|
-
const BRIDGE_URL = (process.env.DIRECTOR_BRIDGE_URL || "http://127.0.0.1:17372").replace(/\/$/, "");
|
|
19
|
-
|
|
20
|
-
const command = process.argv[2] || "";
|
|
21
|
-
|
|
22
|
-
if (command === "mcp") {
|
|
23
|
-
const { startMcpServer } = await import("./src/server/mcp.js");
|
|
24
|
-
await startMcpServer();
|
|
25
|
-
} else if (command === "doctor") {
|
|
26
|
-
await runDoctor();
|
|
27
|
-
} else {
|
|
28
|
-
const { startHttpServer } = await import("./src/server/http.js");
|
|
29
|
-
startHttpServer();
|
|
30
|
-
}
|
|
31
|
-
|
|
32
|
-
/** 一次性 GET(禁用 keep-alive,避免 doctor 退出时 libuv 断言)。 */
|
|
33
|
-
function getJson(url) {
|
|
34
|
-
return new Promise((resolvePromise) => {
|
|
35
|
-
const req = http.get(url, { agent: new http.Agent({ keepAlive: false }) }, (res) => {
|
|
36
|
-
const chunks = [];
|
|
37
|
-
res.on("data", (chunk) => chunks.push(chunk));
|
|
38
|
-
res.on("end", () => {
|
|
39
|
-
try {
|
|
40
|
-
resolvePromise({ status: res.statusCode, body: JSON.parse(Buffer.concat(chunks).toString("utf8")) });
|
|
41
|
-
} catch {
|
|
42
|
-
resolvePromise({ status: res.statusCode, body: null });
|
|
43
|
-
}
|
|
44
|
-
});
|
|
45
|
-
});
|
|
46
|
-
req.setTimeout(2000, () => req.destroy(new Error("timeout")));
|
|
47
|
-
req.on("error", () => resolvePromise(null));
|
|
48
|
-
});
|
|
49
|
-
}
|
|
50
|
-
|
|
51
|
-
/** 自检:桥是否在线、executor 是否就绪、data 目录是否可写、协议版本是否匹配。 */
|
|
52
|
-
async function runDoctor() {
|
|
53
|
-
let failures = 0;
|
|
54
|
-
const fail = (text) => ((failures += 1), console.log(` [FAIL] ${text}`));
|
|
55
|
-
const pass = (text) => console.log(` [ OK ] ${text}`);
|
|
56
|
-
|
|
57
|
-
console.log(`${SERVER_NAME} doctor (v${SERVER_VERSION}, bridge protocol v${DIRECTOR_PROTOCOL_VERSION})`);
|
|
58
|
-
|
|
59
|
-
const health = await getJson(`${BRIDGE_URL}/health`);
|
|
60
|
-
if (health?.body?.ok) pass(`桥在线:${BRIDGE_URL}(data dir: ${health.body.dataDir})`);
|
|
61
|
-
else fail(`桥不在线:${BRIDGE_URL} —— 在 director-mcp 目录运行 node index.js(或用 start.bat 启动)`);
|
|
62
|
-
|
|
63
|
-
if (health?.body?.ok) {
|
|
64
|
-
const status = await getJson(`${BRIDGE_URL}/director/status`);
|
|
65
|
-
const ready = (status?.body?.executors || []).filter((item) => item.ready);
|
|
66
|
-
if (ready.length) pass(`executor 在线 ${ready.length} 个:${ready.map((item) => item.deskId || "(未指定 desk)").join(", ")}`);
|
|
67
|
-
else fail("没有已就绪的导演台页面 —— 打开 http://127.0.0.1:17372 并进入一个导演台编辑器后重试");
|
|
68
|
-
}
|
|
69
|
-
|
|
70
|
-
try {
|
|
71
|
-
const probe = join(DATA_DIR, `doctor-${Date.now()}.tmp`);
|
|
72
|
-
fs.writeFileSync(probe, "ok");
|
|
73
|
-
fs.unlinkSync(probe);
|
|
74
|
-
pass(`data 目录可写:${DATA_DIR}`);
|
|
75
|
-
} catch (error) {
|
|
76
|
-
fail(`data 目录不可写:${error instanceof Error ? error.message : error}`);
|
|
77
|
-
}
|
|
78
|
-
|
|
79
|
-
process.exit(failures ? 1 : 0);
|
|
80
|
-
}
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* director-mcp:3D 导演台的常驻本地服务(零依赖,端口统一 17372:开发态与插件托管同端口,STORE_PORT 可覆盖)。
|
|
4
|
+
*
|
|
5
|
+
* node index.js 常驻 HTTP 服务:本地文件存储(/kv、/assets)+ 导演台桥(/events、/director/*)
|
|
6
|
+
* node index.js mcp stdio MCP 门面(DeepSeek harness 经此接入,工具调用转发到常驻桥)
|
|
7
|
+
* node index.js doctor 自检:桥端口、executor 在线数、data 目录可写、协议版本
|
|
8
|
+
*/
|
|
9
|
+
|
|
10
|
+
import fs from "node:fs";
|
|
11
|
+
import http from "node:http";
|
|
12
|
+
import { join, resolve, dirname } from "node:path";
|
|
13
|
+
import { fileURLToPath } from "node:url";
|
|
14
|
+
|
|
15
|
+
import { DIRECTOR_PROTOCOL_VERSION, SERVER_NAME, SERVER_VERSION } from "./src/protocol.js";
|
|
16
|
+
|
|
17
|
+
const DATA_DIR = resolve(process.env.DIRECTOR_STORE_DIR?.trim() || join(dirname(fileURLToPath(import.meta.url)), "..", "data"));
|
|
18
|
+
const BRIDGE_URL = (process.env.DIRECTOR_BRIDGE_URL || "http://127.0.0.1:17372").replace(/\/$/, "");
|
|
19
|
+
|
|
20
|
+
const command = process.argv[2] || "";
|
|
21
|
+
|
|
22
|
+
if (command === "mcp") {
|
|
23
|
+
const { startMcpServer } = await import("./src/server/mcp.js");
|
|
24
|
+
await startMcpServer();
|
|
25
|
+
} else if (command === "doctor") {
|
|
26
|
+
await runDoctor();
|
|
27
|
+
} else {
|
|
28
|
+
const { startHttpServer } = await import("./src/server/http.js");
|
|
29
|
+
startHttpServer();
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/** 一次性 GET(禁用 keep-alive,避免 doctor 退出时 libuv 断言)。 */
|
|
33
|
+
function getJson(url) {
|
|
34
|
+
return new Promise((resolvePromise) => {
|
|
35
|
+
const req = http.get(url, { agent: new http.Agent({ keepAlive: false }) }, (res) => {
|
|
36
|
+
const chunks = [];
|
|
37
|
+
res.on("data", (chunk) => chunks.push(chunk));
|
|
38
|
+
res.on("end", () => {
|
|
39
|
+
try {
|
|
40
|
+
resolvePromise({ status: res.statusCode, body: JSON.parse(Buffer.concat(chunks).toString("utf8")) });
|
|
41
|
+
} catch {
|
|
42
|
+
resolvePromise({ status: res.statusCode, body: null });
|
|
43
|
+
}
|
|
44
|
+
});
|
|
45
|
+
});
|
|
46
|
+
req.setTimeout(2000, () => req.destroy(new Error("timeout")));
|
|
47
|
+
req.on("error", () => resolvePromise(null));
|
|
48
|
+
});
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
/** 自检:桥是否在线、executor 是否就绪、data 目录是否可写、协议版本是否匹配。 */
|
|
52
|
+
async function runDoctor() {
|
|
53
|
+
let failures = 0;
|
|
54
|
+
const fail = (text) => ((failures += 1), console.log(` [FAIL] ${text}`));
|
|
55
|
+
const pass = (text) => console.log(` [ OK ] ${text}`);
|
|
56
|
+
|
|
57
|
+
console.log(`${SERVER_NAME} doctor (v${SERVER_VERSION}, bridge protocol v${DIRECTOR_PROTOCOL_VERSION})`);
|
|
58
|
+
|
|
59
|
+
const health = await getJson(`${BRIDGE_URL}/health`);
|
|
60
|
+
if (health?.body?.ok) pass(`桥在线:${BRIDGE_URL}(data dir: ${health.body.dataDir})`);
|
|
61
|
+
else fail(`桥不在线:${BRIDGE_URL} —— 在 director-mcp 目录运行 node index.js(或用 start.bat 启动)`);
|
|
62
|
+
|
|
63
|
+
if (health?.body?.ok) {
|
|
64
|
+
const status = await getJson(`${BRIDGE_URL}/director/status`);
|
|
65
|
+
const ready = (status?.body?.executors || []).filter((item) => item.ready);
|
|
66
|
+
if (ready.length) pass(`executor 在线 ${ready.length} 个:${ready.map((item) => item.deskId || "(未指定 desk)").join(", ")}`);
|
|
67
|
+
else fail("没有已就绪的导演台页面 —— 打开 http://127.0.0.1:17372 并进入一个导演台编辑器后重试");
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
try {
|
|
71
|
+
const probe = join(DATA_DIR, `doctor-${Date.now()}.tmp`);
|
|
72
|
+
fs.writeFileSync(probe, "ok");
|
|
73
|
+
fs.unlinkSync(probe);
|
|
74
|
+
pass(`data 目录可写:${DATA_DIR}`);
|
|
75
|
+
} catch (error) {
|
|
76
|
+
fail(`data 目录不可写:${error instanceof Error ? error.message : error}`);
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
process.exit(failures ? 1 : 0);
|
|
80
|
+
}
|
|
@@ -1,42 +1,42 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: director-desk
|
|
3
|
-
description: 用 3D 导演台(director-desk)的 stage/camera/preview 工具摆场景、设运镜、出预演图和成片。当用户要求"摆人物/道具、设计镜头、运镜、出预览图或导出预演视频"时使用。
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# 3D 导演台编排技能
|
|
7
|
-
|
|
8
|
-
3D 导演台是一个浏览器里的 3D 场景编排工具。你(Agent)通过 MCP 工具驱动它:
|
|
9
|
-
摆角色和道具 → 设计摄影机轨迹 → 渲染单帧检查构图 → 导出预演成片。
|
|
10
|
-
用户在浏览器(http://127.0.0.1:17372)里能实时看到你的每一步操作。
|
|
11
|
-
|
|
12
|
-
## 工作流
|
|
13
|
-
|
|
14
|
-
1. **摸底**:`stage_get_state` 看当前场景对象与机位;`stage_list_presets` 查可用
|
|
15
|
-
姿势/动作/几何体/模型库/运镜模板/节奏预设。**调参前先查预设,不要凭空编 ID。**
|
|
16
|
-
2. **摆场景**:
|
|
17
|
-
- 角色:`stage_place_character`(可带 pose 预设、位置 x/y/z、朝向 rotation、缩放)。
|
|
18
|
-
- 道具:`stage_place_prop`(geometryType: box/sphere/cylinder/torus/cone/pyramid)。
|
|
19
|
-
- 库模型:`stage_add_model`(assetId 精确选择或名称匹配,覆盖人物/便利生活/居家生活/户外出行/
|
|
20
|
-
工具配件全目录;assetId 用 stage_list_presets 的 library 查询,条目带 categoryId 与 kind)。
|
|
21
|
-
- 微调:`stage_update_object`(位置/颜色/可见/姿势/动作);删除用 `stage_remove_object`。
|
|
22
|
-
- 坐标系:x 右、y 上、z 前;rotation 是绕 Y 轴角度(度)。两人对话让角色面对面
|
|
23
|
-
(rotation 相差约 180°),间距 1.5~2.5。
|
|
24
|
-
3. **运镜**:
|
|
25
|
-
- 快捷:`camera_apply_preset`(templateId 来自 motionTemplates,可用 subjectObjectId 跟踪角色)。
|
|
26
|
-
- 手动:`camera_set_pose` 调好视角 → `camera_set_keyframe` 逐个记录关键帧(至少 2 个才能出片)。
|
|
27
|
-
- 修改:`camera_update_keyframe` / `camera_delete_keyframe` / `camera_set_pacing`;
|
|
28
|
-
查轨迹用 `camera_get_trajectory`。
|
|
29
|
-
4. **检查**:`preview_render_frame` 渲染单帧(返回文件路径;includeData=true 才内联 base64)。
|
|
30
|
-
多机位时每个机位出一帧确认构图后再继续。
|
|
31
|
-
5. **出片**:`preview_export_animatic` 导出 MP4 预演(耗时可达数分钟,耐心等待;
|
|
32
|
-
fps 24/30/60,quality 720p/1080p)。
|
|
33
|
-
|
|
34
|
-
## 注意
|
|
35
|
-
|
|
36
|
-
- 渲染/导出类工具(preview_*)需要导演台页面在浏览器中打开;离线时会返回
|
|
37
|
-
`executor_offline`——提示用户打开页面后重试。
|
|
38
|
-
- 破坏性工具(stage_clear_scene、stage_remove_object、camera_delete_keyframe)
|
|
39
|
-
调用前先 stage_get_state 确认现状。
|
|
40
|
-
- 多个导演台在线时用 desk 参数指定目标(工具会路由到对应页面);不确定就先
|
|
41
|
-
stage_get_state 验证场景内容。
|
|
42
|
-
- 汇报结果时引用工具返回的文件路径与对象 ID,方便用户在界面上对照。
|
|
1
|
+
---
|
|
2
|
+
name: director-desk
|
|
3
|
+
description: 用 3D 导演台(director-desk)的 stage/camera/preview 工具摆场景、设运镜、出预演图和成片。当用户要求"摆人物/道具、设计镜头、运镜、出预览图或导出预演视频"时使用。
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# 3D 导演台编排技能
|
|
7
|
+
|
|
8
|
+
3D 导演台是一个浏览器里的 3D 场景编排工具。你(Agent)通过 MCP 工具驱动它:
|
|
9
|
+
摆角色和道具 → 设计摄影机轨迹 → 渲染单帧检查构图 → 导出预演成片。
|
|
10
|
+
用户在浏览器(http://127.0.0.1:17372)里能实时看到你的每一步操作。
|
|
11
|
+
|
|
12
|
+
## 工作流
|
|
13
|
+
|
|
14
|
+
1. **摸底**:`stage_get_state` 看当前场景对象与机位;`stage_list_presets` 查可用
|
|
15
|
+
姿势/动作/几何体/模型库/运镜模板/节奏预设。**调参前先查预设,不要凭空编 ID。**
|
|
16
|
+
2. **摆场景**:
|
|
17
|
+
- 角色:`stage_place_character`(可带 pose 预设、位置 x/y/z、朝向 rotation、缩放)。
|
|
18
|
+
- 道具:`stage_place_prop`(geometryType: box/sphere/cylinder/torus/cone/pyramid)。
|
|
19
|
+
- 库模型:`stage_add_model`(assetId 精确选择或名称匹配,覆盖人物/便利生活/居家生活/户外出行/
|
|
20
|
+
工具配件全目录;assetId 用 stage_list_presets 的 library 查询,条目带 categoryId 与 kind)。
|
|
21
|
+
- 微调:`stage_update_object`(位置/颜色/可见/姿势/动作);删除用 `stage_remove_object`。
|
|
22
|
+
- 坐标系:x 右、y 上、z 前;rotation 是绕 Y 轴角度(度)。两人对话让角色面对面
|
|
23
|
+
(rotation 相差约 180°),间距 1.5~2.5。
|
|
24
|
+
3. **运镜**:
|
|
25
|
+
- 快捷:`camera_apply_preset`(templateId 来自 motionTemplates,可用 subjectObjectId 跟踪角色)。
|
|
26
|
+
- 手动:`camera_set_pose` 调好视角 → `camera_set_keyframe` 逐个记录关键帧(至少 2 个才能出片)。
|
|
27
|
+
- 修改:`camera_update_keyframe` / `camera_delete_keyframe` / `camera_set_pacing`;
|
|
28
|
+
查轨迹用 `camera_get_trajectory`。
|
|
29
|
+
4. **检查**:`preview_render_frame` 渲染单帧(返回文件路径;includeData=true 才内联 base64)。
|
|
30
|
+
多机位时每个机位出一帧确认构图后再继续。
|
|
31
|
+
5. **出片**:`preview_export_animatic` 导出 MP4 预演(耗时可达数分钟,耐心等待;
|
|
32
|
+
fps 24/30/60,quality 720p/1080p)。
|
|
33
|
+
|
|
34
|
+
## 注意
|
|
35
|
+
|
|
36
|
+
- 渲染/导出类工具(preview_*)需要导演台页面在浏览器中打开;离线时会返回
|
|
37
|
+
`executor_offline`——提示用户打开页面后重试。
|
|
38
|
+
- 破坏性工具(stage_clear_scene、stage_remove_object、camera_delete_keyframe)
|
|
39
|
+
调用前先 stage_get_state 确认现状。
|
|
40
|
+
- 多个导演台在线时用 desk 参数指定目标(工具会路由到对应页面);不确定就先
|
|
41
|
+
stage_get_state 验证场景内容。
|
|
42
|
+
- 汇报结果时引用工具返回的文件路径与对象 ID,方便用户在界面上对照。
|