mirror of
https://github.com/nonebot/nonebot2.git
synced 2025-07-27 16:21:28 +00:00
📝 update doc
This commit is contained in:
yanyongyu
78
docs/guide/cqhttp-guide.md
Normal file
78
docs/guide/cqhttp-guide.md
Normal file
@ -0,0 +1,78 @@
|
||||
# CQHTTP 协议使用指南
|
||||
|
||||
## 配置 CQHTTP 协议端（以 QQ 为例）
|
||||
|
||||
单纯运行 NoneBot 实例并不会产生任何效果，因为此刻 QQ 这边还不知道 NoneBot 的存在，也就无法把消息发送给它，因此现在需要使用一个无头 QQ 来把消息等事件上报给 NoneBot。
|
||||
|
||||
QQ 协议端举例:
|
||||
|
||||
- [go-cqhttp](https://github.com/Mrs4s/go-cqhttp) (基于 [MiraiGo](https://github.com/Mrs4s/MiraiGo))
|
||||
- [cqhttp-mirai-embedded](https://github.com/yyuueexxiinngg/cqhttp-mirai/tree/embedded)
|
||||
- [Mirai](https://github.com/mamoe/mirai) + [cqhttp-mirai](https://github.com/yyuueexxiinngg/cqhttp-mirai)
|
||||
- [Mirai](https://github.com/mamoe/mirai) + [Mirai Native](https://github.com/iTXTech/mirai-native) + [CQHTTP](https://github.com/richardchien/coolq-http-api)
|
||||
- [OICQ-http-api](https://github.com/takayama-lily/onebot) (基于 [OICQ](https://github.com/takayama-lily/oicq))
|
||||
|
||||
这里以 [go-cqhttp](https://github.com/Mrs4s/go-cqhttp) 为例
|
||||
|
||||
1. 下载 go-cqhttp 对应平台的 release 文件，[点此前往](https://github.com/Mrs4s/go-cqhttp/releases)
|
||||
2. 运行 exe 文件或者使用 `./go-cqhttp` 启动
|
||||
3. 生成默认配置文件并修改默认配置
|
||||
|
||||
```hjson{2,3,35-36,42}
|
||||
{
|
||||
uin: 机器人QQ号
|
||||
password: 机器人密码
|
||||
encrypt_password: false
|
||||
password_encrypted: ""
|
||||
enable_db: true
|
||||
access_token: ""
|
||||
relogin: {
|
||||
enabled: true
|
||||
relogin_delay: 3
|
||||
max_relogin_times: 0
|
||||
}
|
||||
_rate_limit: {
|
||||
enabled: false
|
||||
frequency: 1
|
||||
bucket_size: 1
|
||||
}
|
||||
ignore_invalid_cqcode: false
|
||||
force_fragmented: false
|
||||
heartbeat_interval: 0
|
||||
http_config: {
|
||||
enabled: false
|
||||
host: "0.0.0.0"
|
||||
port: 5700
|
||||
timeout: 0
|
||||
post_urls: {}
|
||||
}
|
||||
ws_config: {
|
||||
enabled: false
|
||||
host: "0.0.0.0"
|
||||
port: 6700
|
||||
}
|
||||
ws_reverse_servers: [
|
||||
{
|
||||
enabled: true
|
||||
reverse_url: ws://127.0.0.1:8080/cqhttp/ws
|
||||
reverse_api_url: ws://you_websocket_api.server
|
||||
reverse_event_url: ws://you_websocket_event.server
|
||||
reverse_reconnect_interval: 3000
|
||||
}
|
||||
]
|
||||
post_message_format: array
|
||||
use_sso_address: false
|
||||
debug: false
|
||||
log_level: ""
|
||||
web_ui: {
|
||||
enabled: false
|
||||
host: 127.0.0.1
|
||||
web_ui_port: 9999
|
||||
web_input: false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
其中 `ws://127.0.0.1:8080/cqhttp/ws` 中的 `127.0.0.1` 和 `8080` 应分别对应 nonebot 配置的 HOST 和 PORT。
|
||||
|
||||
`cqhttp` 是前述 `register_adapter` 时传入的第一个参数，代表设置的 `CQHTTPBot` 适配器的路径，你可以对不同的适配器设置不同路径以作区别。
|
||||
@ -6,14 +6,14 @@
|
||||
|
||||
```python{1,2,8,9}
|
||||
@weather.handle()
|
||||
async def handle_first_receive(bot: Bot, event: Event, state: State):
|
||||
args = str(event.message).strip() # 首次发送命令时跟随的参数，例：/天气 上海，则args为上海
|
||||
async def handle_first_receive(bot: Bot, event: Event, state: T_State):
|
||||
args = str(event.get_message()).strip() # 首次发送命令时跟随的参数，例：/天气 上海，则args为上海
|
||||
if args:
|
||||
state["city"] = args # 如果用户发送了参数则直接赋值
|
||||
|
||||
|
||||
@weather.got("city", prompt="你想查询哪个城市的天气呢？")
|
||||
async def handle_city(bot: Bot, event: Event, state: State):
|
||||
async def handle_city(bot: Bot, event: Event, state: T_State):
|
||||
city = state["city"]
|
||||
if city not in ["上海", "北京"]:
|
||||
await weather.reject("你想查询的城市暂不支持，请重新输入！")
|
||||
@ -53,12 +53,12 @@ async def handle_city(bot: Bot, event: Event, state: State):
|
||||
|
||||
```python
|
||||
@matcher.receive()
|
||||
async def handle(bot: Bot, event: Event, state: State):
|
||||
async def handle(bot: Bot, event: Event, state: T_State):
|
||||
state["key"] = "hello"
|
||||
|
||||
|
||||
@matcher.got("key2", prompt="{key}!")
|
||||
async def handle2(bot: Bot, event: Event, state: State):
|
||||
async def handle2(bot: Bot, event: Event, state: T_State):
|
||||
pass
|
||||
```
|
||||
|
||||
@ -75,17 +75,55 @@ async def handle(bot: Bot, event: Event, state: State):
|
||||
|
||||
### 事件处理函数参数
|
||||
|
||||
事件处理函数类型为 `Callable[[Bot, Event, State], Union[Awaitable[None], Awaitable[NoReturn]]]` 。
|
||||
事件处理函数类型为：
|
||||
|
||||
- `Callable[[Bot, Event, T_State, Matcher], Union[Awaitable[None], Awaitable[NoReturn]]]`
|
||||
- `Callable[[Bot, Event, T_State], Union[Awaitable[None], Awaitable[NoReturn]]]`
|
||||
- `Callable[[Bot, Event, Matcher], Union[Awaitable[None], Awaitable[NoReturn]]]`
|
||||
- `Callable[[Bot, T_State, Matcher], Union[Awaitable[None], Awaitable[NoReturn]]]`
|
||||
- `Callable[[Bot, Event], Union[Awaitable[None], Awaitable[NoReturn]]]`
|
||||
- `Callable[[Bot, T_State], Union[Awaitable[None], Awaitable[NoReturn]]]`
|
||||
- `Callable[[Bot, Matcher], Union[Awaitable[None], Awaitable[NoReturn]]]`
|
||||
- `Callable[[Bot], Union[Awaitable[None], Awaitable[NoReturn]]]`
|
||||
|
||||
简单说就是：除了 `bot` 参数，其他都是可选的。
|
||||
|
||||
以下函数都是合法的事件处理函数（仅列举常用的）：
|
||||
|
||||
```python
|
||||
async def handle(bot: Bot, event: Event, state: T_State):
|
||||
pass
|
||||
|
||||
async def handle(bot: Bot, event: Event, state: T_State, matcher: Matcher):
|
||||
pass
|
||||
|
||||
async def handle(bot: Bot, event: Event):
|
||||
pass
|
||||
|
||||
async def handle(bot: Bot, state: T_State):
|
||||
pass
|
||||
|
||||
async def handle(bot: Bot):
|
||||
pass
|
||||
```
|
||||
|
||||
:::danger 警告
|
||||
函数的参数名固定不能修改！
|
||||
:::
|
||||
|
||||
参数分别为：
|
||||
|
||||
1. [nonebot.adapters.Bot](../api/adapters/#class-bot): 即事件上报连接对应的 Bot 对象，为 BaseBot 的子类。特别注意，此处的类型注释可以替换为指定的 Bot 类型，例如：`nonebot.adapters.cqhttp.Bot`，只有在上报事件的 Bot 类型与类型注释相符时才会执行该处理函数！可用于多平台进行不同的处理。
|
||||
2. [nonebot.adapters.Event](../api/adapters/#class-event): 即上报事件对象，可以获取到上报的所有信息。
|
||||
3. [state](../api/typing.md#state): 状态字典，可以存储任意的信息，其中还包含一些特殊的值以获取 NoneBot 内部处理时的一些信息，如：
|
||||
3. [state](../api/typing.md#t-state): 状态字典，可以存储任意的信息，其中还包含一些特殊的值以获取 NoneBot 内部处理时的一些信息，如：
|
||||
|
||||
- `state["_current_key"]`: 存储当前 `got` 获取的参数名
|
||||
- `state["_prefix"]`, `state["_suffix"]`: 存储当前 TRIE 匹配的前缀/后缀，可以通过该值获取用户命令的原始命令
|
||||
|
||||
:::tip 提示
|
||||
NoneBot 会对不同类型的参数进行不同的操作，详情查看 [事件处理函数重载](../advanced/overloaded-handlers.md)
|
||||
:::
|
||||
|
||||
### 参数处理函数 args_parser
|
||||
|
||||
在使用 `got` 获取用户输入参数时，需要对用户的消息进行处理以转换为我们所需要的信息。在默认情况下，NoneBot 会把用户的消息字符串原封不动的赋值给 `state[key]` 。可以通过以下两种方式修改默认处理逻辑：
|
||||
@ -93,11 +131,11 @@ async def handle(bot: Bot, event: Event, state: State):
|
||||
- `@matcher.args_parser` 装饰器：直接装饰一个函数作为参数处理器
|
||||
- `got(key, prompt, args_parser)`：直接把函数作为参数传入
|
||||
|
||||
参数处理函数类型为：`Callable[[Bot, Event, State], Union[Awaitable[None], Awaitable[NoReturn]]]`，即：
|
||||
参数处理函数类型为：`Callable[[Bot, Event, T_State], Union[Awaitable[None], Awaitable[NoReturn]]]`，即：
|
||||
|
||||
```python
|
||||
async def parser(bot: Bot, event: Event, state: State):
|
||||
state[state["_current_key"]] = str(event.message)
|
||||
async def parser(bot: Bot, event: Event, state: T_State):
|
||||
state[state["_current_key"]] = str(event.get_message())
|
||||
```
|
||||
|
||||
特别的，`state["_current_key"]` 中存储了当前获取的参数名
|
||||
@ -132,15 +170,15 @@ matcher = on_command("test")
|
||||
# 修改默认参数处理
|
||||
@matcher.args_parser
|
||||
async def parse(bot: Bot, event: Event, state: State):
|
||||
print(state["_current_key"], ":", str(event.message))
|
||||
state[state["_current_key"]] = str(event.message)
|
||||
print(state["_current_key"], ":", str(event.get_message()))
|
||||
state[state["_current_key"]] = str(event.get_message())
|
||||
|
||||
@matcher.handle()
|
||||
async def first_receive(bot: Bot, event: Event, state: State):
|
||||
# 获取用户原始命令，如：/test
|
||||
print(state["_prefix"]["raw_command"])
|
||||
# 处理用户输入参数，如：/test arg1 arg2
|
||||
raw_args = str(event.message).strip()
|
||||
raw_args = str(event.get_message()).strip()
|
||||
if raw_args:
|
||||
arg_list = raw_args.split()
|
||||
# 将参数存入state以阻止后续再向用户询问参数
|
||||
|
||||
@ -7,15 +7,15 @@
|
||||
```python
|
||||
from nonebot import on_command
|
||||
from nonebot.rule import to_me
|
||||
from nonebot.typing import State
|
||||
from nonebot.adapters.cqhttp import Bot, Event
|
||||
from nonebot.typing import T_State
|
||||
from nonebot.adapters import Bot, Event
|
||||
|
||||
weather = on_command("天气", rule=to_me(), priority=5)
|
||||
|
||||
|
||||
@weather.handle()
|
||||
async def handle_first_receive(bot: Bot, event: Event, state: State):
|
||||
args = str(event.message).strip() # 首次发送命令时跟随的参数，例：/天气 上海，则args为上海
|
||||
async def handle_first_receive(bot: Bot, event: Event, state: T_State):
|
||||
args = str(event.get_message()).strip() # 首次发送命令时跟随的参数，例：/天气 上海，则args为上海
|
||||
if args:
|
||||
state["city"] = args # 如果用户发送了参数则直接赋值
|
||||
|
||||
@ -63,7 +63,7 @@ weather = on_command("天气", rule=to_me(), permission=Permission(), priority=5
|
||||
|
||||
### 事件响应器类型 type
|
||||
|
||||
事件响应器类型其实就是对应事件的类型 `Event.type` ，NoneBot 提供了一个基础类型事件响应器 `on()` 以及一些其他内置的事件响应器。
|
||||
事件响应器类型其实就是对应事件的类型 `Event.get_type()` ，NoneBot 提供了一个基础类型事件响应器 `on()` 以及一些其他内置的事件响应器。
|
||||
|
||||
以下所有类型的事件响应器都是由 `on(type, rule)` 的形式进行了简化封装。
|
||||
|
||||
@ -92,6 +92,7 @@ weather = on_command("天气", rule=to_me(), permission=Permission(), priority=5
|
||||
```bash
|
||||
nb plugin install nonebot_plugin_test
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
### 阻断 block
|
||||
|
||||
3
docs/guide/ding-guide.md
Normal file
3
docs/guide/ding-guide.md
Normal file
@ -0,0 +1,3 @@
|
||||
# 钉钉机器人使用指南
|
||||
|
||||
~~TODO~~
|
||||
@ -57,86 +57,19 @@ python bot.py
|
||||
09-14 21:02:00 [INFO] uvicorn | Uvicorn running on http://127.0.0.1:8080 (Press CTRL+C to quit)
|
||||
```
|
||||
|
||||
## 配置 CQHTTP 协议端（以 QQ 为例）
|
||||
## 配置协议端
|
||||
|
||||
单纯运行 NoneBot 实例并不会产生任何效果，因为此刻 QQ 这边还不知道 NoneBot 的存在，也就无法把消息发送给它，因此现在需要使用一个无头 QQ 来把消息等事件上报给 NoneBot。
|
||||
在 `bot.py` 文件中使用 `register_adapter` 注册协议适配之后即可配置协议端来完成与 NoneBot 的通信，详细配置方法参考：
|
||||
|
||||
QQ 协议端举例:
|
||||
- [配置 CQHTTP](./cqhttp-guide.md)
|
||||
- [配置钉钉](./ding-guide.md)
|
||||
|
||||
- [go-cqhttp](https://github.com/Mrs4s/go-cqhttp) (基于 [MiraiGo](https://github.com/Mrs4s/MiraiGo))
|
||||
- [cqhttp-mirai-embedded](https://github.com/yyuueexxiinngg/cqhttp-mirai/tree/embedded)
|
||||
- [Mirai](https://github.com/mamoe/mirai) + [cqhttp-mirai](https://github.com/yyuueexxiinngg/cqhttp-mirai)
|
||||
- [Mirai](https://github.com/mamoe/mirai) + [Mirai Native](https://github.com/iTXTech/mirai-native) + [CQHTTP](https://github.com/richardchien/coolq-http-api)
|
||||
- [OICQ-http-api](https://github.com/takayama-lily/onebot) (基于 [OICQ](https://github.com/takayama-lily/oicq))
|
||||
NoneBot 接受的上报地址与 `Driver` 有关，默认使用的 `FastAPI Driver` 所接受的上报地址有：
|
||||
|
||||
这里以 [go-cqhttp](https://github.com/Mrs4s/go-cqhttp) 为例
|
||||
|
||||
1. 下载 go-cqhttp 对应平台的 release 文件，[点此前往](https://github.com/Mrs4s/go-cqhttp/releases)
|
||||
2. 运行 exe 文件或者使用 `./go-cqhttp` 启动
|
||||
3. 生成默认配置文件并修改默认配置
|
||||
|
||||
```hjson{2,3,35-36,42}
|
||||
{
|
||||
uin: 机器人QQ号
|
||||
password: 机器人密码
|
||||
encrypt_password: false
|
||||
password_encrypted: ""
|
||||
enable_db: true
|
||||
access_token: ""
|
||||
relogin: {
|
||||
enabled: true
|
||||
relogin_delay: 3
|
||||
max_relogin_times: 0
|
||||
}
|
||||
_rate_limit: {
|
||||
enabled: false
|
||||
frequency: 1
|
||||
bucket_size: 1
|
||||
}
|
||||
ignore_invalid_cqcode: false
|
||||
force_fragmented: false
|
||||
heartbeat_interval: 0
|
||||
http_config: {
|
||||
enabled: false
|
||||
host: "0.0.0.0"
|
||||
port: 5700
|
||||
timeout: 0
|
||||
post_urls: {}
|
||||
}
|
||||
ws_config: {
|
||||
enabled: false
|
||||
host: "0.0.0.0"
|
||||
port: 6700
|
||||
}
|
||||
ws_reverse_servers: [
|
||||
{
|
||||
enabled: true
|
||||
reverse_url: ws://127.0.0.1:8080/cqhttp/ws
|
||||
reverse_api_url: ws://you_websocket_api.server
|
||||
reverse_event_url: ws://you_websocket_event.server
|
||||
reverse_reconnect_interval: 3000
|
||||
}
|
||||
]
|
||||
post_message_format: array
|
||||
use_sso_address: false
|
||||
debug: false
|
||||
log_level: ""
|
||||
web_ui: {
|
||||
enabled: false
|
||||
host: 127.0.0.1
|
||||
web_ui_port: 9999
|
||||
web_input: false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
其中 `ws://127.0.0.1:8080/cqhttp/ws` 中的 `127.0.0.1` 和 `8080` 应分别对应 nonebot 配置的 HOST 和 PORT。
|
||||
|
||||
`cqhttp` 是前述 `register_adapter` 时传入的第一个参数，代表设置的 `CQHTTPBot` 适配器的路径，你可以对不同的适配器设置不同路径以作区别。
|
||||
|
||||
## 配置钉钉
|
||||
|
||||
~~TODO~~
|
||||
- `/{adapter name}/`: HTTP POST 上报
|
||||
- `/{adapter name}/http/`: HTTP POST 上报
|
||||
- `/{adapter name}/ws`: WebSocket 上报
|
||||
- `/{adapter name}/ws/`: WebSocket 上报
|
||||
|
||||
## 历史性的第一次对话
|
||||
|
||||
|
||||
Reference in New Issue
Block a user