Merge pull request #80 from AzideCupric/main-doc

完善开发文档
2025-07-13 10:54:30 +08:00 · 2022-05-26 21:33:01 +08:00 · 2022-05-26 21:33:01 +08:00 · 2a09d74d67
commit 2a09d74d67
parent cb2f7cc2c7 443d9e9426
2 changed files with 131 additions and 29 deletions
--- a/docs/dev/README.md
+++ b/docs/dev/README.md
@ -31,6 +31,11 @@ sidebar: auto

 本插件需要你的帮助！只需要会写简单的爬虫，就能给本插件适配新的网站。

+::: danger
+Nonebot 项目使用了全异步的处理方式，所以你需要对异步，Python asyncio 的机制有一定了解，当然，
+依葫芦画瓢也是足够的
+:::
+
 ## 基本概念

 - `nonebot_bison.post.Post`: 可以理解为推送内容，其中包含需要发送的文字，图片，链接，平台信息等
@ -53,7 +58,7 @@ sidebar: auto
   例如：微博，Bilibili
 - `nonebot_bison.platform.platform.StatusChange` 每次爬虫获取一个状态，在状态改变时发布推送  
   例如：游戏开服提醒，主播上播提醒
- `nonebot_bison.platform.platform.SimplePost` 与`NewMessage`相似，但是不过滤新的消息
+- `nonebot_bison.platform.platform.SimplePost` 与`NewMessage`相似，但是不过滤之前发过的
  ，每次发送全部消息  
   例如：每日榜单定时发送

@ -64,10 +69,61 @@ sidebar: auto
 - 没有账号的概念  
  例如：游戏公告，教务处公告

+## 实现方法
+
 现在你需要在`src/plugins/nonebot_bison/platform`下新建一个 py 文件，
 在里面新建一个类，继承推送类型的基类，重载一些关键的函数，然后……就完成了，不需要修改别的东西了。

-任何一种订阅类型需要实现的方法/字段如下：
+### 不同类型 Platform 的实现适配以及逻辑
+
+- `nonebot_bison.platform.platform.NewMessage`
+  需要实现：
+
+  - `async get_sub_list(Target) -> list[RawPost]`
+  - `get_id(RawPost)`
+  - `get_date(RawPost)` (可选)
+
+  ::: 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`
+  需要实现：
+
+  - `async get_status(Target) -> Any`
+  - `compare_status(Target, old_status, new_status) -> list[RawPost]`
+
+  :::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)
+
+- `nonebot_bison.platform.platform.SimplePost`
+  需要实现：
+
+  - `async get_sub_list(Target) -> list[RawPost]`
+  - `get_date(RawPost)` (可选)
+
+  ::: details 大致流程
+
+  1. 调用`get_sub_list`拿到 RawPost 列表
+  2. 如果有`get_category`和`get_date`，则调用判断 RawPost 是否满足条件
+  3. 调用`parse`生成正式推文
+     :::
+
+### 公共方法/成员
+
+任何一种订阅类型需要实现的方法/成员如下：

 - `schedule_type`, `schedule_kw` 调度的参数，本质是使用 apscheduler 的[trigger 参数](https://apscheduler.readthedocs.io/en/3.x/userguide.html?highlight=trigger#choosing-the-right-scheduler-job-store-s-executor-s-and-trigger-s)，`schedule_type`可以是`date`,`interval`和`cron`，
  `schedule_kw`是对应的参数，一个常见的配置是`schedule_type=interval`, `schedule_kw={'seconds':30}`
@ -80,11 +136,40 @@ sidebar: auto
 - `enable_tag` 平台发布内容是否带 Tag，例如微博
 - `platform_name` 唯一的，英文的识别标识，比如`weibo`
 - `async get_target_name(Target) -> Optional[str]` 通常用于获取帐号的名称，如果平台没有帐号概念，可以直接返回平台的`name`
- `async parse(RawPost) -> Post`将获取到的 RawPost 处理成 Post
 - `get_tags(RawPost) -> Optional[Collection[Tag]]` （可选） 从 RawPost 中提取 Tag
 - `get_category(RawPos) -> Optional[Category]` （可选）从 RawPost 中提取 Category
+- `async parse(RawPost) -> Post` 将获取到的 RawPost 处理成 Post
+- `async parse_target(str) -> Target` （可选）定制化处理传入用户输入的 Target 字符串，返回 Target（一般是把用户的主页链接解析为 Target），如果输入本身就是 Target，则直接返回 Target
+- `parse_target_promot` （可选）在要求用户输入 Target 的时候显示的提示文字

-例如要适配微博，我希望 bot 搬运新的消息，所以微博的类应该这样定义：
+### 特有的方法/成员
+
+- `async get_sub_list(Target) -> list[RawPost]` 输入一个`Target`，输出一个`RawPost`的 list
+  - 对于`nonebot_bison.platform.platform.NewMessage`  
+    `get_sub_list(Target) -> list[RawPost]` 用于获取对应 Target 的 RawPost 列表，与上一次`get_sub_list`获取的列表比较，过滤出新的 RawPost
+  - 对于`nonebot_bison.platform.platform.SimplePost`  
+    `get_sub_list` 用于获取对应 Target 的 RawPost 列表，但不会与上次获取的结果进行比较，而是直接进行发送
+- `get_id(RawPost) -> Any` 输入一个`RawPost`，从`RawPost`中获取一个唯一的 ID，这个 ID 会用来判断这条`RawPost`是不是之前收到过
+- `get_date(RawPost) -> Optional[int]` 输入一个`RawPost`，如果可以从`RawPost`中提取出发文的时间，返回发文时间的 timestamp，否则返回`None`
+- `async get_status(Target) -> Any`
+  - 对于`nonebot_bison.platform.platform.StatusChange`  
+    `get_status`用于获取对应 Target 当前的状态，随后将获取的状态作为参数`new_status`传入`compare_status`中
+- `compare_status(self, target: Target, old_status, new_status) -> list[RawPost]`
+  - 对于`nonebot_bison.platform.platform.StatusChange`  
+    `compare_status` 用于比较储存的`old_status`与新传入的`new_status`，并返回发生变更的 RawPost 列表
+
+### 单元测试
+
+当然我们非常希望你对自己适配的平台写一些单元测试
+
+你可以参照`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 做一个交叉验证。
+
+## 一些例子
+
+例如要适配微博，我希望 bot 搬运新的消息，所以微博的类应该这样实现：

 ```python
 class Weibo(NewMessage):
@ -103,17 +188,26 @@ 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
-，测试分类以及提取 tag 等，当然最好和 rsshub 做一个交叉验证。
-
-::: danger
-Nonebot 项目使用了全异步的处理方式，所以你需要对异步，Python asyncio 的机制有一定了解，当然，
-依葫芦画瓢也是足够的
-:::
-
-## 类的方法与成员变量
-
-## 方法与变量的定义
--- 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