# AI识别增强架构草案

`AI识别增强` 用来承接 MoviePilot 原生识别失败后的本地 AI 兜底链路。

## 设计目标

- 摆脱外部 AI Gateway 的强依赖
- 直接使用 MoviePilot 已启用的 LLM 配置
- 输出结构化识别结果，而不是只回传一段自由文本

## 模块分层

### 1. hooks

负责接住识别失败事件和后续整理事件。

### 2. llm

负责封装对 MP 当前 LLM 的调用：

- 标准提示词
- 结构化返回约束
- 超时与错误兜底

### 3. normalize

负责把 AI 输出转换成可继续进入 MP 整理链路的数据：

- 标题
- 年份
- 类型
- 季
- 集
- 置信度

### 4. actions

负责根据结果执行后续动作：

- 二次识别
- 二次整理
- 记录失败样本

## 首期配置模型

- `enabled`
- `notify`
- `debug`
- `confidence_threshold`
- `request_timeout`
- `max_retries`
- `save_failed_samples`

## 二期规划

- 生成自定义识别词建议
- 失败样本聚合分析
- 提供给 MP Agent / Skill 直接调起

## 首个里程碑

第一个可用版本只追求：

1. 原生识别失败后自动触发本地 LLM 判断
2. 拿到结构化结果后自动二次整理
3. 能明确记录“成功 / 放弃 / 失败原因”

## 当前实现状态

- 已接住 `ChainEventType.NameRecognize`
- 已复用 `LLMHelper.get_llm(streaming=False)` 做结构化输出
- 已提供手动调试接口用于验证标题识别结果
- 已支持查看低置信度样本，并继续生成为 MoviePilot 自定义识别词建议
- 已支持直接基于失败样本生成建议并一键写入 `CustomIdentifiers`
- 已支持失败样本摘要列表、样本清理、样本去重和保留上限控制
- 已支持失败样本洞察汇总，自动挑出重复问题和优先处理样本
- 已支持失败样本出队：写入识别词后自动移除，或单独按索引移除
- 已支持失败样本复查：按当前识别词和当前识别器重跑，并可自动把已修复样本出队
- 已支持失败样本批量复查：可批量重跑并按结果批量出队
- 已支持失败样本批量建议与批量写入：可批量生成建议并批量落库
- 已支持低 token 精简摘要输出，适合作为智能体批处理入口
- 已支持识别词建议模型退化时自动切换到精确规则兜底，优先保证稳定落地
- 下一步重点会放在提示词打磨、失败样本回放和识别词建议质量提升
