Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fix(Officialqq):完善官方机器人对接相关文档 #279

Merged
merged 19 commits into from
Oct 11, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file added assets/机器人自测报告.xlsx
Binary file not shown.
Binary file not shown.
Binary file added docs/deploy/images/platform-qq-official-10.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/deploy/images/platform-qq-official-11.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/deploy/images/platform-qq-official-12.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/deploy/images/platform-qq-official-13.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/deploy/images/platform-qq-official-14.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/deploy/images/platform-qq-official-15.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/deploy/images/platform-qq-official-4.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/deploy/images/platform-qq-official-5.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/deploy/images/platform-qq-official-6.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/deploy/images/platform-qq-official-7.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/deploy/images/platform-qq-official-8.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/deploy/images/platform-qq-official-9.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
113 changes: 107 additions & 6 deletions docs/deploy/platform-qq.md
cherrybird7 marked this conversation as resolved.
Show resolved Hide resolved
Original file line number Diff line number Diff line change
Expand Up @@ -250,9 +250,13 @@ NapCat 是基于官方 NTQQ 实现的 Bot 框架,因此在开始前,你需

QQ 官方目前已开放了机器人功能,可进入 [QQ 开放平台](https://q.qq.com/#/) 进行申请。

但截止到目前,**QQ 官方机器人的群聊权限并未对所有人开放**。我们也希望在未来,每个人都能轻松地对接上官方提供的机器人服务
搭建机器人官方请参考 [QQ 机器人文档](https://bot.q.qq.com/wiki/#/)

同时,由于 QQ 官方对机器人能力的严格限制(包括获取 QQ 号、昵称,非 @ 时响应,私聊,群控等大量功能目前不支持),目前**对接官方接口的骰子很多功能无法支持**(如跑团 Log,暗骰,对抗等)。
目前, **QQ 官方机器人已开放个体使用权限。但官方文档没有及时更新**。

同时,由于 QQ 官方对机器人能力的严格限制(包括获取 QQ 号、昵称,非 @ 时响应,私聊,群控、发送本地图片等大量功能目前不支持),目前**对接官方接口的骰子很多功能无法支持**(如跑团 Log ,暗骰,对抗等)。

QQ 官方机器人的优点,就是不用担心被风控。

:::
kenichiLyon marked this conversation as resolved.
Show resolved Hide resolved

Expand All @@ -264,26 +268,123 @@ QQ 官方目前已开放了机器人功能,可进入 [QQ 开放平台](https:/

### 获取连接所需信息

要获取用于连接海豹的信息之前,你需要建立好一个 QQ 机器人应用。可前往 [QQ 开放平台](https://q.qq.com/#/) 进行申请,进行**实名**注册后,创建一个机器人应用。
要获取用于连接海豹的信息之前,你需要建立好一个 QQ 机器人应用。可前往 [QQ 开放平台](https://q.qq.com/#/) 进行申请,**实名**注册后,创建一个机器人应用。

创建完成后,进入机器人管理后台,切换到「开发设置」页面:

<img src="./images/platform-qq-official-1.png" alt="切换到开发设置" width="40%">

在页面中你可以看到这样的信息,其中「机器人 ID」「机器人令牌」「机器人密钥」这三项是海豹进行连接所需要的。
在页面中你可以看到这样的信息,其中「机器人 ID 」「机器人令牌」「机器人密钥」这三项是海豹进行连接所需要的。

![开发设置](./images/platform-qq-official-2.png)

然后在「开发设置 IP 白名单」一栏中,填写你骰子所在电脑的 **公网** IP。(使用云服务器时,请填写对应云服务商在控制台提供的 IP)

<img src="./images/platform-qq-official-4.png" alt="连接官方 Bot" width="100%">

::: warning 注意:家庭网络的 IP 变动

如果你使用的是家用网络,在本地电脑运行海豹,要注意家庭网络的 IP 通常是不固定的,运营商随时可能会更换你的 IP,遇到问题时请先检查。

:::

cherrybird7 marked this conversation as resolved.
Show resolved Hide resolved
### 连接海豹

登录海豹并添加账号,选择「QQ(官方机器人)」。填写对应的信息点击连接。你的海豹应该可以正常连接官方机器人运作了!

<img src="./images/platform-qq-official-3.png" alt="连接官方 Bot" width="100%">
<img src="./images/platform-qq-official-3.png" alt="连接官方 Bot" width="100%" />

### 指令配置

1. 进入「发布配置」页面;
2. 点击「功能配置」;
3. 点击「指令配置」;
4. 再点击右上角的「重新配置」开始编辑;
5. 点开「指令」页添加指令,「指令名」里面输入对应指令(例如 `r`、`ra`、`en`),`/` 是 QQ 官方机器人默认的指令前缀(海豹也支持使用 `/`);
6. 然后在「指令介绍」一栏填写指令的简介;
7. 然后在「使用场景」一栏点击「QQ 频道」、「频道私信」、「QQ 群」,切记不能选中「消息列表」;
8. 确认配置完成后,扫码确认修改,就可以完成指令配置。

<img src="./images/platform-qq-official-11.png" alt="进入指令配置页" />

<img src="./images/platform-qq-official-12.png" alt="进行指令配置" />

::: details 推荐指令列表模版

<img src="./images/platform-qq-official-7.png" alt="推荐指令列表模版1" width="66%" />

<img src="./images/platform-qq-official-8.png" alt="推荐指令列表模版2" width="66%" />

:::

### 机器人上线

点开「使用范围和人员页面」,进入「编辑」页,参考下面图片中编辑使用范围与人员。

<img src="./images/platform-qq-official-6.png" alt="连接官方 Bot" />

配置完成后,点击「发布配置」页面,上传「自测报告」与「隐私协议」。

::: details 「隐私协议」与「自测报告」模板

这里提供了海豹骰的机器人「隐私协议」与「自测报告」模版。

**强烈建议你按自身情况进行修改,绝对不要原样上传,这涉及到你的机器人是否能被 QQ 官方的工作人员审核通过。**

[机器人自测报告.xlsx](https://github.com/sealdice/sealdice-manual-next/blob/main/assets/%E6%9C%BA%E5%99%A8%E4%BA%BA%E8%87%AA%E6%B5%8B%E6%8A%A5%E5%91%8A.xlsx?raw=true)

[第三方机器人隐私保护指引.docx](https://github.com/sealdice/sealdice-manual-next/blob/main/assets/%E7%AC%AC%E4%B8%89%E6%96%B9%E6%9C%BA%E5%99%A8%E4%BA%BA%E9%9A%90%E7%A7%81%E4%BF%9D%E6%8A%A4%E6%8C%87%E5%BC%95.docx?raw=true)

如果你对「指令列表」的指令进行了修改,或者新增了其他功能,请自行修改,需要在「预期输出」一栏填「指令简介」。

:::

点击「提交审核」后,等待 QQ 官方人员测试并审核(时间不定)。审核通过后,在「发布设置」页面中点击「上线机器人」。

::: tip 提示:关于 QQ 审核

目前 QQ 审核主要是测试机器人能否在所选支持的场景下,正常回应指令列表里的指令(在没有添加任何其他内容前提下),为人工审核。

在提交审核前,请善用沙盒群,测试你提交的自测报告中,所提到的指令是否都能正常工作,机器人需要正常发出回应。

如果你的指令包含一些需要填写的参数,请务必在「自测报告」表格「特殊说明」一栏里补充说明。(你可以参考模板中对 `.ra` `.sc` `.en` 指令的特殊说明。)

如果审核未通过,点击右上角的「通知」查看原因,解决后再次提交。 如果实在无法解决,可加入「QQ 机器人官方频道」,在「寻求||审核和及 bug 」一栏里,发帖询问。

:::

### 使用海豹

::: warning
点击「使用人员与范围」页面,查看你的机器人对应的邀请二维码,扫码添加即可。

::: warning 注意

目前官方机器人只响应包含 `@` 的消息,操作时请注意。

同时,官方机器人一次只能发一条消息,一次性发送消息太多,官方机器人会因为消息发送过于频繁而报错。

此外,官方机器人目前无法发送本地图片。

:::

### 注意事项

大部分事项 [QQ 机器人文档](https://bot.q.qq.com/wiki) 都有说明,这里补充一些文档中没有说明的其他事项:

#### 企业账号的开发者资质审核

如果你使用企业账号进行了注册,请记得在资料一栏中进行开发者资质状态审核。该审核需要将对应企业的银行卡号上传至腾讯审核,期间的等待时间可能较久。在开发者资质状态通过后,你才能将官方机器人送审。

<img src="./images/platform-qq-official-5.png" alt="开发者资质状态审核" />

#### 机器人官方频道跳转

机器人「资料卡」页面中资料卡设置一栏中,「机器人官方频道跳转」不能是骰子的「沙盒频道」。

<img src="./images/platform-qq-official-9.png" alt="机器人官方频道跳转" />

#### 功能审核未通过

有时候「功能配置」页面中,「功能配置与提审」旁显示审核通过,但实际并没有通过,这时点击「机器人上线」的会显示发送错误。

遇见这种情况请点击「通知」,看机器人哪方面没过审,修改后再次提交审核。