交互与用户体验 / 系统课时
设计工具失败后的重试与接管
设计工具失败后的重试与接管
当 AI 助手调用邮件、工单或外部系统工具失败时,界面不能只给出一个“重试”按钮。本课把错误原因与实际执行状态分开判断,设计可恢复的操作入口,并用发送通知的案例处理重复执行、人工接管和任务终止。
学习目标
- 按错误性质和执行结果判断能否重试。
- 为自动重试、修改参数、重新授权和人工接管安排明确入口。
- 用具体用例验收重复执行防护与终止行为。
先判断错误,再确认是否执行
工具返回错误码,只说明调用未按预期结束,并不一定说明操作没有生效。尤其是“请求已发送但响应超时”,邮件可能已经发出,工单也可能已经创建。界面应同时记录错误类型和执行状态:已完成、确认未执行、尚未确认。
| 情况 | 可观察依据 | 默认恢复方式 |
|---|---|---|
| 临时故障 | 502、503 或连接失败,须核验是否执行 | 限次重试 |
| 请求限流 | 429,可能带 Retry-After |
按服务端要求等待 |
| 参数不合法 | 400、422,返回具体字段问题 | 编辑参数后重新提交 |
| 权限不足 | 401、403 | 重新授权或联系管理员 |
| 无法继续 | 资源已删除、业务明确拒绝执行 | 终止或转人工 |
| 结果不明 | 超时、断线,无法确定副作用 | 先核验,禁止盲目重试 |
这些状态不能只靠 HTTP 状态码推断:例如某次 503 发生在写入之后,仍需查询操作记录。没有可靠核验手段时,将执行状态保持为“尚未确认”。
让每个恢复入口对应一个条件
恢复区固定展示三个要素:失败在哪一步、是否可能已执行、当前允许做什么。不要在“尚未确认”时把“重试”设为主按钮,也不要让用户把“取消重试”误解为“撤销已执行操作”。

对于确认未执行的临时错误,可设置“首次调用后最多自动重试 2 次”,本产品可在两次重试前分别采用约 1 秒和 3 秒的退避,再给并发客户端加随机抖动。服务端若通过 Retry-After 指定等待秒数或 HTTP 日期,应等待到提示时间与本地退避时间中较晚者;达到次数或总体等待预算时,保留原操作状态并停止自动重试。人工重试也要遵守服务端等待时间和执行状态核验。
参数错误应高亮具体字段,例如“收件地址无效”,提供“修改信息”;401 可引导重新登录或授权,403 应说明当前账号缺少权限,而非反复调用。结果不明时只给“核验执行结果”和“转人工处理”等安全入口。
用发送通知验证防重复设计
假设助手替用户发送一封预约确认邮件。用户确认收件人与正文后,工具等待 10 秒超时。此时服务端可能已发送成功,界面应显示“发送结果尚未确认,已暂停自动重试”,而不是“邮件发送失败,请再试一次”。
- 发起业务动作时生成
operationId;同一动作的重复尝试保持相同idempotencyKey,每次尝试另有attemptId。这些键需要服务端支持查询或幂等处理,前端单独保存无法保证不重复。 - 超时后根据操作编号查询服务端记录。若确认服务端已经受理,展示“已提交发送”和回执,不把“受理”误写成“已送达”;只有确认原请求未执行且不会随后执行,或服务端支持该操作的有效幂等键时,才能重试该业务动作。操作查询暂时找不到记录,并不足以证明未执行。
- 如果服务端仍无法确认,又缺少可靠幂等能力,则禁止自动重发,显示“转人工核对发送记录”。
- 若工具明确返回收件地址错误,用户修改收件地址后要再次确认;参数改变意味着新的业务动作,应生成新的幂等键,不能沿用旧请求的键。
界面可在工具卡片内显示“尝试次数 1/3”“最近核验:尚未确认”“操作:核验结果/转人工”。失败卡片应保留在原对话步骤旁,避免用户回看时把下一步任务误认为已经完成。
计算最早允许重试的时间
以下计算只用于已经允许重试的动作。调用方仍需校验执行结果、权限、尝试次数和总时限。例子接受整数秒或服务端按 HTTP 标准发送的日期,计算出的时间也用于控制手动重试按钮。
function retryAt(header, nowMs, backoffMs) {
const value = header?.trim() ?? "";
const local = nowMs + backoffMs;
if (!value) return local;
if (/^\d+$/.test(value)) {
// 极大的等待时间可能超过本次任务的预算,由调用方结束自动重试。
return Math.max(local, nowMs + Number(value) * 1000);
}
const httpDate = /^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2} [A-Z][a-z]{2} \d{4} \d{2}:\d{2}:\d{2} GMT$/;
const parsed = httpDate.test(value) ? Date.parse(value) : NaN;
return Number.isNaN(parsed) ? local : Math.max(local, parsed);
}
const now = Date.parse("Wed, 04 Nov 2026 12:00:00 GMT");
console.log(retryAt("7", now, 3000) - now); // 7000
console.log(retryAt("Wed, 04 Nov 2026 12:00:02 GMT", now, 3000) - now); // 3000这个示例的日期分支识别服务端通常发送的 IMF-fixdate 形式。通用 HTTP 客户端还应使用支持历史日期格式的解析器。若剩余时间不足以等待,停止自动重试。
人工接管和终止如何验收
人工接管时,应把工具名称、脱敏后的输入、错误信息、尝试次数、操作编号、最后一次核验结果和可能的副作用一起交给处理人员;不要仅转发一句“执行失败”。接管后把操作的恢复权移交给人工处理方,取消尚未发出的自动重试,并注明仍在执行或待核验的请求。由人工核对原操作后再决定下一步,避免与自动任务并发重发。
“结束任务”只代表不再发起后续尝试,不等于撤销已经执行的发送、扣款或写入。终止后若晚到成功回执,仍应记录该事实并提示用户核对,不能静默覆盖为“未执行”。
可用四组验收用例逐项检查:只读查询遇 503 时最多重试两次;422 时出现字段修正入口且不自动重试;403 时显示权限处理入口;发送邮件超时且状态未知时必须暂停,并且不会产生第二次发送。若任何一组测试仅靠点击“再试一次”完成恢复,说明风险分流还不够明确。