完善文档，补充配置项的配置方法说明，补充开发文档中适配新网站的介绍

2025-06-05 11:26:43 +08:00 · 2022-05-24 15:10:49 +08:00 · 2022-05-24 15:10:49 +08:00 · 5906cc5b82
commit 5906cc5b82
parent fcf8be38f0
2 changed files with 70 additions and 16 deletions
--- a/docs/dev/README.md
+++ b/docs/dev/README.md
@ -80,11 +80,32 @@ sidebar: auto
 - `enable_tag` 平台发布内容是否带 Tag，例如微博
 - `platform_name` 唯一的，英文的识别标识，比如`weibo`
 - `async get_target_name(Target) -> Optional[str]` 通常用于获取帐号的名称，如果平台没有帐号概念，可以直接返回平台的`name`
- `async parse(RawPost) -> Post`将获取到的 RawPost 处理成 Post
+- `get_sub_lst(Target) -> list[RawPost]` 用于获取对应 Target 的 RawPost 列表，与上一次`get_sub_list`获取的列表比较，过滤出新的 RawPost
 - `get_tags(RawPost) -> Optional[Collection[Tag]]` （可选） 从 RawPost 中提取 Tag
 - `get_category(RawPos) -> Optional[Category]` （可选）从 RawPost 中提取 Category
+- `async parse(RawPost) -> Post`将获取到的 RawPost 处理成 Post

