diff --git a/README.md b/README.md index da64143..202c7a0 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ 面向 AI 长视频创作的本地工作台:**人物与声音资产库 → 分镜与脚本管理 → 视频模型调度中心 → 长视频合成引擎**, 底层由统一任务编排(队列 / 重试 / 断点续跑 / 并发限流)与项目数据库支撑,完整实现业务流程图的 12 个节点。 -> 📖 **[打开图文使用手册](frontend/public/help.html)**(服务启动后也可访问 ) +> 📖 **[图文使用手册](frontend/src/pages/Help.tsx)** —— 已搬进站内:启动后访问 ,或点工作台顶栏的「手册」 > > 手册包含模型管理中心、资产独立生成与镜头关联、分镜检查器、调度、质检、时间线和导出流程的实际截图。 > @@ -35,7 +35,7 @@ ```text backend/ FastAPI 应用:app/api 路由 · app/services 编排 · app/providers 模型适配 · tests 回归用例 -frontend/ React 19 + Vite + Tailwind CSS v4 工作台(public/help.html 就是上面那份图文手册) +frontend/ React 19 + Vite + Tailwind CSS v4 工作台(图文手册 = src/pages/Help.tsx,截图在 public/help/) scripts/ 只放启动 / 部署 / 运维脚本(下表);一次性验证探针不进这个目录 docs/ UI 规范、工程规范、H3 性能诊断记录 media/ 产物库(MEDIA_ROOT) models/ whisper 词级对齐权重 reports/ 阶段验收证据 @@ -597,8 +597,9 @@ NEX_BASE=http://127.0.0.1:8000 ../.venv/bin/python scripts/e2e_selfcheck.py ```bash cd frontend && npm run build # tsc --noEmit && vite build -# 当前 100 modules;页面按路由分包,全部 chunk 合计 ~863 KB(gzip ~283 KB)+ CSS 85 KB(gzip 17 KB) -# 首屏只下载 index(~409 KB/130 KB gzip) + 共享原语 ui(~80 KB/26 KB gzip) + 当前页 chunk +# 当前 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. 边界与说明 diff --git a/backend/app/main.py b/backend/app/main.py index 180797d..e0ed433 100644 --- a/backend/app/main.py +++ b/backend/app/main.py @@ -9,7 +9,7 @@ import logging from contextlib import asynccontextmanager from pathlib import Path -from fastapi import FastAPI, Request +from fastapi import FastAPI, HTTPException, Request from fastapi.middleware.cors import CORSMiddleware from fastapi.responses import FileResponse, JSONResponse from fastapi.staticfiles import StaticFiles @@ -86,6 +86,31 @@ app.mount(settings.media_url_prefix, StaticFiles(directory=settings.media_root), # ------------------------------------------------------------------ 前端产物托管 # 判定逻辑在 app/config.py:Settings.frontend_dist —— 鉴权中间件要问同一个问题, # 而 api 是被本模块反向导入的,放这里会撞循环导入。 + + +def spa_target(dist: Path, full_path: str) -> Path: + """把 URL 路径映射成构建目录里真正要吐出去的文件。 + + React Router 用的是 browser history:`/projects/3/storyboard` 这类深链在磁盘上 + 没有对应文件,必须回落 index.html 交给前端路由,否则用户刷新一次就 404。 + 单独拆成函数(而不是写在路由里)有两个原因: + ① 关着 SERVE_FRONTEND 时下面那段注册代码根本不执行,路由体无法被自检覆盖, + 纯函数则随时能测——路径穿越那一条只能这么验; + ② `/api/xxx` 写错时不该被「回落」骗过去:不排掉 API 前缀的话, + 一个不存在的接口会返回 200 + 一坨 HTML,前端 res.json() 直接报解析错误, + 用户看到的是「Unexpected token '<'」而不是「404 接口不存在」。 + """ + prefix = settings.api_prefix.strip("/") + if full_path == prefix or full_path.startswith(f"{prefix}/"): + # full_path 里本来就带着 api/,别再拼一遍前缀 + raise HTTPException(status_code=404, detail=f"接口不存在:/{full_path}") + target = (dist / full_path).resolve() + # 只允许落在构建目录内:挡掉 "/assets/../../etc/passwd" 这类路径穿越。 + if full_path and target.is_file() and target.is_relative_to(dist): + return target + return dist / "index.html" + + FRONTEND_DIST = settings.frontend_dist() if settings.serve_frontend_enabled() and FRONTEND_DIST is None: logger.warning("SERVE_FRONTEND=%s 但 frontend/dist 里没有 index.html:本次只对外提供 API" @@ -100,11 +125,7 @@ if FRONTEND_DIST is not None: @app.get("/{full_path:path}", include_in_schema=False) async def spa(full_path: str) -> FileResponse: - target = (FRONTEND_DIST / full_path).resolve() - # 只允许落在构建目录内:挡掉 "/assets/../../etc/passwd" 这类路径穿越。 - if full_path and target.is_file() and target.is_relative_to(FRONTEND_DIST): - return FileResponse(target) - return FileResponse(FRONTEND_DIST / "index.html") + return FileResponse(spa_target(FRONTEND_DIST, full_path)) logger.info("前端产物已托管:%s(SERVE_FRONTEND=%s)", FRONTEND_DIST, settings.serve_frontend) diff --git a/backend/tests/test_spa_history_fallback.py b/backend/tests/test_spa_history_fallback.py new file mode 100644 index 0000000..e7ed148 --- /dev/null +++ b/backend/tests/test_spa_history_fallback.py @@ -0,0 +1,103 @@ +"""前端产物托管(React 深链回落)的自检。 + +为什么需要这一组用例:托管路由只在 `SERVE_FRONTEND` 打开时才注册, +日常自检(含 `tests/` 全部既有用例)跑的是纯 API 模式,这段代码一次都没被执行过。 +而 React Router 用的是 browser history——`/projects/3/storyboard` 刷新一次就打不开的话, +整站「能进不能刷」,是部署到服务器上才会暴露的事故,所以把判定拆成纯函数后在这里锁死。 +""" +from __future__ import annotations + +import pytest +from fastapi import FastAPI, HTTPException +from fastapi.responses import FileResponse +from fastapi.testclient import TestClient + +from app.config import settings +from app.main import spa_target + + +@pytest.fixture() +def dist(tmp_path): + """一份最小的「构建产物」:index.html + 一个哈希资源 + dist 外的一份敏感文件。""" + build = tmp_path / "dist" + (build / "assets").mkdir(parents=True) + (build / "index.html").write_text("spa", encoding="utf-8") + (build / "assets" / "index-BRtW2Q.js").write_text("console.log(1)", encoding="utf-8") + # 手册正文搬进 React 后,public/help/ 只剩截图目录:页面本身要回落,图片要直出 + (build / "help").mkdir() + (build / "help" / "overview.png").write_text("PNG", encoding="utf-8") + (tmp_path / "secret.txt").write_text("leaked", encoding="utf-8") + return build + + +def test_deeplinks_fall_back_to_index(dist, tmp_path): + """深链 = 磁盘上没有对应文件 → 必须回 index.html,交给 React Router。""" + index = dist / "index.html" + for path in ("", "projects", "projects/3", "projects/3/storyboard", "assets", + "users", "account", "login", "help"): + assert spa_target(dist, path) == index, path + # 目录不是文件:/assets 也只能回落,不能把目录本身当文件发出去 + assert spa_target(dist, "assets") == index + + +def test_real_build_files_are_served_as_themselves(dist): + assert spa_target(dist, "assets/index-BRtW2Q.js") == dist / "assets" / "index-BRtW2Q.js" + assert spa_target(dist, "help/overview.png") == dist / "help" / "overview.png" + + +def test_missing_asset_falls_back_instead_of_500(dist): + """哈希资源在 CDN/旧标签页里对不上时:回壳,别把 FileResponse 的缺文件异常抛给用户。""" + assert spa_target(dist, "assets/index-STALE00.js") == dist / "index.html" + + +def test_path_traversal_stays_inside_the_build_dir(dist, tmp_path): + """构建目录之外、但磁盘上真实存在的文件,不能被 URL 摸出去。""" + assert spa_target(dist, "../secret.txt") == dist / "index.html" + assert spa_target(dist, "assets/../../secret.txt") == dist / "index.html" + + +def test_unknown_api_path_is_404_not_the_app_shell(dist): + """写错的接口路径不能被 history 回落伪装成 200 + HTML。""" + for path in ("api/nope", "api/library/assets/99999999", "api", "api/"): + with pytest.raises(HTTPException) as caught: + spa_target(dist, path) + assert caught.value.status_code == 404 + assert "接口不存在" in caught.value.detail + # detail 里只出现一次前缀:/api/nope 不该被写成 /api/api/nope + with pytest.raises(HTTPException) as caught: + spa_target(dist, "api/nope") + assert caught.value.detail == "接口不存在:/api/nope" + # 只是名字像 api 的页面路由不能被误伤 + assert spa_target(dist, "api-notes") == dist / "index.html" + + +def test_http_behaviour_matches_the_registered_route(dist): + """把同一个判定挂成一个真路由,验 HTTP 层的形状(页面 200 HTML / 接口 404 JSON)。""" + shell = FastAPI() + + @shell.get("/{full_path:path}", include_in_schema=False) + async def spa(full_path: str): + return FileResponse(spa_target(dist, full_path)) + + client = TestClient(shell) + page = client.get("/projects/3/timeline") + assert page.status_code == 200 and "spa" in page.text + chunk = client.get("/assets/index-BRtW2Q.js") + assert chunk.status_code == 200 and "javascript" in chunk.headers["content-type"] + missing = client.get("/api/definitely-not-a-route") + assert missing.status_code == 404 and "接口不存在" in missing.json()["detail"] + + +def test_frontend_dist_resolution(monkeypatch, tmp_path, dist): + """config 层的三态:关 / 开了但没构建 / 开了且构建过。鉴权中间件问的是同一个问题。""" + monkeypatch.setattr(settings, "serve_frontend", "off") + assert settings.frontend_dist() is None + monkeypatch.setattr(settings, "serve_frontend", "auto") + monkeypatch.setattr(settings, "frontend_dist_dir", str(tmp_path / "not-built")) + assert settings.frontend_dist() is None, "没 index.html 的目录不能当 SPA 壳发出去" + monkeypatch.setattr(settings, "frontend_dist_dir", str(dist)) + assert settings.frontend_dist() == dist + # 相对路径锚定仓库根,避免「换个目录启动就找不到前端」 + monkeypatch.setattr(settings, "frontend_dist_dir", "frontend/dist") + resolved = settings.frontend_dist() + assert resolved is not None and resolved.is_absolute() and resolved.name == "dist" diff --git a/docs/UI规范.md b/docs/UI规范.md index adfe75a..fa7934a 100644 --- a/docs/UI规范.md +++ b/docs/UI规范.md @@ -58,11 +58,13 @@ | `.linehint` | ``(成行告警);空内容不渲染的用 `` / `` | `ui/Panel.tsx` · `ui/Page.tsx` | | `.drawer` `.drawer-backdrop` `.drawer-x` `.drawer-actions` | ``(`actions` 就是外壳直接子元素那一层) | `ui/Overlay.tsx` | | 对话框 / `.modal` | `` | `ui/Overlay.tsx` | +| 白屏 / 整页崩了(老站没有这一层,崩了就直接白屏) | `` 已在 `app/App.tsx` 包住两处 ``,页面**不要**自己再写 try/catch 或错误页 | `app/ErrorBoundary.tsx` | | `.small-label` + `.sect-act` | `` / `` | `ui/Panel.tsx` | | `v-if` / `v-show` | `{cond && }` / `hidden`(条件挂载本身要保留,见 G2) | JSX | | `v-model.number="filters.page_size"` | `value={…}` + `onChange={(next) => …}` | 受控组件 | | `:deep(.aplay){min-width:110px}` | 传 `className`(`cn` 走 tailwind-merge,**后写的赢**)或容器上的任意变体 `[&>*]:min-w-[110px]` | `lib/cn.ts` | | `@media (max-width:1180px)` | 断点变体写在类上:`max-huge:`1440 `max-mid:`1180 `max-mid2:`1100 `max-nav:`900 `max-short:`820 `max-tiny:`640 `max-narrow:`560 | `styles/tokens.css` | +| 上面七档都不合适的阈值(只属于某个组件自己的塌陷点) | **允许**任意值变体 `max-[620px]:`,但只许在同一个组件/同一段类名常量里复用;一旦第二个文件也要用它,就回 `tokens.css` 的 `@theme` 里升格成 `--breakpoint-名字`(现状:命名档 171 处、任意值 21 处,且集中在 `AgentConsole.tsx` 与 `Storyboard.tsx` 两个页面内部) | `styles/tokens.css` · 页面类名常量 | | 栅格降列 | ``——变量驱动,页面不写 `@media` | `ui/Panel.tsx` | ## 1. 控件栏(工具条 / 筛选条 / 搜索条 / 卡片动作行) @@ -273,7 +275,7 @@ - **必填星号**:`.req` 必须和标签文字在**同一个** `.lbl` 里(列方向 `label` 的文本节点与 `` 会被拆成两个 flex item,星号会掉到下一行——图4 的根因)。 未迁移的写法由全局 `label:has(> .req)` 兜底(转块级 + `nowrap`),但新代码一律 `.lbl`。 -- 说明文字用 `.muted`/`.hintline`,**不超过一行**;超出的解释进手册(`public/help.html`)或 `title` 提示。 +- 说明文字用 `.muted`/`.hintline`,**不超过一行**;超出的解释进手册(`/help` → `frontend/src/pages/Help.tsx`)或 `title` 提示。 - 抽屉:标题块与第一个字段之间 ≥ 12px(`.drawer-body > :first-child{margin-top:0}` 由 `.drawer-body` 的 padding 提供,不要在页面上加 `margin-top`);标题与紧随其后的分组标题 不得共用一行(图4「AI 试听」与「模型」挤在一起)。 diff --git a/docs/工程规范.md b/docs/工程规范.md index 412c3f9..3b4fd93 100644 --- a/docs/工程规范.md +++ b/docs/工程规范.md @@ -33,7 +33,7 @@ api/ → app/ → pages/ → components/{ui,forms,media}/ → hooks/ · | 目录 | 放什么 | **不**放什么 | |---|---|---| | `api/` | 唯一的 `fetch` 出口(信封拆包、`detail`→`Error`、401 跳登录) | 业务分支、组件状态 | -| `app/` | 外壳:`router.tsx` 路由表 · `layout/` 顶栏侧栏鉴权闸门 · `nav.ts` 项目页签表 | 任何业务接口调用 | +| `app/` | 外壳:`router.tsx` 路由表 · `App.tsx` 布局与守卫 · `ErrorBoundary.tsx` 分包失败兜底 · `layout/` 顶栏侧栏与 `nav.ts` 页签表 | 任何业务接口调用 | | `pages/` | 一屏一文件;页面私有小组件与类名常量在文件底部 | 页面之间的互相 import | | `components/ui/` | 版式与控件原语(`Button` `Field` `Ctlbar` `Table` `Modal` `Drawer` `Tag` `Pager`…) | 业务字段名、接口路径 | | `components/forms/` | 选择器族(`Select` `MultiSelect` `SecretInput` + `toOptions`) | 页面专属选项 | @@ -47,7 +47,7 @@ api/ → app/ → pages/ → components/{ui,forms,media}/ → hooks/ · | 想做的事 | 改哪儿 | 为什么不用改逻辑 | |---|---|---| | 加一类平台母版 | `pages/AssetLibrary.tsx:TYPE_META` 加一项 | 左栏、卡片、抽屉标题、生成台全部从这张表取标签/图标/提示 | -| 加一个项目页签 | `app/layout/nav.ts` 加一行 + `app/router.tsx` 加子路由(带 `handle` 标题) | 侧栏与文档标题分别由这两处派生,无需注册第三处 | +| 加一个项目页签 | `app/layout/nav.ts` 加一行 + `app/router.tsx` 加子路由(带 `handle` 标题) | 侧栏与文档标题分别由这两处派生,无需注册第三处;新页签自动获得懒加载分包与 `ErrorBoundary` 兜底 | | 改某页每页条数档位 | `Pager` 的 `sizes`(页面里传 `PAGE_SIZES`,`0` = 全部) | 默认档位和「全部」语义在 `Controls.tsx` 一处实现 | | 抽屉想要别的宽度 | `Drawer` 的 `width` 收一个 Tailwind 宽度类 | 默认值只在 `Overlay.tsx` 写一次,页面按屏宽传变体 | | 新增弹窗/表单 | `Modal` `Drawer` `Field` `FormRow` 组合 | 高度、间距、页脚按钮排布由原语和容器 `--ctl-h` 档位兜住 | diff --git a/frontend/public/help.html b/frontend/public/help.html deleted file mode 100644 index 6064028..0000000 --- a/frontend/public/help.html +++ /dev/null @@ -1,954 +0,0 @@ - - - - - - - Nex Animation Studio · 使用手册 - - - - -
- - -
-
-

