wechat-binding

📱 微信绑定

连接／重新连接／断开用户的微信账号，让 Agent 可以通过 send_to_wechat 推送消息。

wechat 工具仍为内置工具。本文档是此技能的参考文档。

另请参阅

• config/context/references/messaging-channels.md — 绑定后如何实际发送消息
• skills/tg-bot-binding/SKILL.md — 类似的 Telegram 流程

---

典型绑定流程

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

1. 生成二维码： wechat(action="qrcode") — 将图片保存到工作区，并返回 qrcode（ID）和 file_path。
2. 向用户展示二维码。 在 Web 渠道中：附上 file_path，以便前端渲染图片。在 TG／微信渠道中：通过 send_to_telegram 使用 file_path 发送图片。
3. 等待用户扫码并在微信中确认。 不要自动轮询——先等用户说“已扫码”／“完成”。
4. 轮询完成状态： wechat(action="qrcode_status", qrcode=<id from step 1>)。扫码并确认完成后会返回 bot_token。
5. 连接： wechat(action="connect", bot_token=<from step 4>)。如果用户有多个微信账号，可选传入 ilink_bot_id、ilink_user_id。
6. 向用户确认：“微信已连接。现在可以使用 send_to_wechat 推送消息。”

---

操作

操作	必填	用途
status	—	当前微信连接状态。在重新连接前使用，以确认绑定状态。
qrcode	—	生成二维码图片（保存到工作区）。返回 qrcode ID 和 file_path。
qrcode_status	qrcode	轮询用户是否已扫码并确认。成功后返回 bot_token。
connect	bot_token	完成新的微信连接（首次扫码后）。可选参数：ilink_bot_id、ilink_user_id。
disconnect	—	结束当前微信会话（解除绑定）。
reconnect	bot_token	重新建立之前绑定的微信连接（使用新扫码生成的令牌）。

---

connect 与 reconnect 的区别

• connect — 首次绑定。用户之前从未绑定过此微信。
• reconnect — 用户之前已连接，但连接已断开（例如 ilink 会话过期），现在刚刚扫描了新的二维码。

不确定时，先调用 status：

• connected: false 且没有历史记录 → connect
• connected: false 且有历史记录 → reconnect

---

根据渠道展示二维码

用户渠道	如何展示二维码
Web	在回复中附上 file_path — 前端会在页面内渲染
Telegram	send_to_telegram(file_path=<qr_path>, message_type="photo")
微信	（无法通过此渠道展示——用户此时正要绑定微信。请告知用户打开 Web 应用。）

---

重要规则

• 不要自动轮询 qrcode_status。调用 qrcode 后，等待用户确认已在微信中扫码并完成确认。自动轮询会给上游 API 发送大量请求。
• 每次调用 qrcode 都会生成一张新图片。 不要将旧的 qrcode ID 与新图片重复使用——上游会话与该 ID 绑定。
• 切勿在聊天中粘贴 bot_token。 它是凭证。从 qrcode_status 获取后，应立即将其传给 connect／reconnect，不要将其发回给用户。
• disconnect 会造成不可逆影响——调用前先征得用户确认。