232 lines
7.3 KiB
Markdown
232 lines
7.3 KiB
Markdown
> [!NOTE]
|
||
> Status: Historical snapshot. Current refactor results and validated baseline are tracked in `CHANGELOG.md` (updated 2026-02-16).
|
||
|
||
# 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 与执行前人工复核强制步骤。
|
||
|