tako 文档 GitHub

01 · 任务看板与单入口(2026-09-26)

性质:定案文档。本文是 doc/ 新系列的第一篇(旧 01–06 与《设计了解》已随本次定案删除, 随后按新方向重写为新系列 03–09,见篇末 §9 索引)。 定案两件事:

  1. 仓库从「分层学习对照」收敛为单入口产品形态:cmd/yktako 是唯一入口, 其余 cmd(l0raw / l0react / l0deep / l1guard / l2planexec)与 internal/planexec 删除;
  2. 任务管理按 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):

Status:pending → in_progress → completed,不再需要时用 deleted(TaskList 不列出)。

约束写在 tool description(不是状态机):

全局约定(什么时候该建表)进 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 源码核实):

同一 middleware 实例内用 mutex 把四个工具串行化(参照 eino plantask),防同轮并行 调用写坏账本。

4. Runtime 接线

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

要硬进度:收窄执行模型(一次只推进一条 / 子 Agent 交卷才算完 / 测试或 goal 作为验收标准), 不要在开放 ReAct 上做语义对齐。

7. 测试计划

8. 参考来源

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 移入), 不占本索引编号;它是冻结存档,行号锚点不随主库代码刷新。

写作约定: