长动画交付流水线
 
 
 
 
 
Go to file
mula.liu 7fcfd2932b 标签统一收尾:调度中心页头的队列计数与总控台的镜头状态计数不再借 Chip 的 31px 胶囊皮肤,改成和旁边标签同档的 TagGroup,只读回显全部归到标签族 2026-11-02 10:50:56 +08:00
backend 前端统一收尾:图文手册从 public/help.html 搬成站内 React+Tailwind 页面 /help,SPA 深链回落与未知接口 404 拆成纯函数补自检,新增 ErrorBoundary 兜住分包加载失败 2026-11-01 19:25:47 +08:00
docs UI 规范:删掉最后一处「全局 :has 兜底」的过时说法,与 §3 的 React 现状保持一致 2026-11-01 19:48:52 +08:00
frontend 标签统一收尾:调度中心页头的队列计数与总控台的镜头状态计数不再借 Chip 的 31px 胶囊皮肤,改成和旁边标签同档的 TagGroup,只读回显全部归到标签族 2026-11-02 10:50:56 +08:00
reports v 0.1.0 2026-11-01 16:18:07 +08:00
scripts 前端统一收尾:图文手册从 public/help.html 搬成站内 React+Tailwind 页面 /help,SPA 深链回落与未知接口 404 拆成纯函数补自检,新增 ErrorBoundary 兜住分包加载失败 2026-11-01 19:25:47 +08:00
.env.example v 0.1.0 2026-11-01 16:18:07 +08:00
.gitignore 修复 media/ 忽略规则误伤前端组件:补回 components/media 六个组件、部署体检增加前端源码完整性计数 2026-11-01 18:59:46 +08:00
README.md 前端统一收尾:图文手册从 public/help.html 搬成站内 React+Tailwind 页面 /help,SPA 深链回落与未知接口 404 拆成纯函数补自检,新增 ErrorBoundary 兜住分包加载失败 2026-11-01 19:25:47 +08:00
docker-compose.yml v 0.1.0 2026-11-01 16:18:07 +08:00

README.md

Nex Animation Studio · 长视频编导平台

面向 AI 长视频创作的本地工作台:人物与声音资产库 → 分镜与脚本管理 → 视频模型调度中心 → 长视频合成引擎, 底层由统一任务编排(队列 / 重试 / 断点续跑 / 并发限流)与项目数据库支撑,完整实现业务流程图的 12 个节点。

📖 图文使用手册 —— 已搬进站内:启动后访问 http://127.0.0.1:5173/help,或点工作台顶栏的「手册」

手册包含模型管理中心、资产独立生成与镜头关联、分镜检查器、调度、质检、时间线和导出流程的实际截图。

🧹 动代码或打部署包之前先读 工程规范与部署数据边界: 目录职责、scripts/ 准入规则、测试规范、改动后的最低验收三连,以及服务器上「什么该搬、什么不该搬」。

┌──────────────────────── Browser (React + Vite + Tailwind CSS) ─────────────────────────┐
│ 项目总览 │ 资产库 │ 分镜与脚本 │ 调度中心 │ 质检与审核 │ 时间线合成 │ 导出与成本          │
└─────────────────────────────────────┬───────────────────────────────────────────────────┘
                                      │ REST / JSON + multipart  (vite proxy 或 nginx)
┌─────────────────────────────────────▼───────────────────────────────────────────────────┐
│ FastAPI (backend/app/api)  system · library · storyboard · pipeline · delivery · agent   │
│  services: importer prompt preflight dispatch execution quality timeline compose agent  │
│            costing ffmpeg audio storage events status daemon                            │
│  providers: mock · http_generic · macos_say · comfyui + provider_models 模型注册表          │
└───────┬───────────────────────────────────────────────┬─────────────────────────────────┘
        │ TASK_EXECUTOR=celery                          │ TASK_EXECUTOR=inline(单机自检)
┌───────▼───────────────┐                    ┌──────────▼───────────────┐
│ Redis + Celery        │                    │ 进程内线程池 +           │
│ worker(generate/audio/│                    │ 守护线程(周期派发 +     │
│ qc/compose/io)+ beat │                    │ 断点续跑)               │
└───────┬───────────────┘                    └──────────┬───────────────┘
        └───────────────► FFmpeg / ffprobe(转场、混音、响度、质检) ─◄──┘
                             │  Postgres / SQLite  +  MEDIA_ROOT 媒体库(/media 直出)

仓库目录与脚本职责

backend/    FastAPI 应用:app/api 路由 · app/services 编排 · app/providers 模型适配 · tests 回归用例
frontend/   React 19 + Vite + Tailwind CSS v4 工作台(图文手册 = src/pages/Help.tsx,截图在 public/help/)
scripts/    只放启动 / 部署 / 运维脚本(下表);一次性验证探针不进这个目录
docs/       UI 规范、工程规范、H3 性能诊断记录
media/      产物库(MEDIA_ROOT)    models/ whisper 词级对齐权重    reports/ 阶段验收证据
.local/     开发态日志与 pid        .trash/ 删除暂存(两者都不进 git,删掉就没了)
.env        本机配置与密钥(不进部署包)    nex_animation.db  开发库

frontend/src/ 分层(依赖只允许自上而下,页面之间不互相 import):

api/        唯一的 fetch 出口:信封自动拆包、detail 统一成 Error、401 跳登录
app/        应用外壳:router.tsx 路由表(唯一一份)· layout/ 顶栏侧栏鉴权闸门
pages/      页面与项目页签,一屏一文件;页面私有的类名常量/子组件留在文件底部
components/ 无业务语义的原语,三个目录按职责分:
            ui/ 版式与控件(Button/Field/Ctlbar/Table/Modal/Drawer/Tag…)
            forms/ 选择器族(Select/MultiSelect/SecretInput + toOptions)
            media/ 带全局状态的媒体件(MediaThumb/AudioPlay/MediaLightbox/WorkflowBar…)
stores/     zustand 切片:auth · theme · notice · project · models · system · audio · preview
hooks/      use-async / use-polling / use-auto-refresh / use-outside-click / use-local-storage
lib/        纯函数与适配器:cn · format · media · pipeline · recorder · versions
styles/     tokens.css(设计令牌 = 唯一尺子来源)· base.css(元素级基线)

