docs: weixin ClawBot bridge protocol and examples
This commit is contained in:
AskaEth committed
commit
4ea3957da9
13 files changed
+2158
No files matched your search
@@ -0,0 +1,358 @@
|
||||
# 05 — 实现指南与代码骨架
|
||||
|
||||
> 给出两个可直接改造的最小实现骨架：Node.js（零依赖，官方 demo 的整理版）和 Python（requests 版）。
|
||||
> 均已按本文档的可靠性建议补强（游标持久化、退避、-14 处理）。媒体收发先略，接入文本跑通后再按 03 文档加。
|
||||
|
||||
## 1. 最小流程回顾
|
||||
|
||||
```
|
||||
1. 扫码拿 bot_token（一次性） ← auth
|
||||
2. loop: ← poller
|
||||
resp = POST getupdates(cursor)
|
||||
保存新 cursor
|
||||
for msg in resp.msgs:
|
||||
text = msg.item_list[*].text_item.text
|
||||
reply = 你的AI后端(text) ← backend
|
||||
POST sendmessage(reply, msg.context_token)
|
||||
```
|
||||
|
||||
## 2. Node.js 骨架（bridge.mjs）
|
||||
|
||||
零第三方依赖（Node 18+ 自带 fetch）。二维码展示可加装 `qrcode-terminal`。
|
||||
|
||||
```js
|
||||
// bridge.mjs — 微信 ClawBot iLink Bridge 最小骨架
|
||||
import { readFileSync, writeFileSync, existsSync } from "node:fs";
|
||||
import { randomBytes } from "node:crypto";
|
||||
|
||||
const BASE_URL = "https://ilinkai.weixin.qq.com";
|
||||
const STATE_FILE = "./bridge-state.json";
|
||||
|
||||
// ---------- 状态持久化 ----------
|
||||
const state = existsSync(STATE_FILE)
|
||||
? JSON.parse(readFileSync(STATE_FILE, "utf8"))
|
||||
: { bot_token: null, cursor: "", contexts: {} };
|
||||
|
||||
const saveState = () =>
|
||||
writeFileSync(STATE_FILE, JSON.stringify(state, null, 2), { mode: 0o600 });
|
||||
|
||||
// ---------- iLink HTTP 封装 ----------
|
||||
function headers() {
|
||||
const uin = Buffer.from(String(randomBytes(4).readUInt32BE(0))).toString("base64");
|
||||
return {
|
||||
"Content-Type": "application/json",
|
||||
AuthorizationType: "ilink_bot_token",
|
||||
"X-WECHAT-UIN": uin,
|
||||
...(state.bot_token ? { Authorization: `Bearer ${state.bot_token}` } : {}),
|
||||
};
|
||||
}
|
||||
|
||||
async function apiPost(path, body, timeoutMs = 45_000) {
|
||||
const res = await fetch(`${BASE_URL}${path}`, {
|
||||
method: "POST",
|
||||
headers: headers(),
|
||||
body: JSON.stringify(body),
|
||||
signal: AbortSignal.timeout(timeoutMs),
|
||||
});
|
||||
return res.json();
|
||||
}
|
||||
|
||||
// ---------- 1. 扫码登录（一次性） ----------
|
||||
async function login() {
|
||||
const qr = await fetch(`${BASE_URL}/ilink/bot/get_bot_qrcode?bot_type=3`)
|
||||
.then((r) => r.json());
|
||||
console.log("请用微信扫码:", qr.qrcode_img_content);
|
||||
// 终端显示二维码: npm i qrcode-terminal，然后 qrcode.generate(qr.qrcode_img_content, {small:true})
|
||||
|
||||
const deadline = Date.now() + 8 * 60_000;
|
||||
while (Date.now() < deadline) {
|
||||
const s = await fetch(
|
||||
`${BASE_URL}/ilink/bot/get_qrcode_status?qrcode=${encodeURIComponent(qr.qrcode)}`,
|
||||
{ headers: { "iLink-App-ClientVersion": "1" } }
|
||||
).then((r) => r.json());
|
||||
|
||||
if (s.status === "confirmed") {
|
||||
state.bot_token = s.bot_token;
|
||||
state.bot_id = s.ilink_bot_id;
|
||||
state.owner_id = s.ilink_user_id;
|
||||
saveState();
|
||||
console.log("登录成功, bot:", s.ilink_bot_id);
|
||||
return;
|
||||
}
|
||||
process.stdout.write(`\r等待扫码... status=${s.status} `);
|
||||
await new Promise((r) => setTimeout(r, 1000));
|
||||
}
|
||||
throw new Error("扫码超时，请重试");
|
||||
}
|
||||
|
||||
// ---------- 2. AI 后端调用（换成你的项目） ----------
|
||||
async function askYourAI(peerId, text) {
|
||||
// 例：调本地 HTTP 后端
|
||||
// const r = await fetch("http://127.0.0.1:8000/chat", {
|
||||
// method: "POST",
|
||||
// headers: { "Content-Type": "application/json" },
|
||||
// body: JSON.stringify({ session_id: peerId, text }),
|
||||
// }).then(r => r.json());
|
||||
// return r.reply;
|
||||
return `你说的是：${text}`; // 回声占位
|
||||
}
|
||||
|
||||
// ---------- 3. 发送回复 ----------
|
||||
async function sendText(toUserId, text, contextToken) {
|
||||
// 长文本简单分片
|
||||
for (let i = 0; i < text.length; i += 1500) {
|
||||
await apiPost("/ilink/bot/sendmessage", {
|
||||
msg: {
|
||||
to_user_id: toUserId,
|
||||
client_id: crypto.randomUUID(),
|
||||
message_type: 2, // bot 消息
|
||||
message_state: 2, // FINISH
|
||||
context_token: contextToken,
|
||||
item_list: [{ type: 1, text_item: { text: text.slice(i, i + 1500) } }],
|
||||
},
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
// ---------- 4. 长轮询主循环 ----------
|
||||
async function pollLoop() {
|
||||
let failures = 0;
|
||||
for (;;) {
|
||||
try {
|
||||
const resp = await apiPost("/ilink/bot/getupdates", {
|
||||
get_updates_buf: state.cursor,
|
||||
base_info: { channel_version: "1.0.2" },
|
||||
});
|
||||
|
||||
if (resp.errcode === -14) {
|
||||
console.error("会话过期(errcode=-14)，请删除 state 文件重新扫码");
|
||||
process.exit(2);
|
||||
}
|
||||
if (resp.ret !== 0 && resp.errcode !== undefined) {
|
||||
throw new Error(`getupdates 错误: ${JSON.stringify(resp)}`);
|
||||
}
|
||||
|
||||
if (resp.get_updates_buf) {
|
||||
state.cursor = resp.get_updates_buf;
|
||||
saveState(); // 游标立即落盘
|
||||
}
|
||||
|
||||
for (const msg of resp.msgs ?? []) {
|
||||
if (msg.message_type !== 1) continue; // 只处理用户消息
|
||||
const text = (msg.item_list ?? [])
|
||||
.filter((it) => it.type === 1)
|
||||
.map((it) => it.text_item?.text ?? "")
|
||||
.join("\n")
|
||||
.trim();
|
||||
if (!text) continue; // 媒体消息此处略，按 03 文档扩展
|
||||
|
||||
state.contexts[msg.from_user_id] = msg.context_token;
|
||||
saveState();
|
||||
|
||||
try {
|
||||
const reply = await askYourAI(msg.from_user_id, text);
|
||||
await sendText(msg.from_user_id, reply, msg.context_token);
|
||||
} catch (e) {
|
||||
console.error("处理消息失败:", e);
|
||||
await sendText(msg.from_user_id, "处理时出错了，请重试", msg.context_token)
|
||||
.catch(() => {});
|
||||
}
|
||||
}
|
||||
failures = 0;
|
||||
} catch (e) {
|
||||
// AbortError(长轮询超时) 视为正常，直接下一轮
|
||||
if (e.name === "TimeoutError" || e.name === "AbortError") continue;
|
||||
failures++;
|
||||
const wait = failures <= 3 ? 2000 : 30_000;
|
||||
console.error(`轮询异常(${failures}次)，${wait / 1000}s 后重试:`, e.message);
|
||||
await new Promise((r) => setTimeout(r, wait));
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// ---------- main ----------
|
||||
if (!state.bot_token) await login();
|
||||
await pollLoop();
|
||||
```
|
||||
|
||||
运行：
|
||||
|
||||
```bash
|
||||
node bridge.mjs # 首次会打印二维码链接，微信扫码确认
|
||||
```
|
||||
|
||||
## 3. Python 骨架（bridge.py）
|
||||
|
||||
依赖只有 `requests`。二维码展示可加装 `qrcode` + 终端渲染。
|
||||
|
||||
```python
|
||||
# bridge.py — 微信 ClawBot iLink Bridge 最小骨架
|
||||
import json, os, time, uuid, base64, random, requests
|
||||
|
||||
BASE_URL = "https://ilinkai.weixin.qq.com"
|
||||
STATE_FILE = "./bridge-state.json"
|
||||
|
||||
# ---------- 状态持久化 ----------
|
||||
state = {"bot_token": None, "cursor": "", "contexts": {}}
|
||||
if os.path.exists(STATE_FILE):
|
||||
state.update(json.load(open(STATE_FILE)))
|
||||
|
||||
def save_state():
|
||||
with open(STATE_FILE, "w") as f:
|
||||
json.dump(state, f, indent=2)
|
||||
os.chmod(STATE_FILE, 0o600)
|
||||
|
||||
# ---------- iLink HTTP 封装 ----------
|
||||
def headers():
|
||||
h = {
|
||||
"Content-Type": "application/json",
|
||||
"AuthorizationType": "ilink_bot_token",
|
||||
"X-WECHAT-UIN": base64.b64encode(str(random.getrandbits(32)).encode()).decode(),
|
||||
}
|
||||
if state["bot_token"]:
|
||||
h["Authorization"] = f"Bearer {state['bot_token']}"
|
||||
return h
|
||||
|
||||
def api_post(path, body, timeout=45):
|
||||
r = requests.post(BASE_URL + path, headers=headers(), json=body, timeout=timeout)
|
||||
return r.json()
|
||||
|
||||
# ---------- 1. 扫码登录（一次性） ----------
|
||||
def login():
|
||||
qr = requests.get(f"{BASE_URL}/ilink/bot/get_bot_qrcode?bot_type=3").json()
|
||||
print("请用微信扫码:", qr["qrcode_img_content"])
|
||||
deadline = time.time() + 8 * 60
|
||||
while time.time() < deadline:
|
||||
s = requests.get(
|
||||
f"{BASE_URL}/ilink/bot/get_qrcode_status",
|
||||
params={"qrcode": qr["qrcode"]},
|
||||
headers={"iLink-App-ClientVersion": "1"},
|
||||
).json()
|
||||
if s.get("status") == "confirmed":
|
||||
state.update(bot_token=s["bot_token"], bot_id=s["ilink_bot_id"],
|
||||
owner_id=s["ilink_user_id"])
|
||||
save_state()
|
||||
print("登录成功, bot:", s["ilink_bot_id"])
|
||||
return
|
||||
time.sleep(1)
|
||||
raise RuntimeError("扫码超时")
|
||||
|
||||
# ---------- 2. AI 后端调用（换成你的项目） ----------
|
||||
def ask_your_ai(peer_id: str, text: str) -> str:
|
||||
# r = requests.post("http://127.0.0.1:8000/chat",
|
||||
# json={"session_id": peer_id, "text": text}).json()
|
||||
# return r["reply"]
|
||||
return f"你说的是：{text}"
|
||||
|
||||
# ---------- 3. 发送回复 ----------
|
||||
def send_text(to_user_id, text, context_token):
|
||||
for i in range(0, len(text), 1500):
|
||||
api_post("/ilink/bot/sendmessage", {
|
||||
"msg": {
|
||||
"to_user_id": to_user_id,
|
||||
"client_id": str(uuid.uuid4()),
|
||||
"message_type": 2,
|
||||
"message_state": 2,
|
||||
"context_token": context_token,
|
||||
"item_list": [{"type": 1, "text_item": {"text": text[i:i+1500]}}],
|
||||
}
|
||||
})
|
||||
|
||||
# ---------- 4. 长轮询主循环 ----------
|
||||
def poll_loop():
|
||||
failures = 0
|
||||
while True:
|
||||
try:
|
||||
resp = api_post("/ilink/bot/getupdates", {
|
||||
"get_updates_buf": state["cursor"],
|
||||
"base_info": {"channel_version": "1.0.2"},
|
||||
})
|
||||
if resp.get("errcode") == -14:
|
||||
print("会话过期(errcode=-14)，请删除 state 文件重新扫码")
|
||||
raise SystemExit(2)
|
||||
if resp.get("ret", 0) != 0:
|
||||
raise RuntimeError(f"getupdates 错误: {resp}")
|
||||
|
||||
if resp.get("get_updates_buf"):
|
||||
state["cursor"] = resp["get_updates_buf"]
|
||||
save_state()
|
||||
|
||||
for msg in resp.get("msgs") or []:
|
||||
if msg.get("message_type") != 1:
|
||||
continue
|
||||
text = "\n".join(
|
||||
it.get("text_item", {}).get("text", "")
|
||||
for it in msg.get("item_list", []) if it.get("type") == 1
|
||||
).strip()
|
||||
if not text:
|
||||
continue
|
||||
|
||||
state["contexts"][msg["from_user_id"]] = msg["context_token"]
|
||||
save_state()
|
||||
|
||||
try:
|
||||
reply = ask_your_ai(msg["from_user_id"], text)
|
||||
send_text(msg["from_user_id"], reply, msg["context_token"])
|
||||
except Exception as e:
|
||||
print("处理消息失败:", e)
|
||||
try:
|
||||
send_text(msg["from_user_id"], "处理时出错了，请重试",
|
||||
msg["context_token"])
|
||||
except Exception:
|
||||
pass
|
||||
failures = 0
|
||||
except requests.exceptions.Timeout:
|
||||
continue # 长轮询正常超时
|
||||
except Exception as e:
|
||||
failures += 1
|
||||
wait = 2 if failures <= 3 else 30
|
||||
print(f"轮询异常({failures}次)，{wait}s 后重试:", e)
|
||||
time.sleep(wait)
|
||||
|
||||
if __name__ == "__main__":
|
||||
if not state["bot_token"]:
|
||||
login()
|
||||
poll_loop()
|
||||
```
|
||||
|
||||
## 4. 接入你自己 AI 项目的改造点
|
||||
|
||||
只需替换 `askYourAI` / `ask_your_ai` 一个函数：
|
||||
|
||||
| 你的后端形态 | 改法 |
|
||||
|---|---|
|
||||
| HTTP API（FastAPI/Flask/Express…） | 函数里 POST 过去，`session_id` 传 `peer_id` |
|
||||
| OpenAI 兼容接口 | 函数里组 messages 调 chat/completions，历史自己存（JSON/SQLite，按 peer_id 分键） |
|
||||
| LangChain / LangGraph | 函数里调 chain.invoke，memory 用 peer_id 做会话键 |
|
||||
| 本地 Agent 框架（Claude Agent SDK 等） | 参考 [cc-weixin](https://github.com/hao-ji-xing/cc-weixin) 的 `askClaude()` 包装 |
|
||||
| 命令行工具 | `subprocess` 调一下取 stdout（注意超时与转义） |
|
||||
|
||||
## 5. 常见坑（按踩坑频率排序）
|
||||
|
||||
1. **游标没存/存晚了** → 重启后消息重复轰炸。收到响应立刻落盘。
|
||||
2. **回复忘带 `context_token`** → 消息发不出或关联不上对话。
|
||||
3. **HTTP 客户端超时 < 长轮询超时** → 每轮都假性超时。骨架里给了 45s。
|
||||
4. **Markdown 直接发** → 微信不渲染，先转纯文本。
|
||||
5. **只处理 `item_list[0]`** → 图文混排丢内容。
|
||||
6. **token 提交进 git** → 泄漏=bot 被接管。state 文件加 `.gitignore`。
|
||||
7. **消息处理抛异常没兜住** → 整个轮询循环挂掉。骨架里已包 try。
|
||||
8. **多开实例** → 同 token 多处轮询互相抢游标，状态错乱。单实例跑。
|
||||
|
||||
## 6. 下一步扩展路线
|
||||
|
||||
1. 文本收发跑通（本骨架）
|
||||
2. 接入你的 AI 后端 + 会话历史
|
||||
3. 入站图片/语音（CDN 下载 + AES 解密，见 03 文档）
|
||||
4. `sendtyping`（处理慢时提升体验）
|
||||
5. 出站图片/文件（getuploadurl + CDN 上传）
|
||||
6. 白名单、限流、多通道（按 04 文档模式 D 演进）
|
||||
|
||||
## 7. 参考项目清单
|
||||
|
||||
| 项目 | 值得借鉴的部分 |
|
||||
|---|---|
|
||||
| [hao-ji-xing/openclaw-weixin](https://github.com/hao-ji-xing/openclaw-weixin) | `demo.mjs` 裸调最小实现、协议逆向文档 |
|
||||
| [hao-ji-xing/cc-weixin](https://github.com/hao-ji-xing/cc-weixin) | Agent SDK 的接入包装方式 |
|
||||
| [openclaw-java/openclaw-weixin-sdk](https://github.com/openclaw-java/openclaw-weixin-sdk) | 完整工程化：状态存储、退避策略、-14 暂停窗口、typing、媒体服务 |
|
||||
| [openakita/openakita](https://github.com/openakita/openakita) | Python 适配器、多通道网关抽象、媒体惰性下载策略 |
|
||||
| `@tencent-weixin/openclaw-weixin`（npm） | 官方协议实现，字段有疑问时的最终依据：`npm pack @tencent-weixin/openclaw-weixin` |
|
||||
Reference in new issue
Block a user