tako 文档 GitHub

73 · 协调通知与交付恢复

性质:已落地。本稿解决持久 Task 结果已经保存后,协调/交付 run 崩溃、error、停止或收尾未完成时怎样恢复。 状态:✅ 已落地;2026-11-11 讨论后成文,同日施工并活体验收。 日期:2026-11-11。 代码落点:internal/runengine/agent_task_{delivery,recovery,scheduler,store,runner,types,api}.go + agent_task_attention.go、auth.go(117003/117109/117110)、pgstore.go 与 store.go(expireDeadSessionRunsTx)、worker.go/agent_task_scheduler.go(RunEnd 与调度对账)、cmd/yktako/main.go;前端 web/src/{App.vue,TasksView.vue,NotificationRecovery.vue,api.ts}。验收:scripts/acceptance/agent_task_delivery_recovery_live.sh(10 场 109 条)、expected.json 用例 55–56、19v6-04 §55–56、go test ./internal/runengine。 前置真源:doc/70(协调通知与交付)、doc/30(journal、租约、epoch 与显式 resume)、doc/72(“需要我处理”入口;待点头)。 边界:本稿不改 DAG 执行语义,不增加运行引擎代际或对外服务版本号。

1. 背景:结果保存成功,不代表通知已经消费完成

当前整组结果的交付链是:

最终 Task 成功并保存结果
→ agent_orchestrations 写 delivery_status=pending
→ agent_notifications 写 orchestration_finished(pending)
→ 两条路二选一(doc/82 扩展):
  a) 调度器认领通知,在来源 session 创建交付 run
  b) 来源 run 正在场(wait_task / bash_output 读到终态)→ 就地认领
     (claimed_in_place=true,不建 runs 行、不写 attempt 行)
→ 通知变 claimed,交付 run 读取结果并向用户生成 assistant 回复
→ run complete 后的对账写口把通知变为 consumed,组变为 delivered

doc/82 施工批(2026-11-15)扩展口径:通知面新增 bash_job_finished(后台命令终态,没有编排组,background_job_id 指向命令行;认领时租户/项目/来源会话从 job 读,组交付判定整段跳过);新增就地认领 ClaimNotificationInline(同一场 run 可先后就地认领 job 与 Task 两条通知,交付对账按 claim_run_id 多行扫描);单组收口抽成 advanceOrchestration,调度循环与 wait_task(「先收口、再认领」)调同一份。

所以“完成”不是结果落库,也不是交付 run 启动,而是来源 session 的交付 run 完整处理这份回执,并由收尾写口确认通知消费完成。

一个具体失败场景:

C 已把报告写入 reports/final.md,最终结果已保存
→ 来源 session 的交付 run 启动后进程死亡或模型调用 error
→ 用户既没有看到最终交付,也不知道报告在哪里
→ 通知停在 claimed,组停在 delivering/failed
→ 如果只靠“让 LLM 告知错误”,而模型根本没有成功输出,用户会永远等下去

本方案要把“通知是否收到、是否正在处理、是否处理完、失败后结果在哪里、谁能恢复”全部变成可查询、可操作的持久事实。

2. 先分清执行失败与交付失败

这两种 error 不能共用“重跑 DAG”的处理:

执行失败:
A 与 B 并行,A error
→ A failed,C 不得执行,未开始后代 blocked
→ 写 task_failed 协调通知,由 mAgent 说明并决定后续

交付失败:
A、B、C 都已成功,最终结果已保存
→ 来源 session 的交付 run error
→ 不改任何 Task 状态,不阻断或重跑 DAG
→ 只恢复通知消费与用户交付

交付失败时,最终结果仍然存在。恢复的目标是读取同一份结果并完成通知消费,不是重新生产结果。

3. 范围与非目标

3.1 本期完成线

3.2 不做

4. 持久对象与各自回答的问题

对象 已有/新增 回答什么
agent_notifications 已有,补失败与当前认领信息 哪件事要交给哪个来源 session、当前由哪场 run 处理、是否消费完成
runs 已有 当前 run 是 running/complete/error/stopped,租约与 epoch 属于谁
run_journal 已有 崩溃前模型见过什么、哪些工具调用已有结果
run_tasks 已有 这场 run 的看板与未完成步骤;可恢复查看,但不作为执行权证明
agent_tasks.result 已有 最终摘要、产物路径与 resultRevision
agent_notification_attempts 新增 同一通知先后由哪些 run 处理,保留每次人工恢复的历史

几个容易混用的字段必须分开:

不能用结果版本卡住旧 worker,也不能只凭 run ID 判断“还是同一代”。

5. 状态机与完成标志

5.1 通知状态

