tako 文档 GitHub

第一版方案:持久 Task 与固定 DAG 编排

性质:方案真源;是 doc/70 的 V1 方案真源。 状态:✅ 已落地(2026-11-09 成文点头,2026-11-10 按 tmp/70-多Agent编排与Task/施工包.md 一次施工完成;端点请求/响应形状细节以施工包 §4、帧与事件契约以施工包 §10 为准,验收后随 build.md 留档)。commit 待用户定,代码当前在 yk-tako-eino/ 工作区。 验收:go test ./internal/runengine 全绿(含图校验、事件、产出归一、依赖失败传播钉子);活体五场 scripts/acceptance/agent_task_{single,busy,dag,crash,two_replicas}_live.sh——single 24/24、busy 14/14、dag 22/22、crash 20/20、two_replicas 13/13;浏览器走查:停止链(blocked/running 均可停、blocked 上游传播)、恢复链(中断行 → 继续执行 → 同 run epoch+1 续跑 → 已完成·已交结果)、交付一次审计(来源会话 17 组各恰一条 orchestration_finished)。 日期:2026-11-09。 代码落点:yk-tako-eino/internal/runengine/agent_task_{api,delivery,graph,runner,scheduler,store,tools,types}.go、auth.go(117xxx 码)、events.go(两类事件)、cmd/yktako/main.go(-task-interval 调度循环)、web/src/TasksView.vue;活体在 scripts/acceptance/agent_task_*.sh。 取代:两篇方案初稿《持久 Task 方案》与《多 Agent 编排方案》;调研篇仍保留参考证据价值。 版本边界:这里的 V1 只指本方案第一期,不是运行引擎代际或对外服务版本。

1. 背景:当前委派在哪里断开

tako 当前的子代理委派是一场同步工具调用:mAgent 调 researcher/coder,父 run 等子代理完成后才继续。子代理内部可以执行完整的模型—工具循环,也有独立上下文、工具权限和执行档案,但“这件工作本身”没有独立的业务身份、状态、结果和通知。

一个具体失败场景是:

用户要调研 A、B 并汇总
  → mAgent 派 A、B
  → B 中途崩溃
  → 父 Agent 只看到一次委派失败
  → A 的已有结果、B 的恢复边界、C 应读取什么,没有同一组持久事实
  → 后续可能重做 A,也可能在 B 缺失时直接汇总

现有 run_tasks 看板只表达“一场 run 计划做什么”,不会因此获得独立 worker、执行 run 或通知能力,不能承担这里的 Task。

V1 因此分两步建立一条完整链路:

  1. 持久 Task:让一件工作脱离一次同步工具调用,独立执行、恢复并留下结果;
  2. 固定 DAG 编排:让一组 Task 按创建时声明的依赖推进,并由明确的协调职责处理失败和最终交付。

没有第 1 步,第 2 步只是另一张不会执行的看板;没有第 2 步,多件工作之间仍然只能靠父 Agent 等待和记忆衔接。

2. V1 目标场景与完成线

V1 只承诺下面这一条多 Agent 完整链路:

用户提出“调研 A、B 并生成综合报告”
  → mAgent 将目标交给协调职责
  → 协调 Agent 规划 A、B、C 及依赖边
  → 服务端一次创建编排组、三件 Task 和两条边
  → 调度程序并行启动 A、B;C 因依赖未满足保持 pending
  → A、B 各自执行完整 ReAct run,并提交结构化结果与文件路径
  → A、B 都成功后,程序才允许 C 进入 ready
  → 调度程序启动 C,程序把 A、B 的结果引用装入 C 的输入
  → C 提交最终汇总产物
  → 协调 Agent 检查结果与整组状态
  → 最终结果进入来源会话
  → mAgent 向用户交付

writer 在这个场景里是汇总工作的执行者角色示例,不代表当前已经有出厂 writer 规格;实际执行者必须来自当时租户可用的 Agent 规格。

完成线不是页面出现几个角色名,而是:

3. 角色与对象必须分开

