# AI 视频生成工作流

**Repository Path**: hadlooop/videoflow-ai

## Basic Information

- **Project Name**: AI 视频生成工作流
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-09
- **Last Updated**: 2026-10-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# VideoFlow AI 短视频生成平台

从**创意输入 → 准备镜头 → 人物设定 → 视频生成 → 音频与口型同步 → 字幕 → 合成导出**的一体化短视频生产平台。

实现依据 [`docs/VideoFlow_AI_设计方案.md`](docs/VideoFlow_AI_设计方案.md)。

## 技术栈

| 层 | 技术 |
|---|---|
| 前端 | Vue 3 + TypeScript + Vite + Element Plus + Pinia |
| API | Python 3.12+ / FastAPI / Pydantic / SQLAlchemy 2.0 (async) |
| LLM 编排 | LangChain + OpenAI 兼容接口（DeepSeek 官方 / New API 中转，无可信密钥时使用确定性本地规划器） |
| 媒体 Provider | New API 中转站（视频 / 图片）+ 演示 Provider |
| 异步执行 | 数据库任务表 + 进程内 Worker（可独立运行） |
| 数据层 | 开发 SQLite（aiosqlite），生产可切 PostgreSQL + Alembic |
| 媒体处理 | FFmpeg / ffprobe（拼接、混音、字幕、质检） |
| 文件存储 | 本地目录（key 布局兼容 OSS/S3） |

## 快速开始

### 后端

```bash
cd backend
uv sync --extra dev
cp .env.example .env            # 可选，见下方"演示模式"
uv run uvicorn app.main:app --reload --port 20010
```

- API 前缀：`http://localhost:20010/api/v1`
- 交互文档：`http://localhost:20010/docs`
- 健康检查：`http://localhost:20010/health`

### 前端

```bash
cd frontend
npm install
npm run dev                     # http://localhost:5173
```

Vite 已配置 `/api` 与 `/media` 代理到 `http://localhost:20010`。

### 登录与账号（JWT）

系统**不开放注册**：账号只能在服务器上用脚本创建，登录后才能调 `/api/v1` 下的业务接口。

```bash
# 仓库根目录：创建第一个账号（会提示输入两次密码）
make create-user USERNAME=admin

# 等价写法（在 backend/ 下）
uv run python scripts/create_user.py -u admin              # 新建，交互式输入密码
uv run python scripts/create_user.py -u admin -p 123456    # 直接指定密码
uv run python scripts/create_user.py -u admin --reset      # 重置密码
uv run python scripts/create_user.py -u admin --disable    # 停用（已签发的令牌立即失效）
uv run python scripts/create_user.py -u admin --delete     # 删除账号
uv run python scripts/create_user.py --list                # 列出账号
```

- **令牌策略**：access token **10 分钟**（`ACCESS_TOKEN_MINUTES`）、refresh token 7 天
  （`REFRESH_TOKEN_DAYS`），都是 HS256 无状态 JWT。前端在到期前 60 秒用 refresh token
  **自动续期**，撞上 401 也会自动刷新并重放原请求，正常使用不会被打断；refresh token
  也过期 / 账号被停用时才回登录页。
- **接口**：`POST /api/v1/auth/login`（返回令牌对 + 账号信息）、`POST /api/v1/auth/refresh`、
  `GET /api/v1/auth/me`、`POST /api/v1/auth/logout`（JWT 无状态，退出即前端丢弃令牌）。
- **鉴权方式**：`Authorization: Bearer <access token>`；任务进度 SSE（`EventSource` 不能改请求头）
  用 `?token=<access token>`。
- **签名密钥**：`.env` 里的 `JWT_SECRET`。留空时用内置开发密钥（启动会打警告），
  生产环境务必配一个随机值，否则重启 / 换机器都等于共享密钥。
- 账号口令用 PBKDF2-HMAC-SHA256（每账号随机盐，24 万次迭代）存储，`app_user` 表里只有散列。
- 登录只作用于 `/api/v1` 与 `/media` 之外的静态文件；`/media/...` 上的成片、参考图仍是直链
  （`<video>` / `<img>` 没法带请求头），需要按账号隔离时再换签名 URL。

### 演示模式

未配置任何密钥时平台自动进入演示模式：

- 镜头 / 提示词 / 音频规划使用 `app/chains/fallback.py` 中的确定性本地规划器：「准备镜头」会按描述与「完善创意」的故事线拼出这条连续画面的描述与提示词；
- 视频生成使用本地 FFmpeg 占位渲染（`app/providers/demo.py`）；
- 完整的「创建项目 → 准备镜头 → 生成视频 → 合成成片」链路可直接跑通。

### 项目工作台

项目列表分页展示（默认每页 10 条，可切 10 / 20 / 50 / 100），按更新时间倒序。任务中心、图片相册
列表同样是默认每页 10 条。接口保持返回裸数组，总数放在 `X-Total-Count` 响应头里，
`GET /projects?limit=10&offset=0` 即分页拉取（`limit` 1–200，`offset` ≥ 0）；
删掉当前页最后几条导致页码超出时会自动回退一页。

### 镜头产物必须是视频

生成的镜头视频不需要封面图。中转站在返回 `video_url` 的同时常附带 `cover_url` / `first_frame_url`，
一旦把封面图当成镜头存下来，合成阶段必然失败。代码在三处拦下：只从视频字段提取地址并排除
图片后缀与封面键；入库前要求产物有可解码视频轨，否则以 `provider_bad_response` 失败；合成前
逐镜头复检并报出「镜头 N 不是可解码视频」。

### 成片片头不留参考图

参考图驱动的图生视频（分镜镜头、抖音成片、主播视频、演唱场景图）第一帧就是提交的那张图，
直接播出来等于拿人物图 / 场景图当封面。所以成片落库前会逐帧跟那张参考图比对开头 2 秒
（`app/integrations/ffmpeg.py` 的 `detect_reference_hold`：SSIM 掉到 0.85 以下就算画面
已经是成片内容；整段窗口都还像参考图就按窗口长度剪），没有参考图可比时退回画面突变检测
（`detect_first_motion`）。剪掉的秒数写进成片备注（「已剪掉开头 X.Xs 定格画面」），
分镜还会同步扣减镜头时长，字幕与音轨时间轴不会整体错位。检测不到要剪的画面、或者转码
失败时按原片入库，这一步永远不会让出片失败。演唱画面是音频驱动、片头本身就在演唱时间轴
上，剪掉会让口型整体偏移，因此不做剪切。

### 完善创意（把简单想法完善成可直接生成的提示词）

用户的一句想法往往只是一个点（有时只有几个字）。项目详情页工具栏的**「完善创意」**按钮会单独
调用大模型，把它完善成**可以直接用于 AI 视频生成的提示词**：

- **完善后的提示词**：一条完整提示词，含视频规格（画幅、时长、声音与字幕安排）、场景、
  人物设定（年龄、外貌、服装、性格、说话方式）、动作表情、人物对白（逐句写清是谁说的）
  与镜头表现（机位、景别、切换方式）；
