dl-organizer/docs/archive/2026-pre-baseline/2026-05-21-functional-code-simplification-plan-v1.md

# 修改计划：只保留对功能有贡献的代码

**日期：** 2026-05-21  
**状态：** 已完成（2026-05-21）  
**基线：** `uv run pytest -q` → **517 passed**（2026-05-21 实测）  
**原则：** 删除或合并**无运行时贡献**的代码与文档；**不**削减 CLI 命令、配置项、产物格式、安全策略或用户工作流。

---

## 1. 目标

| 目标 | 说明 |
|------|------|
| 减噪 | 去掉从未被 import / 调用的模块与一层包装函数 |
| 减重复 | 同一语义只保留一处实现（如 plan 摘要） |
| 减结构债 | 把 `cli.py` 中已独立的命令体迁出，**行为不变** |
| 减文档漂移 | 归档已完成的历史审查/实施计划，避免与 `README`/`CHANGELOG` 冲突 |
| 不丢功能 | 全量 pytest + 现有 `tests/test_cli_*` 作为回归门禁 |

**非目标（本计划不做）：**

- 删除 duplicate 策略、`legacy` 产物回退、anime 扫描分类、TUI、TMDB enrich、transaction/rollback
- 合并 `needs_review` 与 `review_status`（会改变 enrich/plan/CSV 语义）
- 缩小 `quarantine.py` / `executor.py` 的**对外 API**（仅允许内部拆分 + re-export）

---

## 2. 功能贡献判定标准

代码/文件在下列情况之一时视为**有贡献**，保留：

1. 被 `vlm` CLI 路径或 `pyproject.toml` entry point 直接或间接调用
2. 被 `tests/` 覆盖且对应用户可见行为（含可选 `[tui]`）
3. 被其他保留模块 import 且删除会导致 import 失败或行为变化
4. 属于安全/数据契约：`io` 校验、`executor` 边界、`duplicate_resolve` 显式失败

下列情况视为**无贡献**，可删或合并：

1. 全仓库零 import（静态可证）
2. 仅转发到另一函数的薄包装（调用方可直接调目标）
3. 已完成且被 `CHANGELOG` 取代的历史计划/审查 markdown
4. 与保留文档逐字重复、无额外运维价值的 agent 副本（如 `GEMINI.md`）

---

## 3. 审计清单

### 3.1 可删除（运行时零贡献）

| 项 | 路径 | 证据 | 操作 |
|----|------|------|------|
| 未使用异常层次 | `src/vlm/exceptions.py` | 全仓库无 `from vlm.exceptions` | **删除文件** |
| CLI 薄包装 | `cli.py` `_fallback_plan_summary()` L1183–1185 | 仅调用 `plan_render.fallback_plan_summary` | **删除**；调用改 `preferred_plan_summary` |
| 重复 import | `cli.py` 对 `fallback_plan_summary` 的 import | 包装删除后不再需要 | **删除 import** |

### 3.2 可合并（保留行为，减重复）

| 项 | 位置 | 现状 | 操作 |
|----|------|------|------|
| Plan 摘要 | `cli.py` L1332、L1451 | `human_summary or _fallback_plan_summary(...)` | 改为 `preferred_plan_summary(execution_plan)`（与 `execute`/`review-plan` 一致；空白 `human_summary` 处理更一致） |
| 可选依赖声明 | `pyproject.toml` `[dev]` | `textual` 与 `[tui]` 重复 | **从 `[dev]` 移除 textual**；开发需 TUI 时用 `uv pip install -e ".[dev,tui]"` 或文档说明 |

### 3.3 保留（有贡献，勿删）

| 模块 | 贡献 |
|------|------|
| `scanner` / `parser` / `analysis` / `planner` / `executor` | 主管道 |
| `duplicate_resolve` | 重复策略与显式失败 |
| `io` | 产物校验与 typed plan |
| `plan_review` / `plan_render` / `review_display` / `review_tui` | 人工复核与可选 TUI |
| `plan_structure_preview` | `review-plan` 结构预览（`cli` + `test_plan_review`） |
| `transaction` | `executor` 执行期事务日志 |
| `quarantine` / `state` / `reports` / `enrichment` / `cache` / `providers` | 对应子命令 |
| `commands/*`（已有） | scan/parse/enrich/analyze/plan/execute/rollback |
| `logging_config` | CLI + executor + quarantine + 测试 |
| `context` / `config` / `models` / `utils` | 全局基础设施 |

### 3.4 文档归档（不删功能，减仓库噪音）

移至 `docs/archive/2026-pre-baseline/`（或删除若确认无历史查阅需求）：