3.1 mAgent

接待用户、理解原始目标、处理需要用户回答的问题,并最终向用户交付。mAgent 是当前根助手,不是调度程序。

3.2 协调 Agent

围绕一个编排组承担协调职责:规划 Task、选择执行者、接收关键结果与失败、判断原目标能否完成、组织最终结果。

“协调 Agent”是职责名称。它可以由 mAgent 兼任,也可以是独立 Agent 实例;拓扑仍需点头。无论选择哪种,都不能把协调职责归给来源会话。

独立协调者不等于永久运行的进程。它仍采用事件驱动:创建计划、收到关键失败、收到最终结果时,在持久协调上下文中启动一次新的执行 run。

3.3 来源会话

来源会话是用户与 mAgent 的持续对话,也是最终通知和用户交付的归属。它不是 Agent,不会判断失败、修改计划或推进依赖。

3.4 调度程序

调度程序是普通程序组件,不是 Agent。它读取数据库中的 Task 与依赖,判断谁可以执行,原子取得执行权,启动或恢复执行 run,并传播确定性的失败状态。

模型不能直接把 Task 写成 running/ready,也不能绕过依赖检查启动后继。

3.5 Task、DAG node 与执行 run

一个 Task 是 DAG 的一个节点,也是一件持久工作。它保存自包含指令、执行者规格、当前状态、执行 run 指针和最终结果。

一个 Task 节点通常对应一场完整的 ReAct 执行 run:

Task A:调研 A 市场
  → 模型决定下一步
  → web_search
  → 模型读取结果并决定下一步
  → web_fetch
  → write_file
  → 提交 Task 结果

所以:

这里存在两层工具,但它们不相混:

  1. 协调 Agent 调“创建 Task/编排组”的工具,产生持久工作或 DAG 节点;
  2. 执行 Agent 在节点内部调用搜索、读写文件等工具,完成该节点的工作。

3.6 编排组与 DAG

一个编排组对应一个用户目标,也对应一张 DAG。DAG 是有向无环图:Task 是节点,依赖边表示“父 Task 成功后,子 Task 才具备执行资格”。

不是每个 Task 各有一张 DAG。一个 Task 只有在未来明确支持嵌套编排时,才可能再关联一个子编排组;嵌套不是 V1 前提。

4. V1 的图在创建前规划,运行中不改写节点

V1 采用“先规划、整组创建、按依赖执行”的形态。

Task 创建后,下列字段不可被模型临时改写:

运行中可以改变的是执行状态、当前 run、结果与错误。取消一个节点不等于改写它的工作内容。

“动态创建节点”和“修改已有节点”也是两件事:创建接口可以供协调 Agent 在规划阶段使用,不代表执行阶段可以随手改图。

V1 不承诺动态改计划。确实需要替换工作内容时,保留原 Task 的事实,通过新编排组或后续明确设计的计划修订机制处理,不把更新伪装成创建重试。

V1 状态词表不加入 skipped。节点因依赖失败而不执行使用 blocked,被明确停止使用 cancelled;不为了未来分支提前扩状态。

5. 契约草案:先让调用形状可讨论

以下请求形状只用于方案评审,不是已验收 API 字节。施工包点头后,开发必须先用运行中的端点和 curl 钉死真实契约,再完成后续存储与执行;不能直接把本节示例抄成测试期望。

所有新增 JSON API 使用现行 code → message → data 信封;HTTP 状态仍按 400/401/403/404/409/429/500 分类。SSE 帧面与媒体二进制成功体不进信封。

5.1 第一件工作:POST /api/tasks

{
  "idempotencyKey": "task-demo-001",
  "workspaceId": "ws_…",
  "content": "只回复 task-ready",
  "agent": "researcher",
  "modelRef": "可选;缺省继承执行者配置"
}

这个端点服务两个调用方:用户通过产品 API 创建一件工作,mAgent 通过等价模型工具委派一件工作。它立即返回 Task 身份、状态和 execution run 引用,不把长执行塞在创建请求里。

