1. 项目概述:TodoWrite 模块的设计初衷
在开发AI代理(Agent)时,我发现大语言模型(LLM)有个让人头疼的特性——它们像金鱼一样健忘。特别是在处理需要多步操作的长链路任务时,模型常常会忘记自己已经完成了哪些步骤,或者突然跳到一个完全不相关的操作上。这种现象在技术文档中被称为"Models Forget"(模型健忘问题)。
举个例子,当你让AI代理重构一个Python文件时,理想情况下它应该按顺序完成:1)添加类型提示 2)补充文档字符串 3)添加main守卫。但实际上,模型可能在完成第一步后就突然开始修改不相关的代码,或者重复已经做过的步骤。这种问题随着任务步骤的增加会愈发严重,因为工具调用的结果不断填充上下文,最初的系统提示影响力逐渐被稀释。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 核心问题拆解:为什么模型会"健忘"?
2.1 注意力机制的局限性
大语言模型基于Transformer架构,其核心是自注意力机制。虽然理论上注意力机制可以捕捉长距离依赖,但实际上:
- 上下文窗口有限:即使现代模型支持长上下文(如Claude 3的200K tokens),有效注意力范围仍有限
- 注意力稀释:随着对话轮次增加,关键信息被淹没在大量工具调用结果中
- 缺乏持久记忆:模型没有真正的"记忆"能力,每次推理都是基于当前上下文重新计算
2.2 多步任务执行的挑战
在长链路任务中,模型面临几个典型问题:
- 进度丢失:忘记已经完成哪些步骤
- 步骤跳跃:跳过关键中间步骤直接尝试最终目标
- 任务混淆:同时尝试处理多个不相关的子任务
- 上下文污染:工具调用的输出挤占了关键指令的空间
3. TodoWrite 解决方案架构
3.1 系统设计概览
TodoWrite模块的核心思想是:强制模型显式管理任务状态。整个系统的工作流程如下:
code复制用户输入 → LLM处理 → 工具调用(含todo工具) → 结果返回
↑ ↓
← 状态提醒机制 ←
关键组件包括:
- TodoManager类:维护任务列表状态
- todo工具:允许模型更新任务状态
- 提醒机制:防止模型忘记更新任务列表
3.2 TodoManager 类实现细节
这个Python类是整个系统的状态管理中心,主要功能包括:
python复制class TodoManager:
def __init__(self):
self.items = [] # 存储所有任务项
def update(self, items: list) -> str:
# 验证任务状态合法性
validated = []
in_progress_count = 0
for item in items:
# 状态必须是三者之一
if item["status"] not in ("pending", "in_progress", "completed"):
raise ValueError("Invalid status")
if item["status"] == "in_progress":
in_progress_count += 1
validated.append(item)
# 关键约束:同一时间只能有一个进行中任务
if in_progress_count > 1:
raise ValueError("Only one task can be in_progress")
self.items = validated
return self.render() # 返回格式化后的任务列表
def render(self) -> str:
# 将任务列表转换为易读的字符串格式
lines = []
for item in self.items:
marker = {
"pending": "[ ]",
"in_progress": "[>]",
"completed": "[x]"
}[item["status"]]
lines.append(