NEX ANIMATION STUDIO · USER GUIDE

-

长视频编导平台使用手册

-

- 从模型配置、资产管理、脚本导入,到分镜生成、自动质检、人工审核与长视频合成, - 本手册按实际业务流程说明每个页面的用途与关键操作。所有截图均来自正在运行的系统。 -

-
- 四类模型统一管理 - 资产独立生成与镜头关联 - 队列入队 / 重试 / 断点续跑 - 质检、时间线与完整导出 -
-
- -
-
-
00 · GET STARTED

快速开始

-

建议先确认模型可用,再创建项目并导入分镜。单机模式下默认使用 SQLite 与进程内任务执行器。

-
-
-
- ▶ - 一键启动 -

在仓库根目录执行启动脚本,脚本会自检依赖、环境变量和端口。

-
-
- ◫ - 配置模型 -

在模型管理中心检查大模型、视频、图像、声音四类模型的连接状态与默认项。

-
-
- ◎ - 进入项目 -

从项目总览创建或打开项目,按左侧业务模块依次推进。

-
-
-
- 界面导航:顶部应用栏左侧是平台标识;正中间是流程进度控制台——项目名、项目状态、 - 12 个业务节点轨道(按完成 / 进行中 / 需处理 / 待处理着色;进行中的那一段更高、带光晕并与需处理一起呼吸闪烁, - 扫一眼就知道卡在哪一段)、 - 流程进度(已完成节点 ÷ 全部节点)与当前节点,点一下控制台就回到流程概览;12 个节点全部走完时这里改说 - 「全部 12 个节点已完成」,不会在「已交付」旁边再挂一个假的当前节点。这条口径由 - frontend/src/pipeline.ts 统一定义,侧栏项目副标题、项目页头标签、流程进度条 - (含总览右侧的示例流程)、项目设置面板的状态标签(流程推进中 / 流程已完成 / 已归档)、 - 「下一步建议」抬头、项目总览表格与卡片的「流程节点」列、资产库「引入项目」下拉的副标题 - 全部复用它,任何一处都不会各说各话。右侧固定放使用手册、显示模式(深色 / 浅色, - ⌘/Ctrl+Shift+L 随时切换)和账号胶囊;点开账号胶囊即是二级菜单——我的账号、用户管理、退出登录都在这里。 - 接口文档不再占用顶栏入口,需要时直接访问 /docs。 - 左侧栏只保留模块导航:全局三个模块 + 当前项目的七个业务节点。页面底部不再常驻系统信息。 -
-
- - 项目总览页:顶部应用栏(平台标识、居中的流程进度控制台、手册 / 显示模式 / 账号胶囊)与左侧模块导航 - -
项目内页面:顶栏居中的进度控制台常驻,轨道颜色、流程进度与当前节点跟着轮询实时更新;右侧手册 / 显示模式 / 账号胶囊固定。点击图片查看原图 ↗
-
-
- 环境自检:执行器、ffmpeg、字幕烧录 / 内嵌、数据库、调度守护这些后台能力不再常驻页面, - 只有真的出问题时才会在账号菜单里出现一行警告;需要随时核对,直接打开 - /health 与 - /api/meta。 -
-
./scripts/dev.sh                 # 启动前后端
-./scripts/dev.sh status          # 查看端口、健康状态和默认模型
-./scripts/dev.sh logs            # 跟踪前后端日志
-./scripts/dev.sh stop            # 停止服务
-
-# 默认地址
-# 工作台   http://127.0.0.1:5173
-# 接口文档 http://127.0.0.1:8000/docs
-
- 如果页面能打开但页面顶部出现「后端连接异常」,先运行 ./scripts/dev.sh status, - 再检查 http://127.0.0.1:8000/health 是否返回 JSON。 -
-
- -
-
-
01 · PIPELINE

