WeMai Adapter

MaiBot 的微信适配器插件 —— 通过 WebSocket 桥接远端的微信客户端，让 LLM 收发微信消息、朋友圈、好友请求。

⚠️ 分支说明

本分支（master）为 WeFlow 模式版本，通过 WeFlow HTTP API 实现消息收发，无需操控微信 GUI。

如果你需要纯 pyweixin 实现（不依赖 WeFlow，请切换到 pure-uia 分支下载。

⚠️ pure-uia 版本存在以下已知差异：

• emoji 表情通过截图以图片形式识别，无法从微信内直接获取表情包数据
• 不支持 WeFlow 模式的数据源切换
• 部分功能（如图片解密、朋友圈读取）依赖 UIA 自动化，稳定性和速度不如 WeFlow
• 发送仍依赖 pyweixin 的 UIA 操控，WeFlow 版本的发送路径不同

---

是什么

WeMai Adapter 是 MaiBot 的插件，部署在服务器上，开放一个 WebSocket 端口等待运行在 Windows 电脑上的 WeMai Client 连接。连接建立后，微信消息在这条隧道里双向流动：

微信 GUI ←→ WeMai Client (Windows) ←WS→ WeMai Adapter (服务器) ←→ MaiBot ←→ LLM

功能

能力	工具名	说明
收发文本/表情/图片/视频	@MessageGateway	自动处理，双向桥接
群聊 @ 检测	_build_segments_from_raw	自动从消息中提取 @ 成员
好友请求通知	hub_approve_friend	LLM 在"系统"聊天流中接收好友请求通知，可批准或忽略
好友请求批准	hub_approve_friend	通知客户端通过好友申请
好友请求忽略	hub_dismiss_friend	通知客户端清除好友请求但不通过
通知管理员	hub_send_notification	LLM 可主动向管理员发送通知
跨会话消息	hub_tell	中枢介入指定会话发言
读取朋友圈	read_wechat_moments	拉取最近朋友圈（字段：author/content/time/images）
发朋友圈	post_wechat_moment	代表用户发布朋友圈文字
聊天过滤	—	配置群聊/私聊白名单
定时检查	—	内置中枢 tick 驱动 LLM 周期性巡检
消息去重	—	基于内容+时间的 MD5 去重
语音消息	—	客户端自动转文字后以 [语音]xxx 格式送达 LLM
引用回复	reply_to 字段	MaiBot 出站消息带 reply_to 时，自动查原文并调用微信引用回复
连接保持	—	TCP keepalive 加速 + 客户端 30s 心跳，避免长连接被中间设备踢断

架构

┌──────────────────────────────────────────────────────────┐
│  服务器                                                    │
│  ┌─────────────────────────────────────────────────────┐  │
│  │  MaiBot                                              │  │
│  │  ┌────────────────────────────────────────────────┐  │  │
│  │  │  WemaiAdapterPlugin (plugin.py)                │  │  │
│  │  │  ├── @MessageGateway → 消息出入站双向桥接       │  │  │
│  │  │  ├── @Tool × 9 → LLM 可调用功能                │  │  │
│  │  │  │   hub_approve_friend     批准好友            │  │  │
│  │  │  │   hub_dismiss_friend     忽略好友            │  │  │
│  │  │  │   hub_tell               跨会话消息           │  │  │
│  │  │  │   hub_send_notification  系统通知            │  │  │
│  │  │  │   hub_check_chat_status  聊天状态检查         │  │  │
│  │  │  │   read_wechat_moments    读朋友圈            │  │  │
│  │  │  │   post_wechat_moment     发朋友圈            │  │  │
│  │  │  ├── 好友请求 → 注入中枢 → LLM 自主决策        │  │  │
│  │  │  ├── 中枢 tick → 定时巡检                      │  │  │
│  │  │  └── WemaiWsServer (raw TCP, length-prefix)  │──┼──┼── WS
│  │  └────────────────────────────────────────────────┘  │  │
│  └─────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────┘

协议：基于 TCP，4 字节大端长度前缀 + UTF-8 JSON 消息体。Client 主动发起连接，Adapter 只监听不拨出。

好友请求处理流程

Client 检测到新好友请求
  → Adapter 收到 friend_request
    → 注入"系统"聊天流，附带操作说明
      → LLM 看到通知，自主决定：
        ├── hub_approve_friend → Client verify=True → 通过
        ├── hub_dismiss_friend → Client clear=True  → 忽略
        └── hub_tell → 通知管理员或其他会话

引用回复流程

当 MaiBot 使用 reply 工具回复消息时，Adapter 自动检测出站消息的 reply_to 字段，通过 ctx.message.get_by_id() 获取原始消息内容，将原文作为 reply_to.text 传给 Client。Client 收到后调用微信的引用回复功能，在 UI 上完成"右键 → 引用 → 输入 → 发送"操作。

MaiBot reply(set_quote=auto)
  → handle_wemai_gateway 检测 reply_to
    → ctx.message.get_by_id(reply_to_id)
      → 提取 processed_plain_text
        → outbound.reply_to = {text: "原文"}
          → wemai-client wx_sender
            → Messages.reply_with_quote(quote_text="原文", reply_messages=["回复"])

需在 _manifest.json 中声明 "message.get_by_id" 能力。

安装

将 wemai-adaptor/ 放入 MaiBot 的 plugins/ 目录，在 WebUI 中启用插件。

git clone https://github.com/taskmemz/wemai-adapter
cp -r wemai-adapter /path/to/MaiBot/plugins/

配置

所有配置在 MaiBot WebUI 的插件管理界面完成，分为 5 个分组：

分组	配置项	默认值	说明
插件设置	enabled	false	是否启用
	config_version	1.0.0	配置结构版本（自动管理）
	admin	[]	管理员会话名列表，中枢通知发给这些会话
WebSocket 服务器	host	0.0.0.0	WS 监听地址
	port	9721	WS 监听端口
数据源	mode	pyweixin	下拉选择：pyweixin（UIA 自动化）或 weflow（WeFlow HTTP API）
	weflow_base_url	http://127.0.0.1:5031	WeFlow API 地址（仅 weflow 模式生效）
	weflow_api_token	""	WeFlow Token（仅 weflow 模式生效）
	weflow_poll_interval	0.8	WeFlow SSE 轮询间隔（秒）
聊天过滤	enable_chat_list_filter	false	是否按名单过滤
	group_list	[]	群聊白名单（WeFlow: 填 wxid；pyweixin: 填群名）
	private_list	[]	私聊白名单（WeFlow: 填 wxid；pyweixin: 填昵称）
客户端行为	send_delay	0.2	发送间隔（秒）
	close_weixin	false	发送后是否关闭微信窗口
	include_muted	false	是否包含免打扰会话
	excluded	["文件传输助手", "微信团队", "微信支付"]	排除的会话名

配置通过 WebSocket 连接建立时全量推送给客户端，修改后通过热重载即时生效。

依赖

• MaiBot ≥ 1.0.0
• maibot_sdk ≥ 2.0.0

常见问题

Client 连不上？ 检查服务器防火墙是否放行了监控端口（默认 9721），以及 Client 的 config.toml 中 server_host 是否为服务器 IP。

插件日志？ Adapter 的日志通过 MaiBot 的日志系统输出，logger 名为 wemai_adapter。

WS 反复断连？ 检查 Client 日志是否出现 "读取 4 字节超时"——可能是中间网络设备静默踢掉了空闲连接。Client 已内置 30 秒心跳 + TCP keepalive 加速（10s/3s/3 次），通常无需额外配置。若仍有问题可尝试将 reconnect_delay 调大（如 15 秒）。