Skip to content
Skills Library
AI & agents · Tool integration

multi-bot-adapter

/multi-bot-adapter

Add or maintain multi-channel chat bot adapters for QQ official Bot and WeChat wxclaw / iLink Bot in an agent framework. Use when integrating a new messaging channel, implementing QR-code login, AppID/ClientSecret or bot token authentication, WebSocket gateway or long-polling intake, text and rich-media send/receive, voice reply, artifact delivery, admin commands, scheduled push, channel status reporting, or debugging protocol errors such as QQBot auth, passive reply msg_id, wxclaw errcode -14, upload_param, AES media encryption, context_token, message dedupe, and content_type detection. 多渠道机器

Licence
Apache-2.0
Last repository change
07.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
14
Scripts
1
HTML comments
0
URLs in SKILL.md
3
Deprecation

No signals detected. Repository changed on 07.11.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What to check before installing
  • 1 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/package_skill.py

What it does and when to use it

Add or maintain multi-channel chat bot adapters for QQ official Bot and WeChat wxclaw / iLink Bot in an agent framework. Use when integrating a new messaging channel, implementing QR-code login, AppID/ClientSecret or bot token authentication, WebSocket gateway or long-polling intake, text and rich-media send/receive, voice reply, artifact delivery, admin commands, scheduled push, channel status reporting, or debugging protocol errors such as QQBot auth, passive reply msg_id, wxclaw errcode -14, upload_param, AES media encryption, context_token, message dedupe, and content_type detection. 多渠道机器

Original author description

Add or maintain multi-channel chat bot adapters for QQ official Bot and WeChat wxclaw / iLink Bot in an agent framework. Use when integrating a new messaging channel, implementing QR-code login, AppID/ClientSecret or bot token authentication, WebSocket gateway or long-polling intake, text and rich-media send/receive, voice reply, artifact delivery, admin commands, scheduled push, channel status reporting, or debugging protocol errors such as QQBot auth, passive reply msg_id, wxclaw errcode -14, upload_param, AES media encryption, context_token, message dedupe, and content_type detection. 多渠道机器

How it works

  1. 何时使用(触发场景)
  2. 核心架构
  3. 适配器契约
  4. 接入流程(照着做)
  5. 两个渠道的关键差异
  6. 必守不变量(上线前逐条核对)
  7. 常见故障速查
  8. 配置参考(最小集)
  9. 测试与验收
  10. 参考文件路由
Original SKILL.md headings · 305 lines, 994 words
SKILL.md preview
---
name: multi-bot-adapter
version: "1.0.0"
author: "bucai2417"
display_name: "多渠道机器人适配器"
display_name_en: "Multi-Bot Adapter"
description: "Add or maintain multi-channel chat bot adapters for QQ official Bot and WeChat wxclaw / iLink Bot in an agent framework. Use when integrating a new messaging channel, implementing QR-code login, AppID/ClientSecret or bot token authentication, WebSocket gateway or long-polling intake, text and rich-media send/receive, voice reply, artifact delivery, admin commands, scheduled push, channel status reporting, or debugging protocol errors such as QQBot auth, passive reply msg_id, wxclaw errcode -14, upload_param, AES media encryption, context_token, message dedupe, and content_type detection. 多渠道机器人适配器:QQ 官方 Bot 与微信 wxclaw/iLink Bot 接入、扫码登录、WebSocket 网关、长轮询、文本/图片/文件/语音收发、渠道管理、管理员命令、定时推送、协议排错。"
description_zh: "多渠道机器人适配器。适用于给 agent 框架接入或维护 QQ 官方 Bot、微信 wxclaw/iLink Bot:扫码登录、AppID+ClientSecret 或 Bot Token 认证、WebSocket 网关与长轮询收消息、文本/图片/文件/语音收发、产物投递、管理员命令、定时推送、渠道状态上报,以及 QQBot 鉴权、被动回复 msg_id、wxclaw errcode -14、upload_param、AES 媒体加密、context_token、消息去重、content_type 判定等协议排错。"
description_en: "Add or maintain multi-channel chat bot adapters for QQ official Bot and WeChat wxclaw / iLink Bot in an agent framework. Use when integrating a new messaging channel, implementing QR-code login, AppID/ClientSecret or bot token authentication, WebSocket gateway or long-polling intake, text and rich-media send/receive, voice reply, artifact delivery, admin commands, scheduled push, channel status reporting, or debugging protocol errors such as QQBot auth, passive reply msg_id, wxclaw errcode -14, upload_param, AES media encryption, context_token, message dedupe, and content_type detection."
metadata:
  scope: "chat-channels"
  languages: "en,zh"
