tako 文档 GitHub

07 · 任务规划与看板

性质:能力记录 + 决策记录。新系列第七篇,改写自旧《05-L2-任务规划》:问题陈述与"从 deepagents/harness 读到的东西"保留(那是对照物的事实),但结论换了——旧稿的手写规划中间件(internal/planning)与 两个对照入口(cmd/l2planning、cmd/l2builtin)已随 2026-09-26 定案删除, 现在是 Plan / Tasks / Actions 三层分离 + 自研看板(定案见《01》,实现计划见《02》)。 为什么退掉那两条软约束线,见《08-Eino规划机制调研》。

1. 问题

多步任务下,agent 需要:先把任务拆成步骤、执行中能被看见进度、被打断后不丢施工状态。 "看见进度"和"记账准确"是两件事,混在一起就出问题:

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

两个值得停下来想的设计点:

  1. 为什么全量替换而不是增量操作(没有 add_todo / complete_todo):增量 API 需要 id 管理和冲突处理; 全量替换把"当前计划长什么样"的权威来源始终放在模型手里——模型每轮都能在上次回执里看到完整清单, 改起来一步到位。代价是并行调用会产生歧义,所以要有零件 4 的防守。
  2. 提示词是最大的代码量。官方版有效代码约 100 行,提示词约 200 行(带 8 组正反示例)。 什么时候列清单、什么时候别列,全靠提示词约束——这不是工程问题,是 prompt engineering。

2.3 半途而废提醒(我们外扩过的一格)

官方版有个能力空档:模型列了计划,但执行到一半就输出最终回答收工了(清单里还有 in_progress 项), 没有任何机制纠正它。当时在 middleware 里补过一格:模型想收工 + 清单里有 in_progress

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 单条

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 明确不解决什么

要硬进度:收窄执行模型(一次只推进一条 / 子 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。