04 Hook System → 05 规划系统

规划系统

Agent 的大脑 —— 先想后做,让每一步行动都有章可循

📋

想象你去超市购物前,先写一张购物清单:
牛奶、面包、鸡蛋、蔬菜……
有了清单,你就不会在超市里迷路,也不会忘买东西。

规划系统就是 Agent 的「购物清单」。

↓ 向下滚动开始学习
1

什么是规划系统?

没有计划的 Agent 就像没有地图的旅行者 —— 会漂泊

🧠 核心理念:先想后做(Think Before Act)

一个 Agent 面对复杂任务时,不应该立刻动手,而应该先规划—— 把大任务拆成小任务,确定优先级,理清依赖关系,然后一步步执行。

❌ 没有规划

接到任务就冲,做到一半发现漏了依赖,回头重做,效率低下。

✅ 有规划

先列出任务清单,理清依赖,按优先级执行,有条不紊地完成。

🏗️ 类比:盖房子之前需要蓝图,
旅行之前需要行程规划,
Agent 执行任务之前需要规划系统。

🧩 两大核心组件

📝

TodoWrite

任务列表管理器
增删改查任务清单
像冰箱上的便利贴

📊

TaskManager

任务依赖与执行引擎
管理依赖、优先级、状态
像项目经理的甘特图

2

TodoWrite:任务清单可视化

像便利贴一样管理你的待办事项

📋 任务看板

点击任务卡片可以切换状态 →

⏳ 待办
编写用户文档 MEDIUM
代码审查 HIGH
🔄 进行中
设计数据库 Schema CRITICAL
✅ 完成
搭建项目框架 CRITICAL

⚡ TodoWrite 六大操作

➕
add

添加新任务

✏️
update

更新任务内容

✅
complete

标记完成

🚫
cancel

取消任务

📃
list

列出所有任务

🗑️
clear

清空任务列表

3

TaskManager:依赖关系图解

有些任务必须等其他任务完成才能开始

🔗 任务依赖关系示例

场景:搭建一个 Web 应用。注意箭头方向 —— 被依赖的任务必须先完成。

✅ 搭建项目框架
Priority: CRITICAL
✅ 设计数据库
blocked_by: 框架
🔄 实现 API 接口
blocked_by: 数据库
🔒 编写前端页面
blocked_by: API 接口
🔒 集成测试
blocked_by: 前端 + API

🔄 任务状态流转

Pending
待定
→ Ready
就绪
→ Running
运行中
→ Completed
已完成
Running → Failed
失败
或 Ready → Blocked
阻塞

🎯 优先级体系

🔴 CRITICAL 关键 > 🟠 HIGH 高 > 🟡 MEDIUM 中 > ⚪ LOW 低
4

TodoWrite 代码详解

一个简洁的任务列表管理器

Python
class TodoItem:
    """单个待办事项"""
    def __init__(self, content: str, status: str = "pending"):
        self.content = content    # 任务内容
        self.status = status      # pending / in-progress / done

class TodoWrite:
    """任务列表管理器 —— 冰箱上的便利贴"""
    def __init__(self):
        self.todos: list[TodoItem] = []

    def add(self, content: str):
        """添加新任务"""
        self.todos.append(TodoItem(content))
        return f"✅ 已添加: {content}"

    def update(self, index: int, content: str):
        """更新任务内容"""
        self.todos[index].content = content
        return f"✏️ 已更新第 {index} 项"

    def complete(self, index: int):
        """标记任务完成"""
        self.todos[index].status = "done"
        return f"🎉 已完成: {self.todos[index].content}"

    def cancel(self, index: int):
        """取消任务"""
        self.todos[index].status = "cancelled"
        return f"🚫 已取消: {self.todos[index].content}"

    def list_todos(self):
        """列出所有任务"""
        return [f"[{t.status}] {t.content}" for t in self.todos]

    def clear(self):
        """清空所有任务"""
        self.todos.clear()
