> [!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 与执行前人工复核强制步骤。