# 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

- [x] Task 1. [Status: Done] 重新定义 `review-plan` 的输出顺序为“计划概览 → 风险统计 → 操作预览 → CSV 路径”，优先展示决策信息，再展示审核细节，以替代当前仅有 summary 和 5 条样例的输出方式，现状见 `src/vlm/cli.py:546-563`。
- [x] Task 2. [Status: Done] 在 `review-plan` 中优先输出 `ExecutionPlan.human_summary`，若为空则复用现有 fallback summary，避免重复设计摘要逻辑并统一跨命令体验，相关能力见 `src/vlm/planner.py:169-184`、`src/vlm/cli.py:976-987`。
- [x] Task 3. [Status: Done] 提取统一的计划终端渲染 helper，负责 plan header、summary、reason 分布和 operation preview 的格式化输出，避免 CLI 命令函数继续承载大量展示细节，参考现有输出风格见 `src/vlm/commands/execute.py:84-103`。
- [x] Task 4. [Status: Done] 设计受控预览机制，默认仅展示有限条操作并提示剩余数量，同时预留完整显示模式的扩展点，以兼顾可读性和信息完整性。
- [x] 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`。
- [x] 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`。
- [x] Task 7. [Status: Done] 扩展 `review-plan` CLI 测试，覆盖默认摘要输出、受控预览、完整显示模式、CSV 不变性和原有 summary 输出兼容性，弥补当前测试缺口，基线见 `tests/test_cli_review_plan.py:31-88`。
- [x] Task 8. [Status: Done] 评估是否将 `execute` 的计划摘要展示逐步迁移到同一渲染 helper，减少跨命令输出风格分叉，参考现有入口见 `src/vlm/commands/execute.py:84-103` 和 `src/vlm/commands/execute.py:137-146`。
- [x] Task 9. [Status: Done] 在最终验收中重点验证大计划场景下的可读性，确保默认输出足够简洁、重点清晰，并且不影响后续 `apply-review` 使用链路，相关流程见 `src/vlm/cli.py:589-643`。

## Verification Criteria

- [x] `vlm review-plan` 默认输出中包含计划摘要，而不只是风险计数。
- [x] 默认输出中包含可读的操作预览，且预览字段足以支持人工初步审核。
- [x] 大计划场景下默认输出不会无上限刷屏，并会提示仍有未展示操作。
- [x] review CSV 的字段、写入逻辑与后续 `apply-review` 流程保持兼容，相关链路见 `src/vlm/plan_review.py:89-96` 和 `src/vlm/cli.py:621-643`。
- [x] `plan.json` 的 schema、读写行为与现有字段保持不变，见 `src/vlm/planner.py:591-625` 和 `src/vlm/planner.py:628-671`。
- [x] 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 时看不到计划内容”的核心问题。