dl-organizer/IMPROVEMENT_RECOMMENDATIONS_2026-02-13.md

Note

Status: Historical snapshot. Current refactor results and validated baseline are tracked in CHANGELOG.md (updated 2026-04-07).

VLM 项目与 Skill 改进建议（2026-02-13）

1. 评估范围与依据

本建议基于以下真实运行结果与代码阅读：

1. 实际整理流程：scan -> parse -> analyze -> plan -> execute(dry-run)。
2. 实际产物：inventory.csv、identities.json、analysis.json、plan.json、plan_manual_review.csv。
3. 关键代码：src/vlm/parser.py、src/vlm/planner.py、src/vlm/cli.py、src/vlm/executor.py、skills/vlm-library-workflow/SKILL.md。

运行中观测到：

1. plan.json 总操作 4710，其中 move=1623、quarantine=187、no-op=2900。
2. 人工复核候选 516 条，其中：
   1. manual_review=349
   2. source_is_sample=92
   3. season>=20=75
   4. episode>=40=27
   5. truncated_title_pattern=8

这说明当前系统“可用”，但在真实复杂片源命名下，仍存在高风险误解析与误搬运窗口。

2. 代码层改进（按优先级）

P0（必须先做）

2.1 修复 parse_series 的 XXxYY 误匹配分辨率问题

现象：

1. 1440x1080、1920x1080 会被局部匹配成 40x10、20x10，导致生成 Season 40/S40E10、Season 20/S20E10 这类错误目标路径。

根因位置：

1. src/vlm/parser.py:197，模式 (\d{1,2})x(\d{1,2}) 过于宽松且允许子串匹配。

改进建议：

1. 改为边界敏感模式，例如 (?<!\d)(\d{1,2})x(\d{1,2})(?!\d)。
2. 增加“分辨率语境排除”规则：若匹配附近存在 1080/2160/720/480/p 等特征，直接拒绝该候选。
3. 对 x 模式降置信度或增加二次校验（例如 title 长度、是否含明显编码标签）。

验收标准：

1. 1920x1080、1440x1080 不得触发季集解析。
2. 新增回归测试覆盖上述文件名。

2.2 在规划阶段阻断明显异常季集号

现象：

1. 即便解析错误，planner 仍直接生成 move 操作，带来误改风险。

根因位置：

1. src/vlm/planner.py:300-372，仅检查 needs_review/season is None/episodes empty，未对极端季集号做保护。

改进建议：

1. 在 _create_series_operation 增加阈值守卫（例如 season > 15 或 episode > 100 时改为 no-op 并标记 manual review）。
2. 阈值放入配置（如 plan.max_season, plan.max_episode），默认启用。

验收标准：

1. 出现异常季集号时，不得进入 move/rename。
2. plan.json 的 summary_by_reason 可见明确拦截原因。

2.3 Sample 片段默认不应参与主文件整理

现象：

1. Sample 文件被移动为正片目标名，存在“样片覆盖正片语义”的风险。

根因位置：

1. 解析/规划阶段未区分样片；duplicate_keep 也未惩罚 sample。

改进建议：

1. 在扫描或规划阶段识别 Sample（路径段或文件名）。
2. 默认行为：no-op 或优先 quarantine，并提供开关（如 plan.include_sample_files=false）。
3. 在重复保留策略中将 sample 质量权重降到最低。

验收标准：

1. sample 不再成为默认保留/搬运目标。
2. 增加针对 .../Sample/... 的单元测试与集成测试。

P1（高价值）

2.4 优化标题规范化策略，避免语义损伤

现象：

1. normalize_title() 使用 .title() 会把 CJ7 -> Cj7、R.I.P.D -> R I P D，并可能对中日文混排标题产生副作用。

根因位置：

1. src/vlm/parser.py:82-84。

改进建议：

1. 默认不做 .title()，只做分隔符清洗与空白归一。
2. 增加可选 title-case 开关，仅用于纯英文场景。

