pure-wechatbot

精简的微信 iLink Bot 协议客户端，零依赖，TypeScript 实现。

特性

• 零外部依赖，仅使用 Node.js 内置模块
• 长轮询消息接收（含错误退避、session expired 处理）
• 发送文本 / 图片消息
• QR 扫码登录
• 打字指示器
• 图片下载（AES-128-ECB 解密）
• 兼容 iLink API v2.1+（upload_full_url + upload_param 双格式）

安装

npm install pure-wechatbot

要求 Node.js ≥ 18（使用原生 fetch）。

快速开始

import { WeChatClient } from 'pure-wechatbot'

const bot = new WeChatClient()

// 监听消息
bot.on('message', async (msg) => {
  const text = WeChatClient.extractText(msg)
  if (!text || !msg.from_user_id) return

  console.log(`收到消息: ${text}`)

  // 发送回复
  await bot.sendText(msg.from_user_id, `你说的是: ${text}`)
})

// QR 扫码登录 → 启动轮询
const result = await bot.login({
  onQRCode: (img) => console.log('请扫描二维码:', img),
})

if (result.connected) {
  console.log('登录成功:', result.accountId)
  await bot.start() // 阻塞，直到 stop()
}

API

WeChatClient

| 方法 | 说明 | |------|------| | login(opts?) | QR 扫码登录，返回 LoginResult | | start(opts?) | 启动长轮询（阻塞） | | stop() | 停止长轮询 | | sendText(to, text) | 发送文本 | | sendImage(to, filePath, caption?) | 上传图片并发送 | | sendTyping(userId, status?) | 发送打字指示器（自动获取 ticket） | | downloadMedia(item) | 下载并解密入站媒体 | | extractText(msg) | (静态) 提取消息文本 | | isMediaItem(item) | (静态) 判断消息项是否为媒体类型 | | accountId | (getter) 当前账号 ID |

事件

| 事件 | 参数 | 说明 | |------|------|------| | message | WeixinMessage | 收到新消息 | | error | Error | 轮询或网络错误 | | sessionExpired | — | session 过期 |

完整示例

见 examples/demo.ts，覆盖所有 API：登录、收消息、发文本/图片、下载媒体、打字指示器、优雅退出。

上游来源

协议逆向自腾讯官方项目 Tencent/openclaw-weixin。

与 photon-hq/wechat-ilink-client 相比：

• 修复了 getUploadUrl 不兼容 upload_full_url 的问题
• 更精简（~710 行 vs ~1064 行）
• 零依赖

关于流式输出

iLink 协议不支持真正的流式消息（即同一条消息逐字追加）。上游的"streaming"实现是分块发送多条独立消息，本质上就是多次调用 sendText。如需逐段输出，直接循环调用 sendText 即可，无需额外的流式抽象。

构建

npm run build      # TypeScript → dist/
npm run typecheck  # 类型检查

License

MIT

相关项目

| 项目 | 说明 | |------|------| | pure-wechatbot | 微信 iLink Bot 协议客户端（本库） | | pure-qqbot | QQ Bot 协议客户端 | | open-health-agent | 基于 pure-wechatbot 的健康助手 |