问题

Agent 执行 30 步的复杂任务，到第 20 步时上下文早已挤爆：它忘了哪些步骤做过、哪步失败了、下一步该干嘛——开始重复劳动或原地打转。

核心模式

进度追踪：把任务状态从对话历史里抽出来，维护一份结构化的 TODO 清单，每步执行前后显式更新。

class TaskBoard:
    items: list[TodoItem]  # {content, status: pending|doing|done|failed, result}

    def system_injection(self):
        return f"""当前任务进度：
{format_board(self.items)}
规则：每完成一项立即标记 done 并记录结果摘要；
连续两项 failed 时停下来汇报，不要硬闯。"""

# 每轮把 board 快照注入 system 或 user 消息头部
agent.loop(on_step=lambda: inject(board.system_injection()))

这份清单是 Agent 的"工作台账"：对话历史可以被压缩（第 02 讲），但台账始终在场，保证全局方向不丢。

实战要点

  • 粒度是艺术：太细（"打开文件"）浪费 token，太粗（"完成开发"）没有导航价值；以"一次工具调用能完成"为下限
  • 失败项要保留原因摘要，这是第 08 讲失败日记的输入
  • 长任务每 N 步强制 Agent 复述进度并对账——台账与现实漂移是长任务的隐形杀手
  • Claude Code 的 TodoWrite 工具就是这个模式：模型自主维护清单，系统只负责渲染注入