lunanting/ai-chatbot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
ai-chatbot/docs/storyai-director-desk-integration.md

9.3 KiB
Raw Blame History

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 生成完整任务；上传、预处理、按钮状态、费用显示和宿主消息链路已经验证。