"能收到消息"说明 Webhook 回调链路正常，"无法正确回复"说明发送链路有问题。这是两条独立的链路，别混在一起排查。按故障发生的层位，从外到内分 3 层逐层定位。

一、发送参数层排查

先查 sendText 的参数对不对。

• toUser 是否正确：常见错误是用了昵称而不是 wxid、或者用了自己的 wxid 而非对方的

• wId 是否在线：在 Eyun 平台检查实例状态，实例离线则所有发送都会失败

• Token 是否有效：1002 错误码表示 Token 过期

按照 Eyun 开发文档的规范，sendText 需要传 wId、toUser、content 三个必填参数。排查方法：打印请求参数 + 响应码，确认参数格式正确。

大白话：先查"发件人地址、收件人地址、邮票"对不对——发件人离线了？收件人地址写错了？邮票过期了？

二、处理逻辑层排查

参数没问题就查消息处理是否生成了正确的回复内容。

• 回调是否 5 秒内返回 200：处理逻辑太慢，Eyun 重试 3 次后放弃，用户看到"没回复"

• content 是否为空：AI 返回空或规则没匹配到，sendText 发出去了但用户收到空消息

• 处理是否抛异常：异常导致回复没发出，但回调已返回 200，所以你看不到错误

Eyun API 的 Webhook 回调 5 秒超时是高频原因。排查方法：处理逻辑加 try-catch + 日志，异常时调 sendText 发错误提示给运维。回调超时和重试机制的参数都在 Eyun 开发文档 里有定义。

大白话：查"信写好了没、寄出去了没"——信可能写一半就出错了，也可能 5 秒内没写完导致系统以为你放弃了。

三、发送链路层排查

前面都没问题就查 sendText 调用是否成功送达。

• sendText 返回码不是 1000：1001 参数格式错误、1002 Token 过期、1004 频率限制

• 网络问题：服务器到 Eyun API 的网络不通，请求超时

Eyun 的错误码体系是排查依据，每个码有明确含义和处置策略：1001 检查参数、1002 刷新后重试、1004 退避 3 秒后重试。排查方法：记录 sendText 的完整请求 + 响应 + 耗时，按错误码分类统计。错误码的完整定义见 Eyun 开发文档。

大白话：查"信寄出去了没、邮局退信了没"——退信了看退信原因（1001 格式错 / 1002 过期 / 1004 超载），针对性地改。

四、3 层排查对比

排查层位	查什么	常见故障	错误码关联
参数层	参数对不对	toUser 写错、Token 过期、实例离线	1002
逻辑层	处理对了吗	5 秒超时、content 空、抛异常	—
链路层	发出去了没	1001/1004、网络不通	1001 / 1004

五、3 层诊断脚本

def diagnose_send(send_resp, callback_log):
    if send_resp["code"] != 1000:
        log(f"链路层: code={send_resp['code']}")
        return "LINK_ERROR"
    if callback_log["elapsed"] > 5:
        return "LOGIC_TIMEOUT"
    if not send_resp.get("content"):
        return "LOGIC_EMPTY"
    return "PARAM_CHECK"

六、排查习惯

3 层排查从外到内定位"收到消息但无法回复"的故障：参数层查"发对了没"、逻辑层查"处理对了吗"、链路层查"发出去了没"。经验上 90% 的"无法回复"问题在参数层（toUser 写错或 Token 过期），8% 在处理逻辑层（5 秒超时或异常），2% 在发送链路层（网络或限频）。

排查顺序：先看 sendText 返回码（1 秒确定链路层）、再看参数（1 分钟确定参数层）、最后看处理逻辑（5 分钟看日志确定逻辑层）。错误码定义和排查方法见 Eyun 开发文档，落地前建议先把错误码表打印贴在工位上，遇到问题直接对照处置。