update 完善文档

docs/.vitepress/nav/navbar.js

@@ -1,3 +1,5 @@
+import { adapters } from './sidebar'
+
 export default [
     {
         text: '主页',
@@ -11,80 +13,25 @@ export default [
         ]
     },
     {
-        text: '基础指南',
+        text: '开发指南',
         items: [
-            {
-                text: '起步',
-                items: [
-                    { text: '开始使用', link: '/develop/basic/index.md' },
-                    { text: '注册消息响应', link: '/develop/basic/messageHandler.md' },
-                    { text: '构建回复消息', link: '/develop/basic/sendMessage.html#构建消息的方法' },
-                    { text: '事件监听', link: '/develop/basic/handleEvents.md' },
-                    { text: '异常监听', link: '/develop/basic/handleException.md' },
-                    { text: '测试', link: '/develop/basic/testInstance.md' }
-                ]
-            },
-            {
-                text: 'API',
-                items: [
-                    { text: '使用说明', link: '/develop/basic/api/index.md' },
-                    { text: 'QQ 频道', link: '/develop/basic/api/qqbot.md' }
-                ]
-            },
-            {
-                text: '适配器',
-                items: [
-                    { text: 'QQ频道机器人', link: '/develop/adapters/qqChannel.md' },
-                    { text: 'KOOK机器人', link: '/develop/adapters/kook.md' },
-                    { text: 'Mirai-Api-Http', link: '/develop/adapters/mah.md' },
-                    { text: 'Go-CQHttp', link: '/develop/adapters/gocq.md' },
-                    { text: 'ComWeChatBot Client', link: '/develop/adapters/comwechat.md' },
-                    { text: 'OneBot 11', link: '/develop/adapters/onebot11.md' },
-                    { text: 'OneBot 12', link: '/develop/adapters/onebot12.md' },
-                ]
-            }
+            { text: '基础指南', link: '/develop/basic/index.md' },
+            { text: '进阶指南', link: '/develop/advanced/' },
+            { text: '插件开发', link: '/develop/plugin/' },
         ]
     },
     {
-        text: '进阶指南',
-        items: [
-            {
-                text: '进阶开发',
-                items: [
-                    { text: '生命周期', link: '/develop/advanced/lifeCycle.md' },
-                    { text: '定时任务', link: '/develop/advanced/timedTask.md' },
-                    { text: '事件总线', link: '/develop/advanced/eventBus.md' },
-                    { text: '日志模块', link: '/develop/advanced/logger.md' },
-                    { text: '加载插件', link: '/develop/advanced/loadPlugins.md' }
-                ]
-            },
-            {
-                text: '辅助',
-                items: [
-                    { text: 'HTTP 请求', link: '/develop/advanced/httpRequests.md' },
-                    { text: '处理 IO 阻塞的操作', link: '/develop/advanced/blockingIO.md' },
-                    { text: '改变 Playwright 启动', link: '/develop/advanced/playwright.md' },
-                    { text: '启动参数', link: '/develop/advanced/startupParameter.md' }
-                ]
-            },
-            {
-                text: '额外支持',
-                items: [
-                    { text: 'HTTP 服务器', link: '/develop/advanced/httpSupport.md' },
-                    { text: '数据库', link: '/develop/advanced/databaseSupport.md' }
-                ]
-            }
-        ]
-    },
-    {
-        text: '插件开发',
-        link: '/develop/plugin/'
+        text: '适配器',
+        items: adapters
     },
     {
-        text: 'AmiyaBot-demo-V6',
+        text: '兔兔-V6',
         items: [
-            { text: '部署', link: '/guide/deploy/' },
-            { text: '常见问题', link: '/guide/deploy/faq/commonProblem' }
+            { text: '开始部署', link: '/guide/deploy/' },
+            { text: '常见问题', link: '/guide/deploy/faq/commonProblem' },
+            { text: '连接控制台', link: '/guide/deploy/console/index.md' },
+            { text: '如何更新', link: '/guide/deploy/maintain/upgrade.md' },
+            { text: '高级使用', link: '/guide/deploy/advanced/index.md' },
         ]
     },
     {

docs/.vitepress/nav/sidebar.js

@@ -1,3 +1,15 @@
+export const adapters = [
+    { text: 'QQ频道机器人', link: '/develop/adapters/qqChannel.md' },
+    { text: 'QQ群机器人', link: '/develop/adapters/qqGroup.md' },
+    { text: 'KOOK机器人', link: '/develop/adapters/kook.md' },
+    { text: 'Mirai-Api-Http', link: '/develop/adapters/mah.md' },
+    { text: 'Go-CQHttp', link: '/develop/adapters/gocq.md' },
+    { text: 'ComWeChatBot Client', link: '/develop/adapters/comwechat.md' },
+    { text: 'OneBot 11', link: '/develop/adapters/onebot11.md' },
+    { text: 'OneBot 12', link: '/develop/adapters/onebot12.md' },
+
+]
+
 export default {
     '/develop/basic/': [
         {
@@ -86,13 +98,7 @@ export default {
             collapsible: true,
             items: [
                 { text: '说明', link: '/develop/adapters/index.md' },
-                { text: 'QQ频道机器人', link: '/develop/adapters/qqChannel.md' },
-                { text: 'KOOK机器人', link: '/develop/adapters/kook.md' },
-                { text: 'Mirai-Api-Http', link: '/develop/adapters/mah.md' },
-                { text: 'Go-CQHttp', link: '/develop/adapters/gocq.md' },
-                { text: 'ComWeChatBot Client', link: '/develop/adapters/comwechat.md' },
-                { text: 'OneBot 11', link: '/develop/adapters/onebot11.md' },
-                { text: 'OneBot 12', link: '/develop/adapters/onebot12.md' },
+                ...adapters
             ]
         }
     ],
@@ -106,7 +112,8 @@ export default {
                 { text: '定时任务', link: '/develop/advanced/timedTask.md' },
                 { text: '事件总线', link: '/develop/advanced/eventBus.md' },
                 { text: '日志模块', link: '/develop/advanced/logger.md' },
-                { text: '加载插件', link: '/develop/advanced/loadPlugins.md' }
+                { text: '加载插件', link: '/develop/advanced/loadPlugins.md' },
+                { text: '介入媒体消息', link: '/develop/advanced/chainBuilder.md' },
             ]
         },
         {
@@ -175,8 +182,8 @@ export default {
             text: '准备',
             collapsible: true,
             items: [
-                { text: '部署AmiyaBot-demo-v6', link: '/guide/deploy/index.md' },
-                { text: '选择你的运营方', link: '/guide/deploy/yourChoose.md' },
+                { text: '部署兔兔-v6', link: '/guide/deploy/index.md' },
+                // { text: '选择你的运营方', link: '/guide/deploy/yourChoose.md' },
                 { text: '开始部署', link: '/guide/deploy/getStarted.md' },
             ]
         },

docs/develop/adapters/qqGroup.md

@@ -0,0 +1,94 @@
+# QQ 群机器人 <span class="beta-tag">Beta</span>
+
+在 [QQ 开放平台](https://bot.q.qq.com/wiki/#_2-%E4%BC%81%E4%B8%9A%E4%B8%BB%E4%BD%93%E5%85%A5%E9%A9%BB) 完成企业主体入驻，即可创建可在
+QQ 群聊里使用的 QQ 群机器人。
+
+## 在公网下使用
+
+QQ 群聊适配器需要在本地启动资源服务让腾讯端能够访问媒体资源，默认在公网下使用。
+
+```python
+from amiyabot.adapters.tencent.qqGroup import qq_group
+
+client_secret = '******' # 密钥
+
+bot = AmiyaBot(appid='******', token='******', adapter=qq_group(client_secret))
+```
+
+- 在机器人启动时，资源服务也会一同启动。
+- 默认的资源服务是端口单例的，实例化多个 QQ 群聊适配器 AmiyaBot 或使用 [多账号](/develop/basic/multipleAccounts.html)
+  时，同一个端口的资源服务会相互共享。
+
+### 修改资源服务配置
+
+引入 `QQGroupChainBuilderOptions` 修改默认的资源服务配置。
+
+| 参数名                 | 类型   | 释义                                                        | 默认值        |
+|---------------------|------|-----------------------------------------------------------|------------|
+| host                | str  | 资源服务监听地址                                                  | 0.0.0.0    |
+| port                | int  | 资源服务监听端口                                                  | 8086       |
+| resource_path       | str  | 临时文件存放目录                                                  | ./resource |
+| http_server_options | dict | [HttpServer **kwargs](/develop/advanced/httpSupport.html) |            |
+
+```python
+from amiyabot.adapters.tencent.qqGroup import qq_group
+from amiyabot.adapters.tencent.qqGroup.builder import QQGroupChainBuilderOptions
+
+bot = AmiyaBot(
+    appid='******',
+    token='******',
+    adapter=qq_group(
+        client_secret='******',
+        default_chain_builder_options=QQGroupChainBuilderOptions(
+            '0.0.0.0',
+            8086,
+            './resource',
+        ),
+    ),
+)
+```
+
+## 自定义资源服务
+
+多数情况下我们推荐使用第三方托管服务来搭建资源服务，如 [腾讯云COS](https://www.baidu.com/s?wd=%E8%85%BE%E8%AE%AF%E4%BA%91COS)
+或 [阿里云OSS](https://www.baidu.com/s?wd=%E9%98%BF%E9%87%8C%E4%BA%91OSS) 等。
+
+通过自定义默认的 `ChainBuilder`，来实现上传文件到托管服务以及返回生成的 url。
+
+普通 ChainBuilder 可参考 [进阶指南 - 介入媒体消息](/develop/advanced/chainBuilder.md)
+，但在这里更推荐继承适配器中的 `QQGroupChainBuilder`。
+
+### 普通 ChainBuilder
+
+```python
+from typing import Union
+from graiax import silkcoder
+from amiyabot import ChainBuilder
+
+class MyBuilder(ChainBuilder):
+    @classmethod
+    async def get_image(cls, image: Union[str, bytes]) -> Union[str, bytes]:
+        # 上传图片到第三方托管服务
+        ...
+        return url # 返回访问资源的 URL
+
+    @classmethod
+    async def get_voice(cls, voice_file: str) -> str:
+        # 上传语音文件到第三方托管服务，语音文件必须是 silk 格式
+        voice: bytes = await silkcoder.async_encode(voice_file, ios_adaptive=True)
+        ...
+        return url # 返回访问资源的 URL
+
+    @classmethod
+    async def get_video(cls, video_file: str) -> str:
+        # 上传视频文件到第三方托管服务
+        ...
+        return url # 返回访问资源的 URL
+
+
+bot = AmiyaBot(..., adapter=qq_group(default_chain_builder=MyBuilder()))
+```
+
+### 继承 QQGroupChainBuilder
+
+🚧 文档编写中... 🚧

docs/develop/advanced/chainBuilder.md

@@ -0,0 +1,90 @@
+# 介入 Chain 构建媒体消息时的操作
+
+Chain 对象在构建消息时，可使用辅助类介入媒体消息或浏览器的构建过程。
+
+## 创建辅助类
+
+继承 `ChainBuilder` 类并覆写其方法创建一个自定义的辅助类。在实例化 Chain 时，传入辅助类实例即可介入 Chain 的操作。
+
+```python
+from typing import Union
+from amiyabot import Chain, ChainBuilder
+from playwright.async_api import Page
+
+class MyBuilder(ChainBuilder):
+    @classmethod
+    async def get_image(cls, image: Union[str, bytes]) -> Union[str, bytes]:
+        ...
+        return image
+
+    @classmethod
+    async def get_voice(cls, voice_file: str) -> str:
+        ...
+        return voice_file
+
+    @classmethod
+    async def get_video(cls, video_file: str) -> str:
+        ...
+        return video_file
+
+    @classmethod
+    async def on_page_rendered(cls, page: Page):
+        ...
+
+
+# 在构造参数里使用辅助类
+chain = Chain(..., chain_builder=MyBuilder())
+
+# 为属性赋值使用辅助类
+chain.builder = MyBuilder()
+```
+
+## get_image
+
+该函数会在 chain 构建图片消息时调用，每张图片调用一次。传入一个参数 `image` ，类型为 `str`（文件路径或 url） 或
+`bytes`（图片字节数据）。<br>
+如果函数有返回值（必须是以上两种类型），chain 会使用返回值构建图片消息。
+
+## get_voice
+
+该函数会在 chain 构建语音消息时调用，每个语音文件调用一次。传入文件路径 `voice_file`。<br>
+如果函数有返回值，chain 会使用返回值构建语音消息。
+
+## get_video
+
+该函数会在 chain 构建视频消息时调用，每个视频文件调用一次。传入文件路径 `video_file`。<br>
+如果函数有返回值，chain 会使用返回值构建视频消息。
+
+## on_page_rendered
+
+该函数会在 chain 构建浏览器渲染的图片并打开了页面时调用，提供了浏览器的 `Page` 对象，可在此对 `Page` 进行操作（如对页面进行
+JS 注入等）。
+
+::: tip 提示
+构建浏览器渲染的图片同样也会调用一次 `get_image` 函数。
+:::
+
+**使用示例**
+
+```python
+class BaiduSearch(ChainBuilder):
+    @classmethod
+    async def on_page_rendered(cls, page: Page):
+        """
+        可以在截图前先对页面进行操作，比如 ”百度一下“
+        """
+        await page.locator('#kw').fill('AmiyaBot')
+        await page.locator('#su').click()
+        await asyncio.sleep(2)
+
+
+@bot.on_message(keywords='hello')
+async def _(data: Message):
+    chain = Chain(data, chain_builder=BaiduSearch())
+
+    return chain.html(
+        'https://www.baidu.com/',
+        is_template=False,
+        render_time=1000,
+    )
+```

docs/develop/advanced/httpRequests.md

@@ -22,9 +22,41 @@ await http_requests.request()
 await download_async()
 ```
 
-`http_requests` 的请求均返回**字符串**的请求结果。`download_async` 方法则默认返回 **bytes** 结果。
+## 返回值
 
-## GET
+`http_requests` 的请求均返回**字符串**的请求结果（如果请求失败会返回空字符串），但有些不一样。这个 “字符串” 可以使用一些额外的属性。
+
+### json
+
+调用这个属性会尝试返回 json 格式化的 `responseText` 内容。
+
+```python
+res = await http_requests.post('/interface', {...})
+if res:
+    data = res.json['data']
+```
+
+### response
+
+调用这个属性可以返回请求结果（`aiohttp.ClientResponse` 的实例），可以获取请求的状态码和其他信息。
+
+```python
+res = await http_requests.post('/interface', {...})
+
+status = res.response.status
+```
+
+### error
+
+如果请求失败，可以调用这个属性获取异常（`Exception` 的实例）。
+
+```python
+res = await http_requests.post('/interface', {...})
+
+error = res.error
+```
+
+## GET 请求
 
 ```python
 res: str = await http_requests.get()
@@ -35,7 +67,7 @@ res: str = await http_requests.get()
 | interface | str | 请求地址                                                                                 |     |
 | **kwargs  |     | [request 参数](https://github.com/aio-libs/aiohttp/blob/master/aiohttp/client.py#L316) |     |
 
-## POST
+## POST 请求
 
 post 方法默认在请求头内添加 `'Content-Type': 'application/json'`，请求体**仅接受字典或列表类型数据**。
 
@@ -50,7 +82,7 @@ res: str = await http_requests.post()
 | headers   | dict       | 追加的请求头                                                                               |     |
 | **kwargs  |            | [request 参数](https://github.com/aio-libs/aiohttp/blob/master/aiohttp/client.py#L316) |     |
 
-## 发送 form 表单请求
+## FORM 表单请求
 
 post_form 方法类似 post 方法。唯一不同的是请求体仅接受**字典类型**，发送请求时会被构建为 form data 表单数据。