Skip to content

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

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

Merged
merged 19 commits into from
Oct 11, 2024
Merged
Show file tree
Hide file tree
Changes from 12 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 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-16.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-17.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-18.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-20.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.
156 changes: 154 additions & 2 deletions docs/deploy/platform-qq.md
Original file line number Diff line number Diff line change
Expand Up @@ -250,9 +250,11 @@

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

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

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

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

:::

Expand All @@ -270,20 +272,170 @@

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


Check failure on line 275 in docs/deploy/platform-qq.md

View workflow job for this annotation

GitHub Actions / lint

Multiple consecutive blank lines

docs/deploy/platform-qq.md:275 MD012/no-multiple-blanks Multiple consecutive blank lines [Expected: 1; Actual: 2] https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md012.md

Check failure on line 276 in docs/deploy/platform-qq.md

View workflow job for this annotation

GitHub Actions / lint

Multiple consecutive blank lines

docs/deploy/platform-qq.md:276 MD012/no-multiple-blanks Multiple consecutive blank lines [Expected: 1; Actual: 3] https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md012.md
在页面中你可以看到这样的信息,其中「机器人 ID」「机器人令牌」「机器人密钥」这三项是海豹进行连接所需要的。

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

### 连接海豹

首先参考 [QQ机器人文档](https://bot.q.qq.com/wiki/#)来在QQ开发平台注册账号

注意开发设置IP白名单一栏要填写你骰子所在电脑的计算机IP(如果你用的是云电脑的话,那串带.的数字就是计算机IP,本地电脑的话按照下面的教程获取你的计算机IP)

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

::: warning info 本地电脑如何获取获取计算机IP

Windows

1.在Windows搜索栏输入cmd,选择“以管理员身份运行”。

Check failure on line 293 in docs/deploy/platform-qq.md

View workflow job for this annotation

GitHub Actions / lint

Trailing spaces

docs/deploy/platform-qq.md:293:33 MD009/no-trailing-spaces Trailing spaces [Expected: 0 or 2; Actual: 1] https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md009.md

2.输入ipconfig,按回车键。

Check failure on line 295 in docs/deploy/platform-qq.md

View workflow job for this annotation

GitHub Actions / lint

Trailing spaces

docs/deploy/platform-qq.md:295:19 MD009/no-trailing-spaces Trailing spaces [Expected: 0 or 2; Actual: 1] https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md009.md

3.在“IPv4地址”那一行显示的就是你的IP地址。

Mac

1.点击屏幕左上角的苹果图标,在下拉菜单中选择【系统偏好设置】。

Check failure on line 301 in docs/deploy/platform-qq.md

View workflow job for this annotation

GitHub Actions / lint

Trailing spaces

docs/deploy/platform-qq.md:301:33 MD009/no-trailing-spaces Trailing spaces [Expected: 0 or 2; Actual: 1] https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md009.md

2.在弹出的【系统偏好设置】菜单中,选择【网络】。

Check failure on line 303 in docs/deploy/platform-qq.md

View workflow job for this annotation

GitHub Actions / lint

Trailing spaces

docs/deploy/platform-qq.md:303:26 MD009/no-trailing-spaces Trailing spaces [Expected: 0 or 2; Actual: 1] https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md009.md

3.在【网络】菜单中,点击【高级】按钮。

Check failure on line 305 in docs/deploy/platform-qq.md

View workflow job for this annotation

GitHub Actions / lint

Trailing spaces

docs/deploy/platform-qq.md:305:21 MD009/no-trailing-spaces Trailing spaces [Expected: 0 or 2; Actual: 1] https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md009.md

4.在弹出的界面中点击【TCP/IP】标签,即可在下边找到【IP地址】。

:::

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

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

### 指令配置

1.进入发布配置页面

2.在发布配置界面点击功能配置

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

3.点击指令配置

4.再点击右上角的重新配置开始编辑

5.然后点开指令一栏,指令名里面输入指令(例如r、ra、en),/是指令前缀,目前海默认支持/作为指令前缀

6.然后在指令介绍一栏填写指令的简介

7.然后在使用场景一栏点击QQ频道、频道私信、QQ群,切记不能选中消息列表

8.最后再点击保持配置,这个时候网站会要求你手机扫码,扫码后确认修改就好了

<img src="./images/platform-qq-official-12.png" width="50%" height="50%" />

Check failure on line 335 in docs/deploy/platform-qq.md

View workflow job for this annotation

GitHub Actions / lint

Images should have alternate text (alt text)

docs/deploy/platform-qq.md:335:1 MD045/no-alt-text Images should have alternate text (alt text) https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md045.md

### 推荐指令列表模版

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

### 机器人上线

1.点开使用范围和人员页面

2.点击编辑

3.参考下面图片中编辑使用范围与人员

(注意允许消息列表的白名单要是空的,不能添加任何账号)

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

4,然后再点击发布配置页面,上传自测报告与隐私协议(这里提供了海豹骰的机器人机器人隐私协议与自测报告模版,建议不要提到海豹骰)

[模版下载链接](<https://pan.baidu.com/s/1UHclndFyDW-_6168e6gRZg?pwd=trpg>)

5.然后点击提交审核

6.然后自行等待,等审核通过后就可以在发布设置页面中点击上限机器人了,如果审核审核没通过,查看通知看是什么原因,然后对照教程看自己是哪一步做错了。实在不明白可以加入QQ机器人官方频道里发帖询问。

::: warning

注意事项

如果你按照 [推荐指令列表模版](#推荐指令列表模版)填写了前面的指令列表里的指令的话,自测报告里的指令面板表格你不用进行任何更改

如果你对指令列表进行了更改,或者新增了其他功能,请你自行修改,一般来讲预期输出填指令简介就可以了

**目前QQ审核通过的标准就是你机器人能否在你机器人支持的场景下对你指令列表里的指令(没有加任何其他内容)有所回应,对于其他方面的审核较轻。请善用沙盒群,测试你的机器人消息列表里的指令,在没加上其他内容的情况下,骰子能否回应。如果不能的话请在表格特殊特殊说明一栏里补充:
这是一个模版,例如输入xxx,他会xxx**

**其中较常用的投点中,.ra、.sc、.en不加上其他内容骰子没法正常回应,模版已经在表格特殊特殊说明一栏里补充**

Check failure on line 373 in docs/deploy/platform-qq.md

View workflow job for this annotation

GitHub Actions / lint

Emphasis used instead of a heading

docs/deploy/platform-qq.md:373 MD036/no-emphasis-as-heading Emphasis used instead of a heading [Context: "其中较常用的投点中,.ra、.sc、.en不加上其他内容骰子..."] https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md036.md

:::

### 注意事项

大部分事项 [QQ机器人文档](https://bot.q.qq.com/wiki/#)都有说明,这里列举一下QQ机器人文档没有说明有可能踩坑的事项

1.如果你是用企业账号的话,记得在资料一栏里进行开发者资质状态审核,审核简单来说就是你上传企业的银行号码后,腾讯会给你账户发几分钱检查这个账号能不能用。这过程可能会等待较长的时间。开发者资质状态通过后才能将官方机器人送审。

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

2.机器人资料卡界面中资料卡设置设置一栏中的机器人官方频道跳转不能是你骰子的沙盒频道。

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

3.有时候功能配置界面会出现bug,就是功能配置与提审显示你审核通过了,但实际并没有通过,这个时候你点击机器人上线的会显示发送错误,这个时候建议点击通知,看机器人哪方面没过审,然后修改后再次提交审核

4(待验证).QQ审核机器人的时间不定,短则一天,多则一星期都有可能。有穿越你在QQ机器人官方频道发帖子反馈自己问题后能加快审核速度。但请做好正式上限时等待数天的准备。

### 使用海豹

目前添加官方机器人的办法有两种

第一种:在使用人员与范围页面,可以找到将你的骰子添加到群跟频道的二维码,扫码后会跳转到机器人的界面,点击添加到群聊选择自己想添加的群就好了

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

第二种:用QQ号搜索添加机器人

点击开发设置设置页面,在这里可以看到骰子的官方机器人的QQ号

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

在QQ搜索官方机器人QQ号,点击官方机器人那一条

然后进入跟骰子的消息界面,由于海豹没配置消息列表接口,所以在消息列表输入指令骰子不会有任何反应。

如果QQ是电脑端的话,点击左上的骰子名字,然后再点击添加到群聊,就可以将骰子加到你想加的群聊里了

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

如果是手机端QQ的话,在消息列表界面点击右上角的那三条杠

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

然后在聊天设置页面点击圈内一栏(注:你也可以点击下面的发起群聊建立一个新群拉入机器人)

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

跳入新界面后,点击添加到群聊就可以选择自己想添加的群了

目前不知道什么原因,除非在骰子的沙盒群,在群聊设置里群机器人一栏里,只提供了热门的群机器人,没法搜索添加骰子

::: warning

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

此外哪怕不在指令列表的指令的指令,只要@了官方机器人之外,都能正常实现,如抽取牌堆、查询帮助文档等。

开启记录log,暗投,跨群绑卡等涉及到记录群消息功能机器人在群内会正常回复,但是正常实现。

此外官方机器人一次只能发一条消息,一次性发送消息太多官方机器人会没有反应。

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

当前还没配消息列表接口,故无法跟官方机器人私聊。

:::
Loading