树状工作台
本文属于“当前架构”文档,描述已经生效的 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=scenes | props |
/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_batchcoordinator 按该上限逐步入队,未到窗口的任务保持 pending; - 逐镜故事板、整集故事板一次提交多张图片时复用同一 coordinator,不绕过项目并发上限;
- coordinator 每轮都以新事务读取子任务状态,避免 MySQL REPEATABLE READ 旧快照造成「子任务已完成、批量却一直 running」;
- 单次 coordinator 执行最多推进约 4 分钟,未完成时把自己重新入队(交棒),不会触发 Celery 的 1 小时任务上限;
- 执行中的图片任务每 15 秒刷新一次任务心跳;running 超过 5 分钟没有心跳的失联子任务会重置回 pending 并重新入队;
- worker 启动时和运行期间每 60 秒运行看门狗,把超过 3 分钟没有心跳的
image_batchcoordinator 重新入队,覆盖 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/ 各节点中央面板