- **画面推进**：这条提示词按时间顺序压成的一段画面走向（先出现什么、中间怎么变、最后停在哪）；
- **画面提示词**：无标签、单镜头、可直接提交给视频模型的画面描述（「准备镜头」直接用它）。

模型只做「完善」：只能使用用户给出的地点、人物、物件与事件，不得新增人物、情节转折或新场景，
不改变核心想法与人物关系；对白可以写得更口语化、自然，但核心意思不变。镜头自然，不用无意义的
复杂运镜；时长很短（15 秒内）时只聚焦一个瞬间，不塞进多段情节。

它**只产出创意，不准备镜头**，结果写入项目 `enhanced_idea` 与 `shot_prompt`（用户原文 `idea`
不变），并显示在「生成进度」卡片里供人工确认。随后的「准备镜头」会遵循这份创意。
MV 项目请走其自带的「MV 创意完善」入口。

### 逐镜提示词增强

提交视频模型前，`PromptEnhancementChain`（`prompt_enhancement` 提示词）会把镜头画面、
运镜与人物设定整合成**一条**中文提示词，只描述这一条连续画面：

- 结构固定为「主体 → 场景 → 动作 → 镜头语言 → 光影与质感 → 情绪氛围 → 声音」；主体外观与
  人物设定一致，动作写清起势与收势、动作量匹配镜头时长，全程只有一种连续运动；
- 真实感约束：面部与肢体符合运动规律、物体运动符合物理、动作在时长内连续；避免夸张运镜、
  过度磨皮塑料感、光影突变与主体变形（动画 / 幻想风格放宽，但内部规则必须一致）；
- 用可见画面而非抽象词表达情绪（禁止「悲伤 / 震撼 / 电影感」等空词），输出前自检主体、动作、
  场景、形象一致性与动作冲突；只使用给定参数，不编造模型能力；
- 负向约束：不出现文字 / 字幕 / 歌词 / 水印 / 台标 / logo / UI，不切镜转场，不新增人物，
  画面稳定不闪烁、不畸变；
- 运镜固定：所有视频都是单镜头固定机位，不注入运镜描述；
  参考视频抽帧存在时再追加一句「保持与参考图一致的风格、构图与主体形象」；
- 无 LLM 时退回 `fallback.enhance_prompt`，同样带上稳定与规避约束。

MV 演唱镜头不走逐镜增强：提示词由 `prompts/mv.py` 的 `mv_performance` 模板渲染（固定机位、
单条连续演唱画面、全片稳定可循环、规避文字水印；上游接了音频就要求口型与音频同步，
否则靠提示词引导开口）。

### 发布文案（5 条备选 / 推荐正文 / 话题标签）

项目详情页工具栏的**「发布文案」**按钮会为这条片子生成可直接复制发布的文案：

- **备选文案**：一次给 5 条不同风格（推荐版 / 搞笑版 / 悬念版 / 共鸣版 / 互动版），弹窗里可单条复制；
- **推荐正文**：从 5 条里挑出最适合的一条作为主文案写回项目（标题 + 正文，15-30 字为主，
  第一句抓人、结尾自然引导互动）；公众号贴图另收一道 20 字标题上限（提示词与链路都会硬性截断）；
- **话题标签**：3-5 个，不含 `#`（复制时自动补全）。

生成前**必须先选平台**——没选平台时「开始生成」不可点。生成时会把**渠道调性**
（`backend/app/prompts/common/publish_copy.py` 的 `PLATFORM_RULES`）和**片子的实际内容**
（`video_storyboard` 的画面描述 + 对白，逐句引用）一起交给大模型：抖音要强钩子短句、
快手要接地气、小红书要第一人称细节、视频号稳重偏共鸣、B 站像 UP 主介绍自己的作品、公众号贴图直接进画面感；
切换平台不会自动重跑，需要再点一次生成。
短视频项目可选 通用短视频 / 抖音 / 快手 / 视频号 / 小红书 / B 站；图片项目（`kind=image`）另加
**公众号贴图**（公众号图片消息：贴图正文就是这条文案的正文，话题会放到正文最前面，
正文缩进两个空格），
以及 通用图文 / 小红书 / 抖音 / 快手 / 视频号 / B 站。结果写入 `video_project.publish_copy`，
**不改动镜头、视频与项目状态**，MV 项目同样可用。它同时带上「完善创意」的提示词与画面推进，
保证文案写的是片子里真实存在的画面与台词，只换渠道表达方式。

每次生成都会留档：弹窗下半部分是**历史记录**（时间 / 平台 / 标题，可展开查看并单独复制）。
历史直接来自 `video_task(type=publish_copy)` 的成功任务，不额外建表，重复生成与重试都会自然留痕。

### 视频项目都是单镜头（不分镜）

所有视频项目都是**一个场景、一条连续画面**：描述会被直接写成提示词交给视频模型，只生成 1 个
镜头。原来的「多镜头分镜」已移除——多镜头的重排、按镜头重写、`keep_generated` 等能力都不再
提供。镜头步骤叫「准备镜头」，且**可以直接点「生成视频」**——视频入口会自动补齐唯一镜头，
无需先单独跑一次准备镜头。

- 想让内容更细腻/固定，仍可先点「准备镜头」预览并编辑这条镜头的提示词；若先「完善创意」，
  「准备镜头」会调用一次大模型（`single_scene_shot` 提示词），把**完善后的提示词 / 画面推进 /
  画面提示词**拆开作为**唯一依据**逐条落实，写出完整的**画面描述**（180-300 字：主体与外观、
  服饰、动作与对白、环境与时间、光线与色彩、情绪走向）与**画面提示词**（180-320 字：主体→
  动作→环境→光线色彩→镜头与景深→画质→情绪→声音，可直接提交给视频模型），只写细不概括；
  大模型不可用时退回本地拼装（创意 `shot_prompt` → 画面推进）；
  「准备镜头」弹窗的「画面描述」会默认预填完善创意产出的画面提示词（其次画面推进）并标注
  「来自完善创意」，可一键改回原始想法；没改动这个默认值时不下发 `idea`，因此镜头描述不会
  覆盖项目的用户原文 `idea`（它继续供「重新完善创意」以原文为基础）；
- 同一步会把**视频生成参数**算好落库（`video_storyboard.video_params`，上游 VideoRequest 形态：
  `model / prompt / duration / width / height / fps / n / seed / response_format / image / metadata`），
  在镜头列表可见；「编辑镜头」弹窗只展示并允许修改这些参数（提示词 / 时长 / fps / 宽高 / n /
  随机种子 / 模型 / 响应格式），保存后按新值刷新，生成视频时按它们提交（宽高改过则不再提交
  ratio/resolution，避免尺寸互相打架）；
  「完善后的提示词」整体只留在项目 `enhanced_idea` 展示，镜头只取其中的画面部分；
- 目标时长超过模型单段上限（`NEWAPI_VIDEO_MODEL` 决定，如 Seedance mini 15s）时，
  自动按上限拆成若干段分别生成，再用 FFmpeg 无缝拼接成一条镜头，**不会缩水**；