验收标准：

1. 缩写与数字混排标题大小写保持稳定。
2. 新增包含中日文与缩写的测试用例。

2.5 降低 dry-run 日志噪音，提升可审阅性

现象：

1. dry-run 会输出大量逐条日志，审阅效率低。

根因位置：

1. src/vlm/executor.py dry-run 对每条操作记 INFO。
2. src/vlm/cli.py:771 已做“Sample operations”，但日志层仍会刷屏。

改进建议：

1. 默认将逐条 dry-run 日志降为 DEBUG。
2. CLI 增加 --verbose-ops 选项，按需打印全量操作。

验收标准：

1. 默认 dry-run 输出聚合摘要 + 少量样本。
2. 显式开启 verbose 时仍可查看全量。

2.6 提供内建“计划体检”命令

改进建议：

1. 新增 vlm review-plan --input plan.json --output plan_manual_review.csv。
2. 内建规则：异常季集号、sample、标题截断、高风险字符、手工审核项统计。

价值：

1. 将当前人工脚本化能力产品化，减少执行前漏检。

P2（体验与可维护性）

2.7 丰富解析模式（尤其东亚命名）

建议新增模式：

1. EP01 / E01 独立模式（season 缺失时可推断 S01 或标记低置信）。
2. 第09話 / 第09集 模式。
3. S01 Complete、END、SP 特判策略。

2.8 用“真实语料回放测试”补齐回归

建议：

1. 在 tests/fixtures/ 维护匿名化真实文件名样本。
2. 新增端到端测试：parse -> plan 断言“异常项不得进入 move”。

3. Skill 描述改进建议（vlm-library-workflow）

当前 skill 已具备主流程与安全意识，但还可增强“执行前闸门”与“环境兼容性”。

3.1 增加命令回退策略（vlm 不存在时）

问题：

1. 当前文档默认 vlm ...，但实际环境可能仅支持 uv run vlm ...。

建议：

1. 在 SKILL.md 与 references/command-recipes.md 增加规则：
   1. 先试 vlm --help
   2. 失败则自动切换 uv run vlm --help

3.2 把“人工复核闸门”写入 Skill 强制流程

建议：

1. 在 execute --confirm 之前新增固定步骤：生成并汇报高风险清单。
2. 若高风险计数 > 0，默认不执行确认，除非用户明确覆盖。

推荐规则（可直接写入 skill）：

1. season>=20 或 episode>=40
2. source_path 包含 Sample
3. reason 包含 manual review
4. 标题截断模式（如路径中出现异常断裂片段）

3.3 在 Skill 中声明已知解析边界

建议：

1. 明确列出“当前 parser 对某些命名存在误判风险（如分辨率触发 x 模式）”。
2. 遇到这些模式时，优先建议“复核并降级为 no-op”。

3.4 输出契约增加“风险摘要”

建议在 Output Contract 增加：

1. 高风险条目总数与分类计数。
2. 前 5 条代表样本。
3. 执行建议（继续/暂缓）。

4. 推荐实施顺序（两周节奏）

第 1 周（风险收敛）：

1. 修 parse_series 误匹配。
2. planner 增加异常季集号保护。
3. sample 文件默认降级处理。
4. 增加对应单测。

第 2 周（体验提升）：

1. 加 review-plan 命令。
2. 优化 dry-run 日志粒度。
3. 迭代 vlm-library-workflow skill（执行前闸门 + 命令回退 + 风险摘要）。

5. 可直接转任务的条目

1. parser: 修复 XXxYY 与分辨率冲突，新增回归测试。
2. planner: 增加 max_season/max_episode 风险闸门与配置项。
3. planner/duplicate: sample 文件降权或默认不搬运。
4. cli: 增加 review-plan 子命令。
5. executor/logging: dry-run 默认聚合输出，逐条改为 debug。
6. skill: 增加 uv run vlm fallback 与执行前人工复核强制步骤。