pending
  → 认领并创建协调 run → claimed
  → 来源 run 就地认领(claimed_in_place=true,不建 run)→ claimed
  → run complete + 对账成功 → consumed

claimed
  → run 崩溃且租约过期 → 保持 claimed,run 读侧 interrupted,显式 resume
  → run error / stopped → failed + consume_error_code
  → 人工点击“重新处理” → 新 run + claimed

failed
  → 人工重新处理 → claimed
  → 不自动重试

就地认领行(claimed_in_place=true)不算协调身份:CoordinationClaimForRun 与启动回填都以 agent_notification_attempts 行为准,就地认领不写 attempt 行——否则普通聊天 run 会在 resume 时被误裁成只读工具面(doc/82 §4-12)。

装配失败且尚未真正启动 worker 时,沿用现有“退回 pending + 节流”的路径:此时尚无模型输出和工具副作用,可以由调度器稍后重试。它与模型已经执行后的 error 不同。

5.2 整组交付状态

整组完成通知额外维护 agent_orchestrations.delivery_status:

pending → delivering → delivered
                  ↘ failed → delivering → delivered

failed 必须带机器原因,例如 delivery_run_error / delivery_stopped / artifact_invalid;它不是最终 Task 的失败。

完成标志的精确定义:

  1. 当前 claim_run_id 指向的 run 已 complete;
  2. 当前通知从 claimed 变 consumed;
  3. 对 orchestration_finished,同一事务把当前组从 delivering 变 delivered,并写 delivered_at;
  4. 更新条件同时匹配当前 claim_run_id 与 delivery_run_id,旧尝试完成也不能收口新尝试。

RunEnd 钩子与调度循环都调用同一个 ReconcileDeliveryRun。如果进程在“run 已 complete”与“通知仍 claimed”之间死亡,调度器只补收尾,不创建另一场交付 run。

6. 启动前与启动窗口:表能判断,协程只负责对账

6.1 尚未认领

通知为 pending、没有 claim_run_id:调度器按现有事务认领并创建 run。多个副本同时检查时,行锁、状态条件和会话唯一约束只允许一个胜者。

6.2 已认领但 worker 尚未启动

通知为 claimed、run 行已创建,但进程在启动 goroutine 前死亡:

所以“有一个协程去 check”是必要的,但它不能看到 claimed 就重复启动。它只在 PG 事实表明可收尾或可显式接管时行动。

7. 执行中崩溃:恢复原 run,不制造第二份交付

崩溃恢复完全复用 doc/30:

交付 run down
→ 租约过期,run 读侧 interrupted
→ 用户从会话或“需要我处理”点击继续
→ POST /api/runs/:id/resume
→ PG 中 lease_epoch+1,旧 worker 失去写入资格
→ replayJournal 重建模型输入;缺结果的工具调用不自动重跑
→ 同一 run 继续读取结果并组织交付
→ RunEnd → ReconcileDeliveryRun → consumed / delivered

恢复时需要读到的持久原料包括:journal、模型消息与 runlog、待答问题、run todos、通知身份、最终 Task 的结果与产物引用。run todos 用来恢复工作清单,不能替代 journal,也不能证明某次工具副作用已完成。

旧进程即使在接管后醒来,也会因 run 终态、epoch 失配或当前通知 claim 已转移而无法写入。新执行者持有的仍是会过期的租约,停止、终态和接管都必须释放或转移它。

8. 明确 error/stopped:人工触发的新交付尝试

8.1 为什么不能一律 resume 或自动重试

现有普通 resume 只接受“running 且租约过期”的 interrupted run;error/stopped 已是终态。更重要的是,失败前可能已经有部分 assistant 输出或工具调用。把它们直接重新执行会重复发言或重复外部动作。

因此本期采用:

8.2 人工恢复端点

建议新增统一入口,覆盖最终交付与其他协调通知:

POST /api/notifications/:id/retry

成功响应的讨论形状:

{
  "notificationId": "an_…",
  "runId": "r_…",
  "status": "claimed",
  "attempt": 2
}

该形状不是已验收字节。服务端在同一笔 PG 事务中:

  1. 按租户、来源 session 属主和写权限校验;
  2. 锁通知行,要求当前状态为 failed,且最新 run 已是 error/stopped;
  3. 检查来源 session 当前无其他活 run;忙则保持 failed,返回既有会话忙冲突;
  4. 读取当前编排目标、通知类型、结果定位与上次失败原因;
  5. 创建新 run 和 agent_notification_attempts 行,attempt 取上一值+1;
  6. 把通知从 failed 条件更新为 claimed,并改写当前 claim_run_id;
  7. 整组完成通知同时把组的 delivery_status 从 failed 改为 delivering,并更新 delivery_run_id;
  8. 提交后才启动 worker,并发布既有编排变更事件与 doc/72 的调度唤醒。

