AgentHarness 课程

Plan 模式深度解析

5.3K字·14分钟·
需求分析、任务拆解、AskUserQuestion苏格拉底式提问

引言

Plan 模式是 CodeBuddy 最具特色的功能之一，它让 AI 从"直接执行者"转变为"思考伙伴"。在 Plan 模式下，CodeBuddy 不会立即编写代码，而是先理解需求、提出澄清问题、制定实现方案，确认后再执行。

这种"先想后做"的工作方式，特别适合处理复杂需求、大型重构和架构设计等场景。本章将深入解析 Plan 模式的工作流程、提问策略和实战应用。

一、Plan 模式 vs 普通模式对比

1.1 核心差异

特性普通模式Plan 模式
工作方式理解需求后立即执行理解需求→提问→方案→确认→执行
适用场景简单明确的任务复杂模糊的需求
用户参与度低，主要在开始和结束高，全程参与决策
错误风险较高，可能理解偏差较低，多次确认减少误解
输出质量依赖 AI 理解准确度经过人工审核，质量更高
执行速度快，直接开始前期慢，后期快（减少返工）

1.2 何时使用 Plan 模式

适合使用 Plan 模式的场景：

  • 需求模糊或有多种实现方式
  • 涉及多个模块的大型重构
  • 架构设计和技术选型
  • 学习和理解复杂代码库
  • 团队协作项目的关键决策

不适合使用 Plan 模式的场景：

  • 简单明确的 bug 修复
  • 格式化和 lint 修复
  • 简单的文件操作
  • 已经有详细规范的任务

二、5 步工作流详解

2.1 流程总览

启动 Plan 模式 → 探索代码库 → 提出澄清问题 → 制定实现方案 → 确认后执行
     ↓              ↓              ↓              ↓              ↓
  /plan          读取文件        AskUser        输出方案        自动执行
  或 plan:       分析结构        Question       等待确认        逐步实施

2.2 步骤一：启动 Plan 模式

# 方式一：使用斜杠命令
/plan

# 方式二：在需求描述前加上 plan:
plan: 重构用户认证模块，支持多种登录方式

# 方式三：在对话中明确要求
"请先做一个实现方案，不要直接写代码"

2.3 步骤二：探索代码库

CodeBuddy 进入 Plan 模式后，会主动探索相关代码：

# CodeBuddy 会自动执行：
# 1. 读取项目结构
# 2. 分析相关文件
# 3. 理解现有架构
# 4. 识别依赖关系

# 你也可以引导探索方向：
"请先看一下 src/auth/ 目录的结构"
"重点看看现有的认证中间件是怎么实现的"

2.4 步骤三：提出澄清问题

这是 Plan 模式最核心的环节——CodeBuddy 通过提问来澄清需求：

CodeBuddy: 我分析了现有的认证模块，有几个问题需要确认：

1. 你说的"多种登录方式"具体包括哪些？
   - 用户名/密码
   - 手机号/验证码
   - 第三方 OAuth（微信/Google/GitHub）
   - 以上全部？

2. 现有的 JWT token 策略是否需要调整？
   - 当前：access_token 15分钟，refresh_token 7天
   - 是否需要支持"记住我"功能？

3. 数据库方面：
   - 用户表是否需要新增字段？
   - 第三方登录信息存储在独立表还是扩展用户表？

2.5 步骤四：制定实现方案

根据你的回答，CodeBuddy 输出详细的实现方案：

## 实现方案：多方式登录认证模块

### 架构设计
- 采用策略模式（Strategy Pattern）统一处理不同登录方式
- 新增 AuthProvider 接口，各登录方式实现该接口
- 使用 Passport.js 作为认证框架

### 文件变更
| 文件 | 操作 | 说明 |
|------|------|------|
| src/auth/providers/ | 新增 | 各登录方式的 Provider |
| src/auth/auth.service.ts | 修改 | 集成多种登录方式 |
| src/auth/auth.controller.ts | 修改 | 新增登录接口 |
| prisma/schema.prisma | 修改 | 扩展用户表 |

### 实施步骤
1. 定义 AuthProvider 接口
2. 实现 EmailProvider（用户名/密码）
3. 实现 PhoneProvider（手机/验证码）
4. 实现 OAuthProvider（第三方登录）
5. 修改 AuthService 集成各 Provider
6. 更新 API 接口
7. 编写测试用例

### 预计工作量
- 代码编写：约 2-3 小时
- 测试验证：约 1 小时
- 总计：约 3-4 小时

2.6 步骤五：确认后执行

# 确认方案
"方案没问题，开始执行吧"

# 或者提出修改
"第3步先做 OAuth，手机号验证后面再加"

# 或者要求细化
"请详细说明 Passport.js 的配置方式"

三、AskUserQuestion 四种场景

3.1 需求模糊场景

用户："优化一下首页性能"

CodeBuddy (Plan 模式):
我需要了解更多背景：

1. 当前首页有哪些性能问题？
   - 加载速度慢？（白屏时间长）
   - 交互卡顿？（点击响应慢）
   - 还是 Lighthouse 分数低？

2. 目标指标是什么？
   - FCP < 1.5s？
   - LCP < 2.5s？
   - CLS < 0.1？

3. 是否有现成的性能监控数据？

3.2 技术选型场景

