docs: 更新 API 文档 (#155)

Co-authored-by: st1020 <47559019+st1020@users.noreply.github.com>

docs/api/adapter/apscheduler/config.md

@@ -10,4 +10,4 @@ APScheduler 配置类，将在适配器被加载时被混入到机器人主配
 
 - **Attributes**
 
-  - **scheduler\_config** (_Dict\[str, Any\]_) - 调度器配置。
+  - **scheduler\_config** (_dict\[str, typing.Any\]_) - 调度器配置。

docs/api/adapter/apscheduler/event.md

@@ -12,7 +12,7 @@ APSchedulerEvent 事件基类。
 
   - **type** (_Optional\[str\]_)
 
-  - **plugin\_class** (_Type\[alicebot.plugin.Plugin\]_)
+  - **plugin\_class** (_Any_)
 
 ### _readonly property_ `job` {#APSchedulerEvent-job}
 
@@ -28,6 +28,6 @@ Type: _Union\[str, apscheduler.triggers.base.BaseTrigger, NoneType\]_
 
 ### _readonly property_ `trigger_args` {#APSchedulerEvent-trigger-args}
 
-Type: _Optional\[Dict\[str, Any\]\]_
+Type: _Optional\[dict\[str, Any\]\]_
 
 当前事件对应的 Plugin 的 `trigger_args`。

docs/api/adapter/apscheduler/index.md

@@ -17,7 +17,7 @@ APScheduler 适配器。
 
   - **scheduler** (_apscheduler.schedulers.asyncio.AsyncIOScheduler_)
 
-  - **plugin\_class\_to\_job** (_Dict\[Type\[alicebot.plugin.Plugin\[Any, Any, Any\]\], apscheduler.job.Job\]_)
+  - **plugin\_class\_to\_job** (_dict\[type\[alicebot.plugin.Plugin\[typing.Any, typing.Any, typing.Any\]\], apscheduler.job.Job\]_)
 
 ### _class_ `Config` {#Config}
 
@@ -27,23 +27,25 @@ APScheduler 配置类，将在适配器被加载时被混入到机器人主配
 
 - **Attributes**
 
-  - **scheduler\_config** (_Dict\[str, Any\]_) - 调度器配置。
+  - **scheduler\_config** (_dict\[str, typing.Any\]_) - 调度器配置。
 
 ### _async method_ `create_event(self, plugin_class)` {#APSchedulerAdapter-create-event}
 
 创建 `APSchedulerEvent` 事件。
 
 - **Arguments**
 
-  - **plugin\_class** (_Type\[alicebot.plugin.Plugin\[Any, Any, Any\]\]_) - `Plugin` 类。
+  - **plugin\_class** (_type\[alicebot.plugin.Plugin\[typing.Any, typing.Any, typing.Any\]\]_) - `Plugin` 类。
 
 - **Returns**
 
   Type: _None_
 
 ### _async method_ `run(self)` {#APSchedulerAdapter-run}
 
-启动调度器。
+适配器运行方法，适配器开发者必须实现该方法。
+
+适配器运行过程中保持保持运行，当此方法结束后， AliceBot 不会自动重新启动适配器。
 
 - **Returns**
 
@@ -65,15 +67,21 @@ APScheduler 适配器不适用发送消息。
 
 ### _async method_ `shutdown(self)` {#APSchedulerAdapter-shutdown}
 
-关闭调度器。
+在适配器结束运行时运行的方法，用于安全地关闭适配器。
+
+AliceBot 在接收到系统的结束信号后先发送 cancel 请求给 run 任务。
+在所有适配器都停止运行后，会依次运行并等待所有适配器的 `shutdown()` 方法。
+当强制退出时此方法可能未被执行。
 
 - **Returns**
 
   Type: _None_
 
 ### _async method_ `startup(self)` {#APSchedulerAdapter-startup}
 
-创建 `AsyncIOScheduler` 对象。
+在适配器开始运行前运行的方法，用于初始化适配器。
+
+AliceBot 依次运行并等待所有适配器的 `startup()` 方法，待运行完毕后再创建 `run()` 任务。
 
 - **Returns**
 
@@ -87,11 +95,11 @@ APScheduler 适配器不适用发送消息。
 
   - **trigger** (_str_) - APScheduler 触发器。
 
-  - **trigger\_args** (_Dict\[str, Any\]_) - APScheduler 触发器参数。
+  - **trigger\_args** (_dict\[str, typing.Any\]_) - APScheduler 触发器参数。
 
   - **override\_rule** (_bool_) - 是否重写 `rule()` 方法。
   若为 `True`，则会在 `rule()` 方法中添加处理本插件定义的计划任务事件的逻辑。
 
 - **Returns**
 
-  Type: _Callable\[\[Type\[~PluginT\]\], Type\[~PluginT\]\]_
+  Type: _Callable\[\[type\[~PluginT\]\], type\[~PluginT\]\]_

docs/api/adapter/cqhttp/event.md

@@ -92,7 +92,7 @@ CQHTTP 事件基类
 
 - **Returns**
 
-  Type: _Tuple\[Optional\[str\], Optional\[str\], Optional\[str\]\]_
+  Type: _tuple\[typing.Optional\[str\], typing.Optional\[str\], typing.Optional\[str\]\]_
 
   事件类型。
 
@@ -154,11 +154,11 @@ Bases: `alicebot.adapter.cqhttp.event.CQHTTPEvent`, `alicebot.event.MessageEvent
 
 - **Arguments**
 
-  - **message** (_Union\[List\[alicebot.adapter.cqhttp.message.CQHTTPMessageSegment\], alicebot.adapter.cqhttp.message.CQHTTPMessageSegment, str, Mapping\[str, Any\]\]_) - 回复消息的内容，同 `call_api()` 方法。
+  - **message** (_Union\[list\[alicebot.adapter.cqhttp.message.CQHTTPMessageSegment\], alicebot.adapter.cqhttp.message.CQHTTPMessageSegment, str, collections.abc.Mapping\[str, Any\]\]_) - 回复消息的内容，同 `call_api()` 方法。
 
 - **Returns**
 
-  Type: _Dict\[str, Any\]_
+  Type: _dict\[str, typing.Any\]_
 
   API 请求响应。
 
@@ -180,11 +180,11 @@ Bases: `alicebot.adapter.cqhttp.event.MessageEvent`
 
 - **Arguments**
 
-  - **message** (_Union\[List\[alicebot.adapter.cqhttp.message.CQHTTPMessageSegment\], alicebot.adapter.cqhttp.message.CQHTTPMessageSegment, str, Mapping\[str, Any\]\]_) - 回复消息的内容，同 `call_api()` 方法。
+  - **message** (_Union\[list\[alicebot.adapter.cqhttp.message.CQHTTPMessageSegment\], alicebot.adapter.cqhttp.message.CQHTTPMessageSegment, str, collections.abc.Mapping\[str, Any\]\]_) - 回复消息的内容，同 `call_api()` 方法。
 
 - **Returns**
 
-  Type: _Dict\[str, Any\]_
+  Type: _dict\[str, typing.Any\]_
 
   API 请求响应。
 
@@ -210,11 +210,11 @@ Bases: `alicebot.adapter.cqhttp.event.MessageEvent`
 
 - **Arguments**
 
-  - **message** (_Union\[List\[alicebot.adapter.cqhttp.message.CQHTTPMessageSegment\], alicebot.adapter.cqhttp.message.CQHTTPMessageSegment, str, Mapping\[str, Any\]\]_) - 回复消息的内容，同 `call_api()` 方法。
+  - **message** (_Union\[list\[alicebot.adapter.cqhttp.message.CQHTTPMessageSegment\], alicebot.adapter.cqhttp.message.CQHTTPMessageSegment, str, collections.abc.Mapping\[str, Any\]\]_) - 回复消息的内容，同 `call_api()` 方法。
 
 - **Returns**
 
-  Type: _Dict\[str, Any\]_
+  Type: _dict\[str, typing.Any\]_
 
   API 请求响应。
 
@@ -374,8 +374,6 @@ Bases: `alicebot.adapter.cqhttp.event.NoticeEvent`
 
   - **sub\_type** (_str_)
 
-  - **group\_id** (_Optional\[int\]_)
-
   - **user\_id** (_int_)
 
 ## _class_ `PokeNotifyEvent` {#PokeNotifyEvent}
@@ -438,7 +436,7 @@ Bases: `alicebot.adapter.cqhttp.event.CQHTTPEvent`
 
 - **Returns**
 
-  Type: _Dict\[str, Any\]_
+  Type: _dict\[str, typing.Any\]_
 
   API 请求响应。
 
@@ -448,7 +446,7 @@ Bases: `alicebot.adapter.cqhttp.event.CQHTTPEvent`
 
 - **Returns**
 
-  Type: _Dict\[str, Any\]_
+  Type: _dict\[str, typing.Any\]_
 
   API 请求响应。
 
@@ -478,7 +476,7 @@ Bases: `alicebot.adapter.cqhttp.event.RequestEvent`
 
 - **Returns**
 
-  Type: _Dict\[str, Any\]_
+  Type: _dict\[str, typing.Any\]_
 
   API 请求响应。
 
@@ -488,7 +486,7 @@ Bases: `alicebot.adapter.cqhttp.event.RequestEvent`
 
 - **Returns**
 
-  Type: _Dict\[str, Any\]_
+  Type: _dict\[str, typing.Any\]_
 
   API 请求响应。
 
@@ -518,7 +516,7 @@ Bases: `alicebot.adapter.cqhttp.event.RequestEvent`
 
 - **Returns**
 
-  Type: _Dict\[str, Any\]_
+  Type: _dict\[str, typing.Any\]_
 
   API 请求响应。
 
@@ -532,7 +530,7 @@ Bases: `alicebot.adapter.cqhttp.event.RequestEvent`
 
 - **Returns**
 
-  Type: _Dict\[str, Any\]_
+  Type: _dict\[str, typing.Any\]_
 
   API 请求响应。
 

docs/api/adapter/cqhttp/exceptions.md

@@ -26,7 +26,7 @@ API 请求成功响应，但响应表示 API 操作失败。
 
 - **Arguments**
 
-  - **resp** (_Dict\[str, Any\]_) - 返回的响应。
+  - **resp** (_dict\[str, typing.Any\]_) - 返回的响应。
 
 - **Returns**
 

docs/api/adapter/cqhttp/index.md

@@ -13,7 +13,7 @@ CQHTTP 协议适配器。
 
 - **Attributes**
 
-  - **event\_models** (_ClassVar\[Dict\[Tuple\[Optional\[str\], Optional\[str\], Optional\[str\]\], Type\[alicebot.adapter.cqhttp.event.CQHTTPEvent\]\]\]_)
+  - **event\_models** (_ClassVar\[dict\[tuple\[Optional\[str\], Optional\[str\], Optional\[str\]\], type\[alicebot.adapter.cqhttp.event.CQHTTPEvent\]\]\]_)
 
 ### _class_ `Config` {#Config}
 
@@ -83,7 +83,7 @@ CQHTTP 配置类，将在适配器被加载时被混入到机器人主配置中
 
 - **Returns**
 
-  Type: _Type\[alicebot.adapter.cqhttp.event.CQHTTPEvent\]_
+  Type: _type\[alicebot.adapter.cqhttp.event.CQHTTPEvent\]_
 
   对应的事件类。
 
@@ -93,7 +93,7 @@ CQHTTP 配置类，将在适配器被加载时被混入到机器人主配置中
 
 - **Arguments**
 
-  - **msg** (_Dict\[str, Any\]_) - 接收到的信息。
+  - **msg** (_dict\[str, typing.Any\]_) - 接收到的信息。
 
 - **Returns**
 
@@ -125,7 +125,7 @@ CQHTTP 配置类，将在适配器被加载时被混入到机器人主配置中
 
 - **Arguments**
 
-  - **message\_** (_Union\[List\[alicebot.adapter.cqhttp.message.CQHTTPMessageSegment\], alicebot.adapter.cqhttp.message.CQHTTPMessageSegment, str, Mapping\[str, Any\]\]_) - 消息内容，可以是 `str`, `Mapping`, `Iterable[Mapping]`,
+  - **message\_** (_Union\[list\[alicebot.adapter.cqhttp.message.CQHTTPMessageSegment\], alicebot.adapter.cqhttp.message.CQHTTPMessageSegment, str, collections.abc.Mapping\[str, Any\]\]_) - 消息内容，可以是 `str`, `Mapping`, `Iterable[Mapping]`,
   `CQHTTPMessageSegment`, `CQHTTPMessage。`
   将使用 `CQHTTPMessage` 进行封装。
 

docs/api/adapter/cqhttp/message.md

@@ -14,7 +14,7 @@ CQHTTP 消息。
 
 - **Returns**
 
-  Type: _Type\[CQHTTPMessageSegment\]_
+  Type: _type\['CQHTTPMessageSegment'\]_
 
   消息字段类。
 
@@ -86,7 +86,7 @@ QQ 表情
 
 ### _method_ `from_str(msg)` {#CQHTTPMessageSegment-from-str}
 
-用于将 `str` 转换为消息字段。
+用于将 `str` 转换为消息字段，子类应重写此方法。
 
 - **Returns**
 
@@ -110,7 +110,7 @@ QQ 表情
 
 - **Returns**
 
-  Type: _Type\[alicebot.adapter.cqhttp.message.CQHTTPMessage\]_
+  Type: _type\[alicebot.adapter.cqhttp.message.CQHTTPMessage\]_
 
   消息类。
 

docs/api/adapter/dingtalk/event.md

@@ -66,13 +66,13 @@ DingTalk 事件基类
 
   - **chatbotUserId** (_str_)
 
-  - **atUsers** (_List\[alicebot.adapter.dingtalk.event.UserInfo\]_)
+  - **atUsers** (_list\[alicebot.adapter.dingtalk.event.UserInfo\]_)
 
   - **text** (_Text_)
 
-  - **response\_msg** (_Union\[NoneType, str, Dict\[str, Any\], alicebot.adapter.dingtalk.message.DingTalkMessage\]_)
+  - **response\_msg** (_Union\[NoneType, str, dict\[str, Any\], alicebot.adapter.dingtalk.message.DingTalkMessage\]_)
 
-  - **response\_at** (_Union\[NoneType, Dict\[str, Any\], alicebot.adapter.dingtalk.message.DingTalkMessage\]_)
+  - **response\_at** (_Union\[NoneType, dict\[str, Any\], alicebot.adapter.dingtalk.message.DingTalkMessage\]_)
 
 ### _method_ `get_plain_text(self)` {#DingTalkEvent-get-plain-text}
 
@@ -106,13 +106,13 @@ Type: _alicebot.adapter.dingtalk.message.DingTalkMessage_
 
 - **Arguments**
 
-  - **message** (_Union\[str, Dict\[str, Any\], alicebot.adapter.dingtalk.message.DingTalkMessage\]_) - 回复消息的内容，可以是 `str`, `Dict` 或 `DingTalkMessage`。
+  - **message** (_Union\[str, dict\[str, Any\], alicebot.adapter.dingtalk.message.DingTalkMessage\]_) - 回复消息的内容，可以是 `str`, `Dict` 或 `DingTalkMessage`。
 
-  - **at** (_Union\[NoneType, Dict\[str, Any\], alicebot.adapter.dingtalk.message.DingTalkMessage\]_) - 回复消息时 At 的对象，必须时 at 类型的 `DingTalkMessage`，或者符合标准的 `Dict`。
+  - **at** (_Union\[NoneType, dict\[str, Any\], alicebot.adapter.dingtalk.message.DingTalkMessage\]_) - 回复消息时 At 的对象，必须时 at 类型的 `DingTalkMessage`，或者符合标准的 `Dict`。
 
 - **Returns**
 
-  Type: _Dict\[str, Any\]_
+  Type: _dict\[str, typing.Any\]_
 
   调用 Webhook 地址后钉钉服务器的响应。
 

docs/api/adapter/dingtalk/index.md

@@ -69,7 +69,9 @@ DingTalk 配置类，将在适配器被加载时被混入到机器人主配置
 
 ### _async method_ `run(self)` {#DingTalkAdapter-run}
 
-运行 aiohttp 服务器。
+适配器运行方法，适配器开发者必须实现该方法。
+
+适配器运行过程中保持保持运行，当此方法结束后， AliceBot 不会自动重新启动适配器。
 
 - **Returns**
 
@@ -85,13 +87,13 @@ DingTalk 配置类，将在适配器被加载时被混入到机器人主配置
 
   - **conversation\_type** (_Literal\['1', '2'\]_) - 聊天类型，"1" 表示单聊，"2" 表示群聊。
 
-  - **msg** (_Union\[str, Dict\[str, Any\], alicebot.adapter.dingtalk.message.DingTalkMessage\]_) - 消息。
+  - **msg** (_Union\[str, dict\[str, Any\], alicebot.adapter.dingtalk.message.DingTalkMessage\]_) - 消息。
 
-  - **at** (_Union\[NoneType, Dict\[str, Any\], alicebot.adapter.dingtalk.message.DingTalkMessage\]_) - At 对象，仅在群聊时生效，默认为空。
+  - **at** (_Union\[NoneType, dict\[str, Any\], alicebot.adapter.dingtalk.message.DingTalkMessage\]_) - At 对象，仅在群聊时生效，默认为空。
 
 - **Returns**
 
-  Type: _Dict\[str, Any\]_
+  Type: _dict\[str, typing.Any\]_
 
   钉钉服务器的响应。
 
@@ -105,15 +107,21 @@ DingTalk 配置类，将在适配器被加载时被混入到机器人主配置
 
 ### _async method_ `shutdown(self)` {#DingTalkAdapter-shutdown}
 
-清理 aiohttp AppRunner。
+在适配器结束运行时运行的方法，用于安全地关闭适配器。
+
+AliceBot 在接收到系统的结束信号后先发送 cancel 请求给 run 任务。
+在所有适配器都停止运行后，会依次运行并等待所有适配器的 `shutdown()` 方法。
+当强制退出时此方法可能未被执行。
 
 - **Returns**
 
   Type: _None_
 
 ### _async method_ `startup(self)` {#DingTalkAdapter-startup}
 
-创建 aiohttp Application。
+在适配器开始运行前运行的方法，用于初始化适配器。
+
+AliceBot 依次运行并等待所有适配器的 `startup()` 方法，待运行完毕后再创建 `run()` 任务。
 
 - **Returns**