重复点击或双副本同时点击时,第一次已将通知翻为 claimed;后续请求返回当前正在处理的 run,不产生另一场。consumed/pending/运行中的通知不允许“重试”。

8.3 新 run 的输入

新 run 收到的是恢复输入,不是用户新写的一句话:

这是通知 an_… 的第 2 次人工处理。
上一次 run r_… 以 error 结束,机器原因 = delivery_run_error。
原始目标 = …;通知类型 = orchestration_finished。
最终 Task = at_…;resultRevision = 1。
结果摘要 = …;产物 = reports/final.md(report)。
上一次已保存的用户可见正文 = …(若有)。
请核对当前持久结果,补完尚未完成的说明;不要宣称重跑了 Task,不要重复已完成的副作用。

上次正文作为恢复参考,不由程序复制成一条新的 assistant 消息。人工重新处理允许模型组织一份完整说明,但自动路径不得因为 error 再发一遍;已有部分输出必须保留并可审计。

若 doc/72 的计划复核 run 在修订或继续已经被接受后才 error,恢复输入必须读取当前 plan_revision 与图。已接受的决策不因回复 error 而重放;不能在新 run 中再次追加同一批 Task。

9. 回执必须能定位真实内容

最终交付回执至少包含:

{
  "finalTaskId": "at_…",
  "resultRevision": 1,
  "summary": "…",
  "artifacts": [{"path": "reports/final.md", "kind": "report"}]
}

现有 buildCoordinationInput 已把摘要和产物路径拼入协调输入;本方案补的是机器可读的恢复定位、失败后的页面入口和每次尝试的历史,不是把路径只藏在一截提示词里。

10. 限制交付工具面,降低恢复时的副作用

当前交付 run 已移除问人、计划审批与再编排工具。本方案进一步把“读取结果并说明”与“执行新工作”分开:

这样人工重新处理的主要副作用是来源会话里的新说明,而不是一次不受控的新业务执行。即使只读,也不把任何已有输出或工具历史抹掉。

11. 存储与契约变化

11.1 通知行

agent_notifications 增加:

status             -- 增加 failed;既有 pending / claimed / consumed 保持
consume_error_code -- 最近一次协调 run 的 error / stopped / artifact 等原因
failed_at
updated_at

原 error_code 继续表示被通知的 Task 错误,不能与消费通知时的错误混用。

11.2 每次处理尝试

新增 agent_notification_attempts:

id
tenant_id / notification_id
attempt
run_id
created_at

约束 (notification_id, attempt) 唯一、run_id 唯一。首次认领并创建 run 时就写 attempt=1;同 run 的崩溃 resume 只递增 epoch,不新增 attempt;只有人工创建新处理 run 才递增 attempt。doc/82 扩展:来源 run 的就地认领(claimed_in_place=true)不建 run、也不写 attempt 行——attempt 行是「这个 run 承担协调身份」的真源,普通聊天 run 不因此获得只读工具面。run 的状态、正文与错误仍从既有 run/runlog 读取,本表不复制第二份执行状态。覆盖写 claim_run_id 后,旧尝试仍可沿这张表找到。

11.3 编排组与前端

agent_orchestrations 增加 delivery_error_code,与 delivery_status=failed 同源返回。doc/72 的 delivery_failed 处理项增加 notificationId 与当前 runId,让按钮能直接调用重试端点。

浏览器继续复用账号级 SSE;状态改变后发既有 agent_orchestrations_changed,前端重拉,不把失败原因、正文或产物内容塞进事件。普通 HTTP 响应继续使用 code → message → data 信封;新业务码在施工包中分配到 doc/40 的 17 段,并先以真实端点 curl 钉死。

12. 并发、权限与恢复不变量

13. 验收场景

13.1 启动与崩溃窗口

  1. pending 通知在两个副本同时被检查,只创建一个 run 和一条当前认领。
  2. 在“通知 claimed + run 落库”后、worker 启动前 kill -9:租约过期后可显式 resume,同一 run epoch+1,不产生第二条通知。
  3. 交付中 kill -9:journal、todos、结果文件与通知仍在;resume 后旧 epoch 不能写,最终只完成一次交付。
  4. 在 run complete 后、ReconcileDeliveryRun 前死亡:其他副本只补 consumed/delivered,不创建新 run。
  5. 来源会话上有租约已过的中断 run 时,认领与人工重试先把它翻 error 并清 journal,再插新 run;否则 one_live_run_per_session 与「租约仍有效」判据不一致,每轮都撞唯一索引、永久重试。

