wechat-binding

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

📱 WeChat Binding

📱 微信绑定

Connect / reconnect / disconnect the user's WeChat account so the agent can push messages via

send_to_wechat

The

wechat

tool stays built-in. This SKILL.md is the reference doc.

连接/重新连接/断开用户的微信账号，以便Agent可以通过

send_to_wechat

推送消息。

wechat

工具为内置工具，本文档为该技能的参考文档。

Typical binding flow

典型绑定流程

qrcode → user scans → qrcode_status(qrcode=...) → connect(bot_token=...)

Generate QR:
```
wechat(action="qrcode")
```
— saves an image to workspace, returns
```
qrcode
```
(id) +
```
file_path
```
.
Show the QR to the user. On web channel: include the
```
file_path
```
so the frontend renders the image. On TG/WeChat channel: send the image via
```
send_to_telegram
```
with the
```
file_path
```
.
Wait for the user to scan + confirm in WeChat. Don't auto-poll — let them say "scanned" / "done" first.

Poll for completion:

wechat(action="qrcode_status", qrcode=<id from step 1>)

. Returns

bot_token

once scan + confirm completes.

Connect:

wechat(action="connect", bot_token=<from step 4>)

. Optional:

ilink_bot_id

ilink_user_id

if the user has multiple WeChat accounts.

Confirm to user: "WeChat connected. You can now push messages with send_to_wechat."

qrcode → 用户扫码 → qrcode_status(qrcode=...) → connect(bot_token=...)

生成二维码：
```
wechat(action="qrcode")
```
—— 将图片保存至工作区，返回
```
qrcode
```
（ID）和
```
file_path
```
。
向用户展示二维码：在Web渠道中，回复内容包含
```
file_path
```
，由前端渲染图片；在Telegram/微信渠道中，通过
```
send_to_telegram
```
传入
```
file_path
```
发送图片。
等待用户扫码并在微信中确认：不要自动轮询，等待用户发送“已扫码”/“完成”等确认信息。
轮询完成状态：
```
wechat(action="qrcode_status", qrcode=<步骤1中的ID>)
```
。当用户完成扫码和确认后，返回
```
bot_token
```
。
完成连接：
```
wechat(action="connect", bot_token=<步骤4返回值>)
```
。可选参数：若用户有多个微信账号，可传入
```
ilink_bot_id
```
、
```
ilink_user_id
```
。
向用户确认： “微信已连接。现在你可以使用send_to_wechat推送消息。”

Actions

操作列表

action	required	purpose
`status`	—	Current WeChat connection state. Use before reconnect, to verify binding.
`qrcode`	—	Generate QR code image (saved to workspace). Returns `qrcode` id + `file_path` .
`qrcode_status`	`qrcode`	Poll whether user has scanned + confirmed. Returns `bot_token` on success.
`connect`	`bot_token`	Complete a NEW WeChat connection (after first-ever QR scan). Optional: `ilink_bot_id` , `ilink_user_id` .
`disconnect`	—	Terminate current WeChat session (unlink).
`reconnect`	`bot_token`	Re-establish a previously-bound WeChat (token from a fresh QR scan).

action	必填项	用途
`status`	—	当前微信连接状态。重新连接前使用，用于验证绑定状态。
`qrcode`	—	生成二维码图片（保存至工作区）。返回 `qrcode` ID和 `file_path` 。
`qrcode_status`	`qrcode`	轮询用户是否已扫码并确认。成功时返回 `bot_token` 。
`connect`	`bot_token`	完成首次微信连接（首次扫码后）。可选参数： `ilink_bot_id` 、 `ilink_user_id` 。
`disconnect`	—	终止当前微信会话（解绑）。
`reconnect`	`bot_token`	重新建立之前绑定过的微信连接（需通过新扫码获取token）。

connect vs. reconnect

connect与reconnect的区别

connect
— first-time binding. The user has NEVER bound this WeChat before.
reconnect
— the user was previously connected, the connection dropped (e.g. ilink session expired), and they just scanned a fresh QR.

When in doubt, call

status

first:

```
connected: false
```
+ no prior history →
```
connect
```
```
connected: false
```
+ prior history exists →
```
reconnect
```

connect
—— 首次绑定。用户从未绑定过该微信账号。
reconnect
—— 用户之前已连接过，但连接已中断（如ilink会话过期），且刚完成新的扫码操作。

不确定时，先调用

status

：

```
connected: false
```
+ 无绑定历史 → 使用
```
connect
```
```
connected: false
```
+ 存在绑定历史 → 使用
```
reconnect
```

Channel-aware QR display

适配不同渠道的二维码展示方式

User channel	How to show the QR
Web	Include `file_path` in your reply — frontend renders it inline
Telegram	`send_to_telegram(file_path=<qr_path>, message_type="photo")`
WeChat	(You can't — they're trying to bind WeChat in the first place. Tell them to open the web app.)

用户渠道	二维码展示方式
Web	在回复中包含 `file_path` ——前端会将其内嵌渲染
Telegram	`send_to_telegram(file_path=<qr_path>, message_type="photo")`
WeChat	（无法展示——用户本身就是要绑定微信，告知用户打开Web应用操作）

Critical rules

重要规则

Don't auto-poll
```
qrcode_status
```
after
```
qrcode
```
. Wait for user confirmation that they scanned + confirmed in WeChat. Auto-polling spams the upstream API.
Each
qrcode
call generates a fresh image. Don't re-use an old
```
qrcode
```
id with a new image — the upstream session is tied to the id.
Never paste
bot_token
in chat. It's a credential. Once you have it from
```
qrcode_status
```
, immediately pass it to
```
connect
```
/
```
reconnect
```
and don't echo it back to the user.
disconnect
is destructive — confirm with the user before calling it.

生成二维码后不要自动轮询
qrcode_status
：等待用户确认已在微信中扫码并完成授权。自动轮询会对上游API造成请求轰炸。
每次调用
qrcode
都会生成新的图片：不要将旧的
```
qrcode
```
ID与新图片复用——上游会话与ID绑定。
切勿在聊天中粘贴
bot_token
：这是敏感凭证。从
```
qrcode_status
```
获取后，立即传入
```
connect
```
/
```
reconnect
```
，不要回显给用户。
disconnect
操作具有破坏性：调用前需向用户确认。