MoviePilot/docs/smart-search.md

订阅补全搜索与手动分页

补全搜索策略

“设置 → 订阅 → 基础设置”的“补全搜索策略”（SubscribeSearchStrategy）作用于影视订阅的补缺搜索，包括新建、手动、定时和恢复触发的订阅搜索。日常获取最新资源仍由“订阅模式”负责；音乐、字幕、RSS 保持原有流程。

策略	行为
smart（默认，未设置时）	逐页收集，能确定某集已搜完时停止为它翻页
full	翻完全部结果页再择优；资源多时耗时长，开始下载较晚
single_page	每个站点关键词只查第一页（保留别名回退），过滤不通过或下载失败也不翻页，可能遗漏较早剧集

洗版始终完整分页；整季缺失（缺集列表为空）也启用完整收集，即使真实总集数已知并展开为具体集号，也须等各来源结束后统一择优，让后页整季包参与原有的整季优先下载流程。站点冷却、时间片暂停和检查点恢复不会提前提交散集；单页策略仍只检查每个来源第一页。智能和全量不受 SEARCH_RESOURCE_PAGES 限制，但每个来源最多检查 20 页，Web 手动分页同样使用该上限。

智能收集

来源是站点与实际关键词的组合，各缺集共用该来源的一条游标；资源按原搜索去重规则（站点名 + 标题 + 描述）去重。

• 某集在某来源出现后，又在之后完整的一页中缺席，该来源就不再为它翻页；从未出现的集继续寻找。识别不出的资源和失败页不算缺席证据。
• 空页、与上一页完全相同的页、站点明确返回末页时，该来源结束；不支持分页的站点只查第一页，不算失败。
• 普通 IMDb 精确查询中，某来源从未匹配过目标作品，且连续 3 个非空页面全部明确不匹配时，本轮停止该来源并释放候选收集屏障。识别未知页打断计数；匹配过同作品的其他季集也不会触发该早停。全量、洗版、整季缺失和深度兜底不使用该规则，但仍受 20 页上限约束。停止只表示本轮不再检查该来源，不代表站点真实搜尽或订阅已补齐。
• 一集在所有来源都结束收集后才择优提交；合集等它覆盖的集都就绪后一次提交。没有合格候选或下载失败时，从当前进度继续完整翻页兜底。智能模式不保证选到后续页面中的最优版本。
• 连载中的剧：智能模式以站点资源为准，不看播出时间。本轮任一来源出现过的最大集号作为站点已收录边界，大于边界的缺集视为站点尚未收录，只查各来源第一页，不翻页、不兜底、不尝试别名。只剩这类缺集时本轮结束，后续集由订阅模式追更。较深页面出现更新集号时边界随之扩大；同季没有任何资源时按正常规则收集。若各来源第一页都被旧合集或重新上传的旧集占满，较新的集可能被当作站点尚未收录，留待下次搜索或订阅模式；这是为避免连载剧翻遍全站接受的取舍。完整模式（含整季缺失）不使用该推断裁剪分页或提前释放目标，避免错过深页中的全集包。

媒体匹配、季集过滤、排序、下载选择和订阅完成判断都复用原有流程；分页只决定何时提交哪些集。

MiKan 等搜索入口一次返回完整列表的通用站点，按站点单页数量在响应中切出对应页，默认每页 100 条。每次续页仍需重新请求搜索页面，可翻页范围以站点实际返回的结果为限。

中断与恢复

• 进度保存在 searchsession 表，每个订阅搜索任务一行，由队列任务租约和版本号防止迟到的执行者覆盖。只保存仍覆盖剩余缺集的候选，不保存 Cookie、API Key、passkey 等凭据；下载链接能重建的用当前凭据重建，否则重新请求原页取得。同一候选的原页连续 3 次请求失败时，本轮放弃该候选。
• 任务约每 60 秒在页面边界让出执行；同一站点最多一个自动请求在途，间隔至少 10 秒，不同订阅共享该限制，等待期间任务重新入队而不占线程。
• 恢复时，进度超过 36 小时未更新就从第一页重搜；某来源超过 15 分钟没有请求时，先续拉原来的下一页，再重拉一次第一页补入新上传。更换媒体来源、作品、类型、季或剧集组时清除已提交进度；同一作品修改关键词等条件会重搜，但保留已提交的集。
• 作品匹配前史和连续不匹配计数随检查点保存，冷却、让出执行或进程恢复不会清零。补拉首页不增加不匹配计数，但其中的作品匹配仍有效。旧检查点缺少匹配前史时采取保守恢复；搜索范围变化会重新搜索并保留同作品已提交的目标。
• 任务进入完成、失败、取消或跳过等终态时删除检查点；超过 14 天未更新的遗留检查点在新建检查点时清理。
• 翻到末页仍缺集或只剩站点尚未收录的集时本轮结束，订阅保留，不会自动循环重扫。分页进度只写日志。

Web 手动分页接口

/search/title/stream 和 /search/media/{id}/stream 传 manual_paging=true 时启用单页模式：

• 首次请求（不带 source）每个来源请求第 0 页，只有这时才做别名回退和插件搜索。
• 不同站点按既有搜索并发数请求，同站点的多个关键词依次请求；每个来源完成后立即发送 append 预览，慢站点不会阻塞已完成来源的展示。标题预览遵循搜索过滤规则，精确媒体搜索先展示未匹配候选，最终结果统一匹配、过滤和排序。
• replace 和 done 事件带 sources 列表，每项包含不透明的 source、site_name、本次 page、can_continue 和 error。
• 续页时只回传 source 和要请求的 page（零基）；客户端在整页结果应用后才推进页号，失败时保留页号以便重试。
• 后端按本轮来源和页号缓存原始页摘要 36 小时，用于判断与上一页是否重复；上一页摘要缺失时先补请求上一页。空页、重复页、明确末页、不支持分页的站点或达到 20 页时 can_continue=false。can_continue=true 只表示可以继续尝试，后端不预取、不自动重试。
• 续页不覆盖“上次搜索”缓存，不使用订阅的检查点或站点预算队列，只遵循站点原有请求间隔。

不传 manual_paging 时，原接口、同步 HTTP 接口和 Agent search.* 行为不变。