---

# 多渠道机器人适配器 / Multi-Bot Adapter

> 把「聊天平台协议」收敛成一套可复用的渠道适配器:
> **QQ 官方 Bot(WebSocket 网关 + REST)** 与 **微信 wxclaw / iLink Bot(HTTP 长轮询 + REST)**。
>
> 本 skill 来自一个已跑通的 agent 框架渠道实现,覆盖认证、扫码、收消息、发文本、富媒体、
> 语音、产物投递、渠道管理与排错。目标不是讲协议百科,而是让下一位开发者**照着接就能通**。

---

## 何时使用(触发场景)

只要任务涉及下面任一情况,先读本 skill,再按路由打开对应 reference:

- 给 agent / 机器人框架**新增一个消息渠道**(QQ、微信、或照着现有渠道仿写第三个平台)。
- 实现或修改**扫码登录**、AppID/ClientSecret、Bot Token、`access_token` 刷新。
- 接**收消息**:QQ WebSocket 网关 / 心跳 / Resume,或 wxclaw `getupdates` 长轮询。
- 接**发消息**:纯文本、Markdown、图片、视频、语音、文件、产物回传。
- 处理**被动回复**:QQ `msg_id`、微信群/私聊会话、`context_token` 24h 窗口。
- 排查协议错误:`-14 session timeout`、401/403、`upload_param` 为空、文件解密乱码、附件类型误判。
- 做渠道运行时:管理员白名单、`/myuid`、工作流模式、定时任务推送、错误状态上报。

**不适用**:纯 Web 前端聊天、只调用大模型 API、与消息渠道无关的 IM 协议研究。
遇到第三种平台时,仍可用本 skill 的「适配器契约」和「必守不变量」作为接入模板。

---

## 核心架构

```
                       ┌──────────────────────────────┐
   QQ 官方 Bot  ──────► │  QQBotAdapter                │
   WebSocket + REST    │  - token 缓存/刷新            │
                       │  - gateway/心跳/Resume        │
                       │  - 文本 + 富媒体 + 语音        │
                       └──────────────┬───────────────┘
                                      │
                       ┌──────────────▼───────────────┐
   微信 wxclaw  ──────► │  WxclawAdapter               │
   长轮询 + REST       │  - 请求头三件套                │
                       │  - getupdates 游标/去重        │
                       │  - AES 媒体上传/下载解密        │
                       └──────────────┬───────────────┘
                                      │  标准消息
                       ┌──────────────▼───────────────┐
                       │  BaseAdapter.dispatch        │
                       │  过滤 → on_message → 回复     │
                       │  先附件,后文本;语音失败降级   │
                       └──────────────┬───────────────┘
                                      │
                       ┌──────────────▼───────────────┐
                       │  Channel Manager             │
                       │  生命周期/会话/产物/推送/状态   │
                       └──────────────────────────────┘
```

三层职责必须分清:

1. **适配器**只负责平台协议:认证、连接、解析、发送、下载。不要写业务逻辑。
2. **BaseAdapter** 负责标准化投递:过滤、`on_message`、附件顺序、语音降级。
3. **Manager** 负责运行时:渠道启停、会话隔离、入站文件、产物登记、管理员、推送、状态。

---

## 适配器契约

### 标准消息

所有适配器把平台事件转成同一结构,交给 `dispatch`:

```python
{
    "platform": "qqbot | wxclaw",
    "message_id": "...",
    "user_id": "发送者标识",
    "group_id": "群标识,私聊为 None",
    "content": "文本(附件用占位描述拼接)",
    "files": [
        {"type": "image | video | voice | file",
         "url": "...",              # 有直链就放
         "name": "文件名",
         "aes_key": "...",           # wxclaw 加密媒体
         "encrypt_query_param": "..."}
    ],
    "raw_data": {...},               # 原始事件,排错用
}
```

### 必须实现的方法

