# @alemonjs/qq-bot 中文文档

规范地址：https://npmcn.com/package/%40alemonjs/qq-bot/

版本：2\.1\.44
npm 元数据更新时间：2026-10-31T11:46:47.320Z
中文译文更新时间：2026-11-08T09:56:03.400Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40alemonjs/qq-bot
原文对照：https://npmcn.com/package/%40alemonjs/qq-bot/?lang=original
项目主页：https://github.com/lemonade-lab/alemonjs#readme
源码仓库：https://github.com/lemonade-lab/alemonjs

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：880 kB，151 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：15 个
- 首次发布：2024-12-31T03:58:25.621Z
- 最新版本发布：2026-10-31T11:46:47.147Z
- 近 30 天下载量：1812（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：100（近 12 个月 58 个）

## 中文简介

QQ官方平台

## 安装

```sh
npm install @alemonjs/qq-bot
```

也可以使用：`pnpm add @alemonjs/qq-bot`、`yarn add @alemonjs/qq-bot`、`bun add @alemonjs/qq-bot`

## README

# @alemonjs/qq-bot

## 项目作用

AlemonJS 的 QQ 开放平台适配器，用于连接官方机器人接口，将 QQ 消息、事件和操作接入框架 Hook。

-   支持群聊、单聊、频道、频道私信和互动按钮。
-   支持文本、图片、Markdown、按钮、Ark 卡片及音视频、文件消息。
-   提供群管理、媒体上传和单聊流式消息能力；具体能力以平台权限为准。
-   支持 WebSocket、Webhook 连接，以及 WebSocket 多机器人配置。

