> [!NOTE]
> Status: Historical snapshot. Current refactor results and validated baseline are tracked in `CHANGELOG.md` (updated 2026-04-07).

# VLM 改进实施计划（2026-02-13）

## 目标

基于 `IMPROVEMENT_RECOMMENDATIONS_2026-02-13.md` 落地高优先级修复，降低误解析与误搬运风险，并把“执行前人工复核”流程产品化。

## 范围

1. `parser`：修复 `XXxYY` 与分辨率串误匹配；优化标题规范化策略。
2. `planner/config`：新增季集号阈值保护；默认排除 `Sample` 文件。
3. `duplicate_resolve`：在保留策略中降低 `Sample` 优先级。
4. `executor/cli`：dry-run 默认降噪，增加可选 `--verbose-ops`。
5. `cli`：新增 `review-plan` 命令，输出风险复核 CSV。
6. `skill`：补充 `vlm`/`uv run vlm` 回退与执行前风险闸门。

## 任务拆解

1. `T1` 配置扩展
- 增加 `plan.max_season`、`plan.max_episode`、`plan.include_sample_files`。
- 增加配置读写与校验。

2. `T2` 解析修复
- 将 `(\d{1,2})x(\d{1,2})` 改为边界敏感匹配。
- 增加针对 `1920x1080`/`1440x1080` 的回归测试。
- 调整 `normalize_title` 为“仅清洗不强制 title-case”。

3. `T3` 规划闸门
- 在 `_create_series_operation` 增加季集号阈值拦截。
- 在 `_create_operation` 增加 `Sample` 排除（默认 no-op）。
- 保持 `summary_by_reason` 可见拦截原因。

4. `T4` 重复保留策略
- 在 `by_quality` / `by_reputation` 下对 `Sample` 降权。

5. `T5` 执行日志优化
- dry-run 逐条操作日志默认改为 `DEBUG`。
- CLI 增加 `--verbose-ops` 显式输出全量 dry-run 操作日志。

6. `T6` 计划体检命令
- 新增 `vlm review-plan --input plan.json --output plan_manual_review.csv`。
- 输出高风险汇总与明细（manual review / sample / 异常季集号 / conflict）。

7. `T7` Skill 文档更新
- 增加命令回退策略（`vlm` 不可用时切换 `uv run vlm`）。
- 固化执行前风险闸门流程。

8. `T8` 测试与验收
- 补充 parser/planner/config/duplicate/cli/executor 相关测试。
- 跑定向测试与全量回归。

## 执行状态

1. `[x]` `T1` 配置扩展完成。
2. `[x]` `T2` 解析修复完成。
3. `[x]` `T3` 规划闸门完成。
4. `[x]` `T4` 重复保留策略 sample 降权完成。
5. `[x]` `T5` dry-run 日志降噪 + `--verbose-ops` 完成。
6. `[x]` `T6` `review-plan` 命令完成。
7. `[x]` `T7` skill 文档更新完成。
8. `[x]` `T8` 测试通过（定向 + 全量）。

## 验收标准

1. `1920x1080` 不再被解析为 `S20E10`。
2. `season > max_season` 或 `episode > max_episode` 不生成 move/rename。
3. 默认配置下 `Sample` 文件不进入搬运。
4. `review-plan` 能生成 CSV 并输出风险统计。
5. dry-run 默认日志显著降噪，开启 `--verbose-ops` 可恢复逐条日志。
6. 新增与受影响测试通过。