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；入库后自动刮削缺省关且静默；不通知媒体服务器、无真机验证。

待办（按优先级）

每批改动局部、带回归测试，按「计划 → 子代理实现 → 协调者验收」推进。

已完成：v0.3.27 完成 T0、T1、T2；v0.3.28 完成 T3、T4、T5 与多集 NFO、综艺期数、整理剩余隐患（见 CHANGELOG）。剩余：

• 规则组被订阅 / 收录版本引用时停用要拦截或提示（routes/rule-groups.ts）。
• 合并作品后对目标作品重算集数。
• 集 NFO 的 uniqueid / 演职员（需改元数据存储；MP 金样集演职员为空，当前登记为偏离）。

T6 真机验收

• 一套 Emby / Jellyfin 实例验 NFO 识别；补动画 / 公开 BT / 绝对集号的真实样本；在 4380 按四个场景（PT 追更剧、ANi 番、综艺、电影洗版）端到端追到 NFO。读部署库需要用户放行（自动模式把它归为生产数据读取）。

执行

第一波（T0、T1、T2）5 路、第二波（T3、T4、T5、刮削与整理剩余）4 路并行完成，分别发布 v0.3.27、v0.3.28：每路独立 worktree、分支、测试库容器，迁移号预分配，协调者合并后跑全量 ci。合并时发现一处两线交叉（种子被占用而取消的计划会被「失败可重试」规则立即重建），已修。接下来是 T6 真机验收。