windy/dl-organizer
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
6f0df5a774251aa0f9ef99c1114a63dd94bfb3d4
dl-organizer/docs/archive/2026-pre-baseline/2026-05-21-functional-code-simplification-plan-v1.md
T

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

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

  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：

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 完成后再写）。

Reference in New Issue View Git Blame Copy Permalink