Files
Obsidian/githubLibs/epiralweixin-bot WeChat iLink Bot SDK for Node.js and Python — zero-config agent integration.md
T
2026-07-21 14:53:24 +08:00

144 lines
4.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
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