你是一个资深 Python / AI Infra / 推理服务工程师。你的任务不是讨论方案，而是**直接在本地完成一个可运行的项目**。

# 任务目标

在 **WSL2 + Ubuntu + NVIDIA RTX A4000 16GB** 环境下，开发一个 **本地单机视频生成 Worker 服务**，只做一件事：

> 接收一次视频生成请求 → 根据模式选择模型 → 在 A4000 上执行推理 → 输出视频文件 → 返回任务状态与结果路径。

这个 Worker 是一个**边缘执行节点**，不是完整平台。

---

# 必须遵守的边界

## 只做这些

* 提供本地 HTTP API
* 接收 text-to-video 请求
* 使用本地模型推理
* 单任务串行执行
* 输出固定目录结构
* 支持两种模式：

  * `preview` → `LTX-Video`
  * `refine` → `HunyuanVideo-1.5`

## 不要做这些

* 不做脚本生成
* 不做分镜拆解
* 不做 prompt 自动生成
* 不做剪辑
* 不做 ComfyUI 集成
* 不做多机调度
* 不做前端页面
* 不做复杂鉴权
* 不做 image-to-video
* 不做 video extend
* 不做数据库集群
* 不做消息队列中间件

---

# 最终交付物

你必须直接生成一个完整可运行项目，至少包含：

1. 项目源码目录
2. `requirements.txt`
3. `.env.example`
4. `README.md`
5. `scripts/install_wsl_env.sh`
6. `scripts/run_server.sh`
7. `scripts/smoke_test.py`
8. FastAPI 服务源码
9. SQLite 任务存储
10. 单 worker 串行队列
11. 模型路由器
12. `LTX` backend
13. `Hunyuan` backend
14. 统一输出目录
15. 基础日志
16. 错误处理
17. 健康检查接口

---

# 技术要求

## 基础技术栈

* Python 3.10+
* FastAPI
* Uvicorn
* Pydantic
* SQLite
* asyncio
* ffmpeg
* torch
* diffusers / transformers / accelerate / safetensors（按需要引入）
* WSL2 下通过 CUDA 调用 A4000

## 代码要求

* 代码必须结构清晰
* 所有核心模块必须可直接运行
* 不要只写伪代码
* 必须包含真实可执行代码骨架
* 重要处要有注释
* 要考虑异常处理
* 要考虑模型懒加载
* 要考虑单卡显存限制
* 所有路径都要可配置
* 配置统一放到 `settings.py` 和 `.env`

---

# 系统架构

实现下面这个最小架构：

```text
Client
  -> FastAPI
  -> TaskManager
  -> ModelRouter
  -> GPUWorker
  -> Backend(LTX/Hunyuan)
  -> OutputWriter
  -> outputs/{task_id}/video.mp4
```

---

# 模型路由规则

固定规则：

* `quality_mode = "preview"` → `LTX-Video`
* `quality_mode = "refine"` → `HunyuanVideo-1.5`

请把模型路由实现成独立模块，后续方便替换。

---

# 任务状态

只保留这些状态：

* `PENDING`
* `RUNNING`
* `SUCCEEDED`
* `FAILED`

不要额外扩展复杂状态机。

---

# API 设计

你必须实现以下接口。

## 1）创建任务

### `POST /generate`

请求体：

```json
{
  "prompt": "a lonely man walking in a rainy neon street, cinematic, handheld camera",
  "negative_prompt": "blurry, deformed face, extra limbs, flicker",
  "quality_mode": "preview",
  "duration_sec": 5,
  "width": 832,
  "height": 480,
  "fps": 16,
  "steps": 8,
  "seed": 123456
}
```

要求：

* 自动生成 `task_id`
* 写入 SQLite
* 入队
* 返回 `task_id` 和状态

---

## 2）查询任务状态

### `GET /tasks/{task_id}`

返回：

* `task_id`
* `status`
* `backend`
* `model_name`
* `progress`
* `created_at`
* `updated_at`

---

## 3）查询任务结果

### `GET /tasks/{task_id}/result`

成功时返回：

* `task_id`
* `status`
* `video_path`
* `first_frame_path`
* `metadata_path`
* `log_path`

失败时返回：

* `task_id`
* `status`
* `error`

---

## 4）健康检查

### `GET /health`

返回：

* 服务状态
* CUDA 是否可用
* GPU 名称
* 两个模型是否已加载

---

# 输入参数约束

第一版严格限制：

* 只支持 text-to-video
* `duration_sec` 允许 1~5
* `width` 最大 832
* `height` 最大 480
* `fps` 最大 24
* `quality_mode` 只允许 `preview` 或 `refine`

你需要在 Pydantic schema 中严格校验。

---

# 输出目录规范

每个任务固定输出到：

```text
outputs/{task_id}/
  ├─ video.mp4
  ├─ first_frame.jpg
  ├─ metadata.json
  └─ run.log
```

其中：

## `metadata.json`

至少包含：

* task_id
* backend
* model_name
* prompt
* negative_prompt
* seed
* width
* height
* fps
* steps
* duration_sec
* status
* created_at
* started_at
* finished_at
* video_path

---

# 目录结构要求

按下面结构生成项目：

```text
video_worker/
├─ app/
│  ├─ main.py
│  ├─ api.py
│  ├─ schemas.py
│  ├─ settings.py
│  ├─ task_manager.py
│  ├─ model_router.py
│  ├─ gpu_worker.py
│  ├─ task_store.py
│  ├─ backends/
│  │  ├─ base.py
│  │  ├─ ltx_backend.py
│  │  └─ hunyuan_backend.py
│  └─ utils/
│     ├─ files.py
│     ├─ ffmpeg_utils.py
│     ├─ image_utils.py
│     └─ logger.py
├─ models/
│  ├─ ltx/
│  └─ hunyuan/
├─ outputs/
├─ runtime/
│  ├─ tasks.db
│  └─ logs/
├─ scripts/
│  ├─ install_wsl_env.sh
│  ├─ run_server.sh
│  └─ smoke_test.py
├─ requirements.txt
├─ .env.example
└─ README.md
```