- 重新「准备镜头」会先删除旧镜头并清理它已生成的镜头素材（库记录 + 磁盘文件）；
- 支持关联人物，人物定妆照会作为参考图参与生成。

### 图片生成（图片项目）

如果只想要**一张图**而不是视频，新建项目时选择项目类型「图片」：输入生成要求后即可在项目详情页
出图，流程是 **输入生成要求 →（可选）美化描述 → 生成图片**。

- **美化描述**：调用大模型把一句话要求润色成可直接出图的提示词——只补全构图、光线、色彩、
  材质与风格，不新增用户没提到的主体或情节，也不写运镜/时长/分镜。无 LLM 时退回确定性兜底，
  离线也可用。原始要求保留在 `idea`，美化结果写入 `shot_prompt`（可手动编辑）。
- **生成图片**：走图片 Provider（`NEWAPI_IMAGE_MODEL`，未配置时用演示 Provider），按项目画幅与
  清晰度决定出图尺寸，结果挂到项目并设为项目成片；已生成的图片按分组列出，单张可删除，
  也可「打包下载 ZIP」一次拿走项目里的全部图片（按分组放进不同子目录）。
- **人物一致性**：项目里已有图片时，生成新图会把**最早那张**作为参考图（`image` 参数，本地文件
  内联成 data URI）一起提交，并要求模型保持同一人物的长相、发型与着装，只换姿势、表情和场景。
  上游报 `OutputImageSensitiveContentDetected`（出图结果被判可能含敏感信息，常见于过于逼真的真人面孔）时
  会**自动降级重试**：先去人物参考图，仍被拒就把提示词改成非写实插画风格；降级生成的图会在图卡上打
  「已去掉人物参考图重试」之类的黄标，任务结果里也有 `notes`，不会悄悄换个人。
  面板也可手动取消勾选「沿用参考图」（`use_reference_images=false`）直接走纯文本出图；
  两次降级都不行才如实报错（中文提示 + 保留 Request id 便于排查）。
- **相册改名**：相册就是图片项目，相册列表与出图页都能直接「重命名」（写回项目 `name`）。
- **提交幂等**：出图请求按「相册 + 描述 + 分组 + 参考图设置」生成幂等键，重复点击（或网络重试）
  只会复用进行中的那个任务，返回 `deduplicated=true`，不会重复出图 / 重复扣费；任务跑完后再用同样的
  描述仍可继续生成（每次都会换随机种子，出的是新图）。
- **不重复出图**：同一张要求连着生成时，每次都会带一个**随机种子**（`seed`，上游不支持时自动去掉），
  并按「这是同组第几张」在提示词里追加「换个姿势/景别/背景」的变化要求；出图入库前还会按内容
  SHA-256 查重，和项目里已有图片完全一致就删掉重来（最多 3 次），仍重复才保留并在图卡上标注
  「多次重试仍与已有图片相同」。
- **美化描述支持额外要求**：点「美化描述」会弹窗填写「美化要求」（`extra`，≤1000 字，可留空），
  用来写本次想额外强调的点（如 光线更暖 / 更插画感 / 避免真人面孔）；润色提示词与离线兜底都会带上它，
  留空则只用风格与画幅。弹窗里会显示当前「原始要求」便于对照。
- **描述可手动修改**：出图提示词框随时可改，点「保存描述」写回项目（`shot_prompt`），
  生成时也会自动保存；「美化描述」只是给 AI 润色的快捷方式。
- **分组**：出图前**必须选一个分组**（下拉里是相册已有分组，进页面默认选最近用过的那个），
  没有合适的就点「新建分组」：名字默认 **`年月日` + 描述概括出的 10 个字**（如
  `2026年10月11日海边日落时分一个女孩`），日期走 `IMAGE_GROUP_TIMEZONE`（默认 `Asia/Shanghai`），
  10 个字由大模型按当前描述概括（`image_group_name` 提示词 v1.0.0），没配大模型时用确定性截取
  （去掉「一张 / 图片 / 画面」这类无信息量的词后取前 10 个字），弹窗里预填、可再改。
  参考图按组取：同组看本组最早那张，本组还没有图就沿用项目里最早那张，保证同一个项目里始终是同一个人。
  已生成的图片也能随时改分组（留空=移出分组），勾选多张可整批移动（单张不提供单独的改分组入口）；
  分组还支持**新建空组**与**重命名**（改名时组里的图片一起改名）。
  图片列表按分组展示，**分组按最近出图时间倒序**（最近生成的分组排最前，组内仍是早的在前），
  点「打包下载 ZIP」会弹窗选「按分组打包」（每组建子文件夹，未分组的进 `未分组/`）还是「全部平铺」，
  也可以只下某一组（永远平铺）。
- **分组记录出图描述**：分组同时记住「这批图是用什么描述生成的」（`project.image_group_meta`，
  建组时用当前描述写入、之后每次出图用最新描述覆盖，`created_at` 保留首次时间），
  挪已生成的图片进一个还没描述的分组时，会用那张图的出图描述补上；
  分组说明也能手动改（图片列表里每组的「编辑描述」→ `PUT /projects/{id}/image-groups/description`）。
- **发布文案**：图片项目同样可以生成发布文案（5 条备选 + 推荐正文 + 话题标签）。走的是同一套
  `publish_copy` 提示词（v2.0.0），按 `media=image` 切换口径：说明「单张图片」、不写时长、标签偏图文，
  并且**话题硬性不超过 5 个**（提示词按 `{tag_rule}` 要求 3-5 个，模型多给也会在 `PublishCopyChain` 里截断）。
  图片文案支持**按分组生成**：弹窗里可先选分组，生成时用该分组记录的描述（没记录就退回相册描述），
  生成的文案存在该分组里（`image_group_meta.<组>.publish_copy`），不会覆盖相册级文案；
  历史记录也能按分组过滤，分组里给出「发布文案」入口、生成过文案的组会标「已有文案」。
  公众号贴图弹窗选分组时，候选文案同步切换成该分组的文案。
- **发布到公众号贴图**：相册页可直接把图片发成公众号「图片消息」（贴图）：选全部图片或某个分组，
  先传素材再建 `article_type=newspic` 草稿——**只到草稿箱为止，不调发表接口**（发出去收不回来，
  而发表、原创声明、合集、创作方式声明都得在公众号后台勾）。要到公众号后台确认后手动发表。
  标题默认用相册名（≤64 字；选「公众号贴图」文案时按 20 字收口），正文可留空；
  选了发布文案时，正文按「话题 + 空行 + 缩进两个空格的正文」拼，话题在最前面、正文空两格；一次最多 20 张，非 jpg/png 或超过 10MB 的图会用 ffmpeg
  转成 jpg 再传。发布前在**「公众号」页面**添加公众号（AppID / AppSecret / 作者名，可配多个号、
  发布弹窗里选一个；见下面「公众号配置」），并把服务器出口 IP 加进公众号 IP 白名单，否则会报 40164。
