📚 视频创作 · 使用文档

侧边栏「📁 我的项目」→ 第一格 "+ 创建新项目" 虚线卡，或右上角 "+ 创建" 按钮。也可从首页「🧠 精选 Skills」点击 Skill 卡的「使用此 Skill 创建项目」按钮，系统会自动填充 Final Spec 和 3 个模板分镜。

填写项目名称（必填）、描述（选填）、Final Spec（画面比例 + 时长 + 分辨率 + 风格）。Final Spec 是整个项目的创作基调，后续所有分镜都将按此规格生成。

新项目创建后立即进入工作台，左栏自动初始化：Agent 自动发第一条问候消息 + 3 个模板分镜（草稿状态）。你可以立刻开始编辑。

网格列表展示所有项目，状态 Tab 筛选（全部/草稿/进行中/已完成/已归档），右上角搜索框 debounce 300ms 实时过滤。hover 卡片显示：打开、复制（克隆完整项目结构）、归档、重命名、删除。

左栏 = 故事板 + 分镜 | 中央 = 预览区 + 时间线 | 右栏 = Agent 对话 + Final Spec 编辑。三栏固定为浏览器高度（h-screen），每栏可拖拽宽度 + 可收起/展开（左栏收起 40px、右栏收起 48px），宽度状态 localStorage 持久化。

你编辑的 Final Spec、分镜 prompt、缩略图、时间线剪辑都会自动保存，右上角显示"● 已自动保存"绿色提示（800ms debounce）。不需要手动点"保存"按钮。

右侧 Agent 可以帮你：① 规划故事板结构；② 创建 / 更新 / 删除 分镜；③ 生成文案、镜头描述、场景设定。识别中文指令如"加一个夜景分镜"、"把第 3 个镜头改成推镜头"。

左栏顶部有两个 Tab：故事板（可视化卡片，支持拖拽重排）和分镜（列表视图，适合批量操作）。共享同一份 shots[] 数据。

每个分镜卡片包含：序号、状态（草稿 / 生成中 / 已生成 / 失败）、缩略图、prompt 文字、景别（wide/medium/close-up）、镜头角度（eye-level/low/high/dutch）、运动类型。

点击左栏底部"+ 新建分镜"按钮，会在当前末尾插入一个草稿状态的分镜。或者直接跟 Agent 说"加一个夜景分镜"让它帮你创建并写好 prompt。

按住分镜卡片左侧的拖拽把手（6 点手柄），拖到目标分镜的上半区 → 插入到前面；下半区 → 插入到后面。拖动时原位置变透明（opacity-40），目标位置高亮紫色边框（ring-purple-400）。松开后乐观更新 UI + 400ms debounce 持久化到后端；后端校验 ID 集合一致性（无重复、长度匹配、所有 ID 存在），通过一条 CASE WHEN SQL 批量更新 storyboardIndex。失败时从后端拉最新数据回滚。

每个分镜卡片右下角有"✨ 生成"按钮。点击后分镜状态变为"生成中"，后端任务异步处理。你可以继续编辑其他分镜，互不阻塞。

可以同时给多个分镜点"生成"，后端会排队处理。完成后缩略图自动刷新为生成结果。

如果对某个分镜效果不满意，直接再点一次"生成"—— 只重新生成这一个，其他分镜不受影响。

分镜卡片显示红色"失败"标签，hover 可查看错误详情。常见原因：Prompt 触发安全策略、上游模型超时、积分不足。修正 prompt 后重试即可。

中央预览区有三个 Tab：分镜（逐个预览每个分镜的生成结果）、最终成片（合成完成后可在这里播放完整 MP4）、时间线预览（时间线驱动的动态预览）。

点击左侧任意已生成分镜卡片，中央预览区立即切换到该分镜。如果分镜有生成视频则显示 <video controls playsInline>；只有图片则显示 <img>。

合成成功后"📹 看最终成片"按钮点亮，点击后切换到完整 MP4 播放视图。

底部有可折叠的时间线面板。收起时显示 footer + "🧨 打开时间线编辑器"按钮；展开时自动把中央预览区切换到"时间线"模式。状态 localStorage 持久化。

首次展开时间线时，系统自动把所有已生成视频的分镜装配成 video 轨道，每个 clip 的 start / duration 由分镜在 storyboard 中的顺序和 Final Spec 中的时长推断。

支持视频轨道、音频轨道（BGM / 旁白）、特效轨道。每个轨道独立滚缩 / 移动。

播放头可拖拽、空格键播放/暂停、左右箭头逐帧移动、Home/End 跳到开头/结尾、Loop 开关。中央预览区的视频 currentTime 和 src 跟随播放头变化。

右边缘裁剪（拖动右手柄 → 缩短时长）；左边缘裁剪（拖动左手柄 → 移动开始时间 + 缩短时长，确保不超过右边缘）；"split at playhead" 把一个 clip 在播放头位置切成两段。裁剪手柄宽度 12px，中间有白色竖线 hover 高亮。

Ctrl+Z 撤销、Ctrl+Y 重做，最多 50 帧历史。系统内部用 historyPast + historyFuture 双栈。注意：Agent 工具触发的自动 setTimeline 不进撤销栈。

时间线修改后 800ms debounce 自动 PUT 到 /studio/projects/:id/timeline，带 version 乐观锁。多人协作场景每次保存会 increment version。

顶部导航栏有"📹 合成成片"按钮（draft/in_progress 状态），合成中显示"⏳ 合成中…"，完成后变为"📹 重新合成"。

后端用 ffmpeg concat demuxer 实现：① 下载所有 status="done" 且有 generatedVideo 的分镜视频到临时目录；② 按 storyboardIndex 生成 list.txt；③ copy 模式直接拼接（最快），失败时 fallback 到 libx264/aac re-encode；④ 输出到 exports/{projectId}.mp4；⑤ 更新 vs_project.final_video_url + export_status + export_error；⑥ 清理临时文件。

合成触发后前端进入 2 秒轮询：exporting → completed（显示"看最终成片"+"下载 MP4"按钮）→ failed（显示 export_error）。30 分钟未完成会强制标记失败。

合成后的 MP4 通过 NestJS static assets 暴露到 /exports/*，前端直接 <video src="/exports/{projectId}.mp4"> 播放。

合成完成后可以直接发布到社区。发布入口在工作台右上角或合成成功后的提示里。

draft（草稿） → in_progress（进行中，至少有一个分镜生成中） → completed（所有分镜生成完毕）。archive 是归档态，不参与默认列表显示。

整个项目的 Final Spec、故事板、分镜、时间线都实时存数据库。关闭浏览器、断电重启都不会丢失。下次打开 /studio/[id] 自动恢复到上次状态。

卡片 hover 菜单里的"复制"会克隆完整项目结构（Final Spec + 所有分镜的 prompt 和状态），但不会复制已生成的视频—— 你可以作为新起点继续创作。