# LLM 媒体服务器 — 需求文档（中文对照版）

## 项目概述

一个自托管的视频媒体服务器，使用 LLM 对个人视频库（电影、电视剧、家庭录像）进行自动索引、标签分类、元数据生成与字幕生成。参考 Plex/Jellyfin 设计，但深度集成 LLM 能力。支持 Docker 或裸机部署。

---

## 1. 功能需求

### 1.1 媒体摄入与库管理
- [ ] 监听配置目录，自动发现新媒体文件
- [ ] 支持格式：MKV、MP4、AVI、MOV、WEBM、TS
- [ ] 文件指纹识别，防止重复入库
- [ ] 按类型组织库：电影 / 电视剧 / 家庭录像
- [ ] 本地数据库存储库状态（SQLite 或嵌入式数据库）

### 1.2 LLM 自动分类
- [ ] 根据文件名与视频内容识别类型（电影、电视剧集、家庭录像）
- [ ] 匹配已知电影/电视剧标题（本地启发式规则 + LLM 辅助判断）
- [ ] 提取电视剧季号与集号
- [ ] 对家庭录像推断主题、地点、事件（帧分析 + LLM）
- [ ] 分类内容类型：类型、情绪、分级（家庭友好等）
- [ ] 对所有 LLM 生成标签进行置信度评分，低置信度标记待人工审核

### 1.3 元数据生成

**元数据优先级：外部数据源优先 → LLM 作为补充/兜底**

#### 主要来源：外部数据源

| 内容类型 | 主要来源 | 次要来源 | 兜底 |
|---|---|---|---|
| 电影 | TMDB | IMDB（通过 TMDB ID） | LLM |
| 电视剧 | TMDB + TVDB | Trakt | LLM |
| 动漫 | AniDB / AniList | TMDB | LLM |
| 家庭录像 | — | — | 仅 LLM |

- [ ] 从 TMDB 获取结构化元数据：标题、年份、导演、演员、类型、时长、语言、海报、背景图
- [ ] 从 IMDB 获取评分与 ID（通过 TMDB 的 IMDB ID 字段）
- [ ] 从 TVDB 获取电视剧集详情：剧情简介、播出日期、客串演员
- [ ] 从 Trakt 获取观看数据与社区评分（可选）
- [ ] 动漫内容从 AniDB 或 AniList 获取专项元数据
- [ ] 本地缓存 API 响应，避免重复外部请求
- [ ] 每条记录存储来源标注（如 `metadata_source: tmdb`）

#### 其他可接入数据源（待决策）
- [ ] OMDb API — IMDB 的简化封装，有免费额度
- [ ] MyAnimeList (MAL) — 动漫社区评分与元数据
- [ ] Rotten Tomatoes — 影评人 + 观众评分（无官方 API，需爬取）
- [ ] Metacritic — 专业影评评分（同上）

#### 兜底/补充：LLM 生成
LLM 仅在以下情况使用：
- [ ] 外部数据源未匹配到标题时，生成描述/摘要
- [ ] 填充 TMDB/IMDB 未返回的缺失字段
- [ ] 对家庭录像进行标签与描述生成（外部无此类数据）
- [ ] 所有 LLM 生成字段标记 `llm_generated: true`，保持透明度

#### 通用
- [ ] 最终元数据写入旁文件（NFO/JSON）与媒体文件同目录存放
- [ ] 封面/海报：优先使用 TMDB 海报，无则通过 ffmpeg 提取关键帧缩略图

### 1.4 LLM 提供商抽象层
- [ ] 支持本地 LLM（通过 Ollama REST API）
- [ ] 支持 Claude API（Anthropic）云端推理
- [ ] 支持 OpenAI 兼容 API
- [ ] 按任务类型选择提供商（如：标签用本地，摘要用云端）
- [ ] 优雅降级：云端不可用时自动回退本地
- [ ] 记录云端提供商的 token 用量与费用

### 1.5 流媒体与播放
- [ ] HTTP 流媒体，支持 Range 请求
- [ ] HLS 自适应码率转码（通过 ffmpeg）
- [ ] 支持客户端直接播放（无需转码）
- [ ] 基础 Web UI，支持浏览与播放

### 1.6 搜索与发现
- [ ] 全文搜索（标题、描述、标签）
- [ ] 自然语言搜索（如"90年代动作片"、"海边的孩子视频"）
- [ ] 按类型、年份、评分、标签、置信度筛选

### 1.7 API
- [ ] REST API，覆盖所有库操作
- [ ] Webhook/事件系统，推送处理状态更新
- [ ] API 密钥认证

---

## 2. 非功能需求

### 2.1 性能
- 处理流水线不阻塞流媒体，后台 Worker 异步执行
- 直接播放延迟 < 2 秒；转码流延迟 < 5 秒
- 支持至少 2 路并发流（受硬件限制）

### 2.2 存储
- 元数据与索引本地存储（无强制云依赖）
- 旁文件（.nfo、.json）与媒体文件同目录存放
- SQLite 作为元数据库（可通过配置升级为 PostgreSQL）

### 2.3 隐私
- LLM 推理可完全本地运行（数据不出本机）
- 云端 LLM 调用为可选项，明确记录日志
- 默认无遥测

### 2.4 可靠性
- 崩溃恢复：重启后自动续跑中断的处理任务
- 幂等处理：重新索引文件不会产生重复元数据
- 优雅降级：LLM 提供商不可用时服务器继续正常运行