用户："我想给项目加一个状态管理库"

CodeBuddy (Plan 模式):
项目目前使用 React，状态管理有几个主流选择：

| 方案 | 优点 | 缺点 | 适用场景 |
|------|------|------|----------|
| Zustand | 轻量、简单 | 生态较小 | 中小型项目 |
| Redux Toolkit | 生态成熟 | 样板代码多 | 大型复杂项目 |
| Jotai | 原子化、高性能 | 学习曲线 | 高性能要求 |
| Context + useReducer | 无额外依赖 | 性能问题 | 简单状态 |

几个问题：
1. 项目规模和团队熟悉度？
2. 是否需要持久化和离线支持？
3. 对包大小有要求吗？

3.3 复杂重构场景

用户："重构现有的 API 层，支持统一错误处理"

CodeBuddy (Plan 模式):
当前 API 层的问题我看到了：
- 错误处理分散在各个 controller
- 没有统一的错误码体系
- 响应格式不一致

重构方案需要确认：
1. 错误码体系：使用 HTTP 状态码还是自定义业务码？
2. 响应格式：是否统一为 { code, data, message } ？
3. 是否需要支持国际化错误消息？
4. 现有 API 是否需要全部迁移，还是渐进式重构？

3.4 学习探索场景

用户："帮我理解这个项目的认证流程"

CodeBuddy (Plan 模式):
我来帮你梳理。先确认几个问题：

1. 你想了解哪个层面？
   - 整体架构概览
   - 具体代码实现
   - 安全机制设计
   - 还是扩展开发指南

2. 你目前对哪些概念熟悉？
   - JWT
   - OAuth 2.0
   - 中间件模式

四、苏格拉底式提问法

4.1 什么是苏格拉底式提问

苏格拉底式提问法是一种通过连续提问引导思考的方法。CodeBuddy 的 Plan 模式借鉴了这种方法，通过提问帮助你：

  • 发现需求中隐藏的假设
  • 考虑被忽略的边界情况
  • 明确真正的需求目标
  • 理清实现的优先级

4.2 提问层次

# 第一层：事实性提问
"当前系统的用户量是多少？"

# 第二层：澄清性提问
"你说的'优化'是指响应时间还是吞吐量？"

# 第三层：假设性提问
"如果用户量增长10倍，当前方案还能支撑吗？"

# 第四层：开放性提问
"你觉得理想的用户体验应该是什么样的？"

五、完整实战案例

场景：设计一个实时聊天功能

# 用户输入
/plan 实现一个实时聊天功能

# CodeBuddy 的 Plan 模式响应
CodeBuddy: 我来帮你规划实时聊天功能。首先需要了解几个关键点：

## 需求澄清

1. **聊天类型**：
   - 一对一私聊
   - 群组聊天
   - 还是两者都要？

2. **实时性要求**：
   - 消息延迟容忍度？（< 100ms 还是 < 1s）
   - 是否需要消息送达回执？
   - 是否需要在线状态显示？

3. **功能范围**：
   - 文本消息
   - 图片/文件发送
   - 消息撤回
   - 历史消息加载
   - 消息搜索

4. **技术约束**：
   - 是否有现成的 WebSocket 基础设施？
   - 消息存储方案偏好？（MySQL/MongoDB/Redis）

# 用户回答
一对一和群聊都要，延迟<500ms，先做文本消息，
使用现有的 Socket.io，消息存 MySQL

# CodeBuddy 输出方案
## 实时聊天实现方案

### 技术选型
- WebSocket：Socket.io（已有基础）
- 消息存储：MySQL + Redis 缓存
- 消息队列：Redis Pub/Sub

### 数据库设计
- conversations 表：会话信息
- messages 表：消息记录
- participants 表：会话参与者

### API 设计
- POST /api/conversations：创建会话
- GET /api/conversations/:id/messages：获取历史消息
- WebSocket event：message:send / message:receive

### 实施步骤
1. 数据库迁移
2. Socket.io 事件定义
3. 消息发送/接收逻辑
4. 离线消息处理
5. 前端 UI 组件

确认后开始执行？

六、常见陷阱与最佳实践

常见错误

  1. 过度使用 Plan 模式：简单任务也用 Plan 模式，降低效率
  2. 需求描述太模糊：导致 AI 提问过多，流程冗长
  3. 跳过确认环节：方案未确认就执行，可能偏离需求
  4. 不回答澄清问题：AI 无法准确理解需求

最佳实践

  1. 明确使用场景：复杂需求用 Plan 模式，简单任务用普通模式
  2. 提供充分背景：在启动 Plan 模式时尽量描述清楚需求
  3. 认真回答问题：AI 的提问是为了更好地理解你的需求
  4. 审阅实现方案：在确认前仔细检查方案是否符合预期
  5. 灵活调整方案：可以要求 AI 修改方案的任何部分

总结

Plan 模式是 CodeBuddy 处理复杂需求的利器：

  1. 先想后做：避免理解偏差导致的返工
  2. 苏格拉底式提问：通过连续提问澄清需求
  3. 方案可视化：输出结构化的实现方案
  4. 人工确认：确保方向正确后再执行
  5. 灵活适用：适合需求模糊、技术选型、复杂重构等场景

下一章我们将探索 Subagents 子代理系统，了解如何通过并行执行提升效率。