```python
class BaseAdapter(ABC):
    platform: str

    async def connect(self) -> None: ...
    async def disconnect(self) -> None: ...

    async def send(self, target_id: str, content: str, is_group: bool,
                   file_path: str | None = None, file_name: str = "",
                   file_type: str = "file") -> dict: ...

    async def send_file_bytes(self, target_id: str, file_name: str,
                              data: bytes, file_type: str,
                              is_group: bool) -> dict: ...

    async def download_inbound(self, att: dict) -> bytes | None: ...
```

约定:

- `send` / `send_file_bytes` 返回平台响应 dict;失败返回 `{"error": "..."}`,不要静默吞掉。
- `download_inbound` 接收 `files[]` 中的一项,返回原始字节;失败返回 `None` 并记日志。
- 平台响应里的 `ret` / `errcode` 要在适配器内部判定;BaseAdapter 只检查 `error` 和 `ret != 0`。
- 附件下载与发送都要设置超时,避免一个坏附件拖死整条消息。

### 生命周期与状态

- `connect()` 只负责启动后台任务(轮询或 WebSocket),不要阻塞。
- `disconnect()` 关闭连接;后台任务由 BaseAdapter 统一取消。
- 连接/鉴权失败要抛出异常,让 Manager 把渠道状态置为 `error` 并写 `last_error`。
- 运行期错误通过 `manager.mark_status(user_id, channel_id, "error"|"running", message)` 上报。
- 内部配置 `__channel_id` 由 Manager 注入,适配器不要要求用户手填。

---

## 接入流程(照着做)

### 1. 选渠道并准备凭据

| 渠道 | 凭据 | 获取方式 |
|---|---|---|
| QQ 官方 Bot | `app_id` + `client_secret` | 扫码连接(推荐)或 q.qq.com 开放平台 |
| 微信 wxclaw | `token`(`xxx@im.bot:...`) | 扫码登录(推荐)或手动粘贴 |

扫码的完整接口、二维码状态机、凭据落库与热启动,见对应 reference 的「扫码登录」章节。

### 2. 认证

- **QQ**:`POST https://bots.qq.com/app/getAppAccessToken`,token 2 小时过期;
  缓存 + 到期前 60 秒刷新 + 加锁;401/403 强制刷新后重试一次。
- **wxclaw**:请求头三件套缺一不可——`AuthorizationType: ilink_bot_token`、
  `Authorization: Bearer <token>`、非空随机 `X-WECHAT-UIN`;payload 必须带
  `base_info.channel_version`。

### 3. 收消息

- **QQ**:`GET /gateway` → WebSocket → `Hello` → `Identify/Resume` → `Dispatch`。
  处理 `C2C_MESSAGE_CREATE`、`GROUP_AT_MESSAGE_CREATE`、`GROUP_MESSAGE_CREATE`;
  心跳、重连退避、消息 id 去重。
- **wxclaw**:`POST ilink/bot/getupdates` 长轮询,游标 `get_updates_buf`;
  兼容 `next_get_updates_buf`;按 `message_id` 去重;`-14` 时放慢轮询并上报错误。

### 4. 发消息

- **QQ**:`/v2/{groups|users}/{target}/messages`;文本 `msg_type=0/2`;
  富媒体先上传 `/files` 拿 `file_info`,再发 `msg_type=7`;
  被动回复 `msg_id` 有值才带,空串必须省略。
- **wxclaw**:`ilink/bot/sendmessage`,`{"msg": {...}, "base_info": {...}}` 两层包裹;
  `message_type=2`;`context_token` 按发送者缓存 24h。

### 5. 媒体与语音

- **QQ**:`file_type` 1=图片、2=视频、3=语音、4=文件;语音支持 wav/mp3/silk 直传,
  不做转码;上传返回 `file_info` 后立即发送(有 TTL)。
- **wxclaw**:`getuploadurl` → CDN 上传(AES-ECB 加密)→ `sendmessage`;
  `media_type` 1=图片、3=文件;`upload_param` 可能在响应顶层;
  `media` 必须放在 `*_item` 内部;文件带 `file_name` 与 `len`。
- **语音出站**:QQ 原生支持;微信协议未开放,只能降级成文件。
- **降级规则**:语音发送失败 → 改发文件 + 补发文本;语音成功 → 不重复发文本;
  超过 20MB 的语音不投递。

### 6. 渠道运行时

