# YEEX Shorts 本地自用生产线

本文件只服务当前阶段：先把本机能稳定生产短视频做扎实。Web、iOS、Android APK、微信小程序上线是最终目标，但这几端暂时不抢优先级。

## 当前目标

先做到 Susan 自己可用：

1. 本机能启动 API。
2. 本机能打开 WebUI。
3. 能用一个主题生成一条 9:16 短视频。
4. 能找到生成产物。
5. 失败时知道最短恢复动作。
6. Claude、Antigravity、Codex 各自审查同一批材料，不互相覆盖。

## 开工前 Gate

每次真实生成前先跑：

```shell
uv run python scripts/local_preflight.py
```

看结果：

- `PASS`：可以继续。
- `WARN`：可以本地调试，但真实生成前要看清提示。
- `FAIL`：先停，不提交生成任务。

预检不会发起付费生成，不会创建视频任务。

常见 `WARN`：

- `ImageMagick` 缺失：字幕描边、透明字幕背景或封面处理可能受影响。Mac 上可运行 `brew install imagemagick`，修复后重新跑 `uv run python scripts/local_preflight.py`。

## 一键本地控制台

推荐日常只记这一组命令：

```shell
uv run python scripts/local_operator.py status
uv run python scripts/local_operator.py preflight
uv run python scripts/local_operator.py start-api
uv run python scripts/local_operator.py start-webui
uv run python scripts/local_operator.py start-all
uv run python scripts/local_operator.py review-pack
uv run python scripts/local_operator.py stop
```

它会把本地状态报告写到：

```text
.local/yeex-shorts/status.md
```

日志会写到：

```text
.local/yeex-shorts/logs/
```

Claude / Antigravity 审查包会写到：

```text
docs/agent-review-packet.md
```

如果要让外部代理直接参与本轮检查，用下面两个限时入口。它们只发送小上下文和安全摘录，结果保存在本机 `.local/yeex-shorts/agent-reviews/`，不会提交到 Git：

```shell
uv run python scripts/local_operator.py claude-review --topic "支付、审核、账号删除红线复核"
uv run python scripts/local_operator.py antigravity-review --topic "移动 H5 和后台 UI 体验复核"
```

Claude 入口只做红线复核；如果返回内容不按固定格式、陷入读文件循环、超时，或 CLI 退出但没有正文输出，本轮不会计为“Claude 已评审”。Antigravity/`agy` 也一样：没有正文就不能计为有效体验复核。这两个入口会调用外部代理 CLI，可能消耗对应账号额度；真实生成和上线发布仍必须单独走预检门禁。

本地后端管理方案见：

```text
docs/local-admin-management.md
```

配置红灯修复见：

```text
docs/local-config-setup.md
```

对外上线边界见：

```text
docs/external-usage-boundary.md
```

## 本地启动

## 本地入口分工

本地先按真实产品习惯拆成两个入口：

| 入口 | 用途 |
| --- | --- |
| `http://127.0.0.1:8501/` | 创作前台，只做主题、脚本、素材、配音和生成 |
| `http://127.0.0.1:8080/` | 本地管理控制台，查看 API Key 配置状态、会员/收费后台骨架、素材库、队列、任务和样片 |

API Key、模型供应商、素材源 Key、字幕/TTS、会员套餐、额度、订单、队列和成本控制都属于管理设置，不再默认塞进创作前台。旧版 WebUI 全量设置仅作为临时调试入口保留：`http://127.0.0.1:8501/?settings=1`。

### 1. 启动 API

```shell
uv run python scripts/local_operator.py start-api
```

打开：

```text
http://127.0.0.1:8080/
```

API 文档：

```text
http://127.0.0.1:8080/docs
```

### 2. 启动 WebUI

另开一个终端：

```shell
uv run python scripts/local_operator.py start-webui
```

打开：

```text
http://127.0.0.1:8501
```

## 本地生产步骤

1. 先写一个清楚主题，例如：`普通人怎么用 AI 做一条副业短视频`。
2. 如果要控制文案，就填自定义旁白；否则让系统自动写。
3. 默认生成 9:16，一条视频，30-60 秒。
4. 先用 WebUI 自测，稳定后再走小程序入口。
5. 生成完成后，到任务目录找产物。

Susan 本机默认把生成产物放到外接硬盘，避免占用 Mac 内置硬盘：

```text
/Volumes/AI视频素材库/Susan_AI_产出库/YEEX Shorts/storage/tasks/
```

注意：这里说的外接硬盘只放生成出来的视频、缓存素材、本地素材库、临时渲染等大文件。源代码、`config.toml`、后台配置、密钥和本地数据库仍保留在 Mac 上的项目目录：

```text
/Users/susansokin/Desktop/code/myshorts/
```

也就是说：外接硬盘是“产物盘”，不是“项目盘”。以后新增视频废料、测试物料、素材缓存、渲染临时文件时优先放外接硬盘；新增代码、后台配置、密钥文件、数据库迁移和项目文档时仍留在 Mac 项目目录。

每次任务会生成一个独立任务目录，里面通常包含素材、字幕、中间文件和最终视频。现在任务启动入口也会检查外接硬盘：如果产物目录没有指向已挂载外接盘、目录不可写或剩余空间不足，任务会直接失败并提示处理，不会把大文件偷偷写到 Mac 系统盘。

