Planning · write_todos 模式

把目标外化为可读写的 todo 列表——同时解决"agent 忘了在做什么"和"调试时看不见 plan"两个老问题。

1. 没有它会怎样：一个具体的反例

设想一个 agent 接到这样一个任务："给我们的 Postgres 慢查询出一份分析报告，包含 top 10 慢 SQL、对应表与索引、改写建议、估算收益。"

没有 planning 的 agent 会发生什么：

• 第 1-3 轮：执行 SQL 查询、grep 慢日志，找到 top 10 候选——很顺。
• 第 4-8 轮：分析每条 SQL，看 EXPLAIN PLAN——开始走神，给某条 SQL 写了 200 字详细分析，给另一条只写一行。
• 第 9-12 轮：发现需要查 pg_stat_user_indexes——忘了原本要做完整 10 条，开始无限钻第 4 条 SQL 的细节。
• 第 13 轮：被 max_steps 截断，或者直接 final_answer 一份"看上去完整但只覆盖了 4 条"的报告——并且它自己不知道。

问题不是模型不够聪明。问题是——在第 13 轮，它的 prompt 已经有几万 token，原始 user 目标在 prompt 中部，注意力衰减早就让它"忘了完整 10 条"这个数字了（参考 00 章 05 节 Lost-in-the-Middle）。

write_todos 的整个目的，就是不让这个事发生——把"还剩几条没做"做成可读写的状态，让模型每轮都能稳定看见它。

2. write_todos 的真实样子

tool schema 极度简单——它就是一个"完整覆盖式"的写操作：

{
  "name": "write_todos",
  "description": "Maintain the task plan. Call this whenever the plan changes:
  initially to create it; after each meaningful step to update status; when
  scope changes to add/remove items. Always pass the COMPLETE list.",
  "parameters": {
    "type": "object",
    "properties": {
      "todos": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "id":      {"type": "string"},
            "content": {"type": "string"},
            "status":  {"type": "string",
                          "enum": ["pending", "in_progress", "completed", "blocked"]}
          },
          "required": ["id", "content", "status"]
        }
      }
    },
    "required": ["todos"]
  }
}

3. 内部最小实现（30 行）

# state schema：把 todos 放到 agent 全局 state 的一个字段
from typing import Annotated, TypedDict, Literal

class Todo(TypedDict):
    id: str
    content: str
    status: Literal["pending", "in_progress", "completed", "blocked"]

class AgentState(TypedDict):
    messages: list                           # 对话历史
    todos:    list[Todo]                     # planner state

# write_todos 的 tool 实现：覆盖式写入 + 把"当前 plan"序列化进 message
def write_todos(state: AgentState, todos: list[Todo]) -> AgentState:
    st