新增页面只做三件事:在 pages/ 落文件 → 在 app/router.tsx 注册 → 复用 components/* 原语, 缺原语就补进 components/(不要复制粘贴样式)。加一类新母版/新页签同理:改表不改逻辑(见 docs/工程规范.md §1.1)。

脚本 干什么 在哪儿跑
scripts/dev.sh 开发态前后端两个进程(后端 8000 + Vite 5173),缺 .env / .venv / node_modules 自己补 开发机
scripts/server.sh 服务形态全生命周期:install build start stop restart status verify logs systemd 服务器
scripts/deploy.sh 打部署包(白名单 + 体检),或直接 rsync 上服务器并自动安装、重启 开发机
scripts/seed.py 迁移「模型配置 + 加密主密钥 + 管理员」:export 导出、install 幂等落地 两端
scripts/e2e_selfcheck.py 图2 全 12 节点端到端自检(真实 HTTP + ffprobe 实测产物) 两端
scripts/evidence_prune.py 清理 reports/ 下过期的验收证据目录 开发机

1. 图1 模块规划 → 代码实现

模块 后端服务 / 接口 前端页面 关键能力
① 人物与声音资产库 app/api/platform.py、app/api/library.py、services/storage.py、services/audio.py pages/AssetLibrary.tsx、pages/project/Library.tsx 平台级人物 / 场景 / 声线母版创建时始终全局,不绑定项目;项目目标只在「引入项目」时选择。母版可上传、AI 生成、编辑,项目资产可反向「上架平台」。图片支持大图预览,每个媒体可单独删除,不必删除母版。声线在创建时只录入基础设定,生成试听时再选真实模型;项目内继续维护定妆图/三视图/服装/表情、场景图、声线与项目素材;每次上传生成新版本,删除留痕
② 分镜与脚本管理 app/api/storyboard.py、services/importer.py、services/prompt.py、services/preflight.py pages/project/Storyboard.tsx(分镜工作台) Markdown/CSV/TSV/JSON/纯文本脚本导入 + 图片按镜号自动匹配关键帧(支持 zip);shots/preview 与 dry_run 先预览后落库;镜头增删改/排序、人物场景绑定、提示词组装与版本留痕、首尾帧/参考图上传;shots/board 轻量看板(逐镜预检)、shots/bulk 批量复制/移动/改参/删除、shots/export 反向导出 md/csv/json
③ 视频模型调度中心 app/api/pipeline.py、services/dispatch.py、services/capacity.py、services/execution.py、services/daemon.py、app/providers/* pages/project/Dispatch.tsx 任务清单(预检驱动,可解释「为什么跳过/阻塞」)→ 入队 → 按 provider/model 并发槽位与 RPM 限流派发(一个模型一行,视频与 TTS 各自的限额互不串台) → 指数退避重试 → 中断任务断点续跑;模型注册表在线启停/设默认/调并发/调限流/注入故障演练
④ 长视频合成引擎 app/api/delivery.py、services/timeline.py、services/compose.py、services/ffmpeg.py、services/quality.py pages/project/Review.tsx、Timeline.tsx、Delivery.tsx 自动质检 7 项打分;人工审核合格/驳回重做;时间线(片段裁剪/转场/排序/字幕/配音/BGM/响度归一化);交付预检报告;4 档出片预设 + 校验和留档;成本台账与生成记录可复现
底层:任务编排 + 项目数据库 app/models/*、app/db.py、services/events.py、services/status.py、services/costing.py pages/Dashboard.tsx、pages/ProjectDetail.tsx、pages/project/Overview.tsx 12 张表(项目/人物/场景/声线/素材/素材版本/镜头/任务/审核/时间线/片段/字幕/音轨/导出/成本/生成记录/事件);任务幂等键、心跳、错误历史、检查点;全流程事件流与流程进度视图

2. 图2 业务流程 → 状态机与接口

流程节点定义在 backend/app/services/status.py:PIPELINE_STAGES,每个项目/镜头/任务的真实状态收敛成 GET /api/projects/{id} 的 workflow[](pending/active/done/failed),前端 components/media/WorkflowBar.tsx 直接渲染。

# 节点 主要接口 镜头状态流转
1 创建视频项目(可顺带勾选资源库母版 platform_assets:[{owner_type,asset_id}]) POST /api/projects(返回 imported_assets/import_failures)、`GET /api/platform/assets?owner_type=human scene
2 导入分镜图片与脚本 POST /projects/{id}/shots/preview、POST /projects/{id}/import(dry_run/replace/keep_existing/images[]/archive);看板与批量:GET /projects/{id}/shots/board、POST /projects/{id}/shots/bulk、GET /projects/{id}/shots/export 新建镜头 → ready
3 绑定人物/场景与声音资产 POST /projects/{id}/shots/{sid}/bindings、/assets、/characters/{cid}/assets binding → ready
4 生成分镜任务清单 GET /projects/{id}/tasklist、POST /projects/{id}/tasks ready → planned
5 检查素材与参数 GET /projects/{id}/preflight(逐镜头 issues[{code,field,message,severity}]) 阻塞项阻止入队(可 allow_unready)
6 任务队列调度 POST /projects/{id}/dispatch(limit/drain/timeout)、GET /projects/{id}/queue planned → queued → running
7 调用视频模型 任务执行 app/jobs/tasks.py → providers/* running(进度/心跳/尝试次数)
8 下载并保存视频 同上(产物落 MEDIA_ROOT 并注册资产) running → generated
9 质量检查 GET /projects/{id}/qc、POST /projects/{id}/shots/{sid}/qc?drain= generated → qc_passed(失败 → generated + quality_check_failed)
10 人工审核 GET /projects/{id}/reviews、POST .../approve、POST .../reject qc_passed → approved / rejected
11 调整提示词重新生成(驳回回路) reject 携带 prompt/negative_prompt/regenerate → 自动重排任务;POST /projects/{id}/voiceover 补配音 rejected → planned → running
12 时间线合成 + 配音/字幕/混音 → 导出 POST /projects/{id}/timeline、/timeline/segments/{id}、/timeline/reorder、/timeline/subtitles、/timeline/audio、/timeline/settings、GET /timeline/report、POST /compose、GET /exports、GET /api/exports/{id}/download 项目 composing → delivered

失败与恢复:POST /api/tasks/{id}/retry|cancel、POST /projects/{id}/tasks/retry-failed、/tasks/cancel-active、 /projects/{id}/resume(running 超过 STALE_RUNNING_SECONDS 视为中断并带上 checkpoint 续跑)。

2.1 项目主页 LLM 总控台(pages/project/Overview.tsx)

项目主页顶部提供自然语言总控台:使用系统注册并启用的默认真实 LLM 盘点镜头、关键帧、模型能力和 当前阻塞,先落库为可审阅的执行计划,再由用户确认执行。LLM 不直接操作媒体或数据库,后端只接受 resume / rewrite_shots / generate_keyframes / generate_shots / quality_check / approve_passed / build_timeline / compose 八个白名单动作。主题或剧情变化时,rewrite_shots 会整组替换分镜、 按引用补齐缺失场景/人物、作废旧镜头产物并重建后续时间线;创建/删除项目、任意改资产文件或调用 任意 URL 仍不可用。

端点 用途
POST /api/projects/{id}/agent/plan 将自然语言目标转换为结构化计划并持久化
GET /api/projects/{id}/agent/runs 查看当前与历史调度记录
GET /api/projects/{id}/agent/runs/{run_id} 查询分步执行状态与结果
POST /api/projects/{id}/agent/runs/{run_id}/execute 用户确认后执行,默认异步轮询
POST /api/projects/{id}/agent/runs/{run_id}/cancel 请求在当前步骤结束后取消

审核门禁默认开启:未勾选「质检合格后允许 AI 代审」时,计划只能推进到人工审核前;只有用户显式授权后, approve_passed 才会以 kind=agent 单独留痕,绝不冒充人工审核。调度器拒绝 Mock LLM 和 Mock 媒体模型, 不会在真实模型缺失时静默回退。已完成且产物有效的步骤会跳过,失败步骤可从断点继续;实现见 backend/app/services/agent.py,契约测试见 backend/tests/test_agent_orchestrator.py。

2.2 分镜工作台(pages/project/Storyboard.tsx)

分镜是几十上百镜的大页面,所以列表不走返回全字段的 GET /shots,而是按用途拆成三层:

端点 用途 关键字段
GET /projects/{id}/shots/board 看板/分镜表首屏,一次请求带齐指标与逐镜预检 每镜 ready + issues[{code,field,message,severity}]、缩略图地址、QC 分、绑定摘要;不含 prompt 正文、版本、素材明细
GET /projects/{id}/shots/{sid} 选中某镜时按需拉全量详情喂给检查器 prompt / 素材 / QC 明细 / 配音 / effective_*
GET /projects/{id}/shots/export?fmt=md|csv|json 导出给编剧或外部工具 md 与导入格式双向可逆,导出文件可直接再导回
POST /projects/{id}/assets/generate 分镜关键帧 / 尾帧 / 参考图走独立图像模型 target_type=shot、当前镜头提示词、人物/场景/镜头参考图;生成结果覆盖同一关键帧槽位的新版本

批量操作统一走 POST /projects/{id}/shots/bulk(action=duplicate|delete|move|patch):一次请求一个事务, 避免 N 个镜头触发 N 次全项目预检。duplicate 插在来源之后并重排镜号、不继承产物;move 支持 index(绝对落点)与 delta(相对位移);patch 拒绝批量改镜号(镜号需唯一)并在改到摄影参数后重算提示词。 写接口侧的约束也一并收紧:枚举字段与 duration>0 校验不过一律 400(原先静默写脏值)、镜号冲突返回 400 而非 500、 seed 允许显式清空、删除镜头后镜号自动续排。回归见 backend/tests/test_storyboard_workbench.py。

页面交互:网格 / 分镜表双视图(选择记在 localStorage)、搜索 + 状态/模式/排序筛选 + 仅看阻塞/缺关键帧、 HTML5 拖拽改镜序、Shift 范围勾选、批量复制/移到最前/统一改参数/删除。选中镜头后打开独立右侧宽抽屉, 四页签(镜头 / 资产 / 提示词 / 产物)不再挤压分镜看板;关键帧、尾帧、参考图、视频和配音均可在 图片 / 视频 / 音频统一灯箱中预览,并可直接打开原文件。资产页签内置「AI 生成关键帧」, 显示并选择当前真实图像模型,自动带入场景图、人物定妆图和镜头参考图,生成后直接成为 i2v 首帧。 检查器带脏标记与 ⌘S 保存,快捷键 J/K 切镜、X 勾选、Esc 关闭。 卡片上的「生成」「审核」带 ?shot= 深链到调度中心 / 审核页并自动选中该镜。

3. 启动方式

3.1 单机模式(无需 Redis/Postgres,适合开发、演示、自检)

一条命令搞定前后端:

./scripts/dev.sh                 # 启动前后端(缺 .env / .venv / node_modules 会自己补)
./scripts/dev.sh status          # 端口 / 健康 / 当前默认模型 / ComfyUI 连通性
./scripts/dev.sh logs            # 同时跟踪前后端日志(logs backend|frontend 看单个)
./scripts/dev.sh stop            # 停止(按进程组回收,不留孤儿 vite / uvicorn worker)
./scripts/dev.sh restart --reload

选项:--backend-only --frontend-only --reload --no-install --backend-port N --frontend-port N --host ADDR(换端口时 Vite 代理目标自动跟随)。 日志在 .local/logs/,pid 在 .local/run/。

局域网访问(手机 / 同事的电脑打开同一套平台)

dev.sh 默认监听 0.0.0.0,启动时会把本机与局域网地址一起打出来:

界面     http://127.0.0.1:5173     (Vite → 代理 /api、/media 到后端)
接口     http://127.0.0.1:8000/docs
局域网   http://192.168.2.19:5173   (同网段设备可直接打开)
局域网   http://192.168.2.19:8000/docs
  • 同一网段的设备直接开 http://<本机IP>:5173 即可:/api、/media 都由 Vite 代理回后端, 接口返回的又都是相对路径,不会出现「图片只在这台机器上能看」。
  • 只想给本机用:./scripts/dev.sh --host 127.0.0.1(NEX_HOST 环境变量同样生效)。
  • mDNS 机器名(http://<名>.local:5173)已在 frontend/vite.config.ts 的 server.allowedHosts: ['.local'] 里放行;换成自定义域名仍需显式加白名单, 否则 Vite 会返回 403 Blocked request. This host (...) is not allowed.。
  • 🔒 鉴权默认开启(AUTH_ENABLED=true):首次启动自动播种管理员 admin / 初始口令 admin1234 (app/services/auth.py:bootstrap,登录后应立即改密),会话走 nex_session Cookie, 脚本也可以用 Authorization: Bearer <token>。模型配置与账号管理(/api/providers、/api/users) 只有管理员能写,观摩/制作角色可看可拍但不能改全平台配置。 本地调试嫌麻烦可在 .env 设 AUTH_ENABLED=false 关掉,但别把关掉鉴权的实例裸露在公网上。

脚本干了四件手工启动容易漏掉的事(都是踩过的坑): ① 统一从仓库根 --app-dir backend 启动,保证根目录 .env 一定被读到 (.env 被静默忽略时平台照旧跑 mock 且不报错); ② 用独立会话拉起进程,脚本/终端退出不会把服务一起带走; ③ Vite 加 --strictPort,端口冲突直接报错而不是悄悄换端口把前端代理和 e2e 自检打空; ④ 端口被外部进程占用时报出具体 pid,而不是卡在健康检查超时。

手工启动(想单独控制某个进程时):

cp .env.example .env
# 后端(SQLite + 进程内线程池 + 内置守护调度器);.env 已配好 SQLite/inline,可零环境变量启动
../.venv/bin/pip install -r backend/requirements.txt
../.venv/bin/uvicorn app.main:app --app-dir backend --reload --port 8000
# 前端(另一个终端)
cd frontend && npm install && npm run dev      # http://localhost:5173

TASK_EXECUTOR=inline 时 POST /dispatch、/compose 会同步排空队列并直接返回结果,页面无需等待 worker; /health 的 executor、daemon.running 可确认当前后端。

前端开发态代理:frontend/vite.config.ts 必须把 /api、/health、/media、/docs、 /openapi.json 五条路径一起代理到后端。少代理任意一条,Vite 的 SPA 回退会用 index.html 应答,前端拿到 200 却没有字段,对应面板就静默失效(侧边栏曾因此整块显示 「任务执行 —/ffmpeg 缺失/字幕烧录 滤镜缺失/调度守护 未运行」)。src/stores/system.ts 现在会 校验 typeof health.status === 'string',一旦代理缺失直接抛出可读错误而不是假装健康。

后端换地址/换端口:NEX_BACKEND=http://127.0.0.1:8010 npm run dev,无需改代码。 SQLite 路径的父目录由 app/db.py 自动创建,DATABASE_URL='sqlite://////tmp/nex_ui/ui.db' 可直接使用(注意 SQLite URL 是 6 个斜杠:3 个协议分隔 + 绝对路径根)。

3.2 生产模式(Postgres + Redis + Celery worker/beat)

cp .env.example .env        # 修改数据库/Redis 口令
docker compose up --build   # web:8080  api:8000  worker  beat  db  redis

或本机进程:celery -A app.worker.celery_app worker -Q generate,audio,qc,compose,io,default -c 2 与 celery -A app.worker.celery_app beat(beat 负责周期派发与断点续跑)。

3.3 冒烟自检

/health 与 /api/auth/state 免登录(监控探针和登录页要用),其余 /api/* 在默认鉴权下需要先拿会话:

curl -s localhost:8000/health | jq '.executor,.ffmpeg_capabilities,.auth_enabled,.frontend'
curl -s localhost:8000/api/auth/state | jq '.auth_enabled,.login_hint'   # 未登录也返回 200
# 读业务接口前先登录拿 Cookie(账号口令就是首启播种的那一对):
curl -s -c /tmp/nex.jar -H 'content-type: application/json' \
  -d '{"username":"admin","password":"admin1234"}' localhost:8000/api/auth/login > /dev/null
curl -s -b /tmp/nex.jar localhost:8000/api/meta | jq '.presets,.options.transition'

AUTH_ENABLED=false 时可以省掉登录那两步直接 curl。 端到端业务自检(不只是接口活着)见 §6.2。

3.4 服务器部署(一台机器一个端口)

开发态是「Vite 5173 + 后端 8000」两个进程;服务器上不需要 Vite—— SERVE_FRONTEND=on 让同一个进程既出 API 又发 frontend/dist, React Router 的 history 回退已经处理好(地址栏直接刷 /projects/3 不会 404), 反向代理只需转发一处,/api、/media、/docs 与页面同源。 SERVE_FRONTEND 默认 off,所以开发与测试行为完全不变。

# ---- 开发机:打包(内容白名单 + 体检,体检不过直接报错不产出包)----
./scripts/deploy.sh --check                       # 只看会带上什么、排掉什么
./scripts/deploy.sh                               # → .local/deploy/nex_animation-<时间戳>.tar.gz
./scripts/deploy.sh --host deploy@10.0.0.8 \
    --path /opt/nex_animation                     # 上传 + 远端 install + restart + status

# ---- 服务器:落地 ----
tar -xzf nex_animation-*.tar.gz && cd nex_animation
./scripts/server.sh install      # venv + 依赖 + npm build + 听写模型 + 建表灌种子数据
./scripts/server.sh start        # 单进程 uvicorn,默认 :8000
./scripts/server.sh verify       # 图2 全 12 节点真实 HTTP + ffprobe 自检
./scripts/server.sh status       # 端口 / 健康 / 默认模型 / ComfyUI 连通性 / 数据边界
sudo ./scripts/server.sh systemd > /etc/systemd/system/nex-animation.service \
  && sudo systemctl daemon-reload && sudo systemctl enable --now nex-animation

install 首次生成的 .env 是单机版(SQLite + TASK_EXECUTOR=inline + SERVE_FRONTEND=on), 不是 cp .env.example——模板里那套是 Postgres + Redis + Celery 的容器形态,直接 cp 会因为 连不上 DB/Redis 而起不来。inline 的调度守护线程跑在进程内,所以服务形态固定单进程, 加 --workers 等于 N 份守护线程抢同一批任务重复派发;要横向扩展就切 celery 另起 worker。

部署包里只有代码,没有你跑出来的内容(deploy.sh 逐条体检,缺的多的直接 die):

随包走 不随包走
表结构:应用首启 app/db.py:init_db() 自己 create_all + 补列 media/ 产物库——换环境是「迁移」不是「部署」,单独 rsync
模型配置 model_specs + 加密主密钥 model_secret_keys(scripts/seed/) 项目 / 分镜 / 任务等业务数据(开发库全是过程产物)
管理员账号 users(仅 admin,沿用导出的口令哈希) .env——ComfyUI 地址、数据库串都是机器相关的
启动脚本与 DEPLOY-INFO.txt(包里有什么、服务器三步) backend/tests、reports/、docs/、models/、frontend/dist(远端 build;--with-dist 可带上)

主密钥跟包走是有意的:model_specs.api_key 是密文,换机器解不开就等于每台服务器都要重录一遍 各家 Key。代价是 scripts/seed/ 属于机密——已 gitignore、随包走、包内是密文但主密钥也在里面, 按密钥对待。装完 seed.py install 会自检解密并打印当前默认模型;--only-missing 只补缺不覆盖 已有配置,--dry-run 先看将要发生什么,主密钥冲突时区分「没有解密依赖 → 换」与「有依赖 → 中止等你决策」。

服务器上没有 whisper-cli / 听写模型时,只有「台词听写质检」这一项不生效,其余流程照常; server.sh status 会把它标成黄色告警而不是静默降级。--no-asr 可以跳过下载(465M 权重)。

4. 模型与供应商

4.0 真实模型:ComfyUI · MiniMax H3(已实跑通过)

模型接入地址 http://10.100.53.199:9200(ComfyUI 0.42 / GB10 单卡)。填好地址即自动登记进模型注册表:

# .env(放仓库根;backend/ 下启动也会向上找到,见 app/config.py:_dotenv_candidates)
COMFYUI_BASE_URL=http://10.100.53.199:9200
VIDEO_PROVIDER=comfyui
VIDEO_MODEL=minimax-h3

cd backend && ../.venv/bin/uvicorn app.main:app --port 8000 之后, 调度中心 → 模型注册表里 comfyui/minimax-h3 的 🔌 探测会列出机器上真实存在的 UNET / CLIP / VAE 文件名,可直接照着改 config,不必猜 unet_name。

项 实机口径
节点 MiniMaxH3ImageToVideo(首帧/首尾帧/t2v)· MiniMaxH3ReferenceToVideo(参考图 r2v)
画布 模型原生 16:9 → 1312×736(短边 768 档,最长边 ≤1344,边长必须是 32 的倍数);1080p 是交付档:出片仍按原生像素,合成端 lanczos 放大(capabilities.upscale_to),不额外花卡时
时长 帧数必须落在 17k+5 网格:5s→124 帧(5.17s)… 15s→362 帧;模型只在 124–362 帧上训练过
音轨 原生音画同步:VAEDecode + VAEDecodeAudio → CreateVideo(fps=24) → 一次成片自带 AAC
耗时 5s / 20 步 ≈ 18 分钟/镜头(单卡串行,COMFYUI_CONCURRENCY=1;心跳每 STALE_RUNNING_SECONDS/3 续租,不会误判重跑)
反向提示词 H3 无独立入口,适配器把 negative_prompt 折进提示词末尾的自然语言子句

踩过的两个坑(已修 + 已锁测试,改适配器前请先读):

  1. 参考图是 ComfyUI 的 autogrow 槽位(COMFY_AUTOGROW_V3)。ComfyUI 3.x 的 API prompt 必须使用 “父输入.槽位”扁平键:H3 为 ref_images.ref_image_0,Qwen-Image 为 images.image_1。传嵌套字典不会报错,但会被静默解析成空参考集,最终成图/成片与参考图无关。
  2. 时长窗口不能只看节点参数下限(节点 min=5 帧)。低于 124 帧的时长虽然能对齐到 17k+5 网格(4s→107 帧、3s→73 帧),却落在模型训练区间之外,属于「语法合法但模型没见过」 的静默劣化,而且已经花掉一次真实渲染。因此 capabilities 的上下限必须满足: 两端对齐到帧网格后仍落在 124–362 帧内(tests/test_comfyui_adapter.py)。

真实模型端到端验证走平台内链路:模型中心对 comfyui/minimax-h3 点 🔌 探测确认权重到位, 然后新建项目 → 分镜 → 派发,产物用 ffprobe 复核时长与音轨;单个镜头失败就在镜头详情里 「重新生成」,不必整项目重跑。整套 12 节点的自动化版本是 §6.2 的 scripts/e2e_selfcheck.py (mock 适配器,不烧卡时)。早期那些直连 ComfyUI 的一次性探针 (comfyui_e2e.py / predator_meal_e2e.py / platform_full_e2e.py)已完成使命, 归档在 .trash/2026-11-01/scripts/,不再进 scripts/。

4.0.1 台词的语音来源:默认由 H3 直出原声(音画同步)

H3 是原生音画同步模型,人声是对着口型生成在产物音轨里的。所以时间线出厂默认 voice_source="native":镜头产物自带音轨时,台词直接用原声,片段时长 = 产物时长, 不再生成 TTS 覆盖(dispatch 把这类镜头的配音计划标成 skip 并给出理由)。 以前的「单独 TTS + ffmpeg 合成」链路保留为 dub,随时可在 时间线 → 台词语音来源 切回。

错位的根因是口径不一致,不是 ffmpeg 混音不准:TTS 长度与停顿与画面无关,旧逻辑却把 片段拉到 max(画面, 配音+留白) 并定格补帧,于是出现「画面里人物闭着嘴、声音还在说」 (实测旧链路一条 5s 片段里 57% 是静音);改走原声后同一段产物 silencedetect -35dB/0.35s 测不出静音段,音画长度天然相等。

音色不是模型随机挑的嗓子:生成时平台把本镜每个说话人声线的克隆样本按台词顺序喂进 MiniMaxH3ReferenceToVideo.ref_audios.ref_audio_{0,1,2}(prompt.reference_voice_audios, 上限 Capabilities.max_reference_audios=3)。用基频中位数 f0 做 A/B(shot26「俊杰」, 音色样本 120.3 Hz,同 seed 配对):

喂进 ref_audios 的内容 产物 f0_med 相对本人音色样本
不喂任何参考音频 216.2 Hz +11.2 半音(模型自己挑了把嗓子)
俊杰本人的音色样本 131.1 Hz +1.5 半音 ✅
俊杰本人的音色样本 + <Audio 1> 标签 135.6 Hz +2.1 半音(标签无增益)
紫小慧的音色样本(女声喂男画面) 177.8 Hz 画面优先,性别冲突时以人物为准

要点:参考音频真的能锁音色(同性别误差 2 半音内);不给参考就会跑调; 性别冲突时模型以画面人物为准,所以 speaker→声线 的绑定必须准确(预检里 voice_identity_risk 就是盯这个)。产物确实没有音轨时自动回退配音,不会把台词变成哑巴。

一镜多人说话(shot.lines 里有多个 character_id)时,上面的表不够用了: MiniMaxH3ReferenceToVideo 只有一个 prompt 文本入口,「这一句是谁说的」只能靠官方 语音标记表达——<Audio j><d>台词</d> 表示这段用 ref_audio_j 的嗓子(文本编码器 把标签与 prompt 裸拼,见 comfy_text_encoders_minimax.py)。因此 caption 里的说话人 只走标签,绝不写角色名(「俊杰台词:」会被原样念出来,见 4.0.2)。三处必须同时成立:

环节 位置 断掉的后果
按逐句说话人收集音色,顺序=开口顺序 prompt.dialogue_voices 第二个人没有参考音频,全片一个人说话
序号来自同一份列表 prompt.joint_voice_names → compose_joint_caption 标签把台词安到别人的嗓子上
只在「本镜不同说话人 ≤ 1」时才兜底标 <Audio 1> compose_joint_caption.audio_label 单人音色被套给整段对白

漏绑不报错,只会静默换声,所以预检加了 joint_speaker_unbound:某句台词的说话人拿不到 自己的参考音频(角色没设默认声线 / 声线缺克隆样本 / 超出 3 条上限)时点名告警。

4.0.2 联合音视频模型的提示词契约:整段 caption 既被「看」也被「听」

H3 的文字入口只有一个 prompt 字段,没有 chat 模板、没有 system/user 之分, 文本编码器把整段文字同时当画面脚本和声音脚本。凡句子里出现「说/台词/配音/口型/ 音画不同步/必须/严禁/为准」这类关于声音或下指令的说法,它就去念给你听—— 项目 11《告诉你个小秘密第1期》v2 成片逐镜 ASR 实测:开头那两句莫名其妙的 「是这一镜的画面和石腰准和碍」,正是 <Picture 1>是这一镜的画面。<Picture 2>是俊杰, 高大,和蔼 被原样朗读(drop_topic/sanitize_visual 负责剔除)。

因此 prompt.compose_joint_caption 与通用提示词分道,规则是「只写看得见的东西」:

规则 做法
身份锚定不能写成句子 定语 <Picture 3>中的紫小慧,… 而非 <Picture 3>是紫小慧(JOINT_REF_STYLE="prefix" 可回退旧写法做 A/B)
时长/画幅不进文字 它们是 length/width/height 结构化入参,写成「时长约 9 秒」就会被念出来
「谁在说话」不进文字 由首帧构图决定(keyframe_speech_note 只给图像模型)+ <Audio n> 标签;speaking_subject_note 那句构图描述写进 H3 文字就会被朗读
台词是最后一段 官方 <d>…</d> 段落,段间不补句号(会被当成句子结束、各配一段气口)
表情里的「嘴」要改写 「嘴角上扬」→「面带笑意」:发声器官词会诱发即兴人声
台词时长按实测语速 JOINT_CPS_CJK=5.0 字/秒(TTS 口径 4.3 + 标点停顿会多留 2s 空档,模型拿来念提示词),并允许短于分镜时长;帧数还要落在 n % 17 == 5@24fps 格点

回归用例:tests/test_joint_caption.py、tests/test_speaking_subject.py、 tests/test_comfyui_adapter.py::test_joint_av_model_never_gets_a_spoken_negative。

4.1 真实配音:macOS 系统语音(含外星语效果)

macos_say 适配器把系统 say 命令接入统一 TTS 任务、字幕对齐与混音链路,不需要 云服务密钥。启动后端时会自动登记为 macos-say/system-voice:

# 声线资产示例
{
  "name": "女服务员 · Tingting",
  "provider": "macos-say",
  "provider_voice_id": "Tingting",
  "language": "zh-CN",
  "tuning": {"speed": 1.15}
}

# 外星语:Fred 低男声 + 降调/金属共振/颗粒化
{
  "name": "铁血战士 · 外星低吼",
  "provider": "macos-say",
  "provider_voice_id": "Fred",
  "language": "en",
  "tuning": {"params": {"effect": "alien"}}
}

「资产库 → 声线」创建时只填写名称、语言、语速、音色和 alien 效果等基础设定,模型选择 移到「生成试听」步骤,并只列出真实 TTS 模型(Mock 不作为资产生成选项)。未就绪的模型仍可 选择并查看状态,生成时会返回具体缺失节点或服务错误,避免“探测失败就直接禁用”导致 IndexTTS2 无法选。IndexTTS2 必须提供参考音色:可上传一段音频,也可选择资产已有的音频;项目资产库同样 支持从当前声线的音频素材中选择参考音色。单独删除参考音频时会同步清理声线里失效的路径绑定; 若历史数据仍指向已删除文件,适配器会自动回退到模型配置的默认参考音频。适配器会用 ffmpeg 统一转为 24kHz 单声道 PCM WAV 并校验时长;未下载的系统音色或 ComfyUI 缺少 IndexTTS2 节点时 会明确报错,不会再生成只有 0.01 秒的静默文件。

IndexTTS2 是 ComfyUI 自定义节点,不是 Nex 内置推理器。目标 ComfyUI 需安装 ComfyUI-Easy-IndexTTS2,安装模型与 Python 依赖后重启 ComfyUI;/object_info 必须同时出现 easy downloadIndexTTSAndLoadModel 与 easy indexTTSGenerateSimple。Nex 不会在未经授权时远程安装节点或下载大模型。

在 9200 的 ComfyUI 主机上安装节点:

cd /dep/Bfmodeltest/ComfyUI-H3/custom_nodes
git clone https://github.com/yolain/ComfyUI-Easy-IndexTTS2
cd ComfyUI-Easy-IndexTTS2
/dep/Bfmodeltest/ComfyUI-H3/.conda-env/bin/pip install -r requirements.txt
# 重启启动 /dep/Bfmodeltest/ComfyUI-H3/main.py 的 ComfyUI 进程

注意:9200 当前运行 Python 3.13。pynini==2.1.6 没有 cp313 wheel,应先在同一 conda 环境执行 conda install -c conda-forge "pynini=2.1.7";transformers 需限制在 >=4.50,<5,否则 IndexTTS2 vendored 的 4.x generation 实现无法导入;同时需要 WeTextProcessing 与 accelerate。9200 上已按此组合安装并完成真实参考音色生成验收。

节点首次生成时可按 modelscope 下载 IndexTTS-2 模型;也可按项目 README 将模型预置到 ComfyUI/models/IndexTTS-2/。重启后可检查:

curl -fsS 'http://10.100.53.199:9200/object_info/easy%20downloadIndexTTSAndLoadModel'
curl -fsS 'http://10.100.53.199:9200/object_info/easy%20indexTTSGenerateSimple'

Qwen-Image 生成同样支持参考图:平台和项目资产卡片都可选择当前人物/场景已有图片,或临时上传 一张图。适配器通过 LoadImage 和 TextEncodeQwenImage21 的 images.image_N autogrow 扁平槽位提交,并使用编码器输出的参考 latent;不选参考图时仍走 原有纯文生图流程。参考图存在时,输出画布会跟随第一张参考图的宽高比,这是该节点的原生行为。 Qwen Image 2.1 还要求提示词显式引用图片槽位;用户只写“参考图”时,适配器会自动在指令前 补充 以<image1>为参考,按以下要求生成或编辑:。室内/内景类短提示还会自动补充“镜头移到 建筑内部、不要展示外立面或室外庭院”的机位约束,否则模型常沿用参考图的外景构图。生成种子 同时由提示词、参考图和画布尺寸共同派生;用户未固定 seed 时,再次生成会得到新的随机结果, 不会因为平台资产 ID 相同而永久复用同一张图。 分镜关键帧从「分镜 → 资产 → AI 生成关键帧」发起,走同一个真实图像模型与 AssetGenRequest 链路;生成前会同步当前镜头的版本化提示词,结果写入镜头的 keyframe 资产槽位并递增版本, 因此后续 H3 i2v 会立即使用新首帧,无需手工再上传一次。

4.2 三关键帧真实成片示例(平台内跑法)

这条链路已经在真实 H3 上跑通过:三张关键帧 → 角色/场景/声线 → 真人报菜名 → 外星语回应 → H3 三段出片 → 审核 → 时间线混音 → 1080p 导出。现在直接在界面上走:

  1. 资产库录角色定妆图 / 场景图 / 声线;新建项目时可勾选要引入的资源库,避免每次重录;
  2. 分镜写三段镜头:有台词(真人)、有台词(外星语 + 变声)、无台词空镜各一段—— 无台词是正常形态,平台不会为它编一句旁白;
  3. 每段先出关键帧,再用 H3 i2v 出片;voice_source=native 时带原生音轨的镜头不再叠加 TTS(§4.0.1);
  4. 质检 + 人工审核通过后,时间线混音、挂字幕,导出 1080p。

固化的 predator_meal_e2e.py 探针已归档到 .trash/2026-11-01/scripts/;它当年靠 「跳过已成功镜头」省卡时,今天这件事由平台的断点续跑与单镜头重新生成承担。

  • 默认 mock 适配器:不依赖任何供应商即可跑通全流程。视频以关键帧/定妆图为底图按运镜参数生成真实可播放的测试片段,配音按文本长度生成占位人声 WAV,因此质检、时长对账、转场、混音都能被完整验证。它是流水线验证工具,不是 AI 视频模型。
  • http_generic 适配器:供应商协议骨架(提交任务 → 轮询 → 下载),各家(Veo/Kling/可灵/即梦等)请求体差异需实现各自的 adapter,不要假定开箱兼容。
  • 模型注册表 provider_models:GET/POST/PATCH/DELETE /api/providers,可设默认模型、每模型并发上限与 RPM、时长/分辨率能力、每秒单价;调度中心页面支持💥注入 failure_rate=1.0 做故障演练。
  • 真实大模型:在「模型控制台 → 大模型」登记 OpenAI 兼容端点(如 https://api.deepseek.com/v1 / deepseek-v4-pro),填写密钥并设为默认;密钥只以密文落库, 页面回显掩码。大模型只承担 chat / prompt 文本能力,不再提供文生图端点、图像模型或尺寸配置; 旧数据中的 t2i 模式、参考图/画幅字段和 config.image 会在保存或启动迁移时自动清理。 图像生成统一使用独立图像模型。Mock LLM 应在登记真实模型后停用,避免文本补全误走占位结果。
  • 真实供应商通常要求参考图公网可读,请自行接入对象存储并注入签名 URL。

5. 质检与合成参数

项 默认 配置
质检打分 解码完整性 30 / 时长偏差 20 / 分辨率 15 / 码率 10 / 黑屏 8 / 冻结 9 / 帧率 8,硬失败项(severity=error)直接判不合格 QC_DURATION_TOLERANCE、QC_MIN_BITRATE_KBPS、QC_BLACK_THRESHOLD
出片预设 draft_720p(1280×720) · vertical_720p(720×1280) · web_1080p(1920×1080) · vertical_1080p(1080×1920) · hq_1080p(CRF18 slow) · uhd_4k(3840×2160 CRF18 slow) services/ffmpeg.py:EXPORT_PRESETS
时间线 fps/width/height、subtitle_mode、subtitle_style、voice_source(native/auto/dub,见 §4.0.1)、keep_shot_audio、voice_gain_db、bgm_gain_db、duck_bgm、target_lufs、lead/tail_padding_ms、hold_last_frame PATCH /timeline/settings
转场 xfade(有转场滤镜时)或直切;XFADE_MAX_DURATION_MS 限制 TARGET_LUFS 控制 loudnorm 目标响度

FFmpeg 能力探测:GET /health 返回 ffmpeg_capabilities,字段为 available / drawtext / subtitle_burn / subtitle_filter / xfade / concat / loudnorm / blackdetect / freezedetect / font。当 subtitle_burn=false(本机 ffmpeg 未编译 subtitles/ass 滤镜)时:

  • 走时间线默认设置的字幕会被自动降级为「外挂字幕」,导出照常成功,并写入 compose.subtitle_skipped 警告事件(合成报告与事件流可见),不会让任务失败;
  • 只有导出时显式传 burn_subtitle=true 才会中止任务并给出可执行的修复建议—— 用户点名要烧字幕时绝不静默忽略;
  • 外挂字幕随时可取:GET /projects/{id}/timeline/subtitles?fmt=srt|ass; 要真正烧录请换用带 libass 的 ffmpeg 构建(侧边栏此时以黄色标注「降级为外挂字幕」, 而缺 ffmpeg 本体才是红色「阻断合成」)。

6. 测试与自检

改完代码的最低验收(完整约定见 docs/工程规范.md):

cd backend && ../.venv/bin/python -m pytest -q     # 全量回归,约 3 分钟,必须全绿
bash -n scripts/*.sh                               # 脚本语法(shellcheck 没装也别跳过这条)
cd frontend && npm run build                       # 类型与打包

碰到派发 / 合成 / 部署链路的改动,再补一次 §6.2 的端到端自检——pytest 用 TestClient 在进程内测契约,测不出「这台机器上这套服务能不能交付」。

6.1 单元/接口回归(pytest + TestClient,进程内,无需起服务)

cd backend
DATABASE_URL='sqlite://////tmp/nex_tests/t.db' TASK_EXECUTOR=inline MEDIA_ROOT=/tmp/nexmeta \
  ../.venv/bin/python -m pytest -q        # 12 个测试文件 / 115 个用例,全绿

覆盖:系统/健康/枚举、资产库与素材版本、脚本导入与图片匹配、 提示词组装与版本、入队预检与幂等、失败重试与错误留痕、断点续跑、质检打分、审核回路、 时间线重算与交付预检、导出成片与成本台账,以及 tests/test_regression_fixes.py (14 个用例,专门锁定端到端验证中发现并修掉的缺陷:Markdown 文档标题误判为镜头、重复镜号触发 UNIQUE 500、上传响应回吐过期版本、黑场 转场常量拼写、流程节点按镜头计数导致 5/4 分母、 review_state 与审核记录 verdict 必须同源且无产物不得放行、局部生成失败被整体成功掩盖 (失败镜头的旧产物仍在磁盘上时,节点 8/9 也必须转红并从可用产物计数里扣除)、 限流容量行按 (provider, model) 去重且媒体类型跟随模型规格、项目队列不得混入其他项目任务、 平台人物创建时保持全局、单媒体删除及文件清理、IndexTTS2 参考音色上传与项目引入时的本地副本等)。 tests/test_comfyui_adapter.py 还会用本地假 ComfyUI 完整走一遍 IndexTTS2 节点探测、参考音频上传、 节点图提交、音频下载与产物校验,并锁定“缺少节点时不得提交任务”以及 Qwen 参考图 autogrow 连线与参考 latent 的行为。Qwen 参考图节点图已在 9200 实机生成验证。 tests/test_agent_orchestrator.py 覆盖 LLM 结构化计划、全流程白名单执行、Mock 拒绝、越权动作拒绝、 AI 审核授权门禁、空项目阻塞、已完成项目的幂等诊断,以及 kind=agent 审核审计隔离。 tests/test_macos_say.py 另外用系统 say 实测中文与外星语音频,并校验配音任务记录实际 供应商而非全局默认值。Python 需 3.11+ (系统自带 3.9 无法运行本项目)。

6.2 端到端业务自检(打真实服务 + ffprobe 实测)

# 终端 A:起后端(无需 Redis / Postgres / 供应商密钥)
cd backend && DATABASE_URL='sqlite://////tmp/nex_ui/ui.db' MEDIA_ROOT=/tmp/nex_ui/media \
  TASK_EXECUTOR=inline MAX_SHOT_RETRIES=2 RETRY_BACKOFF_BASE_SECONDS=1 \
  RETRY_BACKOFF_MAX_SECONDS=2 ../.venv/bin/uvicorn app.main:app --port 8000
  # 后三个变量只是把「失败重试」的退避从默认几十秒压到 1~2s,让第 16 步不必干等
# 终端 B:跑图2 全 12 节点
NEX_BASE=http://127.0.0.1:8000 ../.venv/bin/python scripts/e2e_selfcheck.py

scripts/e2e_selfcheck.py 会新建一个独立项目,按图2 顺序跑完 12 个节点(含「生成失败重试」 与「审核驳回 → 改提示词 → 重新生成」两条回路),并真的下载产物用 ffprobe 校验镜头与成片 (时长 / 分辨率 / 编码 / 音轨),任一环节不符合预期就打印接口原文并以退出码 1 结束。 它只依赖 HTTP 与本机 ffprobe,不需要知道后端 MEDIA_ROOT。也可 NEX_BASE=http://127.0.0.1:5173 走前端代理,顺带验证代理配置是否正确。服务端开着鉴权(默认值)时脚本会先自动登录换 Cookie (账号取 NEX_USER / NEX_PASS,缺省用 /api/auth/state 回传的初始管理员), 所以部署完在服务器上直接 ./scripts/server.sh verify 就能跑,不用手工准备会话。

第 [16] 步用 PATCH /api/providers/{id} 给 mock 视频模型注入 failure_rate=1.0,验证节点 8 判定为「否」时的完整链路:按上限重试并逐次留痕 → 镜头落 failed 且不产脏数据 → 流程节点转红 并写明原因 → 修复配置后 POST /tasks/retry-failed 一键重跑 → 节点重新全绿,跑完自动把注入复原。 开跑前的 [00] 步还会先清掉上一轮中断残留的注入,因此脚本可以反复执行。

6.3 前端构建

cd frontend && npm run build     # tsc --noEmit && vite build
# 当前 103 modules → 17 个 chunk,JS 合计 ~907 KB(gzip ~296 KB)+ CSS 98 KB(gzip 19 KB)
# 首屏只下载 index(~411 KB/131 KB gzip) + 共享原语 ui(~80 KB/26 KB gzip) + 当前页 chunk;
# 手册 /help 也是懒加载页面(Help chunk 42 KB / 12 KB gzip),不再是一份独立静态 HTML

7. 边界与说明

  • 平台保证的是工程可靠性(幂等、重试、断点续跑、限流、质检、留痕),不保证供应商永不失败,也不保证模型生成的人物绝对一致——一致性靠资产库定妆图 + 提示词约束 + 人工审核共同兜底。
  • 登录鉴权(会话 Cookie + 角色闸门)与供应商密钥加密落库已内置并默认开启,页面只回显掩码; 公网部署仍建议放在 HTTPS 反代后面,并把 MEDIA_ROOT 放在受控存储上。关掉鉴权只适合可信内网。
  • 媒体文件一律由后端 /media/* 直出,前端不拼本地路径;导出记录保留 checksum、size_bytes、elapsed_ms 便于对账。
  • 变更类接口统一返回 {ok, result, summary}(前端 src/api/client.ts 自动拆包),错误体统一读 detail;只读接口大多直接返回资源对象,两个例外是 GET /api/projects/{id} 与 GET /api/projects/{id}/summary——它们也带信封(前端已统一处理,写脚本时记得拆开或自动拆)。

7.1 前后端契约(已用回归用例锁死,改动前请先跑 tests/test_regression_fixes.py)

  • review_state ∈ pending / pass / fail(app/constants.py:ReviewVerdict,与 ReviewRecord.verdict 同源)。它和镜头 status(approved/rejected/…)是两个字段, 分镜卡片按前者显示人工结论;写成 approved 会让每个合格镜头都标红成「被驳回」。
  • 人工审核必须在产物之后:镜头没有 output_path 时 POST /approve 直接 400, 对应图2「质检(9)→ 人工审核(10)」的先后顺序。
  • 流程节点计数按镜头去重:workflow[] 每项是 {key,label,state,done,total,detail}, 同一镜头驳回重做会产生多条任务,计数必须按镜头去重(否则节点 6 永远 active、 节点 4 会出现 5/4);done 恒 ≤ total。
  • /health 是前端侧边栏的唯一数据源:{status, app, executor, ffmpeg, ffmpeg_capabilities{available,drawtext,subtitle_burn,subtitle_filter,xfade,concat,loudnorm, blackdetect,freezedetect,font}, database, model_specs, daemon{enabled,running,executor, inline_pending,loops,last_dispatched,last_error,last_tick}},前端会校验字段类型, 拿不到合法 JSON(例如代理漏配)时直接报错而不是显示「未知」。
  • 响应三套约定:写接口 = {ok, result, summary} 信封;绝大多数只读接口 = 裸资源对象 ({shots,count}、{timeline,report}、{preflight,summary}…);错误 = detail。 例外只有 GET /projects/{id} 与 GET /projects/{id}/summary 也走信封。 另外 PATCH /timeline/settings 的参数需要再包一层 {"settings": {...}}。
  • 交付文案里的项目名:workflow[0].detail 只在项目名不含 《 时补书名号,避免渲染成《《…》》。
  • 限流容量行 GET /api/projects/{id}/queue 的 capacity[]:一个 (provider, model) 只允许一行,media_type / concurrency_limit / rpm_limit / enabled 必须取自该模型的 ModelSpec。曾因任务派生的容量键一律写成 media_type="video",配音模型多出一行默认限额 (2 并发 / 30 RPM)的幽灵记录,并按 provider|model 覆盖掉真正的 TTS 行(4 / 120),派发时的 headroom() 与模型注册表的 load 一起被降级。
  • 局部失败不许被整体成功掩盖:节点 8「调用视频模型」/节点 9「下载并保存视频」的进度按 可用产物计数,停在 failed 的镜头即使磁盘上还留着上一次的旧产物也要从分子里扣掉, 且节点状态必须是 failed。曾因按「产物文件是否存在」直接计数,重做失败的镜头仍显示 「生成成功 4/4 [done]」,界面上完全看不见图2 节点 8 的「否」分支。