AgentHarness 课程
CodeBuddy 专题/第 2 章

智能体模式入门

创建任务、任务管理、对话技巧、结果查看

引言：从被动回答到主动执行

传统 AI 编程助手的交互模式是「你问我答」——你提出问题，AI 给出答案。这种模式在简单场景下足够好用，但面对复杂任务时就显得力不从心：你需要手动拆解任务、手动执行每一步、手动验证结果。

CodeBuddy 的智能体模式（Agent Mode）彻底改变了这个范式。在智能体模式下，你只需要描述目标，AI 会自动规划、执行、验证，直到任务完成。这就是「你说目标，AI 去做」的工作方式。

本章将深入讲解智能体模式的核心概念、使用技巧和实战案例。

1. 智能体模式 vs 普通模式

1.1 核心区别对比

维度普通模式智能体模式
交互方式你问我答你说目标，AI 去做
任务规划用户手动拆解AI 自动规划
工具调用仅生成代码文本读写文件、执行命令、搜索代码
错误处理用户手动修复AI 自动重试和修复
结果验证用户自行检查AI 主动验证
适用场景快速问答、代码片段复杂任务、多步骤操作

1.2 什么时候用智能体模式？

适合使用智能体模式的场景：

  • 创建新功能（涉及多个文件）
  • 重构代码（需要理解整体结构）
  • 修复 Bug（需要分析和定位问题）
  • 添加测试（需要理解业务逻辑）
  • 项目初始化（需要搭建完整框架）

不适合的场景：

  • 简单的代码片段查询
  • 快速语法问题
  • 概念解释

2. 任务创建的三种方式

2.1 方式一：自然语言描述

最直接的方式，直接在对话框输入你的目标：

给项目添加用户认证功能，包括：
1. 注册页面（邮箱 + 密码）
2. 登录页面
3. JWT Token 认证
4. 路由保护中间件

AI 会自动：

  1. 分析现有项目结构
  2. 规划实现方案
  3. 创建/修改相关文件
  4. 安装必要依赖
  5. 编写测试用例

2.2 方式二：斜杠命令

使用斜杠命令快速创建标准化任务：

/add-task 实现用户注册功能
/add-task 添加单元测试
/add-task 配置 CI/CD 流水线

2.3 方式三：文件引用

通过 @ 引用特定文件，让 AI 针对性地处理：

请优化 @src/utils/parser.ts 的性能，
当前解析 1MB 文件需要 5 秒，目标是降到 500ms 以内

3. 任务状态与依赖管理

3.1 任务状态

状态含义可操作
Pending等待执行可重排优先级、可取消
In Progress正在执行可暂停、可查看日志
Completed已完成可查看结果、可回滚
Failed执行失败可重试、可查看错误
Paused已暂停可恢复、可修改

3.2 任务依赖

AI 会自动识别任务间的依赖关系，确保正确的执行顺序：

Task A: 创建数据库模型       -> 先执行
Task B: 创建 API 路由        -> 依赖 A
Task C: 创建前端页面         -> 依赖 B
Task D: 编写集成测试         -> 依赖 B, C

执行顺序：A -> B -> (C, D 并行)

3.3 任务查看命令

查看任务列表：  /tasks
查看任务详情：  /task <id>
重新执行任务：  /retry <id>
回滚任务：      /rollback <id>

4. 对话技巧

4.1 明确目标，而非步骤

不推荐：

帮我创建一个文件叫 user.ts，定义一个 User 接口，
然后创建一个 UserService 类，实现 CRUD 方法...

推荐：

创建一个用户管理模块，支持增删改查，使用 TypeScript，
数据存储用 PostgreSQL，遵循 RESTful 规范

区别：前者告诉 AI 每一步怎么做（限制了 AI 的发挥），后者告诉 AI 你要什么（让 AI 自己规划最优方案）。

4.2 提供上下文

不推荐：

修复这个 Bug

推荐：

用户反馈在 Safari 浏览器上，点击"提交订单"按钮后页面卡住，
控制台报 CORS 错误。其他浏览器正常。
@src/api/order.ts

关键上下文：

  • 问题现象
  • 复现条件
  • 相关文件
  • 已尝试的方案

4.3 分步确认

对于大任务，可以让 AI 先出方案再执行：

我想把项目的 CSS 从普通 CSS 迁移到 Tailwind CSS。
请先给出迁移方案，不要直接执行。

AI 会输出详细的迁移计划，你确认后再执行：

方案没问题，开始执行。先从 Header 组件开始。

5. 完整实战案例

5.1 场景：给现有 Express 项目添加 API 文档

项目背景：

  • Express.js 后端项目
  • 有 20+ 个 API 路由
  • 没有 API 文档

输入：

给项目添加 Swagger API 文档。要求：
1. 自动从路由代码中提取 API 信息
2. 支持请求参数和响应格式的文档
3. 文档页面可在线测试 API
4. 添加到 /api-docs 路径

AI 执行过程：

Step 1: 分析现有路由文件 (3个文件，20+路由)
Step 2: 安装依赖 (swagger-jsdoc, swagger-ui-express)
Step 3: 创建 swagger 配置文件 (config/swagger.ts)
Step 4: 在每个路由文件中添加 JSDoc 注释
Step 5: 创建文档中间件 (middleware/swagger.ts)
Step 6: 在 app.ts 中挂载 Swagger UI
Step 7: 启动服务器验证 /api-docs 可访问
Step 8: 运行测试确保没有破坏现有功能

输出结果：

  • 新增 2 个文件
  • 修改 4 个文件
  • 20+ 个 API 路由全部有文档
  • /api-docs 页面可在线测试

5.2 验证结果

AI 完成后，检查点面板显示：

  • 每个文件的变更 diff
  • 任务执行日志
  • 回滚按钮（如果不满意）

6. 常见陷阱与解决方案

陷阱 1：大任务导致上下文溢出

现象：AI 执行到一半，开始「遗忘」之前的步骤

原因：任务太大，上下文窗口被填满

解决：将大任务拆分为 3-5 个子任务，分步执行和验证

陷阱 2：AI 修改了不该改的文件

现象：AI 重构时意外修改了配置文件或公共模块

解决：

  • 在 Rules 中明确禁止修改的文件
  • 使用检查点功能及时回滚
  • 分步确认，先看方案再执行

陷阱 3：盲目信任 AI 的方案

现象：AI 给出的方案看起来正确，但有隐藏的安全问题

解决：

  • 涉及安全的代码必须人工审核
  • AI 不了解你的业务上下文，方案需要团队讨论
  • 运行完整的测试套件验证

总结

学习内容要点
模式对比智能体模式 = 你说目标，AI 去做
任务创建自然语言 / 斜杠命令 / 文件引用
对话技巧明确目标、提供上下文、分步确认
任务管理状态跟踪、依赖管理、回滚机制
实战案例完整的 API 文档添加流程

下一章预告：我们将学习代码补全和内联对话功能，了解 AI 如何在你编码的每一刻提供智能辅助。