S03｜待办写入：让 AI 不再走一步忘一步，多步任务不再跑偏

在上一章 S02，我们给 Agent 装上了工具分发系统，能安全调用读、写、改、执行命令 4 个工具，已经是个能干活的智能体了。

但一遇到复杂任务，问题立刻暴露：做着做着跑偏、重复干活、忘了下一步干啥......

这一章 S03，我们给 Agent 加上会话级计划（待办清单），让它把 "要做什么、正在做什么、做完了什么" 明明白白写下来，彻底解决任务漂移。

---

本章核心信息

• 核心闭环：会话级计划 + 显式待办更新
• 工具数量：5 个（新增 todo 工具）
• 核心思想：把计划从模型脑子里，挪到系统看得见的地方

---

先看懂本章所有名词

1. 会话内规划

就是当前这一轮对话里的小计划。不是长期项目排期，不是后台任务，只是为了完成你现在这一个需求，列的几步操作清单。

2. Todo（待办）

可以理解成 Agent 的小笔记本 。模型通过 todo 工具，把计划写下来、更新进度，相当于给自己定任务。

3. Active Step / in_progress

当前正在做的那一步。同一时间只允许一个，防止 AI 三心二意、多线操作把任务搞乱。

4. 会话漂移

做着做着跑偏了：

• 忘记原本目标
• 重复执行相同步骤
• 想到哪做到哪加了计划就是为了按住它不跑偏。

5. PlanningState（计划状态）

专门存 "待办清单" 的状态，包括：

• 所有任务条目
• 每个条目的状态（待做 / 进行中 / 已完成）
• 多久没更新计划了

6. rounds_since_update

记录连续多少轮没更新计划。太久不更新，系统就提醒它：别光顾着干活，先看看清单！

7. reminder（提醒）

系统主动给模型发的小提示，比如："先更新你的计划再继续"。不是瞎提醒，是为了让计划一直生效。

---

这一章到底要解决什么问题？

到 S02 为止，Agent 已经会：读文件、写文件、改文件、执行命令。

但一遇到多步骤复杂任务，立刻暴露弱点：

1. 走一步忘一步让它先读文件 → 改代码 → 测运行，它可能改完就停了，忘了要测试。

2. 重复做无用功明明已经读过的文件，又重新读一遍。

3. 即兴发挥，越跑越偏一开始说的好好的，做着做着就歪了，完全偏离最初目标。

根本原因：模型的注意力是短暂的，全靠脑子里记，很容易断片。

解决方案：让 Agent 把计划写下来，变成看得见、能更新、可追踪的清单。

---

最小心智模型：一张图看懂本章逻辑

用户提一个复杂任务
    ↓

模型拆分成几步 → 写入 todo 计划
    ↓

计划状态：
  - [ ] 任务1（还没做）
  - [>] 任务2（正在做）
  - [x] 任务3（已完成）
    ↓

每做完一步 → 更新计划
    ↓

太久不更新 → 系统提醒
    ↓

全部完成 → 结束

重点不是 AI 会不会规划，而是：计划必须写出来，而不是放在它脑子里。

---

关键数据结构（超简单版）

1. 单个计划项 PlanItem

{
    "content": "读取 requirements.txt",
    "status": "pending" | "in_progress" | "completed",
    "activeForm": "正在读取 requirements.txt"
}

• content：这一步要干啥
• status：状态（待办 / 进行中 / 已完成）
• activeForm：进行时描述，让上下文更自然

2. 计划状态 PlanningState

{
    "items": [PlanItem...],
    "rounds_since_update": 0  # 几轮没更新计划
}

3. 一条重要规则

同一时间只能有一个 in_progress强制 AI 专注当前一步，不搞多线程混乱操作。

---

最小实现：怎么给 Agent 加上待办功能？

1. 建一个待办管理器

class TodoManager:
    def __init__(self):
        self.items = []  # 存所有待办

2. 让模型可以整体更新计划

def update(self, items: list):
    # 校验：最多一个进行中
    in_progress_count = 0
    for item in items:
        if item["status"] == "in_progress":
            in_progress_count += 1
    if in_progress_count > 1:
        raise ValueError("一次只能做一件事")

    self.items = items
    return 渲染后的计划文本

3. 把计划渲染成看得懂的列表

[ ] 读取 greet.py
[>] 给函数加文档字符串
[x] 创建文件 greet.py

4. 把 todo 加入工具路由

TOOL_HANDLERS = {
    "read_file": run_read,
    "write_file": run_write,
    "edit_file": run_edit,
    "bash": run_bash,
    "todo": lambda **kw: TODO.update(kw["items"])
}

5. 太久不更新计划就提醒

如果连续 3 轮都没改 todo，系统自动插入提醒：

<reminder>Refresh your plan before continuing.</reminder>

这标志着：主循环不再只管对话，还开始管理 "任务过程状态"。

---

它如何接入整个 Agent 系统？

之前 S01/S02 的 Agent 只维护：

• messages 对话历史

到了 S03，多了一个独立状态：

• PlanningState 计划状态

结构变成：

主循环
  ↓
messages（对话记忆） + planning_state（任务进度）
  ↓
模型推理
  ↓
调用工具 / 更新待办
  ↓
把结果写回
  ↓
继续下一轮

这是 Agent 非常重要的一次升级：从 "纯对话" 升级为 "带任务状态的工作流"。

---

S02 → S03 升级了什么？

模块	S02	S03
工具数量	4 个	5 个（加了 todo）
状态管理	只有 messages	消息 + 计划双状态
任务能力	单步、易跑偏	多步、可追踪、不漂移
模型行为	想到哪做到哪	按清单执行、聚焦当前步
主循环	不变	不变（只加状态）

---

初学者最容易踩的 5 个坑

1. 计划写太长列十几步，模型根本维护不过来，直接摆烂。

2. 多个任务同时进行中一会做这一会做那，越做越乱。

3. 把会话计划当成长期任务系统 这一章只是当前对话的小清单，不是后台任务平台。

4. 只在开头写一次计划不更新的计划 = 废纸，必须边做边改。

5. 觉得提醒没用 提醒非常关键，它代表系统开始主动控制任务流程。

---

本章教学边界（不搞复杂，只抓核心）

这一章不讲：

• 复杂任务依赖图
• 持久化存储
• 多智能体协作
• 后台任务调度

只讲一件最核心的事：把计划外显成结构化状态，能显著减少 Agent 跑偏。

---

一句话总结本章

S03 的 todo 不是什么高大上的任务平台，只是给 Agent 加了一个当前对话专用的外置小脑袋。让它把计划写下来、盯着当前步骤、持续更新，多步任务从此不再跑偏。