- 每个「渠道 + 发送者」一个独立会话;同一渠道串行处理,新消息打断旧任务。
- 「停止/取消/算了」等短指令中断当前任务。
- 入站附件保存到工作区 `inbox/`,登记为会话产物;图片走多模态,语音转写,文档抽文本。
- 管理员 `admin_ids` 才可用管理工具;`/myuid` 返回发送者 ID。
- 定时推送目标:显式 `target` → `admin_ids` 第一个 → `last_sender_id` → `last_group_id`。

---

## 两个渠道的关键差异

| 项目 | QQ 官方 Bot | 微信 wxclaw |
|---|---|---|
| 收消息 | WebSocket 网关(心跳 + Resume) | HTTP 长轮询(游标) |
| 认证头 | `Authorization: QQBot <token>` | `AuthorizationType` + `Bearer` + `X-WECHAT-UIN` |
| token | 2 小时,自动刷新 | 扫码后长期,但 24h 会话窗口 |
| 响应 | 标准 JSON | octet-stream 伪装 JSON |
| 文本回复 | `msg_type=0/2` + `msg_seq` | `msg` 包裹 + `message_type=2` |
| 被动回复 | 群聊必须带 `msg_id` | 带 `context_token` |
| 媒体加密 | 无 | AES-ECB(上传/下载) |
| 媒体流程 | `/files` → `file_info` → `msg_type=7` | `getuploadurl` → CDN → `sendmessage` |
| 出站语音 | 原生支持 | 不支持,降级为文件 |
| 错误定位 | HTTP / code 较明确 | 统一 `-14`,需逐项核对请求头 |

---

## 必守不变量(上线前逐条核对)

- [ ] token / secret 不落日志、不返回前端明文;列表接口脱敏,敏感字段单独 reveal。
- [ ] 保存配置时过滤占位符(`已自动填入`、`****`),缺省敏感字段沿用旧值。
- [ ] QQ `msg_id` 空串不传;wxclaw `context_token` 过期(24h)视为空。
- [ ] wxclaw 三个请求头齐全,`base_info.channel_version` 存在。
- [ ] wxclaw `upload_param` 顶层和 `data` 双查;上传后立即发送。
- [ ] wxclaw 解密 key 尝试顺序:**hex → base64 → 原文**,并用 PKCS7 校验。
- [ ] QQ 附件类型用 `content_type` 判定,缺文件名补带扩展名的占位名。
- [ ] QQ `content_type` 缺失时按扩展名兜底;相对 URL 补 `https://multimedia.nt.qq.com`。
- [ ] 两个渠道都按消息 id 去重,防止重连/游标回退导致重复回复。
- [ ] 单条消息/附件失败只影响当前项,不能让整条消息崩掉。
- [ ] 连接失败、鉴权失败、token 失效都要上报渠道 `status` / `last_error`。
- [ ] 语音失败降级为文件并补发文本;超大语音直接走文本。

---

## 常见故障速查

| 现象 | 渠道 | 首要排查 |
|---|---|---|
| `-14 session timeout` | wxclaw | 三个请求头、`get_updates_buf`、`base_info.channel_version` |
| 401 / 鉴权失败 | QQ | `Authorization` 前缀必须是 `QQBot` |
| 群聊 403 / 无响应 | QQ | 被动回复缺 `msg_id`;群消息通常只在 @ 时触发 |
| `upload_param` 为空 | wxclaw | 响应在顶层,不是 `data` |
| 文件上传成功但没到 | wxclaw | `item.type`、`media` 位置、`file_name`/`len` |
| 文件内容乱码 | wxclaw | aes_key 编码/尝试顺序、PKCS7、是否错误 key |
| 语音被当成文件 | QQ | 用 `content_type=audio/*` 判定 |
| 回复重复 | 两者 | 消息 id 去重 |
| 私聊永远纯文本 | QQ | 不要写 `is_group and markdown_support` |
| Token 输入框为空 | wxclaw | 登录响应回传 `data.token`,前端填回输入框 |

更深的原因与修复见 `references/qqbot-integration.md` 与
`references/wxclaw-integration.md` 的「踩坑清单」。

---

## 配置参考(最小集)

**QQ**

```json
{
  "app_id": "...",
  "client_secret": "...",
  "admin_ids": "openid1,openid2",
  "markdown_support": true,
  "disable_group": false,
  "disable_private": false,
  "tts_voice_id": ""
}
```

**wxclaw**