💡 核心思路:TodoWrite 是一个简单的列表管理器,提供增删改查操作。 它不关心任务之间的关系,只负责记录"要做什么"。
5

TodoManager 代码详解

增强版的任务管理,支持导出为 Markdown

Python
class TodoManager:
    """增强版任务管理器"""
    def __init__(self):
        self.tasks: list[dict] = []

    def add_task(self, content: str, priority: str = "MEDIUM"):
        """添加任务,支持优先级"""
        task = {
            "id": len(self.tasks),
            "content": content,
            "status": "pending",
            "priority": priority
        }
        self.tasks.append(task)
        return task

    def mark_complete(self, task_id: int):
        """标记任务完成"""
        self.tasks[task_id]["status"] = "done"

    def export_markdown(self) -> str:
        """导出为 Markdown 格式"""
        lines = ["# 📋 任务清单\n"]
        for t in self.tasks:
            check = "x" if t["status"] == "done" else " "
            lines.append(f"- [{check}] **{t['priority']}** {t['content']}")
        return "\n".join(lines)
💡 比 TodoWrite 多了什么:TodoManager 增加了优先级字段、任务 ID、 以及导出 Markdown 的能力。适合需要持久化或分享任务列表的场景。
6

TaskManager 代码详解

核心:任务依赖管理与智能调度

Python
from enum import Enum

class TaskState(Enum):
    PENDING = "pending"       # 已创建,等待依赖满足
    READY = "ready"           # 依赖已满足,可以执行
    RUNNING = "running"       # 正在执行
    COMPLETED = "completed"   # 执行成功
    FAILED = "failed"         # 执行失败
    BLOCKED = "blocked"       # 被依赖阻塞

class Priority(Enum):
    CRITICAL = 4
    HIGH = 3
    MEDIUM = 2
    LOW = 1

class TaskManager:
    def __init__(self):
        self.tasks: dict[int, dict] = {}
        self.next_id = 0

    def create_task(self, title: str, priority="MEDIUM",
                    blocked_by: list[int] = None):
        """创建任务,可指定依赖"""
        task_id = self.next_id
        self.next_id += 1
        # 如果有依赖,状态为 BLOCKED;否则为 READY
        state = TaskState.BLOCKED if blocked_by else TaskState.READY
        self.tasks[task_id] = {
            "id": task_id,
            "title": title,
            "priority": priority,
            "state": state,
            "blocked_by": set(blocked_by or []),
            "dependents": set()  # 谁依赖了我
        }
        # 注册依赖关系
        for dep_id in (blocked_by or []):
            self.tasks[dep_id]["dependents"].add(task_id)
        return task_id

    def complete_task(self, task_id: int):
        """完成任务,并解锁依赖它的任务"""
        self.tasks[task_id]["state"] = TaskState.COMPLETED
        # 遍历依赖此任务的其他任务
        for dep_id in self.tasks[task_id]["dependents"]:
            dep = self.tasks[dep_id]
            dep["blocked_by"].discard(task_id)
            # 如果所有依赖都完成了,状态变为 READY
            if not dep["blocked_by"]:
                dep["state"] = TaskState.READY

    def get_next_task(self) -> dict | None:
        """获取下一个应执行的任务(按优先级)"""
        ready = [t for t in self.tasks.values()
                 if t["state"] == TaskState.READY]
        if not ready:
            return None
        # 按优先级排序,返回最高的
        return max(ready, key=lambda t: Priority[t["priority"]].value)
💡 三个核心方法
① create_task:创建任务并声明依赖(blocked_by)
② complete_task:完成任务后自动解锁下游依赖
③ get_next_task:智能选择下一个应执行的任务(按优先级)
7

实战案例

看看规划系统如何解决真实问题

🔧 案例一:代码重构任务

  • 分析现有代码结构 (CRITICAL)
  • 识别需要重构的模块 (HIGH)
  • 编写单元测试 (HIGH)
  • 执行重构 (MEDIUM)
  • 运行回归测试 (MEDIUM)
  • 更新文档 (LOW)

