# YEEX Shorts 本地运行手册

## 目标

本文件替代旧的上游 Colab notebook。YEEX Shorts 当前以本机开发、小程序测试和后续云端部署为主。

项目最终要支持 Web、iOS、Android APK、微信小程序四端上线。当前本地运行优先验证后端 API、小程序 MVP 和 WebUI 调试入口。

当前更完整的本地自用生产流程见：

```text
docs/local-production-workflow.md
```

Claude / Antigravity / Codex 协作入口见：

```text
docs/agent-collaboration-board.md
```

## 本地预检

真实生成前先跑：

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

预检只检查配置、目录、API 健康和常见本地依赖，不创建视频任务。

## 本地控制台

日常启动和状态检查推荐使用：

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

状态报告会写到：

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

## 本机项目盘与外接产物盘

YEEX Shorts 的重要文件继续保存在 Mac 本机项目目录：

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

这里包括源代码、`config.toml`、环境配置、密钥、本地数据库、后台设置、Git 仓库和项目文档。不要把这些内容迁到外接硬盘。

外接硬盘只用于体积大、可重新生成或可清理的产物：

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

这里放生成视频、测试物料、本地素材库、素材缓存和临时渲染文件。真实生成前预检会检查 `app.generated_storage_dir` 是否指向外接盘；任务启动入口也会再次硬拦截，外接盘未挂载、误写 Mac 本机目录、目录不可写或剩余空间不足时直接失败，不会静默写回 Mac 内置硬盘。

## 本机 API

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

验证：

```shell
curl http://127.0.0.1:8080/api/v1/miniapp/presets
```

## 本机 WebUI

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

访问：

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

## 小程序

用微信开发者工具打开：

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

本地开发时可以关闭合法域名校验。上线前必须替换为 HTTPS 云端 API 并配置合法域名。