docs: archive completed functional simplification plan

Co-authored-by: Cursor <cursoragent@cursor.com>

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

@@ -0,0 +1,266 @@
+# 修改计划：只保留对功能有贡献的代码
+
+**日期：** 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 完成后再写）。*