🔗 案例二:任务依赖链

  • 安装依赖 → 无依赖 (READY)
  • 配置数据库 → blocked_by: 安装依赖
  • 迁移数据 → blocked_by: 配置数据库
  • 启动服务 → blocked_by: 迁移数据
  • 运行测试 → blocked_by: 启动服务

💻 代码示例:用 TaskManager 规划重构

Python
# 创建任务管理器
mgr = TaskManager()

# 第一步没有依赖
t0 = mgr.create_task("分析代码结构", "CRITICAL")

# 后续任务依赖前一个
t1 = mgr.create_task("编写单元测试", "HIGH", blocked_by=[t0])
t2 = mgr.create_task("执行重构", "HIGH", blocked_by=[t1])
t3 = mgr.create_task("回归测试", "MEDIUM", blocked_by=[t2])
t4 = mgr.create_task("更新文档", "LOW", blocked_by=[t2])

# 智能调度:每次获取下一个该执行的任务
while task := mgr.get_next_task():
    print(f"▶ 执行: {task['title']}")
    # ... 执行任务 ...
    mgr.complete_task(task["id"])
    # 完成后,下游任务自动解锁!
💡 执行顺序:分析代码 → 编写测试 → 执行重构 → 回归测试 + 更新文档(后两个可并行)。 get_next_task 会自动选择优先级最高的就绪任务。
8

知识测验

检验你的理解,5 道题等你挑战

9

深度探索

点击展开,深入了解规划系统的高级话题

🧩

任务分解策略

▼

好的任务分解是规划系统的基础。以下是几个关键原则:

📏 SMART 原则

  • Specific - 具体明确,不含糊
  • Measurable - 可衡量完成标准
  • Achievable - 单个 Agent 可独立完成
  • Relevant - 与整体目标相关
  • Time-bound - 有明确的完成条件

粒度控制:任务不宜太粗("开发整个系统")也不宜太细("写一行代码")。 理想粒度是每个任务可在 5-30 分钟内完成,有明确的输入和输出。

🎯

优先级算法

▼

简单的优先级排序可能不够。在复杂场景中,需要综合考虑多个因素:

📊 多维评分模型

# 综合优先级 = 权重加权
score = (
    priority_weight * 0.4     # 基础优先级
    + urgency_weight * 0.3     # 紧急程度
    + dependency_weight * 0.2  # 被依赖数量(越多人等它越重要)
    + effort_weight * 0.1     # 预估工作量(快的任务先做)
)

关键洞见:被很多任务依赖的节点(如数据库 Schema), 即使基础优先级不高,也应该优先执行,因为它会阻塞整个工作流。

🔄

与 Agent Loop 的集成

▼

规划系统不是孤立存在的,它与 Agent 的主循环紧密集成:

🔄 Agent Loop 中的规划

while True:
    # 1. 获取用户请求
    request = get_user_input()

    # 2. 📋 规划阶段:分解任务
    tasks = planner.decompose(request)
    for t in tasks:
        task_mgr.create_task(...)

    # 3. 🔁 执行循环
    while task := task_mgr.get_next_task():
        result = execute(task)
        task_mgr.complete_task(task.id)

    # 4. 📊 汇总结果
    report = summarize_results()

动态重规划:如果某个任务失败, Agent 可以重新评估计划,创建新的修复任务并插入到依赖图中。 这就是"Think → Act → Observe → Replan"的循环。

📖 本章总结

🧠

先想后做

规划系统让 Agent 在行动前先制定计划,避免盲目执行

📝

TodoWrite

简单任务清单管理器,支持增删改查六种操作

📊

TaskManager

高级任务引擎,支持依赖管理、优先级调度、状态流转

🔗

依赖管理

通过 blocked_by 声明依赖,完成任务自动解锁下游

🎯

优先级

CRITICAL > HIGH > MEDIUM > LOW,get_next_task 自动选最高

🔄

状态流转

Pending → Ready → Running → Completed/Failed/Blocked