前端统一收尾:图文手册从 public/help.html 搬成站内 React+Tailwind 页面 /help,SPA 深链回落与未知接口 404 拆成纯函数补自检,新增 ErrorBoundary 兜住分包加载失败
parent
e8e5a1cd2b
commit
20e8f19eca
|
|
@ -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. 边界与说明
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
|
|
@ -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 试听」与「模型」挤在一起)。
|
||||
|
|
|
|||
|
|
@ -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` 档位兜住 |
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
|
|
@ -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 />
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
)
|
||||
}
|
||||
}
|
||||
|
|
@ -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}
|
||||
|
|
|
|||
|
|
@ -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 /> }
|
||||
]
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
)
|
||||
}
|
||||
|
|
@ -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 右栏检查器落到下方、控制台收起当前节点
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
|
|
|
|||
Loading…
Reference in New Issue