---

# 模块职责

## `schemas.py`

定义：

* `GenerateRequest`
* `TaskStatusResponse`
* `TaskResultResponse`
* `HealthResponse`

---

## `task_store.py`

使用 SQLite 存储任务信息，至少包含：

* `task_id`
* `status`
* `backend`
* `model_name`
* `request_json`
* `output_dir`
* `error_message`
* `created_at`
* `updated_at`

---

## `task_manager.py`

负责：

* 创建任务
* 写入数据库
* 入队
* 更新状态
* 查询状态与结果

---

## `gpu_worker.py`

负责：

* 后台单线程取任务
* 标记任务为 RUNNING
* 调用路由器选择 backend
* 执行生成
* 写入结果
* 成功标记 SUCCEEDED
* 失败标记 FAILED

要求：

* 必须是**单任务串行**
* 不允许多任务并发占用 GPU

---

## `model_router.py`

根据 `quality_mode` 返回 `ltx_backend` 或 `hunyuan_backend`

---

## `backends/base.py`

定义统一接口：

* `load()`
* `is_loaded()`
* `generate(task)`

---

## `backends/ltx_backend.py`

要求：

* 实现懒加载
* 作为默认 preview 模型
* 重点保证代码结构正确
* 若本地真实模型推理接入较复杂，可先封装清晰的推理入口与参数映射，但不要省略真实调用预留位
* 输出必须符合统一目录规范

---

## `backends/hunyuan_backend.py`

要求：

* 实现懒加载
* 作为 refine 模型
* 保留 `cpu offload`、`vae tiling` 等内存优化入口
* 输出必须符合统一目录规范

---

## `utils/ffmpeg_utils.py`

必须实现：

* 如果 backend 输出帧序列，则合成为 `video.mp4`
* 从 `video.mp4` 抽取 `first_frame.jpg`

---

# 运行原则

## 1）模型懒加载

* 服务启动时不要强制加载所有模型
* 第一次调用对应 backend 时再加载
* 加载后常驻

## 2）单任务串行

* A4000 16GB 只允许一个视频任务同时运行
* 必须实现内存队列 + 单 worker

## 3）先支持 preview，再支持 refine

* 但代码结构里两个 backend 都要存在
* 如果某个 backend 先以占位实现，也必须说明后续替换点

---

# 配置要求

在 `.env.example` 中提供以下配置项：

```env
APP_HOST=0.0.0.0
APP_PORT=8000
OUTPUT_DIR=./outputs
RUNTIME_DIR=./runtime
SQLITE_PATH=./runtime/tasks.db

LTX_MODEL_DIR=./models/ltx
HUNYUAN_MODEL_DIR=./models/hunyuan

DEFAULT_WIDTH=832
DEFAULT_HEIGHT=480
DEFAULT_FPS=16
DEFAULT_DURATION=5
DEFAULT_STEPS_PREVIEW=8
DEFAULT_STEPS_REFINE=12
```

---

# README 必须包含

1. 项目说明
2. 环境准备
3. WSL + CUDA 检查方法
4. 安装命令
5. 启动命令
6. 调用示例
7. 目录说明
8. API 说明
9. 常见问题
10. 已知限制

---

# 安装脚本要求

## `scripts/install_wsl_env.sh`

需要完成：

* 创建 Python venv
* 升级 pip
* 安装 requirements
* 安装 ffmpeg
* 创建输出目录
* 创建 runtime 目录
* 给出后续启动提示

---

# 启动脚本要求

## `scripts/run_server.sh`

需要完成：

* 激活 venv
* 检查 `.env`
* 启动 uvicorn

---

# 烟雾测试要求

## `scripts/smoke_test.py`

需要完成：

* 调用 `/health`
* 创建一个 `preview` 任务
* 轮询任务状态
* 打印结果路径

---

# 开发顺序

严格按这个顺序实现：

## Phase 1

* 建目录
* 写 `settings.py`
* 写 `schemas.py`
* 写 `task_store.py`
* 写 `task_manager.py`
* 写基础 API
* 写 SQLite 初始化
* 写单 worker 队列

## Phase 2

* 写 `model_router.py`
* 写 `backends/base.py`
* 写 `ltx_backend.py`
* 打通 preview 路由
* 输出 `video.mp4 / metadata.json / run.log`

## Phase 3

* 写 `hunyuan_backend.py`
* 打通 refine 路由
* 增加 `/health`
* 增加 ffmpeg 抽帧

## Phase 4

* 完善 README
* 完善脚本
* 完善错误处理
* 完善 smoke test

---

# 验收标准

你完成后，必须满足以下条件：

1. 项目可直接启动
2. `GET /health` 可用
3. `POST /generate` 可创建任务
4. 任务会进入 `PENDING -> RUNNING -> SUCCEEDED/FAILED`
5. preview 模式能真正走 `LTX backend`
6. refine 模式能真正走 `Hunyuan backend`
7. 输出目录结构正确
8. `metadata.json` 完整
9. 失败时有明确错误信息
10. 代码结构足够清晰，后续方便替换真实模型实现

---

# 输出要求

你现在直接开始产出代码与文件内容，不要继续解释方案，不要重复需求，不要空谈架构。

请按下面顺序输出：

1. 项目目录树
2. 每个文件的完整内容
3. 最后给出运行步骤

要求所有内容都尽可能完整，可复制使用。