# Nex Animation Studio · 长视频编导平台 面向 AI 长视频创作的本地工作台:**人物与声音资产库 → 分镜与脚本管理 → 视频模型调度中心 → 长视频合成引擎**, 底层由统一任务编排(队列 / 重试 / 断点续跑 / 并发限流)与项目数据库支撑,完整实现业务流程图的 12 个节点。 > 📖 **[图文使用手册](frontend/src/pages/Help.tsx)** —— 已搬进站内:启动后访问 ,或点工作台顶栏的「手册」 > > 手册包含模型管理中心、资产独立生成与镜头关联、分镜检查器、调度、质检、时间线和导出流程的实际截图。 > > 🧹 动代码或打部署包之前先读 **[工程规范与部署数据边界](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 · comfyui(含 IndexTTS2 配音)+ 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/ 页面与项目子页(项目详情里的业务子页走 ,不是外壳页签),一屏一文件; 页面私有的类名常量/子组件留在文件底部 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}` 可以 `import 'antd'`—— R8,探针第 5 道闸逐行扫,不再只写在文档里(吐司自绘后 `stores/notice.ts` 已从白名单摘掉); `.ant-*` 选择器只准出现在 `styles/app.css`;`pages/` 与 `app/` 里**一个原生 `