nex_animation/README.md

704 lines
58 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

# Nex Animation Studio · 长视频编导平台
面向 AI 长视频创作的本地工作台:**人物与声音资产库 → 分镜与脚本管理 → 视频模型调度中心 → 长视频合成引擎**,
底层由统一任务编排(队列 / 重试 / 断点续跑 / 并发限流)与项目数据库支撑,完整实现业务流程图的 12 个节点。
> 📖 **[图文使用手册](frontend/src/pages/Help.tsx)** —— 已搬进站内:启动后访问 <http://127.0.0.1:5173/help>,或点工作台顶栏的「手册」
>
> 手册包含模型管理中心、资产独立生成与镜头关联、分镜检查器、调度、质检、时间线和导出流程的实际截图。
>
> 🧹 动代码或打部署包之前先读 **[工程规范与部署数据边界](docs/工程规范.md)**:
> 目录职责、`scripts/` 准入规则、测试规范、改动后的最低验收三连,以及服务器上「什么该搬、什么不该搬」。
```
┌─────────── Browser (React 18 + Ant Design 5 + Vite + Zustand + Router 6) ─────────────┐
│ 项目总览 │ 资产库 │ 分镜与脚本 │ 调度中心 │ 质检与审核 │ 时间线合成 │ 导出与成本 │
└─────────────────────────────────────┬───────────────────────────────────────────────────┘
│ 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 直出)
```
### 仓库目录与脚本职责
```text
backend/ FastAPI 应用:app/api 路由 · app/services 编排 · app/providers 模型适配 · tests 回归用例
frontend/ React 18 + Ant Design 5 + Vite + Zustand + React Router 6 工作台
(图文手册 = 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):
```text
api/ 唯一的 fetch 出口:信封自动拆包、detail 统一成 Error、401 跳登录
app/ 应用外壳:router.tsx 路由表(唯一一份)· layout/ 顶栏侧栏与 nav.tsx 两级导航表 · 鉴权闸门
pages/ 页面与项目子页(项目详情里的业务子页走 <Outlet/>,不是外壳页签),一屏一文件;
页面私有的类名常量/子组件留在文件底部
components/ 页面只从这里取组件,三个目录按职责分:
ui/ antd 的唯一封装层 + 自绘版式件(Button/Input/Checkbox/Menu/Overlay/Status
+ Field/Ctlbar/FormGrid/Table/Steps/Tabs/Pager/Rows…)
forms/ 选择器族(Select/MultiSelect/SecretInput + toOptions,本体是 antd Select)
media/ 带全局状态的媒体件(MediaThumb/AudioPlay/RecordAudio/MediaLightbox/VersionPanel…)
theme/ 只剩 antd.ts 一个文件,它是本站对 antd 的唯一改动清单:buildAntdTheme() 品牌色 + 表面色
+ 少数结构性 ComponentToken(几何/字阶/圆角/间距/断点一律用 antd 默认)· applyRootVars()
在 createRoot 之前把同一批 token 以 --ant-* 的名字铺到 :root · HEADER_HEIGHT 顶栏高度
stores/ zustand 切片:auth · theme · notice · project · models · system · audio · preview · recording
hooks/ use-async / use-polling / use-auto-refresh / use-local-storage(浮层外点关闭交给 antd,不再自己实现)
lib/ 纯函数与适配器:cn · format · media · pipeline · recorder · versions · layers
styles/ index.css(Tailwind @theme:语义名 → antd 落下来的 --ant-*,零像素,圆角与字阶只是别名)
· app.css(语义布局类 + 标签度量 --tag-* + 全站唯一允许写 .ant-* 的地方)
```
新增页面只做三件事:在 `pages/` 落文件 → 在 `app/router.tsx` 注册 → 复用 `components/*` 原语,
缺原语就补进 `components/`(不要复制粘贴样式)。加一类新母版、加一个项目环节(改 `app/layout/nav.tsx`
那张两级导航表 + `app/router.tsx` 子路由)、加一个页面内部页签同理:改表不改逻辑(见 `docs/工程规范.md` §1.1)。
**控件统一用 Ant Design 5**(2026-11-02 定案,此前「Radix primitives + 自有皮肤」那一版已废弃):
浮层定位、翻边避让、焦点圈定与归还、键盘、Esc 分层、锁滚动这些行为不再自己实现——
自己实现时「字段标题与控件不对齐」「下拉面板该翻不翻被压成 35px」这类问题修不完,
而每一项都是组件库早就解决过的。**尺子也交还给 antd**:自造的 `metrics.ts` / `palette.ts` /
`css-vars.ts` 三把尺子已删,`theme/antd.ts` 一处写完两件事——`buildAntdTheme(mode)` 只改品牌色、
表面色和少数结构性 ComponentToken(几何、字阶、圆角、间距、断点全用 antd 默认档位),
`applyRootVars(mode)` 在 `createRoot` 之前把 antd 算出来的 token 以 `--ant-*` 铺到 `:root`;
Tailwind 的 `@theme` 只是把 `--ant-*` 转发成语义类名,控件与自绘区读同一批变量,不可能漂成两套。
硬边界:全仓库只有 `theme/` · `app/`(`providers.tsx` 与外壳 `layout/` 四件套直接铺 `Layout.*`,
外壳没有第二份实现,包一层只会多一个名字)· `components/{ui,forms}` · `stores/notice.ts`
(antd `message` 的唯一出口)可以 `import 'antd'`——R8,探针第 5 道闸逐行扫,不再只写在文档里;
`.ant-*` 选择器只准出现在 `styles/app.css`;`pages/` 与 `app/` 里**一个原生 `<button>` / `<input>` /
`<select>` / `<textarea>` 都没有**,也不许给控件拼 `bg-`/`border-`/`rounded-`。裸 `<button>` 只许留在
「自定义表面族」里,判据是几何而不是长相:宽高由所在那块媒体/容器决定、antd 三档 24/32/40 套不进去的才算。
白名单就 7 个文件(`classaudit.mjs:CUSTOM_SURFACES`)——`ui/Controls`(Chip / TagChip 的叉)、
`ui/Overlay`(Scrim 整屏遮罩)、`media/MediaThumb`(封面角标与删除叉)、`media/AudioPlay`(走带键)、
`media/MediaLightbox`(灯箱翻页钮)、`media/VersionPanel`(版本缩略热区)、`pages/project/Storyboard`;
另有宿主标签不写字面量的 `ui/Tile`(`<As>`,见 `HOST_ELEMENT`)。
自绘区只剩三块并已在规范里登记边界:`Table`、`Steps`、媒体区(缩略图 / 播放条 / 录音 / 灯箱 / 时间线)。
再加一条 **ref 契约(R10)**:kit 组件一律 `forwardRef`,交给页面的 ref 只能是真实 DOM 节点,
antd 的 `InputRef` / `TextAreaRef` 在 kit 内部折掉(`lib/ref.ts`)——React 18 的函数组件收不到 ref,
`tsc` 不报错、像素不变,四处「点了不聚焦」就是这么静默死掉的(报告 26.6)。
这些边界都不靠自觉,两道闸各管一头:
- `node scripts/ui/classaudit.mjs`——**源码用词**(静态,五道检查,退出码 = 五项违规之和):
Tailwind 生成不出规则的**死类名**(v4 改过名的 `break-anywhere` 这类静默失效)/
绕过图标登记表的 `@ant-design/icons` import(只许 `components/icons/index.ts` 一处)/
未收口的裸 `<button>`(白名单外即违规;白名单文件一个 `nex-*` 标记都不写了也违规——说明这一族
已被 antd 取代,条目该从表里删)/ **浮层底部动作条**口径(不写 `size`、`type="primary"` ≤1、
`danger` 必须同带 `type="primary"`、最后一颗是主行动)/ **越界的 `import 'antd'`**(R8);
- `.venv/bin/python scripts/ui/visualcheck.py`——**渲染结果**(浏览器实测,逐路由 × 逐档宽度 × 明暗两色,
八类断言 + console / pageerror,逐条口径见 `docs/UI规范.md` §15.2):**先把 chromeless 的登录页量一遍再登录**
(登录后访问 `/login` 会被鉴权守卫弹回首页,登录后再量只会得到假故障);`:root` 上的 `--ant-*`
是否真的铺到、文字行高有没有塌成 px、侧栏选中态是否跟路由走(≤768 侧栏折叠,二级项在 hover 浮层里,
探针会把浮层打开确认那一条真的带 `.ant-menu-item-selected`)、请求的路由有没有被 `path:'*'` 静默重定向、
display utility 有没有被组件样式静默盖掉(R13 那条层叠陷阱)、横向溢出(祖先横向滚动盒或程序滚动的
裁切盒接住的不算——antd 页签条收溢出页签用的正是后者)、`overflow:hidden` 切掉的字、
**控件标签被省略号截掉**(分段 / 页签 / 按钮 / **下拉当前值**)、**4xx/5xx**(按 URL 分诊:素材文件在
开发库里缺失的 404 单独计数,接口 404 判失败并点名发出它的路由)。
选型理由、四层分工、咬过人的陷阱见 `docs/UI规范.md` §0(十四条硬规矩 R1–R14)与 §1。
旧的手写规范探针(`scripts/ui/legacy/{audit,metrics,vocab}.py`)已作废归档。
改过控件、表单或主题,提交前跑一遍 UI 体检(前端 5173 与后端 8000 需在跑):
```bash
cd frontend && npx tsc --noEmit && npm run build
node scripts/ui/classaudit.mjs # 源码用词闸(不用起服务)
NEX_WIDTHS=1440,992,768,430 NEX_THEMES=dark,light \
.venv/bin/python -u scripts/ui/visualcheck.py # 渲染结果体检 + 截图
```
体检默认量 dev server(5173):**`console` 那一项只能在 dev 上量**——React 与 antd 的告警是
DEV-only,拿 `NEX_UI_BASE=:4173` 量构建产物时它恒为 0,别把那份绿当证据。
| 脚本 | 干什么 | 在哪儿跑 |
| --- | --- | --- |
| `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|voice` | 项目 `draft` |
| 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,适合开发、演示、自检)
**一条命令搞定前后端:**
```bash
./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`,启动时会把本机与局域网地址一起打出来:
```text
界面 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,而不是卡在健康检查超时。
手工启动(想单独控制某个进程时):
```bash
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)
```bash
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/*` 在默认鉴权下需要先拿会话:
```bash
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`,所以开发与测试行为完全不变。
```bash
# ---- 开发机:打包(内容白名单 + 体检,体检不过直接报错不产出包)----
./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 单卡)。填好地址即自动登记进模型注册表:
```bash
# .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`:
```bash
# 声线资产示例
{
"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`](https://github.com/yolain/ComfyUI-Easy-IndexTTS2),安装模型与 Python
依赖后重启 ComfyUI;`/object_info` 必须同时出现 `easy downloadIndexTTSAndLoadModel` 与
`easy indexTTSGenerateSimple`。Nex 不会在未经授权时远程安装节点或下载大模型。
在 9200 的 ComfyUI 主机上安装节点:
```bash
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/`。重启后可检查:
```bash
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`):
```bash
cd backend && ../.venv/bin/python -m pytest -q # 全量回归,约 3 分钟,必须全绿
bash -n scripts/*.sh # 脚本语法(shellcheck 没装也别跳过这条)
cd frontend && npm run build # 类型与打包(tsc --noEmit && vite build)
node scripts/ui/classaudit.mjs # 前端用词闸(源码,秒级)
NEX_WIDTHS=1440,992,768,430 .venv/bin/python -u scripts/ui/visualcheck.py # UI 体检 + 截图
```
碰到派发 / 合成 / 部署链路的改动,再补一次 §6.2 的端到端自检——pytest 用 TestClient
在进程内测契约,测不出「这台机器上这套服务能不能交付」。
### 6.1 单元/接口回归(pytest + TestClient,进程内,无需起服务)
```bash
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 实测)
```bash
# 终端 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 前端构建
```bash
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 的「否」分支。