完整业务流程

-

项目的流程条会实时汇总镜头、任务、质检、时间线与导出状态。任何一步跳过或失败,都会在上方流程条中暴露。

-
-
-
① 创建项目设定片长、画幅与风格
-
② 导入分镜脚本与关键帧一起入库
-
③ 绑定资产人物、场景、声线关联镜头
-
④ 生成任务按镜头生成任务清单
-
⑤ 预检调度检查素材、参数与容量
-
⑥ 调用模型执行视频和配音生成
-
⑦ 保存产物下载并登记新素材版本
-
⑧ 自动质检解码、时长、分辨率、帧率等
-
⑨ 人工审核合格通过或带修改意见重做
-
⑩ 时间线合成裁剪、转场、字幕、配音、BGM
-
⑪ 出片预检检查缺片、字幕与音轨
-
⑫ 导出交付生成成片并记录成本与校验和
-
-
- 推荐顺序:模型管理中心 → 资产管理 → 分镜与脚本 → 任务调度中心 → 质检与审核 → 时间线合成 → 导出与成本。 - 资产可以先独立生成,再在分镜的“资产绑定”页中关联,不要求先有镜头的生成产物。 -
-
- -
-
-
02 · MODEL OPERATIONS

模型管理中心

-

统一管理机构可调用的四类能力。资产独立生成和分镜任务都会读取这里的默认模型与供应能力。