配套最小读写在 V1 中包括:

5.2 整张初始 DAG:POST /api/orchestrations

{
  "idempotencyKey": "report-20261109-001",
  "workspaceId": "ws_…",
  "goal": "调研 A、B 并生成综合报告",
  "tasks": [
    {"key": "A", "content": "调研 A,写入 a.md", "agent": "researcher"},
    {"key": "B", "content": "调研 B,写入 b.md", "agent": "researcher"},
    {"key": "C", "content": "综合 A、B,写入 final.md", "agent": "writer"}
  ],
  "links": [
    {"parent": "A", "child": "C"},
    {"parent": "B", "child": "C"}
  ]
}

V1 的多 Agent 验收场景只有一个汇聚终点 C。多个最终节点怎样选择交付物不在本期扩展。

配套最小读取包括编排组详情、组内 Task 与依赖关系;整组取消复用各 Task 的停止语义,具体端点形状在对应契约拍确定。

5.3 模型工具边界

建议新增三类模型工具,名称在契约拍复核:

前两类只给承担协调职责的 Agent;第三类只给当前 Task 的执行 Agent。模型工具返回可供模型修正的业务结果,不向模型暴露 HTTP 栈或 SQL。

6. 创建幂等发生在哪一步

创建幂等只发生在 Task/DAG 写入数据库的入口,不发生在节点内部执行过程中,也不是 LLM 并发修改节点。

V1 推荐整张初始 DAG 一次提交。服务端在同一事务内:

  1. 校验租户、项目、执行者规格和模型权限;
  2. 校验局部 Task key、依赖边、自依赖与环;
  3. 写入编排组、Task 和依赖边;
  4. 提交后才让调度程序看到可执行节点。

若先写编排组再逐件补 Task,进程可能死在中间,留下半张图。因此初始 A/B/C 不采用多次独立请求慢慢拼出来。

6.1 plan_hash 的作用

服务端根据完整、规范化的创建计划计算 plan_hash,包括目标、项目、Task 内容、执行者、模型与依赖边。idempotencyKey 标识一次逻辑创建请求,plan_hash 验证重试内容是否一致。

收到创建请求
  → 在调用方作用域内检查 idempotencyKey
  → 不存在:原子创建整组
  → 已存在且 plan_hash 相同:返回原编排组
  → 已存在但 plan_hash 不同:返回冲突

场景是“创建已经成功,但回执丢失,调用方再次发送同一请求”。相同请求不能产生第二套 A/B/C。

这不是 CAS:CAS 是确认旧值未变后更新;这里是利用唯一约束与事务防止重复创建。它也不提供更新已有节点的能力。

单件 Task 创建使用同样的幂等思路,此时比较的是单件工作的完整创建命令。初始 DAG 的整组幂等放在编排组记录上,不要求每个节点重复承担整组 plan_hash。

7. 状态、结果与裁决

7.1 Task 状态

pending(仍有依赖未满足)
  → ready(依赖满足,等待执行容量)
  → running(已经取得执行权)
  → succeeded / failed / cancelled

pending / ready → blocked(父任务失败或取消)
running+执行租约过期 → interrupted(读侧派生)→ 显式 resume → running

独立 Task 或没有 parents 的组内 Task 创建后可直接成为 ready。blocked 必须带机器原因,例如 dependency_failed,不能只存一段模型解释。

interrupted 表示“数据库仍认为它 running,但执行租约已经过期”,不是成功,也不是可随意重试的普通失败。

7.2 显式提交结果

执行 run 正常结束不自动等于 Task 成功。Agent 可能只回复“没找到资料”,也可能没有生成约定产物。

建议执行 Agent 显式提交:

{
  "summary": "调研结论",
  "artifacts": [{"path": "a.md", "kind": "report"}],
  "metadata": {}
}

程序收到后校验结果形状、项目归属和产物路径,再写 Task 结果并推进依赖。没有提交有效结果的 run,应留下明确失败原因,不能推动 C。

