CodeBuddy对话模式深度使用技巧指南
CodeBuddy 学习（2）：对话模式深度使用
使用CodeBuddy这类AI编程工具时，控制权分配是核心议题。何时让AI自主执行，何时必须等待人工审批，决定了开发效率与风险可控性。CodeBuddy的三种对话模式正是为此设计。
一、概述：三种模式的内在逻辑
为什么需要三种模式？
对话式AI编程的核心矛盾在于控制权分配。AI何时可以自主行动，何时必须等待确认，直接影响工作流效率与安全边界。
| 场景 | 控制权归属 | 匹配模式 |
|---|---|---|
| 提问/学习/讨论 | 你完全掌控，AI只输出信息 | Ask |
| 明确编码任务 | AI直接执行，你逐条审查 | Craft |
| 复杂不确定任务 | AI先规划，你确认后执行 | Plan |
三种模式并非简单三选一，本质是一条控制权逐级释放的递进路径：
Ask（只问不做）→ Craft（边做边调）→ Plan（先想后做）
核心原则：你越清楚目标，越可交给AI直接执行；越不确定，越应先用Ask或Plan收敛思路。切勿一上来就让AI动手，先问清楚再行动。
二、Ask模式：只读问答
原理讲解
Ask模式是约束最严格的模式——禁止修改任何文件，禁止执行任何命令。AI只输出信息，不产生副作用。
工作原理：
- AI接收你的问题，同时从当前打开的文件和项目中收集上下文。
- 通过
@引用可以在当前消息中注入特定文件的完整内容。 - AI基于上下文生成回复，所有回复均为纯文本，不产生任何副作用。
- 回复中可能包含代码片段，但需你手动复制到文件。
适用场景：
| 场景 | 你问什么 | 得到什么 |
|---|---|---|
| 学习API | “useEffect cleanup怎么写？” | 代码片段+使用说明 |
| 分析代码 | “解释这段业务逻辑” | 分步注释+风险标注 |
| 方案决策 | “方案A和B哪个好？” | 结构化对比分析 |
示例：分析遗留代码
假设项目中有以下代码文件order.ts，这是一个典型的遗留代码模块：
操作步骤：
- 在CodeBuddy中打开
order.ts。 - 切换到Ask模式。
- 在对话框中输入：
@file order.ts 请分析 processOrder 函数，包括： 1. 状态流转分支 2. 潜在的 Bug 和风险 3. 数据库事务重写的注意事项
预期输出会是类似这样的结构化分析：
状态流转分析：
cancelled / returned → 直接返回（不处理）
pending → 计算总价 → 检查余额 → 扣款 → 标记 paid
paid → 直接返回（幂等保护）
风险标注：
⚠ 高：高并发超扣风险
两个请求同时读取到相同的 userBalance，各自扣款后都认为余额足够，最终超扣。
数据库层应使用 SELECT ... FOR UPDATE 或乐观锁（version 字段）。
⚠ 中：数据一致性问题
函数只在内存中修改 order 对象，如果没有持久化步骤，状态变更会丢失。
建议增加一个 orderRepository.sa ve(order) 调用点。
⚠ 低：空数组免费漏洞
total === 0 时直接将状态设为 paid，可能导致空订单被标记为已支付。
应区分"空订单"和"总价为 0 的订单"。
事务重写注意事项：
1. 使用数据库事务包裹整个流程
2. 先锁定用户余额行（SELECT FOR UPDATE）
3. 在事务内完成：余额检查 → 扣款 → 订单状态更新
4. 全部成功后提交，任何一步失败则回滚调试过程
场景一：回答太泛，未聚焦核心问题
现象：AI给出了通用性分析，但没有深入具体的状态流转分支。原因在于问题描述过于开放，AI不知道你关心的侧重点。排查时检查原始问题是否包含明确的输出格式要求。修复方法很简单：收紧焦点，加上具体指令，比如“重点说明cancelled和returned的区别，以及process步骤中的余额检查顺序是否有问题”。
场景二：Ask模式下AI拒绝给出代码
现象：你问“怎么重构这个函数”，AI只提供了文字建议。这其实是Ask模式的预期行为——只给分析不给代码修改，属于安全设计。排查时确认对话面板顶部当前模式是否为Ask。如需生成代码，切换到Craft模式；或者把需求改为“请帮我写一个重构方案（伪代码）”，伪代码不算写文件，Ask模式通常会提供。
场景三：@file引用后AI似乎没看到文件
现象：提问@file order.ts后，AI的回复和文件内容无关。可能原因有两个：一是文件路径不匹配，AI没找到该文件；二是光标放错位置——@引用必须在对话输入框内手动输入。排查时检查文件是否当前在CodeBuddy项目中（IDE左侧文件树中可见），确认@file是通过弹出菜单选择的（而不是手动敲的路径字符串）。如果文件不在当前项目中，先用“文件 → 打开文件夹”打开包含该文件的目录。
三、Craft模式：让AI动手写代码
原理讲解
Craft模式是CodeBuddy的核心执行模式，AI获得了文件读写和终端命令执行权限，直接提升生产效率。
工作原理：
- 你描述需求，AI解析后规划执行步骤。
- AI依次执行：读取现有文件 → 生成代码 → 写入文件 → （可选）运行ESLint/测试 → 修复错误。
- 每步文件变更都以Diff视图展示，你可以逐条Accept或Reject。
- 每次写操作前，CodeBuddy会自动创建Checkpoint（快照），出问题时一键回滚。
Craft有四件法宝值得记住：
| 法宝 | 作用 | 使用时机 |
|---|---|---|
| Diff视图 | 查看所有变更细节 | 每次Accept前逐条审查 |
| Checkpoint | 一键回滚到修改前状态 | 改坏了、改错了 |
| @引用 | 限定AI操作范围 | 防止AI修改不该动的文件 |
| 否定约束 | 告诉AI不要做什么 | “不要改Props接口”“不要引入新依赖” |
示例一：从零创建登录组件
操作步骤：
- 切换到Craft模式。
- 确保项目使用TailwindCSS（如果没有，先用@file引用配置文件）。
- 在对话框中输入：
@folder src/components 请创建 LoginForm 组件，要求： - Props：onSubmit(email: string, password: string) => void - 包含邮箱输入框、密码输入框、提交按钮 - 校验：邮箱格式（正则）、密码至少 6 位 - 错误信息红色显示在对应输入框下方 - 使用 TailwindCSS 样式 - 使用 TypeScript - 创建后运行 ESLint 检查
AI执行过程：
Step 1: Write → src/components/LoginForm.tsx ← 写入组件文件
Step 2: Bash → npx eslint src/components/LoginForm.tsx ← ESLint 检查
Step 3: 如果 ESLint 0 error → 完成
如果有 error → AI 自动修复 → 再次检查
Step 4: Checkpoint 自动保存预期输出文件（src/components/LoginForm.tsx）：
验收步骤：
- 在Diff视图中审查所有变更，确认：
- Props接口未丢失属性。
- 错误提示文案是中文。
- 校验逻辑完整（空值+格式）。
- 没有引入额外依赖。
- 全部确认后，点击Accept保存。
示例二：Bug修复流程
场景：运行npm run dev后终端报错TypeError: Cannot read properties of undefined。
操作步骤：
- 在CodeBuddy内置终端中重新执行
npm run dev，确保错误输出完整。 - 切换到Craft模式。
- 输入：
@terminal @file src/hooks/useUsers.ts @file src/components/UserList.tsx 请分析终端报错，找出根因并修复。
预期执行过程：
Step 1: Read → 阅读 useUsers.ts 和 UserList.tsx
Step 2: Bash → grep 查找相关引用点
Step 3: Edit → 修复空值访问（添加 ?. 或 if 守卫）
Step 4: Bash → npm run dev → 验证通过调试过程
场景一：AI修改了不该动的东西
现象：你让AI“重构校验逻辑”，结果它连Props接口也改了，onSubmit签名从(email, password)变成了(data: LoginData)。排查步骤：第一步，Diff视图审查，发现接口变更；第二步，点击Checkpoint，选择修改前的快照，一键回滚；第三步，重新发送指令：“重构校验逻辑，但不修改LoginFormProps接口，保持onSubmit(email, password)签名不变”。教训很深刻：“不要改X”的否定约束往往比“要做Y”的正面指令更精确。
场景二：ESLint报错后AI修复循环
现象：AI写完代码后ESLint报错，AI自动修复，又引入新错误，陷入死循环。原因在于ESLint规则与AI的代码风格冲突。排查时先阅读ESLint输出，确认冲突的规则。如果冲突规则是项目必需的，就把具体规则告知AI。修复方式：输入“ESLint规则要求：函数必须有返回类型注解、禁止any类型、使用单引号。请按这些规则重新生成代码”。
场景三：终端命令执行失败
现象：AI执行npm run dev时报错“command not found: npm”。原因在于CodeBuddy的内置终端环境变量可能不完整。排查时先在CodeBuddy终端中手动执行npm --version，确认npm是否可用。如果不可用，检查Node.js安装和PATH配置。修复方式：Windows上重启CodeBuddy后再次尝试；macOS/Linux上确认~/.zshrc或~/.bashrc中有正确的PATH配置。
四、Plan模式：先规划再执行
原理讲解
Plan模式专门面向不确定性高、影响面广的任务。针对那些你不敢让AI直接动手的场景。
工作原理：
- 需求澄清阶段：AI不会直接动手，而是反过来提问。通过多轮问答消除需求歧义。
- 方案制定阶段：AI输出技术方案（数据模型、API设计、模块拆分），你审阅修改。
- 方案确认阶段：确认无误后切换到Craft模式执行。
- 逐步实施：按方案分阶段执行，每阶段完成后验证。
- 归档复用：方案文档保存在.codebuddy/目录，下次类似需求可直接参考。
什么时候用Plan，什么时候用Craft？
| 维度 | Plan | Craft |
|---|---|---|
| 清楚要做什么？ | 不太清楚 | 非常清楚 |
| 涉及模块数量 | 3个以上 | 1-2个 |
| 有前后端协作？ | 有 | 没有 |
| 失败损失 | 大（重构/迁移） | 小（Checkpoint可回滚） |
示例：电商优惠券功能规划
操作步骤：
- 切换到Plan模式。
- 输入：
我们是一个电商平台，需要加上优惠券功能。 支持的优惠券类型：固定金额减免、百分比折扣。 每张优惠券可以有使用次数限制。 请先做需求澄清。
阶段一：需求澄清
AI会逐条提问：
Q1: 一个订单可以使用多张优惠券吗？还是一单一券？
Q2: 优惠券有最低消费门槛吗（如满100减20）？
Q3: 优惠券能和会员折扣叠加吗？
Q4: 优惠券需要设置过期时间吗（绝对时间 or 领取后N天）？
Q5: 优惠券是全场的还是只能用于特定商品/分类？你的回答：
每单只能用一张优惠券。满100元可用。
不能和会员折扣叠加（选最优的那个）。
需要设置过期时间（绝对时间）。
全场通用（第一期不做商品/分类限制）。阶段二：方案制定
AI输出技术方案：
# 优惠券功能技术方案
## 数据模型
### coupons 表（优惠券模板）
| 字段 | 类型 | 说明 |
|------|------|------|
| id | int | 主键 |
| type | enum('fixed','percent') | 优惠券类型 |
| value | decimal | 面额（固定金额/百分比） |
| min_amount | decimal | 最低消费门槛 |
| max_uses | int | 全局最大使用次数 |
| used_count | int | 已使用次数 |
| expired_at | datetime | 过期时间 |
| is_active | boolean | 是否启用 |
### user_coupons 表（用户领取记录）
| 字段 | 类型 | 说明 |
|------|------|------|
| id | int | 主键 |
| user_id | int | 用户ID |
| coupon_id | int | 优惠券ID |
| used_at | datetime | 使用时间（null=未使用） |
## API 设计
GET /api/coupons/a vailable → 获取可用优惠券列表（带条件筛选）
POST /api/coupons/apply → 应用优惠券（计算折后价）
## 实施阶段
Phase 1: 数据模型 + CRUD（管理后台）
Phase 2: 优惠券使用逻辑（下单时计算优惠）
Phase 3: 前端展示（优惠券列表 + 使用入口）
Phase 4: 过期检查（定时任务清理过期券）阶段三：方案确认
你审阅后提出修改：
在coupons表加is_active字段很好。
user_coupons也要加一个status字段（unused / used / expired）。
Phase 2要补充：优惠券和会员折扣不能叠加时的选择逻辑。AI更新方案后，你确认，然后切换到Craft模式执行。
跑偏纠偏指南
| 偏差类型 | 表现 | 纠偏方法 |
|---|---|---|
| 需求理解错 | AI方案和你的预期差很远 | 回到阶段一，补充更多约束条件 |
| 方案太大 | 拆了20个Phase做不完 | 让AI按“最小可行产品”重新裁剪 |
| 实施有坑 | 执行中卡住、技术选型不对 | 暂停实施，修改Plan中对应部分，重新执行 |
调试过程
场景一：Plan模式下AI直接开始写代码
现象：你在Plan模式下提需求，AI没有做需求澄清，直接创建了文件。原因可能是模式切换未生效——当前实际处于Craft模式，或者需求描述过于具体，AI判断“不需要规划”就直接执行了。排查时确认对话面板顶部模式显示为“Plan”，或者在问题开头加一句“先做需求澄清，不要直接写代码”。修复方法：新建对话，重新选择Plan模式，用更开放的方式描述需求。
场景二：AI的澄清问题不够深入
现象：AI只问了1-2个表面问题就开始出方案。原因在于你的初始描述已经比较完整，AI觉得自己理解了。排查时如果方案中确实遗漏了关键点，说明AI没有真正理解。修复方法：主动补充“关于X方面，我还没有想清楚，请你多问几个问题帮我理清思路”。
五、组合拳：一天的标准工作流
三种模式不是孤立的，把它们组合起来，就能形成一条有节奏的编码流水线：
09:00 Ask → "useEffect deps数组怎么写？" → 学习/理解
09:30 Ask → "方案A vs 方案B？" → 决策
10:00 Plan → "按方案B规划重构" → Phase 1/2/3 → 确认 → 规划
10:30 Craft → Phase 1执行 → Diff审查 → Accept → 编码
11:00 Craft → Phase 2执行 → 测试3失败 → AI修复 → 通过 → 编码+修复
11:30 Ask → "还有什么可以优化的？" → 复盘/验证核心节奏：Ask评估 → Plan规划 → Craft执行 → Ask验证。
六、高效习惯总结
| 习惯 | 说明 |
|---|---|
| Diff必看 | Accept前逐条审查每一处变更 |
| 迭代推进 | 把大任务拆成小目标，每完成一个就验证 |
| Checkpoint兜底 | 重大修改前确认有快照，出问题秒回滚 |
| 否定约束 | “不要改X”比“做Y”更精准 |
| 一个对话一主题 | 避免多个不相关任务混在同一个对话里 |
七、快捷键速查
| 功能 | Windows | macOS |
|---|---|---|
| 打开对话面板 | Ctrl+Shift+V | Cmd+Shift+V |
| 内联编辑 | Ctrl+I | Cmd+I |
八、小结
Ask→只问不做：查API、看代码、做决策。Craft→直接动手：写代码、修Bug、跑终端，Checkpoint保底。Plan→先想后做：新功能、迁移、协同，零成本改方案。组合拳：Ask评估 → Plan规划 → Craft执行 → Ask验证。