-
-
-
✦大模型

剧本拆解、编导指令与提示词补全,修正跨镜头一致性。

-
▶视频模型

文生视频、图生视频、首尾帧;配置并发、RPM、时长与分辨率。

-
▧图像模型

人物定妆图、三视图、服装、表情以及场景参考图。

-
◉声音模型

TTS 配音与声线试听样本,可绑定到人物和镜头台词。

-
-
- - 模型管理中心:大模型、视频、图像、声音四类模型统一管理 - -
模型管理中心:四类模型分类、默认模型、连接状态、容量与价格。点击图片查看原图 ↗
-
-

常用操作

-
    -
  1. 点击右上角“登记模型”,填写 Provider、Model、媒体类型与适配器;媒体类型必须与适配器匹配。
  2. -
  3. 为大模型、视频、图像、声音分别设置一个启用中的默认模型,资产页会自动选中对应默认项。
  4. -
  5. 展开模型卡片编辑并发、RPM、时长、分辨率、价格和默认参数。
  6. -
  7. 点击「检测连接」检查适配器与外部服务是否可达;不可用时先修复连接再执行生成。
  8. -
  9. 在故障演练中使用可控失败率验证重试与断点续跑,验证完成后恢复为正常配置。
  10. -
-
- 提示:切换默认模型只影响后续任务,不会重写已经完成的任务记录。历史任务仍保留当时的 Provider、Model、参数和产物版本。 -
-
- -
-
-
03 · ASSET MANAGEMENT