这里分三层裁决:

  1. 程序判断执行 run 是否正常结束;
  2. 程序判断 Task 是否提交了符合交接契约的结果;
  3. 协调 Agent 判断这些结果能否完成原始用户目标。

第二层只证明“下游拿到了符合契约的交接物”,不证明内容正确。需要语义审查时增加 reviewer Task 或独立场景 Eval,不用多个 Agent 投票代替验证。

V1 不直接照搬“每个 Worker 结果都等 Router 裁决”,否则 A、B 每次完成都必须唤醒协调者,自动依赖推进会退化成逐节点模型审批。需要审查的节点应显式建审查 Task。

8. 最小持久事实

8.1 编排组 agent_orchestrations

V1 需要编排组自身的持久记录,而不是只把同一个 orchestration_id 复制到每个 Task。

至少保存:

它回答“这组工作为谁服务、由谁协调、最终该交付到哪里、是否已经交付”。

8.2 Task agent_tasks

建议字段:

id
tenant_id
workspace_id
orchestration_id        -- 组内 Task 必填;独立 Task 的归属形状待契约复核
content
agent_name
model_ref
status
current_run_id
result                  -- JSON:summary、artifacts、metadata
error                   -- 机器原因与可读说明
result_revision
idempotency_key         -- 仅承担该 Task 创建入口的防重
command_hash            -- 仅比较该 Task 的创建命令,不是运行期编辑
created_at / started_at / finished_at / updated_at

current_run_id 指向当前执行 run;完整模型历史、工具调用和事件仍由现有 run 账本保存,不复制进 Task。

Task 执行 run 需要独立的内部 session/会话归属,避免多个 Task 被现有“同一聊天 session 同时只允许一个活 run”的限制串行化。具体复用形状是第一项契约决策,不能靠关闭现有限流实现。

tenant_id
orchestration_id
parent_task_id
child_task_id
created_at

约束至少包括:

A/B/C 场景中,agent_tasks 有三行,agent_task_links 有 (A,C) 与 (B,C) 两行。

数据库保存结构化节点和边,不保存自然语言 DAG、不保存 todos 作为调度依据,也不保存一份 Eino Graph 序列化结果作为第二份真相。

8.4 持久通知

Task 终态、协调者唤醒和来源会话交付不能依赖进程内消息。通知至少需要:

Task 完成与对应通知写入必须处于同一笔 PG 事务,或具备可对账的等价事务链。Redis/asynq 可以负责叫醒,但丢了不能丢事实;重启后从 PostgreSQL 对账。

9. 调度与 Eino 的边界

Eino 已有 Graph、DAG、并行 workflow、interrupt/resume 和 checkpoint,可以表达并执行节点间的数据流。当前 tako 也已经使用 Eino Agent 执行模型与工具循环。

但本方案最外层需要的不是一张只负责执行的图,而是一组可独立管理的业务工作:它们有租户、项目、权限、页面查询、独立恢复、跨副本领取、通知和最终交付。Eino checkpoint 可以保存图执行状态,但不直接提供这些产品事实。

因此采用两层分工:

外层:PostgreSQL 中的编排组、Task、依赖边
      → 防环、ready 计算、原子领取、失败传播、通知、交付

内层:每个 Task 的现有 Eino Agent run
      → ReAct、模型调用、工具调用、折叠、用量、trace

调度事务内重新检查状态、依赖与容量,再绑定执行 run;数据库行锁或等价原语防止两个副本领取同一 Task。长模型调用不在领取事务内执行,领取只确定执行权。

这不是开发另一个通用 DAG 执行引擎。外层只实现明确规则:防环、依赖满足计算、事务内领取和状态转换。

V1 不让 Eino checkpoint 成为另一套恢复真源,避免与现有 run 租约、执行代次和 journal 同时裁决同一执行状态。未来若某个节点内部需要固定的 Eino 子图,可以单独使用,不改变外层 Task 契约。

10. 通知:进度、失败与最终交付走不同路径

