Spring AI Agent 模式：利用 TodoWriteTool 解决任务遗忘
研究表明，大语言模型存在一个被称为'Lost in the Middle'的问题——当上下文变长时，模型对中间位置的信息注意力会显著下降。开头和结尾的内容记得清清楚楚，中间的任务就容易被'遗忘'。当你的 Agent 需要同时处理文件编辑、测试执行、文档更新等多个步骤时，某些重要步骤就可能悄无声息地消失了。
你有没有遇到过这种情况：让 AI Agent 执行一个复杂的多步骤任务，结果它做到一半就悄悄跳过了某个关键步骤？比如你让它修改代码、运行测试、更新文档，最后发现测试根本没跑。
这不是个例。Claude Code 给出了一个思路：让规划变得显式且可观察。
具体做法是引入一个专门的 TodoWrite 工具，让 Agent 在执行任务前先列出待办清单，然后逐项完成、逐项打勾。这样一来，Agent 不再是'心里默默记着要做什么'，而是'白纸黑字写下来，做一件划一件'。
本文将介绍 Spring AI 中的 TodoWriteTool，探讨其如何为 Agent 带来结构化的任务管理能力。
TodoWriteTool 是什么
简单来说，TodoWriteTool 是一个让大语言模型能够创建、跟踪和更新任务列表的 Spring AI 工具。
它的设计灵感来自 Claude Code 的 TodoWrite 功能，核心思想是把隐式的规划变成显式的、可追踪的工作流。完整实现可以在 GitHub 上找到：TodoWriteTool.java
当 Agent 收到一个复杂任务，比如'在设置页面添加深色模式开关并运行测试'，它会先用 TodoWriteTool 把任务分解成若干子任务：
- 创建深色模式开关组件 - 在 Settings 页面添加 UI 组件
- 添加状态管理 - 使用 context 或 store 管理深色模式状态
- 实现主题样式 - 添加深色主题的 CSS 样式
- 运行测试 - 确保功能正常工作
每当需要更新计划——无论是创建初始任务、标记进度，还是添加新发现的工作——LLM 都会调用这个工具。
任务状态的生命周期
这个工具接受一个待办项列表，每个待办项包含 id、content（要做什么）和 status（状态）。每个待办项遵循简单的生命周期：
- pending - 待办，还没开始
- in_progress - 进行中，正在处理
- completed - 已完成
这里有一个重要的约束：同一时间只能有一个任务处于 in_progress 状态。
这个设计强制 Agent 专注于顺序执行，而不是分散地尝试并行处理多个任务。对于 LLM 来说，这种约束能有效避免注意力分散导致的遗漏。
执行过程中的进度展示看起来是这样的：
Progress: 2/4 tasks completed (50%) [✓] 查找 Tom Hanks 前 10 部电影 [✓] 将电影两两分组 [→] 打印反转后的标题 [ ] 最终总结
LLM 如何知道何时使用这个工具
工具描述中包含了使用指导：
"当任务需要 3 个或更多不同的步骤或操作时使用此工具。如果只有一个简单任务，且可以在 3 个简单步骤内完成，则跳过使用。"
这种自治行为意味着 Agent 会根据任务复杂度自主决定是否创建任务列表。简单任务直接执行，复杂任务先规划再执行。
为了获得更好的效果，建议在系统提示词中加入详细的任务管理说明。项目中提供了一个参考示例 MAIN_AGENT_SYSTEM_PROMPT_V2，这是一个受 Claude Code 启发的提示词模板。
