微信机器人背后的接口基础：个人微信API接口究竟承担哪些工作？

微信机器人不是单一接口的简单调用而是一条从感知—理解—决策—执行的流水线。按职责切分这条流水线可以分为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 处理常见三种实现路径关键词匹配规则引擎适合话术明确的客服场景延迟低。意图分类传统机器学习模型处理多意图识别。大模型推理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层对比表层级承担方核心工作Eyun接口输出物感知层EyunWebhook接收用户消息Webhook(4类事件回调)JSON回调体(msgId/fromUser/content)理解层自建NLU意图识别与实体抽取无结构化意图实体决策层自建响应策略选择与状态机无回复内容/动作指令执行层Eyun发送富媒体回复sendText/sendImage/sendFile消息送达回执七、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层分工的边界划分。