# QQ机器人

> For the complete documentation index, see [llms.txt](https://simbot.forte.love/llms.txt).

[https://github.com/simple-robot/simpler-robot/releases](https://github.com/simple-robot/simpler-robot/releases)

## See also

### 相关链接

[QQ机器人组件源码](https://github.com/simple-robot/simpler-robot/tree/dev/simbot-component-qq) [Ktor首页](https://ktor.io/) [QQ机器人开放平台](https://bot.q.qq.com/wiki/develop/api-v2/)

## 概述

QQ机器人组件 是一个 [Kotlin 多平台](https://kotlinlang.org/docs/multiplatform.html) 的 [QQ机器人官方API](https://bot.q.qq.com/wiki/develop/api-v2/) SDK实现库， 也是 Simple Robot 标准API下实现的组件库，异步高效、Java友好！

QQ 组件主要分成三个层次：

* simbot-component-qq-api 对 QQ 开放平台 API、模型、网关事件体的原始封装。

* simbot-component-qq-stdlib 在 API 之上提供较低封装的 Bot、鉴权与事件接收实现。

* simbot-component-qq-core 面向 simbot 的组件实现，也是大多数业务项目真正直接依赖的模块。

目前核心能力覆盖：

* 频道公域消息、频道/成员相关事件

* 论坛相关事件

* 频道私聊 `DMS`

* QQ群与 `C2C` 单聊能力

* 频道、QQ群与 C2C 消息撤回 API（自 `5.0` 起补充群聊与单聊支持）

* C2C 自定义菜单与多场景指令面板管理（自 `5.0` 起）

* 群基础信息、机器人群内状态、入群申请管理和成员禁言（自 `5.0` 起）

其中 QQ 群与 `C2C` 单聊能力自 `4.0.0-beta6` 起加入。 更细粒度的事件与对象范围，请以 [事件列表](component-qq-guild-event-list.html) 和相邻对象章节为准。

> **Tip:**
> 序列化和网络请求相关分别基于 [Kotlin serialization](https://github.com/Kotlin/kotlinx.serialization) 和 [Ktor](https://ktor.io/).

* 前往QQ机器人组件的 [源码目录](https://github.com/simple-robot/simpler-robot/tree/dev/simbot-component-qq)

## 模块

QQ 组件使用 `simbot-component-qq-*` 坐标，随标准库统一版本发布。

| 模块 | 内容 |
| --- | --- |
| `simbot-component-qq-common` | 共享常量与注解，自 `5.0` 起提供 |
| `simbot-component-qq-api` | API 请求、原始事件、消息模型与构建器 |
| `simbot-component-qq-stdlib` | Bot、鉴权和事件接收处理 |
| `simbot-component-qq-core` | simbot 组件实现，普通应用直接依赖此模块 |
| `simbot-component-qq-internal-ed25519` | 内部签名支持，通常不需要直接依赖 |

上述模块均支持 JVM、JS、`wasm-js` 和部分 Native 目标。 版本升级与旧坐标迁移参见 [5.0 更新与迁移](migration-5-0.html)。

## 命名说明

QQ机器人组件最初只支持 QQ 频道，因此使用 `simbot-component-qq-guild` 命名。 自 `5.0` 起，模块坐标调整为 `simbot-component-qq-*`。 包名与 `QQGuildComponent`、`QQGuildBotManager` 等类型名仍保留原有命名。

> **Tip:**
> QQ群、QQ单聊功能自 `4.0.0-beta6` 版本起开始支持。

## 前提准备

### 机器人账号

你需要参考 [官方QQ机器人文档](https://bot.q.qq.com/wiki) ，并注册一个 机器人账号 。审核通过， 便可登录 [QQ开放平台](https://q.qq.com/#/) 查看你的机器人账号信息了。

### 事件订阅方式

官方提供了 `webhook` 与 `websocket` 两种事件订阅方式。

目前，这两种接入路径都有对应实现或示例：

* 如果你要接入 `webhook` 回调，前往 [Webhook](component-qq-guild-webhook.html)

* 如果你要使用 `websocket` 收事件，则继续参考本页与 [开始使用](component-qq-guild-start-using.html)

你可以在机器人后台中查看、配置自己的回调地址与订阅范围。

## 安装

### 安装组件库

Procedure: 安装依赖

1. 安装simbot核心库实现

> **Note:**
> 在安装组件库之前，确保你已经安装了可用的核心库实现，比如 [核心库](start-use-core.html) 或 [Spring Boot starter](spring-boot.html) 。

核心库:

Gradle(Kotlin DSL):

```KOTLIN
implementation("love.forte.simbot:simbot-core:5.0.0-Alpha2")
```

如果使用 Java 而不配合使用 Gradle 的 [Kotlin 插件](https://kotlinlang.org/docs/gradle-configure-project.html#apply-the-plugin), 那么你需要指定依赖的后缀为 `-jvm`。

```KOTLIN
implementation("love.forte.simbot:simbot-core-jvm:5.0.0-Alpha2")
```

Gradle(Groovy):

```GROOVY
implementation 'love.forte.simbot:simbot-core:5.0.0-Alpha2'
```

如果使用 Java 而不配合使用 Gradle 的 [Kotlin 插件](https://kotlinlang.org/docs/gradle-configure-project.html#apply-the-plugin), 那么你需要指定依赖的后缀为 `-jvm`。

```GROOVY
implementation 'love.forte.simbot:simbot-core-jvm:5.0.0-Alpha2'
```

Maven:

```XML
<dependency>
    <groupId>love.forte.simbot</groupId>
    <artifactId>simbot-core-jvm</artifactId>
    <version>5.0.0-Alpha2</version>
</dependency>
```

> **Tip:**
> 前往 [核心库](start-use-core.html) 了解更多内容。

Spring Boot starter:

Spring Boot 3:

Gradle(Kotlin DSL):

```KOTLIN
implementation("love.forte.simbot:simbot-core-spring-boot-starter:5.0.0-Alpha2")
```

Gradle(Groovy):

```GROOVY
implementation 'love.forte.simbot:simbot-core-spring-boot-starter:5.0.0-Alpha2'
```

Maven:

```XML
<dependency>
    <groupId>love.forte.simbot</groupId>
    <artifactId>simbot-core-spring-boot-starter</artifactId>
    <version>5.0.0-Alpha2</version>
</dependency>
```

> **Tip:**
> 前往 [使用 Spring Boot 3](start-use-spring-boot-3.html) 或 [集成Spring Boot](spring-boot.html) 了解更多内容。

Spring Boot 2:

Gradle(Kotlin DSL):

```KOTLIN
implementation("love.forte.simbot:simbot-core-spring-boot-starter-v2:5.0.0-Alpha2")
```

Gradle(Groovy):

```GROOVY
implementation 'love.forte.simbot:simbot-core-spring-boot-starter-v2:5.0.0-Alpha2'
```

Maven:

```XML
<dependency>
    <groupId>love.forte.simbot</groupId>
    <artifactId>simbot-core-spring-boot-starter-v2</artifactId>
    <version>5.0.0-Alpha2</version>
</dependency>
```

> **Tip:**
> 前往 [使用 Spring Boot 2](start-use-spring-boot-2.html) 了解更多内容。

2. 安装组件库

`simbot-component-qq-core` 即为QQ机器人组件的核心库， 也就是作为simbot组件所使用的 组件库 。

Gradle(Kotlin DSL):

```KOTLIN
implementation("love.forte.simbot.component:simbot-component-qq-core:5.0.0-Alpha2")
```

如果使用 Java 而不配合使用 Gradle 的 `kotlin` 插件, 那么你需要指定依赖的后缀为 `-jvm`。

```KOTLIN
implementation("love.forte.simbot.component:simbot-component-qq-core-jvm:5.0.0-Alpha2")
```

Gradle(Groovy):

```GROOVY
implementation 'love.forte.simbot.component:simbot-component-qq-core:5.0.0-Alpha2'
```

如果使用 Java 而不配合使用 Gradle 的 `kotlin` 插件, 那么你需要指定依赖的后缀为 `-jvm`。

```GROOVY
implementation 'love.forte.simbot.component:simbot-component-qq-core-jvm:5.0.0-Alpha2'
```

Maven:

```XML
<dependency>
    <groupId>love.forte.simbot.component</groupId>
    <artifactId>simbot-component-qq-core-jvm</artifactId>
    <version>5.0.0-Alpha2</version>
</dependency>
```

3. 安装Ktor客户端引擎

QQ机器人组件使用 [Ktor](https://ktor.io) 作为 HTTP 客户端实现， 但是默认不会依赖任何具体的引擎。

因此，你需要选择并使用一个 Ktor Client 引擎实现。

> **Warning:**
> 如果你使用 `websocket` 订阅事件，需要选择一个支持 WebSocket 的引擎。 如果你只做 `webhook` 回调并自行处理服务端接入，则只需要满足 HTTP 客户端侧的依赖要求。

你可以前往 [Ktor文档](https://ktor.io/docs/http-client-engines.html) 处选择一个对应所用平台下合适的 `Client Engine`。 这里会根据不同平台提供几个示例，你可以选择其他可用目标。

> **Tip:**
> 注意应选择使用 `v2.x` 版本的 Ktor。5.0 后的版本会更新到 Ktor 3。

JVM:

Java:

在 Java11+ 的环境下，可以选择 [Java](https://ktor.io/docs/http-client-engines.html#java) 引擎。

Gradle Kotlin DSL:

```KOTLIN
runtimeOnly("io.ktor:ktor-client-java:$ktor_version")
```

如果不使用Kotlin的[Gradle插件](https://kotlinlang.org/docs/gradle-configure-project.html):

```KOTLIN
runtimeOnly("io.ktor:ktor-client-java-jvm:$ktor_version")
```

Gradle Groovy:

```GROOVY
runtimeOnly 'io.ktor:ktor-client-java:$ktor_version'
```

如果不使用Kotlin的[Gradle插件](https://kotlinlang.org/docs/gradle-configure-project.html):

```GROOVY
runtimeOnly 'io.ktor:ktor-client-java-jvm:$ktor_version'
```

Maven:

```XML
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-client-java-jvm</artifactId>
    <version>${ktor_version}</version>
    <scope>runtime</scope>
</dependency>
```

OkHttp:

[OkHttp](https://ktor.io/docs/client-engines.html#okhttp) 引擎基于 OkHttp，是一个不错的库。

Gradle Kotlin DSL:

```KOTLIN
runtimeOnly("io.ktor:ktor-client-okhttp:$ktor_version")
```

如果不使用Kotlin的[Gradle插件](https://kotlinlang.org/docs/gradle-configure-project.html):

```KOTLIN
runtimeOnly("io.ktor:ktor-client-okhttp-jvm:$ktor_version")
```

Gradle Groovy:

```GROOVY
runtimeOnly 'io.ktor:ktor-client-okhttp:$ktor_version'
```

如果不使用Kotlin的[Gradle插件](https://kotlinlang.org/docs/gradle-configure-project.html):

```GROOVY
runtimeOnly 'io.ktor:ktor-client-okhttp-jvm:$ktor_version'
```

Maven:

```XML
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-client-okhttp-jvm</artifactId>
    <version>${ktor_version}</version>
    <scope>runtime</scope>
</dependency>
```

CIO:

[CIO](https://ktor.io/docs/http-client-engines.html#cio) 是一个比较通用的引擎。 在不知道选什么的情况下，可以考虑使用它。

Gradle Kotlin DSL:

```KOTLIN
runtimeOnly("io.ktor:ktor-client-cio:$ktor_version")
```

如果不使用Kotlin的[Gradle插件](https://kotlinlang.org/docs/gradle-configure-project.html):

```KOTLIN
runtimeOnly("io.ktor:ktor-client-cio-jvm:$ktor_version")
```

Gradle Groovy:

```GROOVY
runtimeOnly 'io.ktor:ktor-client-cio:$ktor_version'
```

如果不使用Kotlin的[Gradle插件](https://kotlinlang.org/docs/gradle-configure-project.html):

```GROOVY
runtimeOnly 'io.ktor:ktor-client-cio-jvm:$ktor_version'
```

Maven:

```XML
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-client-cio-jvm</artifactId>
    <version>${ktor_version}</version>
    <scope>runtime</scope>
</dependency>
```

> **Tip:**
> 引擎大部分情况下可以 runtime only，除非你需要显式地定制化它。

JavaScript:

JavaScript 平台下可以选择 [Js](https://ktor.io/docs/http-client-engines.html#js) 引擎。

Gradle Kotlin DSL:

```KOTLIN
implementation("io.ktor:ktor-client-js:$ktor_version")
```

Gradle Groovy:

```GROOVY
implementation 'io.ktor:ktor-client-js:$ktor_version'
```

Native:

native 平台目标下，可能需要根据不同的平台类型选择不同的引擎。

Mingw:

可以选择 [WinHttp](https://ktor.io/docs/http-client-engines.html#winhttp) 引擎。

Gradle Kotlin DSL:

```KOTLIN
implementation("io.ktor:ktor-client-winhttp:$ktor_version")
```

Gradle Groovy:

```GROOVY
implementation 'io.ktor:ktor-client-winhttp:$ktor_version'
```

Linux:

Linux 下依旧可以选择 [CIO](https://ktor.io/docs/http-client-engines.html#cio) 引擎。

Gradle Kotlin DSL:

```KOTLIN
implementation("io.ktor:ktor-client-cio:$ktor_version")
```

Gradle Groovy:

```GROOVY
implementation 'io.ktor:ktor-client-cio:$ktor_version'
```

MacOS:

可以选择 [Darwin](https://ktor.io/docs/http-client-engines.html#darwin) 引擎。

Gradle Kotlin DSL:

```KOTLIN
implementation("io.ktor:ktor-client-darwin:$ktor_version")
```

Gradle Groovy:

```GROOVY
implementation 'io.ktor:ktor-client-darwin:$ktor_version'
```