dl-organizer/docs/archive/2026-pre-baseline/2026-04-02-review-plan-output-refactor-v1.md

Review-Plan Output Refactor Plan

Objective

在不修改 plan.json schema、不中断现有 CSV 手工审核流程的前提下，重构 vlm review-plan 的输出体验，让用户在终端中直接看到计划的核心内容和可审核的操作预览，减少必须打开 plan.json 才能继续操作的成本。

Validated Baseline

• review-plan 当前只输出计划加载提示、风险统计、CSV 保存路径和前 5 条样例，没有输出完整计划预览，见 src/vlm/cli.py:536-563。
• ExecutionPlan 已包含 operations、summary、summary_by_reason、human_summary、metadata，足以支撑更强的终端展示，见 src/vlm/models.py:133-153。
• 计划保存时会把上述字段全部写入 JSON，因此无需改动 plan schema，见 src/vlm/planner.py:591-625。
• CLI 中已经存在 fallback 计划摘要逻辑，可复用于 review-plan，见 src/vlm/cli.py:976-987。
• execute 已经采用“计划概要 + 样例操作”的输出方式，可作为统一风格参考，见 src/vlm/commands/execute.py:84-103 和 src/vlm/commands/execute.py:137-146。
• 当前测试只覆盖 summary 和 CSV 导出，未覆盖完整计划预览输出，见 tests/test_cli_review_plan.py:31-88。

Recommended Approach

采用推荐方案：抽离通用渲染层，并为 review-plan 提供受控预览输出。

原因：

1. 只加 human_summary 无法解决“看不到计划内容”的核心问题。
2. 直接打印全部 operations 会在大计划场景下严重刷屏。
3. 抽离通用渲染层可以同时提升用户体验、结构清晰度和后续复用性。

Scope

In Scope

• 优化 review-plan 的终端输出结构。
• 复用已有 human_summary / fallback summary。
• 增加受控的操作预览输出。
• 为计划展示提取可复用 helper。
• 补充 CLI 测试，覆盖新增展示行为。

Out of Scope

• 修改 ExecutionPlan 数据模型。
• 修改 plan.json schema。
• 修改 review CSV 字段或 apply-review 工作流。
• 引入交互式 TUI/Web 界面。

Implementation Plan

• Task 1. [Status: Done] 重新定义 review-plan 的输出顺序为“计划概览 → 风险统计 → 操作预览 → CSV 路径”，优先展示决策信息，再展示审核细节，以替代当前仅有 summary 和 5 条样例的输出方式，现状见 src/vlm/cli.py:546-563。
• Task 2. [Status: Done] 在 review-plan 中优先输出 ExecutionPlan.human_summary，若为空则复用现有 fallback summary，避免重复设计摘要逻辑并统一跨命令体验，相关能力见 src/vlm/planner.py:169-184、src/vlm/cli.py:976-987。
• Task 3. [Status: Done] 提取统一的计划终端渲染 helper，负责 plan header、summary、reason 分布和 operation preview 的格式化输出，避免 CLI 命令函数继续承载大量展示细节，参考现有输出风格见 src/vlm/commands/execute.py:84-103。
• Task 4. [Status: Done] 设计受控预览机制，默认仅展示有限条操作并提示剩余数量，同时预留完整显示模式的扩展点，以兼顾可读性和信息完整性。
• Task 5. [Status: Done] 在预览输出中优先展示审核价值最高的字段，包括 index、operation_type、risk_flags、source_path、destination_path、reason，以便用户在不打开 JSON 的情况下完成多数审核判断，字段来源见 src/vlm/plan_review.py:75-83 和 src/vlm/planner.py:606-620。
• Task 6. [Status: Done] 保持 ExecutionPlan 模型、plan JSON schema 和 review CSV schema 完全兼容，将改动严格限制在输出层，降低对 execute、report 和 apply-review 的影响，相关结构见 src/vlm/models.py:133-153 和 src/vlm/planner.py:591-625。
• Task 7. [Status: Done] 扩展 review-plan CLI 测试，覆盖默认摘要输出、受控预览、完整显示模式、CSV 不变性和原有 summary 输出兼容性，弥补当前测试缺口，基线见 tests/test_cli_review_plan.py:31-88。
• Task 8. [Status: Done] 评估是否将 execute 的计划摘要展示逐步迁移到同一渲染 helper，减少跨命令输出风格分叉，参考现有入口见 src/vlm/commands/execute.py:84-103 和 src/vlm/commands/execute.py:137-146。
• Task 9. [Status: Done] 在最终验收中重点验证大计划场景下的可读性，确保默认输出足够简洁、重点清晰，并且不影响后续 apply-review 使用链路，相关流程见 src/vlm/cli.py:589-643。

Verification Criteria

• vlm review-plan 默认输出中包含计划摘要，而不只是风险计数。
• 默认输出中包含可读的操作预览，且预览字段足以支持人工初步审核。
• 大计划场景下默认输出不会无上限刷屏，并会提示仍有未展示操作。
• review CSV 的字段、写入逻辑与后续 apply-review 流程保持兼容，相关链路见 src/vlm/plan_review.py:89-96 和 src/vlm/cli.py:621-643。
• plan.json 的 schema、读写行为与现有字段保持不变，见 src/vlm/planner.py:591-625 和 src/vlm/planner.py:628-671。
• CLI 测试覆盖新增预览行为，并保留现有 summary/CSV 行为验证，基线见 tests/test_cli_review_plan.py:31-88。

Risks and Mitigations

1. 默认输出过长，降低可读性
   Mitigation: 使用默认限量预览，只展示高价值字段，并明确提示剩余条目数量。

2. 展示逻辑分散，后续难维护
   Mitigation: 将计划渲染抽离为统一 helper，让 CLI 命令函数只负责流程编排与参数处理。

3. 改动误伤 CSV 手工审核链路
   Mitigation: 将 CSV 视为稳定接口，不调整字段结构与导出逻辑，保持 src/vlm/plan_review.py:89-96 行为不变。

4. CLI 输出测试过于脆弱
   Mitigation: 测试聚焦结构性关键片段与核心字段，不对整段输出做过度刚性匹配。

Alternatives Considered

1. 仅增加 human_summary 输出
   优点：改动最小，交付最快。
   缺点：仍然看不到操作层内容。

2. 直接打印全部 operations
   优点：实现简单，信息最完整。
   缺点：大计划会严重刷屏。

3. 抽离通用渲染层并提供受控预览
   优点：用户体验、可维护性与复用性最平衡。
   缺点：实现成本略高于局部修补。
   结论：推荐采用。

Recommended Outcome

推荐采用“仅重构展示层、不改数据层”的方案：

• 保持 ExecutionPlan、plan JSON、review CSV 全部兼容。
• 为 review-plan 增加计划摘要与受控操作预览。
• 把计划展示逻辑抽离为可复用渲染能力。
• 用测试确保 CLI 可见行为稳定。

这样可以以最小风险解决当前“review 时看不到计划内容”的核心问题。