按故障选择动作
重试同一提交
在发送之前持久保存下列值。恢复片段接续已有客户端:idempotency_conflict。已经接受的同一请求会返回原记录,即使后来连接被禁用;这不意味着可以提交新的工作。
重试策略应限定次数和退避,区分瞬时传输故障、鉴权失败、输入错误和业务状态冲突。SDK 不会替你盲重放非幂等操作。
网络调用前保存恢复记录
可恢复的 Run 提交不能只保存最后一个错误。持久记录业务请求 ID、有权使用的 Session ID、精确 input 和 origin、幂等键、尝试时间、已知时的 Run ID,以及最后提交的事件游标。它们应存放在私有应用存储,原始任务内容可能敏感。响应丢失应记录为提交结果未知,不是任务失败。 SQLite 意图示例演示提交持久化边界,事件游标示例演示观察恢复。两者记录不同事实:事件游标不能找回丢失的提交键,提交键也不表示 UI 已收到事件。
有限重试结束后,应保留可恢复状态与标识。达到重试次数上限不证明远端任务失败;操作员或后续恢复任务应从原记录继续调查。
主动取消与关闭
对账外部写入
tool_calls / toolCalls 提供调用与 request_hash。先在远端查明请求是否生效,再通过 resolve_tool_call / resolveToolCall 提交结果和审计证据。该接口交付已验证结果,不重新请求外部服务。无法证明结果时保留 unknown,不能编造成功或失败。管理身份限制与审批类似,见对账协议。
验证恢复
分别注入流断开、提交响应丢失、worker 重启、远程写入响应丢失和删除响应丢失。核对是否仍是同一个 Run / 原始资源,工具副作用次数是否正确,并保留未决 ID。模拟检查只能证明对应分支逻辑,真实云与模型的完整旅程单独记录。 依据:恢复架构、持久事件。下一步:后端接入。明确每项恢复的结束条件
观察截止时间只表示应用停止等待,不代表 Hexagon 已取消任务。向用户返回可恢复的状态,保留调查记录。清理异常必须继续可见,不能为了在业务结果成功后打印“完成”而吞掉异常。
例如,第二轮提交超时且未返回 Run ID:读取保存的 input、origin 和 key,按有界重试策略精确重发;取得 R2 后先保存 R2,再从已提交游标恢复事件。如果随后某个 Tool call 进入 unknown,就应停止提交重试:此时恢复对象已变成该调用的外部结果,而不是原 Run 请求。最后关闭 Session 又是独立操作,需要另行确认结果。
依据:提交与取消、Runtime 监督、Tool 对账、错误参考。下一步:资源对账、故障排查、事件与恢复概念。