diff --git a/docs/plan/README.md b/docs/plan/README.md index e410b3ed..1c8b882f 100644 --- a/docs/plan/README.md +++ b/docs/plan/README.md @@ -31,6 +31,7 @@ ### 进行中 +- 系统梳理后的待办:[system-review.md](system-review.md),T0~T6 按优先级。 - 补字幕:[subtitles.md](subtitles.md),第 1、2 步已完成;待办:以后接进整理 / 订阅工作流。 - 沙箱第二批:站点网页、RSS、网页抓取的 HTML / XML 解析迁入常驻子进程池(ADR-005)。 diff --git a/docs/plan/system-review.md b/docs/plan/system-review.md new file mode 100644 index 00000000..f11e51a8 --- /dev/null +++ b/docs/plan/system-review.md @@ -0,0 +1,95 @@ +# 系统梳理(2026-10-03,v0.3.26) + +按五块能力逐块只读审视,再看交接点。各块完整报告(带 `文件:行号` 证据)在 `.local/review/1-identity.md` ~ `5-scrape.md`;下面每条高风险都由协调者回到代码核对过。修完一条就从这里删掉,全部处理完删除本文件。 + +## 结论 + +- **五块主流程都不依赖 Agent**。Agent 只在待处理事项上兜底(识别歧义、下载失败 / 卡住、集数待确认)和整理时补元数据,符合定位。 +- **最常见的问题不是"做错",而是"停下来没人知道"**:任务、记录、计划卡在中间态,没有巡检回收,也不开待处理。这类问题在五块里都有。 +- **第二类是一次错误被放大或锁死**:一次误指定扩散到同名资源、一次失败让同一资源永不再选、一次移除让同一种子永不再接管。 +- **第三类是交接口径不一致**:同一件事在两三处各算一遍(季号推断、完成判定、覆盖矩阵、作品类型),已经出现分歧;整理向导绕过集数映射就是这一类。 +- **刮削准确度有三处结构性缺口**:改身份后不刷新、缺集元数据写占位并报成功、覆盖策略只有全量二选一。 +- 测试覆盖了主路径,失败路径几乎都没有测试;真实样本只有一个站点,媒体服务器从未真机验证。 + +## 主链路与交接点 + +``` +来源(RSS / 站点快照 / 搜索) + │ release.observed + ▼ +① 识别 ── release.resolved(作品 + 集单元) ──▶ ② 获取(订阅评估 / 手动) + │ 待识别池 / 待处理 │ acquisition_plan(reserved) + │ ▼ + │ ③ 下载调度 ── download.status_changed(completed) ──▶ ④ 整理 + │ │ qB 任务 / 同步 / 阈值 / 清理 │ 媒体库文件 + 资产 + 记录 + │ │ ▼ + └──────── 改身份 / 刷新元数据 ───────────────────────────────────────────────────────────▶ ⑤ 刮削(NFO / 图片) +``` + +| 交接点 | 正常路径 | 兜底巡检 | 漏洞 | +| --- | --- | --- | --- | +| 识别 → 获取 | outbox `release.resolved` → `evaluateAcquisition` | Slot 6h 周期重评(只剧集、只未满足) | 评估被预算 / 缓存卷 / 开关挡住只记 skipped,不写延后,电影与已满足剧集不再重评 | +| 获取 → 下载 | 入队 `submitDownload` | `sweepReservedPlans` 补投 reserved | 同 hash 已有 removed 行时计划停在 submitted;同 hash 第二个计划成孤儿 | +| 下载 → 整理 | `download.completed` → `verifyAndImport` | `sweepPendingImports`:只补"没有任何整理记录"的任务 | 记录卡在 running(重试耗尽 / 入队前崩溃)无人回收 | +| 整理 → 刮削 | 入库后 `scrapeAfterImport` | 无 | 缺省关闭;没排上只打日志 | +| 元数据 → 刮削 | 无(刷新不触发重刮) | 无 | 改身份不刷新;刷新后已有 NFO 不更新 | + +## 分块要点 + +### ① 资源识别(`1-identity.md`) +- 高:bgm 按标题搜索直接取第一条再去 TMDB 召回(`meta-subjects.ts:66`);人工 / Agent 一次指定回填识别缓存,同名资源命中后只剩这一个候选;合并事项按「站点 + 标题」整组锁定,同名不同年份会被锁进同一作品。 +- 中:自动识别新建的作品不排元数据刷新,季表为空,集数映射对绝对集号只能按原号放行;季表把资源懒建的临时季也算进去;站点改版 / Cloudflare 导致快照失败只在站点页显示,不开待处理。 +- 主流程稳:憨憨 113 条真实标题与 MP 对照 112 条一致。 + +### ② 获取(`2-acquisition.md`) +- 高:订阅可能 0 个收录版本而永远不下(无策略模板也没填质量预设,或作品已有旧订阅的收录版本);洗版订阅拿到第一个版本就完成;被挡住的资源无人重评;「接续后续季」没有季下界,从 S3 订会下 S1/S2,矩阵还不显示。 +- 中:失败一次的资源对该收录版本永不再计划(幂等键对 failed 也生效);先到先得不择优(`rankForSlot` 无调用);重评只看最近 50 条;手动下载与订阅互不感知在途。 + +### ③ 下载调度(`3-download.md`) +- 高:同一种子被移除过,再提交后计划永远停在"已提交"(upsert 不清 removed);qB 重启 / 重新校验后已入库任务回退成"已完成",从此不被清理。 +- 中:一次查不到即判移除(终态);H&R 未知的任务(M-Team、接管)永不清理;下载目录读不到容量时所有提交永远延后却显示"等空间";季包不先暂停再选文件;qB 长时间不可达不开待处理。 + +### ④ 整理(`4-organize.md`) +- 高:整理向导把预填季集当人工指定发给服务端,绕过集数映射(`organize-wizard/model.ts:265-266` 不看 `touched`);整理记录卡在 running 无巡检回收。 +- 中:被排除的视频算成功,Move 后 qB 任务被删、文件留在下载目录无人管;非洗版"替换"沿用旧资产行;NOT_VIDEO 文件进库不登记不回滚;Move 后删 qB 任务失败不重试(日志说会重试,实际没有)。 + +### ⑤ 刮削(`5-scrape.md`) +- 高:改 TMDB 映射不清旧元数据也不刷新,NFO 的 tmdbid 新、其余字段与默认 IMDb 是旧作品;集 / 季元数据缺失时写「第 N 集」占位并报成功,缺省"只补缺失"下永不替换;覆盖策略只有"只补缺失 / 全部覆盖",刷新不触发重刮,文档承诺的人工修改保护未实现。 +- 中:合集 / 其他类作品的电影 NFO 根元素写成 ``;多集文件只写首集;综艺日期期数无分集 NFO;入库后自动刮削缺省关且静默;不通知媒体服务器、无真机验证。 + +## 待办(按优先级) + +每批改动局部、带回归测试,按「计划 → 子代理实现 → 协调者验收」推进。 + +**T0 集数映射补丁**(刚上线功能的漏口,改动最小) +1. 整理向导只发用户改过的季集(`touched`),未改的交给服务端映射;待确认行在向导里标为未决。 +2. 自动识别新建作品时排一次 `refreshMetadata`(刷新后已有逻辑会重算待确认 / 放行资源)。 +3. 评估跳过 `episode_unresolved` 时写候选记录,订阅矩阵能看到原因。 + +**T1 静默卡死**(数据面稳定性,局部改动) +1. 下载:提交 upsert 遇到 removed 行时复活;同步不覆盖 importing / imported;连续多轮缺席才判移除。 +2. 整理:巡检 running 且无活跃任务超过 N 分钟的记录,重新入队;库根离线改为开待处理而不是耗尽重试。 +3. 获取:gates 不过时写延后并排重评,并发不计 stalled;幂等键只对在途 / 已完成生效;同 hash 已绑别的计划时结束或关联本计划。 + +**T2 刮削准确度** +1. 改身份:清该作品 tmdb 来源字段 → 排刷新 → 刷新完成后重刮(更新模式)。 +2. 集 / 季元数据缺失时按 TMDB id 现取季详情;仍缺就记 skipped / partial,不写占位。 +3. 覆盖策略加"更新本工具写过且未被改动的文件"(记写入 hash),作为缺省;元数据刷新有变化时自动排这种重刮。 +4. 统一作品类型判定(修 `` 根元素);多集文件写多个 ``。 + +**T3 获取正确性** +1. 订阅总带一个自己的收录版本(没有就建)。 +2. 有升级目标的收录版本完成条件加 `pri ≥ targetPri`。 +3. 「接续后续季」评估加季下界,与矩阵同口径。 +4. 按收录版本重评时先排序再预留;去掉 50 条上限改为按缺集查;手动计划计入在途。 + +**T4 识别准确度** +1. bgm 候选用资源原标题再核对,不再取第一条直接用。 +2. 识别缓存回填区分来源,人工 / Agent 指定不扩散到不同年份 / 类型;合并事项分组键带年份与类型。 +3. 快照失败、TMDB 查询复查耗尽开待处理。 + +**T5 可见性** +- qB 离线、下载目录读不到容量、整理排除视频、自动刮削没排上:都开待处理或在记录上标原因;卡住事项恢复后自动关闭。 + +**T6 真机验收** +- 一套 Emby / Jellyfin 实例验 NFO 识别;补动画 / 公开 BT / 绝对集号的真实样本;在 4380 按四个场景(PT 追更剧、ANi 番、综艺、电影洗版)端到端追到 NFO。读部署库需要用户放行(自动模式把它归为生产数据读取)。