07 · 任务规划与看板
性质:能力记录 + 决策记录。新系列第七篇,改写自旧《05-L2-任务规划》:问题陈述与"从 deepagents/harness 读到的东西"保留(那是对照物的事实),但结论换了——旧稿的手写规划中间件(
internal/planning)与 两个对照入口(cmd/l2planning、cmd/l2builtin)已随 2026-09-26 定案删除, 现在是 Plan / Tasks / Actions 三层分离 + 自研看板(定案见《01》,实现计划见《02》)。 为什么退掉那两条软约束线,见《08-Eino规划机制调研》。
1. 问题
多步任务下,agent 需要:先把任务拆成步骤、执行中能被看见进度、被打断后不丢施工状态。 "看见进度"和"记账准确"是两件事,混在一起就出问题:
- 让模型每轮把整张清单重写一遍(DeepAgent 的
write_todos),模型漏更新时账本就是旧的; - 想让"改哪一行"有据可依,就得给行一个稳定主键,而不是每次全量覆盖。
2. 从参考实现读到什么
2.1 harness 自己没有 todo 中间件
带着"任务规划参考 harness 哪个文件"的问题翻 harness_agent/middleware/,24 个中间件里没有 todo—— harness 直接用 deepagents 的。目录里的 tool_order.py 名字像规划,实际是另一件事:把 task 工具排到 工具列表末尾,让父子 agent 的公共工具前缀对齐,给 prompt cache 复用服务的。 提醒:按名字猜职责会踩空,得看实现。
2.2 官方 TodoListMiddleware 的四个零件
官方实现是 Python 的 TodoListMiddleware(langchain.agents.middleware,deepagents 直接引用); 我们精读过的是它的 JS 移植(agents/middleware/todoListMiddleware.js,约 100 行有效代码),四个零件与 Python 版一致:
| 零件 | 机制 | 作用 |
|---|---|---|
| 状态频道 | stateSchema: z.object({ todos: ...default([]) }) |
给 agent 状态图加 todos 频道 |
write_todos 工具 |
返回 Command({ update: { todos, messages } }) |
全量替换清单 + 回执 ToolMessage |
| 提示词注入 | wrapModelCall 里拼 systemMessage |
教模型什么时候该用、什么时候别用 |
| 并行防守 | afterModel 检查一轮内 write_todos 调用数 |
>1 次就全部换成错误 ToolMessage |
两个值得停下来想的设计点:
- 为什么全量替换而不是增量操作(没有 add_todo / complete_todo):增量 API 需要 id 管理和冲突处理; 全量替换把"当前计划长什么样"的权威来源始终放在模型手里——模型每轮都能在上次回执里看到完整清单, 改起来一步到位。代价是并行调用会产生歧义,所以要有零件 4 的防守。
- 提示词是最大的代码量。官方版有效代码约 100 行,提示词约 200 行(带 8 组正反示例)。 什么时候列清单、什么时候别列,全靠提示词约束——这不是工程问题,是 prompt engineering。
2.3 半途而废提醒(我们外扩过的一格)
官方版有个能力空档:模型列了计划,但执行到一半就输出最终回答收工了(清单里还有 in_progress 项), 没有任何机制纠正它。当时在 middleware 里补过一格:模型想收工 + 清单里有 in_progress
- 本轮写过清单 + 本轮还没提醒过 → 注入一条提醒并跳回模型节点。四条约束(只催 in_progress、 只催本轮刚写过的、每轮最多一次、只在无待执行 tool_calls 时跳转)在旧稿里有完整记录, 这套状态机已随
internal/planning删除;它的"提醒"意图被新设计继承成了工具输出尾部的催更块(见 §4)。
3. 两条旧线的退场(决策记录)
3.1 手写规划中间件(internal/planning + cmd/l2planning)
复刻了官方四个零件,提示词换成紧凑中文版(15 行 vs 官方 200 行)。实测结论值得留档: 在 deepseek-flash 这个量级上,紧凑中文提示词与官方 200 行版行为无差别——"什么时候列清单" 不需要 8 组示例;提示词长度与效果的拐点在哪,留给后续继续观察。
顺带留下一条 Eino 侧的实现差异备忘:ChatModelAgent 没有自定义 state 频道,清单只能放进程内; "半途而废提醒"因此不能靠"追加 HumanMessage + jumpTo"(那是 LangGraph 的路由玩法), 要让图走进工具节点再回到模型,只能补一次对模型隐藏的工具调用。
退场原因(2026-09-26 定案):单入口产品形态下不需要"同一能力两套实现"; 而这类软约束的定位本身尴尬——它只解决"提醒模型更新",不解决"账本对不对"(见《08》§0)。
3.2 官方 write_todos 对照(cmd/l2builtin)
deep.New 自带 write_todos,当时的用途是"官方软对照"。它随单入口收敛一起删除: 对照结论已经写进《08》,留一个演示入口没有意义。
3.3 硬编排线(cmd/l2planexec + internal/planexec)
同一批收敛里退场的还有 planexecute 硬编排(Sequential(Gate, Loop(Executor, Replanner)))。 它证明过"时序可以由图保证",但产品形态是一个能聊的助手,不是流程图应用: 强制 tool_choice 的结构化 Planner/Replanner 带来过度规划、阶段间无共享对话等代价(实测记录见《08》§6、§7), 而定案选择的是"看板记账 + 模型自主推进"。图能力留在工具箱里,等真需要确定性流程时再用。
4. 现在的答案:三层分离 + 看板
4.1 三层,不并成一层
| 层 | 是什么 | 谁写 | 主键 |
|---|---|---|---|
| Plan | 给人审的方案(背景、步骤、文件、风险) | 模型 + 用户改 | 文档结构 |
| Tasks | 执行期勾选看板 | 模型用记账工具 | taskId(自增数字) |
| Actions | bash / 读写文件等干活工具 |
模型按 ReAct 选 | tool_call id,与 task 无外键 |
关系是分离(对标 Claude 默认):Plan 是给人审的文档;开干后模型用 TaskCreate 建看板, 文案不必逐行等于 plan。一条 Task 下可以有任意多次 Action,taskId 只寻址看板行。
Plan 层本轮不新增机制:没有人审 gate、没有 ExitPlanMode 式 interrupt,Plan 仅以提示词约定的口述方案形态存在。 Tasks 账本是本轮唯一新建机制。
4.2 记账协议(四个工具)
| 工具 | 入参 | 返回 |
|---|---|---|
TaskCreate |
subject、description?、activeForm? |
新建行 + taskId |
TaskUpdate |
taskId、status?、subject?、description?、activeForm? |
按 id patch(空串字段不动) |
TaskList |
— | 全部未删除任务 |
TaskGet |
taskId |
单条 |
- 状态:
pending → in_progress → completed;不再需要时用deleted(TaskList不列出,快照里保留)。 - 约束写在 tool description(不是状态机):≥3 步或用户一次列了多件事才建表;动手前标
in_progress且同时尽量只留一条;做完立刻标completed;测试红 / 做了一半 / 未解报错不准标completed; 卡住就新建一条 blocker。 - 全局约定(什么时候该建表)进 agent 的
Instruction(taskboard.Instruction,由cmd/yktako拼在config.SystemPrompt()后面)。 - 每个工具的输出 = 操作回执 + 当前看板紧凑视图 + 催更块(存在未完成项时提醒"先更新状态再干活""做完立刻勾")。 催更块是把 §2.3 那个"半途而废提醒"从 middleware 钩子下移到工具回执尾部的做法, 灵感来自 WeKnora 的
todo_write(在 tool_result 尾部注入 Important Reminder)。
4.3 存储:正本 + 镜像
| 层 | 角色 | 生命周期 |
|---|---|---|
middleware 自持 *Store(mutex + map + 自增计数器) |
正本:四个工具直接读写 | agent 建一次 → 跨 REPL 轮次存活 |
adk.AddSessionValue(SessionKey, snapshot) |
镜像:每次变更后全量写入 | interrupt 时随 runContext gob 进 checkpoint |
机制依据(eino v0.9.21 源码核实):adk/runctx.go 的 runSession.Values 标注 CheckpointSchema: persisted via serialization.RunCtx (gob)——session 值在 interrupt 时随整个 runContext gob 序列化进 CheckPointStore,账本镜像随图状态一起落盘是免费得到的(快照类型必须 gob.Register)。 但 session 每轮 runner.Run 新建,能把父 session 带进子 run 的 option 未导出,所以跨轮正本不能放 session, 只能 middleware 自持。进程重启全丢——adkrun.Store 本来就是内存实现,磁盘持久化留给后面的层级。
同一 middleware 实例内用 mutex 把四个工具串行化(参照 eino plantask),防同轮并行调用写坏账本; 入口再开 ExecuteSequentially: true 让同批工具调用串行(秩序偏好,不是正确性保证)。
4.4 明确不解决什么
- Action ↔︎ Task 双射(不推断「这次调用对应哪条 todo」);
- 模型漏更新时自动勾选正确的行;
- 用图拓扑强制执行顺序。
要硬进度:收窄执行模型(一次只推进一条 / 子 Agent 交卷才算完 / 测试或 goal 作为验收标准), 不要在开放 ReAct 上做语义对齐。
5. 与官方 write_todos 的对照
| 维度 | DeepAgent write_todos |
本仓库 taskboard |
|---|---|---|
| 清单存放 | session(deep_agent_session_key_todos) |
middleware 自持 Store 正本 + session 镜像 |
| 更新粒度 | 整表替换 | 按 taskId patch |
| 主键 | 无(靠数组顺序/文案) | 自增数字 taskId |
| 同轮并发 | afterModel 并行防守:一轮 >1 次调用就全部换成错误回执 |
Store 全方法加锁 + ExecuteSequentially |
| 催更 | 无 | 工具回执尾部催更块 |
| 依赖图 | 无(eino PlanTask 有 blockedBy + 环检测) |
有意不做(只做看板,不做编排器) |
| 提示词位置 | 中间件注入 systemMessage | Instruction(全局约定)+ tool description(工具级约束) |
6. 实现状态与落点
| 部分 | 落点 | 状态 |
|---|---|---|
| Store 正本(Task/Patch/Status、自增 id、deleted 过滤、Snapshot) | internal/taskboard/taskboard.go |
✅ Task 1(6 个单测,-race 通过) |
| 四工具 + 回执/看板/催更输出 | internal/taskboard/tools.go |
✅ Task 2(7 个单测) |
middleware(BeforeAgent 注入)+ Instruction |
internal/taskboard/middleware.go |
✅ Task 3(2 个单测) |
流式投影(分类归 adkrun(IsBoardTool),打印归 REPL sink) |
internal/adkrun/event.go + cmd/yktako/sink.go |
✅ Task 4;T1 重构后落点 |
| 集成测试(假模型走真实图 + checkpoint 里能 gob 解出账本) | internal/taskboard/integration_test.go |
✅ Task 5(3 个集成测试,-race 通过) |
入口接线(Handlers = [taskboard] + guard,ExecuteSequentially) |
cmd/yktako/main.go |
✅ Task 6 |
Task 7(删除旧 L0–L2 五个入口与 internal/planexec)已执行:cmd/ 只剩 yktako, internal/ 保留 adkrun / config / fsbackend / guard / repl / taskboard / tools。
测试计划(定案 §7):CRUD、非法 id、deleted 不出现在 List、status 校验、session 镜像写入、 看板/催更输出、并行调用串行化、BeforeAgent 注入、投影格式、以及 interrupt 后能从 checkpoint 字节里 gob 解出账本快照。
7. 下一层
上下文管理(《05》§4 能力路线第 4 项):看板让任务变长,长任务的上下文膨胀问题随后就到—— 参考 harness 的 compaction / media_offload / context_usage。
更新(2026-09-26,见《10》):下一层改为最小 Web UI(事件 sink 重构 → HTTP + SSE 单页 → HITL 审批结构),本节原判断顺延一位、不作废——「任务变长 → 上下文膨胀」的 入场条件不依赖入口形态,UI 完成后回到本层。顺延的完整论证见《10》§2.2。