61 lines
9.3 KiB
Markdown
61 lines
9.3 KiB
Markdown
# StoryAI 3D Director Desk 集成审计
|
||
|
||
## 结论
|
||
|
||
可以直接复用，而且本项目已经完成复用，不再使用 CSS 模拟导演台视口。上游是 MIT 许可的真实 React Three Fiber / Three.js 编辑器，并提供宿主通信桥；当前版本已通过同源 iframe、`postMessage`、画布节点数据和后台配置接入，不需要从零重写 3D 场景、机位和角色编辑内核。
|
||
|
||
## 固定版本
|
||
|
||
- 仓库：https://github.com/jiguang132/storyai-3d-director-desk
|
||
- 提交：`8c8bd361790be4d37158a7430365e65546e358fe`
|
||
- 上游状态：2026-07-14 通过 `git ls-remote` 复核，`HEAD` 与 `main` 仍指向上述提交，无版本漂移；上游当前没有 release 或 tag。
|
||
- 许可证：MIT；内置 UE Mannequin 另附 Sketchfab Standard 许可说明
|
||
- 技术栈：React 18、Vite 6、TypeScript、Three.js、React Three Fiber、Drei、Zustand
|
||
- 上游构建：`npm run build` 通过，生产 JS 约 1.37 MB，gzip 约 382 KB
|
||
- 上游测试：304/312 通过；8 项失败集中在模型库缺失和视觉常量/样式断言漂移
|
||
|
||
## 已接入
|
||
|
||
- 构建产物固定在 `/public/vendor/storyai-director`，Vite 使用相对基址 `./`，可从 `/vendor/storyai-director/` 子目录加载带哈希的 JS/CSS；目录内保留上游 `LICENSE`、`SOURCE-NOTICE.md` 和模型素材的独立许可说明。
|
||
- 视频画布通过同源 iframe 打开真实导演台，以导演节点 ID 作为场景隔离键。
|
||
- 全景图入口已对齐竞品的 `本地上传 / 历史记录 / AI生成`。iframe 把请求发给宿主，宿主创建外层图片节点和图片到导演节点的有向边；取消链接时同步移除对应画布边。
|
||
- 导演台发送的真实 PNG 截图通过现有图片上传服务归档，再创建为导演节点的下游图片节点，不再使用固定演示图。
|
||
- `/settings/video-canvas` 新增导演台启停、同源嵌入地址、帮助文档地址和四/十二方位截图显示开关，运行时从 `video_canvas_function_config` 读取。
|
||
- 宿主只在收到 `storyai:director-desk-ready` 后显示 iframe；每次打开生成唯一 `frameSession` 避免静态入口复用旧哈希缓存，首次 10 秒超时会自动换地址重载一次，再失败时显示手动“重新加载”。
|
||
- 角色姿势预设由 `directorDesk.posePresets` 运行时下发，StoryAI store 不再要求 UI 直接读取固定常量；后台以 JSON 维护 20 套预设和骨骼角度。
|
||
- 机位视角预设由 `directorDesk.cameraPresets` 运行时下发；后台可维护动态当前视角及固定位置、注视点和 FOV，StoryAI 根据配置生成摄像机快照。
|
||
- `directorDesk.panorama` 运行时配置控制 PNG 上传格式、AI 费用显示、预处理延时、历史数量、输出比例和尺寸；`director-panorama-ai` 功能项控制后端模型与系统提示词。
|
||
- 开发环境在 `USE_REMOTE_STORAGE_IN_DEV!=true` 时将 `canvas-upload` 写入 `public/uploads/local`，避免复制的生产 S3 端点在本机超时；生产存储、权限校验和媒体资产登记逻辑不变。
|
||
|
||
## Chrome 回归结果
|
||
|
||
- 本地已从空画布创建导演台节点并打开 iframe；场景树、蓝色 UE Mannequin、网格、坐标轴、变换工具和右侧属性面板均为真实 WebGL/DOM 状态，不存在登录重定向或空白画布。
|
||
- `导演视角 -> 机位视角` 会自动选择 `机位1`、启用活动 PerspectiveCamera，并把右侧切为摄像机属性。选择 `9:16` 后取景框、遮罩和导出裁切同步生效。
|
||
- `当前视角截图 -> 发送到画布` 已完整跑通：iframe 生成真实 PNG，宿主上传到对象存储，创建下游图片节点与有向边，关闭导演台后画布能看到截图结果。
|
||
- 上传后的 CDN 首次加载竞态已由媒体节点有限次数指数退避重试修复；回归图片尺寸为 `640 × 1138`。
|
||
- 竞品相同链路已实测：点击截图时先上传并显示 `正在上传截图...`，生成机位内递增 shot 卡片；点击卡片发送按钮后才创建画布图片节点和边。
|
||
- 竞品变换入口实测为单按钮菜单 `移动 V / 旋转 R / 缩放 S`。内置 StoryAI 已改为相同结构并支持快捷键，角色属性页会回到移动模式。
|
||
- 竞品没有四/十二方位截图入口；内置扩展能力由后台开关控制并默认隐藏。Chrome 已验证 `batchCapture=0` 不渲染按钮、`batchCapture=1` 渲染两个按钮。
|
||
- 本轮 Chrome 还定位并修复了静态包根路径错误造成的纯黑 iframe；父画布内现已验证真实 WebGL 画面非空，iframe ready 后类名为 `opacity-100`。
|
||
- 最终静态哈希替换后又复现一次旧入口缓存；加入每次挂载唯一 `frameSession` 后，Chrome 实测关闭再打开可直接加载最新哈希，iframe 首次即为 `opacity-100`，不再依赖手动重载。
|
||
- 竞品 20 套姿势的 25 个可见关节角度已全部通过 Chrome 逐项采集，每次应用后都用 `Cmd+Z` 验证原状态恢复。本地运行时配置的 20 个入口和 `T型` 全部关键角度已浏览器回归一致。
|
||
- 竞品全景图已实测：PNG 上传自动创建外层图片节点与入边，水平旋转和半径修改均可一次 undo；AI 面板在约 3 秒处理后启用费用 `22` 的生成按钮。
|
||
- 本地同一 PNG 已完整回归：生成 `codex-panorama-source` 外层节点和 1 条边，导演台显示 `已连接全景图 / 取消链接`，历史条目显示 `使用中`，AI 上传预处理后 `生成 22` 可用。未点击生成，避免未确认的外部模型费用。
|
||
- 竞品场景设置已逐项实测：四个开关默认为 `角色标签 on / 网格吸附 off / 高斯地面吸附 on / 地面 on`；场景缩放滑杆使用倍率 `0.1..10`、文本显示 `10%..1000%`。本地已补齐相同默认值、旧工程迁移、缩放编辑语义和两列开关布局。
|
||
- 竞品场景树已逐项实测为 `道具 -> 机位 -> 角色` 扁平顺序；搜索、无结果文案、选中保留、显隐/锁定动态动作和单步撤销均已在本地 Chrome 对照通过。StoryAI 去除了可见分组标题，但保留群众展开、多选和成员预览扩展能力。
|
||
- 构图参考线已按竞品完成：具体画幅内右上角使用小型 `构图参考线` 开关，开启时只绘制三分线；`Cmd+Z` 不影响该临时状态，关闭并重开导演台恢复关闭。Chrome 已验证 `Value: 0 -> 1 -> Cmd+Z 仍为 1 -> 重开后 0`，旧快照中的开启值也不会再恢复。
|
||
- 顶栏 `帮助 / 关闭` 已按竞品完成：帮助地址由宿主配置下发，iframe 具备受限的新标签弹窗权限；Chrome 已验证新标签最终导航到 `LibTV使用指南 - 飞书云文档` 的准确飞书 URL。关闭仍只卸载全屏 iframe，保留外层导演台节点和再次打开入口。
|
||
- 画幅比例菜单已按竞品完成：可见选项固定为 `Auto / 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16`，选择后保持菜单展开，比例变化不进入 undo，重复点击入口才收起。Chrome 已逐步验证 `Auto -> 21:9 -> Cmd+Z 仍为 21:9 -> 9:16 -> 关闭菜单`，取景框、遮罩和选中态同步正确。
|
||
- 视口全屏已按竞品完成：进入后仅折叠左右侧栏，顶栏、3D 视口、画幅框和工具条保留，单按 `Escape` 不退出，再点同一入口恢复。折叠态现为不进入 undo 和项目快照的会话 UI；Chrome 已验证全屏态关闭并重开后侧栏恢复，而 `9:16` 画幅和工程状态保留。
|
||
- 机位视角预设已按竞品完成：`添加机位` 展示相同顺序的 15 项双列菜单；14 个固定预设使用逐项采集的位置、注视点和 FOV，`当前视角` 使用实时视口快照。Chrome 已验证 `正面特写` 和动态当前视角的创建、属性联动与单步撤销，菜单与全景图浮层互斥。
|
||
- 摄像机属性面板已按竞品完成：原生机位/跟随/注视下拉框、名称延迟提交、机位视角快捷键、位置/偏移、旋转、手动坐标与手动旋转双状态、对象注视、第一/第三人称跟随、`15..90` 整数 FOV 和空截图区均已对齐。默认位置/注视/旋转为 `[0,2.2,10] / [0,1.2,0] / [5.71,180,0]`，旧机位与截图名称在加载时迁移为 `机位1 / 机位1-shot-01`。
|
||
|
||
## 当前边界
|
||
|
||
- 工程 JSON 已通过 `storyai:director-desk-project-updated` 写回导演节点的 `directorProject` 并随画布数据库持久化，跨浏览器和环境复制恢复已验证；`localStorage` 只保留独立运行兜底，不再是宿主模式的唯一数据源。
|
||
- 上游模型库引用的外置中文 FBX 目录未随仓库或服务器提供，因此竞品对齐版本不展示这些失效资源。后续若开放模型库，必须接入自有后台素材并逐项确认模型、贴图和缩略图分发许可。
|
||
- 角色姿势、机位、群众默认值、全景图和高斯配置均已改为宿主运行时下发。角色基础网格仍使用随包 UE Mannequin，其 Sketchfab Standard 许可需要与静态包一起保留。
|
||
- Gaussian Splat 已支持 PLY/SPLAT/SPZ/KSPLAT 上传、解析、渲染、射线命中和落地补偿，不再是占位开关。
|
||
- 当前固定版本与上游 HEAD 相同，但本地补丁较大。升级时必须从固定提交重新应用 `patches/storyai-3d-director-desk-local.patch`，完整运行 StoryAI 测试、TypeScript、生产构建和父画布 Chrome 回归，不能直接替换哈希静态包。
|
||
- 未执行的只有会真实消耗积分的 AI 生成完整任务；上传、预处理、按钮状态、费用显示和宿主消息链路已经验证。
|