Obsidian/GitHub/epiralweixin-bot WeChat iLink Bot SDK for Node.js and Python — zero-config agent integration.md at main - Obsidian

admin/Obsidian

Fork 0

Files

T

coco 8b94d76799 a

2026-07-21 13:57:15 +08:00

4.1 KiB

Raw Permalink Blame History

title, source, author, published, created, description, tags

title

source

author

published

created

description

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 （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`

License

MIT

4.1 KiB Raw Permalink Blame History Unescape Escape