```json
{
  "token": "xxxx@im.bot:...",
  "api_url": "https://ilinkai.weixin.qq.com",
  "x_wechat_uin": "",
  "poll_interval_sec": 2,
  "admin_ids": "wxid1,wxid2",
  "tts_voice_id": ""
}
```

隐藏但可配置:`authorization_type`、`channel_version`、`get_updates_path`、
`send_message_path`、`login_qr_path`、`login_check_path`。

---

## 测试与验收

```bash
# QQ:扫码解密、状态机、msg_id、语音、Markdown、附件类型
pytest tests/test_qqbot_login.py tests/test_qqbot_sessions.py -q

# wxclaw:请求头、游标、占位符、媒体映射、上传地址、解密
pytest tests/test_wxclaw_protocol.py tests/test_wxclaw_channel.py tests/test_channel_media.py -q
```

验收最少覆盖:

1. 扫码成功 → 凭据落库 → 渠道热启动。
2. 私聊/群聊各发一条文本,确认会话隔离与被动回复。
3. 发一张图、一个文件、一条语音;确认附件顺序与降级。
4. 断开重连/游标回退时不重复回复。
5. 错误 token 能给出可读的 `last_error`,而不是静默卡死。

---

## 参考文件路由

| 需要什么 | 打开 |
|---|---|
| QQ 全量协议、扫码、WebSocket、富媒体、语音、排错 | `references/qqbot-integration.md` |
| 微信全量协议、请求头、长轮询、加密上传/下载、排错 | `references/wxclaw-integration.md` |
| 两个渠道的端点/字段并排速查 | `references/protocol-cheatsheet.md` |
| 基类契约、标准消息、Manager 生命周期与推送 | `references/adapter-contract.md` |
| 版本记录 | `CHANGELOG.md` |
| 安装与发布 | `README.md` |

---

*版本 1.0.0 · 作者 bucai2417 · 最后更新 2026-11-06*
Files in this package (14)
  • .gitignore 1 KB
  • CHANGELOG.md 2 KB
  • LICENSE 11 KB
  • README.md 6 KB
  • SKILL.md 16 KB
  • assets/icon-1024.png 267 KB
  • assets/icon-128.png 17 KB
  • assets/icon-256.png 49 KB
  • assets/icon-512.png 121 KB
  • references/adapter-contract.md 10 KB
  • references/protocol-cheatsheet.md 7 KB
  • references/qqbot-integration.md 24 KB
  • references/wxclaw-integration.md 31 KB
  • scripts/package_skill.py 8 KB

Versions

The database has no other skills named multi-bot-adapter.

Database snapshot: 13.11.2026 · package version 61d5ef5c5b7b (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100channel-bot
    Work with messaging-channel bots (Telegram / Slack) — register a bot, route inbound messages through the AI agent, handle webhooks vs polling, or add a new channel adapter. Use when wiring chat into a messaging platform or debugging bot delivery.
  • 100bot-config
    管理 CloseCrab bot 配置(Firestore)。添加新 bot、给已有 bot 添加 channel、切换 channel、查看配置。当用户说"添加一个 bot"、"新建 bot"、"加个飞书 channel"、"加个 discord channel"、"切换到飞书"、"bot 配置"、"add bot"、"add channel"等关键词时触发。
  • 100chat-sdk
    Build multi-platform chat bots with Chat SDK (`chat` npm package). Use when developers want to (1) Build a Slack, Teams, Google Chat, Discord, Telegram, GitHub, Linear, or WhatsApp bot, (2) Use Chat SDK to handle mentions, direct messages, subscribed threads, reactions, slash…
  • 100configure
    Configure Slack channel tokens (bot token + app-level token). Use when writing or rotating the Slack bot and app-level tokens for the slack-channel plugin. Trigger with "/slack-channel:configure", "configure slack tokens", or "set up my slack bot token".
  • 100agent-messaging
    Send and receive cryptographically signed messages between AI agents using the Agent Messaging Protocol (AMP). Use when the user asks to "send a message to an agent", "check agent inbox", "message another agent", "reply to a message", "notify an agent", or any inter-agent communication task.
  • 85azure-health-bot
    Expert knowledge for Azure Health Bot development including best practices, security, configuration, and integrations & coding patterns. Use when configuring Health Bot auth, Teams/web chat, channel integrations, App Insights telemetry, or voice safeguards, and other Azure…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.