## 本地素材优先测试

如果还没有 Pexels / Pixabay / Coverr Key，可以先用本地素材测试：

1. 在 `config.toml` 里把 `[app] video_source` 改成 `local`。
2. 如果手头没有素材，先运行 `uv run python scripts/local_operator.py seed-local-materials`。
3. 如果不想手动改配置，运行 `uv run python scripts/local_operator.py use-local-materials`。
4. 启动 WebUI。
5. 在视频来源里选 `Local file`。
6. 上传几段视频或图片，或复用刚生成的本地测试素材。
7. 再提交第一条测试任务。

本地素材库目录：

```text
/Volumes/AI视频素材库/Susan_AI_产出库/YEEX Shorts/storage/local_videos/
```

8080 本地控制台会显示本地素材库数量。如果本地素材库为空，先补素材，再做真实生成测试。

## 模型 Key 临时替代路线

如果还没有 OpenAI / DeepSeek / Qwen / Gemini 等模型 Key，可以先试用 Pollinations：

```shell
uv run python scripts/local_operator.py use-pollinations-model
uv run python scripts/local_operator.py preflight
```

预检通过后，才继续进入 WebUI 做本地样片。Pollinations 依赖公网服务，只适合本机冒烟测试；正式上线前仍建议换成可控的正式模型供应商。

## 一键本机样片

模型和本地素材预检通过后，可以先不用打开 WebUI，直接生成一条本机样片：

```shell
uv run python scripts/local_operator.py smoke-video
```

这个命令会使用本地测试素材、中文默认配音、无字幕、无背景音乐，产物会写到：

```text
/Volumes/AI视频素材库/Susan_AI_产出库/YEEX Shorts/storage/tasks/
```

它的目的只是验证本机能完整产出 MP4。样片画面是测试素材，不代表最终产品风格。

生成成功后，打开 8080 控制台：

```text
http://127.0.0.1:8080/
```

在“最近本地样片”里可以直接点“预览”或“下载”。

同一个页面的“会员与收费后台骨架”会显示：

- 未来后台模块：用户、会员、额度、订单、任务、成本、配置、审计。
- 套餐蓝图：体验版、创作者版、专业版。
- 收费准备清单：登录、扣减、支付回调、成本统计、审计。

这些只是本地只读规划，不代表已经接入真实收费。

发布平台凭据可以在后台配置中心登记状态，但自动发布当前保持关闭。正式接入前必须先补用户平台授权、内容审核通过后的人工确认/幂等发布动作、AI 生成披露文案和发布回执台账。

同一个页面的“最近任务”会显示：

- 当前任务是生成中、已完成还是失败。
- 当前阶段，例如准备配音、准备素材、合成视频。
- 进度百分比和进度条。
- 完成后的预览/下载按钮。
- 失败后的最短恢复动作。

## 失败恢复

| 现象 | 先做什么 |
| --- | --- |
| API 页面打不开 | 重新启动 `uv run python main.py` |
| WebUI 打不开 | 运行 `uv run python scripts/local_operator.py start-webui`，它会自动跳过 Streamlit 首次邮箱提示 |
| 主题提交失败 | 把主题写具体一点，再重试 |
| 素材找不到 | 换素材源，或补 Pexels / Pixabay / Coverr key |
| 配音失败 | 检查 TTS provider 和网络 |
| 视频合成失败 | 先看任务目录和终端日志，不整项目重装 |
| 保存失败 | 先确认最终视频文件是否已经在外接硬盘的 `YEEX Shorts/storage/tasks/` |

失败时只修最近一层，不整集重跑，不重装环境。

## 三个助手怎么协作

每轮修改前先看分支审查记录：

```text
docs/agent-branch-review.md
```

如果 GitHub 上有新的 Claude / Antigravity 分支，先对比它们的建议，再由 Codex 收口成代码和文档。

### Claude

Claude 负责判断产品和文案：

- 主题是否适合做短视频。
- 旁白是否像真人会说的话。
- 用户失败提示是否看得懂。
- 当前功能是否偏离“本地先能用”。

给 Claude 看：

```text
docs/agent-review-packet.md
docs/claude-review-brief.md
docs/claude-product-review.md
docs/local-production-workflow.md
```

### Antigravity

Antigravity 负责前端体验：

- 8080 入口页是否符合 YEEX 深色毛玻璃风格。
- WebUI 和小程序首屏是否清楚。
- 生成中、失败、完成、保存状态是否明显。
- 普通用户是否知道下一步点哪里。

给 Antigravity 看：

```text
docs/agent-review-packet.md
docs/antigravity-review-brief.md
docs/项目修改总控.md
resource/public/index.html
miniapp/pages/index/
```

### Codex

Codex 负责执行和验证：

- 改代码。
- 跑测试。
- 修 GitHub Actions / Docker。
- 写本地预检。
- 保持文档和代码一致。

Codex 每次收口前至少跑：

```shell
uv run python scripts/local_preflight.py
uv run python scripts/local_operator.py status
uv run --with pytest pytest
```

## 当前不做

- 不先做 iOS App。
- 不先做 Android APK。
- 不先提交微信小程序审核。
- 不先做复杂会员系统。
- 不先做全平台自动发布。
- 不把本机 8080 或 WebUI 当正式公网后台。

这些等本地生产闭环稳定后再进入下一阶段。