事件 程序动作 协调 Agent mAgent/来源会话
搜索、读写文件等普通进度 写执行 run 账本与事件,Task 详情可查 不唤醒 不唤醒
A 成功,B 未完成 保存 A 结果,C 继续 pending 不唤醒 不唤醒
A、B 都成功 C 进入 ready,等待执行容量 不必逐件介入 不唤醒
B 确定失败 B failed,未开始的后代 blocked 唤醒并给出失败事实 仅需要用户决策或无法继续时通知
B 执行中断 派生 interrupted,不允许 C 提前 通知恢复决策,不自动重跑未知副作用 按恢复权限与产品策略通知
C 提交最终结果 保存结果与版本 唤醒协调者检查原目标 协调者确认后进入最终交付
最终交付完成 持久记录已交付 不再重复唤醒 用户看到一次最终结果

如果 mAgent 兼任协调者,物理通知可以合并到同一会话,但逻辑规则不变:普通进度不进入模型上下文,关键失败和最终结果才触发新的 run。

来源会话正忙时,通知保持持久,等能够启动交付 run 时再消费。不能因为一次叫醒失败就永远忘记交付,也不能重复创建多个交付 run。

11. 失败、取消与恢复

11.1 确定失败

B failed 时,程序立即把尚未执行的 C 标为 blocked,并记录 dependency_failed。独立分支是否继续按整组策略执行;协调者收到关键失败,判断是否需要用户介入。

V1 不自动替换节点、不改写 B 的 content、不把 B 当成功输入。协调者可以解释失败、取消整组,或在用户同意后另建新计划;它不能在原图里偷偷换一份工作继续跑。

11.2 执行中断

worker 死亡后,执行租约过期,Task 显示 interrupted。C 仍不能启动。显式 resume 取得新的执行代次后再恢复;旧 worker 醒来后不能覆盖新结果。

外部工具结果未知时不自动重放。本方案承诺状态可判定、依赖不提前和旧执行者不能乱写,不承诺跨第三方系统的 exactly-once。

11.3 取消整组

pending/ready/blocked 直接取消;running 通过现有 stop 链路停止;已经发生的外部副作用不自动撤销。取消不改变原 Task 的工作指令和历史结果。

12. 并发、权限与结果交接

默认不复制完整历史,是因为两个调研 Agent 各读一百页材料后,如果汇总 Agent 开局就继承全部记录,会在开始汇总前先超上下文。需要细节时,它沿产物路径读取真实文件。

13. V1 非目标与下一版边界

V1 不做:

下一版可以讨论 Goal 驱动的动态编排:用户给出目标,协调 Agent 根据真实 Task 结果提交新的计划修订,程序校验后调度新增工作。这里的自由是“可以调整接下来做什么”,不是模型直接改执行状态,也不是无限群聊。

下一版讨论可以现在开始,但不改变 V1 的固定 DAG 完成线,也不在 V1 存储中提前实现未经场景验证的计划修订协议。

14. 验收场景

14.1 单件 Task

  1. 创建一件 Task 后立即得到持久身份与执行 run 引用;
  2. 同幂等键、同命令重试返回原 Task,不增加执行 run;
  3. 同幂等键、不同命令返回冲突,不覆盖旧工作;
  4. Task 最终提交真实结果,来源会话只消费一次完成通知;
  5. 停止后状态明确,不宣称已回滚工具副作用;
  6. 另一租户不能通过同一 Task ID 读取它。

14.2 创建与图校验

  1. 一次创建 A/B/C 后,三件 Task 与两条边同时可见;
  2. 同幂等键、同计划重试,返回原编排组,不增加 Task 或执行 run;
  3. 同幂等键、不同计划返回冲突,不修改旧节点;
  4. 创建过程中断不能留下可被调度的一半 DAG;
  5. 循环依赖、自依赖、未知父节点、跨租户父节点均被拒绝。

