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 本期完成线
- 覆盖通知从 pending、claimed、failed 到 consumed 的完整生命周期,以及启动前、执行中、收尾后的故障窗口。
- 进程崩溃/租约过期继续使用同一 run、epoch+1 的显式 resume。
- 交付 run 明确 error/stopped 时提供人工触发的新交付尝试;不自动重放。
- 回执始终能定位最终 Task、结果版本、摘要与实际产物路径;文件型结果不能只存在于交付 run 的上下文。
- 新尝试获得唯一执行权,旧 run、旧 epoch 或旧通知认领者不能覆盖新状态。
- 左侧“需要我处理”与任务/会话详情能看到失败原因、结果位置和可用恢复动作;不依赖 LLM 自己成功报错。
- RunEnd 快路径与调度对账慢路径使用同一收尾函数,崩溃发生在两者之间的通知也能收敛。
3.2 不做
- 不自动重试已经 error/stopped 的交付 run,不自动重放结果未知的外部动作。
- 不把普通聊天 run 的 error 改成可 resume;本方案只处理协调通知所拥有的 run。
- 不重跑已成功的 Task,不修改其结果revision,不把交付失败翻译成依赖失败。
- 不承诺第三方副作用 exactly-once,不用“新 run 永远持有任务不放”代替可过期租约。
- 不新建通知中心、未读表、WebSocket 或另一套 Agent 执行器。
- 不在本方案实现 doc/72 的动态修订;但协调通知的新增类型必须遵守这里的恢复规则。
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 处理,保留每次人工恢复的历史 |
几个容易混用的字段必须分开:
resultRevision只标识结果内容版本;runs.lease_epoch只标识同一 run 的第几代执行者;notification.claim_run_id只标识当前通知由哪场 run 消费;orchestration.delivery_run_id只标识整组当前交付 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 的失败。
完成标志的精确定义:
- 当前
claim_run_id指向的 run 已 complete; - 当前通知从 claimed 变 consumed;
- 对
orchestration_finished,同一事务把当前组从 delivering 变 delivered,并写delivered_at; - 更新条件同时匹配当前
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 前死亡:
- 租约仍有效时不另起 run,因为其他副本可能正在启动同一执行者;
- 租约过期后读侧派生 interrupted,进入现有显式 resume;
- resume 使用同一 run、epoch+1,不另写一条通知,也不改变结果revision。
所以“有一个协程去 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 输出或工具调用。把它们直接重新执行会重复发言或重复外部动作。
因此本期采用:
- down/interrupted:恢复原 run;
- error/stopped:保留原 run 历史,由用户显式发起同一通知的新处理 run;
- 不自动把 error 当 down,也不自动创建无限次重试。
8.2 人工恢复端点
建议新增统一入口,覆盖最终交付与其他协调通知:
POST /api/notifications/:id/retry
成功响应的讨论形状:
{
"notificationId": "an_…",
"runId": "r_…",
"status": "claimed",
"attempt": 2
}该形状不是已验收字节。服务端在同一笔 PG 事务中:
- 按租户、来源 session 属主和写权限校验;
- 锁通知行,要求当前状态为 failed,且最新 run 已是 error/stopped;
- 检查来源 session 当前无其他活 run;忙则保持 failed,返回既有会话忙冲突;
- 读取当前编排目标、通知类型、结果定位与上次失败原因;
- 创建新 run 和
agent_notification_attempts行,attempt 取上一值+1; - 把通知从 failed 条件更新为 claimed,并改写当前
claim_run_id; - 整组完成通知同时把组的
delivery_status从 failed 改为 delivering,并更新delivery_run_id; - 提交后才启动 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"}]
}finalTaskId + resultRevision永远提供,恢复时按它读取当前结果;- 文件型结果必须至少有一个有效
artifacts[].path,使用项目根的规范相对路径; - 纯摘要型结果可以没有文件,但必须保留摘要,不能成为“只有模型上下文里才有答案”的空结果;
- 恢复装配时重新校验项目归属、路径规范与文件存在性;文件缺失时明确报
artifact_invalid,不能把缺失产物交付成成功; - 页面同时提供产物打开/下载与“重新处理”入口,用户即使不再调用模型也能拿到文件。
现有 buildCoordinationInput 已把摘要和产物路径拼入协调输入;本方案补的是机器可读的恢复定位、失败后的页面入口和每次尝试的历史,不是把路径只藏在一截提示词里。
10. 限制交付工具面,降低恢复时的副作用
当前交付 run 已移除问人、计划审批与再编排工具。本方案进一步把“读取结果并说明”与“执行新工作”分开:
- 最终交付与失败/中断说明只允许读取授权结果和产物的只读工具,例如
read_file / read_text_file / read_media_file / read_pdf_text / list_directory / get_file_info; - 不提供 bash、写文件、记忆写入、MCP、子代理、新建编排或问人工具;
- doc/72 的计划复核属于另一种职责,只额外获得
revise_orchestration / continue_orchestration,其写操作必须经过该方案的幂等与版本校验; - 恢复 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. 并发、权限与恢复不变量
- 同一通知任意时刻只有一个当前
claim_run_id;旧 run complete 不得把新尝试标为 consumed/delivered。 - 同一 run 的恢复由
lease_epoch防旧写;不同 run 的人工恢复由通知行的状态条件和当前 claim 指针防旧写。 - 新 run 创建、attempt 审计、通知认领和组交付状态在同一 PG 事务中成功或失败。
- 结果revision在交付恢复中保持不变;如果它被其他合法业务流程改变,恢复输入必须读取最新版本,而不是旧通知快照。
- 只有来源 session 属主且具备既有写权限的用户能恢复;不可见、其他租户和已删除会话不得通过通知 ID 探测。
- 会话忙、租户容量满时不抢占;失败事实保留,用户可稍后处理。认领与人工重试在插 run 前,先按
AcquireRun同一条扫尾把来源会话上租约已过的活行翻 error 并删 journal——忙检查按租约判,one_live_run_per_session只认status='running';少了这一步,崩溃留下的中断会话会让每次认领都撞唯一索引、永久重试。 - 事件丢失只延迟发现,PG 对账仍能完成“complete 但未 consumed”的收尾;事件故障不触发额外恢复 run。
- trace 串联
notificationId / orchestrationId / taskId / runId / attempt / resultRevision / leaseEpoch,日志不记录答案全文或敏感产物内容。
13. 验收场景
13.1 启动与崩溃窗口
- pending 通知在两个副本同时被检查,只创建一个 run 和一条当前认领。
- 在“通知 claimed + run 落库”后、worker 启动前
kill -9:租约过期后可显式 resume,同一 run epoch+1,不产生第二条通知。 - 交付中
kill -9:journal、todos、结果文件与通知仍在;resume 后旧 epoch 不能写,最终只完成一次交付。 - 在 run complete 后、ReconcileDeliveryRun 前死亡:其他副本只补 consumed/delivered,不创建新 run。
- 来源会话上有租约已过的中断 run 时,认领与人工重试先把它翻 error 并清 journal,再插新 run;否则
one_live_run_per_session与「租约仍有效」判据不一致,每轮都撞唯一索引、永久重试。
13.2 error、停止与人工恢复
- 交付 run error 且没有 assistant 输出:左侧出现交付失败,产物仍可打开;用户点击重新处理后只创建一场新 run。
- 已有部分 assistant 输出后 error:原输出保留,恢复输入包含该事实;不发生自动重试或程序复制旧消息。
- 用户停止交付 run:通知变 failed/
delivery_stopped,不自动重启;用户明确重试才创建新尝试。 - 双击重试、两个标签页或两个副本同时重试:通知状态条件只放行一次,attempt 只增加一次。
- 新尝试进行期间旧 run 的迟到收尾不能改变当前通知或组状态。
- 新尝试 complete 后,通知 consumed、组 delivered、处理项消失;Task 不重跑、结果revision不变。
- 计划复核在修订接受后 error:恢复读取当前图,不重复追加节点。
13.3 结果定位、权限与事件故障
- 文件型结果缺少有效产物路径、路径越界或文件已删除时拒绝假装交付,并给出
artifact_invalid。 - 纯摘要结果可以在没有文件时恢复,但输入必须带 finalTaskId、resultRevision 与摘要。
- 非属主、viewer、其他租户不能读取通知、产物或调用重试。
- 来源会话忙或租户容量满时不创建恢复 run;稍后仍可处理。
- 停掉事件通道后,RunEnd 与 PG 对账的既有事实仍能收敛;不会因通知重复而多开交付 run。
14. 施工与完成线
施工包按「契约 → 数据需求 → 存储 → 实现 → 验收」连续完成;本稿即最终状态,验收结论见本节末。
施工内部连续完成:
- 先以真实端点钉死通知读取、人工重试、失败原因和响应字节;
- 补通知失败状态、attempt 审计、当前 claim 条件与交付状态机;
- 接通崩溃 resume、RunEnd/调度对账和人工新尝试;
- 收紧交付工具面,接通结果文件定位与页面恢复动作;
- 完成单测、双副本、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 的结果才真正从执行环境可靠地回到用户会话。