微信 iLink Bot SDK — 让任何 Agent 5 分钟接入微信消息。
- 扫码登录，凭证自动保存
- 长轮询收消息，HTTP 发消息
- context_token 自动管理，开发者无需关心
- Typing 状态（"对方正在输入中"）
- Session 过期自动重登录
- 零配置，零 Webhook，纯本地运行
npm install @pinixai/weixin-botimport { WeixinBot } from '@pinixai/weixin-bot'
const bot = new WeixinBot()
await bot.login()
bot.onMessage(async (msg) => {
await bot.sendTyping(msg.userId)
await bot.reply(msg, `Echo: ${msg.text}`)
})
await bot.run()pip install weixin-bot-sdkfrom weixin_bot import WeixinBot
bot = WeixinBot()
bot.login()
@bot.on_message
async def handle(msg):
await bot.send_typing(msg.user_id)
await bot.reply(msg, f"Echo: {msg.text}")
bot.run()sequenceDiagram
participant Agent as 你的 Agent
participant SDK as weixin-bot SDK
participant API as iLink Bot API
participant User as 微信用户
Note over Agent,User: 1. 登录
Agent->>SDK: bot.login()
SDK->>API: GET /get_bot_qrcode?bot_type=3
API-->>SDK: 二维码 URL
SDK-->>Agent: 终端显示二维码
User->>API: 微信扫码确认
API-->>SDK: bot_token + baseurl
SDK-->>Agent: 登录成功，凭证已保存
Note over Agent,User: 2. 收发消息循环
Agent->>SDK: bot.run()
loop 长轮询
SDK->>API: POST /getupdates (hold ≤35s)
User->>API: 发消息 "你好"
API-->>SDK: 消息 + context_token
SDK-->>Agent: onMessage(msg)
Agent->>SDK: bot.sendTyping(userId)
SDK->>API: POST /sendtyping
Note over User: 显示"对方正在输入中"
Agent->>SDK: bot.reply(msg, "Echo: 你好")
SDK->>API: POST /sendmessage (带 context_token)
API-->>User: 推送回复
SDK->>API: POST /sendtyping (取消)
end
| 方法 | 说明 |
|---|---|
login(force?) |
扫码登录，已有凭证则自动跳过 |
onMessage(handler) |
注册消息处理回调 |
reply(msg, text) |
回复消息（自动取消 typing） |
send(userId, text) |
主动发消息（需已有 context_token） |
sendTyping(userId) |
显示"对方正在输入中" |
stopTyping(userId) |
取消输入状态 |
run() |
启动长轮询循环 |
stop() |
停止 |
完整的微信 iLink Bot API 协议分析见 docs/protocol-spec.md（1200+ 行，含 curl 示例和 mermaid 时序图）。
| 发现 | 结论 |
|---|---|
context_token |
回复时必须原样传回，否则消息无法投递。SDK 内部自动管理 |
message_state: GENERATING |
API 层面可用，但微信客户端不渲染气泡更新。不建议使用 |
sendtyping |
唯一能触发"对方正在输入中"的方式 |
Session 过期 (errcode: -14) |
需要重新扫码登录。SDK 自动处理 |
- Node.js Echo Bot — 完整示例，含日志和 typing
- Node.js 流式测试 — GENERATING vs FINISH 测试
- Node.js Typing 测试 — sendtyping vs GENERATING 对比
| 包 | 安装 | 状态 |
|---|---|---|
| @pinixai/weixin-bot | npm install @pinixai/weixin-bot |
 |
| weixin-bot-sdk | pip install weixin-bot-sdk |
 |
MIT