| 文件 | 理由 |
|------|------|
| `REVIEW_REPORT.md` | 2026-04-07 计划已 Completed |
| `ARCHITECTURE_REVIEW.md` | 历史架构审查，多处已修复 |
| `VLM_PROJECT_AUDIT_REPORT.md` | 审计快照 |
| `AUDIT_FIX_PLAN.md` | 任务已勾选完成 |
| `FIX_PLAN.md` | 同上 |
| `CODE_IMPROVEMENTS.md` | 建议清单，非现行规范 |
| `CODE_ANALYSIS_2026-04-01.md` | 一次性分析 |
| `IMPLEMENTATION_PLAN_2026-02-13.md` | 已过期 |
| `IMPROVEMENT_RECOMMENDATIONS_2026-02-13.md` | 已过期 |
| `TMDB_REFACTOR_PLAN.md` | 若 TMDB 已落地则归档 |
| `codex_review.md` | 外部审查副本 |
| `plans/2026-04-07-review-report-refactor-plan-v1.md` | Status: Completed |
| `plans/2026-04-02-review-plan-output-refactor-v1.md` | 已完成 |
| `plans/2026-04-01-CODE_REFACTOR_REFINEMENT_PLAN-v1.md` | 已完成 |
| `GEMINI.md` | 与 `CLAUDE.md`/`AGENTS.md` 重复 |

**保留为现行文档：**

- `README.md`、`CHANGELOG.md`、`CLAUDE.md`、`AGENTS.md`
- `docs/TECHNICAL_REVIEW.md`（可选：精简后保留为「设计备忘」或一并归档）
- `skills/vlm-library-workflow/**`（Agent 操作指引）
- `plans/2026-05-21-functional-code-simplification-plan-v1.md`（本计划）

**可选归档：** `.kiro/specs/video-library-manager/` — 若与当前实现严重偏离且团队不用 Kiro，整目录归档。

### 3.5 结构重组（不删命令，减 `cli.py` 体积）

将下列 Click 命令体迁到 `commands/`，`cli.py` 只保留装饰器 + 一行委托：

| 新文件 | 迁出命令 |
|--------|----------|
| `commands/review_plan.py` | `review_plan_cmd`, `apply_review_cmd` |
| `commands/report.py` | `report` 组及四个子命令 |
| `commands/quarantine_cmd.py` | `quarantine` 组（避免与 `quarantine.py` 模块名冲突） |
| `commands/state_cmd.py` | `state` 组 |
| `commands/config_cmd.py` | `config` 组 |

共享辅助函数抽到 `cli_helpers.py`（或 `context.py` 旁）：

- `default_config_path`, `default_artifact_path`, `resolve_legacy_default_input_path`
- `_load_or_create_config`, `_command_error`, `_review_plan_tui_streams_ok`

**预期：** `cli.py` 从 ~1941 行降至 ~300 行；**`vlm --help` 与子命令选项不变**。

### 3.6 延后（本计划不拆文件内容）

以下能减行数但工作量/风险更高，单列 **Phase 2**（可选后续计划）：

- 拆分 `quarantine.py`（1027 行）、`executor.py`（833 行）、`planner.py`（815 行）
- 统一 rollback/quarantine 的 `is_within_root`（**安全增强**，非删功能）
- `io.py` 增加 `operation_type` 白名单（**更严校验**）

---

## 4. 分阶段实施

### Phase 0 — 准备（0.5h）

- [ ] 确认工作区干净或建立分支 `chore/functional-code-trim`
- [ ] 记录基线：`uv run pytest -q` → 517 passed
- [ ] 记录 `uv run vlm --help` 与子命令列表截图或文本（回归对比）

### Phase 1 — 删除零贡献代码（0.5–1h）

| 步骤 | 改动 |
|------|------|
| 1.1 | 删除 `src/vlm/exceptions.py` |
| 1.2 | 删除 `cli.py` `_fallback_plan_summary`；L1332/L1451 改用 `preferred_plan_summary`；移除 `fallback_plan_summary` import |
| 1.3 | `pyproject.toml`：`[dev]` 去掉 `textual`；README/CLAUDE 一行说明 TUI 安装方式 |

**验收：**

- [ ] `uv run pytest -q` 全绿
- [ ] `rg "exceptions|_fallback_plan_summary" src tests` 无匹配

### Phase 2 — 文档归档（0.5h）

| 步骤 | 改动 |
|------|------|
| 2.1 | 创建 `docs/archive/2026-pre-baseline/README.md`（索引归档原因与日期） |
| 2.2 | `git mv` 第三节所列 markdown 到归档目录 |
| 2.3 | 更新 `README.md`：测试基线 **517**；`CLAUDE.md` 补充 `by_reputation_quality_time` |
| 2.4 | `CHANGELOG.md` 增加条目：「文档归档 + 删除未使用 exceptions + CLI 摘要合并」 |

