Files

T

79797644e1 chore: trim dead code, modularize CLI, and archive stale docs

Extract review-plan, report, quarantine, state, and config handlers into
commands/ with shared cli_helpers; remove unused exceptions and duplicate
plan summary wrappers. Archive superseded review markdown, sync docs to
517-test baseline, and fix empty series titles when only a quality tag remains.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

2026-05-21 10:36:03 +08:00

11 KiB

Raw Blame History

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

日期： 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. 功能贡献判定标准

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

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

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

全仓库零 import（静态可证）
仅转发到另一函数的薄包装（调用方可直接调目标）
已完成且被 CHANGELOG 取代的历史计划/审查 markdown
与保留文档逐字重复、无额外运维价值的 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：

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）

功能： 所有现有 vlm 子命令、配置键、产物文件名与 schema 行为不变
测试： pytest -q 全绿，数量不低于 517（允许因补测略增）
代码： 无全仓库零引用 Python 模块；cli.py 仅负责注册与委托
文档： 单一事实来源 = README + CHANGELOG + CLAUDE/AGENTS；历史计划进 docs/archive/
可维护性： 新贡献者不再面对 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 完成后再写）。

11 KiB Raw Blame History Unescape Escape

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

1. 目标

2. 功能贡献判定标准

3. 审计清单

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

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

3.3 保留（有贡献，勿删）

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

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

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

4. 分阶段实施

Phase 0 — 准备（0.5h）

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

Phase 2 — 文档归档（0.5h）

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

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

5. 验证矩阵

6. 风险与回滚

7. 成功标准（Definition of Done）

8. 工作量估算

9. 建议 PR 拆分

10. 执行后预期指标

11 KiB

Raw Blame History

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