14.3 确定性调度

  1. 初始只有 A、B 可领取;
  2. 只有 A 成功时 C 仍 pending;
  3. A、B 都成功后 C 才 ready;
  4. 两个调度副本同时领取,只产生一个执行权与一个当前 run;
  5. B failed 时 C blocked,协调者收到关键失败;
  6. 重放同一结果或通知,不重复启动 C,也不重复交付。

14.4 活体执行

  1. A 或 B 的一场 run 内实际发生多次工具调用,但仍只对应一个 DAG 节点;
  2. C 的输入包含 A、B 的结果版本与文件路径;
  3. 最终文件同时包含 A、B 的预定证据;
  4. 中途终止自己启动的隔离执行实例,恢复前 C 不启动,显式恢复后只产生一个 C;
  5. 最终结果落库后来源会话暂时不能启动交付 run,恢复后仍能交付一次;
  6. 模型未按预期规划时登记为模型行为问题,不用假数据冒充调度验收通过。

契约字节一旦实施,同步进入 scripts/acceptance/expected.json、doc/19-v6/19v6-04-验收-curl.md 与 contract_test.go;任务效果由场景化 Eval 判定,不能与接口验收混为一谈。

15. 落地 pipeline:施工包、一次开发与终审

15.1 方案与施工包分工

本文件负责长期回答“V1 做什么、不做什么、怎样算完成”。主 Agent 另在 tmp/70-多Agent编排与Task/施工包.md 写实施细化:现有代码接缝、固定契约、数据模型、权限、恢复、测试与禁止事项。 施工包交用户点头前不开始 coding。

15.2 大任务一次开发

用户确认施工包后,开发模型一次完成 V1 的完整后端、前端、测试与文档,不按 A1/A2 让用户逐拍验收。 内部仍遵循“契约 → 数据需求 → 存储 → 实现 → 验收”,但这些是开发内部顺序,不是用户的审批点。

完整链路是:

主 Agent 写施工包
→ 用户确认一次
→ 开发模型连续完成整个 V1
→ Go/前端/契约/活体/浏览器机器验收
→ 主 Agent 审查实际 diff 并重跑关键场景
→ 不合格则按证据返工,合格后交付用户

开发模型不能自行改方案、删测试或缩小完成线。主 Agent 终审必须看真实 diff 与运行证据,不能只接受开发模型的完成总结。

15.3 交付检查

交付前运行 Go 测试、vet、build 与前端 typecheck/build;改了契约字节就更新机器期望并跑活体验收, 改了存储、游标或可见性再跑 spotcheck。V1 的并发、崩溃、权限、单次交付和浏览器场景都要有实际结果。 前端消费真实 API,不用假数据反向决定后端契约。

16. 仍需点头的决策与推荐值

决策 V1 推荐
mAgent 兼任还是独立协调 Agent V1 优先 mAgent 兼任,减少一层持久协调上下文;逻辑角色仍分开
初始 DAG 是否整组原子创建 是,使用编排组级 idempotencyKey + plan_hash 防重
节点内容、执行者与依赖是否不可改 是,动态计划修订后置
结果如何裁决 执行 Agent 显式提交,程序校验交接契约,协调者判断原目标
何时唤醒协调者 普通进度不唤醒;关键失败、执行中断与最终结果唤醒
中断是否自动重试 否,V1 坚持显式 resume
独立 Task 与编排组的归属形状 施工包采用单节点编排组,统一来源会话、幂等与交付;不让一个字段混指会话与 Agent
是否加入 skipped 不加入,V1 只使用 cancelled 与 blocked 覆盖对应事实

这些决策随施工包一起交审;用户确认施工包后,开发模型才一次完成整个 V1。

17. 参照分工

18. 所以这解决什么

V1 把“多个 Agent 都出现过”变成“一组工作有持久身份、有明确依赖、能独立恢复,并且最终结果只交付一次”。

它先固定 mAgent、协调职责、来源会话与调度程序的边界,再固定 Task、执行 run 与 wire 档案的边界。这样下一版讨论 Goal 驱动的动态编排时,改的是“计划怎样产生和修订”,不需要重新发明执行、权限、恢复和交付底座。