- **公众号配置**：AppID / AppSecret 不再放 `backend/.env`，改在侧边栏「公众号」页面维护：
  可新增 / 编辑 / 删除多个公众号、设默认号、启停，以及「测试连接」（真去拿一次 `access_token`，
  顺带验证 IP 白名单）。AppSecret 存在服务端数据库里、**明文返回给页面**（本地自用：列表直接显示，编辑时带出原文改），保存后立即生效（缓存的 access_token 一并作废）。
  页面下半部分是**草稿箱**（`GET /wechat/drafts`）：列出这个号还没发布的图文 / 图片消息，本系统推的
  小说章节会标出「小说《X》第 N 章」，点「查看」跳后台预览。要直接发就点行里的「发表」
  （`POST /wechat/drafts:publish`，带二次确认）——注意接口发表带不了原创声明 / 合集 / 创作方式声明，
  而且发表是异步的（提交成功 ≠ 发表成功），想带这几项声明请去公众号后台发表。
  页面上还有一份**所有公众号共用的 access_token 获取地址**（`GET|PUT /wechat/settings`，存在
  `app_setting` 表）：只填**一个完整地址**，默认就是官方的
  `https://api.weixin.qq.com/cgi-bin/token`；你要是包装了只提供取 token 的服务，把它的完整地址
  填这里即可（入参与微信原来的完全一样：`grant_type` / `appid` / `secret`），
  素材 / 草稿仍走官方接口（`WECHAT_MP_API_BASE`）。
  首次启动会先把**原始（官方）地址**初始化进这份共用配置；`backend/.env` 里老的
  `WECHAT_MP_APPID` / `WECHAT_MP_SECRET` / `WECHAT_MP_AUTHOR` 只在**首次启动时导入成第一个公众号**
  （库里已有账号就不动），之后请全部在页面上管理。
- **两个 worker 通道**：任务分有序（`lane=serial`）和无序（`lane=parallel`）两条道。
  有序通道单并发、严格按入队顺序一条条跑，小说章节 / 小说封面 / 短剧剧本这类「插队就乱」的活儿走它；
  其余任务（出图 / 视频 / 合成）走无序通道并发跑。`python -m app.worker_main` 默认拉起
  **有序 1 个进程 + 无序 3 个进程**（`WORKER_PARALLEL_PROCESSES`），父进程负责看着子进程、
  挂了自动重拉，收到 SIGINT / SIGTERM 一起收走；只想跑一条道就 `--lane serial` / `--lane parallel`，
  本地调试用 `--processes 1` 就在当前进程里跑。`make backend-worker-serial` / `make backend-worker-parallel`
  是同样的快捷方式。接口进程自己起的 worker（`WORKER_ENABLED=true`）也是两条道一起起。
- **内存吃紧怎么办**（NAS 内存小的时候最有用，按性价比排序）：
  - 减进程：每个 worker 进程的基线约 **90–120 MB**（Python + SQLAlchemy + httpx 的 import 图），
    进程数就是最大的一块开销 —— `WORKER_PARALLEL_PROCESSES` 调小（有序通道固定 1 个）；
    另外 `WORKER_PROCESS_MEM_BUDGET_MB`（默认 160MB）会在启动时按可用内存自动少开几个进程，
    内存不够就先跑得少一点，缓过来再重启（设 0 = 不干预，严格按配置的进程数开）；
  - 降并发：`WORKER_MAX_CONCURRENCY` 控制每个进程同时跑几个任务（默认 2），调小同时省内存和上游配额；
  - 定期换进程：`WORKER_RECYCLE_MAX_TASKS`（默认 80 个任务）和 `WORKER_RECYCLE_MAX_RSS_MB`（默认 600MB）
    让 worker 到点就退休，父进程立刻重拉一个新进程 —— 长跑的 Python 进程很难把内存还给系统，
    定期换进程是最实在的回收方式（只在父进程看护时生效，单进程调试不会自己退出）；
  - 内存闸门：`WORKER_MIN_FREE_MB`（默认 256MB）——系统可用内存低于它时 worker 就不领新任务了，
    任务在队列里排队等（看门狗按卡死线兜底），「慢一点」换「接口不被换页拖死」；
    可用内存读的是容器 cgroup 额度，没设额度就退到宿主机 `MemAvailable`；
    顶满 `WORKER_MEMORY_GATE_MAX_WAIT_SECONDS`（默认 5 分钟）会放行一次，
    机器长期吃紧也只是慢，不会让队列整晚不动；
  - 跑完就还内存：`WORKER_TRIM_RSS_MB`（默认 200MB）——超过它才在任务结束后
    `malloc_trim` + `gc.collect()`（`app/core/memory.py`），把空闲页还给系统，而不是一直攥在进程里；
  - 算力让路：`WORKER_NICE=5` 让 worker 进程降优先级、`FFMPEG_THREADS=2` 限住编码线程数，
    渲染 / 出图再忙也不会把接口和前端卡住（代价是渲染慢一些）；
  - `MALLOC_ARENA_MAX=2`（NAS 的 compose 里已加）：glibc 默认按 CPU 核数开 arena，长跑进程容易碎片化撑大 RSS；
  - SQLite 侧：连接池收到 2 + 3 浮动、每连接页缓存 1MB（本地文件库，开大纯属浪费）；
  - 别开 `NEWAPI_IMAGE_EXTRA={"response_format":"b64_json"}`：出图响应会整张图进内存，
    内存紧的时候用默认的 URL 下载（边下边落盘，不占内存）；
  - 已知还没动的一块：`langchain_openai`（首次调用 LLM 时 import）会给进程多加约 **40 MB**（openai + tiktoken）。
    改成直接用 httpx 打 `/chat/completions` 能省下它，但结构化输出要从 function calling 换成
    `json_object` + 提示词内嵌 schema，得拿真实中转站验过才敢上。
- **出图速度**：出图基本都在等上游返回，因此每个 worker 进程默认并发 2（`WORKER_MAX_CONCURRENCY`，
  内存吃紧可以调到 1）——无序通道 3 个进程就是 6 路并发；队列轮询 0.2 秒（`WORKER_POLL_INTERVAL_SECONDS`）——连着提交多张会并行跑，而不是一张张排队；
  抢占任务用「条件更新 + 影响行数」保证并发下同一任务不会被领两次。上游与素材下载共用一条
  keep-alive 连接池（少一次 TLS 握手）。图片宽高改成读文件头（`app/integrations/imageinfo.py`），
  不再为每张图起一个 ffprobe 进程；查重哈希也挪到线程池，不阻塞事件循环。
  前端出图完成后走任务 SSE 推送立刻刷新（原来固定 4 秒轮询，图早就好了页面还不知道）。
  想再快：`NEWAPI_IMAGE_EXTRA={"response_format":"b64_json"}` 可省掉「拿到 URL 再下载一次」的往返；
  把 `NEWAPI_IMAGE_MIN_PIXELS` 调小能直接降出图耗时（只要上游接受）。
