archived-MoviePilot-Plugins/plugins/airecognizerenhancer/ARCHITECTURE.md

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 精简摘要输出，适合作为智能体批处理入口
• 已支持识别词建议模型退化时自动切换到精确规则兜底，优先保证稳定落地
• 下一步重点会放在提示词打磨、失败样本回放和识别词建议质量提升