Skip to content

树状工作台

本文属于“当前架构”文档,描述已经生效的 V2 树状工作台。 历史页面退役与深链接映射见 V2 工作台迁移与旧页面退役清单。

定位

工作台把项目、剧集、镜头与全局资产收进同一套「左树 + 中编辑区 + 右属性栏 + 底部任务栏」布局, 是项目制作的主入口。

当前边界:

  • 树与面板只使用真实接口,不提供静态演示数据;
  • 项目创建/编辑在项目列表完成,进入项目后不再依赖旧版项目页;
  • 剧集新增/改名/删除、剧本原文编辑、AI 解析、分镜规划与确认、资产档案、参考素材、视频生成、审核与选择式导出都在 V2 内完成;
  • 旧版项目页、章节页、分镜页、分镜工作室、角色编辑页只保留安全重定向;
  • 不引入无限画布,也不复制一套新的业务状态机。

路由契约

所有节点都挂在 /projects/:projectId/workbench/* 下,使用 URL 表达选中对象:

路由选中节点
/workbench、/workbench/overview项目总览
/workbench/config项目配置(P2 起可编辑)
/workbench/script世界观与剧本(项目级)
/workbench/script/:chapterId某一集的剧本原文
/workbench/style风格圣经
/workbench/assets/:type角色 / 场景 / 道具 / 服装列表
/workbench/assets/:type/:assetId单个资产
/workbench/episodes/:chapterId某一集
/workbench/episodes/:chapterId/shots/:shotId某个镜头
/workbench/export导出

为什么用路径段而不是 ?node=shot:xxx:

  • 层级与业务结构一一对应,可读、可分享、可被日志直接识别;
  • 刷新、深链接、浏览器前进后退都由路由天然承担,不需要额外同步内存状态;
  • 查询参数更适合表达「同一节点的显示选项」,不适合表达资源定位。

路由使用 splat(workbench/*)+ frontend/src/features/workbench/routes.ts 解析, 因此新增节点类型只需扩展解析函数,不必为每一层再注册一次嵌套路由。

布局

front/src/features/workbench/WorkbenchLayout.tsx:

顶部:返回项目列表 / 项目名称 / 制作进度 / 主题 / 语言 / 账号
左侧:项目资源树(220–420px,可拖拽,偏好存 localStorage)
中央:当前节点面板(唯一滚动区)
右侧:属性面板(240–420px,可收起)
底部:任务中心(120–360px,可收起)

响应式规则:

  • < 1024px:左树改为抽屉;
  • < 1280px:右栏改为抽屉;
  • 抽屉与桌面面板互斥渲染,避免同一棵树挂两份 DOM。

工作台路径下 AppShell 直接返回 Outlet,不渲染旧侧边栏与全局浮窗, 避免双导航;任务轮询仍复用同一个 TaskRuntimeProvider,底部任务栏与浮窗同源。

树节点

front/src/features/workbench/buildTree.ts 是纯函数,输入真实业务数据,输出:

项目
├── 项目配置
├── 世界观与剧本
├── 风格圣经
├── 全局资产
│   ├── 角色(项目内资产)
│   ├── 场景(工作区全局资产)
│   ├── 道具
│   └── 服装
├── 第 1 集
│   └── 镜头 01 / 02 / …
├── 第 2 集
└── 导出

规则:

  • 节点 ID 只使用业务 ID 拼接(episode:<id>、shot:<id>、asset:<type>:<id>),不用数组下标;
  • 剧集按 index 升序,镜头按 index 升序;
  • 镜头按剧集懒加载:只有展开的剧集才会请求镜头与 runtime summary;
  • 未加载完成时显示「正在加载镜头…」,失败显示「镜头加载失败」,不把未知状态写成 0;
  • 搜索只过滤已加载节点;命中后代时保留祖先,但不会因为父节点命中就把整集镜头铺开;
  • scene-group 来自正式 scene_groups;历史无场次镜头归入「未分配场次」,不伪造场次;
  • 剧集节点显示制作阶段文案(未输入剧本 / 待规划分镜 / 分镜待确认 / 分镜已确认 / 镜头生成中 / 已完成),只做后端状态映射;
  • 左树工具栏固定提供「新增剧集」:位于搜索框下方并占满整行,不与「全部展开/收起/刷新」挤在同一行;零集、一集、多集和窄屏抽屉中位置一致。
  • 创建成功后立即写入剧集缓存、按 index 排序并展开新剧集节点,随后进入该集剧本面板;失败时保留对话框输入并显示服务端原因。

数据来源

全部走 services/generated(OpenAPI 客户端),没有新的手写接口封装:

数据接口说明
项目GET /studio/projects/{id}名称、题材、进度、生成参数
剧集GET /studio/chapters?project_id=按 index 升序
镜头GET /studio/shots?chapter_id=按 index 升序,展开时加载
运行时摘要GET /studio/shots/runtime-summary?chapter_id=镜头节点上的运行中标记
镜头详情GET /studio/shots/{id} / shot-details/{id}基础信息与镜头语言
准备状态GET /studio/shots/{id}/preparation-state待确认项与生成准备
视频准备度GET /studio/shots/{id}/video-readiness?reference_mode=reference仅选中镜头时请求
角色GET /studio/entities/character工作区返回后按 project_id 收敛
场景 / 道具 / 服装GET /studio/entities/{type}工作区级全局资产
风格目录GET /studio/styles说明与提示词质感描述
时间线GET /studio/timeline/projects/{id}导出面板的片段统计

分页策略(front/src/features/workbench/api.ts):

  • 每页 100 条(与后端上限一致),按 max_page 翻到最后一页;
  • 超过 200 页(20,000 条)时抛错而不是静默截断,避免用户误以为镜头丢了。

状态展示

树与面板严格区分三类状态,颜色取自 state-* / run-* / ready-* 三组 token:

语义来源展示位置
信息提取确认shot.status、preparation-state树节点圆点、镜头面板「信息确认状态」
运行时任务GenerationTask / runtime summary树节点运行中圆点、底部任务栏
视频生成准备度video-readiness镜头面板与右侧属性栏
  • 历史上的 generating 不再表示运行时状态,前端按「未确认」处理;
  • 运行中不会写回 shot.status;
  • video-readiness 只对当前选中的镜头请求,避免对几百个镜头做 N+1 查询。

旧版页面退役

旧版项目页与章节制作页不再渲染业务组件,只做安全重定向:

旧地址V2 落点
/projects/{id}?tab=settings/workbench/config
/projects/{id}?tab=chapters(可带 edit / create)/workbench/script[/{cid}]
/projects/{id}?tab=roles/workbench/assets/character
`/projects/{id}?tab=scenesprops
/projects/{id}/chapters/{cid}/shots/workbench/episodes/{cid}
/projects/{id}/chapters/{cid}/shots/{sid}/edit/workbench/episodes/{cid}/shots/{sid}
/projects/{id}/chapters/{cid}/studio/workbench/episodes/{cid}
/projects/{id}/chapters/{cid}/board/workbench/episodes/{cid}
/projects/{id}/chapters/{cid}/review/workbench/script/{cid}
/projects/{id}/roles/{rid}/edit/workbench/assets/character/{rid}
/projects/{id}/editor/workbench/export

/assets/* 全局素材库、/files、/styles、/models、/voices、/settings 仍是独立支持页面,不属于旧版项目制作链路。

项目概述与图片生成并发

  • 项目概述允许编辑 image_concurrency(1–16,默认 2),作为该项目批量图片任务的同时运行上限;
  • 批量资产图片由独立 image_batch coordinator 按该上限逐步入队,未到窗口的任务保持 pending;
  • 逐镜故事板、整集故事板一次提交多张图片时复用同一 coordinator,不绕过项目并发上限;
  • coordinator 每轮都以新事务读取子任务状态,避免 MySQL REPEATABLE READ 旧快照造成「子任务已完成、批量却一直 running」;
  • 单次 coordinator 执行最多推进约 4 分钟,未完成时把自己重新入队(交棒),不会触发 Celery 的 1 小时任务上限;
  • 执行中的图片任务每 15 秒刷新一次任务心跳;running 超过 5 分钟没有心跳的失联子任务会重置回 pending 并重新入队;
  • worker 启动时和运行期间每 60 秒运行看门狗,把超过 3 分钟没有心跳的 image_batch coordinator 重新入队,覆盖 worker 重启或交棒消息丢失;
  • 图片 worker 的总并发由部署侧 dyeingtime-celery-image 配置,项目设置不能超过实际 worker 与供应商能力;
  • 单个资产手动生成仍立即入队,不受批量 coordinator 的窗口控制;
  • 资产列表会显示「待选用」候选预览(candidate_thumbnail),生成完成后自动轮询刷新;候选只有显式「选用为当前图」后才会写入资产当前图槽位。

剧集、资产与时长

  • 剧集新增、改名、删除在 V2 完成;删除剧集会级联删除本集镜头与关联数据,但保留项目。
  • 系统操作统一使用「剧集」:首次创建显示「创建第1集」,后续显示「新增第 N 集」,编辑入口显示「编辑剧集」;不修改用户填写的标题或原文。
  • 剧集序号由客户端按当前最大 index 生成,后端保留 project_id + index 唯一约束并给出可执行的重复提示。
  • 角色、场景、道具、服装均可在 V2 内新增、查看、编辑、删除;空状态提供「新建…」入口。
  • 删除资产会清理其版本、候选图、提示词审核稿与镜头资产版本,并停用镜头参考绑定;历史生成快照保持不变。
  • 剧本原文可直接编辑;未保存草稿按「项目 + 剧集」写入 localStorage,切换剧集后可恢复。
  • 项目配置默认「AI 智能规划镜头时长」;只有显式开启时长偏好时,default_shot_duration 才作为参考值/兜底。
  • 单镜头在 ShotPanel 内修改的是实际请求时长,并受「项目范围 ∩ 模型能力」约束;前端与服务端使用同一范围语义。
  • 历史越界时长(例如统一范围前保存的 3 秒)不会被静默改写:保存其他字段时允许保留,但会明确提示,视频准备度仍会阻塞生成。

参考素材与生成预览

  • 术语统一为「镜头参考素材」,按人物 / 场景 / 道具 / 服装 / 首帧分类。
  • 自动匹配基于 ShotAssetVersion;历史镜头回退到 ShotCharacterLink 与 ShotDetail.scene_id,不按文件名猜测。
  • 支持从项目资产库添加、从已确认帧添加、上传、锁定、替换、移除与恢复。
  • 「生成输入预览」展示模型、模式、请求时长、实际进入请求的图片、警告与阻塞项。
  • 预览 manifest、最终 Renderer 编号、生成任务快照使用同一份有序 file_id 列表;素材变更后旧预览失效,必须重新预览。
  • 生成按钮必须人工确认,不会因打开页面、自动匹配或选择素材而触发付费任务。

相关文件

front/src/features/workbench/
├── WorkbenchPage.tsx          页面容器:路由解析、取数、面板分发
├── WorkbenchLayout.tsx        三栏布局、拖拽调宽、抽屉
├── WorkbenchTree.tsx          资源树、搜索、键盘导航
├── WorkbenchInspector.tsx     右侧只读属性
├── WorkbenchTaskDock.tsx      底部任务栏
├── routes.ts                  路由构造与解析
├── buildTree.ts               纯函数树装配与过滤
├── deriveStage.ts             章节阶段推导
├── useWorkbenchQueries.ts     TanStack Query 查询
├── api.ts                     翻页拉全与数据归一
├── usePanelResize.ts          面板尺寸与持久化
└── panels/                    各节点中央面板