接手过一个别人搭的自动回复机器人，跑了半个月停了——回调超时、消息丢失、回复错乱，客户投诉一堆。后来重新搭了一遍，把链路理顺了才稳定下来。这篇按功能模块讲怎么搭一个支持自动回复的业务助手，从收消息到回消息再到异常处理，每一步该调什么接口、注意什么坑。

底层用的是 Eyun 平台开放的企微 API，凭证和实例在Eyun 平台首页开通，统一 POST+JSON、Bearer 鉴权。核心链路是 Webhook 收消息 → 处理 → sendText 回消息，中间加状态管理和异常处理。

主流程：收消息 → 处理 → 回消息

from flask import Flask, request
import requests

app = Flask(__name__)
BASE = "https://api.eyun.com"
HEADERS = {"Authorization": "Bearer eyk_xxxx"}

@app.route("/wx-api/webhook/", methods=["POST"])
def webhook():
    event = request.headers.get("X-Eyun-Event")
    if event != "message":
        return "ok"
    
    payload = request.json
    from_uin = payload["data"]["fromUin"]
    content = payload["data"]["content"]
    appid = payload["data"]["appid"]
    
    # 异步处理，立即返回
    handle_message(appid, from_uin, content)
    return "ok"

def handle_message(appid, from_uin, content):
    reply = generate_reply(appid, from_uin, content)
    requests.post(
        f"{BASE}/wx-api/api/message/sendText",
        headers=HEADERS,
        json={"appid": appid, "to": from_uin, "content": reply}
    )

Webhook 必须 5 秒内返回，所以 handle_message 是异步的——实际实现里推队列或开线程，这里简化了。消息体字段和投递语义在开发文档里有完整说明，回调是至少一次投递，要用 X-Eyun-Delivery 去重。

会话状态机：idle → in_flow → need_human

自动回复不能每条消息都回——客户连发三条"在吗""多少钱""能便宜吗"，机器人连回三条"您好请问有什么可以帮您"，体验很差。用会话状态机管理：

• idle：空闲状态，收到新消息进入处理流程

• in_flow：正在处理中，收到的消息合并到当前流程

• need_human：需要人工介入，机器人不再自动回复

状态存 Redis，key 是 chat_state:{fromUin}，TTL 30 分钟。客户发消息先查状态，idle 就启动新流程，in_flow 就合并消息，need_human 就转人工不自动回。

关键词 + 轻量意图：两层匹配

回复内容怎么生成？两层匹配：

第一层关键词规则——"退款"回退款流程、"发票"回发票链接、"人工"转人工。规则是正则或关键词列表，命中即回，响应快、成本低。

第二层轻量意图分类——规则没命中的，塞给模型分类到预定义意图（咨询产品、询价、投诉、其他），按意图回对应话术。模型用轻量版（比如 7B 参数），延迟控制在 1 秒内，成本可控。

两层都找不到答案的，回"我帮您转接人工客服"，同时调接口通知客服组。别硬答，答错了客户更烦。

单聊和群聊分流

单聊和群聊的处理逻辑不同。单聊是 1v1，客户发什么机器人都可以回。群聊是 NvN，机器人乱回会刷屏，要克制：

• 群聊里只回 @ 机器人的消息，或者命中关键词的消息

• 群聊里客户连发消息要合并——30 秒内同一客户的多条消息合并成一条处理

• 群聊里机器人的回复要 @ 提问的人，不然别人不知道在回谁

群聊的 conversationId 是 roomId，单聊是 userId，处理时按类型分流。

异常处理：回调超时和发送失败

回调超时是最常见的事故源头。处理流程里调模型、查业务数据库都可能慢，超过 5 秒平台会重试，重试三次还超时就丢消息。我们的做法是把耗时操作（调模型、查业务）压缩到 3 秒内，超时的走降级——回"正在为您查询，请稍等"，然后异步处理完再补发结果。

发送失败也要处理。sendText 返回错误码 -3020 会话错误、-11001 断线，按类型分流：会话错误重新拉会话，断线告警人工介入。错误码对照在开发文档里有完整列表。

业务助手的核心是稳定

自动回复机器人不难搭，难的是搭稳定。回调 5 秒内响应、消息去重、状态管理、异常分流，每一层都做扎实，客户才感觉不到机器人的存在——消息发出去 3 秒内收到回复，回复内容准确，体验自然。