Agent 双模式 —— Build vs Plan 全解析与规划模式实战

Build 模式工作流：
用户输入 → AI 理解 → 直接执行工具 → 输出结果 → 继续

Plan 模式工作流：
用户输入 → AI 理解 → 生成计划 → 用户确认 → 逐步执行 → 完成

# 场景 1：快速修复一个明确的 Bug
opencode
(opencode prompt)> 修复 login.py 第 42 行的空指针异常

# 场景 2：添加一个简单的函数
(opencode prompt)> 在 utils.py 中添加一个格式化日期的函数

# 场景 3：快速原型验证
(opencode prompt)> 创建一个 Flask 的 Hello World 应用

用户: 修复 login.py 的空指针异常
  │
  ▼
AI: 让我先查看 login.py 的内容
  │
  ▼
工具调用: read_file("login.py")
  │
  ▼
AI: 找到了问题，第 42 行 user.name 可能为空，我来修复
  │
  ▼
工具调用: edit_file("login.py", patch="...")
  │
  ▼
AI: 修复完成，让我运行测试验证
  │
  ▼
工具调用: terminal("python -m pytest tests/test_login.py")
  │
  ▼
AI: 测试通过，修复完成！

# 技巧 1：使用约束条件引导 Build 模式
(opencode prompt)> 修改 database.py 使用连接池，要求：
(opencode prompt)> 1. 使用 psycopg2 的 SimpleConnectionPool
(opencode prompt)> 2. 最大连接数设为 10
(opencode prompt)> 3. 保持现有的 API 接口不变

# 技巧 2：分步骤请求，逐步推进
(opencode prompt)> 第一步：帮我创建 user_model.py 的骨架

(opencode prompt)> 第二步：现在添加 CRUD 方法

(opencode prompt)> 第三步：添加单元测试

# 技巧 3：让 AI 在 Build 中自我验证
(opencode prompt)> 重写 parse_config 函数，完成后运行测试验证正确性

# 场景 1：大型架构重构
(opencode prompt)> 帮我把单体应用拆分为微服务架构

# 场景 2：添加一个完整的功能模块
(opencode prompt)> 添加一个完整的用户权限管理系统，包括：
(opencode prompt)> - 角色定义
(opencode prompt)> - 权限矩阵
(opencode prompt)> - 中间件验证
(opencode prompt)> - 管理界面

# 场景 3：技术栈迁移
(opencode prompt)> 将项目从 Flask 迁移到 FastAPI

用户: 添加用户权限管理系统
  │
  ▼
AI: [进入 Plan 模式] 让我先分析现有代码结构...
  │
  ▼
工具调用: 分析项目结构、查看相关文件
  │
  ▼
AI: 生成执行计划：

  📋 权限管理系统实施计划

  阶段一：数据模型设计
  ├── 1.1 创建 Role 模型
  ├── 1.2 创建 Permission 模型
  └── 1.3 创建 RolePermission 关联表

  阶段二：核心逻辑实现
  ├── 2.1 实现权限检查中间件
  ├── 2.2 实现角色分配服务
  └── 2.3 实现权限缓存层

  阶段三：API 接口
  ├── 3.1 角色管理 API
  ├── 3.2 权限管理 API
  └── 3.3 用户-角色绑定 API

  阶段四：测试与文档
  ├── 4.1 单元测试
  ├── 4.2 集成测试
  └── 4.3 API 文档

  预计修改文件：8 个
  预计新增文件：12 个

  是否开始执行？[Y/n]
  │
  ▼
用户: Y
  │
  ▼
AI: 开始执行阶段一...
  │
  ▼
[逐步执行各个阶段，每阶段完成后汇报进度]

📋 [任务名称] 实施计划

## 概述
简要说明任务目标和范围

## 前置分析
- 当前状态分析
- 影响因素评估
- 风险识别

## 执行计划

### 阶段 N：[阶段名称]
- [ ] 步骤 N.1：具体描述
  - 涉及文件：xxx
  - 预计工作量：小/中/大
- [ ] 步骤 N.2：具体描述
  ...

### 阶段 N+1：[阶段名称]
...

## 依赖关系
阶段一 → 阶段二 → 阶段三
         ↓
       阶段四（可与阶段三并行）

