2026-05-14 · 视频抽帧面板默认静音播放
Input Video问题:输入视频缩略图改为单击打开抽帧面板后,面板播放器如果自动播放带声音,会打断工作流。
改动:VideoFramePanelNode 的主播放器增加 muted,默认静音自动播放;用户仍可通过浏览器视频 controls 自行取消静音。
影响:web/components/nodes/index.tsx、docs/source-analysis.html。
它把“你看到的界面、你想改的功能、实际要动的源码、可能影响的数据和接口”放在同一个地方。 后续描述需求时,可以直接说“改源码地图里的某个区域 / 某个节点职责 / 某个接口行为”,这样改动范围会更准,也更容易追踪每次变更带来的影响。
例如“镜头拆解 / 元素提取面板”、“元素改造 Storyboard 节点”、“分镜头编排下拉区 4 图槽”。不要只说“这里乱”,要指向页面里的功能区。
例如“Vision 只给候选元素,用户必须能编辑、删除、重新提取”,这会直接落到 FrameLightbox 和元素接口。
例如“点击元素不要跳页面”、“不要直接进入编排打断思路”、“不要把参考视频复刻成一样的东西”。这能约束交互和文案。
建议表达格式:我要改「功能区」;当前问题是「行为」;正确职责是「业务目的」;不要影响「已有流程」。
| 项目 | 命令 / 入口 | 说明 |
|---|---|---|
| 前端开发服务 | cd web && pnpm dev |
Next.js App Router,主页面是 web/app/page.tsx,默认端口 4290。 |
| 后端开发服务 | cd api && source .venv/bin/activate && uvicorn main:app --port 4291 --reload |
FastAPI,所有任务状态、视频、关键帧、清洗、元素、分镜保存都在 api/main.py。 |
| 测试页面 | http://localhost:4290/?job=c6767f3a166b |
URL 里可放多个 job id:?job=id1,id2,id3,前端会恢复多个任务并激活最后一个。 |
| 源码解析页 | open docs/source-analysis.html |
独立静态 HTML,不被 Next 构建、不影响产品工作台。 |
当前产品不是“复制别人的视频”,而是拆解参考视频,提取可借鉴的镜头元素,再改造成 SKG 产品语境的视频素材。
TK 链接或本地上传,后端下载/保存源视频。
拆轨、抽关键帧、手动加帧,形成参考分镜池。
对关键帧做全图或区域清洗,必要时应用为当前参考图。
识别场景和候选元素,只是候选,不应锁死。
编辑/新增/删除元素,对元素反复生成提取图。
把参考主体、场景、动作和 SKG 产品放入分镜结构。
用分镜 4 图槽、改造目标和时长调用 Seedance / Kling / Veo 3 生视频 API,结果回写到画面工作台节点。
片段、字幕、配音、转场合成最终 mp4。当前未实现。
web/app/page.tsx | 产品工作台主状态:jobs、activeJobId、selectedFrames、clipboard、ReactFlow 节点和边;负责打开/找回画布工作面板。 |
web/components/nodes/index.tsx | DAG 节点定义:Input、VisualLab、Audio、Compose,以及画布工作面板 KeyframePanel / VideoFramePanel;旧 Keyframe/Storyboard/VideoGen 组件保留但不再挂主画布。 |
web/components/lightbox.tsx | 镜头拆解和元素提取的主工作面板:清洗、识别、元素编辑、区域提取、抠图。 |
web/components/storyboard-bar.tsx | 顶部分镜编排条:展示选入编排的关键帧,并作为唯一分镜导航。 |
web/components/storyboard-workbench.tsx | 顶部分镜编排条下方的明细区:4 图槽、改造目标、时长、自动保存。 |
web/lib/api.ts | 前端类型和 API client,是前后端数据契约镜像。 |
api/main.py | FastAPI 单文件后端:状态模型、任务恢复、下载、抽帧、Vision、清洗、元素、分镜、文件返回。 |
jobs/<jobId>/state.json | 运行时状态文件,不在源码列表里,但刷新恢复依赖它。 |
jobs/<jobId>/frames | 关键帧 jpg。注意 frame.index 是稳定 ID,不等于数组下标。 |
jobs/<jobId>/cleaned | 清洗后待应用图片。 |
jobs/<jobId>/elements | 元素提取图,多版本命名:idx_elementId_cutoutId.jpg。 |
jobs/<jobId>/gen | 关键帧生图结果。 |
前端主链路: web/app/page.tsx -> ReactFlow 节点:web/components/nodes/index.tsx -> 主画布:Input → VisualLab / Audio → Compose -> 画布内视频抽帧面板:InputNode 双击视频缩略图打开 videoFramePanel -> 画布内镜头拆解面板:VisualLabNode 打开 keyframePanel,内嵌 web/components/lightbox.tsx -> 分镜工作台:web/components/storyboard-workbench.tsx(底层保留) -> API 契约:web/lib/api.ts 后端主链路: api/main.py -> Job / KeyFrame / KeyElement / StoryboardScene -> 下载 / 上传 / 抽帧 / Vision / 清洗 / 元素提取 / 分镜保存 -> jobs/<jobId>/state.json + 图片文件落盘
InputNode in web/components/nodes/index.tsx;状态处理在 page.tsx。VisualLabNode in web/components/nodes/index.tsx;它汇总关键帧、元素 cutout 和视频任务缩略图。FrameLightbox;类型 KeyElement;接口 addElement/updateElement/deleteElement/cutoutElement/deleteCutout。StoryboardWorkbench;保存到 frame.storyboard;接口 PUT /storyboard。一个视频任务。前端维护多个 jobs[],当前激活的是 activeJobId。URL 查询参数会持久化多个 job。
Job {
id, url, status, progress, message,
video_url, duration, width, height,
frames: KeyFrame[],
transcript: TranscriptSegment[],
storyboard_images?: StoryboardImage[]
}
关键帧是整个产品的核心单位。index 是稳定 ID,手动加帧后不连续,不能用数组下标代替。
KeyFrame {
index, timestamp, url,
description,
cleaned_url, cleaned_applied,
elements: KeyElement[],
storyboard: StoryboardScene,
generated_images: GeneratedImage[]
}
从关键帧里识别或手动添加的可借鉴元素。Vision 给的是候选,用户可编辑,并可多次生成提取图。
KeyElement {
id,
name_zh, name_en, position,
source: auto | manual | region,
region,
cutouts: string[],
cutout_id
}
分镜编排结果,不是复刻说明。它把参考图和 SKG 改造方向绑定到一个分镜上。
StoryboardScene {
duration,
subject_image,
scene_image,
product_image,
action_image,
subject,
product,
scene,
action
}
| 功能 | 接口 | 前端调用 | 说明 |
|---|---|---|---|
| 历史列表 | GET /jobs | listJobs | 所有 job 精简列表(id/url/status/thumbnail/mtime…),按 state.json mtime 倒序。前端 URL 无 ?job= 时拉它回填全部历史;带 limit 可截断。 |
| 创建任务 | POST /jobs | createJob | 提交 TK 链接,后台开始下载,停在 downloaded 等用户点解析。 |
| 上传视频 | POST /jobs/upload | uploadJob | 保存 source.mp4,然后同样进入下载完成状态。 |
| 删除输入视频 | DELETE /jobs/{id} | deleteJob | 从任务队列、URL 和磁盘 jobs/<id> 目录移除整个 job,包括源视频、关键帧、元素提取图和生成视频。 |
| 解析视频 | POST /jobs/{id}/analyze | analyzeJob | 拆轨 + 抽关键帧。当前不自动跑 ASR,避免 audio 阻塞视觉管线。 |
| 手动加帧 | POST /jobs/{id}/frames?t= | addManualFrame | 按视频时间戳抽一帧,index 递增但 frames 按 timestamp 排序。 |
| Vision 识别 | POST /frames/{idx}/describe | describeFrame | 写入 frame.description,后续可从 objects 加候选元素。 |
| 清洗水印 | POST /frames/{idx}/cleanup | cleanupFrame | 支持全图和区域清洗,生成 cleaned 待应用版本。 |
| 应用清洗 | POST /cleanup/apply | applyCleanedFrame | 物理覆盖 frames/{idx}.jpg,并备份原图。 |
| 元素增改删 | POST/PATCH/DELETE /elements | addElement/updateElement/deleteElement | 让用户修正 Vision 错误,避免候选结果锁死。 |
| 元素提取 | POST /elements/{element_id}/cutout | cutoutElement | 调用图像模型生成独立白底素材图,每次累积一张 cutout。 |
| 分镜保存 | PUT /frames/{idx}/storyboard | updateStoryboard | 保存 4 图槽、时长和改造说明。 |
| 生图 | POST /frames/{idx}/generate | generateImage | 基于关键帧或已选生成图做 image-to-image,目前可用。 |
| 节点 | 当前职责 | 不该承担 | 改动主要文件 |
|---|---|---|---|
| 输入 Input | 创建/上传任务,显示视频就绪,触发解析;双击视频缩略图打开画布内抽帧面板。 | 不要自动一路跑到 ASR 或生图;用户需要控制解析节奏。 | page.tsx、InputNode、VideoFramePanelNode、api/main.py |
| 画面工作台 Visual Lab | 在一个画布卡片里展示关键帧、元素 cutout 和视频任务;点击缩略图进入对应处理面板。 | 不要在主卡片里堆复杂表单;主卡片只做状态总览和入口。 | VisualLabNode、FrameLightbox、StoryboardWorkbench、视频任务接口 |
| 分镜工作台 | 每个分镜填 4 图槽和改造 brief,为后续生成首帧/视频片段做准备。 | 当前不负责真实调用视频模型。 | StoryboardWorkbench、updateStoryboard |
| ASR / Translate / Rewrite | 未来的文案轨,目前部分占位或受 audio 阻塞。 | 不要阻断视觉素材管线。 | ASRNode、TranslateNode、RewriteNode、ASR 接口 |
| Video / Compose | 视频任务状态展示在 Visual Lab;Compose 承载最终合成。 | 不要把 Compose 提前变成视频生成控制台。 | VisualLabNode、/storyboard/video、generated_videos、ComposeNode |
seedance-2-fast、kling-omni、veo-3.1-fast,提交后写入 Video Gen 节点。最重要的产品判断:当前视觉素材管线已经能继续推进,文案/音频/视频生成不要再反过来卡住镜头拆解和元素改造。
“我在关键帧 lightbox 里,Vision 识别后的元素列表应该怎么编辑/重提取/删除;点击元素不要跳转;提取图怎么预览和复制。”
“我在 DAG 的元素改造节点,它上方缩略图展示什么、hover 预览什么、点击后是否进入工作台、是否自动选中对应分镜。”
“我在顶部分镜头编排下拉面板,每个分镜需要哪些槽位、字段如何命名、保存后如何传给后续生成视频。”
“这个动作需要持久化到 state.json,字段加在 Job/KeyFrame/KeyElement/StoryboardScene 哪一层,刷新后要恢复。”
“这个节点的业务职责要改,不只是 UI 文案;请同步更新节点标题、subtitle、说明、可点击行为、状态推导和本源码解析页。”
这个记录不是 git log 的替代品。它记录“产品理解发生了什么变化、影响了哪些源码、你以后描述需求时该怎么说”。后续每次改功能都要补一条。
问题:输入视频缩略图改为单击打开抽帧面板后,面板播放器如果自动播放带声音,会打断工作流。
改动:VideoFramePanelNode 的主播放器增加 muted,默认静音自动播放;用户仍可通过浏览器视频 controls 自行取消静音。
影响:web/components/nodes/index.tsx、docs/source-analysis.html。
问题:视频抽帧面板和画面工作台详情面板框架一致后,标题栏颜色也需要分别跟各自来源卡片一致;输入视频缩略图仍需要双击才能打开抽帧面板,操作偏重。
改动:视频抽帧面板标题栏使用 --grad-input,画面工作台详情面板标题栏使用 --grad-ai;输入视频缩略图改为单击打开抽帧面板,hover 仍负责尺寸预览。
影响:web/components/nodes/index.tsx、docs/source-analysis.html。后续面板颜色应从来源卡片类型继承。
问题:关键帧详情 / 元素提取面板虽然默认左侧吸附,但外层仍是旧橙色“钉住”框架,和视频抽帧面板的紫色标题栏、画布/左/右/底吸附按钮不一致。
改动:KeyframePanelNode 改为和 VideoFramePanelNode 同一套 Canvas Panel 外壳:紫色标题栏、画布模式、吸附左侧、吸附右侧、吸附底部、缩放、关闭和右下角拖拽缩放。面板定位状态从单一 pinned 语义升级为 framePanelDock。
影响:web/app/page.tsx、web/components/nodes/index.tsx、docs/source-analysis.html。后续工作面板应复用这套 Canvas Panel 框架。
问题:画面工作台详情面板外层已有“关键帧详情 · 元素提取”工具栏,内层 FrameLightbox 嵌入态又显示一条橙红分镜导航栏,视觉上像两个窗口叠在一起。
改动:FrameLightbox 在 embedded 模式下不再渲染自己的顶部工具栏和外边框;上一帧 / 下一帧导航移动到 KeyframePanelNode 外层标题栏。
影响:web/components/lightbox.tsx、web/components/nodes/index.tsx、docs/source-analysis.html。非嵌入式 lightbox 保留原标题栏。
问题:画面工作台点击关键帧后,关键帧详情 / 元素提取面板仍默认作为画布节点出现,还会触发 fitView 拉动画布;和视频抽帧面板默认左侧吸附的规则不一致。
改动:framePanelDock 初始值改为 left;从关闭状态打开关键帧详情时默认吸附左侧。若面板已打开,用户切回画布模式后继续切换关键帧,不会被强制吸回左侧;默认吸附状态下也不再触发画布 fitView。
影响:web/app/page.tsx、docs/source-analysis.html。画面工作台处理面板现在与视频抽帧面板保持同一默认策略:先贴左侧,需要时再切回画布。
问题:视频抽帧面板默认以画布节点方式打开时,用户还要再点一次吸附左侧,和“处理面板先贴边、需要时再拖回画布”的工作习惯不一致。
改动:videoPanelDock 初始值改为 left;从关闭状态双击输入视频缩略图时默认吸附左侧。面板已打开后,用户手动切换到画布 / 右侧 / 底部不会被找回动作覆盖。
影响:web/app/page.tsx、docs/source-analysis.html。后续同类处理面板应优先考虑“默认贴边,必要时切回画布”的交互。
问题:视频抽帧面板只能新增关键帧,用户看到“已抽关键帧”后不能在同一工作上下文里清理误抽的帧。
改动:已抽关键帧缩略图右上角增加删除按钮,点击后按 jobId + frameIdx 删除对应关键帧;删除期间显示小号 loading。图片类素材仍沿用快速删除策略,不弹确认。
影响:web/app/page.tsx、web/components/nodes/index.tsx、docs/source-analysis.html。视频抽帧面板不再依赖当前 active job 来决定删除目标。
问题:视频抽帧面板吸附左侧 / 右侧时顶部仍留出明显空白;这不是实际板块遮挡,而是面板吸附样式里硬编码了 top: 72 和对应的高度预留。关键帧面板也保留了旧 storyboard 顶栏避让逻辑。
改动:新增统一吸附边距常量,视频抽帧面板和关键帧详情面板吸附时都贴近视口边缘,仅保留 8px 安全边距;移除关键帧面板对旧 data-storyboard-dock / data-storyboard-bar 的避让查询。
影响:web/components/nodes/index.tsx、docs/source-analysis.html。后续画布工作面板的吸附语义统一为“贴边”,不是为顶部旧板块预留空间。
问题:输入视频缩略图双击原来只在 Input 节点上方展开一个临时播放器,不能作为无限画布工作台移动、找回或吸附,后续其他板块也无法复用这种交互。
改动:新增 videoFramePanel ReactFlow 节点和 VideoFramePanelNode。双击输入视频缩略图会打开/找回画布内抽帧面板,面板可拖动、右下角缩放,也可一键吸附到左侧、右侧或底部边缘;面板内支持播放、时间轴定位、当前时间抽帧和查看已抽关键帧。
影响:web/app/page.tsx、web/components/nodes/index.tsx、docs/source-analysis.html。原固定全屏 VideoLightbox 不再从 Input 双击路径进入;后续处理板块应复用同类画布工作面板语义。
问题:原始尺寸和 Fit 比例之前是左上角小号单行文字,用户在快速扫缩略图时不够醒目,无法马上感知素材分辨率差异。
改动:HoverPreview 左上角改为两层信息徽章:标题固定为“原始尺寸”,主数字用大号等宽字体显示 宽 × 高,旁边保留 Fit 百分比或 1:1 原寸 状态。
影响:web/components/nodes/hover-preview.tsx、docs/source-analysis.html。定位和 Fit / 1:1 行为不变,只提升尺寸信息可读性。
问题:浏览器原生删除确认会突然出现在页面顶部,和无限画布的操作上下文割裂;图片类素材如果每次删除都确认,也会拖慢快速整理素材的节奏。
改动:输入视频和生成视频任务删除改为画布内确认层,背景轻遮罩并支持点击背景 / Esc 取消;关键帧和元素提取图属于可快速整理的图片素材,点击删除后直接执行。
影响:web/components/nodes/index.tsx、docs/source-analysis.html。视频删除仍走既有删除接口;图片删除仍走原有回调,只调整确认策略。
问题:画布顶部输入视频缩略图只有切换和预览,没有删除入口;用户清理视频队列时只能删关键帧或生成视频任务,不能删除整个输入视频。
改动:新增 DELETE /jobs/{id},前端新增 deleteJob 和 onDeleteJob;Input 缩略图右上角常驻删除按钮,确认后移除该 job、清理 URL 参数,并删除本地 jobs/<id> 目录。
影响:api/main.py、web/lib/api.ts、web/app/page.tsx、web/components/nodes/index.tsx、docs/source-analysis.html。
问题:有些源视频和图片分辨率很大,完全按原尺寸展示会撑爆画布;但统一固定预览大小又会丢失素材真实尺寸感知。
改动:HoverPreview 默认按原比例适应可视区域,角标显示原始分辨率和当前 Fit 百分比;点击钉住后可切换到 1:1,超大素材在预览框内滚动查看局部。
影响:web/components/nodes/hover-preview.tsx。视觉缩略图高度同步放大,图片缩略图的复制 / 删除按钮改为常驻大号 icon。
问题:节点上方缩略图横排内容多时,原生横向滚动条太细且在画布缩放下不容易点中,用户很难拖动。
改动:新增 FloatingThumbnailStrip / ThumbnailScrollRail,在缩略图下方显示明显的大号紫色拖动轨道;轨道支持点击跳转、按住拖动和键盘左右移动,并用 nodrag nopan 避免误触发画布拖拽。
影响:web/components/nodes/index.tsx、web/app/globals.css、docs/source-analysis.html。Input、VisualLab 以及保留的旧视觉节点缩略图条共用同一交互。
问题:镜头拆解、元素改造、生成视频三个卡片在主画布上占同等权重,但它们只是视觉素材状态展示和入口;真正处理都在点击后的工作台/面板中完成。
改动:新增 VisualLabNode,把关键帧、元素 cutout、视频任务缩略图合并到一个“画面工作台 · Visual Lab”卡片里;DAG 从 Input → Keyframe → Storyboard → VideoGen → Compose 简化为 Input → VisualLab → Compose,音频线仍独立。
影响:web/app/page.tsx、web/components/nodes/index.tsx、docs/source-analysis.html。底层数据、接口和旧节点组件暂不删除。
问题:点击或轻微拖动卡片右下角缩放把手时,节点会突然偏移/跳变,影响在无限画布上精调卡片大小。
原因:getComputedStyle(nodeEl).width/height 读到的已经是 ReactFlow 节点坐标下的布局尺寸,旧逻辑又除了一次 zoom,导致拖动起始宽高被放大或缩小;点击时 1px 级 pointermove 也会立刻写入错误宽高。
改动:起始宽高直接使用 computed style,只有鼠标移动量按 zoom 换算;增加 2px 点击死区,单纯点击缩放角不再改写节点尺寸。
影响:web/components/nodes/resize-handle.tsx、docs/source-analysis.html。
问题:用户要的是“鼠标停在卡片缩略图上时,原尺寸图片/视频在该缩略图上方边缘展示,并且仍属于无限画布”;不能贴节点卡片上边缘,也不能放到页面 fixed 层。
改动:HoverPreview 增加缩略图锚点坐标,预览层仍渲染在 ReactFlow 节点 DOM 内,但用缩略图的中心 x 和 top y 定位,预览底边贴缩略图上边缘;Input 视频、镜头拆解关键帧、元素改造 cutout、生成视频缩略图统一走该逻辑。
影响:web/components/nodes/hover-preview.tsx、web/components/nodes/index.tsx、docs/source-analysis.html。
问题:前端只从 URL ?job= 读 job 列表,没有任何本地或后端列表回填,打开 / 不带参数就是空白,之前跑过的 job 看不见。
改动:后端新增 GET /jobs 列表接口(返回 JobSummary:id/url/status/progress/duration/width/height/video_url/frame_count/video_count/thumbnail/error/mtime,按 state.json mtime 倒序,可带 limit)。前端 page.tsx 启动逻辑:URL 有 ?job= 时尊重 URL;没有时自动调 listJobs() 拿全部历史,反转后让最新 job 落在末尾(active)。持久化基于 api/jobs/<id>/state.json 磁盘文件,不依赖浏览器存储,换浏览器/清缓存都不会傻。
影响:api/main.py(JobSummary 类型 + list_jobs endpoint)、web/lib/api.ts(JobSummary + listJobs)、web/app/page.tsx(启动 useEffect)。
问题:本轮参考素材的主体可能是人形骷髅/透明骨骼人,不应被提示词强行替换成普通真人;核心是“用了 SKG 颈部按摩仪后状态变好”。
改动:prompt 允许保留人形骷髅作为视觉隐喻,要求正确佩戴 U 形颈部按摩仪,并通过从僵硬/揉脖子/疲惫到抬头/肩颈舒展/放松来表现状态改善;同时禁止恐怖化、血腥化或夸大医疗治愈。
影响:web/app/page.tsx。
问题:已经有真实 SKG 产品图后,提示词还偏“借鉴原视频”,容易让模型保留竞品或改变产品形态。
改动:生成视频 prompt 明确“上传的 SKG 产品图是唯一产品真源”,首尾帧只控制起止构图、场景和动作,原视频链接只参考节奏和镜头调度;增加产品一致性、产品呈现、禁止非 SKG 产品/竞品包装/随机新增结构等约束。
影响:web/app/page.tsx。
问题:SKG 产品参考不能只依赖从关键帧/元素里复制,用户需要手动上传同一产品的多角度图。
改动:SKG 产品参考 区支持点击上传和拖拽上传图片,一次可传多张,最多保留 6 张。后端新增 POST /jobs/{job_id}/assets 保存产品图资产,并返回 kind: "asset" 的 ImageRef;生成视频时这些资产会作为产品参考传入 Ark。
影响:web/components/storyboard-workbench.tsx、web/lib/api.ts、api/main.py。
问题:首尾帧可以控制视频起止,但还需要单独指定 SKG 产品图,避免模型只模仿原视频动作而没有稳定产品外观。
改动:分镜编排区新增 SKG 产品 槽,和首帧、尾帧并列;生成视频时把该槽作为 product_image 提交。Ark 请求会附加一张 reference_image 产品参考图;如果接口不接受额外参考图,后端自动回退到首尾帧生成。
影响:web/components/storyboard-workbench.tsx、web/app/page.tsx、api/main.py。
问题:赶交付时,顶部横向分镜缩略条占空间,4 图槽也不如“首帧到尾帧”直接;用户希望直接做首尾帧视频生成。
改动:移除 StoryboardBar 的横向分镜缩略图区域,只保留标题栏和展开按钮;StoryboardWorkbench 改成首帧 / 尾帧两个槽,首帧默认当前分镜,尾帧默认下一张已选分镜,也可从剪贴板粘贴指定结束画面。后端 /storyboard/video 支持 first_image/last_image,Ark 请求同时传 first_frame/last_frame,如果接口不接受尾帧字段则自动回退到单首帧。
影响:web/components/storyboard-bar.tsx、web/components/storyboard-workbench.tsx、web/app/page.tsx、web/lib/api.ts、api/main.py。
问题:用户赶交付,希望直接把上传的原视频链接给视频模型参考,而不是只靠单张关键帧。
改动:前端提交生视频时增加 source_ref: { kind: "source_video", url: job.url };Ark 请求体在文本 prompt 和首帧之外追加 video_url 参考视频,用于模仿节奏、镜头运动和动作顺序。如果 Ark 返回 400/422 不接受参考视频字段,后端自动回退到“当前关键帧首帧生成”,保证这次不会直接阻断出片。
影响:web/app/page.tsx、web/lib/api.ts、api/main.py、docs/source-analysis.html。
问题:赶交付时不适合再让 4 图槽决定首帧;如果某个槽里是抠图元素,模型会拿碎元素当第一帧,视频容易不连贯。
改动:“生成视频”按钮改成直接用当前分镜关键帧作为首帧提交,4 图槽和改造目标只作为提示词参考;提示词强调一镜到底、首帧稳定、时间线连续、禁止跳切/换场景/主体变形。后端取关键帧时优先使用未应用的清洗版,否则使用当前 frame 文件。
影响:web/app/page.tsx、web/components/storyboard-workbench.tsx、api/main.py。
问题:用户提供火山方舟 https://ark.cn-beijing.volces.com/api/v3 作为生视频通道;这个通道不是 Poe 的 /videos 形态,而是内容生成异步任务。
改动:后端识别 Ark base 后,提交改为 POST /contents/generations/tasks,请求体使用 content 数组:文本 prompt + 首帧 image_url data URL;轮询改为 GET /contents/generations/tasks/{id},成功后读取 content.video_url 下载 MP4。本机默认 Seedance 模型改为 Ark 可见的 doubao-seedance-2-0-fast-260128。
影响:api/main.py、api/.env.example、docs/source-analysis.html。本机 api/.env 需要把 VIDEO_API_BASE_URL/VIDEO_API_KEY/VIDEO_CREATE_PATHS/VIDEO_STATUS_PATH 指向 Ark。
问题:SKG ezlink 的 OpenAI 兼容 base 可列出部分模型,但常规 /videos 入口返回 404/unsupported;用户确认可用的视频模型在 Poe 通道里。
改动:后端新增 POE_API_BASE_URL/POE_API_KEY 配置,未显式配置 VIDEO_API_BASE_URL 时优先走 Poe;Seedance / Kling / Veo/Voe 业务别名默认映射到 Poe 真实模型 seedance-2-fast、kling-omni、veo-3.1-fast。Poe 提交使用 input_image base64,继续轮询 /videos/{id} 并下载 /videos/{id}/content。
影响:api/main.py、api/.env.example、docs/source-analysis.html。密钥只放本地 api/.env,不进入源码解析页。
问题:虽然当前探测到常见视频入口返回 404/unsupported,但模型层确实有视频模型,不能在前端简单判定“未开通”并禁用。
改动:撤掉分镜编排里的前置禁用;后端允许提交 seedance / kling / veo / voe,并支持通过 VIDEO_CREATE_PATHS 逗号分隔配置多个候选生成入口,逐个尝试。
影响:api/main.py、api/.env.example、web/app/page.tsx、web/components/storyboard-workbench.tsx。
问题:提交生视频失败时,前端把 generateStoryboardVideo 503 {"detail": ...} 原样展示,用户无法快速判断是配置、端点还是 UI 问题。
改动:generateStoryboardVideo 解析后端 JSON 的 detail 后再抛错;后端错误文案区分“模型存在”和“入口不可用”;Video Gen 失败卡把 /videos 404 长错误压缩成一句可读原因。
影响:web/lib/api.ts、web/components/nodes/index.tsx、api/main.py。
问题:Video Gen 节点上方失败/完成任务卡只有整卡点击复制,不够明确;失败任务也无法从界面清掉。
改动:每张视频任务卡左上角增加复制 prompt 按钮,右上角增加删除任务按钮;后端新增 DELETE /jobs/{job_id}/storyboard-videos/{video_id},删除 generated_videos 记录并清理本地任务目录。
影响:web/components/nodes/index.tsx、web/app/page.tsx、web/lib/api.ts、api/main.py。
问题:4 图槽已经粘贴参考图后,用户要直接调用生视频 API,而不是只生成 prompt 或图片任务。
改动:分镜编排明细区增加 Seedance / Kling / Veo 3 模型选择和“调用模型生成视频”按钮;后端新增 /jobs/{job_id}/frames/{idx}/storyboard/video。提交后按 VIDEO_CREATE_PATHS 逐个尝试生成入口,成功后轮询并保存 MP4;失败时保留任务卡和具体入口错误,方便继续排查网关实际路径。VideoGenNode 读取 job.generated_videos 展示排队、生成中、失败和完成视频。
影响:api/main.py、api/.env.example、web/components/storyboard-workbench.tsx、web/components/nodes/index.tsx、web/app/page.tsx、web/lib/api.ts。Sora 不再作为默认模型;真实模型 ID 通过 VIDEO_MODEL_SEEDANCE、VIDEO_MODEL_KLING、VIDEO_MODEL_VEO3 配置,真实视频 API 地址通过 VIDEO_API_BASE_URL/VIDEO_API_KEY 配置。
问题:分镜编排明细区默认占用太多顶部面积,展开后下方画布空间不足。
改动:明细区默认高度降为 320px,并增加底部拖拽手柄,可上推缩到 180px,也可下拉放大查看完整内容。
影响:web/components/storyboard-workbench.tsx。
问题:顶部分镜缩略图条和下方内嵌工作台都带分镜导航,看起来像两个不同板块。
改动:StoryboardBar 成为唯一分镜导航;StoryboardWorkbench 移除自己的标题栏、左侧分镜列表和底部快捷栏,只保留当前分镜的 4 图槽与改造目标明细。
影响:web/components/storyboard-bar.tsx、web/components/storyboard-workbench.tsx、web/app/page.tsx。
问题:元素改造节点等入口仍会打开 fixed inset-0 的全屏 StoryboardWorkbench,用户感觉像跳转页面。
改动:移除 StoryboardWorkbench 的 portal 全屏承载方式,改为渲染在顶部分镜栏下方;所有“打开编排”入口只展开这个内嵌区域。
影响:web/components/storyboard-workbench.tsx、web/components/storyboard-bar.tsx、web/app/page.tsx、web/components/nodes/index.tsx。
问题:关键帧详情钉住在浏览器左侧固定位置时,会遮挡顶部分镜头编排栏展开后的缩略图区域。
改动:给 StoryboardBar 增加稳定 DOM 标记;钉住面板实时读取该区域下边缘,并吸附到其下方。展开 / 折叠分镜头编排时,钉住面板自动让位。
影响:web/components/storyboard-bar.tsx、web/components/nodes/index.tsx。
问题:顶部 StoryboardBar 的“进入编排”和分镜缩略图点击会打开全屏 StoryboardWorkbench,打断当前画布流程。
改动:顶部按钮改为“展开编排”,只下拉展示当前分镜列表;缩略图点击只聚焦该分镜,不再触发全屏跳转。后续已把工作台整体改成内嵌下拉,见上方最新记录。
影响:web/components/storyboard-bar.tsx、web/app/page.tsx。
问题:钉住后仍像自由浮层一样停在画布附近,用户继续缩放画布或调整面板尺寸时容易把它和画布节点混在一起。
改动:钉住后统一吸附到浏览器左侧边缘,脱离 ReactFlow 画布缩放;钉住瞬间把当前可见大小转换成面板真实尺寸,之后只由右下角拖拽或标题栏按钮调整。
影响:web/components/nodes/index.tsx;钉住语义从“原地浮在上层”改为“左侧停靠工作面板”。
问题:只有按钮缩放不够直观;钉住后仍作为画布节点,会继续随 ReactFlow 画布缩放。
改动:增加右下角拖拽缩放手柄;钉住时通过 portal 固定到浏览器上层,脱离 ReactFlow 画布缩放和平移。
影响:web/components/nodes/index.tsx、web/app/page.tsx;未钉住时仍是画布节点,钉住后保持屏幕固定位置。
问题:面板可以拖动后,用户仍可能误拖;切换图片时希望保持固定工作位置。
改动:在标题栏增加钉子按钮。钉住后面板节点禁止拖动,切换关键帧只切换内容不移动位置;取消钉住后可继续拖动。
影响:web/app/page.tsx、web/components/nodes/index.tsx。
问题:用户把关键帧详情面板拖到合适位置后,再点击下一张关键帧会把面板拉回默认位置,造成视觉疲劳。
改动:已打开的面板只切换内容,不移动位置;只有面板不存在、首次打开时才放到默认位置并自动聚焦。
影响:web/app/page.tsx;关闭后重新打开仍会出现在默认位置。
问题:关键帧详情面板作为画布节点后可以随画布缩放,但面板自身没有尺寸控制,用户无法单独放大或缩小它。
改动:在面板标题栏增加 -、百分比重置、+ 控制,支持 75% 到 135% 的面板级缩放。
影响:web/app/page.tsx、web/components/nodes/index.tsx;点击新关键帧仍会找回到默认位置,缩放比例保留。
问题:关键帧详情 / 元素提取面板固定在左侧 drawer,和 ReactFlow 无限画布割裂,也不会跟随画布缩放。
改动:移除主页面隐藏渲染的 Dashboard drawer 承载方式,新增独立 keyframePanel ReactFlow 节点来挂载 FrameLightbox。
影响:web/app/page.tsx、web/components/nodes/index.tsx;点关键帧后面板默认出现在流程左侧空白画布里,不遮挡 Input / Keyframe 主节点;标题栏可拖动,跟随 ReactFlow 平移和缩放。再次点击关键帧缩略图会把面板找回到默认位置,并自动把视野拉到“关键帧 + 面板”。
问题:元素改造节点的 hover 预览虽然已改为节点内显示,但仍比关键帧节点复杂,多了“来源原帧 / 提取元素”两栏和元素名称,信息过载。
改动:改成和镜头拆解关键帧一致的简单预览:只显示来源原帧,底部显示分镜编号和时间。
影响:web/components/nodes/index.tsx;元素改造板块 hover 现在更轻,不干扰当前判断。
问题:上一版把元素预览用 createPortal 挂到 body,DevTools 里会出现额外 fixed 层,交互形态和关键帧节点不一致。
改动:改成节点内 group-hover 预览,不再向 body 插入预览层。后续又简化为只展示来源原帧,见上方最新记录。
影响:web/components/nodes/index.tsx;元素改造板块的 DOM 和交互效果更接近关键帧缩略图。
目的:把产品功能区、源码位置、接口、数据模型、需求描述方式固定下来,减少“描述不准导致改偏”。
影响:新增 docs/source-analysis.html,不接入 Next 应用,不影响工作台运行。
以后描述:可以直接引用本页的功能区名称、节点职责和源码文件名。
问题:元素改造节点上方小图 hover 没有像镜头拆解节点一样显示原图预览,并且首次修复时出现运行时错误。
原因:节点内部 overflow 裁剪了预览;随后 portal 预览里把变量写成了不存在的 aspectRatio。
影响:web/components/nodes/index.tsx。该记录之后又改为节点内预览,见上方最新记录。
问题:Vision 识别可能错,但元素列表像最终结果;点击提取图会跳页面,打断用户思路。
改动:支持元素改名、改英文提示、改位置、删除元素、重复提取、删除单张提取图;提取图不再用链接跳新页。
影响:FrameLightbox、web/lib/api.ts、PATCH /jobs/{job_id}/frames/{idx}/elements/{element_id}。
问题:从 Storyboard 或顶部分镜条进入编排时,没有明确定位到用户正在看的那一帧。
改动:工作台接受 focusedFrame,点击缩略图会打开工作台并聚焦对应分镜。
影响:page.tsx、StoryboardBar、StoryboardWorkbench、StoryboardNode。
问题:SKG 网关 audio 不通时,视觉解析也容易被标记失败。
改动:analyze 主流程强调拆轨和关键帧,声音文案轨独立处理。
影响:api/main.py、page.tsx、节点语义说明。
以后任何改动只要影响产品理解、节点职责、界面行为、数据模型、API、运行方式或用户操作路径,都要同步更新本页的对应章节和“变更记录”。
| 改动类型 | 必须更新本页哪里 | 原因 |
|---|---|---|
| 节点文案 / 节点功能 | 业务管线、节点职责边界、界面区域到源码、变更记录 | 避免用户按旧节点理解描述需求。 |
| 新增 / 修改接口 | 接口地图、数据模型、变更记录 | 避免前后端契约不清。 |
| 新增数据字段 | 数据模型、源码结构地图、变更记录 | 刷新恢复和 state.json 依赖字段一致。 |
| 改交互路径 | 界面区域到源码、需求描述模板、变更记录 | 用户描述“点击哪里”时必须和真实路径一致。 |
| 修 bug | 变更记录;如果暴露新坑,也更新当前已通与阻塞 | 让后续同类问题能快速定位。 |