资产管理

-

集中维护人物、场景、声线与项目素材。资产可以独立调用模型生成,也可在分镜中绑定并参与后续视频生成。

-
-
-
人物

外观、性格、一致性提示词、默认声线;定妆图 / 三视图 / 服装 / 表情。

-
场景

描述、光线、时间、色调;场景图可作为镜头参考与关键帧来源。

-
声线

Provider voice_id、语言、性别、语速、效果与试听样本。

-
项目素材

BGM、音效、通用参考图与视频,可挂到时间线音轨。

-
-
- - 资产管理人物页:独立生成、默认模型、版本与被镜头使用情况 - -
人物资产:默认图像 / 大模型已自动选中,并显示镜头使用位置与模型生成版本。点击图片查看原图 ↗
-
-

独立生成人物或场景资产

-
    -
  1. 打开“资产管理”,选择人物或场景页签。
  2. -
  3. 在对应的 AI 生成卡片中选择图像模型和生成类型;需要文本补全时选择大模型。
  4. -
  5. 生成描述可以留空,系统会使用人物外观、场景描述、光线与风格设定自动组装提示词。
  6. -
  7. 点击「生成母版图像」(人物定妆图 / 三视图 / 场景图)。完成后资产自动登记新版本,并显示 Provider / Model。
  8. -
  9. 点击“AI 补全一致性提示词”,检查建议内容后选择“采用”,写回人物或场景设定。
  10. -
-
- 与分镜的关联:每个资产卡片显示“被 N 个镜头使用”。点击镜头链接会进入分镜页并自动选中对应镜头; - 在分镜右侧“资产绑定”页可调整人物、场景和声音。生成视频时,有效的参考资产会进入模型请求。 -
-
- - 场景资产页:场景独立生成、模型选择、镜头使用关系和场景参考图 - -
场景资产:同样可以选择图像 / 大模型独立生成,结果自动登记版本并显示关联镜头。点击图片查看原图 ↗
-
-
- - 声音资产页:TTS 模型选择、AI 试听生成和可播放音色样本 - -
声音资产:选择声音模型生成试听样本,音频版本可直接播放;下方展示绑定的镜头。点击图片查看原图 ↗
-
-

声音资产

-
    -
  • 选择可用声音模型,填写试听文本后点击「生成试听样本」。
  • -
  • 生成完成会得到带时长、Provider、Model 与任务 ID 的新版本音频。
  • -
  • macOS 系统语音可使用 Tingting、Meijia、Fred 等 voice_id;外星角色可选择降调与金属共振效果。
  • -
  • 人物默认声线绑定后,镜头台词可自动进入 TTS 配音与时间线混音流程。
  • -