**验收：**

- [ ] 根目录仅保留现行文档（见 3.4）
- [ ] 无断链：README 不引用已归档文件名（或改为 archive 链接）

### Phase 3 — CLI 模块化（1–2d）

按 3.5 迁移；每迁一组命令跑一次 targeted tests：

```bash
uv run pytest tests/test_cli_review_plan.py tests/test_cli_reports.py \
  tests/test_cli_quarantine.py tests/test_cli_state.py tests/test_config.py -q
```

**验收：**

- [ ] 全量 `pytest -q` 517+ passed
- [ ] `uv run vlm --help` 与 Phase 0 命令列表一致
- [ ] `cli.py` 行数 < 400（软目标）

### Phase 4 — 收尾与门禁（0.5h）

- [ ] 更新 `AGENTS.md` / `skills/vlm-library-workflow/SKILL.md` 中的模块路径说明（若 CLI 拆分）
- [ ] PR 描述附：删除/归档清单、pytest 输出、`wc -l src/vlm/cli.py` 前后对比
- [ ] 不提交 `artifacts/`、`.nvimlog`、`.venv/`

---

## 5. 验证矩阵

| 检查项 | 命令/方法 |
|--------|-----------|
| 单元+集成测试 | `uv run pytest -q` |
| CLI 冒烟 | `uv run vlm --help`；`config validate`；`review-plan --help` |
| 可选 TUI 边界 | `uv run pytest tests/test_cli_review_plan.py -q` |
| 无死 import | `rg "vlm\.exceptions"` → 空 |
| 包可安装 | `uv pip install -e .` |

---

## 6. 风险与回滚

| 风险 | 等级 | 缓解 |
|------|------|------|
| 删除 `exceptions.py` 后未来 PR 又引入 import | 低 | PR 门禁 `rg exceptions` |
| `preferred_plan_summary` 与 `or _fallback` 空白语义差异 | 低 | 以 tests 为准；`test_plan_render` / report CLI 测试覆盖 |
| CLI 迁移遗漏 `pass_context` / 选项默认值 | 中 | 分命令迁移 + cli 集成测试 |
| 文档归档后外部链接失效 | 低 | archive README 写清迁移；根 README 不链旧文件 |

**回滚：** 按 Phase 逆序 revert；Phase 1 可单独 revert 且不影响 Phase 3。

---

## 7. 成功标准（Definition of Done）

1. **功能：** 所有现有 `vlm` 子命令、配置键、产物文件名与 schema 行为不变  
2. **测试：** `pytest -q` 全绿，数量不低于 517（允许因补测略增）  
3. **代码：** 无全仓库零引用 Python 模块；`cli.py` 仅负责注册与委托  
4. **文档：** 单一事实来源 = `README` + `CHANGELOG` + `CLAUDE`/`AGENTS`；历史计划进 `docs/archive/`  
5. **可维护性：** 新贡献者不再面对 6+ 份互相矛盾的 REVIEW/AUDIT 文档  

---

## 8. 工作量估算

| Phase | 估时 | 可独立合并 |
|-------|------|------------|
| 0 准备 | 0.5h | — |
| 1 删死代码 | 0.5–1h | ✅ 建议首 PR |
| 2 文档归档 | 0.5h | ✅ 可与 Phase 1 同 PR |
| 3 CLI 拆分 | 1–2d | ✅ 单独 PR |
| 4 收尾 | 0.5h | 随 PR |

**合计：** 约 2–3 个工作日（含 review），若只做 Phase 1+2 约 **半天**。

---

## 9. 建议 PR 拆分

| PR | 内容 | 标题示例 |
|----|------|----------|
| PR-1 | Phase 1 + 2 | `chore: remove unused code and archive stale docs` |
| PR-2 | Phase 3 | `refactor: extract remaining CLI commands to commands/` |
| PR-3（可选） | Phase 2 计划 3.6 | `refactor: split quarantine and align path guards` |

---

## 10. 执行后预期指标

| 指标 | 当前 | Phase 1+2 后 | Phase 3 后 |
|------|------|--------------|------------|
| `src/vlm/*.py` 模块数 | 36 | 35（-exceptions） | 35 + 4~5 command 模块 |
| `cli.py` 行数 | ~1941 | ~1935 | ~300–400 |
| 根目录 *.md（审查类） | ~12 | 0（已归档） | 0 |
| pytest | 517 | 517 | 517 |

---

*本计划只覆盖「删无贡献 + 合重复 + 搬 CLI」；更深的安全加固与 domain 文件拆分见后续 `plans/2026-*-phase2-internal-split-v1.md`（待 Phase 1–3 完成后再写）。*