WeChatBot 的 context_token 全解:跨重启持久化的微信消息路由机制

原创2026-11-03 18:17:351,963 阅读

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 的独门绝技

这是 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 该有的样子。

登录后查看全文
wechatbot