-
- -
-
-
04 · STORYBOARD

分镜与脚本

-

分镜工作台:顶栏看总量与预检指标,看板或分镜表浏览镜头序列,右侧常驻检查器按“镜头 / 资产 / 提示词 / 产物”组织细节。

-
-
- - 分镜工作台:指标条、搜索筛选、批量操作与网格看板 - -
分镜工作台:镜头数 / 计划时长 / 已合格 / 有阻塞一眼可见,卡片显示缩略图、景别运镜、QC 分、绑定与逐镜预检问题。点击图片查看原图 ↗
-
-
-
导入脚本

支持 Markdown、CSV、TSV、JSON 与纯文本,可先预览再落库。

-
关键帧匹配

图片可按镜号自动匹配,也支持 ZIP 批量导入。

-
资产绑定

人物、场景和声音可逐镜头关联,并即时看到使用关系。

-
-
- - 分镜工作台:选中镜头后右侧常驻检查器的镜头页签 - -
选中任一镜头后检查器常驻右侧并与看板并排:镜头参数、资产绑定、提示词版本、产物与质检各占一个页签,改动未保存会有「未保存」标记。点击图片查看原图 ↗
-
-

推荐操作

-
    -
  1. 点击“导入脚本 / 关键帧”,粘贴脚本并上传关键帧;先用“导入预演”确认镜头数量与图片匹配,再正式导入。
  2. -
  3. 用搜索框和状态 / 模式 / 排序筛选定位镜头,或点“仅看阻塞”“仅看缺关键帧”直接清理预检问题。
  4. -
  5. 拖动卡片即可改镜序(分镜表视图也可拖行或用 ↑↓);勾选多个镜头后可批量复制、移到最前、统一改参数或删除。
  6. -
  7. 选中镜头后在检查器编辑参数与绑定;提示词页可切换“自动组装 / 人工覆盖”,并回填任意历史版本。
  8. -
  9. 卡片上的“生成”“审核”带 ?shot=镜头ID 深链,跳到调度中心或审核页时会自动选中同一镜头。
  10. -
  11. 需要交给编剧或外部工具时,用右上角导出 Markdown / CSV / JSON,导出的 Markdown 可以直接再导回来。
  12. -
-
- 快捷键:J / K 或 ↑↓ 切换镜头,X 勾选当前镜头, - ⌘S 保存检查器改动,Esc 关闭检查器或导入面板。首屏只拉轻量看板数据, - 几十上百镜也不会拖慢页面。 -
-
- -
-
-
05 · DISPATCH

任务调度

-

任务清单先解释执行原因,再按模型容量和限流派发。已完成镜头会被跳过,避免重复消耗真实模型时长。

-
-
- - 任务调度中心:分镜任务清单、预检结果、执行开关和异常处理 - -
调度中心:任务状态、Provider / Model、预计成本、入队选项与断点续跑入口。点击图片查看原图 ↗
-
-
-
- 入队前 -

检查预检阻塞项、镜头状态、模型容量与预计成本。默认只入队预检通过的镜头,缺素材或缺参数的镜头会被跳过,需要时再勾选「放行预检未通过的镜头」。

-
-
- 执行中 -

查看运行任务、心跳、尝试次数与进度。失败任务会按配置重试,超时任务可从中断点续跑。

-
-
-
    -
  1. 确认任务清单中的 Provider / Model 与预期一致。
  2. -
  3. 按需开启「入队时一并排配音任务」「放行预检未通过的镜头」「强制重建任务(忽略幂等)」,并设置优先级与单次派发上限。
  4. -
  5. 点击「入队所选 / 全部待生成」。勾选「派发后同步排空」会一直等到任务跑完再返回;不勾选时任务在后台执行,页面自动刷新进度。
  6. -
  7. 失败时查看错误码与错误历史;修复后使用“重排全部失败任务”或“断点续跑”。
  8. -
  9. 已完成且仍需强制重做的镜头,勾选“强制重建任务”后再派发。
  10. -
-
- -
-
-
06 · QUALITY & REVIEW

质检与审核

-

先自动检查文件完整性、时长、分辨率、帧率等指标,再由人工确认画面和声音。驳回可携带修改意见重新生成。

-
-
- - 质检与审核页面:自动质检清单、镜头预览、检查项得分和人工审核 - -
质检与审核:自动质检清单、视频预览、逐项指标解释和人工通过 / 驳回操作。点击图片查看原图 ↗
-
-
    -
  • 在自动质检清单中按镜头检查得分为 100 的项,确认没有解码、时长或分辨率异常。
  • -
  • 播放右侧产物,检查人物一致性、动作、构图、音轨和字幕风险。
  • -
  • 合格后填写审核人并提交;不合格时填写修改意见与新的提示词,选择是否立即重新生成。
  • -
  • 驳回镜头会回到任务计划状态,再次进入调度中心,不会覆盖之前的历史产物。
  • -
  • 镜头多时用顶部“批量放行质检合格镜头”一次性放过全部质检通过且待审核的镜头,只手工盯有问题的几个。
  • -
  • 从分镜工作台点“审核”跳过来时带 ?shot=镜头ID,右侧直接定位到该镜头。
  • -
-
- -
-
-
07 · COMPOSE & DELIVER

时间线与导出

-

