跳转到内容

消息发送与故障恢复

在消息发送过程中,可能会遭遇一种尴尬的故障:微信服务端已经成功接收了消息,但在向客户端返回 ACK 确认时网络发生了中断。如果客户端此时无脑重发,就会在群里造成消息轰炸和内容重复。因此,agent-wechat 为每一次发送都强制绑定了 幂等键 (Idempotency Key),对于未决结果一律如实报告,绝不擅自自动盲目重试。

微信服务端确认接收 微信服务端明确拒绝 未收到应答超时 取消任务 排队中 queued 提交中 submitting 已接受 accepted 失败 failed 待人工复核 needs_review 已取消 cancelled
状态值业务含义应对方案
accepted微信服务端已确认接收该消息无需操作。(注:这不代表对方手机一定已联网收到)
failed微信服务端明确拒绝该请求排查具体原因,修正后换用一个 全新的 幂等键重新发送
needs_review状态未决:消息可能已经发出,也可能未发出打开手机微信查看该会话实际情况。切勿自动化盲目重发。
cancelled在正式向服务端提交前任务已被主动取消无需操作

相同幂等键,对应同一条发送

CLI 在正式发出网络请求前,会首先在本地保存一份带有该幂等键的收据。如果网络中途断开,请使用该键查询已有记录,而非再次调用发送:

Terminal window
wx messages sends lookup --idempotency-key order-1234-confirmation
wx jobs get JOB_ID

使用相同的幂等键和完全相同的内容再次提交,接口将幂等返回初次发送的已有记录。如果幂等键相同但请求体内容发生了变化,请求将被系统明确拒绝。

服务重启后的恢复机制

已排队的待发送任务、正在进行的下载、未完成的已读通知、事件审计日志以及登录授权凭证均能够完整跨越服务重启。在 Daemon 异常退出时正处于在途提交阶段的任务,在重启后会被标记为 needs_review,防止拉起后无脑二次重复发送。

正常停止 Daemon(或断开网络连接)会保留已保存的登录态。使用 wx auth logout 执行登出,或使用 wx auth logout --local 跳过向微信服务端发送登出请求。两种方式均会停止后台自动重连,直到再次登录。