官方 Node SDK 的对照结果、已落实修复和后续框架改进见 [SDK 对照与改进](https://npmcn.com/package/%40alemonjs/qq-bot/SDK_REVIEW.md)。

三层限流、QQ 文本清洗、引用索引、群历史、LLM 上下文和 C2C 自动 typing 的配置与用法见 [消息处理与会话上下文](https://npmcn.com/package/%40alemonjs/alemonjs/docs/message-context.md)。

Markdown 图片支持使用 `Media.image(source)` 自动准备 QQ 素材，也可通过媒体 Hook 提前上传、查询与删除，见[图片来源与平台资源](https://npmcn.com/package/%40alemonjs/alemonjs/docs/media.md)。

## 配置

### 基础配置

在项目的 `alemon.config.yaml` 中填写：

```yaml
qq-bot:
  app_id: 'YOUR_APP_ID'
  secret: 'YOUR_APP_SECRET'
```

`app_id` 和 `secret` 可在 [QQ 开放平台](https://q.qq.com/) 获取。默认使用 WebSocket；未填写凭证且未配置 `bots` 时，会进入[扫码登录](https://npmcn.com/package/%40alemonjs/qq-bot/QR_LOGIN.md)。扫码授权会重置 AppSecret，使旧密钥失效。

### 连接模式

| 模式 | 配置方式 | 说明 |
| --- | --- | --- |
| WebSocket（默认） | 不配置 `route`、`port`、`ws` | 直连官方网关 |
| Webhook | 配置 `route` 或 `port` | 本地服务接收回调，需要公网地址；启用后官方会禁用 WebSocket 模式 |
| Webhook 转发 | 配置 `ws` | 连接已有的 Webhook 转发服务 |
| 自定义网关 | 配置 `gatewayURL` 或 `base_url_gateway` | 使用自建网关或域名代理 |

Webhook 配置示例（需自行填写完整凭证，不触发扫码登录）：

```yaml
qq-bot:
  app_id: 'YOUR_APP_ID'
  secret: 'YOUR_APP_SECRET'
  port: '17157'
  route: '/webhook'
```

### 多机器人（WebSocket）

`bots` 的键为 BotId/AppID，每项填写对应密钥，可覆盖公共 SDK 配置。配置多个机器人时必须设置 `default_bot`，其值须匹配 `bots` 中的键。事件回复自动使用事件所属机器人，主动操作可通过 `BotId` 指定机器人。

```yaml
qq-bot:
  default_bot: 'app-a'
  bots:
    app-a:
      secret: 'secret-a'
    app-b:
      secret: 'secret-b'
```

### 配置项说明

| 配置项 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `app_id` | string | — | 单机器人 AppID；可通过扫码自动写入 |
| `secret` | string | — | AppSecret；Webhook 模式同时用于签名 |
| `bots` | object | — | 多机器人配置，键为 BotId/AppID，仅用于 WebSocket |
| `default_bot` | string | 单个机器人的 ID | 默认机器人，配置多个机器人时必填 |
| `master_key` | string\[\] | `[]` | 主人 UserKey 列表 |
| `master_id` | string\[\] | `[]` | 主人 UserId 列表 |
| `route` | string | `/webhook` | Webhook 回调路由；显式配置后启用 Webhook |
| `port` | string | `17157` | Webhook 本地监听端口；显式配置后启用 Webhook |
| `ws` | string | — | 已有 Webhook 转发服务的 WebSocket 地址 |
| `gatewayURL` | string | — | 自定义 WebSocket 网关地址 |
| `base_url_gateway` | string | — | 网关域名代理 |
| `base_url_app_access_token` | string | — | 获取 access\_token 的域名代理 |
| `is_private` | boolean | `false` | 私域机器人，影响默认事件订阅 |
| `sandbox` | boolean | `false` | 显式使用旧版沙盒域名；默认正式环境使用 api.bot.qq.com |
| `shard` | number\[\] | `[0, 1]` | WebSocket 分片 |
| `intents` | string\[\] | 自动组装 | 自定义事件订阅，覆盖默认值，见 [intents.ts](https://npmcn.com/package/%40alemonjs/qq-bot/src/sdk/intents.ts)；通常省略，不要填空数组 |
| `autoInteractionAck` | boolean | `true` | 自动确认按钮、快捷菜单事件；关闭后由应用调用 `useInteraction().ack()` |
| `markdownToText` | boolean | `false` | 将 Markdown 和按钮降级为可读纯文本 |
| `hideUnsupported` | boolean / number | `false` | 消息降级时的隐藏级别，见下方说明 |

`hideUnsupported` 支持以下级别，转换后内容为空时跳过发送：

-   `false`：不启用隐藏。
-   `true` 或 `1`：隐藏图片、音频、附件等不可读占位符，保留可读内容。
-   `2`：按钮仅显示指令数据，链接仅显示 URL。
-   `3`：进一步隐藏按钮和链接的数据。
-   `4`：不转换，直接丢弃降级数据。

## 文档目录

| 文档 | 内容 |
| --- | --- |
| [安装与快速开始](https://npmcn.com/package/%40alemonjs/qq-bot/GETTING_STARTED.md) | 安装、路由注册和第一个消息回复 |
| [框架开发指南](https://npmcn.com/package/%40alemonjs/qq-bot/FRAMEWORK.md) | 群聊、单聊、菜单、面板、管理能力及标准事件，业务开发优先阅读 |
| [扫码登录](https://npmcn.com/package/%40alemonjs/qq-bot/QR_LOGIN.md) | 授权流程、密钥重置和失败处理 |
| [调用方式与 API 参考](https://npmcn.com/package/%40alemonjs/qq-bot/API.md) | 调用示例、API 索引、参数与 SDK 方法速查 |
| [消息类型与格式](https://npmcn.com/package/%40alemonjs/qq-bot/MESSAGES.md) | Format 映射、Markdown、按钮、Ark 和富媒体 |
| [事件参考](https://npmcn.com/package/%40alemonjs/qq-bot/EVENTS.md) | 事件映射、数据结构与读取示例 |
| [常见问题与验证范围](https://npmcn.com/package/%40alemonjs/qq-bot/FAQ.md) | 排障、能力覆盖和验证命令 |
| [QQ 官方开发文档](https://bot.q.qq.com/wiki/) | 平台接口与权限说明 |

## 常见问题

### @alemonjs/qq-bot 是什么？

QQ官方平台

### 如何安装 @alemonjs/qq-bot？

在项目目录运行 npm install @alemonjs/qq-bot，或使用 pnpm add / yarn add / bun add。

### @alemonjs/qq-bot 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @alemonjs/qq-bot 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @alemonjs/qq-bot 可以商用吗？

@alemonjs/qq-bot 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @alemonjs/qq-bot 的下载量有多少？

根据 npm 官方下载统计，@alemonjs/qq-bot 在 2026/10/06 – 2026/11/04 这 30 天内被下载 1,812 次，日均约 60 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @alemonjs/qq-bot 还在维护吗？

最新版本 2\.1\.44 发布于 2026/10/31（8 天前）；至今共发布 100 个版本，其中过去 12 个月发布了 58 个；首次发布于 2024/12/31。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。