WeChatBot 的 context_token 全解:跨重启持久化的微信消息路由机制
WeChatBot 的 context_token 全解:跨重启持久化的微信消息路由机制
WeChatBot 是一款支持 Node.js、Python、Go、Rust 四种语言的微信 iLink Bot SDK,其消息路由的核心就是一串名为 context_token 的令牌。它决定了你的 Bot 发出的每一条消息能否准确落到正确的会话里。本文带你完整拆解 context_token 的获取、缓存、注入与跨重启持久化全流程,并附上常见坑点。
context_token 是什么?微信消息路由的第一把钥匙
在 iLink 协议中,context_token 是服务端用来将会话与消息绑定的路由凭据。它由用户发来的每一条消息携带,而你的 Bot 回复时必须把它原样带回:
每次回复都必须包含来自入站消息的
context_token,它负责将消息路由到正确的会话。—— 协议文档原文
简单理解:用户发来的消息里带着一张"回邮地址",你的 Bot 回复时贴回这张地址,服务端才知道该把消息投给哪个对话。相关协议定义见 docs/protocol.md。
如果没有这张"地址"会发生什么?发送会直接失败,各 SDK 都会抛出明确错误(后文详解)。
生命周期:三个阶段全自动,零手动处理
WeChatBot 四套 SDK 遵循同一套设计,把 context_token 的管理完全自动化。整体流程在架构文档 docs/architecture.md 中有清晰描述:
1️⃣ 收消息时自动捕获
长轮询循环每收到一批消息,SDK 会先执行"记忆"动作——从每条消息中抽取 userId 和 context_token 写入内存缓存。Node.js 侧的实现非常直观,在 nodejs/src/messaging/context.ts 中:
/** 从线上消息中提取并缓存 context_token */
remember(message: WireMessage): void {
const userId = ...
if (userId && message.context_token) {
this.set(userId, message.context_token)
}
}
调用时机在 nodejs/src/core/client.ts 的消息分发管道里——即使消息最终被过滤,token 也一定先被记住,这是"先缓存、后处理"的防御性设计。
2️⃣ 发消息时自动注入
SDK 把发送分成两个入口,对应两种典型场景:
| 方法 | 场景 | token 来源 |
|---|---|---|
bot.reply(msg, content) |
回复刚刚收到的消息 | 直接用消息自带的 token |
bot.send(userId, content) |
主动推送给某个用户 | 从缓存中按 userId 查找 |
以 send 为例(nodejs/src/core/client.ts):
async send(userId: string, content: SendContent): Promise<void> {
const ctx = this.contextStore.get(userId)
if (!ctx) throw new NoContextError(userId)
await this.sendContent(userId, ctx, content)
}
注意一个细节:长文本分片时所有分片共享同一个 context_token,只是每片拥有独立的 client_id,保证整段消息在服务端仍是同一会话。另外,"对方正在输入中"指示条同样依赖 token 换取 ticket,所以主动 sendTyping 也需要用户先给 Bot 发过消息。
3️⃣ 会话过期时一键清空
当服务端返回 errcode: -14(会话过期)触发重新登录后,旧凭据下的 token 全部作废,SDK 会主动清空缓存防止误用:
- Node.js:
contextStore.clear()同时清除内存与磁盘(client.ts) - Go:
b.contextTokens = sync.Map{}整体重置(golang/bot.go) - Rust:
*self.context_tokens.write().await = HashMap::new()(rust/src/bot.rs) - Python:
self._context_tokens.clear()(python/wechatbot/client.py)
这是"宁可重收、不可误用"的可靠性设计。
跨重启持久化:Node.js 的独门绝技
这是 context_token 机制中最值得称道的部分。Bot 重启后如果丢失缓存,就得等用户重新发消息才能回复——对需要主动推送(如定时通知)的 Bot 来说几乎不可用。
Node.js SDK 是唯一提供磁盘持久化的实现,采用"内存 + 磁盘"双层策略(docs/architecture.md):
| 阶段 | 动作 | 代码位置 |
|---|---|---|
| 每批消息处理完 | 脏检查 + flush() 落盘 |
context.ts |
| Bot 停止时 | stop() 触发最后一次 flush() |
client.ts |
下次启动 start() |
load() 恢复全部 token 到内存 |
context.ts |
落盘位置是标准文件存储 ~/.wechatbot/ 下的 JSON 文件(默认目录见 nodejs/src/storage/file.ts),键名固定为 context_tokens(nodejs/src/storage/interface.ts):
{
"wx_user_id_1": "<token_A>",
"wx_user_id_2": "<token_B>"
}
脏标记(dirty)机制保证没有变化就不写盘,避免无谓 IO。由于存储层是可插拔接口,你还可以把 context_token 持久化到 Redis、PostgreSQL 等自定义后端——这对多租户部署(同一进程跑多个微信账号、每个账号独立存储命名空间)尤为关键。
各语言 SDK 对比一览:
| SDK | 内存缓存 | 跨重启持久化 | 实现 |
|---|---|---|---|
| Node.js | ✅ Map | ✅ 文件/自定义存储 | ContextStore |
| Python | ✅ dict | ❌ | client.py |
| Go | ✅ sync.Map | ❌ | bot.go |
| Rust | ✅ RwLock |
❌ | bot.rs |
常见坑点:三种"丢"掉 context_token 的场景
场景一:用户还没发过消息就主动推送
最常见的报错。四种语言的错误信息都很直白:
No context_token cached for user xxx. A message from this user must be received first.
(Node.js,定义于 nodejs/src/core/errors.ts)
解法:让目标用户先给 Bot 发任意一条消息,或依赖持久化缓存中已有的 token。
场景二:重启后 Python/Go/Rust Bot "失忆"
这三套 SDK 的 token 缓存只存在于内存中,重启即清空。如果业务强依赖主动推送,建议选 Node.js SDK,或自行把缓存层接到数据库。
场景三:重新扫码登录导致 token 全部失效
Node.js 中当登录 token 发生变化时(client.ts),会判定旧缓存为"脏数据"并整体清除——这是正确的行为,因为旧凭据下的 context_token 已被服务端作废。此时必须等用户重新发消息刷新。
文件导航 📁
| 文件 | 说明 |
|---|---|
| docs/protocol.md | context_token 协议级要求(必带、按用户缓存、持久化、过期清空) |
| docs/architecture.md | 四 SDK 共享的 context_token 概念 |
| nodejs/src/messaging/context.ts | ContextStore:记忆、缓存、落盘、清空 |
| nodejs/src/core/client.ts | 消息管道中 token 的捕获与批量持久化 |
| nodejs/src/messaging/sender.ts | 发送时 token 解析与文本分片 |
| nodejs/src/storage/interface.ts | 存储键常量(含 context_tokens) |
| golang/bot.go | Go 版内存缓存与缺失报错 |
| rust/src/bot.rs | Rust 版缓存读写 |
| python/wechatbot/client.py | Python 版缓存与注入 |
一句话总结:context_token 是 WeChatBot 消息路由的命脉——收消息自动记、发消息自动带、会话过期自动清;而 Node.js 版更把它写进磁盘,让 Bot 重启后依然能主动开口,这才是生产级 Bot 该有的样子。