前端统一收尾:图文手册从 public/help.html 搬成站内 React+Tailwind 页面 /help,SPA 深链回落与未知接口 404 拆成纯函数补自检,新增 ErrorBoundary 兜住分包加载失败

main
mula.liu 2026-11-01 19:25:47 +08:00
parent e8e5a1cd2b
commit 20e8f19eca
13 changed files with 1000 additions and 976 deletions

View File

@ -3,7 +3,7 @@
面向 AI 长视频创作的本地工作台:**人物与声音资产库 → 分镜与脚本管理 → 视频模型调度中心 → 长视频合成引擎**,
底层由统一任务编排(队列 / 重试 / 断点续跑 / 并发限流)与项目数据库支撑,完整实现业务流程图的 12 个节点。
> 📖 **[打开图文使用手册](frontend/public/help.html)**(服务启动后也可访问 <http://127.0.0.1:5173/help.html>)
> 📖 **[图文使用手册](frontend/src/pages/Help.tsx)** —— 已搬进站内:启动后访问 <http://127.0.0.1:5173/help>,或点工作台顶栏的「手册」
>
> 手册包含模型管理中心、资产独立生成与镜头关联、分镜检查器、调度、质检、时间线和导出流程的实际截图。
>
@ -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. 边界与说明

View File

@ -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)

View File