## 风险与备选方案
- 风险 1：描述 → 备选方案
- 风险 2：描述 → 备选方案

## 验收标准
- [ ] 标准 1
- [ ] 标准 2

┌─────────────────────────────────────────────┐
│  [Build]  [Plan]    ← 当前选中：Build       │
│                                             │
│  > 帮我优化数据库查询性能                    │
│                                             │
│  按 Tab 切换到 Plan 模式                    │
└─────────────────────────────────────────────┘

        ↓ 按 Tab

┌─────────────────────────────────────────────┐
│  [Build]  [Plan]    ← 当前选中：Plan        │
│                                             │
│  > 帮我优化数据库查询性能                    │
│                                             │
│  按 Tab 切换回 Build 模式                   │
└─────────────────────────────────────────────┘

何时切换到 Plan 模式？
│
├── 任务描述超过 3 行 → 切换 Plan
├── 涉及修改 5+ 个文件 → 切换 Plan
├── 包含架构决策 → 切换 Plan
├── 需要多阶段执行 → 切换 Plan
└── 不确定如何实现 → 切换 Plan

何时切换回 Build 模式？
│
├── 任务明确且简单 → 切换 Build
├── 快速原型验证 → 切换 Build
├── 修复小 Bug → 切换 Build
├── 添加单个函数 → 切换 Build
└── 计划已确认，进入执行阶段 → 切换 Build

# Build 模式下的典型行为
# 用户输入后，AI 立即开始：
# 1. 读取相关文件
# 2. 分析代码
# 3. 直接修改
# 4. 运行测试验证

# Plan 模式下的典型行为
# 用户输入后，AI 首先：
# 1. 读取相关文件（了解现状）
# 2. 分析问题
# 3. 生成结构化计划
# 4. 等待用户确认
# 5. 确认后逐步执行

# 用户输入
(opencode prompt)> [切换到 Plan 模式]
(opencode prompt)> 帮我将项目的错误处理从 try-except 模式
(opencode prompt)> 统一改造为自定义异常 + 全局异常处理器的模式

📋 错误处理统一重构计划

## 概述
将项目中分散的 try-except 错误处理改造为统一的自定义异常体系，
并添加全局异常处理器，提升代码可维护性和错误追踪能力。

## 前置分析
- 当前项目中有 23 处使用 try-except 直接捕获 Exception
- 涉及 8 个模块文件
- 部分异常处理缺少日志记录
- 没有统一的错误响应格式

## 执行计划

### 阶段一：定义异常体系
- [ ] 1.1 创建 exceptions.py 基础模块
  ├── 定义 AppException 基类
  ├── 定义业务异常子类（NotFoundError, ValidationError 等）
  └── 定义错误码枚举
  涉及文件：src/exceptions.py（新建）

- [ ] 1.2 定义错误响应模型
  ├── ErrorResponse 数据类
  └── 错误码到 HTTP 状态的映射
  涉及文件：src/models/error.py（新建）

### 阶段二：实现全局异常处理器
- [ ] 2.1 创建异常处理中间件
  ├── 捕获 AppException 并格式化响应
  ├── 捕获未知异常并记录日志
  └── 添加请求追踪 ID
  涉及文件：src/middleware/exceptions.py（新建）

- [ ] 2.2 注册全局异常处理器
  └── 在应用入口注册中间件
  涉及文件：src/app.py（修改）

### 阶段三：替换现有异常处理
- [ ] 3.1 替换 service 层的异常处理（5 个文件）
- [ ] 3.2 替换 api 层的异常处理（3 个文件）
- [ ] 3.3 替换 util 层的异常处理（2 个文件）
  每个文件：
  ├── 将裸 except 替换为具体异常
  ├── 添加异常日志
  └── 确保错误传播到全局处理器

### 阶段四：测试验证
- [ ] 4.1 单元测试：每个自定义异常
- [ ] 4.2 集成测试：异常处理中间件
- [ ] 4.3 回归测试：确保现有功能正常

## 依赖关系
阶段一 → 阶段二 → 阶段三 → 阶段四

## 风险与备选方案
- 风险：替换过程中可能遗漏某些异常处理
  → 方案：使用静态分析工具扫描所有 try-except
