Director Desk 集成指南
3D 导演台 → kais-aigc-platform 正式集成 · 全部组件状态 + API 文档 + 架构图
整体架构
📐 Agent
构造场景 JSON
→
🌐 Platform API
:10588/render
→
🎭 SPA + Playwright
headless Chrome
→
📸 captureBridge
gl.render + toDataURL
→
🖼️ PNG → OSS
/oss/director-desk/
→
🎬 LTX 参考
图生视频
组件清单
| 组件 | 路径 | 状态 | 说明 |
|---|
| SPA 源码 | ~/workspace/storyai-3d-director-desk/ | ✅ 已集成 | React + Three.js，vite build |
| SPA 部署目录 | platform/data/web/director-desk/ | ✅ 已部署 | 含 index.html + assets/ + models/ |
| GLB 模型 | models/ue-mannequin-retopology.glb | ✅ 已部署 | UE4 重拓扑骨骼模型 |
| 静态服务 | app.ts L157-163 | ✅ 已挂载 | /director-desk/ → express.static |
| Render API | /api/v1/director-desk/render | ✅ 已挂载 | router.ts L239 |
| Capabilities API | /api/v1/director-desk/capabilities | ✅ 已挂载 | router.ts L240 |
| Scene API | /api/v1/director-desk/scene | ✅ 已挂载 | router.ts L241 |
| 渲染引擎 | _render.ts | ✅ 已修复 | 4 bugs 已修（弧度/相机/缩放/跑步） |
| OSS 输出 | /data/oss/director-desk/ | ✅ 正常 | 自动创建 |
| Playwright + Chrome | ~/.cache/ms-playwright/ | ✅ 已安装 | v1.61.1 + Chromium 1228 |
| Swagger 文档 | — | ⬜ 待做 | 可选 |
API 完整文档
1. 渲染场景 POST /api/v1/director-desk/render
// 请求体（简写格式 — Agent 推荐用法）
{
"project": {
"settings": {
"background": "#1a1a2e", // 背景色 (hex)
"groundVisible": true // 显示地面
},
"characters": [
{
"id": "c1",
"name": "角色A", // 可选，默认自动命名
"bodyType": "mannequin", // 8种体型
"position": [0, 0, 0], // 世界坐标 [x,y,z]
"rotation": 0, // Y轴旋转（度数，非弧度）
"scale": 1.0, // 缩放（以身体中心为原点）
"pose": "wave" // 20种预设姿势
},
{
"id": "c2",
"bodyType": "female",
"position": [1.5, 0, 0],
"rotation": -60,
"pose": "cross-arms"
}
],
"camera": { // 可选；不传则 autoFrame 自动取景
"position": [0, 1.2, 4],
"lookAt": [0, 1, 0],
"fov": 50 // 视野角度 (15-90)
}
},
"width": 1280, // 可选，默认 1280
"height": 720 // 可选，默认 720
}
// 响应
{
"code": 200,
"data": {
"imageUrl": "/oss/director-desk/director-desk-1784424409187.png",
"width": 1280,
"height": 720,
"fileSize": 72757,
"timestamp": "2026-07-19T01:26:49.115Z"
}
}
2. 查询能力 GET /api/v1/director-desk/capabilities
// 返回所有可用体型、姿势、道具
{
"code": 200,
"data": {
"bodyTypes": [8种], // mannequin/female/broad/muscular/slim/teen/child/chibi
"poses": [20种], // stand/wave/cross-arms/run/...
"propTypes": [6种], // box/cylinder/sphere/cone/chair/wall
"defaults": { rigType, cameraFov, backgroundColor }
}
}
3. 场景管理
// 保存场景
POST /api/v1/director-desk/scene
{ projectId, episodesId, project: {...}, sceneId?: "my-scene", label?: "第一场" }
// 读取场景
GET /api/v1/director-desk/scene/:sceneId?projectId=X&episodesId=Y
// 列出所有场景
GET /api/v1/director-desk/scene?projectId=X&episodesId=Y
// 异步渲染（大数据量推荐）
POST /api/v1/director-desk/render
{ ..., "async": true } → { taskId }
GET /api/v1/director-desk/render/status/:taskId
参数总表
| 参数 | 路径 | 类型 | 取值范围 | 默认值 | 说明 |
|---|
| bodyType | characters[].bodyType | string | 8 种 | mannequin | 体型决定模型缩放 |
| pose | characters[].pose | string | 20 种 | stand | 预设骨骼姿势 |
| position | characters[].position | [x,y,z] | 世界坐标 | [0,0,0] | 角色位置 |
| rotation | characters[].rotation | number | 0-360 | 0 | Y轴旋转（度） |
| scale | characters[].scale | number | 0.5-1.5 | 1.0 | 以身体中心为原点 |
| camera.position | camera.position | [x,y,z] | 世界坐标 | autoFrame | 不传则自动取景 |
| camera.lookAt | camera.lookAt | [x,y,z] | 目标点 | [0,1,0] | 相机看向的目标 |
| camera.fov | camera.fov | number | 15-90 | 50 | 小=长焦，大=广角 |
| background | settings.background | hex | 任意颜色 | #1a1a2e | 背景色 |
| groundVisible | settings.groundVisible | bool | true/false | true | 地面网格 |
| width/height | body | number | 任意 | 1280×720 | 渲染分辨率 |
部署流程
# 1. SPA 重新构建（修改源码后）
cd ~/workspace/storyai-3d-director-desk
npx vite build # 跳过 tsc（有已知类型问题）
# 2. 复制到 platform（dist → data/web/director-desk）
cp -r dist/* ~/workspace/kais-aigc-platform/data/web/director-desk/
# 3. 重启 platform（_render.ts 用 tsx 热加载，无需 build）
cd ~/workspace/kais-aigc-platform
npx tsx src/app.ts
# 4. 验证
curl http://localhost:10588/api/v1/director-desk/capabilities | jq .
curl -X POST http://localhost:10588/api/v1/director-desk/render \
-H "Content-Type: application/json" \
-d '{"project":{"characters":[{"pose":"wave"}]}}' | jq .
渲染管线流程
- normalizeProject() — Agent 简写 → 完整 DirectorProject（度→弧度、缩放中心补偿）
- expandPosePresets() — pose ID → 骨骼 controls 键值对
- replaceProject() — 注入到 SPA 的 zustand store
- 等待 GLB 加载 — waitFor 3000ms（模型 + React 渲染）
- 相机应用 — Agent camera → 直接 set camera.position/lookAt/fov；否则 autoFrame
- requestViewportCapture() — SPA 内置 captureBridge（隐藏 helper 物体）
- canvas.toDataURL() — Three.js 原生渲染 → PNG base64
- 写文件 → OSS — Buffer → /data/oss/director-desk/xxx.png
已知限制
- 渲染速度：~6s/张（Playwright 启动 + GLB 加载 + WebGL）；3 并发约 2.7min/80 张
- 软件渲染：SwiftShader WebGL（无 GPU 加速）；headless Chrome 不支持 GPU
- 单模型：只有 UE4 mannequin 骨骼（所有体型共享同一拓扑）
- 无动画：静态姿势快照，不支持连续动画导出
- 低 FOV 截断：FOV < 30° 时角色可能超出画框（autoFrame 可解决，但与手动 camera 冲突）
待做（可选增强）
- Canvas 节点集成：storyboard 节点 → 自动生成场景 JSON → render → 缩略图回写
- Hermes Skill：封装为
kais-blender-engine skill 的轻量替代（不需要 Docker）
- 批量渲染 API：一次 POST 多个场景，返回多张图
- 全景背景：support
panoramaAssetId 加载 360° HDR 背景