- 图片项目的 `kind=image`，时长/生成方式等视频字段不参与流程；镜头准备、视频生成、合成成片入口
  在该类型下不可用。

对应接口：

- `POST /projects/{id}/image-prompt:enhance` — 美化描述（`{idea?, style?, extra?}`，`extra` 为补充要求），返回 `{prompt, used_llm}` 并保存；
- `POST /projects/{id}/image:generate` — 提交图片生成任务（异步，`type=image`；`{prompt?, group?, use_reference_images?}`）；
- `GET /projects/{id}/images:download` — 打包 zip 下载，`by_group`（默认 1）决定是否按分组建子目录，`by_group=0` 全部平铺；带 `?group=` 只下该组（平铺），文件名直接用组名（`2026年10月11日.zip`）；
- `DELETE /projects/{id}/images/{asset_id}` — 删除一张图片（记录 + 磁盘文件，若是项目成片则清空）。
- `PATCH /projects/{id}/images/{asset_id}` — 单张改分组（保留接口，前端只用批量）；`POST /projects/{id}/images:group` 批量移动；
- `POST /projects/{id}/image-groups` — 新建分组（可空组，`{name, description?}` 一并记下出图描述）；
  `PATCH /projects/{id}/image-groups` 重命名分组；`PUT /projects/{id}/image-groups/description` 改分组说明；
- `POST /projects/{id}/image-groups:suggest` — 给「新建分组」起名（`{idea?}`，留空用相册已保存的描述），
  返回 `{name, used_llm}`，`name` 即「年月日 + 10 个字」；
- `POST /projects/{id}/publish-copy:generate` — 生成发布文案，图片项目同样适用（`{platform?, group?}`，
  带 `group` 时按该分组的描述生成、文案存回分组）；`GET /projects/{id}/publish-copies?group=` 按分组过滤历史；
- `POST /projects/{id}/wechat:newspic` — 发布到公众号贴图
  （`{title?, content?, group?, asset_ids?, account_id?}`，`account_id` 留空用默认号），
  只建草稿不发表；同步返回 `{draft_media_id, image_count, account_id, account_name}`；
- `GET /wechat/status` — 贴图是否可用 + 可选公众号列表 / 默认号（发布弹窗据此提示或禁用按钮）；
- `GET|POST /wechat/accounts`、`PATCH|DELETE /wechat/accounts/{id}` — 公众号账号增删改查
  （列表不回 AppSecret）；
- `POST /wechat/accounts/{id}:check` — 测试连接，返回 `{ok, message}`；
- `GET /wechat/drafts` — 这个号的草稿箱（图文 / 图片消息，可按 `account_id` 换号、翻页）；
  `POST /wechat/drafts:publish` — 直接把某条草稿提交发表（`{media_id, account_id?}`）；
  接口只收 `media_id`：原创声明、合集、创作方式声明带不上去，且发表是异步的（提交成功 ≠ 发表成功），
  要带这几种声明还是去公众号后台发表；
- `GET|PUT /wechat/settings` — 所有公众号共用的 access_token 获取地址（`{token_url}`，完整地址，留空=官方默认）。

### 单场景演唱 MV

MV 使用一张场景图生成一段连续演唱画面，原曲在合成阶段回混成唯一音轨；画面不足整首歌的
部分不会循环补时，缺口超容差直接失败。

演唱画面走已配置的 **New API 中转站视频模型**（`NEWAPI_VIDEO_MODEL`），即 i2v：
场景图 + 演唱提示词。上游不接受音频输入，因此口型由提示词引导，**不是逐字对齐**；
原曲只用于回混与时长基准。需要真正的音频驱动口型时，改用 `sync-3` 或自部署 MuseTalk
（见设计方案 3.3，尚未接入）。

1. 新建「MV 音乐短片」，填写场景创意并上传歌曲。
2. 在项目详情上传一张包含单人和完整场景的图片，或点击「AI 生成场景图」。
3. 查看「演唱模型」卡片：显示实际 Provider、模型、单段时长上限、画幅支持与是否可用。
4. 点击「生成连续演唱视频」。歌曲超过单段上限时接口会显式拒绝；若接受拼接风险，
   勾选「分段实验」后按多段生成再拼接，**不会静默把长歌裁短**。
5. 预览镜头后点击「合成成片」。成片使用原曲音轨，可选烧录 LRC 歌词字幕。

更换歌曲或场景图会使旧演唱镜头失效，需重新生成。未配置 New API 时，场景图仍可准备，
但演唱生成接口会说明缺少的配置；演唱效果须用真实样片验收。

配置真实供应商后自动切换：

```bash
DEEPSEEK_API_KEY=sk-xxx          # 启用真实的创意 / 镜头提示词生成 (DeepSeek 官方)
LLM_BASE_URL=https://newapi.example.com/v1   # 走 New API 中转站 (须带 /v1)
LLM_API_KEY=sk-xxx                           # 中转站密钥
```

### 通过 New API 中转站调用模型

