01 · 任务看板与单入口(2026-09-26)
性质:定案文档。本文是 doc/ 新系列的第一篇(旧 01–06 与《设计了解》已随本次定案删除, 随后按新方向重写为新系列 03–09,见篇末 §9 索引)。 定案两件事:
- 仓库从「分层学习对照」收敛为单入口产品形态:
cmd/yktako是唯一入口, 其余 cmd(l0raw / l0react / l0deep / l1guard / l2planexec)与internal/planexec删除;- 任务管理按 Plan / Tasks / Actions 三层分离落地,Tasks 层自研记账工具 (
internal/taskboard),替代 DeepAgent 的整表write_todos。
0. 问题
产品要有 Planning,执行前/执行中要有 todos。Eino DeepAgent 把规划做成 ReAct 工具 write_todos,不保证每一轮工具跑完或中断时账本都是最新,也不保证 status 与具体 调用对齐。目标不是「推断这次调用对应哪条 todo」,而是把蓝图 / 看板 / 动作分开: 账本有稳定主键、更新可投影、落盘不依赖模型自觉。
1. 三层,不并成一层
| 层 | 是什么 | 谁写 | 主键 |
|---|---|---|---|
| Plan | 给人审的方案(背景、步骤、文件、风险) | 模型 + 用户改 | 文档结构 |
| Tasks | 执行期勾选看板 | 模型用记账 tool | taskId(自增数字) |
| Actions | Edit / Bash 等干活工具 |
模型按 ReAct 选 | tool_call id,与 task 无外键 |
关系定案为分离(对标 Claude 默认):Plan 是给人审的文档;开干后模型用 TaskCreate 建看板,文案不必逐行等于 plan。一条 Task 下许多 Action,taskId 只寻址看板行, 不是 plan 第 N 条,也也不是某次工具调用。
本轮 Plan 层不新增机制:没有人审 gate,没有 ExitPlanMode 式 interrupt,Plan 仅以 提示词约定的口述方案形态存在。Tasks 账本是本轮唯一新建机制。
2. 记账协议(替代整表 write_todos)
四个工具(utils.InferTool 生成,最终实现 tool.InvokableTool):
TaskCreate(subject, description?, activeForm?)→ 返回taskIdTaskUpdate(taskId, status?, subject?, description?, activeForm?)→ 按 id patchTaskList()→ 全部未删除任务TaskGet(taskId)→ 单条
Status:pending → in_progress → completed,不再需要时用 deleted(TaskList 不列出)。
约束写在 tool description(不是状态机):
- ≥3 步或用户列了多件事才建表;一步任务不建
- 动手前标
in_progress,同时尽量一条 - 做完立刻
completed,不要攒着勾 - 测试红 / 做了一半 / 未解报错 → 不准 completed
- 卡住就 Create 一条 blocker
全局约定(什么时候该建表)进 agent 的 Instruction。模型仍自评「做没做完」—— 协议解决的是改哪一行,不是客观验收。
每个工具输出 = 操作回执 + 当前看板紧凑视图 + 催更块(存在未完成项时提醒 「先更新状态再干活」「做完立刻标 completed」,参照 WeKnora todo_write 的 Important Reminder 注入)。
3. 存储:正本 + 镜像(「落盘不依赖模型自觉」的具体机制)
| 层 | 角色 | 生命周期 |
|---|---|---|
middleware 自持 *Store(mutex + map + 自增计数器) |
正本:四工具直接读写 | agent 建一次 → 跨 REPL 轮次存活 |
adk.AddSessionValue 写快照 |
镜像:每次变更后全量写入 | 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.Values 是map[string]any,具体类型不注册无法序列化)。- 但 session 每轮
runner.Run新建(ctxWithNewTypedRunCtx);能把父 session 带进 子 run 的 option(withSharedParentSession)未导出,外部用不了——所以跨轮 正本不能放 session,只能 middleware 自持。 - resume 后:同进程 middleware 正本不变,checkpoint 恢复的镜像与之一致。
- 进程重启全丢:
adkrun.Store本来就是内存实现(「进程退出即清空,足够演示 interrupt」), 磁盘持久化留作后续层级。
同一 middleware 实例内用 mutex 把四个工具串行化(参照 eino plantask),防同轮并行 调用写坏账本。
4. Runtime 接线
- 流式投影:
adkrun按账本工具名把回执分类成 board 事件,📋 看板投影由消费方 sink 打印(REPL sink 在cmd/yktako/sink.go;替换原formatTodoReceipt的 write_todos 投影,随 l0deep 一起退役)。 - Checkpoint:interrupt 时账本镜像随图状态落盘(§3 机制);Run 正常结束 eino 不写 checkpoint,跨轮靠 middleware 正本——如实记录,不假装有「Run 结束落盘」。
ExecuteSequentially: true:ChatModelAgentConfig内嵌compose.ToolsNodeConfig直接可用;同批工具调用串行,「同批里先 Update 再干活」降低打架。这是秩序偏好, 不是正确性保证。- 每轮新 checkpointID(沿用
turn-%d模式)。
5. 单入口结构
cmd/yktako(唯一入口)
└─ ChatModelAgent(裸 ReAct,MaxIterations 20)
├─ Instruction = config.SystemPrompt() + taskboard 记账约定
├─ Handlers = [taskboard middleware] + guard.Handlers(...)(L1 三件套)
├─ Tools = internal/tools 现有工具(Actions 层)
└─ Runner(CheckPointStore = adkrun.NewStore()) + REPL 审批回路
taskboard middleware 实现 adk.ChatModelAgentMiddleware,BeforeAgent 里往 runCtx.Tools 追加四个工具(eino plantask 同款机制)。
删除:cmd/{l0raw,l0react,l0deep,l1guard,l2planexec}、internal/planexec、 adkrun 的 write_todos 投影。 保留:internal/{adkrun,config,fsbackend,guard,repl,tools}。
6. 明确不解决什么
- Action ↔︎ Task 双射
- 模型漏 Update 时自动勾选正确的行
- 用 Graph 拓扑强制执行顺序
要硬进度:收窄执行模型(一次只推进一条 / 子 Agent 交卷才算完 / 测试或 goal 作为验收标准), 不要在开放 ReAct 上做语义对齐。
7. 测试计划
- taskboard 单测:CRUD、非法 id、deleted 不出现在 List、status 校验、session 镜像 写入、看板/催更输出、并行调用串行化;
- middleware
BeforeAgent注入测试;adkrun 投影测试; - 集成:假模型走真实图(turn_test 风格)——建表 → 干活 → 更新 → 完成全链路, 以及 interrupt 后从 checkpoint 字节里能 gob 解出账本快照。
8. 参考来源
- WeKnora(
ref-agent/WeKnora):todo_write无状态 echo 设计 + tool_result 尾部 催更注入 + 随消息 jsonb 落库。它的状态寄生在对话历史里;本设计改为 middleware 正本 + session 镜像,不依赖历史回放。 - eino plantask(
adk/middlewares/plantask):四工具名字/状态值/数字 id/mutex 串行化对齐它;但它的存储是文件 Backend(file-per-task + highwatermark)、带 Blocks/BlockedBy 依赖图,与本设计的 Session 镜像路线不同,故自研。 - Claude Tasks:记账协议原型(TaskCreate/TaskUpdate/TaskList/TaskGet、 pending→in_progress→completed/deleted、约束写在 tool description)。
9. doc/ 系列索引(2026-09-26 起)
| 篇 | 内容 |
|---|---|
| 01 任务看板与单入口 | 定案:单入口收敛、Plan/Tasks/Actions 三层分离、正本 + 镜像 |
| 02 任务看板实现计划 | Task 1–8 逐任务实现计划(含每步验收命令) |
| 03 立项与命名 | 背景、技术选型终版、命名、参考资产位置 |
| 04 技术路线 | T-Mem 取舍、LangGraph.js vs Eino、反转记、LangGraph→Eino 映射表 |
| 05 Octop 架构剖析与生长式复刻 | 壳/芯分层、组件清单、产品能力路线、翻译原则 |
| 06 工具安全层 | 命令/文件/PII 三件套、三态裁决、审批回路、溯源纠错与踩坑 |
| 07 任务规划与看板 | 三层分离与记账协议、与官方 write_todos 的对照、旧线退场 |
| 08 Eino 规划机制调研 | write_todos / PlanTask / Workflow + Plan-Execute 三套机制与定案依据 |
| 09 设计了解 | Eino 机制笔记:钩子时机、endpoint、session 落盘、adkrun.Run 的两个标识 |
| 10 最小 Web UI | 定案:方案 A 先行——事件 sink 重构 → HTTP + SSE 单页 → 回 #4;范围冻结与事件契约 |
| 11 最小 Web-UI 实施计划 | 方案 A 执行台账:T0–T3 状态、P1/P2、进度日志 |
注:maf 冻结线的对照篇在
maf/doc/10-MAF审批回路与Eino对照.md(2026-09-26 移入), 不占本索引编号;它是冻结存档,行号锚点不随主库代码刷新。
写作约定:
- 定案与决策篇记"为什么这么定"(01 的取舍、02 的逐任务计划、04 的反转记、08 的调研);
- 能力篇记"现在是什么 + 落点在哪 + 和参考实现的差距"(05、06、07);
- 机制篇记"框架怎么运作"(09),行号锚点跟当前代码刷新;
- 被删掉的实现不抹掉记录:注明退场原因与替代者(
cmd/l2planning、cmd/l2builtin、cmd/l2planexec与internal/{planning,planexec}都按这个规矩留在 07、08 里),避免同一个坑踩第二次。