本地视频复刻工作台：React + TypeScript 前端与 Python + FastAPI 本地服务。主线是参考视频复刻，并面向灰度深度视频与三维白模视频两类输入准备复刻方案；剪辑与本地音频处理服务于复刻结果的对齐和交付。最终 AI 视频生成在外部工具完成。
灰度深度输入与三维白模输入须分别处理，两条完整复刻链路仍需逐项实现及验证，现有深度提取不等于已完成白模复刻。
在仓库根目录安装本地服务依赖：
python3 -m venv .venv
.venv/bin/pip install -r backend/requirements.lockbackend/requirements.lock 包含后端的 multipart 上传与 Pillow 图片探测依赖；请始终通过上述锁定文件安装。
安装前端依赖：
cd frontend
npm ci在第一个终端启动本地服务：
cd backend
../.venv/bin/uvicorn app.main:app --app-dir . --reload --port 8000在第二个终端启动前端：
cd frontend
npm run dev前端开发与预览服务器都会将 /api 请求转发到 127.0.0.1:8000。
项目页按「需求、素材、镜头、工具、交付」组织，不使用无限画布。
- 需求：主题、用途、风格、总时长、画幅和必须保留的要素。
- 素材：独立保存多张图片、多段视频和音频，上传时标注角色、场景、动作、音频或参考；可将原有参考素材和已完成的工具视频产物复制进素材库。
- 镜头：排序、时长、正负提示词与共享素材绑定；每个镜头的节点可引用素材或前面节点的产物。
- 节点：素材引用、视频/音频片段截取、视频首帧/尾帧、图片/视频裁切、保持比例并填边的尺寸调整，以及提示词整理。处理在本地运行。尺寸调整是常规缩放，AI 超分仍在「工具」中使用 Real-ESRGAN。
- 工具：保留已有分镜、语义分析、深度、人物控制、字幕、主体跟踪、插帧、1080P/2K 超分、角色动作方案与离线工作流导出；模型依赖未安装时按原有环境检查提示。
- 交付：检查镜头素材和节点状态，导出需求、镜头表、提示词、所引用素材与有效产物。普通交付包不承诺被任意生成模型直接读取；专用候选工作流从「工具」单独导出。
交付 ZIP 内的 HANDOFF.md 按镜头顺序列出需求、正负提示词、素材角色、步骤输入与参数、可点击的相对文件路径，以及未解决检查项和外部制作步骤。交接说明与同一版本的 JSON 和素材一起生成；准备检查通过不代表目标模型兼容性或成片质量已经验收。
交付检查会提醒需求缺项、镜头计划总时长偏差、未绑定素材及无有效时长的镜头；提醒允许导出，文件缺失或步骤失败/过期仍会阻断。检查项可以定位对应镜头或步骤，定位保留未保存草稿；有草稿时检查结果仍以已保存版本为准。
素材和状态保存在 <data_dir>/project-files/<project-id>/preproduction/，不会替换旧工具使用的当前参考素材。保存使用版本校验；上游节点变化后下游产物过期，需重新运行后交付。所有前置操作无需安装 ComfyUI，也不会自动调用外部分析或生成服务。
基础节点支持最长 300 秒、最长边 4096 像素的输入；单次片段截取最长 120 秒。FFmpeg 处理有执行时限，较大素材超时会返回失败并清理未完成产物，可先截短再处理。
启动服务前请先运行 ffprobe -version。若命令不可用，请安装 FFmpeg 后再启动服务。
每个复刻项目在任一时刻只保存一份参考素材，可以是图片或视频。图片仅接受 JPG/JPEG、PNG、WebP，文件最大 30,000,000 字节；按旋转后的显示尺寸计算，宽和高均为 256～5760 像素，宽高比为 2:5～5:2；不接受动画 WebP。服务端按真实内容校验格式，而非仅信任扩展名或浏览器 MIME。图片透明区域会在本地预处理时使用白色背景合成，并记录实际处理结果。
参考视频仅接受 MP4/MOV，时长为 2～300 秒（5 分钟），文件最大 200,000,000 字节；按旋转后的显示尺寸计算，不设最低分辨率门槛，最高为 UHD 3840×2160。低分辨率视频可上传，但可能影响分析细节。
原始参考素材字节会复制到 <data_dir>/project-files/<project-id>/reference-media/。从旧版项目迁移而来的参考视频仍可从旧 reference-videos/ 目录读取，以保证已有项目可继续打开。projects.json 仅保存参考素材元数据，不记录来源路径。
通过 PUT /api/projects/{project_id}/reference-media 上传一个 file，可首次添加或替换图片、视频。服务端在一次项目写入中提交校验后的素材；替换失败时保留旧素材与现有状态。成功替换会清空当前 localPreprocessing、清除 activeDepthCaptureId，并清理旧参考素材及旧本地预处理产物；历史 depthCaptures 记录仍保留。只要本地预处理、深度捕捉或语义分析处于排队或运行中，即禁止替换。通过 GET /api/projects/{project_id}/reference-media/content 读取当前参考素材内容；旧 GET /api/projects/{project_id}/reference-video/content 仅为旧视频客户端兼容保留。完整参考素材不会发送到外部服务。
参考素材上传成功后不会自动处理。在宽度至少 1024px 的项目页点击“开始本地预处理”：视频依次完成解码、镜头检测、关键帧提取、运动分析和初步可复刻性判断；图片则依次完成图像解码、方向与色彩标准化、分析代理生成和初步可复刻性判断。图片处理会写入去除来源元数据的 normalized.png 与 analysis-proxy.jpg，并在存在实际透明区域时合成白色背景。图片代理的尺寸和白底处理结果来自本地实际处理产物；图片深度素材和可执行工作流生成仍是后续独立能力。
当前 FFmpeg 构建必须包含 scdet、scale、metadata、drawtext 和 tile 滤镜。可以运行 ffmpeg -filters 检查。
macOS 使用 Homebrew 时，可安装 brew install ffmpeg-full。它是独立安装的完整构建；在启动后端或运行后端测试的同一终端中，先执行 export PATH="$(brew --prefix ffmpeg-full)/bin:$PATH"，再检查 ffmpeg -version、ffprobe -version 和上述滤镜。
版本化视频产物保存在 <data_dir>/project-files/<project-id>/local-preprocessing/<preprocessing-id>/。视频语义分析只发送 contact-sheet.jpg 和 analysis-proxy.json；图片只发送去元数据的 analysis-proxy.jpg 与基础尺寸信息。完整参考素材、独立关键帧和本地路径不会进入分析代理。
本地阶段只判断多镜头和运动强度。显示“待语义分析确认”不代表已经处于可复刻范围；主要主体数量和复杂交互由语义分析确认。
04c 已支持图片和视频的统一、可恢复语义分析。当前设置目录包含阿里云百炼 qwen3.7-flash、本地 OpenAI 兼容服务（回环地址、自填非空模型）、OpenAI gpt-5.6-luna、火山方舟豆包 doubao-seed-2-0-lite-260428、Google Gemini gemini-2.5-flash、xAI Grok grok-4.6、Anthropic Claude claude-sonnet-5 与 ChatAnywhere gpt-4o-mini。六家云端与百炼必须配置 API Key；本地服务的 Key 可选，Base URL 仅允许回环主机。
目录中的“未验证/可用/验证失败”是当前本机配置的连接测试结果，不是供应商可用性的承诺。连接测试只发送内置的 16×16 PNG 和完整结构化分析提示；它不会发送参考素材。目录升级会使已退役模型的本地配置与验证状态失效；保留的系统钥匙串密钥须随当前目录重新保存后再验证。豆包图片与结构化输出组合基于方舟 Responses 兼容协议推断，在真实密钥的本地连接测试成功前保持“未验证”。模拟契约测试不能替代真实冒烟。
用户在宽度至少 1024px 的项目页先查看接收方、将发送的代理内容和明确不发送内容，再确认提交。凭据仅由本地服务的系统安全存储管理，前端、项目数据和日志不保存或回显密钥。任务会保存检查点以便重新打开后恢复状态；失败保留本地预处理结果，且不会自动切换供应商或模型。窄屏仅可查看配置、任务和结果。
可用本地服务的同一路径执行脱敏连接冒烟：PYTHONPATH=backend .venv/bin/python backend/scripts/smoke_analysis_provider.py --provider openai。它只调用本机 /api/analysis-providers/<id>/test-connection，不会直接读取安全存储、打印凭据、请求体或供应商原始响应；未配置或失败时非零退出。
语义分析完成后，“准备工具”中的“提示词与工作流准备”提供按需生成中英文正负提示词、编辑和复制、模板参数调整与复刻包下载。点击“生成提示词”只向原分析服务发送结构化分析，不重新发送参考图片或视频；已有提示词不会因失败而丢失。素材、分析或有效深度素材改变后，旧方案标记过期，保留编辑内容，但需重新生成提示词后再导出。
当前提供 Wan2.2 14B I2V 与 Wan2.2 Fun Control 深度候选模板。模板尚未在本机真实 Queue 验证，不能视为已验证的可执行工作流。默认生成 81 帧、16 FPS（约 5.06 秒），参考视频可更长；可编辑尺寸、帧数、帧率和种子。Fun Control 只使用当前通过质量检查或已确认复核的深度结果；控制片段按所选尺寸与帧率转换，长片取开头，短片保持末帧补足长度。
无需安装 ComfyUI 即可编辑方案与下载 ZIP。复刻包包含 workflow-api.json（ComfyUI API 格式）、中英文提示词、参数、结构化分析、输入首帧、选用的深度控制片段和带模板来源的清单，不包含生成模型、凭据或完整参考视频。项目方案、输入快照和生成记录独立保存在 <data_dir>/project-files/<project-id>/reproduction/。
应用当前不提供最终生成入口，两个历史生成提交接口返回 410 final_generation_disabled。已有记录和素材保留，离线工作流可继续导出；本地 ComfyUI 不作为前置工作台的依赖。候选模板的真实推理质量仍需在目标环境自行验证。
先在 frontend/ 中构建，再启动预览服务器：
cd frontend
npm run build
npm run preview以下命令均从仓库根目录运行：
PYTHONPATH=backend .venv/bin/pytest -q backend/tests
npm --prefix frontend test
node frontend/scripts/verify-color-contrast.mjs
npm --prefix frontend run build深度素材准备独立于生成环境：完成深度提取后，可在「深度动作捕捉」下载完整深度素材包（GET /api/projects/{project_id}/depth-captures/{capture_id}/package）。包内保留提取产物的完整灰度控制视频、彩色预览、质量报告、模型版本与执行记录，不要求语义提示词或 ComfyUI，不按生成模板截短、补帧。质量失败或待复核的素材仍可下载用于检查，下载不会解除生成质量门禁。此包不同于按输出参数转换的候选工作流复刻包。
上传普通参考视频后即可提取整段灰度深度视频，无需先完成预处理、语义分析或可复刻性判断，也不要求主体是单人。使用已安装的 Video Depth Anything Small，相对深度显示为近白远黑。480P / 720P 对应输出短边 480 / 720 像素，保持画面比例并使用偶数尺寸；低分辨率原片放大不会增加原始细节。两档使用不同推理配置，推理尺寸和最终编码尺寸分别记录，输出像素数不等于模型原生精度。
默认并排播放原片和灰度视频，可从任意一侧播放、暂停或定位。点击「下载灰度深度视频」获取独立 MP4（GET /api/projects/{project_id}/depth-captures/{capture_id}/video?download=true）；不带下载参数的同一路径支持 Range 预览。完整 ZIP 和原有彩色预览继续保留。旧任务只显示其实际尺寸，不自动标成新的 480P 档位。
提取按真实时间戳规范化后分段处理，整段使用统一深度范围，避免把长片全部保存在内存中。保留视频时间线，不按后续生成模型限制截短；输出实际帧率、时长与质量报告随结果保存。计算耗时取决于设备和视频长度。深度估计不等于精确三维重建，也不能保证与 LibTV 使用的未知模型效果相同。
当前视频完成本地预处理后，「逐镜头素材准备」按已检测切点显示从 0 秒到视频末尾的完整时间线，为每镜头提取代表帧，可定位原视频、编辑备注与中英文正负提示词。多镜头不受单镜头生成模板门禁限制；未填写的提示词保持为空，不自动复制整片分析。
已选择语义分析服务时，可显式点击「分析当前镜头并生成提示词」。仅发送该镜头内四个采样位置对应的帧拼图及时间信息，再通过纯文本请求生成提示词；可能产生分析费用，不上传原视频，也不自动批量调用。变帧率视频按真实帧时间戳取样，短镜头允许重复同一有效帧；四帧分析不能代替逐帧动作捕捉。分析失败保留旧草稿，可重试。
独立准备包包含 timeline.json、每镜头备注和提示词、代表帧、可验证的当前深度产物及溯源清单。无需 ComfyUI、生成模型或已完成语义分析即可下载。提示词全部四字段非空才计为该镜头提示词准备完成；人物控制素材需单独提取，下载或提示词完成不会改变其状态。素材或预处理更换会重置当前准备视图，保存及分析使用来源 ID 和版本校验，拒绝迟到覆盖。
逐镜头可点击「提取人物姿态与遮罩」，在本机 CPU 上生成 33 点身体骨架、黑白人体遮罩、原画叠加预览及逐帧关键点。参考片段统一为 8 FPS、长边不超过 640 像素；预览与原视频按镜头时间同步。任务持久化并共用本地计算队列，失败可重试，重启中断会明确显示失败。无人物判为失败，缺检、多人、低置信度或退化遮罩判为待复核；质量通过仍需目视检查。产物与质量报告会进入独立准备包。当前范围是单人人体，不包含任意物体分割，也不宣称兼容 OpenPose。
人物提取使用独立的 backend/person_worker/.venv 和 backend/person_worker/models/pose_landmarker_full.task，不会占用深度模型目录。该模型只负责姿态和遮罩，不是视频生成模型；提取与导出均无需 ComfyUI。独立命令与依赖记录见 人物 worker 说明。
项目页「视频超分」可对当前参考视频执行 Real-ESRGAN 1080P / 2K（1440P）增强，独立于语义分析、深度捕捉与 ComfyUI。支持排队进度、失败重试、结果预览和 MP4 下载，保留完整时长与首条音轨。生成后的视频也可上传为新项目参考素材处理。
需先安装本地 ncnn Vulkan 可执行程序与 realesrgan-x4plus 权重；缺少环境时页面会显示原因并禁用开始。保持画面比例，以短边1080/1440确定输出尺寸（偶数像素）；模型原生4×推理后调整为目标尺寸，低分辨率输入超过4倍部分采用额外缩放；首版支持SDR，最高8K，变帧率按平均帧率规范化，不执行补帧。安装、环境变量与验证说明见 超分引擎说明。
“准备工具”保留以下功能：
- 视频工具：当前参考视频及已保存的生成/超分结果可多选；支持自适应分镜与切点编辑、字幕提取、首帧点选主体跟踪、RIFE 30/60 FPS 补帧、1080P/2K 超分；任务可取消、失败重试；结果支持同步对比与下载。
- 自动处理流程：选择一份素材和至少两个步骤，按分镜、字幕、主体跟踪、补帧、超分的顺序自动执行所选步骤。分析步骤使用输入快照；补帧输出自动传入超分。每步独立保存状态和产物，取消会停止后续步骤，失败或服务中断后可保留已完成步骤并继续处理。完成的视频可再次作为工具素材使用。
- 分镜联动：在「逐镜头前置准备」刷新分镜结果，选择当前参考视频的检测结果并应用，或恢复本地预处理切点。时间范围完全相同的镜头保留已保存的备注和提示词；变化的镜头重新准备。时间线变化后人物控制素材需重新提取，旧运行不会绑定到新时间线。未保存草稿须先保存；应用切点不会自动发送云端分析。
- 角色动画与动作迁移：独立上传角色图，使用当前参考视频驱动 Wan Animate Move 模式。无需语义分析或已安装 ComfyUI 即可保存方案、导出离线包。最终生成在外部 ComfyUI 中执行，应用不提交生成。
当前机器没有 ComfyUI，角色生成尚未完成真实模型验收。官方候选模板附带固定来源 commit、SHA-256 和许可证。导出 workflow-api.json 为应用展开的 Move 图，official-template.json 为原始来源快照（含其他分支），不能将原始快照的背景替换分支误认为当前默认模式。
驱动视频按所选 FPS 重采样，截取开头 frames / fps 秒；不足时保持末帧。角色图片背景参与生成，不能承诺逐像素保持。DW 预处理权重缓存无法通过通用 ComfyUI HTTP 接口自动核验，在外部执行前需确认目标环境已缓存 yolox_l.onnx 和 dw-ll_ucoco_384_bs5.torchscript.pt，不能以节点存在代替模型准备。
本地工具安装、配置与当前验证范围见 视频工具说明。分镜工具已通过真实样例；SAM 2、whisper、RIFE 推理需要分别安装对应引擎和模型。无依赖时按钮会明确显示未就绪，不会生成虚假结果。