时间线只收集已审核合格产物,统一处理片段顺序、转场、字幕、配音、BGM、响度与最终编码。

-
-
-
- - 时间线合成:片段、转场、字幕、音轨和交付预检 - -
时间线:片段与转场、字幕、音轨和交付预检。查看原图 ↗
-
-
- - 导出与成本:出片预设、成本台账、成片记录与下载 - -
交付:选择预设、检查成本、生成并下载成片。查看原图 ↗
-
-
-

时间线合成

-
    -
  1. 点击“构建 / 重建时间线”,系统自动收集已审核合格镜头。
  2. -
  3. 调整片段顺序、时长、入点、转场和音量;补齐缺失字幕与配音。
  4. -
  5. 检查交付预检报告,确保缺片、字幕、声轨和总时长均为通过状态。
  6. -
  7. 如使用外挂字幕,保持字幕模式为 SRT;当前 ffmpeg 未启用烧录滤镜时会明确降级。
  8. -
-

导出与成本

-
    -
  • 选择横屏或竖屏的 720p 试片、1080p 投放、高质量 1080p 或超清 4K 预设,可多选依次入队。
  • -
  • 确认成片名称、字幕策略与优先级,然后点击“开始合成导出”。
  • -
  • 在成片记录中检查分辨率、帧率、时长、大小、校验和与下载地址。
  • -
  • 成本台账按 Provider、Model 汇总实际费用;mock 模型的单价为 0。
  • -
-
- -
-
-
08 · TROUBLESHOOTING

故障排查

-

先看页面错误和任务错误历史,再看后端健康状态与日志;不要在未确认原因时反复重烧真实模型。

-
-
- - - - - - - - - - - - - - - - -
现象优先检查处理方式
前后端服务未启动./scripts/dev.sh status运行 ./scripts/dev.sh restart --no-install,再查看 .local/logs/。
启动时报 unbound variable脚本是否将变量写作 ${VAR}Bash 3.2 下变量紧邻中文或全角符号时必须使用花括号形式。
模型下拉框为空模型管理中心是否启用对应媒体类型启用并设置默认模型;资产页加载完成后会自动同步默认值。
资产显示被 0 个镜头使用分镜“资产绑定”页逐镜头绑定人物、场景或声音;预检会提示缺失绑定。
派发被拒或镜头被跳过预检问题与镜头状态优先补齐阻塞项;只有确认需要重做时才开启强制重建。
任务超时或进程重启任务心跳和检查点使用断点续跑,保留已成功镜头,避免重复调用模型。
时间线为空是否存在已审核合格镜头先完成质检与人工审核,再重建时间线。
字幕烧录失败/health 中的 ffmpeg_capabilities.subtitle_burn改为外挂 SRT,或安装带 libass / subtitles 滤镜的 ffmpeg。
真实模型连接不可达模型中心的探测结果(含中文结论)按探测提示确认那台机器上的 ComfyUI 进程与端口是否还在。平台直连 ComfyUI,不走系统代理,因此本机开了 Clash / VPN 也不影响出片,排查时不必检查代理设置。
点录音没有弹授权框,或提示打不开麦克风页面会先体检麦克风:设备数、系统权限、当前地址是否 https按提示逐条处理:系统设置 → 隐私与安全性 → 麦克风里放开浏览器;地址栏左侧图标把麦克风改回「允许」;用 IP + http 从别的机器访问时浏览器根本没有录音接口,请改用 localhost 或 https。急着出片可先在外部录好再走「上传文件」。
点了「开始录制」一直转圈,系统授权框始终没出现(macOS)macOS 的麦克风授权框出现在屏幕左下角(不是窗口正中),很容易被忽略;一旦误点「不允许」,Chrome 会记住结论,之后不再弹框,页面只会收到一句 Requested device not found录音面板顶部有一行麦克风自检:✓ 麦克风已就绪:设备名 表示可以直接录;⚠ 时按下面的说明逐条走,需要重置系统权限时点「复制修复命令」,粘到终端执行 tccutil reset Microphone com.google.Chrome 后回到面板点「重新检测」即可,不用重启浏览器。换了麦克风或改了系统权限也不用刷新:面板会自动重新体检。
录到一半录音面板自己消失了是否正好切走了类型 / 筛选(母版列表换了内容,卡片上的面板随之关闭)录音期间平台的自动刷新会主动让路(不重建列表),录完或关掉面板后下一轮自动恢复;切换类型、翻页会离开当前母版,请先停止录制并保存这段录音。
-
-
# 快速收集运行时信息
-./scripts/dev.sh status
-curl -fsS http://127.0.0.1:8000/health
-tail -n 200 .local/logs/backend.log
-tail -n 200 .local/logs/frontend.log
-
- -
-
-
09 · API REFERENCE

接口文档

-

所有前后端操作都通过同一组 REST 接口完成,便于脚本化、自动测试和后续接入其他客户端。

-
-
-
Swagger UI

/docs:浏览并直接调用全部接口。

-
OpenAPI JSON

/openapi.json:供代码生成与自动化测试使用。

-
健康检查

/health:执行器、数据库、ffmpeg、守护调度器与模型数量。