@ -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("<!doctype html><title>spa</title>", 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"

View File

@ -58,11 +58,13 @@
| `.linehint` | `<LineHint>`(成行告警);空内容不渲染的用 `<Notice>` / `<ErrorText>` | `ui/Panel.tsx` · `ui/Page.tsx` |
| `.drawer` `.drawer-backdrop` `.drawer-x` `.drawer-actions` | `<Drawer title sub eyebrow actions width>`(`actions` 就是外壳直接子元素那一层) | `ui/Overlay.tsx` |
| 对话框 / `.modal` | `<Modal title eyebrow footer width>` | `ui/Overlay.tsx` |
| 白屏 / 整页崩了(老站没有这一层,崩了就直接白屏) | `<ErrorBoundary>` 已在 `app/App.tsx` 包住两处 `<Suspense>`,页面**不要**自己再写 try/catch 或错误页 | `app/ErrorBoundary.tsx` |
| `.small-label` + `.sect-act` | `<SectionTitle action>` / `<PanelHead right eyebrow sub>` | `ui/Panel.tsx` |
| `v-if` / `v-show` | `{cond && <X />}` / `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` · 页面类名常量 |
| 栅格降列 | `<Grid cols min oneAt steps>`——变量驱动,页面不写 `@media` | `ui/Panel.tsx` |
## 1. 控件栏(工具条 / 筛选条 / 搜索条 / 卡片动作行)
@ -273,7 +275,7 @@
- **必填星号**:`.req` 必须和标签文字在**同一个** `.lbl` 里(列方向 `label` 的文本节点与
`<b>` 会被拆成两个 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 试听」与「模型」挤在一起)。

View File

@ -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` 档位兜住 |

View File

@ -1,954 +0,0 @@
<!doctype html>
<html lang="zh-CN" data-theme="dark">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description" content="Nex Animation Studio 长视频编导平台图文使用手册">
<title>Nex Animation Studio · 使用手册</title>
<style>
:root {
color-scheme: dark;
--bg: #091016;
--bg-soft: #0f1820;
--panel: #131e27;
--panel-2: #17242e;
--line: #2a3a46;
--line-soft: #21303a;
--text: #edf3f5;
--muted: #91a1ac;
--green: #b8f35b;
--green-soft: #263c20;
--blue: #83c9f4;
--orange: #f2bd74;
--danger: #ff857c;
--radius: 14px;
--sidebar: 250px;
}
:root[data-theme="light"] {
color-scheme: light;
--bg: #f2f6fa;
--bg-soft: #e9eff5;
--panel: #ffffff;
--panel-2: #f7f9fc;
--line: #cbd6e1;
--line-soft: #dce5ee;
--text: #18232d;
--muted: #5d6d7b;
--green: #416600;
--green-soft: #edf5dd;
--blue: #176a95;
--orange: #8c5700;
--danger: #b42f29;
}
* { box-sizing: border-box; }
html { scroll-behavior: smooth; }
body {
margin: 0;
background:
radial-gradient(circle at 88% -8%, rgba(184, 243, 91, .08), transparent 34rem),
linear-gradient(180deg, #0b1219 0, var(--bg) 42rem);
color: var(--text);
font: 14px/1.75 -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC",
"Hiragino Sans GB", "Microsoft YaHei", sans-serif;
}
a { color: var(--green); text-decoration: none; }
a:hover { text-decoration: underline; }
code, kbd, pre {
font-family: "SFMono-Regular", Consolas, "Liberation Mono", Menlo, monospace;
}
code {
padding: 2px 6px;
border: 1px solid var(--line-soft);
border-radius: 5px;
background: #0b141b;
color: #cce7ad;
font-size: .9em;
}
pre {
margin: 12px 0;
padding: 15px 17px;
overflow: auto;
border: 1px solid var(--line);
border-radius: 10px;
background: #0a1218;
color: #d5e1e7;
font-size: 12px;
line-height: 1.7;
}
pre code { padding: 0; border: 0; background: none; color: inherit; }
img { display: block; max-width: 100%; }
.layout {
display: grid;
grid-template-columns: var(--sidebar) minmax(0, 1fr);
min-height: 100vh;
}
aside {
position: sticky;
top: 0;
height: 100vh;
overflow: auto;
padding: 24px 18px;
border-right: 1px solid var(--line-soft);
background: rgba(8, 15, 21, .92);
backdrop-filter: blur(16px);
}
.brand {
display: flex;
align-items: center;
gap: 11px;
margin: 0 4px 24px;
}
.brand-mark {
display: grid;
width: 42px;
height: 42px;
place-items: center;
border-radius: 11px;
background: var(--green);
color: #10170b;
font-size: 22px;
font-weight: 900;
box-shadow: 0 0 24px rgba(184, 243, 91, .18);
}
.brand b { display: block; font-size: 14px; }
.brand small {
display: block;
margin-top: 2px;
color: var(--muted);
font-size: 9px;
letter-spacing: .12em;
}
.theme-toggle {
width: 100%;
margin: -12px 0 4px;
padding: 8px 10px;
border: 1px solid var(--line);
border-radius: 8px;
background: var(--panel);
color: var(--text);
font-family: inherit;
font-size: 11px;
font-weight: 600;
line-height: 1.4;
text-align: left;
}
.theme-toggle:hover { border-color: var(--green); }
.theme-toggle:focus-visible { outline: 2px solid var(--green); outline-offset: 2px; }
.toc-title {
margin: 22px 9px 8px;
color: #6f808b;
font-size: 10px;
font-weight: 700;
letter-spacing: .16em;
text-transform: uppercase;
}
nav a {
display: flex;
align-items: center;
gap: 9px;
padding: 8px 10px;
border-radius: 8px;
color: #aab8c1;
text-decoration: none;
font-size: 12px;
}
nav a:hover { background: #121e27; color: var(--text); text-decoration: none; }
nav a::before { content: "›"; color: #62737f; }
.side-links {
display: grid;
gap: 7px;
margin-top: 24px;
padding-top: 18px;
border-top: 1px solid var(--line-soft);
}
.side-links a {
padding: 9px 10px;
border: 1px solid var(--line);
border-radius: 8px;
background: #111c24;
font-size: 11px;
}
.side-links a:hover { border-color: #657f3e; text-decoration: none; }
main {
width: min(1200px, 100%);
padding: 42px clamp(24px, 5vw, 72px) 90px;
}
.hero {
position: relative;
overflow: hidden;
padding: 36px 38px;
border: 1px solid #33462e;
border-radius: 20px;
background:
radial-gradient(circle at 82% 10%, rgba(184, 243, 91, .16), transparent 21rem),
linear-gradient(130deg, #142019, #111b23 64%);
}
.hero::after {
position: absolute;
right: 26px;
bottom: -58px;
color: rgba(184, 243, 91, .05);
content: "N";
font-size: 250px;
font-weight: 900;
line-height: 1;
pointer-events: none;
}
.eyebrow {
margin: 0 0 9px;
color: var(--green);
font-size: 10px;
font-weight: 700;
letter-spacing: .18em;
text-transform: uppercase;
}
h1, h2, h3 { line-height: 1.35; }
h1 { margin: 0; font-size: clamp(30px, 4vw, 48px); letter-spacing: -.035em; }
h2 {
margin: 0 0 14px;
font-size: 23px;
letter-spacing: -.02em;
}
h3 { margin: 24px 0 9px; font-size: 16px; }
.hero > p {
position: relative;
z-index: 1;
max-width: 760px;
margin: 14px 0 20px;
color: #b4c1c7;
font-size: 14px;
}
.pills { position: relative; z-index: 1; display: flex; flex-wrap: wrap; gap: 8px; }
.pill {
padding: 5px 10px;
border: 1px solid #40533a;
border-radius: 999px;
background: rgba(30, 46, 30, .7);
color: #cce7ad;
font-size: 10px;
}
section {
scroll-margin-top: 24px;
margin-top: 46px;
}
.section-head {
display: flex;
align-items: flex-end;
justify-content: space-between;
gap: 20px;
margin-bottom: 18px;
padding-bottom: 13px;
border-bottom: 1px solid var(--line-soft);
}
.section-head p { max-width: 620px; margin: 0; color: var(--muted); font-size: 12px; }
.step-no {
color: var(--green);
font: 11px/1 "SFMono-Regular", Menlo, monospace;
letter-spacing: .12em;
}
.grid-2, .grid-3, .grid-4 {
display: grid;
gap: 13px;
}
.grid-2 { grid-template-columns: repeat(2, minmax(0, 1fr)); }
.grid-3 { grid-template-columns: repeat(3, minmax(0, 1fr)); }
.grid-4 { grid-template-columns: repeat(4, minmax(0, 1fr)); }
.card {
padding: 17px;
border: 1px solid var(--line);
border-radius: 11px;
background: linear-gradient(180deg, rgba(23, 36, 46, .9), rgba(15, 24, 32, .9));
}
.card b { display: block; margin-bottom: 6px; font-size: 13px; }
.card p { margin: 0; color: var(--muted); font-size: 11.5px; }
.card .icon {
display: grid;
width: 30px;
height: 30px;
margin-bottom: 11px;
place-items: center;
border: 1px solid #40533a;
border-radius: 8px;
background: #20301d;
color: var(--green);
font-size: 14px;
}
.callout {
margin: 16px 0;
padding: 13px 15px;
border-left: 3px solid var(--green);
border-radius: 0 8px 8px 0;
background: #142019;
color: #b9c8bd;
font-size: 12px;
}
.callout.warn {
border-color: var(--orange);
background: #241e15;
color: #d7c5a8;
}
.callout.info {
border-color: var(--blue);
background: #121f28;
color: #b9cfdb;
}
.flow {
display: grid;
grid-template-columns: repeat(6, minmax(0, 1fr));
gap: 7px;
margin: 20px 0;
}
.flow div {
position: relative;
min-height: 74px;
padding: 11px 10px;
border: 1px solid var(--line);
border-radius: 8px;
background: var(--panel);
color: #b8c4ca;
font-size: 10.5px;
}
.flow div::after {
position: absolute;
top: 31px;
right: -8px;
color: #50626e;
content: "›";
font-size: 15px;
}
.flow div:last-child::after { content: ""; }
.flow b { display: block; margin-bottom: 4px; color: var(--text); font-size: 11px; }
ol.steps, ul.checks { margin: 12px 0; padding: 0; list-style: none; }
ol.steps { counter-reset: steps; }
ol.steps li {
position: relative;
margin: 9px 0;
padding: 9px 11px 9px 43px;
border: 1px solid var(--line-soft);
border-radius: 8px;
background: #101a22;
color: #b8c5cb;
font-size: 12px;
}
ol.steps li::before {
position: absolute;
top: 9px;
left: 11px;
display: grid;
width: 22px;
height: 22px;
place-items: center;
border-radius: 6px;
background: #24341f;
color: var(--green);
counter-increment: steps;
content: counter(steps);
font: 10px/1 Menlo, monospace;
}
ul.checks li {
padding-left: 23px;
color: #b8c5cb;
font-size: 12px;
}
ul.checks li::before { margin-left: -21px; margin-right: 8px; color: var(--green); content: "✓"; }
.screenshot {
overflow: hidden;
margin: 18px 0 24px;
border: 1px solid var(--line);
border-radius: 13px;
background: #090f14;
box-shadow: 0 18px 45px rgba(0, 0, 0, .25);
}
.screenshot a { display: block; }
.screenshot img { width: 100%; height: auto; }
.screenshot figcaption {
display: flex;
justify-content: space-between;
gap: 12px;
padding: 10px 14px;
border-top: 1px solid var(--line-soft);
color: var(--muted);
font-size: 10.5px;
}
.shot-grid {
display: grid;
grid-template-columns: repeat(2, minmax(0, 1fr));
gap: 14px;
}
.shot-grid .screenshot { margin: 0; }
.shot-grid figcaption { min-height: 50px; }
.table-wrap { overflow-x: auto; border: 1px solid var(--line); border-radius: 10px; }
table { width: 100%; border-collapse: collapse; font-size: 11.5px; }
th, td {
padding: 10px 12px;
border-bottom: 1px solid var(--line-soft);
text-align: left;
vertical-align: top;
}
th { background: #15222b; color: #a9bac4; font-size: 10px; letter-spacing: .04em; }
td { color: #b8c5cb; }
tr:last-child td { border-bottom: 0; }
kbd {
padding: 1px 5px;
border: 1px solid #53636d;
border-bottom-width: 2px;
border-radius: 4px;
background: #17232c;
font-size: 10px;
}
footer {
margin-top: 52px;
padding-top: 18px;
border-top: 1px solid var(--line-soft);
color: #71828d;
font-size: 10.5px;
}
:root[data-theme="light"] body {
background:
radial-gradient(circle at 88% -8%, rgba(65, 102, 0, .10), transparent 34rem),
linear-gradient(180deg, #f7f9fc 0, var(--bg) 42rem);
}
:root[data-theme="light"] code {
background: #f5f8f2;
color: #315500;
}
:root[data-theme="light"] pre {
background: #f8fafc;
color: #26343e;
}
:root[data-theme="light"] aside {
background: rgba(244, 247, 250, .94);
}
:root[data-theme="light"] .brand-mark {
color: #fff;
box-shadow: 0 0 24px rgba(65, 102, 0, .14);
}
:root[data-theme="light"] .toc-title { color: #6a7c89; }
:root[data-theme="light"] nav a { color: #40515e; }
:root[data-theme="light"] nav a:hover { background: #e7edf3; }
:root[data-theme="light"] nav a::before { color: #8a99a4; }
:root[data-theme="light"] .side-links a { background: #fff; }
:root[data-theme="light"] .hero {
border-color: #c8d7b0;
background:
radial-gradient(circle at 82% 10%, rgba(65, 102, 0, .12), transparent 21rem),
linear-gradient(130deg, #edf5df, #f8fafc 64%);
}
:root[data-theme="light"] .hero::after { color: rgba(65, 102, 0, .06); }
:root[data-theme="light"] .hero > p { color: #485964; }
:root[data-theme="light"] .pill {
border-color: #b6c99e;
background: #eef5e3;
color: #315500;
}
:root[data-theme="light"] .card {
background: linear-gradient(180deg, #fff, #f7f9fb);
}
:root[data-theme="light"] .card .icon {
border-color: #c3d4aa;
background: #edf5df;
}
:root[data-theme="light"] .callout {
background: #eef6e4;
color: #34422d;
}
:root[data-theme="light"] .callout.warn {
background: #fff5e7;
color: #6f4b17;
}
:root[data-theme="light"] .callout.info {
background: #ebf5fb;
color: #285068;
}
:root[data-theme="light"] .flow div {
color: #4b5c68;
}
:root[data-theme="light"] .flow div::after { color: #95a3ae; }
:root[data-theme="light"] ol.steps li,
:root[data-theme="light"] ul.checks li {
color: #475865;
}
:root[data-theme="light"] ol.steps li { background: #f7fafc; }
:root[data-theme="light"] ol.steps li::before { background: #edf5df; }
:root[data-theme="light"] .screenshot {
background: #e7edf2;
box-shadow: 0 18px 45px rgba(40, 61, 79, .12);
}
:root[data-theme="light"] th {
background: #edf2f7;
color: #43535f;
}
:root[data-theme="light"] td { color: #475865; }
:root[data-theme="light"] kbd {
border-color: #b7c2cb;
background: #f4f7fa;
}
:root[data-theme="light"] footer { color: #657581; }
@media (max-width: 980px) {
.layout { display: block; }
aside {
position: relative;
width: 100%;
height: auto;
padding: 16px 20px;
border-right: 0;
border-bottom: 1px solid var(--line-soft);
}
aside nav { display: flex; flex-wrap: wrap; gap: 4px; }
.toc-title, .side-links, .brand small { display: none; }
.brand { margin-bottom: 10px; }
.theme-toggle { width: auto; margin: 0; }
main { padding: 28px 20px 70px; }
.flow { grid-template-columns: repeat(3, minmax(0, 1fr)); }
.grid-4 { grid-template-columns: repeat(2, minmax(0, 1fr)); }
}
@media (max-width: 680px) {
.hero { padding: 27px 22px; }
.grid-2, .grid-3, .grid-4, .shot-grid { grid-template-columns: 1fr; }
.flow { grid-template-columns: repeat(2, minmax(0, 1fr)); }
.section-head { display: block; }
.section-head p { margin-top: 7px; }
.screenshot figcaption { display: block; }
}
@media print {
:root { color-scheme: light; }
body { background: #fff; color: #172027; }
aside { display: none; }
.layout { display: block; }
main { width: 100%; padding: 0; }
.hero, .card, pre, .screenshot, .table-wrap { break-inside: avoid; }
a { color: #315d00; }
}
</style>
<script>
(() => {
const key = 'nex-the'
const media = window.matchMedia('(prefers-color-scheme: light)')
const saved = (() => {
try { return localStorage.getItem(key) } catch { return null }
})()
const initial = saved === 'light' || saved === 'dark'
? saved
: (media.matches ? 'light' : 'dark')
document.documentElement.dataset.theme = initial
const sync = (mode) => {
document.documentElement.dataset.theme = mode
const button = document.getElementById('theme-toggle')
if (button) {
button.textContent = mode === 'light' ? '☀ 浅色模式' : '☾ 深色模式'
button.setAttribute('aria-label', `切换明暗主题,当前为${mode === 'light' ? '浅色' : '深色'}`)
}
}
window.addEventListener('DOMContentLoaded', () => {
sync(initial)
document.getElementById('theme-toggle')?.addEventListener('click', () => {
const next = document.documentElement.dataset.theme === 'light' ? 'dark' : 'light'
try { localStorage.setItem(key, next) } catch { /* ignore */ }
sync(next)
})
})
window.addEventListener('storage', (event) => {
if (event.key === key && (event.newValue === 'light' || event.newValue === 'dark')) {
sync(event.newValue)
}
})
})()
</script>
</head>
<body>
<div class="layout">
<aside>
<div class="brand">
<div class="brand-mark">N</div>
<div><b>长视频编导平台</b><small>NEX ANIMATION STUDIO</small></div>
</div>
<button class="theme-toggle" id="theme-toggle" type="button" aria-label="切换明暗主题">☾ 深色模式</button>
<div class="toc-title">使用手册</div>
<nav aria-label="目录">
<a href="#quick-start">快速开始</a>
<a href="#workflow">完整业务流程</a>
<a href="#models">模型管理中心</a>
<a href="#assets">资产管理</a>
<a href="#storyboard">分镜与脚本</a>
<a href="#dispatch">任务调度</a>
<a href="#review">质检与审核</a>
<a href="#timeline">时间线与导出</a>
<a href="#troubleshooting">故障排查</a>
<a href="#api">接口文档</a>
</nav>
<div class="side-links">
<a href="/">进入工作台 →</a>
<a href="/models">打开模型管理中心 →</a>
<a href="/docs" target="_blank" rel="noreferrer">查看 FastAPI 接口 →</a>
</div>
</aside>
<main>
<header class="hero">
<p class="eyebrow">NEX ANIMATION STUDIO · USER GUIDE</p>
<h1>长视频编导平台使用手册</h1>
<p>
从模型配置、资产管理、脚本导入,到分镜生成、自动质检、人工审核与长视频合成,
本手册按实际业务流程说明每个页面的用途与关键操作。所有截图均来自正在运行的系统。
</p>
<div class="pills">
<span class="pill">四类模型统一管理</span>
<span class="pill">资产独立生成与镜头关联</span>
<span class="pill">队列入队 / 重试 / 断点续跑</span>
<span class="pill">质检、时间线与完整导出</span>
</div>
</header>
<section id="quick-start">
<div class="section-head">
<div><span class="step-no">00 · GET STARTED</span><h2>快速开始</h2></div>
<p>建议先确认模型可用,再创建项目并导入分镜。单机模式下默认使用 SQLite 与进程内任务执行器。</p>
</div>
<div class="grid-3">
<article class="card">
<span class="icon">▶</span>
<b>一键启动</b>
<p>在仓库根目录执行启动脚本,脚本会自检依赖、环境变量和端口。</p>
</article>
<article class="card">
<span class="icon">◫</span>
<b>配置模型</b>
<p>在模型管理中心检查大模型、视频、图像、声音四类模型的连接状态与默认项。</p>
</article>
<article class="card">
<span class="icon">◎</span>
<b>进入项目</b>
<p>从项目总览创建或打开项目,按左侧业务模块依次推进。</p>
</article>
</div>
<div class="callout info">
<b>界面导航:</b>顶部应用栏左侧是平台标识;正中间是<b>流程进度控制台</b>——项目名、项目状态、
12 个业务节点轨道(按完成 / 进行中 / 需处理 / 待处理着色;进行中的那一段更高、带光晕并与需处理一起呼吸闪烁,
扫一眼就知道卡在哪一段)、
流程进度(已完成节点 ÷ 全部节点)与当前节点,点一下控制台就回到流程概览;12 个节点全部走完时这里改说
<b>「全部 12 个节点已完成」</b>,不会在「已交付」旁边再挂一个假的当前节点。这条口径由
<code>frontend/src/pipeline.ts</code> 统一定义,侧栏项目副标题、项目页头标签、流程进度条
(含总览右侧的示例流程)、项目设置面板的状态标签(流程推进中 / <b>流程已完成</b> / 已归档)、
「下一步建议」抬头、项目总览表格与卡片的<b>「流程节点」列</b>、资产库「引入项目」下拉的副标题
全部复用它,任何一处都不会各说各话。右侧固定放使用手册、显示模式(深色 / 浅色,
<code>⌘/Ctrl+Shift+L</code> 随时切换)和账号胶囊;点开账号胶囊即是二级菜单——我的账号、用户管理、退出登录都在这里。
接口文档不再占用顶栏入口,需要时直接访问 <a href="/docs" target="_blank" rel="noreferrer"><code>/docs</code></a>。
左侧栏只保留模块导航:全局三个模块 + 当前项目的七个业务节点。页面底部不再常驻系统信息。
</div>
<figure class="screenshot">
<a href="/help/overview.png" target="_blank" rel="noreferrer" aria-label="查看项目总览页截图">
<img src="/help/overview.png" alt="项目总览页:顶部应用栏(平台标识、居中的流程进度控制台、手册 / 显示模式 / 账号胶囊)与左侧模块导航">
</a>
<figcaption><span>项目内页面:顶栏居中的进度控制台常驻,轨道颜色、流程进度与当前节点跟着轮询实时更新;右侧手册 / 显示模式 / 账号胶囊固定。</span><span>点击图片查看原图 ↗</span></figcaption>
</figure>
<div class="callout">
<b>环境自检:</b>执行器、ffmpeg、字幕烧录 / 内嵌、数据库、调度守护这些后台能力不再常驻页面,
只有真的出问题时才会在账号菜单里出现一行警告;需要随时核对,直接打开
<a href="/health" target="_blank" rel="noreferrer"><code>/health</code></a> 与
<a href="/api/meta" target="_blank" rel="noreferrer"><code>/api/meta</code></a>。
</div>
<pre><code>./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</code></pre>
<div class="callout info">
如果页面能打开但页面顶部出现「后端连接异常」,先运行 <code>./scripts/dev.sh status</code>,
再检查 <code>http://127.0.0.1:8000/health</code> 是否返回 JSON。
</div>
</section>
<section id="workflow">
<div class="section-head">
<div><span class="step-no">01 · PIPELINE</span><h2>完整业务流程</h2></div>
<p>项目的流程条会实时汇总镜头、任务、质检、时间线与导出状态。任何一步跳过或失败,都会在上方流程条中暴露。</p>
</div>
<div class="flow">
<div><b>① 创建项目</b>设定片长、画幅与风格</div>
<div><b>② 导入分镜</b>脚本与关键帧一起入库</div>
<div><b>③ 绑定资产</b>人物、场景、声线关联镜头</div>
<div><b>④ 生成任务</b>按镜头生成任务清单</div>
<div><b>⑤ 预检调度</b>检查素材、参数与容量</div>
<div><b>⑥ 调用模型</b>执行视频和配音生成</div>
<div><b>⑦ 保存产物</b>下载并登记新素材版本</div>
<div><b>⑧ 自动质检</b>解码、时长、分辨率、帧率等</div>
<div><b>⑨ 人工审核</b>合格通过或带修改意见重做</div>
<div><b>⑩ 时间线合成</b>裁剪、转场、字幕、配音、BGM</div>
<div><b>⑪ 出片预检</b>检查缺片、字幕与音轨</div>
<div><b>⑫ 导出交付</b>生成成片并记录成本与校验和</div>
</div>
<div class="callout">
推荐顺序:<b>模型管理中心 → 资产管理 → 分镜与脚本 → 任务调度中心 → 质检与审核 → 时间线合成 → 导出与成本</b>。
资产可以先独立生成,再在分镜的“资产绑定”页中关联,不要求先有镜头的生成产物。
</div>
</section>
<section id="models">
<div class="section-head">
<div><span class="step-no">02 · MODEL OPERATIONS</span><h2>模型管理中心</h2></div>
<p>统一管理机构可调用的四类能力。资产独立生成和分镜任务都会读取这里的默认模型与供应能力。</p>
</div>
<div class="grid-4">
<article class="card"><span class="icon">✦</span><b>大模型</b><p>剧本拆解、编导指令与提示词补全,修正跨镜头一致性。</p></article>
<article class="card"><span class="icon">▶</span><b>视频模型</b><p>文生视频、图生视频、首尾帧;配置并发、RPM、时长与分辨率。</p></article>
<article class="card"><span class="icon">▧</span><b>图像模型</b><p>人物定妆图、三视图、服装、表情以及场景参考图。</p></article>
<article class="card"><span class="icon">◉</span><b>声音模型</b><p>TTS 配音与声线试听样本,可绑定到人物和镜头台词。</p></article>
</div>
<figure class="screenshot">
<a href="/help/model-center.png" target="_blank" rel="noreferrer" aria-label="查看模型管理中心截图">
<img src="/help/model-center.png" alt="模型管理中心:大模型、视频、图像、声音四类模型统一管理">
</a>
<figcaption><span>模型管理中心:四类模型分类、默认模型、连接状态、容量与价格。</span><span>点击图片查看原图 ↗</span></figcaption>
</figure>
<h3>常用操作</h3>
<ol class="steps">
<li>点击右上角“登记模型”,填写 Provider、Model、媒体类型与适配器;媒体类型必须与适配器匹配。</li>
<li>为大模型、视频、图像、声音分别设置一个启用中的默认模型,资产页会自动选中对应默认项。</li>
<li>展开模型卡片编辑并发、RPM、时长、分辨率、价格和默认参数。</li>
<li>点击「检测连接」检查适配器与外部服务是否可达;不可用时先修复连接再执行生成。</li>
<li>在故障演练中使用可控失败率验证重试与断点续跑,验证完成后恢复为正常配置。</li>
</ol>
<div class="callout warn">
<b>提示:</b>切换默认模型只影响后续任务,不会重写已经完成的任务记录。历史任务仍保留当时的 Provider、Model、参数和产物版本。
</div>
</section>
<section id="assets">
<div class="section-head">
<div><span class="step-no">03 · ASSET MANAGEMENT</span><h2>资产管理</h2></div>
<p>集中维护人物、场景、声线与项目素材。资产可以独立调用模型生成,也可在分镜中绑定并参与后续视频生成。</p>
</div>
<div class="grid-4">
<article class="card"><b>人物</b><p>外观、性格、一致性提示词、默认声线;定妆图 / 三视图 / 服装 / 表情。</p></article>
<article class="card"><b>场景</b><p>描述、光线、时间、色调;场景图可作为镜头参考与关键帧来源。</p></article>
<article class="card"><b>声线</b><p>Provider voice_id、语言、性别、语速、效果与试听样本。</p></article>
<article class="card"><b>项目素材</b><p>BGM、音效、通用参考图与视频,可挂到时间线音轨。</p></article>
</div>
<figure class="screenshot">
<a href="/help/asset-management.png" target="_blank" rel="noreferrer" aria-label="查看资产管理人物页截图">
<img src="/help/asset-management.png" alt="资产管理人物页:独立生成、默认模型、版本与被镜头使用情况">
</a>
<figcaption><span>人物资产:默认图像 / 大模型已自动选中,并显示镜头使用位置与模型生成版本。</span><span>点击图片查看原图 ↗</span></figcaption>
</figure>
<h3>独立生成人物或场景资产</h3>
<ol class="steps">
<li>打开“资产管理”,选择人物或场景页签。</li>
<li>在对应的 AI 生成卡片中选择图像模型和生成类型;需要文本补全时选择大模型。</li>
<li>生成描述可以留空,系统会使用人物外观、场景描述、光线与风格设定自动组装提示词。</li>
<li>点击「生成母版图像」(人物定妆图 / 三视图 / 场景图)。完成后资产自动登记新版本,并显示 Provider / Model。</li>
<li>点击“AI 补全一致性提示词”,检查建议内容后选择“采用”,写回人物或场景设定。</li>
</ol>
<div class="callout">
<b>与分镜的关联:</b>每个资产卡片显示“被 N 个镜头使用”。点击镜头链接会进入分镜页并自动选中对应镜头;
在分镜右侧“资产绑定”页可调整人物、场景和声音。生成视频时,有效的参考资产会进入模型请求。
</div>
<figure class="screenshot">
<a href="/help/scene-assets.png" target="_blank" rel="noreferrer" aria-label="查看场景资产页截图">
<img src="/help/scene-assets.png" alt="场景资产页:场景独立生成、模型选择、镜头使用关系和场景参考图">
</a>
<figcaption><span>场景资产:同样可以选择图像 / 大模型独立生成,结果自动登记版本并显示关联镜头。</span><span>点击图片查看原图 ↗</span></figcaption>
</figure>
<figure class="screenshot">
<a href="/help/voice-assets.png" target="_blank" rel="noreferrer" aria-label="查看声音资产页截图">
<img src="/help/voice-assets.png" alt="声音资产页:TTS 模型选择、AI 试听生成和可播放音色样本">
</a>
<figcaption><span>声音资产:选择声音模型生成试听样本,音频版本可直接播放;下方展示绑定的镜头。</span><span>点击图片查看原图 ↗</span></figcaption>
</figure>
<h3>声音资产</h3>
<ul class="checks">
<li>选择可用声音模型,填写试听文本后点击「生成试听样本」。</li>
<li>生成完成会得到带时长、Provider、Model 与任务 ID 的新版本音频。</li>
<li>macOS 系统语音可使用 Tingting、Meijia、Fred 等 voice_id;外星角色可选择降调与金属共振效果。</li>
<li>人物默认声线绑定后,镜头台词可自动进入 TTS 配音与时间线混音流程。</li>
</ul>
</section>
<section id="storyboard">
<div class="section-head">
<div><span class="step-no">04 · STORYBOARD</span><h2>分镜与脚本</h2></div>
<p>分镜工作台:顶栏看总量与预检指标,看板或分镜表浏览镜头序列,右侧常驻检查器按“镜头 / 资产 / 提示词 / 产物”组织细节。</p>
</div>
<figure class="screenshot">
<a href="/help/storyboard.png" target="_blank" rel="noreferrer" aria-label="查看分镜工作台截图">
<img src="/help/storyboard.png" alt="分镜工作台:指标条、搜索筛选、批量操作与网格看板">
</a>
<figcaption><span>分镜工作台:镜头数 / 计划时长 / 已合格 / 有阻塞一眼可见,卡片显示缩略图、景别运镜、QC 分、绑定与逐镜预检问题。</span><span>点击图片查看原图 ↗</span></figcaption>
</figure>
<div class="grid-3">
<article class="card"><b>导入脚本</b><p>支持 Markdown、CSV、TSV、JSON 与纯文本,可先预览再落库。</p></article>
<article class="card"><b>关键帧匹配</b><p>图片可按镜号自动匹配,也支持 ZIP 批量导入。</p></article>
<article class="card"><b>资产绑定</b><p>人物、场景和声音可逐镜头关联,并即时看到使用关系。</p></article>
</div>
<figure class="screenshot">
<a href="/help/storyboard-inspector.png" target="_blank" rel="noreferrer" aria-label="查看分镜检查器截图">
<img src="/help/storyboard-inspector.png" alt="分镜工作台:选中镜头后右侧常驻检查器的镜头页签">
</a>
<figcaption><span>选中任一镜头后检查器常驻右侧并与看板并排:镜头参数、资产绑定、提示词版本、产物与质检各占一个页签,改动未保存会有「未保存」标记。</span><span>点击图片查看原图 ↗</span></figcaption>
</figure>
<h3>推荐操作</h3>
<ol class="steps">
<li>点击“导入脚本 / 关键帧”,粘贴脚本并上传关键帧;先用“导入预演”确认镜头数量与图片匹配,再正式导入。</li>
<li>用搜索框和状态 / 模式 / 排序筛选定位镜头,或点“仅看阻塞”“仅看缺关键帧”直接清理预检问题。</li>
<li>拖动卡片即可改镜序(分镜表视图也可拖行或用 ↑↓);勾选多个镜头后可批量复制、移到最前、统一改参数或删除。</li>
<li>选中镜头后在检查器编辑参数与绑定;提示词页可切换“自动组装 / 人工覆盖”,并回填任意历史版本。</li>
<li>卡片上的“生成”“审核”带 <code>?shot=镜头ID</code> 深链,跳到调度中心或审核页时会自动选中同一镜头。</li>
<li>需要交给编剧或外部工具时,用右上角导出 Markdown / CSV / JSON,导出的 Markdown 可以直接再导回来。</li>
</ol>
<div class="callout">
<b>快捷键:</b><code>J</code> / <code>K</code> 或 <code>↑</code><code>↓</code> 切换镜头,<code>X</code> 勾选当前镜头,
<code>⌘S</code> 保存检查器改动,<code>Esc</code> 关闭检查器或导入面板。首屏只拉轻量看板数据,
几十上百镜也不会拖慢页面。
</div>
</section>
<section id="dispatch">
<div class="section-head">
<div><span class="step-no">05 · DISPATCH</span><h2>任务调度</h2></div>
<p>任务清单先解释执行原因,再按模型容量和限流派发。已完成镜头会被跳过,避免重复消耗真实模型时长。</p>
</div>
<figure class="screenshot">
<a href="/help/dispatch.png" target="_blank" rel="noreferrer" aria-label="查看任务调度中心截图">
<img src="/help/dispatch.png" alt="任务调度中心:分镜任务清单、预检结果、执行开关和异常处理">
</a>
<figcaption><span>调度中心:任务状态、Provider / Model、预计成本、入队选项与断点续跑入口。</span><span>点击图片查看原图 ↗</span></figcaption>
</figure>
<div class="grid-2">
<article class="card">
<b>入队前</b>
<p>检查预检阻塞项、镜头状态、模型容量与预计成本。默认只入队预检通过的镜头,缺素材或缺参数的镜头会被跳过,需要时再勾选「放行预检未通过的镜头」。</p>
</article>
<article class="card">
<b>执行中</b>
<p>查看运行任务、心跳、尝试次数与进度。失败任务会按配置重试,超时任务可从中断点续跑。</p>
</article>
</div>
<ol class="steps">
<li>确认任务清单中的 Provider / Model 与预期一致。</li>
<li>按需开启「入队时一并排配音任务」「放行预检未通过的镜头」「强制重建任务(忽略幂等)」,并设置优先级与单次派发上限。</li>
<li>点击「入队所选 / 全部待生成」。勾选「派发后同步排空」会一直等到任务跑完再返回;不勾选时任务在后台执行,页面自动刷新进度。</li>
<li>失败时查看错误码与错误历史;修复后使用“重排全部失败任务”或“断点续跑”。</li>
<li>已完成且仍需强制重做的镜头,勾选“强制重建任务”后再派发。</li>
</ol>
</section>
<section id="review">
<div class="section-head">
<div><span class="step-no">06 · QUALITY & REVIEW</span><h2>质检与审核</h2></div>
<p>先自动检查文件完整性、时长、分辨率、帧率等指标,再由人工确认画面和声音。驳回可携带修改意见重新生成。</p>
</div>
<figure class="screenshot">
<a href="/help/review.png" target="_blank" rel="noreferrer" aria-label="查看质检与审核页面截图">
<img src="/help/review.png" alt="质检与审核页面:自动质检清单、镜头预览、检查项得分和人工审核">
</a>
<figcaption><span>质检与审核:自动质检清单、视频预览、逐项指标解释和人工通过 / 驳回操作。</span><span>点击图片查看原图 ↗</span></figcaption>
</figure>
<ul class="checks">
<li>在自动质检清单中按镜头检查得分为 100 的项,确认没有解码、时长或分辨率异常。</li>
<li>播放右侧产物,检查人物一致性、动作、构图、音轨和字幕风险。</li>
<li>合格后填写审核人并提交;不合格时填写修改意见与新的提示词,选择是否立即重新生成。</li>
<li>驳回镜头会回到任务计划状态,再次进入调度中心,不会覆盖之前的历史产物。</li>
<li>镜头多时用顶部“批量放行质检合格镜头”一次性放过全部质检通过且待审核的镜头,只手工盯有问题的几个。</li>
<li>从分镜工作台点“审核”跳过来时带 <code>?shot=镜头ID</code>,右侧直接定位到该镜头。</li>
</ul>
</section>
<section id="timeline">
<div class="section-head">
<div><span class="step-no">07 · COMPOSE & DELIVER</span><h2>时间线与导出</h2></div>
<p>时间线只收集已审核合格产物,统一处理片段顺序、转场、字幕、配音、BGM、响度与最终编码。</p>
</div>
<div class="shot-grid">
<figure class="screenshot">
<a href="/help/timeline.png" target="_blank" rel="noreferrer" aria-label="查看时间线合成页面截图">
<img src="/help/timeline.png" alt="时间线合成:片段、转场、字幕、音轨和交付预检">
</a>
<figcaption><span>时间线:片段与转场、字幕、音轨和交付预检。</span><span>查看原图 ↗</span></figcaption>
</figure>
<figure class="screenshot">
<a href="/help/delivery.png" target="_blank" rel="noreferrer" aria-label="查看项目交付页面截图">
<img src="/help/delivery.png" alt="导出与成本:出片预设、成本台账、成片记录与下载">
</a>
<figcaption><span>交付:选择预设、检查成本、生成并下载成片。</span><span>查看原图 ↗</span></figcaption>
</figure>
</div>
<h3>时间线合成</h3>
<ol class="steps">
<li>点击“构建 / 重建时间线”,系统自动收集已审核合格镜头。</li>
<li>调整片段顺序、时长、入点、转场和音量;补齐缺失字幕与配音。</li>
<li>检查交付预检报告,确保缺片、字幕、声轨和总时长均为通过状态。</li>
<li>如使用外挂字幕,保持字幕模式为 SRT;当前 ffmpeg 未启用烧录滤镜时会明确降级。</li>
</ol>
<h3>导出与成本</h3>
<ul class="checks">
<li>选择横屏或竖屏的 720p 试片、1080p 投放、高质量 1080p 或超清 4K 预设,可多选依次入队。</li>
<li>确认成片名称、字幕策略与优先级,然后点击“开始合成导出”。</li>
<li>在成片记录中检查分辨率、帧率、时长、大小、校验和与下载地址。</li>
<li>成本台账按 Provider、Model 汇总实际费用;mock 模型的单价为 0。</li>
</ul>
</section>
<section id="troubleshooting">
<div class="section-head">
<div><span class="step-no">08 · TROUBLESHOOTING</span><h2>故障排查</h2></div>
<p>先看页面错误和任务错误历史,再看后端健康状态与日志;不要在未确认原因时反复重烧真实模型。</p>
</div>
<div class="table-wrap">
<table>
<thead><tr><th>现象</th><th>优先检查</th><th>处理方式</th></tr></thead>
<tbody>
<tr><td>前后端服务未启动</td><td><code>./scripts/dev.sh status</code></td><td>运行 <code>./scripts/dev.sh restart --no-install</code>,再查看 <code>.local/logs/</code>。</td></tr>
<tr><td>启动时报 unbound variable</td><td>脚本是否将变量写作 <code>${VAR}</code></td><td>Bash 3.2 下变量紧邻中文或全角符号时必须使用花括号形式。</td></tr>
<tr><td>模型下拉框为空</td><td>模型管理中心是否启用对应媒体类型</td><td>启用并设置默认模型;资产页加载完成后会自动同步默认值。</td></tr>
<tr><td>资产显示被 0 个镜头使用</td><td>分镜“资产绑定”页</td><td>逐镜头绑定人物、场景或声音;预检会提示缺失绑定。</td></tr>
<tr><td>派发被拒或镜头被跳过</td><td>预检问题与镜头状态</td><td>优先补齐阻塞项;只有确认需要重做时才开启强制重建。</td></tr>
<tr><td>任务超时或进程重启</td><td>任务心跳和检查点</td><td>使用断点续跑,保留已成功镜头,避免重复调用模型。</td></tr>
<tr><td>时间线为空</td><td>是否存在已审核合格镜头</td><td>先完成质检与人工审核,再重建时间线。</td></tr>
<tr><td>字幕烧录失败</td><td><code>/health</code> 中的 <code>ffmpeg_capabilities.subtitle_burn</code></td><td>改为外挂 SRT,或安装带 libass / subtitles 滤镜的 ffmpeg。</td></tr>
<tr><td>真实模型连接不可达</td><td>模型中心的探测结果(含中文结论)</td><td>按探测提示确认那台机器上的 ComfyUI 进程与端口是否还在。<b>平台直连 ComfyUI,不走系统代理</b>,因此本机开了 Clash / VPN 也不影响出片,排查时不必检查代理设置。</td></tr>
<tr><td>点录音没有弹授权框,或提示打不开麦克风</td><td>页面会先体检麦克风:设备数、系统权限、当前地址是否 https</td><td>按提示逐条处理:系统设置 → 隐私与安全性 → 麦克风里放开浏览器;地址栏左侧图标把麦克风改回「允许」;用 IP + http 从别的机器访问时浏览器根本没有录音接口,请改用 <code>localhost</code> 或 https。急着出片可先在外部录好再走「上传文件」。</td></tr>
<tr><td>点了「开始录制」一直转圈,系统授权框始终没出现(macOS)</td><td>macOS 的麦克风授权框<b>出现在屏幕左下角</b>(不是窗口正中),很容易被忽略;一旦误点「不允许」,Chrome 会记住结论,之后<b>不再弹框</b>,页面只会收到一句 <code>Requested device not found</code></td><td>录音面板顶部有一行麦克风自检:<b>✓ 麦克风已就绪:设备名</b> 表示可以直接录;⚠ 时按下面的说明逐条走,需要重置系统权限时点<b>「复制修复命令」</b>,粘到终端执行 <code>tccutil reset Microphone com.google.Chrome</code> 后回到面板点「重新检测」即可,<b>不用重启浏览器</b>。换了麦克风或改了系统权限也不用刷新:面板会自动重新体检。</td></tr>
<tr><td>录到一半录音面板自己消失了</td><td>是否正好切走了类型 / 筛选(母版列表换了内容,卡片上的面板随之关闭)</td><td>录音期间平台的自动刷新会主动让路(不重建列表),录完或关掉面板后下一轮自动恢复;切换类型、翻页会离开当前母版,请先停止录制并保存这段录音。</td></tr>
</tbody>
</table>
</div>
<pre><code># 快速收集运行时信息
./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</code></pre>
</section>
<section id="api">
<div class="section-head">
<div><span class="step-no">09 · API REFERENCE</span><h2>接口文档</h2></div>
<p>所有前后端操作都通过同一组 REST 接口完成,便于脚本化、自动测试和后续接入其他客户端。</p>
</div>
<div class="grid-3">
<article class="card"><b>Swagger UI</b><p><a href="/docs" target="_blank" rel="noreferrer">/docs</a>:浏览并直接调用全部接口。</p></article>
<article class="card"><b>OpenAPI JSON</b><p><a href="/openapi.json" target="_blank" rel="noreferrer">/openapi.json</a>:供代码生成与自动化测试使用。</p></article>
<article class="card"><b>健康检查</b><p><a href="/health" target="_blank" rel="noreferrer">/health</a>:执行器、数据库、ffmpeg、守护调度器与模型数量。</p></article>
</div>
<div class="callout info">
常用接口包括 <code>GET /api/providers</code>、<code>POST /api/projects/{id}/assets/generate</code>、
<code>POST /api/projects/{id}/assets/text-assist</code>、<code>GET /api/projects/{id}/assets/usage</code>、
<code>POST /api/projects/{id}/dispatch</code> 与 <code>POST /api/projects/{id}/compose</code>。
</div>
</section>
<footer>
Nex Animation Studio · 本手册随平台代码维护。截图来自项目《铁血战士的猎人晚宴》的实际运行状态。
</footer>
</main>
</div>
</body>
</html>

View File

@ -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 <Navigate to="/" replace />
return (
<div className="min-h-screen">
<Suspense fallback={<Loading>页面加载中</Loading>}>
<Outlet />
</Suspense>
<ErrorBoundary key={location.pathname}>
<Suspense fallback={<Loading>页面加载中</Loading>}>
<Outlet />
</Suspense>
</ErrorBoundary>
<MediaLightbox />
</div>
)
@ -128,9 +131,12 @@ export default function App() {
<AuthGate admin={handle.admin}>
{/* 换顶级路由时整块重挂:避免上一个页面的本地状态(筛选条件、抽屉)
串到下一个页面。同一项目内切页签时顶级路由没变,不会重挂。 */}
<Suspense fallback={<Loading>页面加载中</Loading>}>
<Outlet key={matches[1]?.id || location.pathname} />
</Suspense>
{/* 边界在 Suspense 外层:换页时随 pathname 复位(见 ErrorBoundary 注释) */}
<ErrorBoundary key={location.pathname}>
<Suspense fallback={<Loading>页面加载中</Loading>}>
<Outlet key={matches[1]?.id || location.pathname} />
</Suspense>
</ErrorBoundary>
</AuthGate>
</main>
<MediaLightbox />

View File

@ -0,0 +1,81 @@
/**
* 渲染期兜底 + 路由分包加载失败自愈。
*
* 为什么必须有它:页面全部改成路由级懒加载之后,「点一个页面」多了一次网络请求。
* 重新部署过一次,浏览器里那份 index.html 还在引用被替换掉的旧哈希 chunk,
* 点进去就是 `Failed to fetch dynamically imported module`;React.lazy 在渲染期
* 抛出的这个 rejection 要是没人接,会一路冒到根、整棵树被卸载 —— 用户看到的
* 是一片白屏,而且他手上的壳还是缓存的旧版,刷新也不一定自己好。
* 所以这里做两件事:① chunk 加载失败先自动重刷一次(只一次,避免刷新循环);
* ② 真兜住了就给出带说明的兜底页,而不是 console 里一行红字。
*
* React 19 至今只有 class 组件能当错误边界,所以这是全仓唯一的 class。
* 用法:包在 <Suspense> 外面,并用 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<Props, State> {
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 (
<Panel className="mt-3">
<PanelHead
eyebrow="页面渲染中断"
title={chunk ? '这一页的代码没拿到' : '这一页没能画出来'}
sub={chunk
? '多半是服务端刚重新部署过,浏览器还在用旧版页面清单。重新加载通常就好了;一直不好就把本页地址发我。'
: '页面在渲染时抛了异常。先重新加载一次;如果每次进来都这样,请附上下面这行提示。'}
/>
<Notice danger>{chunk ? '分包加载失败' : '渲染异常'}:{error.message || String(error)}</Notice>
<div className="flex items-center gap-2 flex-wrap min-w-0">
<Button variant="primary" onClick={() => window.location.reload()}>重新加载本页</Button>
<Button variant="outline" onClick={() => { window.location.href = '/' }}>回到项目列表</Button>
</div>
<LineHint className="mt-3">兜底页由 ErrorBoundary 渲染;具体堆栈在浏览器控制台的 [nex] 页面渲染失败。</LineHint>
</Panel>
)
}
}

View File

@ -38,7 +38,7 @@ export function AppBar({ projectId }: { projectId: string }) {
{projectId && <PipelineConsole projectId={projectId} />}
<div className="flex flex-[1_1_0] items-center justify-end gap-[7px]">
<a className={cn(TOOL)} href="/help.html" target="_blank" rel="noopener" title="使用手册 · 全流程操作截图(新窗口打开)">
<a className={cn(TOOL)} href="/help" target="_blank" rel="noopener" title="使用手册 · 全流程操作截图(新窗口打开)">
<i aria-hidden="true" className="text-ui not-italic text-muted group-hover:text-accent">🛈</i><span>手册</span>
</a>
<button type="button" className={cn(TOOL, 'cursor-pointer')} onClick={toggleTheme}

View File

@ -1,7 +1,7 @@
/**
* 路由表。
*
* 路由级懒加载:以前所有视图静态 import,打开「平台资产库」也要先把
* 路由级懒加载:Vue 老站所有视图静态 import,打开「平台资产库」也要先把
* 分镜 / 资产 / 模型中心一整套模块下载并编译完(开发模式首屏 77 个请求 / 4.7MB,
* 其中 1.9MB 是这次根本用不到的页面)。现在只保留入口页(项目列表)同步加载,
* 其余按路由切分:点进哪个页面才拉哪个页面的 chunk,构建产物也跟着按路由分包。
@ -28,6 +28,7 @@ const loadDelivery = () => import('../pages/project/Delivery')
const loadLogin = () => import('../pages/Login')
const loadAccount = () => import('../pages/Account')
const loadUserAdmin = () => import('../pages/UserAdmin')
const loadHelp = () => import('../pages/Help')
const AssetLibrary = lazy(loadAssetLibrary)
const ModelCenter = lazy(loadModelCenter)
@ -42,6 +43,7 @@ const Delivery = lazy(loadDelivery)
const Login = lazy(loadLogin)
const Account = lazy(loadAccount)
const UserAdmin = lazy(loadUserAdmin)
const Help = lazy(loadHelp)
/** 挂在每条路由上的元信息:App 用 useMatches() 读取 */
export type RouteHandle = { title?: string; public?: boolean; admin?: boolean }
@ -74,6 +76,9 @@ export const router = createBrowserRouter([
{ path: 'login', element: <Login />, handle: withHandle('登录', { public: true }) },
{ path: 'account', element: <Account />, handle: withHandle('我的账号') },
{ path: 'users', element: <UserAdmin />, handle: withHandle('用户管理', { admin: true }) },
// 图文手册是站内页面(旧 /help.html 独立静态页已删),新窗口打开不影响当前工作台
{ path: 'help', element: <Help />, handle: withHandle('使用手册') },
{ path: 'help.html', element: <Navigate to="/help" replace /> },
{ path: '*', element: <Navigate to="/" replace /> }
]
}

View File

@ -0,0 +1,748 @@
/**
* 图文使用手册(原 `frontend/public/help.html`,随「前端统一 React + Tailwind」搬进站内)。
*
* 为什么值得搬:那份手册自带 15 KB CSS 和一份从旧站抄来的调色板,主题开关也得
* 自己再实现一遍——它是 `frontend/` 里最后一块不是 Tailwind 的样式,也是唯一一处
* 不跟着 `data-theme` 走的界面。搬进来之后它和平台共用 `styles/tokens.css` 里的
* 尺子与颜色,深浅色、字号、圆角、断点全部自动跟着主站走。
*
* · 目录(`TOC`)由正文的 `<section id>` 生成,加一节不用记得改第二处;
* 锚点滚动自己实现(React Router 只改 location,不会替 `#id` 滚动)。
* · 截图仍在 `frontend/public/help/`,构建后由 `/help/*.png` 直出:文件命中优先,
* 未命中才回落路由,所以图片路径和路由 `/help` 同前缀但不冲突。
* · 这些排版类是**页面私有**的(只有手册用),因此写成文件里的类名常量,
* 不占用 `components/ui/`——按 UI规范,被第二个页面用到才提上去。
*/
import { type MouseEvent } from 'react'
import { Link } from 'react-router-dom'
import { ExtLink } from '../components/ui'
/** 页面外壳:行内强调、代码、链接的皮肤统一给一次,正文不重复贴类名 */
const SHELL = 'min-w-0 [&_b]:font-semibold [&_b]:text-ink [&_a_code]:text-success [&_pre]:m-0'
const PRE = 'mt-4 overflow-x-auto rounded-block border border-line bg-sunken p-[13px] text-[11.5px] leading-[1.8] text-ink-2 font-mono'
const TOC_NAV = 'sticky top-[8px] z-[5] mb-7 flex flex-wrap items-center gap-2 rounded-block '
+ 'border border-line bg-panel p-[11px] backdrop-blur'
const TOC_LINK = 'rounded-chip border border-line-strong bg-sunken px-[10px] py-[5px] '
+ 'text-caption text-ink-2 no-underline hover:bg-hover hover:border-line-bright hover:text-ink'
const SIDE = 'mt-6 flex flex-wrap items-center gap-[9px] rounded-block border border-line bg-panel p-[13px]'
const SIDE_LABEL = 'mr-1 text-tiny font-bold uppercase tracking-[1.5px] text-muted'
/** 标签级皮肤:同一标签在手册里出现几十次,样式只在这一处定义 */
const TAG_H1 = 'text-display font-bold mt-[9px] mb-[9px] text-ink tracking-[-.03em]'
const TAG_P = 'text-body text-dim leading-[1.85] max-w-[76ch] m-0 mt-[9px]'
const TAG_SECTION = 'scroll-mt-[88px] mt-[46px] min-w-0 first:mt-0'
const TAG_H2 = 'text-lg font-bold mt-[3px] mb-0 text-ink tracking-[-.02em]'
const TAG_CODE = 'rounded-chip border border-line bg-sunken px-[5px] py-px text-[11px] text-accent-bright '
+ 'font-mono'
const TAG_A = 'text-success no-underline hover:underline'
const TAG_IMG = 'block w-full rounded-tile border border-line-strong'
const TAG_FIGCAPTION = 'flex justify-between gap-3 flex-wrap text-tiny text-faint leading-[1.75] pt-[7px] px-1 '
+ '[&>span]:min-w-0 [&>span+span]:shrink-0 [&>span+span]:text-accent'
const TAG_H3 = 'text-md font-bold mt-6 mb-[9px] text-ink'
const TAG_TABLE = 'w-full border-collapse text-label min-w-[680px]'
const TAG_TR = '[&:last-child>td]:border-b-0'
const TAG_TH = 'text-left px-3 py-[10px] bg-sunken text-faint font-bold border-b border-line-strong '
+ 'whitespace-nowrap text-tiny'
const TAG_TD = 'px-3 py-[10px] border-b border-line align-top text-ink-2 leading-[1.75] last:border-b-0'
const TAG_FOOTER = 'text-tiny text-faint mt-[52px] border-t border-line pt-[18px] leading-[1.9]'
/** 版块皮肤:卡片、网格、提示条、流程节点(一一对应旧 help.html 的 class) */
const HERO = 'relative overflow-hidden rounded-float border border-accent-line p-[26px] mb-7 shadow-raise '
+ 'bg-accent-tint min-w-0'
const EYEBROW = 'm-0 text-tiny tracking-[1.7px] font-bold text-accent uppercase'
const PILLS = 'flex items-center gap-2 flex-wrap mt-4'
const PILL = 'rounded-pill border border-line-strong bg-sunken px-[11px] py-[5px] text-caption text-ink-2'
const SECTION_HEAD = 'flex items-end justify-between gap-5 flex-wrap border-b border-line pb-[13px] mb-[18px] '
+ 'min-w-0'
const STEP_NO = 'block text-tiny tracking-[1.5px] font-bold text-accent uppercase'
const GRID_3 = 'grid gap-4 mt-4 grid-cols-3 max-mid2:grid-cols-2 max-tiny:grid-cols-1'
const CARD = 'min-w-0 rounded-block border border-line bg-card p-[15px] shadow-raise [&>b]:block '
+ '[&>b]:text-ui [&>b]:font-bold [&>b]:text-ink [&>b]:mb-[5px] [&>p]:m-0 [&>p]:text-body '
+ '[&>p]:text-dim [&>p]:leading-[1.75]'
const ICON = 'block text-md text-accent mb-1'
const CALLOUT_INFO = 'mt-4 rounded-block border p-[13px] text-label leading-[1.9] min-w-0 break-words '
+ 'border-info-line bg-info-tint text-ink-2'
const SCREENSHOT = 'mt-4 min-w-0 rounded-block border border-line bg-sunken p-[9px] overflow-hidden '
+ '[&>img]:rounded-tile [&>figcaption]:mt-[7px]'
const CALLOUT = 'mt-4 rounded-block border p-[13px] text-label leading-[1.9] min-w-0 break-words '
+ 'border-accent-line bg-accent-tint'
const FLOW = 'grid gap-2 mt-4 grid-cols-4 max-mid:grid-cols-3 max-mid2:grid-cols-2 max-tiny:grid-cols-1'
const GRID_4 = 'grid gap-4 mt-4 grid-cols-4 max-mid:grid-cols-2 max-tiny:grid-cols-1'
const STEPS = 'm-0 mt-3 p-0 list-none space-y-2 min-w-0 [counter-reset:steps] [&>li]:relative [&>li]:min-w-0 '
+ '[&>li]:rounded-control [&>li]:border [&>li]:border-line [&>li]:bg-panel [&>li]:py-[9px] '
+ '[&>li]:pr-[11px] [&>li]:pl-[43px] [&>li]:text-body [&>li]:text-ink-2 [&>li]:leading-[1.75] '
+ '[&>li]:[counter-increment:steps] [&>li]:before:absolute [&>li]:before:top-[9px] '
+ '[&>li]:before:left-[11px] [&>li]:before:grid [&>li]:before:h-[22px] [&>li]:before:w-[22px] '
+ '[&>li]:before:place-items-center [&>li]:before:rounded-chip [&>li]:before:bg-accent-tint '
+ '[&>li]:before:text-accent [&>li]:before:font-mono [&>li]:before:text-tiny '
+ '[&>li]:before:content-[counter(steps)]'
const CALLOUT_WARN = 'mt-4 rounded-block border p-[13px] text-label leading-[1.9] min-w-0 break-words '
+ 'border-warn-line bg-warn-tint text-ink-2'
const CHECKS = "m-0 mt-3 p-0 list-none space-y-[7px] min-w-0 [&>li]:text-body [&>li]:text-ink-2 "
+ "[&>li]:leading-[1.75] [&>li]:pl-[23px] [&>li]:before:float-left [&>li]:before:-ml-[21px] "
+ "[&>li]:before:mr-[8px] [&>li]:before:text-accent [&>li]:before:content-['✓']"
const GRID_2 = 'grid gap-4 mt-4 grid-cols-2 max-tiny:grid-cols-1'
const SHOT_GRID = 'grid gap-4 mt-4 grid-cols-2 max-mid:grid-cols-1'
const TABLE_WRAP = 'mt-4 overflow-x-auto rounded-block border border-line min-w-0'
const FLOW_NODE = 'min-w-0 rounded-control border border-line bg-panel p-[11px] text-caption text-dim '
+ 'leading-[1.7] [&>b]:block [&>b]:text-ui [&>b]:font-bold [&>b]:text-ink [&>b]:mb-[3px]'
const HEAD_WRAP = 'min-w-0'
/** 手册目录:`id` 与节号一改,这里跟着正文一起变 */
const TOC = [
['quick-start', '00 · GET STARTED', '快速开始'],
['workflow', '01 · PIPELINE', '完整业务流程'],
['models', '02 · MODEL OPERATIONS', '模型管理中心'],
['assets', '03 · ASSET MANAGEMENT', '资产管理'],
['storyboard', '04 · STORYBOARD', '分镜与脚本'],
['dispatch', '05 · DISPATCH', '任务调度'],
['review', '06 · QUALITY & REVIEW', '质检与审核'],
['timeline', '07 · COMPOSE & DELIVER', '时间线与导出'],
['troubleshooting', '08 · TROUBLESHOOTING', '故障排查'],
['api', '09 · API REFERENCE', '接口文档']
] as [string, string, string][]
/** 点目录只滚本页,不把浏览器历史堆满(返回键应该离开手册,不是退回上一个锚点) */
function jumpTo(event: MouseEvent<HTMLAnchorElement>, id: string) {
event.preventDefault()
document.getElementById(id)?.scrollIntoView({ behavior: 'smooth', block: 'start' })
window.history.replaceState(null, '', '#' + id)
}
export default function Help() {
return (
<div className={SHELL}>
<nav aria-label="手册目录" className={TOC_NAV}>
{TOC.map(([id, no, title]) => (
<a key={id} href={'#' + id} className={TOC_LINK} title={no} onClick={(e) => jumpTo(e, id)}>{title}</a>
))}
</nav>
<header className={HERO}>
<p className={EYEBROW}>
NEX ANIMATION STUDIO · USER GUIDE
</p>
<h1 className={TAG_H1}>
长视频编导平台使用手册
</h1>
<p className={TAG_P}>
从模型配置、资产管理、脚本导入,到分镜生成、自动质检、人工审核与长视频合成, 本手册按实际业务流程说明每个页面的用途与关键操作。所有截图均来自正在运行的系统。
</p>
<div className={PILLS}>
<span className={PILL}>四类模型统一管理</span> <span className={PILL}>资产独立生成与镜头关联</span> <span className={PILL}>队列入队 / 重试 / 断点续跑</span> <span className={PILL}>质检、时间线与完整导出</span>
</div>
</header>
<section id="quick-start" className={TAG_SECTION}>
<div className={SECTION_HEAD}>
<div className={HEAD_WRAP}>
<span className={STEP_NO}>00 · GET STARTED</span>
<h2 className={TAG_H2}>
快速开始
</h2>
</div>
<p className={TAG_P}>
建议先确认模型可用,再创建项目并导入分镜。单机模式下默认使用 SQLite 与进程内任务执行器。
</p>
</div>
<div className={GRID_3}>
<article className={CARD}>
<span className={ICON}>▶</span> <b>一键启动</b>
<p className={TAG_P}>
在仓库根目录执行启动脚本,脚本会自检依赖、环境变量和端口。
</p>
</article>
<article className={CARD}>
<span className={ICON}>◫</span> <b>配置模型</b>
<p className={TAG_P}>
在模型管理中心检查大模型、视频、图像、声音四类模型的连接状态与默认项。
</p>
</article>
<article className={CARD}>
<span className={ICON}>◎</span> <b>进入项目</b>
<p className={TAG_P}>
从项目总览创建或打开项目,按左侧业务模块依次推进。
</p>
</article>
</div>
<div className={CALLOUT_INFO}>
<b>界面导航:</b>顶部应用栏左侧是平台标识;正中间是<b>流程进度控制台</b>——项目名、项目状态、 12 个业务节点轨道(按完成 / 进行中 / 需处理 / 待处理着色;进行中的那一段更高、带光晕并与需处理一起呼吸闪烁, 扫一眼就知道卡在哪一段)、 流程进度(已完成节点 ÷ 全部节点)与当前节点,点一下控制台就回到流程概览;12 个节点全部走完时这里改说 <b>「全部 12 个节点已完成」</b>,不会在「已交付」旁边再挂一个假的当前节点。这条口径由 <code className={TAG_CODE}>frontend/src/lib/pipeline.ts</code> 统一定义,侧栏项目副标题、项目页头标签、流程进度条 (含总览右侧的示例流程)、项目设置面板的状态标签(流程推进中 / <b>流程已完成</b> / 已归档)、 「下一步建议」抬头、项目总览表格与卡片的<b>「流程节点」列</b>、资产库「引入项目」下拉的副标题 全部复用它,任何一处都不会各说各话。右侧固定放使用手册、显示模式(深色 / 浅色, <code className={TAG_CODE}>⌘/Ctrl+Shift+L</code> 随时切换)和账号胶囊;点开账号胶囊即是二级菜单——我的账号、用户管理、退出登录都在这里。 接口文档不再占用顶栏入口,需要时直接访问 <a href="/docs" target="_blank" rel="noreferrer" className={TAG_A}><code className={TAG_CODE}>/docs</code></a>。 左侧栏只保留模块导航:全局三个模块 + 当前项目的七个业务节点。页面底部不再常驻系统信息。
</div>
<figure className={SCREENSHOT}>
<a href="/help/overview.png" target="_blank" rel="noreferrer" aria-label="查看项目总览页截图" className={TAG_A}><img src="/help/overview.png" alt="项目总览页:顶部应用栏(平台标识、居中的流程进度控制台、手册 / 显示模式 / 账号胶囊)与左侧模块导航" className={TAG_IMG} /></a>
<figcaption className={TAG_FIGCAPTION}>
<span>项目内页面:顶栏居中的进度控制台常驻,轨道颜色、流程进度与当前节点跟着轮询实时更新;右侧手册 / 显示模式 / 账号胶囊固定。</span> <span>点击图片查看原图 ↗</span>
</figcaption>
</figure>
<div className={CALLOUT}>
<b>环境自检:</b>执行器、ffmpeg、字幕烧录 / 内嵌、数据库、调度守护这些后台能力不再常驻页面, 只有真的出问题时才会在账号菜单里出现一行警告;需要随时核对,直接打开 <a href="/health" target="_blank" rel="noreferrer" className={TAG_A}><code className={TAG_CODE}>/health</code></a> 与 <a href="/api/meta" target="_blank" rel="noreferrer" className={TAG_A}><code className={TAG_CODE}>/api/meta</code></a>。
</div>
<pre className={PRE}>
<code>{`./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`}</code>
</pre>
<div className={CALLOUT_INFO}>
如果页面能打开但页面顶部出现「后端连接异常」,先运行 <code className={TAG_CODE}>./scripts/dev.sh status</code>, 再检查 <code className={TAG_CODE}>http://127.0.0.1:8000/health</code> 是否返回 JSON。
</div>
</section>
<section id="workflow" className={TAG_SECTION}>
<div className={SECTION_HEAD}>
<div className={HEAD_WRAP}>
<span className={STEP_NO}>01 · PIPELINE</span>
<h2 className={TAG_H2}>
完整业务流程
</h2>
</div>
<p className={TAG_P}>
项目的流程条会实时汇总镜头、任务、质检、时间线与导出状态。任何一步跳过或失败,都会在上方流程条中暴露。
</p>
</div>
<div className={FLOW}>
<div className={FLOW_NODE}>
<b>① 创建项目</b>设定片长、画幅与风格
</div>
<div className={FLOW_NODE}>
<b>② 导入分镜</b>脚本与关键帧一起入库
</div>
<div className={FLOW_NODE}>
<b>③ 绑定资产</b>人物、场景、声线关联镜头
</div>
<div className={FLOW_NODE}>
<b>④ 生成任务</b>按镜头生成任务清单
</div>
<div className={FLOW_NODE}>
<b>⑤ 预检调度</b>检查素材、参数与容量
</div>
<div className={FLOW_NODE}>
<b>⑥ 调用模型</b>执行视频和配音生成
</div>
<div className={FLOW_NODE}>
<b>⑦ 保存产物</b>下载并登记新素材版本
</div>
<div className={FLOW_NODE}>
<b>⑧ 自动质检</b>解码、时长、分辨率、帧率等
</div>
<div className={FLOW_NODE}>
<b>⑨ 人工审核</b>合格通过或带修改意见重做
</div>
<div className={FLOW_NODE}>
<b>⑩ 时间线合成</b>裁剪、转场、字幕、配音、BGM
</div>
<div className={FLOW_NODE}>
<b>⑪ 出片预检</b>检查缺片、字幕与音轨
</div>
<div className={FLOW_NODE}>
<b>⑫ 导出交付</b>生成成片并记录成本与校验和
</div>
</div>
<div className={CALLOUT}>
推荐顺序:<b>模型管理中心 → 资产管理 → 分镜与脚本 → 任务调度中心 → 质检与审核 → 时间线合成 → 导出与成本</b>。 资产可以先独立生成,再在分镜的“资产绑定”页中关联,不要求先有镜头的生成产物。
</div>
</section>
<section id="models" className={TAG_SECTION}>
<div className={SECTION_HEAD}>
<div className={HEAD_WRAP}>
<span className={STEP_NO}>02 · MODEL OPERATIONS</span>
<h2 className={TAG_H2}>
模型管理中心
</h2>
</div>
<p className={TAG_P}>
统一管理机构可调用的四类能力。资产独立生成和分镜任务都会读取这里的默认模型与供应能力。
</p>
</div>
<div className={GRID_4}>
<article className={CARD}>
<span className={ICON}>✦</span> <b>大模型</b>
<p className={TAG_P}>
剧本拆解、编导指令与提示词补全,修正跨镜头一致性。
</p>
</article>
<article className={CARD}>
<span className={ICON}>▶</span> <b>视频模型</b>
<p className={TAG_P}>
文生视频、图生视频、首尾帧;配置并发、RPM、时长与分辨率。
</p>
</article>
<article className={CARD}>
<span className={ICON}>▧</span> <b>图像模型</b>
<p className={TAG_P}>
人物定妆图、三视图、服装、表情以及场景参考图。
</p>
</article>
<article className={CARD}>
<span className={ICON}>◉</span> <b>声音模型</b>
<p className={TAG_P}>
TTS 配音与声线试听样本,可绑定到人物和镜头台词。
</p>
</article>
</div>
<figure className={SCREENSHOT}>
<a href="/help/model-center.png" target="_blank" rel="noreferrer" aria-label="查看模型管理中心截图" className={TAG_A}><img src="/help/model-center.png" alt="模型管理中心:大模型、视频、图像、声音四类模型统一管理" className={TAG_IMG} /></a>
<figcaption className={TAG_FIGCAPTION}>
<span>模型管理中心:四类模型分类、默认模型、连接状态、容量与价格。</span> <span>点击图片查看原图 ↗</span>
</figcaption>
</figure>
<h3 className={TAG_H3}>
常用操作
</h3>
<ol className={STEPS}>
<li>
点击右上角“登记模型”,填写 Provider、Model、媒体类型与适配器;媒体类型必须与适配器匹配。
</li>
<li>
为大模型、视频、图像、声音分别设置一个启用中的默认模型,资产页会自动选中对应默认项。
</li>
<li>
展开模型卡片编辑并发、RPM、时长、分辨率、价格和默认参数。
</li>
<li>
点击「检测连接」检查适配器与外部服务是否可达;不可用时先修复连接再执行生成。
</li>
<li>
在故障演练中使用可控失败率验证重试与断点续跑,验证完成后恢复为正常配置。
</li>
</ol>
<div className={CALLOUT_WARN}>
<b>提示:</b>切换默认模型只影响后续任务,不会重写已经完成的任务记录。历史任务仍保留当时的 Provider、Model、参数和产物版本。
</div>
</section>
<section id="assets" className={TAG_SECTION}>
<div className={SECTION_HEAD}>
<div className={HEAD_WRAP}>
<span className={STEP_NO}>03 · ASSET MANAGEMENT</span>
<h2 className={TAG_H2}>
资产管理
</h2>
</div>
<p className={TAG_P}>
集中维护人物、场景、声线与项目素材。资产可以独立调用模型生成,也可在分镜中绑定并参与后续视频生成。
</p>
</div>
<div className={GRID_4}>
<article className={CARD}>
<b>人物</b>
<p className={TAG_P}>
外观、性格、一致性提示词、默认声线;定妆图 / 三视图 / 服装 / 表情。
</p>
</article>
<article className={CARD}>
<b>场景</b>
<p className={TAG_P}>
描述、光线、时间、色调;场景图可作为镜头参考与关键帧来源。
</p>
</article>
<article className={CARD}>
<b>声线</b>
<p className={TAG_P}>
Provider voice_id、语言、性别、语速、效果与试听样本。
</p>
</article>
<article className={CARD}>
<b>项目素材</b>
<p className={TAG_P}>
BGM、音效、通用参考图与视频,可挂到时间线音轨。
</p>
</article>
</div>
<figure className={SCREENSHOT}>
<a href="/help/asset-management.png" target="_blank" rel="noreferrer" aria-label="查看资产管理人物页截图" className={TAG_A}><img src="/help/asset-management.png" alt="资产管理人物页:独立生成、默认模型、版本与被镜头使用情况" className={TAG_IMG} /></a>
<figcaption className={TAG_FIGCAPTION}>
<span>人物资产:默认图像 / 大模型已自动选中,并显示镜头使用位置与模型生成版本。</span> <span>点击图片查看原图 ↗</span>
</figcaption>
</figure>
<h3 className={TAG_H3}>
独立生成人物或场景资产
</h3>
<ol className={STEPS}>
<li>
打开“资产管理”,选择人物或场景页签。
</li>
<li>
在对应的 AI 生成卡片中选择图像模型和生成类型;需要文本补全时选择大模型。
</li>
<li>
生成描述可以留空,系统会使用人物外观、场景描述、光线与风格设定自动组装提示词。
</li>
<li>
点击「生成母版图像」(人物定妆图 / 三视图 / 场景图)。完成后资产自动登记新版本,并显示 Provider / Model。
</li>
<li>
点击“AI 补全一致性提示词”,检查建议内容后选择“采用”,写回人物或场景设定。
</li>
</ol>
<div className={CALLOUT}>
<b>与分镜的关联:</b>每个资产卡片显示“被 N 个镜头使用”。点击镜头链接会进入分镜页并自动选中对应镜头; 在分镜右侧“资产绑定”页可调整人物、场景和声音。生成视频时,有效的参考资产会进入模型请求。
</div>
<figure className={SCREENSHOT}>
<a href="/help/scene-assets.png" target="_blank" rel="noreferrer" aria-label="查看场景资产页截图" className={TAG_A}><img src="/help/scene-assets.png" alt="场景资产页:场景独立生成、模型选择、镜头使用关系和场景参考图" className={TAG_IMG} /></a>
<figcaption className={TAG_FIGCAPTION}>
<span>场景资产:同样可以选择图像 / 大模型独立生成,结果自动登记版本并显示关联镜头。</span> <span>点击图片查看原图 ↗</span>
</figcaption>
</figure>
<figure className={SCREENSHOT}>
<a href="/help/voice-assets.png" target="_blank" rel="noreferrer" aria-label="查看声音资产页截图" className={TAG_A}><img src="/help/voice-assets.png" alt="声音资产页:TTS 模型选择、AI 试听生成和可播放音色样本" className={TAG_IMG} /></a>
<figcaption className={TAG_FIGCAPTION}>
<span>声音资产:选择声音模型生成试听样本,音频版本可直接播放;下方展示绑定的镜头。</span> <span>点击图片查看原图 ↗</span>
</figcaption>
</figure>
<h3 className={TAG_H3}>
声音资产
</h3>
<ul className={CHECKS}>
<li>
选择可用声音模型,填写试听文本后点击「生成试听样本」。
</li>
<li>
生成完成会得到带时长、Provider、Model 与任务 ID 的新版本音频。
</li>
<li>
macOS 系统语音可使用 Tingting、Meijia、Fred 等 voice_id;外星角色可选择降调与金属共振效果。
</li>
<li>
人物默认声线绑定后,镜头台词可自动进入 TTS 配音与时间线混音流程。
</li>
</ul>
</section>
<section id="storyboard" className={TAG_SECTION}>
<div className={SECTION_HEAD}>
<div className={HEAD_WRAP}>
<span className={STEP_NO}>04 · STORYBOARD</span>
<h2 className={TAG_H2}>
分镜与脚本
</h2>
</div>
<p className={TAG_P}>
分镜工作台:顶栏看总量与预检指标,看板或分镜表浏览镜头序列,右侧常驻检查器按“镜头 / 资产 / 提示词 / 产物”组织细节。
</p>
</div>
<figure className={SCREENSHOT}>
<a href="/help/storyboard.png" target="_blank" rel="noreferrer" aria-label="查看分镜工作台截图" className={TAG_A}><img src="/help/storyboard.png" alt="分镜工作台:指标条、搜索筛选、批量操作与网格看板" className={TAG_IMG} /></a>
<figcaption className={TAG_FIGCAPTION}>
<span>分镜工作台:镜头数 / 计划时长 / 已合格 / 有阻塞一眼可见,卡片显示缩略图、景别运镜、QC 分、绑定与逐镜预检问题。</span> <span>点击图片查看原图 ↗</span>
</figcaption>
</figure>
<div className={GRID_3}>
<article className={CARD}>
<b>导入脚本</b>
<p className={TAG_P}>
支持 Markdown、CSV、TSV、JSON 与纯文本,可先预览再落库。
</p>
</article>
<article className={CARD}>
<b>关键帧匹配</b>
<p className={TAG_P}>
图片可按镜号自动匹配,也支持 ZIP 批量导入。
</p>
</article>
<article className={CARD}>
<b>资产绑定</b>
<p className={TAG_P}>
人物、场景和声音可逐镜头关联,并即时看到使用关系。
</p>
</article>
</div>
<figure className={SCREENSHOT}>
<a href="/help/storyboard-inspector.png" target="_blank" rel="noreferrer" aria-label="查看分镜检查器截图" className={TAG_A}><img src="/help/storyboard-inspector.png" alt="分镜工作台:选中镜头后右侧常驻检查器的镜头页签" className={TAG_IMG} /></a>
<figcaption className={TAG_FIGCAPTION}>
<span>选中任一镜头后检查器常驻右侧并与看板并排:镜头参数、资产绑定、提示词版本、产物与质检各占一个页签,改动未保存会有「未保存」标记。</span> <span>点击图片查看原图 ↗</span>
</figcaption>
</figure>
<h3 className={TAG_H3}>
推荐操作
</h3>
<ol className={STEPS}>
<li>
点击“导入脚本 / 关键帧”,粘贴脚本并上传关键帧;先用“导入预演”确认镜头数量与图片匹配,再正式导入。
</li>
<li>
用搜索框和状态 / 模式 / 排序筛选定位镜头,或点“仅看阻塞”“仅看缺关键帧”直接清理预检问题。
</li>
<li>
拖动卡片即可改镜序(分镜表视图也可拖行或用 ↑↓);勾选多个镜头后可批量复制、移到最前、统一改参数或删除。
</li>
<li>
选中镜头后在检查器编辑参数与绑定;提示词页可切换“自动组装 / 人工覆盖”,并回填任意历史版本。
</li>
<li>
卡片上的“生成”“审核”带 <code className={TAG_CODE}>?shot=镜头ID</code> 深链,跳到调度中心或审核页时会自动选中同一镜头。
</li>
<li>
需要交给编剧或外部工具时,用右上角导出 Markdown / CSV / JSON,导出的 Markdown 可以直接再导回来。
</li>
</ol>
<div className={CALLOUT}>
<b>快捷键:</b> <code className={TAG_CODE}>J</code> / <code className={TAG_CODE}>K</code> 或 <code className={TAG_CODE}>↑</code> <code className={TAG_CODE}>↓</code> 切换镜头,<code className={TAG_CODE}>X</code> 勾选当前镜头, <code className={TAG_CODE}>⌘S</code> 保存检查器改动,<code className={TAG_CODE}>Esc</code> 关闭检查器或导入面板。首屏只拉轻量看板数据, 几十上百镜也不会拖慢页面。
</div>
</section>
<section id="dispatch" className={TAG_SECTION}>
<div className={SECTION_HEAD}>
<div className={HEAD_WRAP}>
<span className={STEP_NO}>05 · DISPATCH</span>
<h2 className={TAG_H2}>
任务调度
</h2>
</div>
<p className={TAG_P}>
任务清单先解释执行原因,再按模型容量和限流派发。已完成镜头会被跳过,避免重复消耗真实模型时长。
</p>
</div>
<figure className={SCREENSHOT}>
<a href="/help/dispatch.png" target="_blank" rel="noreferrer" aria-label="查看任务调度中心截图" className={TAG_A}><img src="/help/dispatch.png" alt="任务调度中心:分镜任务清单、预检结果、执行开关和异常处理" className={TAG_IMG} /></a>
<figcaption className={TAG_FIGCAPTION}>
<span>调度中心:任务状态、Provider / Model、预计成本、入队选项与断点续跑入口。</span> <span>点击图片查看原图 ↗</span>
</figcaption>
</figure>
<div className={GRID_2}>
<article className={CARD}>
<b>入队前</b>
<p className={TAG_P}>
检查预检阻塞项、镜头状态、模型容量与预计成本。默认只入队预检通过的镜头,缺素材或缺参数的镜头会被跳过,需要时再勾选「放行预检未通过的镜头」。
</p>
</article>
<article className={CARD}>
<b>执行中</b>
<p className={TAG_P}>
查看运行任务、心跳、尝试次数与进度。失败任务会按配置重试,超时任务可从中断点续跑。
</p>
</article>
</div>
<ol className={STEPS}>
<li>
确认任务清单中的 Provider / Model 与预期一致。
</li>
<li>
按需开启「入队时一并排配音任务」「放行预检未通过的镜头」「强制重建任务(忽略幂等)」,并设置优先级与单次派发上限。
</li>
<li>
点击「入队所选 / 全部待生成」。勾选「派发后同步排空」会一直等到任务跑完再返回;不勾选时任务在后台执行,页面自动刷新进度。
</li>
<li>
失败时查看错误码与错误历史;修复后使用“重排全部失败任务”或“断点续跑”。
</li>
<li>
已完成且仍需强制重做的镜头,勾选“强制重建任务”后再派发。
</li>
</ol>
</section>
<section id="review" className={TAG_SECTION}>
<div className={SECTION_HEAD}>
<div className={HEAD_WRAP}>
<span className={STEP_NO}>06 · QUALITY & REVIEW</span>
<h2 className={TAG_H2}>
质检与审核
</h2>
</div>
<p className={TAG_P}>
先自动检查文件完整性、时长、分辨率、帧率等指标,再由人工确认画面和声音。驳回可携带修改意见重新生成。
</p>
</div>
<figure className={SCREENSHOT}>
<a href="/help/review.png" target="_blank" rel="noreferrer" aria-label="查看质检与审核页面截图" className={TAG_A}><img src="/help/review.png" alt="质检与审核页面:自动质检清单、镜头预览、检查项得分和人工审核" className={TAG_IMG} /></a>
<figcaption className={TAG_FIGCAPTION}>
<span>质检与审核:自动质检清单、视频预览、逐项指标解释和人工通过 / 驳回操作。</span> <span>点击图片查看原图 ↗</span>
</figcaption>
</figure>
<ul className={CHECKS}>
<li>
在自动质检清单中按镜头检查得分为 100 的项,确认没有解码、时长或分辨率异常。
</li>
<li>
播放右侧产物,检查人物一致性、动作、构图、音轨和字幕风险。
</li>
<li>
合格后填写审核人并提交;不合格时填写修改意见与新的提示词,选择是否立即重新生成。
</li>
<li>
驳回镜头会回到任务计划状态,再次进入调度中心,不会覆盖之前的历史产物。
</li>
<li>
镜头多时用顶部“批量放行质检合格镜头”一次性放过全部质检通过且待审核的镜头,只手工盯有问题的几个。
</li>
<li>
从分镜工作台点“审核”跳过来时带 <code className={TAG_CODE}>?shot=镜头ID</code>,右侧直接定位到该镜头。
</li>
</ul>
</section>
<section id="timeline" className={TAG_SECTION}>
<div className={SECTION_HEAD}>
<div className={HEAD_WRAP}>
<span className={STEP_NO}>07 · COMPOSE & DELIVER</span>
<h2 className={TAG_H2}>
时间线与导出
</h2>
</div>
<p className={TAG_P}>
时间线只收集已审核合格产物,统一处理片段顺序、转场、字幕、配音、BGM、响度与最终编码。
</p>
</div>
<div className={SHOT_GRID}>
<figure className={SCREENSHOT}>
<a href="/help/timeline.png" target="_blank" rel="noreferrer" aria-label="查看时间线合成页面截图" className={TAG_A}><img src="/help/timeline.png" alt="时间线合成:片段、转场、字幕、音轨和交付预检" className={TAG_IMG} /></a>
<figcaption className={TAG_FIGCAPTION}>
<span>时间线:片段与转场、字幕、音轨和交付预检。</span> <span>查看原图 ↗</span>
</figcaption>
</figure>
<figure className={SCREENSHOT}>
<a href="/help/delivery.png" target="_blank" rel="noreferrer" aria-label="查看项目交付页面截图" className={TAG_A}><img src="/help/delivery.png" alt="导出与成本:出片预设、成本台账、成片记录与下载" className={TAG_IMG} /></a>
<figcaption className={TAG_FIGCAPTION}>
<span>交付:选择预设、检查成本、生成并下载成片。</span> <span>查看原图 ↗</span>
</figcaption>
</figure>
</div>
<h3 className={TAG_H3}>
时间线合成
</h3>
<ol className={STEPS}>
<li>
点击“构建 / 重建时间线”,系统自动收集已审核合格镜头。
</li>
<li>
调整片段顺序、时长、入点、转场和音量;补齐缺失字幕与配音。
</li>
<li>
检查交付预检报告,确保缺片、字幕、声轨和总时长均为通过状态。
</li>
<li>
如使用外挂字幕,保持字幕模式为 SRT;当前 ffmpeg 未启用烧录滤镜时会明确降级。
</li>
</ol>
<h3 className={TAG_H3}>
导出与成本
</h3>
<ul className={CHECKS}>
<li>
选择横屏或竖屏的 720p 试片、1080p 投放、高质量 1080p 或超清 4K 预设,可多选依次入队。
</li>
<li>
确认成片名称、字幕策略与优先级,然后点击“开始合成导出”。
</li>
<li>
在成片记录中检查分辨率、帧率、时长、大小、校验和与下载地址。
</li>
<li>
成本台账按 Provider、Model 汇总实际费用;mock 模型的单价为 0。
</li>
</ul>
</section>
<section id="troubleshooting" className={TAG_SECTION}>
<div className={SECTION_HEAD}>
<div className={HEAD_WRAP}>
<span className={STEP_NO}>08 · TROUBLESHOOTING</span>
<h2 className={TAG_H2}>
故障排查
</h2>
</div>
<p className={TAG_P}>
先看页面错误和任务错误历史,再看后端健康状态与日志;不要在未确认原因时反复重烧真实模型。
</p>
</div>
<div className={TABLE_WRAP}>
<table className={TAG_TABLE}>
<thead>
<tr className={TAG_TR}>
<th className={TAG_TH}>现象</th><th className={TAG_TH}>优先检查</th><th className={TAG_TH}>处理方式</th>
</tr>
</thead>
<tbody>
<tr className={TAG_TR}>
<td className={TAG_TD}>前后端服务未启动</td><td className={TAG_TD}><code className={TAG_CODE}>./scripts/dev.sh status</code></td><td className={TAG_TD}>运行 <code className={TAG_CODE}>./scripts/dev.sh restart --no-install</code>,再查看 <code className={TAG_CODE}>.local/logs/</code>。</td>
</tr>
<tr className={TAG_TR}>
<td className={TAG_TD}>启动时报 unbound variable</td><td className={TAG_TD}>脚本是否将变量写作 <code className={TAG_CODE}>{"${VAR}"}</code></td><td className={TAG_TD}>Bash 3.2 下变量紧邻中文或全角符号时必须使用花括号形式。</td>
</tr>
<tr className={TAG_TR}>
<td className={TAG_TD}>模型下拉框为空</td><td className={TAG_TD}>模型管理中心是否启用对应媒体类型</td><td className={TAG_TD}>启用并设置默认模型;资产页加载完成后会自动同步默认值。</td>
</tr>
<tr className={TAG_TR}>
<td className={TAG_TD}>资产显示被 0 个镜头使用</td><td className={TAG_TD}>分镜“资产绑定”页</td><td className={TAG_TD}>逐镜头绑定人物、场景或声音;预检会提示缺失绑定。</td>
</tr>
<tr className={TAG_TR}>
<td className={TAG_TD}>派发被拒或镜头被跳过</td><td className={TAG_TD}>预检问题与镜头状态</td><td className={TAG_TD}>优先补齐阻塞项;只有确认需要重做时才开启强制重建。</td>
</tr>
<tr className={TAG_TR}>
<td className={TAG_TD}>任务超时或进程重启</td><td className={TAG_TD}>任务心跳和检查点</td><td className={TAG_TD}>使用断点续跑,保留已成功镜头,避免重复调用模型。</td>
</tr>
<tr className={TAG_TR}>
<td className={TAG_TD}>时间线为空</td><td className={TAG_TD}>是否存在已审核合格镜头</td><td className={TAG_TD}>先完成质检与人工审核,再重建时间线。</td>
</tr>
<tr className={TAG_TR}>
<td className={TAG_TD}>字幕烧录失败</td><td className={TAG_TD}><code className={TAG_CODE}>/health</code> 中的 <code className={TAG_CODE}>ffmpeg_capabilities.subtitle_burn</code></td><td className={TAG_TD}>改为外挂 SRT,或安装带 libass / subtitles 滤镜的 ffmpeg。</td>
</tr>
<tr className={TAG_TR}>
<td className={TAG_TD}>真实模型连接不可达</td><td className={TAG_TD}>模型中心的探测结果(含中文结论)</td><td className={TAG_TD}>按探测提示确认那台机器上的 ComfyUI 进程与端口是否还在。<b>平台直连 ComfyUI,不走系统代理</b>,因此本机开了 Clash / VPN 也不影响出片,排查时不必检查代理设置。</td>
</tr>
<tr className={TAG_TR}>
<td className={TAG_TD}>点录音没有弹授权框,或提示打不开麦克风</td><td className={TAG_TD}>页面会先体检麦克风:设备数、系统权限、当前地址是否 https</td><td className={TAG_TD}>按提示逐条处理:系统设置 → 隐私与安全性 → 麦克风里放开浏览器;地址栏左侧图标把麦克风改回「允许」;用 IP + http 从别的机器访问时浏览器根本没有录音接口,请改用 <code className={TAG_CODE}>localhost</code> 或 https。急着出片可先在外部录好再走「上传文件」。</td>
</tr>
<tr className={TAG_TR}>
<td className={TAG_TD}>点了「开始录制」一直转圈,系统授权框始终没出现(macOS)</td><td className={TAG_TD}>macOS 的麦克风授权框<b>出现在屏幕左下角</b>(不是窗口正中),很容易被忽略;一旦误点「不允许」,Chrome 会记住结论,之后<b>不再弹框</b>,页面只会收到一句 <code className={TAG_CODE}>Requested device not found</code></td><td className={TAG_TD}>录音面板顶部有一行麦克风自检:<b>✓ 麦克风已就绪:设备名</b> 表示可以直接录;⚠ 时按下面的说明逐条走,需要重置系统权限时点<b>「复制修复命令」</b>,粘到终端执行 <code className={TAG_CODE}>tccutil reset Microphone com.google.Chrome</code> 后回到面板点「重新检测」即可,<b>不用重启浏览器</b>。换了麦克风或改了系统权限也不用刷新:面板会自动重新体检。</td>
</tr>
<tr className={TAG_TR}>
<td className={TAG_TD}>录到一半录音面板自己消失了</td><td className={TAG_TD}>是否正好切走了类型 / 筛选(母版列表换了内容,卡片上的面板随之关闭)</td><td className={TAG_TD}>录音期间平台的自动刷新会主动让路(不重建列表),录完或关掉面板后下一轮自动恢复;切换类型、翻页会离开当前母版,请先停止录制并保存这段录音。</td>
</tr>
</tbody>
</table>
</div>
<pre className={PRE}>
<code>{`# 快速收集运行时信息
./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`}</code>
</pre>
</section>
<section id="api" className={TAG_SECTION}>
<div className={SECTION_HEAD}>
<div className={HEAD_WRAP}>
<span className={STEP_NO}>09 · API REFERENCE</span>
<h2 className={TAG_H2}>
接口文档
</h2>
</div>
<p className={TAG_P}>
所有前后端操作都通过同一组 REST 接口完成,便于脚本化、自动测试和后续接入其他客户端。
</p>
</div>
<div className={GRID_3}>
<article className={CARD}>
<b>Swagger UI</b>
<p className={TAG_P}>
<a href="/docs" target="_blank" rel="noreferrer" className={TAG_A}>/docs</a>:浏览并直接调用全部接口。
</p>
</article>
<article className={CARD}>
<b>OpenAPI JSON</b>
<p className={TAG_P}>
<a href="/openapi.json" target="_blank" rel="noreferrer" className={TAG_A}>/openapi.json</a>:供代码生成与自动化测试使用。
</p>
</article>
<article className={CARD}>
<b>健康检查</b>
<p className={TAG_P}>
<a href="/health" target="_blank" rel="noreferrer" className={TAG_A}>/health</a>:执行器、数据库、ffmpeg、守护调度器与模型数量。
</p>
</article>
</div>
<div className={CALLOUT_INFO}>
常用接口包括 <code className={TAG_CODE}>GET /api/providers</code>、<code className={TAG_CODE}>{"POST /api/projects/{id}/assets/generate"}</code>、 <code className={TAG_CODE}>{"POST /api/projects/{id}/assets/text-assist"}</code>、<code className={TAG_CODE}>{"GET /api/projects/{id}/assets/usage"}</code>、 <code className={TAG_CODE}>{"POST /api/projects/{id}/dispatch"}</code> 与 <code className={TAG_CODE}>{"POST /api/projects/{id}/compose"}</code>。
</div>
</section>
<footer className={TAG_FOOTER}>
Nex Animation Studio · 本手册随平台代码维护。截图来自项目《铁血战士的猎人晚宴》的实际运行状态。
</footer>
<div className={SIDE}>
<span className={SIDE_LABEL}>相关入口</span>
<Link className={TOC_LINK} to="/">进入工作台</Link>
<Link className={TOC_LINK} to="/models">模型管理中心</Link>
<ExtLink href="/docs" className={TOC_LINK}>FastAPI 接口文档</ExtLink>
<ExtLink href="/health" className={TOC_LINK}>系统健康检查</ExtLink>
</div>
</div>
)
}

View File

@ -299,7 +299,7 @@
--shadow-pop: 0 18px 44px var(--c-backdrop-shadow);
--shadow-drawer: -25px 0 80px var(--c-shade-2);
/* 断点:沿用旧站已经调好的六档,名字按「这一档在收什么」取。
/* 断点:沿用旧站已经调好的七档,名字按「这一档在收什么」取。
页面不要再自己写 @media(1180px) 这类魔法数字(UI规范 §0)。
huge 1440 超宽屏开始收窄
mid 1180 右栏检查器落到下方、控制台收起当前节点

View File

@ -214,6 +214,17 @@ start_server() {
else
warn "$BASE/ 未返回页面:确认已构建前端且 .env 没把 SERVE_FRONTEND 关掉"
fi
# 深链回落:React Router 用 browser history,/projects/1 在磁盘上没有对应文件,
# 必须回 index.html。这条挂了 = 用户刷新一次页面就 404(见 backend/app/main.py:spa_target)。
if curl -fsS --max-time 3 -o /dev/null "$BASE/projects/1" 2>/dev/null; then
ok "深链回落 $BASE/projects/1(history 模式正常)"
else
warn "$BASE/projects/1 没有回落页面:刷新深链会 404,检查 SERVE_FRONTEND 与 frontend/dist"
fi
# 不存在的接口必须是 JSON 404,不能被 SPA 壳伪装成 200 + HTML(前端会把 HTML 当 JSON 解析)
code="$(curl -s -o /dev/null -w '%{http_code}' --max-time 3 "$BASE/api/__spa_probe__" 2>/dev/null || echo 000)"
[ "$code" = "404" ] && ok "未知接口返回 404(未被 SPA 壳吞掉)" \
|| warn "$BASE/api/__spa_probe__ 返回 $code,期望 404:SPA catch-all 可能吞掉了 API 路径"
head2 "已启动"
info "${C_B}平台${C_0} $BASE/"
info "${C_B}接口${C_0} $BASE/docs"