144 lines
4.1 KiB
Markdown
144 lines
4.1 KiB
Markdown
---
|
||
title: "epiral/weixin-bot: WeChat iLink Bot SDK for Node.js and Python — zero-config agent integration"
|
||
source: "https://github.com/epiral/weixin-bot/blob/main/README.md"
|
||
author:
|
||
- "[[GitHub]]"
|
||
published:
|
||
created: 2026-03-28
|
||
description: "WeChat iLink Bot SDK for Node.js and Python — zero-config agent integration - epiral/weixin-bot"
|
||
tags:
|
||
- "clippings"
|
||
---
|
||
## weixin-bot
|
||
|
||
微信 iLink Bot SDK — 让任何 Agent 5 分钟接入微信消息。
|
||
|
||
## 特性
|
||
|
||
- 扫码登录,凭证自动保存
|
||
- 长轮询收消息,HTTP 发消息
|
||
- context\_token 自动管理,开发者无需关心
|
||
- Typing 状态("对方正在输入中")
|
||
- Session 过期自动重登录
|
||
- 零配置,零 Webhook,纯本地运行
|
||
|
||
## 快速开始
|
||
|
||
### Node.js
|
||
|
||
```
|
||
npm install @pinixai/weixin-bot
|
||
```
|
||
```
|
||
import { 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()
|
||
```
|
||
|
||
### Python
|
||
|
||
```
|
||
pip install weixin-bot-sdk
|
||
```
|
||
```
|
||
from 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
|
||
```
|
||
|
||
## API
|
||
|
||
| 方法 | 说明 |
|
||
| --- | --- |
|
||
| `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](https://github.com/epiral/weixin-bot/blob/main/docs/protocol-spec.md) (1200+ 行,含 curl 示例和 mermaid 时序图)。
|
||
|
||
## 关键协议发现
|
||
|
||
| 发现 | 结论 |
|
||
| --- | --- |
|
||
| `context_token` | 回复时必须原样传回,否则消息无法投递。SDK 内部自动管理 |
|
||
| `message_state: GENERATING` | API 层面可用,但微信客户端不渲染气泡更新。不建议使用 |
|
||
| `sendtyping` | 唯一能触发"对方正在输入中"的方式 |
|
||
| Session 过期 (`errcode: -14`) | 需要重新扫码登录。SDK 自动处理 |
|
||
|
||
## 示例
|
||
|
||
- [Node.js Echo Bot](https://github.com/epiral/weixin-bot/blob/main/examples/nodejs/echo-bot.ts) — 完整示例,含日志和 typing
|
||
- [Node.js 流式测试](https://github.com/epiral/weixin-bot/blob/main/examples/nodejs/stream-test.ts) — GENERATING vs FINISH 测试
|
||
- [Node.js Typing 测试](https://github.com/epiral/weixin-bot/blob/main/examples/nodejs/generating-test.ts) — sendtyping vs GENERATING 对比
|
||
|
||
## 包
|
||
|
||
| 包 | 安装 | 状态 |
|
||
| --- | --- | --- |
|
||
| [@pinixai/weixin-bot](https://github.com/epiral/weixin-bot/blob/main/nodejs) | `npm install @pinixai/weixin-bot` | |
|
||
| [weixin-bot-sdk](https://github.com/epiral/weixin-bot/blob/main/python) | `pip install weixin-bot-sdk` | |
|
||
|
||
## License
|
||
|
||
MIT |