-
-
- 常用接口包括 GET /api/providers、POST /api/projects/{id}/assets/generate、 - POST /api/projects/{id}/assets/text-assist、GET /api/projects/{id}/assets/usage、 - POST /api/projects/{id}/dispatch 与 POST /api/projects/{id}/compose。 -
-
- -
- Nex Animation Studio · 本手册随平台代码维护。截图来自项目《铁血战士的猎人晚宴》的实际运行状态。 -
-
-
- - diff --git a/frontend/src/app/App.tsx b/frontend/src/app/App.tsx index cddddc7..4dfdca4 100644 --- a/frontend/src/app/App.tsx +++ b/frontend/src/app/App.tsx @@ -15,6 +15,7 @@ import { toggleTheme } from '../stores/theme' import { useProjectStore } from '../stores/project' import MediaLightbox from '../components/media/MediaLightbox' import AppBar from './layout/AppBar' +import ErrorBoundary from './ErrorBoundary' import SideNav from './layout/SideNav' import NoticeToast from './layout/NoticeToast' import type { RouteHandle } from './router' @@ -107,9 +108,11 @@ export default function App() { if (location.pathname === '/login' && auth.checked && auth.user && !auth.offline) return return (
- 页面加载中}> - - + + 页面加载中}> + + +
) @@ -128,9 +131,12 @@ export default function App() { {/* 换顶级路由时整块重挂:避免上一个页面的本地状态(筛选条件、抽屉) 串到下一个页面。同一项目内切页签时顶级路由没变,不会重挂。 */} - 页面加载中}> - - + {/* 边界在 Suspense 外层:换页时随 pathname 复位(见 ErrorBoundary 注释) */} + + 页面加载中}> + + + diff --git a/frontend/src/app/ErrorBoundary.tsx b/frontend/src/app/ErrorBoundary.tsx new file mode 100644 index 0000000..794aa96 --- /dev/null +++ b/frontend/src/app/ErrorBoundary.tsx @@ -0,0 +1,81 @@ +/** + * 渲染期兜底 + 路由分包加载失败自愈。 + * + * 为什么必须有它:页面全部改成路由级懒加载之后,「点一个页面」多了一次网络请求。 + * 重新部署过一次,浏览器里那份 index.html 还在引用被替换掉的旧哈希 chunk, + * 点进去就是 `Failed to fetch dynamically imported module`;React.lazy 在渲染期 + * 抛出的这个 rejection 要是没人接,会一路冒到根、整棵树被卸载 —— 用户看到的 + * 是一片白屏,而且他手上的壳还是缓存的旧版,刷新也不一定自己好。 + * 所以这里做两件事:① chunk 加载失败先自动重刷一次(只一次,避免刷新循环); + * ② 真兜住了就给出带说明的兜底页,而不是 console 里一行红字。 + * + * React 19 至今只有 class 组件能当错误边界,所以这是全仓唯一的 class。 + * 用法:包在 外面,并用 pathname 当 key —— 换页时边界自动复位, + * 不需要额外的「清除错误」状态。 + */ +import { Component, type ErrorInfo, type ReactNode } from 'react' +import { Button, LineHint, Notice, Panel, PanelHead } from '../components/ui' + +/** 自动重刷只允许发生一次:记时间戳而不是布尔值,隔一阵子的问题还能再自愈一回 */ +const RELOAD_KEY = 'nex.chunk.reload.at' +const RELOAD_WINDOW_MS = 30_000 + +/** 各家浏览器对「动态 import 失败」的措辞不一样,统一按语义匹配 */ +const CHUNK_FAILURE = /dynamically imported module|importing a module script failed|error loading dynamically|failed to fetch/i + +export function isChunkLoadFailure(error: Error | null): boolean { + return !!error && CHUNK_FAILURE.test(`${error.name} ${error.message}`) +} + +/** 抢这一次重刷机会;隐私模式下 sessionStorage 会抛,那种时候宁可放它过去。 */ +function claimReload(): boolean { + const now = Date.now() + try { + const last = Number(sessionStorage.getItem(RELOAD_KEY) || 0) + if (last && now - last < RELOAD_WINDOW_MS) return false + sessionStorage.setItem(RELOAD_KEY, String(now)) + return true + } catch { + return true + } +} + +type Props = { children: ReactNode } +type State = { error: Error | null } + +export default class ErrorBoundary extends Component { + state: State = { error: null } + + static getDerivedStateFromError(error: Error): State { + return { error } + } + + componentDidCatch(error: Error, info: ErrorInfo) { + // 堆栈留在 console:兜底页只给人话,把 componentStack 摊给用户看没有意义 + console.error('[nex] 页面渲染失败', error, info.componentStack) + if (isChunkLoadFailure(error) && claimReload()) window.location.reload() + } + + render() { + const { error } = this.state + if (!error) return this.props.children + const chunk = isChunkLoadFailure(error) + return ( + + + {chunk ? '分包加载失败' : '渲染异常'}:{error.message || String(error)} +
+ + +
+ 兜底页由 ErrorBoundary 渲染;具体堆栈在浏览器控制台的 [nex] 页面渲染失败。 +
+ ) + } +} diff --git a/frontend/src/app/layout/AppBar.tsx b/frontend/src/app/layout/AppBar.tsx index ed33c44..d4842e8 100644 --- a/frontend/src/app/layout/AppBar.tsx +++ b/frontend/src/app/layout/AppBar.tsx @@ -38,7 +38,7 @@ export function AppBar({ projectId }: { projectId: string }) { {projectId && }
- + 手册