微信机器人不是单一接口的简单调用，而是一条从"感知—理解—决策—执行"的流水线。按职责切分，这条流水线可以分为4层，Eyun 接口承担其中感知层和执行层，中间两层由开发者自建。本文按4层架构拆解接口分工，更多接口规范见 Eyun开发文档。

一、4层架构总览

+-------------------+     用户消息
|  感知层 (Eyun)     | <-------------- Webhook回调(4类事件)
|  Webhook接收       |                JSON: msgId/fromUser/content/eventType/wId
+---------+---------+
          |
          v
+-------------------+
|  理解层 (自建)     |     NLU解析
|  意图识别/实体抽取  |                keyword / intent classifier / LLM
+---------+---------+
          |
          v
+-------------------+
|  决策层 (自建)     |     策略选择
|  响应策略/状态机    |                知识库查询 / 业务接口 / 转人工 / 拒绝
+---------+---------+
          |
          v
+-------------------+     回复内容
|  执行层 (Eyun)     | --------------> sendText/sendImage/sendFile
|  消息发送          |                wId指定实例, Token鉴权
+-------------------+

二、感知层

感知层负责"听到"。Eyun 通过 Webhook 推送4类事件回调：消息事件、好友事件、群事件、状态事件。机器人场景主要消费消息事件，回调体为 JSON，字段含 msgId（消息ID）、fromUser（发送方）、content（内容）、eventType（事件类型）、wId（实例ID）。

两个工程约束在此层落地：

• 5秒响应窗口：回调要求5秒内返回 HTTP 200，超时触发重试，最多3次。

• msgId幂等：重试可能导致同一回调多次到达，必须以 msgId 做主键去重。

感知层只做"接"，不做"解"。把解析和决策下推到后续两层，保证回调线程快速返回。

三、理解层

理解层负责"听懂"。从感知层拿到的 content 文本进入 NLU 处理，常见三种实现路径：

1. 关键词匹配：规则引擎，适合话术明确的客服场景，延迟低。

2. 意图分类：传统机器学习模型，处理多意图识别。

3. 大模型推理：LLM 处理开放域对话和复杂语义。

理解层输出的是结构化意图 + 实体，例如 {intent: "查询订单", entity: {order_id: "12345"}}，交给决策层使用。

四、决策层

决策层负责"决定做什么"。输入是意图+实体，输出是响应策略。策略类型包括：查知识库返回FAQ、调业务接口取数据、多轮对话追问、转人工坐席、拒绝应答。

多轮对话由状态机管理上下文，每个会话维护一个状态节点，决策层根据当前状态和输入决定跳转。这层不直接接触 Eyun 接口，但产生的"回复内容"会下发给执行层。

五、执行层

执行层负责"说出口"。决策层产出回复内容后，执行层调用 Eyun 的 sendText/sendImage/sendFile 接口发送。请求体 JSON 含 wId（指定实例）、to（接收方）、content/fileUrl（内容），Token 鉴权在请求头。

执行层的关键容错点是 Token 失效处理：Eyun 返回 1002 错误码表示 Token 过期，调用方需自动刷新 Token 后重试原请求，保证执行链路不断裂。其他常见错误码：1000（参数错误）、1001（鉴权失败）、1004（频率限制）。完整错误码列表见 Eyun平台。

六、4层对比表

七、4层架构消息处理流水线

下面是4层流水线的伪代码，展示一条消息从 Webhook 进入到 sendText 发出的完整链路。

# 4层架构消息处理流水线
from fastapi import FastAPI, Request
import httpx

app = FastAPI()
WID = "instance_001"
EYUN = "https://api.eyunz.com"
seen = set()                # msgId幂等去重

@app.post("/webhook")
async def pipeline(req: Request):
    body = await req.json()
    if body["msgId"] in seen:        # 感知层:幂等
        return {"code": 0}
    seen.add(body["msgId"])
    content, user = body["content"], body["fromUser"]
    intent = nlu_parse(content)      # 理解层:NLU
    action = decide(intent, user)   # 决策层:策略+状态机
    if action.need_reply:
        eyun_send(user, action.reply)   # 执行层:发送
    return {"code": 0}              # 5秒内返回避免重试

def nlu_parse(text: str) -> dict:
    if "订单" in text:
        return {"intent": "query_order", "entity": extract_order_id(text)}
    return {"intent": "unknown", "entity": {}}

def decide(intent: dict, user: str):
    if intent["intent"] == "query_order":
        return Action(True, query_kb(intent["entity"]))
    return Action(True, "未识别意图,转人工")

def eyun_send(to: str, content: str):
    r = httpx.post(f"{EYUN}/sendText",
        json={"wId": WID, "to": to, "content": content},
        headers={"Token": get_token()})
    if r.json().get("code") == 1002:     # Token过期自动刷新
        refresh_token()
        eyun_send(to, content)

class Action:
    def __init__(self, need_reply, reply):
        self.need_reply, self.reply = need_reply, reply

八、小结

4层架构中，Eyun 承担首尾两层：感知层通过 Webhook 把用户消息送进来，执行层通过 sendText 系列把回复发出去。中间的理解层和决策层是开发者的核心工作量所在，决定了机器人的"智能"上限。接口规范与错误码以 Eyun开发文档 为准，本文聚焦于4层分工的边界划分。