第 7 章 · 03 国内平台实战：微信/飞书/钉钉/QQ/企微/元宝
第 7 章 · 03 国内平台实战：微信/飞书/钉钉/QQ/企微/元宝
本节摘要：本节是中文读者的主场——Hermes 原生支持国内六大平台：微信（weixin，个人号经腾讯 iLink Bot API）、飞书/Lark（feishu，企业应用 websocket/webhook 双模）、钉钉（dingtalk，Stream 模式 WebSocket）、QQ 机器人（qqbot，官方 Bot API v2 网关）、企业微信（wecom，AI Bot WebSocket 网关）、元宝（yuanbao，腾讯企业消息 WebSocket 网关）。先给六平台接入方式对照表，再精读
weixin.py（2451 行）：长轮询驱动、context_token 回显契约、AES-128-ECB 加密 CDN 媒体协议、QR 扫码登录。随后过一遍其余五平台的接入要点，最后直面国内平台的特有挑战（iLink 身份限制、审核、接口配额），并回答一个战略问题：agent 直接进国民级 IM，对中文用户意味着什么。
内容来源：原项目源码
gateway/platforms/weixin.py、gateway/platforms/qqbot/、gateway/platforms/yuanbao.py、plugins/platforms/feishu/、plugins/platforms/dingtalk/、plugins/platforms/wecom/，以及website/docs/user-guide/messaging/下 weixin/feishu/dingtalk/qqbot/wecom/yuanbao 六篇文档。
⚠️ 注意：微信适配器面向个人号（iLink Bot 身份），不是公众号/企业微信；企业场景请用 wecom。官方文档明确警告：iLink bot 身份通常进不了普通微信群、也收不到普通群的 @ 事件——群策略配置只有在 iLink 真的回报群事件时才有意义，多数部署只有 DM 可靠。网关在
WEIXIN_GROUP_POLICY非 disabled 时会打 WARNING。
学习目标
阅读完本节，你应当能够：
- 列出六平台的接入方式、传输协议与凭据形态。
- 讲清 weixin 的四条设计笔记：长轮询、context_token 回显、AES CDN、QR 登录。
- 说出微信入站的三重准入策略（dm_policy/group_policy/pairing）。
- 解释飞书/钉钉/企微/元宝为何都选 WebSocket 而非 webhook。
- 描述 QQ 机器人如何复用第 7.2 节的语音转写链路。
一、六平台接入对照表
| 平台 | 目录 | 接入方式 | 传输 | 凭据 | 建应用入口 |
|---|---|---|---|---|---|
| 微信 weixin | gateway/platforms/weixin.py |
iLink Bot API（个人号） | HTTP 长轮询（35s） | QR 扫码换 account_id+token | hermes gateway setup 终端 QR |
| 飞书 feishu | plugins/platforms/feishu/ |
企业自建应用 | websocket（推荐）/webhook | App ID + App Secret | 扫码建应用或开放平台手建 |
| 钉钉 dingtalk | plugins/platforms/dingtalk/ |
机器人 Stream 模式 | 长连 WebSocket | Client ID + Secret | 开放平台建机器人 |
| QQ qqbot | gateway/platforms/qqbot/ |
官方 Bot API v2 | WebSocket 网关 + REST | App ID + App Secret | q.qq.com 注册 |
| 企微 wecom | plugins/platforms/wecom/ |
AI Bot 网关 | WebSocket 双向 | Bot ID + Secret | 管理后台建 AI Bot（可扫码代建） |
| 元宝 yuanbao | gateway/platforms/yuanbao.py |
企业消息网关 | WebSocket + HMAC | APP_ID + APP_SECRET | App 内 PAI→My Bot |
共同点一眼可见：全部不需要公网 IP。六家全部走外连（长轮询或 WebSocket），家庭宽带、NAS、公司内网都能部署——这与国际平台的形态分布一致，但密度更高：国内平台几乎清一色「客户端模式」。
二、微信精读：iLink Bot API 的四条契约
weixin.py 模块头的设计笔记言简意赅：
weixin.py:4 Design notes: 5 - Long-poll ``getupdates`` drives inbound delivery. 6 - Every outbound reply must echo the latest ``context_token`` for the peer. 7 - Media files move through an AES-128-ECB encrypted CDN protocol. 8 - QR login is exposed as a helper for the gateway setup wizard.
其一，长轮询。_poll_loop（weixin.py:1371）循环调用 EP_GET_UPDATES（ilink/bot/getupdates，35 秒超时），会话过期（errcode -14）自动重建，限频（errcode -2）开退避断路器（_open_rate_limit_circuit），连续失败 3 次进入 30 秒 backoff。
其二，context_token 回显契约。iLink 要求每条回复携带对话方最新的 context_token。入站处理的第一件事就是存下它：
weixin.py:1499 context_token = str(message.get("context_token") or "").strip() 1500 if context_token: 1501 self._token_store.set(self._account_id, sender_id, context_token)
ContextTokenStore（weixin.py:298）把 per-peer token 持久化到 ~/.hermes/weixin/，网关重启后第一句回复依然合规。配套的 TypingTicketCache 缓存"正在输入"票据，让 agent 思考时对方能看到输入态。
其三，AES-128-ECB CDN。图片/视频/文件/语音经 novac2c.cdn.weixin.qq.com 收发，报文体 AES 加密——_download_voice、_download_image 等先解密再落本地缓存（复用第 7.1 节 base.py 的 cache_audio/image/video 体系）。
其四，准入三策略。_process_message（weixin.py:1467）先做 message_id 去重 + 内容指纹去重（content:{sender}:{md5}，TTL 300 秒——微信会重推消息），再按策略放行：
weixin.py:1488 chat_type, effective_chat_id = _guess_chat_type(message, self._account_id) 1489 if chat_type == "group": 1490 if self._group_policy == "disabled": 1491 return ... 1496 elif not self._is_dm_intake_allowed(sender_id): 1497 return
DM 走 dm_policy（disabled/allowlist/open/pairing），群走 group_policy（disabled/allowlist/pairing）；enforces_own_access_policy=True 告知网关"我在入口处自管鉴权"。文本消息还有合批防抖（_enqueue_text_event，weixin.py:1587）：用户连转多条消息时按会话键缓冲、定时 flush 合并成一个事件——照顾"转发聊天记录"这类中文场景。
出站同样有细节：_send_text_chunk_locked 发送前检查限频断路器（_rate_limit_error），_SPLIT_THRESHOLD = 1800（iLink 在约 2048 字符处截断，提前自己分片保完整），TypingTicketCache 的票据让"对方正在输入"显示与发送节奏解耦。环境变量面（~/.hermes/.env）足够精简：QR 登录后自动持久化 account_id/token/base_url 到 ~/.hermes/weixin/accounts/，日常只需 WEIXIN_DM_POLICY、WEIXIN_GROUP_POLICY、WEIXIN_ALLOWED_USERS 三五个旋钮。
三、其余五平台要点
飞书：双模（websocket 推荐 / webhook 备选），文档给足权限 scope 清单；群内只响应 @机器人，共享群默认 group_sessions_per_user: true 按用户隔离会话。插件目录里还有 feishu_comment.py（评论联动）与 feishu_meeting_invite.py（会议邀约）两个增值模块，tools/feishu_doc_tool.py、feishu_drive_tool.py 更把飞书文档与云盘做成 agent 工具——不只是聊天，而是整个工作面。扫码建应用（scan-to-create）是首选：hermes gateway setup 选 Feishu/Lark，手机扫码即自动建好带正确权限的应用并存好凭据；手动路径则是开放平台建应用→复制 App ID/Secret→开 Bot 能力→在权限管理页批量导入 scope（消息读写、群信息、文件下载等）。
钉钉：Stream 模式长连 WebSocket，免公网；回复走钉钉 session webhook API，markdown 格式渲染。行为约定与飞书一致：DM 全响应、群内 @ 才响应。依赖安装一条命令：uv pip install -e ".[dingtalk]"——第 7.1 节 PlatformEntry 的 ensure_deps_fn 钩子管的就是这类 extras。hermes_cli/dingtalk_auth.py 辅助凭据接入。
企微：AI Bot WebSocket 网关（wecom/adapter.py），另有 wecom_callback.py 处理回调模式的入站事件、wecom_crypto.py 负责加解密。扫码建应用流程与飞书同款：终端出二维码→企微 App 扫码→自动取回 Bot ID 与 Secret→引导配置访问控制。
QQ 机器人：官方 Bot API v2，持久 WebSocket 收消息 + REST 发回复，支持 C2C 私聊、群 @、频道、私信四种场景；语音转写直接复用第 7.2 节链路，文档明言可用腾讯自带 ASR 或自定义 STT provider——国内平台同样吃到语音器官。目录里 crypto.py（票据解密）、chunked_upload.py（分片上传）、keyboards.py（按钮）、onboard.py（QR 注册流程，qr_register 渲染终端二维码引导绑定）分工明确。
元宝：WebSocket 网关 + HMAC 认证，支持 C2C 与群聊、富媒体；yuanbao_proto.py（协议编解码）、yuanbao_media.py、yuanbao_sticker.py（表情包）分层清晰。App 内「PAI → My Bot」创建后复制 APP_ID/APP_SECRET 即可。
准入侧还有一层与平台无关的通用闸：pairing 配对码（第 7.2 节讲过的 gateway/pairing.py）。微信的 dm_policy=pairing 模式正是它的消费者——陌生用户私聊 bot 时收到配对码，主人在 CLI 批准后才进 allowlist，比手工抄 weixin_id 友好得多。
四、特有挑战与战略价值
国内平台的挑战清单：其一，身份与审核——iLink bot 身份进不了普通微信群；QQ/企微机器人需要在开放平台注册应用、沙箱先行；飞书钉钉需要企业管理员权限与 scope 审批。其二，接口配额——微信 errcode -2 限频、钉钉企业 API 配额、QQ 平台频控，适配器层面普遍内置断路器与退避（weixin.py 的 rate-limit circuit 是范本）。其三，协议私有性——context_token 回显、AES CDN、HMAC 握手都没有公开标准文档可循，适配器注释里大量"实测行为"记录正是逆向成本。其四，凭据生命周期——token 过期重登（SESSION_EXPIRED_ERRCODE=-14）、多账号目录（~/.hermes/weixin/accounts/）、scope 增补，都是长期运维的日常。
但对中文用户，回报是决定性的：agent 第一次可以直接住进国民级 IM。微信月活十亿级、飞书钉钉覆盖绝大多数企业与高校——不需要教用户开新 App、不需要导流，Hermes 的技能系统（第 4 章）、记忆（第 5 章）、审批安全（第 3 章）全部原样出现在他们每天已经打开的聊天窗口里。一个具体的使用图景：飞书群里 @机器人「把上周的会议纪要整理成文档存到云盘」——feishu_doc_tool 与 feishu_drive_tool 直接可用，产出回到同一个群；第二天在微信里问起后续，跨平台会话连续性与记忆器官把上下文接上。配合第 9 章的 deepseek/kimi/qwen/GLM provider 与 FTS5 中文检索，一条全栈国产的 agent 落地路径就此闭环：国产 IM 进、国产模型算、国产化部署（单进程、免公网、内网可跑）。
💡 循环要点：六大国内平台共用国际平台的同一套抽象（BasePlatformAdapter + PlatformEntry + 会话键），这印证了第 7.1 节的设计——平台差异被压缩在适配器一个文件里，网关与内循环完全无感。对外循环而言，中文会话轨迹与英文轨迹同权地进入 curator 与 learning_graph；用户基数越大、场景越多，技能库的复利越厚。社交器官的宽度，就是自我改进循环的供血量。
本节要点回顾
- 六平台对照：微信 iLink 长轮询、飞书 websocket/webhook 双模、钉钉 Stream WebSocket、QQ 官方 API v2、企微 AI Bot 网关、元宝 WebSocket+HMAC——全部免公网。
- 微信四契约：35 秒长轮询、context_token 持久化回显、AES-128-ECB CDN 媒体、QR 扫码登录；配额限频走断路器退避；出站 1800 字符自分片。
- 入站防御：message_id + 内容指纹双重去重（TTL 300 秒）、dm/group/pairing 三策略自管准入、文本合批防抖。
- 增值面：飞书文档/云盘工具与扫码建应用、钉钉 extras 安装、QQ 四场景 + QR 注册 + 语音转写复用、元宝表情包——平台适配不止于收发消息。
- 准入通用闸：pairing 配对码让陌生用户经主人批准进入，免手工抄 ID。
- 战略价值：agent 入驻国民级 IM + 国产模型 + 国产部署 = 全栈国产 agent 路径；平台宽度直接放大外循环供血。
下一章升级战斗编制：从单 agent 到军团——delegate 委派、subagent 生命周期、父子预算与验证引擎。