-例如要适配微博，我希望 bot 搬运新的消息，所以微博的类应该这样定义：
+#### 简要的处理流程
+
+- `nonebot_bison.platform.platform.NewMessage`
+  ::: details 大致流程
+  1. 调用`get_sub_list`拿到 RawPost 列表
+  2. 调用`get_id`判断是否重复，如果没有重复就说明是新的 RawPost
+  3. 如果有`get_category`和`get_date`，则调用判断 RawPost 是否满足条件
+  4. 调用`parse`生成正式推文
+     :::
+  - 参考[nonebot_bison.platform.Weibo](https://github.com/felinae98/nonebot-bison/blob/v0.5.3/src/plugins/nonebot_bison/platform/weibo.py)
+- `nonebot_bison.platform.platform.StatusChange`
+  :::details 大致流程
+  1. `get_status`获取当前状态
+  2. 传入`compare_status`比较前状态
+  3. 通过则进入`parser`生成 Post
+     :::
+  - 参考[nonenot_bison.platform.AkVersion](https://github.com/felinae98/nonebot-bison/blob/v0.5.3/src/plugins/nonebot_bison/platform/arknights.py#L86)
+
+#### 一些例子
+
+例如要适配微博，我希望 bot 搬运新的消息，所以微博的类应该这样实现：

 ```python
 class Weibo(NewMessage):
@ -103,10 +124,35 @@ class Weibo(NewMessage):
    schedule_type = "interval"
    schedule_kw = {"seconds": 3}
    has_target = True
+
+    async def get_target_name(self, target: Target) -> Optional[str]:
+      #获取Target对应的用户名
+      ...
+    async def get_sub_list(self, target: Target) -> list[RawPost]:
+      #获取对应Target的RawPost列表，会与上一次get_sub_list获取的列表比较，过滤出新的RawPost
+      ...
+    def get_id(self, post: RawPost) -> Any:
+      #获取可以标识每个Rawpost的，不与之前RawPost重复的id，用于过滤出新的RawPost
+      ...
+    def get_date(self, raw_post: RawPost) -> float:
+      #获取RawPost的发布时间，若bot过滤出的新RawPost发布时间与当前时间差超过2小时，该RawPost将被忽略，可以返回None
+      ...
+    def get_tags(self, raw_post: RawPost) -> Optional[list[Tag]]:
+      #获取RawPost中包含的微博话题（#xxx#中的内容）
+      ...
+    def get_category(self, raw_post: RawPost) -> Category:
+      #获取该RawPost在该类定义categories的具体分类(转发？视频？图文？...？)
+      ...
+    async def parse(self, raw_post: RawPost) -> Post:
+      #将需要bot推送的RawPost处理成正式推送的Post
+      ...
 ```

-当然我们非常希望你对自己适配的平台写一些单元测试，你可以模仿`tests/platforms/test_*.py`中的内容写
-一些单元测试。为保证多次运行测试的一致性，可以 mock http 的响应，测试的内容包括获取 RawPost，处理成 Post
+当然我们非常希望你对自己适配的平台写一些单元测试
+
+你可以参照`tests/platforms/test_*.py`中的内容对单元测试进行编写。
+
+为保证多次运行测试的一致性，可以 mock http 的响应，测试的内容应包括[获取 RawPost](https://github.com/felinae98/nonebot-bison/blob/v0.5.3/tests/platforms/test_weibo.py#L59)，处理成 Post
 ，测试分类以及提取 tag 等，当然最好和 rsshub 做一个交叉验证。

 ::: danger
--- a/docs/usage/README.md
+++ b/docs/usage/README.md
@ -94,23 +94,27 @@ sidebar: auto

 ## 配置

-可参考[源文件](https://github.com/felinae98/nonebot-bison/blob/main/src/plugins/nonebot_bison/plugin_config.py)
+::: tip INFO
+
+- 所有配置项可参考[源文件](https://github.com/felinae98/nonebot-bison/blob/main/src/plugins/nonebot_bison/plugin_config.py)
+- **配置项的配置方法** 请参考[NoneBot 配置方式](https://v2.nonebot.dev/docs/tutorial/configuration#%E9%85%8D%E7%BD%AE%E6%96%B9%E5%BC%8F)，在`.env`/`.env.*`文件中写入希望配置的 Bison 配置项
+  :::

 - `BISON_CONFIG_PATH`: 插件存放配置文件的位置，如果不设定默认为项目目录下的`data`目录
 - `BISON_USE_PIC`: 将文字渲染成图片后进行发送，多用于规避风控
 - `BISON_BROWSER`: 本插件使用 Chrome 来渲染图片
-  - 使用 browserless 提供的 Chrome 管理服务，设置为`ws://xxxxxxxx`，值为 Chrome Endpoint（推荐）
-  - 使用 cdp 连接相关服务，设置为`wsc://xxxxxxxxx`
-  - 使用本地安装的 Chrome，设置为`local:<chrome path>`，例如`local:/usr/bin/google-chrome-stable`
  - 如果不进行配置，那么会在启动时候自动进行安装，在官方的 docker 镜像中已经安装了浏览器
+  - 使用本地安装的 Chrome，设置为`local:<chrome path>`，例如`local:/usr/bin/google-chrome-stable`
+  - 使用 cdp 连接相关服务，设置为`wsc://xxxxxxxxx`
+  - 使用 browserless 提供的 Chrome 管理服务，设置为`ws://xxxxxxxx`，值为 Chrome Endpoint
    ::: warning
    截止发布时，本项目尚不能完全与 browserless 兼容，目前建议使用镜像内自带的浏览器，即
    不要配置这个变量
    :::
 - `BISON_SKIP_BROWSER_CHECK`: 是否在启动时自动下载浏览器，如果选择`False`会在用到浏览器时自动下载，
  默认`True`
- `BISON_OUTER_URL`: 从外部访问服务器的地址，默认为`http://localhost:8080/bison`，如果你的插件部署
-  在服务器上，建议配置为`http://<你的服务器ip>:8080/bison`
+- `BISON_OUTER_URL`: 从外部访问服务器的地址，默认为`http://localhost:8080/bison/`，如果你的插件部署
+  在服务器上，建议配置为`http://<你的服务器ip>:8080/bison/`
  ::: warning
  如果需要从外网或者 Docker 容器外访问后台页面，请确保`HOST=0.0.0.0`
  :::
@ -124,7 +128,7 @@ sidebar: auto
  - `1`: 首条消息单独发送，剩余图片合并转发
  - `2`: 所有消息全部合并转发

-  ::: details 配置项示例
+  ::: details BISON_USE_PIC_MERGE 配置项示例

  - 当`BISON_USE_PIC_MERGE=1`时:
    ![simple1](/images/forward-msg-simple1.png)
@ -155,12 +159,16 @@ sidebar: auto
 所有命令都需要@bot 触发

 - 添加订阅（仅管理员和群主和 SUPERUSER）：`添加订阅`
-  ::: tip 关于中止订阅
-  对于[**v0.5.1**](https://github.com/felinae98/nonebot-bison/releases/tag/v0.5.1)及以上的版本中，已经为`添加订阅`命令添加了中止订阅的功能。  
-  在添加订阅命令的~~几乎~~各个阶段，都可以向 Bot 发送`取消`消息来中止订阅过程(需要订阅发起者本人发送)
+  ::: details 关于中止添加订阅
+  对于[**v0.5.1**](https://github.com/felinae98/nonebot-bison/releases/tag/v0.5.1)及以上的版本中，已经为`添加订阅`命令添加了中止添加功能。  
+  在`添加订阅`命令的~~几乎~~各个阶段，都可以向 Bot 发送`取消`消息来中止订阅过程(需要发起者本人发送)
  :::
 - 查询订阅：`查询订阅`
 - 删除订阅（仅管理员和群主和 SUPERUSER）：`删除订阅`
+  ::: details 关于中止删除订阅
+  对于[**v0.5.3**](https://github.com/felinae98/nonebot-bison/releases/tag/v0.5.3)及以上的版本中，已经为`删除订阅`命令添加了中止删除功能。
+  在`删除订阅`命令的~~几乎~~各个阶段，都可以向 Bot 发送`取消`消息来中止订阅过程(需要发起者本人发送)
+  :::

 #### 私聊机器人获取后台地址

@ -179,8 +187,8 @@ sidebar: auto
 #### 私聊机器人进行配置（需要 SUPERUER 权限）

 请私聊 bot`群管理`
-::: tip 关于中止订阅
-与普通的[`添加订阅`](#在本群中进行配置)命令一样，在`群管理`命令中使用的`添加订阅`命令也可以使用`取消`来中止订阅过程
+::: details 关于中止订阅
+与普通的[`添加订阅`/`删除订阅`](#在本群中进行配置)命令一样，在`群管理`命令中使用的`添加订阅`/`删除订阅`命令也可以使用`取消`来中止订阅过程
 :::

 ### 所支持平台的 uid