- 风险：新异常体系与第三方库不兼容
  → 方案：保留对第三方异常的适配层

## 预计工作量
- 新增文件：3 个
- 修改文件：10 个
- 预计时间：30-45 分钟

是否开始执行？[Y/n]

# 用户确认
(opencode prompt)> Y 开始执行

# AI 逐步执行
正在执行阶段一：定义异常体系...
✅ 创建了 src/exceptions.py
✅ 创建了 src/models/error.py

正在执行阶段二：实现全局异常处理器...
✅ 创建了 src/middleware/exceptions.py
✅ 修改了 src/app.py

正在执行阶段三：替换现有异常处理...
✅ 修改了 src/services/user_service.py
✅ 修改了 src/services/order_service.py
...

正在执行阶段四：测试验证...
✅ 12 个单元测试全部通过
✅ 5 个集成测试全部通过

🎉 重构完成！共修改 10 个文件，新增 3 个文件。

# 技巧 1：要求 AI 在计划中标注风险点
(opencode prompt)> 帮我设计一个缓存层，请给出详细计划，
(opencode prompt)> 特别标注可能的性能风险和一致性风险

# 技巧 2：要求 AI 分多个方案对比
(opencode prompt)> 帮我选择合适的数据库方案，请给出：
(opencode prompt)> - 方案 A：PostgreSQL
(opencode prompt)> - 方案 B：MongoDB
(opencode prompt)> - 方案 C：混合使用
(opencode prompt)> 每个方案都给出实施计划和优劣分析

# 技巧 3：要求 AI 只出计划不执行
(opencode prompt)> 请只做规划，不要执行任何代码修改
(opencode prompt)> 我需要先评审计划后再决定是否执行

# 技巧 4：计划执行中的中途调整
(opencode prompt)> 暂停当前计划
(opencode prompt)> 先修改阶段二的实现方式，改用装饰器模式
(opencode prompt)> 然后继续

收到任务
    │
    ▼
任务是否明确？
    ├── 是 → 涉及文件是否 > 3？
    │           ├── 是 → 需要架构决策？
    │           │           ├── 是 → 【Plan 模式】
    │           │           └── 否 → 【Build 模式】
    │           └── 否 → 【Build 模式】
    │
    └── 否 → 是否需要分步骤？
                ├── 是 → 【Plan 模式】
                └── 否 → 先切换到 Plan 模式让 AI 分析

# 1. 先在 Plan 模式下生成整体计划
(opencode prompt)> [Plan 模式] 帮我设计一个完整的用户认证系统

# 2. AI 生成计划后，你评审并确认

# 3. 确认后切换到 Build 模式执行具体步骤
(opencode prompt)> [Build 模式] 开始执行阶段一：创建数据模型

# 4. 每个阶段完成后，评估是否需要调整后续计划
(opencode prompt)> [Plan 模式] 阶段一已完成，阶段二的计划需要调整吗？

# 1. 先在 Build 模式下快速验证想法
(opencode prompt)> [Build 模式] 快速写一个文件上传的原型

# 2. 原型验证可行后，切换到 Plan 模式做完整设计
(opencode prompt)> [Plan 模式] 原型可行，现在请给出完整的生产级实现计划

# 3. 确认后执行完整实现
(opencode prompt)> 开始执行

请帮我规划以下任务：

## 任务描述
[详细描述你要完成的任务]

## 当前状态
[描述项目的当前状态、已有的相关代码]

## 约束条件
- [列出技术约束，如必须使用某个库]
- [列出时间约束]
- [列出兼容性要求]

## 期望输出
- [ ] 详细的阶段划分
- [ ] 每个阶段的具体步骤
- [ ] 涉及的文件列表
- [ ] 风险点和备选方案
- [ ] 验收标准

请只做规划，不要执行任何代码修改。

评审计划时，检查以下方面：

- [ ] 阶段划分是否合理？
- [ ] 是否有遗漏的步骤？
- [ ] 依赖关系是否正确？
- [ ] 风险评估是否全面？
- [ ] 是否有更好的实现方案？
- [ ] 工作量预估是否合理？
- [ ] 是否需要拆分为更小的任务？
- [ ] 是否考虑了向后兼容性？