mulit-agent/controller/docs/steps/12-任务取消超时与重试.md

12：任务取消、超时与重试

目标

让总控对单 Agent 任务拥有最小、可审计的控制闭环：下发时设定超时；执行中可以取消；失败、取消或超时后可以创建一次新的尝试。原始任务记录始终保留。

已实现

1. task_runs 增加 deadline_at、timeout_seconds、attempt 与 retry_of 字段；旧数据库通过增量迁移保持可打开。
2. 下发的 task_dispatch 携带 ISO 8601 的“无进展截止时间”和尝试次数。Agent 回传 accepted 或 running 等有效进展后，总控会以该任务的超时窗口重新计算截止时间。
3. 总控在界面轮询快照/任务列表时检查连续无进展的任务：将状态置为 timed_out、保存事件，并向已连接的 Agent 发送 task_cancel。
4. 新任务默认使用 5 分钟无进展超时；任务页可选择 5、15、30 分钟或 1 小时。活动任务可取消。
5. 只有 failed、cancelled、timed_out 的任务显示“重试”。重试会生成新的任务 ID 和新的尝试次数，并以 retry_of 指回原始任务，绝不覆写旧记录。

协议约定

取消消息：

{
  "type": "task_cancel",
  "schema_version": 1,
  "task_id": "...",
  "reason": "由总控取消"
}

Agent 必须以普通 task_event 回报最终状态 cancelled 或 timed_out；总控不把“取消指令已发出”误当作 Agent 已停止。

验收

1. 下发任务后确认 Agent 回传“已接收”或“执行中”，任务详情中的“下次无进展超时”应向后刷新。
2. 在演示任务的执行窗口内点击“取消”，任务应最终显示“已取消”。
3. 对已取消或已超时任务点击“重试”，列表应出现新的任务 ID 与“第 2 次”，旧记录仍存在。
4. 已完成任务不应提供重试操作。

当前边界与下一步

当前 Agent 在连接中断时只在内存中暂存待发送事件；进程重启后的事件补传、任务幂等恢复和断线重连回放尚未实现。这些属于下一阶段的可靠性工作，不能作为本步骤已完成的能力对外承诺。