13.2 error、停止与人工恢复

  1. 交付 run error 且没有 assistant 输出:左侧出现交付失败,产物仍可打开;用户点击重新处理后只创建一场新 run。
  2. 已有部分 assistant 输出后 error:原输出保留,恢复输入包含该事实;不发生自动重试或程序复制旧消息。
  3. 用户停止交付 run:通知变 failed/delivery_stopped,不自动重启;用户明确重试才创建新尝试。
  4. 双击重试、两个标签页或两个副本同时重试:通知状态条件只放行一次,attempt 只增加一次。
  5. 新尝试进行期间旧 run 的迟到收尾不能改变当前通知或组状态。
  6. 新尝试 complete 后,通知 consumed、组 delivered、处理项消失;Task 不重跑、结果revision不变。
  7. 计划复核在修订接受后 error:恢复读取当前图,不重复追加节点。

13.3 结果定位、权限与事件故障

  1. 文件型结果缺少有效产物路径、路径越界或文件已删除时拒绝假装交付,并给出 artifact_invalid。
  2. 纯摘要结果可以在没有文件时恢复,但输入必须带 finalTaskId、resultRevision 与摘要。
  3. 非属主、viewer、其他租户不能读取通知、产物或调用重试。
  4. 来源会话忙或租户容量满时不创建恢复 run;稍后仍可处理。
  5. 停掉事件通道后,RunEnd 与 PG 对账的既有事实仍能收敛;不会因通知重复而多开交付 run。

14. 施工与完成线

施工包按「契约 → 数据需求 → 存储 → 实现 → 验收」连续完成;本稿即最终状态,验收结论见本节末。

施工内部连续完成:

  1. 先以真实端点钉死通知读取、人工重试、失败原因和响应字节;
  2. 补通知失败状态、attempt 审计、当前 claim 条件与交付状态机;
  3. 接通崩溃 resume、RunEnd/调度对账和人工新尝试;
  4. 收紧交付工具面,接通结果文件定位与页面恢复动作;
  5. 完成单测、双副本、kill -9、error、停止、部分输出、事件故障与浏览器验收,主 Agent 审查真实 diff 并重跑关键场景。

完整完成线不是“多了一张 attempts 表”或“重试端点返回 202”,而是:

结果已保存
→ 无论通知在启动前、执行中、收尾后还是明确 error 中出错
→ 系统都能指出结果在哪里、当前谁负责、为什么还没完成
→ 用户能按错误类型安全恢复
→ 旧执行者不能污染新执行者
→ 最终通知只消费完成一次

2026-11-11 验收:agent_task_delivery_recovery_live.sh 十场 109 条全绿(双副本认领、真模型 error → failed → 重试、停止 → 人工重试、产物删除 117110/恢复、双副本并发重试只成一次、worker 首帧前 kill -9 与 delta 后 kill -9 的同 run epoch+1 续跑、complete 后未消费窗口、权限四路径、唤醒流删除后仅靠 PG 周期收敛);expected.json 用例 55–56 与 assert_contract.py 344 条、spotcheck.sh 37 条、doc/72 的 attention/revision/HITL/wakeup(39/68/48/14)及 V1 五场回归全绿。浏览器验收(Playwright + 真模型):左侧出现「交付失败」处理项、点击进入恢复面板、产物按钮触发 GET /api/media 200;点「重新处理」后只多一场交付 run、旧消息与结果保留、处理项与角标随事件消失;两 tab 同时看到同一批处理项,一端动作后两端都自动更新;产物删除后点重试显示「结果产物已不可读取」,会话忙时显示「这场会话正在生成,请稍后再试」。浏览器验收同时抓到并修掉一个前端缺陷:117110 的提示写在 load() 之前会被 load() 开头的清空覆盖,用户看不到反馈。

施工中发现并修掉一个收敛缺陷:崩溃留下的来源会话中断 run 租约已过、忙检查放行,但 one_live_run_per_session 只认 status='running',认领与人工重试会每轮撞唯一索引永久重试;认领/重试事务在插 run 前先跑 expireDeadSessionRunsTx(与 AcquireRun 同一条扫尾,同事务只清被翻 error 的 run 的 journal,§12、§13.1 第 5 条)。

15. 所以这解决了什么

73 把“Task 做完了”与“用户已经收到”之间的最后一段变成可恢复的业务链:崩溃沿用原 run 的 epoch 恢复,明确失败由人发起新尝试,结果始终有持久定位,通知只有在当前交付 run 完整处理后才算消费完成。

它不靠 LLM 自己成功报告错误,不靠盲目重试掩盖部分输出,也不把交付失败误当成 DAG 执行失败。这样,多 Agent 的结果才真正从执行环境可靠地回到用户会话。