Subtitle Scout：LLM Agent 驱动自托管字幕搜刮系统，自动甄别、择优挂载字幕，缺源可 AI 翻译

在家庭媒体库的维护中，寻找并匹配精准的字幕往往是一项繁琐且充满挫败感的任务。传统的自动化方案通常依赖僵化的文件名匹配规则，不仅容易因命名不规范而失效，还常常引入错误的时间轴或乱码字幕。Subtitle Scout 的出现彻底改变了这一现状。作为一个以大型语言模型（LLM）Agent 为核心的自托管系统，它摒弃了固定的流水线，转而采用动态的智能决策循环，为每一集缺失字幕的影视作品精准寻找、验证并安装最适配的字幕。

• 官网：https://subtitlescout.com/zh
• GitHub：https://github.com/fancydirty/subtitle-scout

核心机制：像人类一样思考的决策循环

Subtitle Scout 的核心优势在于其“思考”能力。对于每一个待处理的任务，系统会驱动一个智能体执行完整的认知循环，而非盲目下载：

1. 智能路由与搜索：Agent 会根据文件名、TMDB 元数据以及历史搜索结果，动态决定在哪些字幕源（如 ASSRT、OpenSubtitles、SubDL、Jimaku 等）中进行检索，并自主构建最优的搜索关键词组合。
2. 深度结果读取：系统不会盲目相信搜索引擎的最高排名。它会严格校验候选字幕的剧集、集数以及剪辑版本，确保匹配的逻辑正确性。
3. 沙箱结构化判定：这是 Subtitle Scout 的杀手锏。每个候选字幕都会被下载到一个一次性沙箱中，进行严格的结构性体检（包括字幕条数、时间线跨度是否与片长匹配、编码格式等）。随后，LLM 会综合这些证据，最终裁定该字幕是否真正属于当前这一集。
4. 安全安装与翻译兜底：系统秉持“错误的字幕比没有字幕更糟”的原则。只有经过严格验证的字幕才会被安装；若未找到合适的外挂字幕，第二个 Agent 会介入，基于术语表对现有外语字幕（如日文）进行逐句的高质量翻译。

独立架构与广泛的生态支持

与传统的媒体管理工具不同，Subtitle Scout 无需依赖 Plex、Jellyfin、Emby、Sonarr 或 Radarr。它直接扫描你指定的本地媒体目录，凭借自身的 SQLite 数据库管理状态，实现了真正的轻量化与解耦。

在语言与源的支持上，系统对中文的覆盖最为深入，同时完全支持英语、日语和韩语，并对西班牙语、法语、德语等提供了基础覆盖。它内置了约 7 个主流字幕源的适配器，用户可根据目标语言灵活启停。

在文件操作层面，系统极其注重数据安全性。当需要进行文件整理（realign）时，它严格使用原子重命名（atomic rename）操作。如果归档目录与媒体库不在同一文件系统（例如群晖的不同共享文件夹），系统会主动跳过搬移并记录日志，绝不退化为不可靠的拷贝操作，从而杜绝半成品库的产生。

部署与核心配置指南

Subtitle Scout 提供了极简的 Docker 部署体验，但其强大的功能依赖于几项关键配置。

1. 快速启动
通过 Docker Compose 即可快速拉起服务。首次运行需创建缓存目录并复制环境变量模板：

mkdir -p cache
cp .env.example .env
docker compose up -d

启动后，访问 http://<主机IP>:8099 即可进入监控面板。

2. 核心凭证配置

系统运行依赖两类硬性凭证，需在首次设置向导中完成配置：

• TMDB API Key：这是系统识别影视文件的基石。TMDB 的 /alternative_titles 接口能有效解决同一部影片在不同地区译名变体（如“和”、“与”、“&”）导致的检索遗漏问题，大幅提升召回率。
  • 大陆网络特别提示：若 api.themoviedb.org 访问受阻，可在 docker-compose.yml 的环境变量中配置官方旧域名 TMDB_BASE_URL: https://api.tmdb.org/3，或强烈建议通过 Cloudflare Worker 自建反代（绑定自有域名），以同时解决 API 与图片的访问问题。
• LLM 三件套：包括 LLM_BASE_URL、LLM_API_KEY 和 LLM_MODEL。任何兼容 OpenAI 协议的端点均可使用。
  • 模型选择建议：Agent 的识别与匹配涉及长链路多步工具调用。推荐使用具备较强逻辑推理能力的模型（如 deepseek-v4-flash、qwen3.5-plus 等）。切勿使用参数量过小的本地模型，否则模型可能会自信地编造错误信息（幻觉），导致“识别成另一部片”的严重错误。

3. 字幕源配置

• ASSRT：专业的免费中文字幕源，配额约 5 次/分钟，程序已内置自动限速。
• OpenSubtitles：覆盖面极广的国际源，建议注册账号并创建 API Consumer 以获取更高额度。
• Jimaku：专为翻译 Agent 提供高质量的日文源字幕。

4. 运行前体检

配置完成后，务必运行 doctor 命令进行全方位接线检查：

docker compose exec subtitle-scout node dist/cli/index.js doctor

该命令会逐项验证 TMDB、ASSRT、LLM 端点、媒体目录写入权限及数据库状态，确保系统在健康状态下开始工作。

监控面板与安全规范

Subtitle Scout 提供了一个功能丰富的 Web 监控面板，用户可以在此一览所有影视作品的字幕覆盖状态，查看正在处理或已排队的任务。其最具价值的功能是“决策历史”：系统会用人类可读的语言摘要每次处理的逻辑（例如“选择了哪个字幕，为什么放弃另一个”），并支持展开查看完整的工具调用 Trace，让 AI 的决策过程完全透明、可追溯。

⚠️ 关键安全警告：

首次启动后，请立即通过监控面板完成管理员账号的创建。在未初始化状态下，/api/v2/auth/setup 端点对局域网完全开放，任何局域网内的设备均可抢先创建管理员并接管实例。若需在不可信网络环境中暴露服务，请务必通过反向代理（如 Caddy、Nginx）终止 TLS 并配置额外的访问鉴权。