UHD_Media_Tool/docs/plan/system-review.md

系统梳理（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 根元素写成 <tvshow>；多集文件只写首集；综艺日期期数无分集 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. 统一作品类型判定（修 <tvshow> 根元素）；多集文件写多个 <episodedetails>。

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。读部署库需要用户放行（自动模式把它归为生产数据读取）。