如何防止Agent执行任务时出现任务跑偏问题？

## 作用 ### 1. 用显式待办列表维护全局任务状态 复杂任务中，Agent 容易被最新的文件内容、命令输出或报错牵着走，陷入局部排错，忘记最初目标。`todo_write` 可将任务拆成可追踪的待办项，记录： - 哪些步骤尚未开始：`pending` - 哪一步正在执行：`in_progress` - 哪些步骤已经完成：`completed` 这样 Agent 每完成一轮工具调用后，都能对照列表确认： - 原始目标还剩哪些部分； - 当前动作服务于哪一项任务； - 是否还需要回到之前未完成的检查； - 是否真正满足了验收条件。 ### 2. 把自然语言目标转成可检查的承诺 待办项不能只写笼统动作，而应对应明确、可验证的完成条件。 例如： - 不建议只写：`扫描文件` - 更适合写：`确认项目中不存在不符合 snake_case 的 Python 文件` 又如： - 不建议只写：`修复测试` - 更适合写：`运行 pytest，并处理本次重命名引入的导入错误` 这样可以限制 Agent 的处理范围，避免它为了让测试通过而不断修改无关代码。 ### 3. 在排错后帮助 Agent 回到主任务 当测试失败或工具报错时，Agent 很容易持续追踪新错误。待办列表中仍保留“检查遗漏”“更新引用”等全局事项，可以提醒它修完当前问题后回到原始任务，而不是过早结束或无限排错。 ## 原理 ### 1. TodoWrite 本身不执行任务 `todo_write` 不读文件、不改代码、不运行命令，只负责接收并保存待办列表，例如： ```json [ {"content": "扫描不符合 snake_case 的文件", "status": "in_progress"}, {"content": "更新文件名和相关导入", "status": "pending"}, {"content": "运行测试并修复失败", "status": "pending"}, {"content": "检查是否有遗漏", "status": "pending"} ] ``` 工具会把列表保存在当前进程状态中，并展示当前任务进度。 ### 2. 通过对话历史成为模型的工作记忆 待办数据本身并不会直接参与模型推理，但每次调用 `todo_write` 时，待办内容和状态都会作为工具调用记录进入消息历史，并在下一轮请求中提供给模型。 因此，它提供的是一份显式、可更新的工作记忆，而不是长期记忆，也不能自动保证模型永远遵守计划。 ### 3. 关键在于持续更新状态 待办列表不能只在开始时写一次，而应随着执行过程不断更新： ```text 扫描文件：in_progress ↓ 扫描完成：completed ↓ 更新导入路径：in_progress ↓ 运行测试：in_progress ↓ 检查遗漏：completed ``` 每次状态更新都会明确两件事： - 已经完成了什么； - 当前应该关注什么。 ### 4. 增加提醒护栏 仅靠 System Prompt 要求“先制定计划并更新状态”，模型在长任务中仍可能忘记更新。可以在 Agent Loop 中加入计数器： - 普通工具调用后增加未更新计数； - 调用 `todo_write` 后将计数归零； - 长时间未更新时，向上下文注入提醒，如 `<reminder>Update your todos.</reminder>`。 这属于一种护栏，用来提醒 Agent 从局部工具结果中抬头，重新检查整体计划。提醒频率不应机械固定，而应结合任务复杂度、工具类型和上下文长度调整。 ### 5. 计划应允许修订 待办列表不是一次性的执行顺序表，而是一份可随实际情况修订的任务承诺。如果执行中发现任务拆分不合理，应更新列表；但每一项仍应保持明确的验收条件，避免 Agent 在未验证的情况下过早标记为完成。