密钥与模型都走 OpenAI 兼容中转站（如 [New API](https://github.com/Calcium-Ion/new-api)）时：

```bash
LLM_BASE_URL=https://newapi.example.com/v1   # 须带 /v1 后缀
LLM_API_KEY=sk-xxx                           # 中转站密钥
LLM_MODEL=deepseek-chat                      # 以 GET {base}/models 返回为准

NEWAPI_BASE_URL=https://newapi.example.com/v1
NEWAPI_API_KEY=sk-xxx

# 视频生成走中转站
NEWAPI_VIDEO_MODEL=veo-3                     # 中转站实际支持的视频模型
VIDEO_PROVIDER=newapi

# 可选：人物参考图也走中转站
NEWAPI_IMAGE_MODEL=gpt-image-1               # 中转站实际支持的图片模型
IMAGE_PROVIDER=newapi
```

- `LLM_BASE_URL` 留空则保持原有 DeepSeek 官方 SDK 行为；`LLM_API_KEY` 留空时依次回退到 `DEEPSEEK_API_KEY`、`NEWAPI_API_KEY`。
- 视频默认请求 `POST {base}/video/generations`、`GET {base}/video/generations/{task_id}`，可用 `NEWAPI_VIDEO_SUBMIT_PATH` / `NEWAPI_VIDEO_QUERY_PATH` 覆盖，特殊字段用 `NEWAPI_VIDEO_EXTRA`（JSON）注入。
- Seedance i2v 要求 `duration >= 5`：MV 单镜头时长不足时按 `NEWAPI_VIDEO_MIN_DURATION`（默认 5）向上取整，保证字幕/音轨时间轴一致。
- 角色参考图若是本地文件会内联为 base64（上游无法访问 `http://localhost:20010` 这类地址）；`image` 只取第一张参考图。
- `NEWAPI_VIDEO_MODEL` 未配置时视频回退演示 Provider（本地 FFmpeg 占位渲染）。
- 图片三项（`NEWAPI_BASE_URL`/`NEWAPI_API_KEY`/`NEWAPI_IMAGE_MODEL`）齐备时自动启用中转站出图，否则回退演示 Provider。

### 插件注册接口（给 Harness 插件一键领 Key）

桌面端 Harness 的 MetaOnticVideo 插件设置页有个「注册并填写」按钮：它调本服务的
`GET /api/v1/register/status`（按钮是否可用）与 `POST /api/v1/register`（领一个新密钥），
拿到 `api_key` / `base_url` / `model` 后自动填进插件配置——用户不用手抄 Key。

服务端要做的只有一件事：在 `backend/.env` 里配好中转站（New API）的**管理端**凭据。

```bash
# 二选一。推荐账号密码：后端自己调 /api/user/login 换 access token
NEWAPI_ADMIN_USERNAME=你的 New API 账号
NEWAPI_ADMIN_PASSWORD=你的 New API 密码
# 或者直接给一个管理端 access token（省一次登录）
NEWAPI_ADMIN_ACCESS_TOKEN=

# 管理端地址；留空时取 NEWAPI_BASE_URL 去掉结尾的 /v1
NEWAPI_ADMIN_BASE_URL=

# 新密钥规格
REGISTER_TOKEN_NAME_PREFIX=metaontic-video   # 只在没填用户名时兜底的密钥名前缀
REGISTER_TOKEN_QUOTA=5000                    # New API 额度单位，500000 = 1 美元，5000 = 0.01 美元
REGISTER_TOKEN_UNLIMITED_QUOTA=false
REGISTER_TOKEN_EXPIRED_DAYS=0                # 0 = 永不过期
REGISTER_TOKEN_GROUP=                        # 留空 = 默认用户组
REGISTER_TOKEN_MODELS=                       # 逗号分隔的模型白名单，留空 = 不限

# 插件请求头 X-Register-Token 要带的值（插件里叫 registerToken，默认同值）
# 注册入口不需要登录，靠这个共享口令挡住随手扫接口的脚本；置空 = 不校验
REGISTER_CLIENT_TOKEN=metaontic-video-register-v1
```

- 注册请求要带 `name`（用户名/昵称）：**它就是中转站里的密钥名**（用户填什么就叫什么，方便后台认领）；
  插件设置页会要求先填这一项，没填时后端才用 `REGISTER_TOKEN_NAME_PREFIX` + 时间戳兜底。
- 默认额度 `REGISTER_TOKEN_QUOTA=5000`，即 **0.01 美元**（New API 的额度单位是 1/500000 美元），
  想多给几条就把它调大（例如 50000 = 0.1 美元）。
- 流程：`POST /api/user/login` 换 `access_token` → `POST /api/token/` 建密钥 →
  某些版本的创建响应不含 key，会自动回退到 `GET /api/token/{id}`，再退化为按名字查 `GET /api/token/`。
- 每次注册都在 `app_relay_registration` 表留一行（token id、名字、设备标识、下单 IP），Key 只在返回给插件时出现，不进日志。
- **不支持重复领取**：同一台设备（`device_id`）或同一个用户名只能领一次，再来返回 409 `register_duplicate`（不会在中转站多开 token）；密钥丢了或额度用完找管理员重置。
- 请求必须带 `X-Register-Token` 头（值 = `REGISTER_CLIENT_TOKEN`），缺失或不匹配一律 403；
  插件目前已领过 Key 时不会再要求填写，只在用户主动点「重新领一把」时才再发请求。
- 没配凭据时按钮置灰并给出提示（`/register/status` 的 `hint` 字段直接说明要配哪个环境变量）。
- 插件的来源是桌面端自定义协议 `ln://app`，已由 `DESKTOP_APP_ORIGINS`（默认 `ln://app,dsh-app://app`）并进 CORS 白名单。

### 抖音视频生成（独立模块）

「抖音视频生成」按**项目**出品，走三步：**第一步完善创意 → 第二步生成 Seedance 提示词 →
第三步生成视频**（对应 [`docs/AI短视频生成步骤.md`](docs/AI短视频生成步骤.md)）。

- **项目维度**：一个项目 = 一条片子。想法、风格、时长 / 画幅 / 清晰度、主角参考图与三步结果
  都保存在 `douyin_project` 上，重新打开项目即可继续；每次第二步生成往 `douyin_video_plan`
  追加一条历史留档（可载入、复制、删除），每次第三步出片往 `douyin_video` 留一条成片记录。
- **第一步「完善创意」**：按「AI 氛围感短视频导演」的角色设定，把一句话想法完善成可拍摄的画面，
  固定输出 **视频主题 / 人物设定 / 场景设计 / 核心动作 / 镜头设计 / 视频风格** 六项，
  写回项目 `creative_json`；带「完善要求」输入框，结果可人工修改，「保存创意」单独落库。
- **第二步「Seedance 提示词」**：把确认后的创意写成一条可直接提交给 Seedance 的完整中文提示词
  （含时长与画幅、人物与穿着、场景、动作、镜头、光影质感、声音与连续性约束），
  并附 **生成注意事项**（容易生成失败的动作与优化建议），写回项目并留档。
- **主角参考图**：项目内可上传 / 替换 / 移除一张主角参考图（`douyin_asset`，JPG / PNG / WebP，
  ≤10MB）；有参考图时提示词会明确要求保持人物五官、发型与服装一致，记录里也标注「参考图：有」。
- **第三步「生成视频」**：把提示词与主角参考图交给中转站的视频模型出片（后台任务，任务中心可看
  进度 / 耗时 / 调用日志）。出片走图生视频：参考图先适配到项目画幅再内联提交，保证成片是选定人物、
  也是目标画幅；参考图被上游安全策略拒绝时自动退回纯文本并把说明记进成片。成片（含时长 / 宽高 /
  体积）存在 `douyin_video`，工作台内可直接播放、复制当次提示词、删除。提示词也可以先复制到
  Seedance 手动出片（接口与错误处理见 [`docs/视频生成调用示例.md`](docs/视频生成调用示例.md)）。
- 时长只支持 **5 / 10 / 15 秒** 三档，画幅默认 `9:16`（可选 16:9 / 1:1 / 3:4），清晰度只有
  `480p`（默认，省额度）/ `720p` 两档。出片参数一律以项目当前设置为准：第二步之后改了画幅 /
  时长 / 清晰度，第三步按新值提交，并把与提示词记录的差异写进成片备注。
  未配置大模型时两步都退回确定性本地兜底，离线可用。
- 提示词在代码里（`backend/app/prompts/douyin/`）：`douyin_creative`、`douyin_seedance_prompt`。
- 接口：`GET|POST /api/v1/douyin/projects`、`GET|PATCH|DELETE /api/v1/douyin/projects/{id}`、
  `POST|DELETE /api/v1/douyin/projects/{id}/reference`、
  `POST /api/v1/douyin/projects/{id}/creative:generate`、
  `POST /api/v1/douyin/projects/{id}/seedance-prompt:generate`、
  `POST /api/v1/douyin/projects/{id}/video:generate`、`GET /api/v1/douyin/projects/{id}/videos`、
  `DELETE /api/v1/douyin/videos/{video_id}`、
  `GET /api/v1/douyin/projects/{id}/plans`、`GET|DELETE /api/v1/douyin/plans/{plan_id}`。

### 视频去水印（独立模块）

侧边栏「视频去水印」：把 AI 生成视频上的角标抹掉，**目前主要处理豆包 16:9 的视频**。
实测豆包 16:9 的片子左上角是「豆包 AI 生成」、右下角是 logo 角标，所以一次可以框**多处**水印一起抹。

- **处理方式**：`delogo` 插值抹除（默认，用四周像素补上、看不出方块）、高斯模糊、马赛克、
  裁掉水印所在的那条边（画面会变窄 / 变矮）。
- **内置预设**：豆包 16:9「左上角 + 右下角」（推荐）、只去左上角、只去右下角、底部通栏（裁掉）。
  预设只是起点，界面上的框按百分比（0-100）随便拖，预览里直接看到框在哪。
- **流程**：选视频（本地预览）→ 框水印 → 提交（HTTP 202）→ 后台 `TaskType.WATERMARK` 任务跑 ffmpeg →
  成片落进对象存储，页面轮询完就能预览与下载；同一参数重跑直接在**任务中心重试**。
- 源片与成片都在 `storage/watermark/` 下（`sources` / `outputs`），记录在 `watermark_job` 表，
  删除记录会把两个文件一起清掉。音轨优先原样复制，容器不兼容才重编码。

### AI 小说（独立模块）

侧边栏「AI 小说」：一个项目一本书，先写世界观、人物档案和大纲，再逐章连续生成（后一章会读前文事实、
承接上一章）。这类活儿是「一章接一章」，走**有序通道单并发**（见「两个 worker 通道」）。

- **标题只有一个章号**：生成 / 导入的标题统一存成「第 N 章 + 纯标题」（中文数字），界面、Markdown 导出、
  公众号文章标题都用这一个标题，不会再出现「第 3 章 第3章 新的选择」这种重复。
- **导入 Markdown / TXT 稿件**：列表页「导入 Markdown」（`POST /novels/import`，新建一本，
  `dry_run=true` 只回解析预览）与工作台章节栏「导入 Markdown」（`POST /novels/projects/{id}/chapters:import`，
  追加到已有小说，章号接着往下排）。按 `# 第一章 xxx` / `第2章 xxx` / `第十二回 xxx` / `Chapter 5 xxx`
  这类章号切章，没有 `#` 的纯文本稿也认；`第 3 章：押车` 这种带分隔符的写法同样能切。
  两个入口都**支持一次多选文件**（表单字段 `files`，多个值；老的单值字段 `file` 仍然兼容）：
  先各自解析，再按稿子里写的章号排序（写不出章号就按上传顺序）并成一条章节流水，最后统一顺序编号落库，
  所以把几卷稿件一起拖进来、顺序反了也不会串章——`chapter_no` 始终等于阅读顺序。
  书名取稿件里的 H1 / 第一行（也可以导入时自己填），正文前的自序够长才单独收一章（卷名、稿约这类
  引用块不算正文），章节末尾「`---` + 引用」的编者注（本阶段结束 / 未完待续）不会并进正文。
  单文件 10MB、一次最多 2000 章，UTF-8（含 BOM）/ GBK 都能读，读不出来或超限会明确报错。
- 导入的章节 `used_llm=false`，落库后可以接着往下生成；**整本书的封面（3:4 竖版）** 与每章那张
  公众号头图（2.35:1）是两回事，历史项目可以手动生成，已生成的能重新生成。
- **批量补章节封面**：章节栏「补齐缺封面（N）」一键把缺的补齐，或「批量生成封面」自己勾章节
  （`POST /novels/projects/{id}/chapters:covers`，`chapter_ids` 留空 = 整本书，`only_missing=false`
  就是选中的全部重出，一次上限 500 章）。一次请求排完整批（不再由前端逐章打接口），
  每章一个任务、带幂等键（重复点不会重复排队，队列里已有的会复用），并走**无序通道**并发出图——
  几十上百张不会把有序通道上的正文生成 / 扩写堵在后面。
- **扩写范围**：工作台「扩写初稿」的「扩写范围」可选**整部小说**，也可以选**指定章节区间**——
  起止章节用带章名和字数的下拉选（`from_chapter_no` / `to_chapter_no`，只给一个就是「从这里到结尾」/「从头到这里」），
  也可以直接在章节面板点「扩写本章」「从本章向后续写」把范围填好。范围选好后卡片上会先算给你看：
  「本次将扩写第 3 — 4 章：范围内 2 章，全部都会扩写」/「…其中 3 章已扩写 / 已达标会跳过，实际扩写 8 章」。
- **扩写初稿（先扩写、再标记，不重复烧 token）**：工作台「扩写初稿」把导入的初稿逐章扩写成正式正文，
  每章落库后都会打上扩写标记（`novel_chapter.expanded_at` + 扩写前字数 `expanded_from_words`），
  界面上标成「已扩写 / 初稿 1.2k → 成稿 3.6k」。之后再点一次（整本书也一样），**已扩写的章节会被跳过**，
  只补还没扩写过的——任务中断重跑就是断点续写；要重写某一批就把「跳过已扩写 / 已达标的章节」取消勾选，
  用 `only_short=false` 一律重写。
- **作者跟着公众号走**：发布弹窗的作者默认带出**所选公众号配的作者**（`wechat_mp_account.author`，
  在「公众号」页面里填），**切换公众号就自动更新**；接口侧同样兜底（`author` 留空时用该号的作者），
  所以批量发出去的文章不会出现空作者。手填的作者只作用于本次发布。
- **批量发公众号草稿**：`POST /novels/projects/{id}/chapters:wechat-publish`，一章一篇、按章号顺序推，
  缺封面的章节顺带排一张封面任务；标题前缀默认 `《书名》`，标题里不会重复出现章号。
- 删除小说 / 删除章节会把章节、封面文件和生成任务一起清掉（后面章节自动重新排号）。

### 提示词（全部在代码里）

所有提示词都是 `backend/app/prompts/` 下的版本化模板（每个模块一个子包 + `registry.py` 注册）：
完善创意、单场景镜头、发布文案、MV 创意与演唱提示词、出图描述增强、分组命名、人物定妆照、
美妆四件套、抖音创意与 Seedance 提示词等。改文案就是改代码，改完重启后端生效。

- 每份模板带 `name` / `version`，调用时写进 `ai_call_log`（连同提示词哈希），出问题能定位到版本。
- 不再有网页端提示词编辑 / 覆盖：没有 `agent_prompt` 表，也没有 `/api/v1/agents` 接口。

### 任务中心（大模型调用都留痕）

`video_task` 是唯一的任务表（`GET /api/v1/tasks`，前端 `TasksView.vue` 按类型过滤）：
`storyboard` / `publish_copy` / `image` / `video` / `audio` / `lip_sync` / `render` / `beauty` / `watermark`
走 worker 队列，`llm` 则是**请求里同步跑完**的大模型调用 —— 美化描述、分组命名、抖音完善创意、
Seedance 提示词、商品理解。

- 同步调用不进队列，但开始 / 结束时各写一次任务事件并提交：任务中心看得到它，
  `started_at` / `finished_at` / `result_json` 都是真实值，`ai_call_log.task_id` 挂在它下面，
  「费用（token）」列与后台任务同一套汇总逻辑。
- 调用失败时先回滚请求事务、再用独立会话补一条 failed（写明原因）：请求报错后任务中心仍留得下这次失败。
- 这类任务没有「重试 / 取消」（`POST /tasks/{id}/retry|cancel` 返回 409）：结果已经当场返回页面，
  在页面上重新点一次即可，排队重跑没有意义。

## 目录结构

```text
backend/app/
  api/v1/        # projects/storyboards/characters/tasks/assets/providers/douyin
  core/          # 配置、日志、错误、枚举
  db/            # 引擎、会话、Base
  models/        # SQLAlchemy ORM
  schemas/       # Pydantic DTO
  repositories/  # 数据访问
  services/      # 业务服务、任务编排、渲染
  chains/        # LangChain 调用链 + 本地回退
  prompts/       # 版本化提示词，每主题一个模块 + registry 注册（带 hash）
  providers/     # New API 中转站 / 演示 Provider 适配器
  workers/       # 任务 Worker
  integrations/  # FFmpeg、存储、SSRF 安全下载
frontend/src/
  api/           # Axios 封装
  views/         # 工作台 / 项目详情 / 人物 / 任务 / 抖音视频生成 / 供应商
  stores/        # Pinia（任务 SSE 流）
  router/  types/  utils/
storage/         # 本地素材、成片、字幕
docs/            # 设计方案
backend/scripts/ # 工具脚本（gen_er_diagram.py 生成数据表关系图）
```

数据表关系图：[`docs/数据表关系图.md`](docs/数据表关系图.md)（含 Mermaid 源与
`docs/images/数据表关系图.svg`），由 `backend/scripts/gen_er_diagram.py` 读 SQLAlchemy
元数据自动生成，表/字段注释直接取自模型，改完模型重跑脚本即可同步：

```bash
cd backend && uv run python scripts/gen_er_diagram.py
```

图片生成接口调用示例（通用，不依赖本项目代码：curl / Python / Node 的
「提交 → 轮询 → 取件」三步调用、参考图、错误处理）：
[`docs/图片生成调用示例.md`](docs/图片生成调用示例.md)

AI 短视频生成三步流程（提出简单创意 → AI 完善创意并生成提示词 → 调用视频模型生成），
含提示词模板：
[`docs/AI短视频生成步骤.md`](docs/AI短视频生成步骤.md)

视频生成接口调用示例（同样不依赖本项目代码：curl / Python / Node 的
「提交 → 轮询 → 取件」三步调用、参考图、参数表、状态与错误处理）：
[`docs/视频生成调用示例.md`](docs/视频生成调用示例.md)

Harness 桌面端插件的**服务端已独立部署**（发密钥 / 查额度 / 控制台），代码在同级目录的
`MetaOnticVideoService` 项目（FastAPI + Vue3 + Element Plus）：
`../MetaOnticVideoService/docs/插件服务架构.md`（配图 `../MetaOnticVideoService/docs/images/插件服务架构图.svg`）。
本项目不再提供 `/api/v1/register/*` 接口。

## 测试

```bash
cd backend && uv run pytest -q
```

覆盖：健康检查、统一响应信封与链路 ID、Chain 回退结构、完整项目流水线（准备镜头 → 生成视频 → 合成）、任务生命周期。

## 数据库迁移

开发环境 `AUTO_CREATE_TABLES=true` 会自动建表。生产建议使用 Alembic：

```bash
cd backend
uv run alembic revision --autogenerate -m "init schema"
uv run alembic upgrade head
```

## 部署

线上环境：`root@124.223.72.223`，代码目录 `/home/biu/video`，前后端共用域名 `https://video.mybfs.cn`。

```bash
make deploy                 # 或 ./deploy/deploy.sh
./deploy/deploy.sh --help   # --skip-build / --skip-install / --no-restart / --dry-run
```

脚本做四件事：

1. 本地 `npm run build` 生成 `frontend/dist`；
2. `rsync` 覆盖式同步代码到 `/home/biu/video`（排除 `.git`/`.venv`/`node_modules`/`storage` 等生成物）；
3. 远端用 `uv` 安装依赖（uv 自动拉取项目所需的 Python ≥3.12），首次部署从 `.env.example` 生成 `backend/.env`，并把 `PUBLIC_BASE_URL` 指向 `https://video.mybfs.cn`；
4. 渲染 `deploy/videoflow-api.service` 写入 systemd，重启并通过 `/health` 做健康检查。

后端由 `videoflow-api.service` 监听 `127.0.0.1:20010`；nginx 站点与证书由其它项目统一维护，需要指向本项目的部分为：

- 静态站点 root → `/home/biu/video/frontend/dist`（SPA 回退 `index.html`）；
- `/api`、`/media` 反向代理到 `http://127.0.0.1:20010`，并放开上传体积（`MAX_UPLOAD_MB` 默认 200）。

服务器上尚未安装 `ffmpeg`，演示渲染与成片合成需要时执行 `dnf install -y ffmpeg`。

## 关键设计

- **LangChain 管理语言模型链路，Worker 管理异步多媒体任务，FFmpeg 负责最终合成。**
- **统一响应格式**：`/api/v1` 全部返回 `{code, data, message}`（成功 `code=0`；失败 `code` 等于 HTTP 状态码，另有机器码 `error_code` 与校验失败时的 `details`）。SSE 进度流、`/media`、`/health` 保持原样，前端在 axios 拦截器里统一拆信封。
- **链路追踪**：每个响应带 `X-Request-ID`（可传入覆盖）；日志每行为 `[时间] [级别] [链路ID] logger | 消息`，后台任务直接用任务 UUID 作链路 ID，与 `ai_call_log.trace_id` 对齐，一个 ID 可检索完整链路。
- 所有供应商通过 Provider 适配器封装（`app/providers/base.py` 中的 Protocol）。
- 音频优先使用视频模型原生音频；不足时独立生成，对白镜头标记口型同步需求。
- 人物形象库版本化：修改外观类字段自动提升版本，旧项目锁定原版本；人物可删除（参考图与文件一并清掉，被项目引用时返回 409 并说明是哪些项目，也可以改为归档 / 恢复）。
- 任务、素材、模型调用日志从第一版即持久化，支持重试、取消、幂等与成本核算。
- **登录鉴权**：`/api/v1` 除 `/auth/login`、`/auth/refresh` 外都要带 JWT（`Authorization: Bearer`，SSE 用 `?token=`）。access token 10 分钟、refresh token 7 天，前端到期前自动续期。账号由脚本创建（`make create-user`），系统不开放注册。
- 密钥仅存于服务端环境变量；`model_provider_config` 只保存 `secret_ref`。
- 供应商素材下载做 SSRF 校验（禁内网/保留地址，可配白名单）。