### 2.5 可移植性
- Docker 镜像内置 ffmpeg
- 单二进制文件支持裸机部署（Go 首选）
- 配置通过 TOML 文件 + 环境变量覆盖

---

## 3. 架构概览

```
┌─────────────────────────────────────────────────────────┐
│                     媒体服务器核心                        │
│                                                         │
│  ┌──────────┐  ┌──────────────┐  ┌──────────────────┐  │
│  │ 目录监听 │→ │  摄入流水线  │→ │  处理队列(Worker)│  │
│  │(inotify) │  │              │  │                  │  │
│  └──────────┘  └──────────────┘  └────────┬─────────┘  │
│                                           │             │
│              ┌────────────────────────────┤             │
│              ▼            ▼               ▼             │
│            ┌──────────────┐  ┌──────────────┐          │
│            │ 元数据       │  │ 分类         │          │
│            │ Worker       │  │ Worker       │          │
│            └──────┬───────┘  └──────┬───────┘          │
│                   └─────────────────┘                   │
│                          │                              │
│             ┌────────────▼──────────────┐               │
│             │     外部数据源路由器       │               │
│             │ TMDB / TVDB / AniDB /     │               │
│             │ OpenSubtitles / Trakt     │               │
│             └────────────┬──────────────┘               │
│                          │ 未匹配/缺失字段               │
│                   ┌──────▼──────┐                       │
│                   │  LLM 路由器 │                        │
│                   └──┬──────┬───┘                       │
│                      │      │                           │
│              ┌────────┘      └──────────┐               │
│         ┌────▼─────┐           ┌────────▼─────┐         │
│         │  Ollama  │           │ Claude/OpenAI│         │
│         │ (本地)   │           │ (云端)       │         │
│         └──────────┘           └──────────────┘         │
│                                                         │
│  ┌──────────────┐  ┌─────────────┐  ┌───────────────┐  │
│  │  SQLite DB   │  │  HTTP API   │  │  Web UI       │  │
│  │ （元数据）   │  │  （REST）   │  │ （播放器）    │  │
│  └──────────────┘  └─────────────┘  └───────────────┘  │
└─────────────────────────────────────────────────────────┘
```

---

## 4. 技术栈决策

| 关注点 | 选型 | 理由 |
|---|---|---|
| 后端语言 | Go | 单二进制、HTTP/并发优秀、部署简单 |
| 数据库 | SQLite (sqlx) | 零配置、可嵌入、单用户足够 |
| 媒体处理 | ffmpeg（子进程） | 行业标准，格式支持广泛 |
| LLM 本地 | Ollama REST API | HTTP 接口简单，内置模型管理 |
| LLM 云端 | Anthropic SDK + OpenAI SDK | 抽象层双提供商支持 |
| 容器化 | Docker + Compose | 多服务：server + ollama + 可选 GPU |
| 配置格式 | TOML | 人类友好，Go 生态支持（viper） |
| Web UI | HTMX + Tailwind | 无 JS 框架，Go 模板渲染 |

> **Rust 备选**：如果性能成为瓶颈（转码流水线），Rust 是可行选项，但 Go 开发速度更快，部署更简单，推荐作为首选。

---

## 5. MVP 范围（第一阶段）

目标：可用的库扫描 + LLM 辅助标签 + 基础 Web UI + 流媒体播放

- [ ] 目录监听 + 文件摄入
- [ ] 电影/电视剧分类（文件名启发式 + LLM 辅助）
- [ ] TMDB 元数据获取（主要来源）；LLM 填补缺失字段
- [ ] 缩略图提取（TMDB 海报优先，ffmpeg 关键帧兜底）
- [ ] SQLite 元数据存储
- [ ] REST API：库列表、获取条目、触发重扫
- [ ] 基础 Web UI：网格视图 + 视频播放器
- [ ] HTTP 直接播放流媒体
- [ ] Ollama 集成（本地 LLM）
- [ ] Docker Compose 配置

---

## 6. 第二阶段（MVP 后）

- [ ] HLS 转码
- [ ] Claude API / OpenAI API 集成 + 提供商路由
- [ ] 自然语言搜索
- [ ] TVDB 集成（电视剧强化）
- [ ] Trakt 集成（观看历史与社区数据）
- [ ] 多用户支持与观看记录

---

## 7. 第三阶段（未来规划）

- [ ] 移动端友好 UI / PWA
- [ ] GPU 加速转码
- [ ] 家庭录像场景检测 + 自动章节标记
- [ ] 家庭录像人脸识别标签
- [ ] 合集与播放列表
- [ ] Jellyfin 协议兼容（接入 Infuse、Swiftfin 等现有客户端）
- [ ] AniDB / AniList / MAL 动漫数据源集成
- [ ] Rotten Tomatoes / Metacritic 评分爬取（无官方 API）

---

## 8. 待决策事项

- [ ] 是否暴露 Jellyfin 兼容 API 以复用现有客户端（Infuse、Swiftfin）？
- [ ] Docker 中 GPU 直通：必选还是可选？
- [ ] 家庭录像帧分析是否引入视觉模型（LLaVA / Claude Vision）？
- [ ] 是否支持多用户（MVP 单用户是否可接受）？
- [x] ~~TMDB/TVDB 是否接入~~：**已决策** — TMDB 为主要数据源，LLM 仅作补充