# 系统梳理（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 真机验收。