工具执行、确认与幂等

核心概念

工具调用让系统读取或修改业务状态。模型提出的调用参数只是候选输入，服务端必须校验参数、授权和业务条件。创建、修改等动作应先展示动作、目标及关键字段，请用户确认；确认后字段发生实质变化，需要重新确认。

幂等是让同一个业务动作重复提交时不产生重复效果。通常为一个确认后的动作分配稳定的幂等键，并让接口保存该键对应的结果。换一个键重试，可能被接口视作新动作。

情境拆解

员工确认创建空调报修工单，mock API 已保存工单但响应超时。助手此时只能说“结果待核对”，不能报告失败，也不能换键再建一次。应按原幂等键或业务关联编号查状态；需要重试时，须遵守接口约定并沿用同一动作标识。

只有取得可靠工单编号或状态记录，才能报告“已创建”。执行记录应关联请求、确认摘要、幂等键及结果，方便追溯；练习只调用模拟接口，不接真实企业服务。

常见误区

把用户一句“帮我弄好”理解成所有后续修改的授权，会扩大动作范围。日志显示“发出请求”也不等于工单完成；网络超时不能证明服务器没有写入。

一次动作从确认到核对

模拟用户确认了 store-demo 门店、device-demo 设备和一段故障描述。应用为这次动作保留稳定标识 action-demo-001。

接口写入成功，但响应在返回途中超时。客户端此时是“结果未知”；服务端可能已经有一张工单。先按原动作标识查询，查到可靠编号后反馈结果。不能换一个标识立即重建。

幂等需要服务端定义去重、参数冲突和保留期限等行为，并验证实际状态。仅在请求里加一个字段，不会自动产生这些保证。

动手：设计确认卡与三种回执

1. 写一张确认卡，让用户看清动作、门店、设备与描述。字段变化后重新确认。
2. 分别模拟成功、无权限拒绝和写入后响应超时，记录请求、实际状态及用户能看到的证据。
3. 给超时情境增加按原动作标识查询的步骤。仍无法核实时保留未知，交给明确接手者。
4. 对相同动作重复请求，说明服务端应返回原结果还是拒绝冲突，而不是另建记录。

确认摘要：
当前参数版本 / 动作标识：
用户是否确认当前摘要：
权限与资源状态：
接口尝试及传输结果：
业务状态：已完成、已拒绝或未知
核对方式与可靠工单编号：
给用户的回复：

检查产物

“已完成”只在有可靠证据时出现。重复请求不会被设计成新动作；用户取消或未确认时不写入。有关 HTTP 重试与幂等语义可参阅 RFC 9110 第 9.2.2 节，它不能替代你自己的业务去重契约。