suyiiyii/nonebot-bison
1
0
Fork 0
mirror of https://github.com/suyiiyii/nonebot-bison.git synced 2025-07-13 11:03:00 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

Merge pull request #80 from AzideCupric/main-doc

Browse Source 
完善开发文档
This commit is contained in:
felinae98 2022-05-26 21:33:01 +08:00 committed by GitHub
commit 2a09d74d67
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 131 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

128
docs/dev/README.md
View File

@ -31,6 +31,11 @@ sidebar: auto
本插件需要你的帮助！只需要会写简单的爬虫，就能给本插件适配新的网站。 本插件需要你的帮助！只需要会写简单的爬虫，就能给本插件适配新的网站。
::: danger
Nonebot 项目使用了全异步的处理方式，所以你需要对异步，Python asyncio 的机制有一定了解，当然，
依葫芦画瓢也是足够的
:::
## 基本概念 ## 基本概念
- `nonebot_bison.post.Post`: 可以理解为推送内容，其中包含需要发送的文字，图片，链接，平台信息等 - `nonebot_bison.post.Post`: 可以理解为推送内容，其中包含需要发送的文字，图片，链接，平台信息等
@ -53,7 +58,7 @@ sidebar: auto
例如：微博，Bilibili 例如：微博，Bilibili
- `nonebot_bison.platform.platform.StatusChange` 每次爬虫获取一个状态，在状态改变时发布推送 - `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 文件， 现在你需要在`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_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}` `schedule_kw`是对应的参数，一个常见的配置是`schedule_type=interval`, `schedule_kw={'seconds':30}`
@ -80,11 +136,40 @@ sidebar: auto
- `enable_tag` 平台发布内容是否带 Tag，例如微博 - `enable_tag` 平台发布内容是否带 Tag，例如微博
- `platform_name` 唯一的，英文的识别标识，比如`weibo` - `platform_name` 唯一的，英文的识别标识，比如`weibo`
- `async get_target_name(Target) -> Optional[str]` 通常用于获取帐号的名称，如果平台没有帐号概念，可以直接返回平台的`name` - `async get_target_name(Target) -> Optional[str]` 通常用于获取帐号的名称，如果平台没有帐号概念，可以直接返回平台的`name`
- `async parse(RawPost) -> Post`将获取到的 RawPost 处理成 Post
- `get_tags(RawPost) -> Optional[Collection[Tag]]` （可选） 从 RawPost 中提取 Tag - `get_tags(RawPost) -> Optional[Collection[Tag]]` （可选） 从 RawPost 中提取 Tag
- `get_category(RawPos) -> Optional[Category]` （可选）从 RawPost 中提取 Category - `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 ```python
class Weibo(NewMessage): class Weibo(NewMessage):
@ -103,17 +188,26 @@ class Weibo(NewMessage):
schedule_type = "interval" schedule_type = "interval"
schedule_kw = {"seconds": 3} schedule_kw = {"seconds": 3}
has_target = True 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 的机制有一定了解，当然，
依葫芦画瓢也是足够的
:::
## 类的方法与成员变量
## 方法与变量的定义

32
docs/usage/README.md
View File

@ -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_CONFIG_PATH`: 插件存放配置文件的位置，如果不设定默认为项目目录下的`data`目录
- `BISON_USE_PIC`: 将文字渲染成图片后进行发送，多用于规避风控 - `BISON_USE_PIC`: 将文字渲染成图片后进行发送，多用于规避风控
- `BISON_BROWSER`: 本插件使用 Chrome 来渲染图片 - `BISON_BROWSER`: 本插件使用 Chrome 来渲染图片
- 使用 browserless 提供的 Chrome 管理服务，设置为`ws://xxxxxxxx`，值为 Chrome Endpoint（推荐）
- 使用 cdp 连接相关服务，设置为`wsc://xxxxxxxxx`
- 使用本地安装的 Chrome，设置为`local:<chrome path>`，例如`local:/usr/bin/google-chrome-stable`
- 如果不进行配置，那么会在启动时候自动进行安装，在官方的 docker 镜像中已经安装了浏览器 - 如果不进行配置，那么会在启动时候自动进行安装，在官方的 docker 镜像中已经安装了浏览器
- 使用本地安装的 Chrome，设置为`local:<chrome path>`，例如`local:/usr/bin/google-chrome-stable`
- 使用 cdp 连接相关服务，设置为`wsc://xxxxxxxxx`
- 使用 browserless 提供的 Chrome 管理服务，设置为`ws://xxxxxxxx`，值为 Chrome Endpoint
::: warning ::: warning
截止发布时，本项目尚不能完全与 browserless 兼容，目前建议使用镜像内自带的浏览器，即 截止发布时，本项目尚不能完全与 browserless 兼容，目前建议使用镜像内自带的浏览器，即
不要配置这个变量 不要配置这个变量
::: :::
- `BISON_SKIP_BROWSER_CHECK`: 是否在启动时自动下载浏览器，如果选择`False`会在用到浏览器时自动下载， - `BISON_SKIP_BROWSER_CHECK`: 是否在启动时自动下载浏览器，如果选择`False`会在用到浏览器时自动下载，
默认`True` 默认`True`
- `BISON_OUTER_URL`: 从外部访问服务器的地址，默认为`http://localhost:8080/bison`，如果你的插件部署 - `BISON_OUTER_URL`: 从外部访问服务器的地址，默认为`http://localhost:8080/bison/`，如果你的插件部署
在服务器上，建议配置为`http://<你的服务器ip>:8080/bison` 在服务器上，建议配置为`http://<你的服务器ip>:8080/bison/`
::: warning ::: warning
如果需要从外网或者 Docker 容器外访问后台页面，请确保`HOST=0.0.0.0` 如果需要从外网或者 Docker 容器外访问后台页面，请确保`HOST=0.0.0.0`
::: :::
@ -124,7 +128,7 @@ sidebar: auto
- `1`: 首条消息单独发送，剩余图片合并转发 - `1`: 首条消息单独发送，剩余图片合并转发
- `2`: 所有消息全部合并转发 - `2`: 所有消息全部合并转发
::: details 配置项示例 ::: details BISON_USE_PIC_MERGE 配置项示例
- 当`BISON_USE_PIC_MERGE=1`时: - 当`BISON_USE_PIC_MERGE=1`时:
![simple1](/images/forward-msg-simple1.png) ![simple1](/images/forward-msg-simple1.png)
@ -155,12 +159,16 @@ sidebar: auto
所有命令都需要@bot 触发 所有命令都需要@bot 触发
- 添加订阅（仅管理员和群主和 SUPERUSER）：`添加订阅` - 添加订阅（仅管理员和群主和 SUPERUSER）：`添加订阅`
::: tip 关于中止订阅 ::: details 关于中止添加订阅
对于[**v0.5.1**](https://github.com/felinae98/nonebot-bison/releases/tag/v0.5.1)及以上的版本中，已经为`添加订阅`命令添加了中止订阅的功能。 对于[**v0.5.1**](https://github.com/felinae98/nonebot-bison/releases/tag/v0.5.1)及以上的版本中，已经为`添加订阅`命令添加了中止添加功能。
在添加订阅命令的~~几乎~~各个阶段，都可以向 Bot 发送`取消`消息来中止订阅过程(需要订阅发起者本人发送) 在`添加订阅`命令的~~几乎~~各个阶段，都可以向 Bot 发送`取消`消息来中止订阅过程(需要发起者本人发送)
::: :::
- 查询订阅：`查询订阅` - 查询订阅：`查询订阅`
- 删除订阅（仅管理员和群主和 SUPERUSER）：`删除订阅` - 删除订阅（仅管理员和群主和 SUPERUSER）：`删除订阅`
::: details 关于中止删除订阅
对于[**v0.5.3**](https://github.com/felinae98/nonebot-bison/releases/tag/v0.5.3)及以上的版本中，已经为`删除订阅`命令添加了中止删除功能。
在`删除订阅`命令的~~几乎~~各个阶段，都可以向 Bot 发送`取消`消息来中止订阅过程(需要发起者本人发送)
:::
#### 私聊机器人获取后台地址 #### 私聊机器人获取后台地址
@ -179,8 +187,8 @@ sidebar: auto
#### 私聊机器人进行配置（需要 SUPERUER 权限） #### 私聊机器人进行配置（需要 SUPERUER 权限）
请私聊 bot`群管理` 请私聊 bot`群管理`
::: tip 关于中止订阅 ::: details 关于中止订阅
与普通的[`添加订阅`](#在本群中进行配置)命令一样，在`群管理`命令中使用的`添加订阅`命令也可以使用`取消`来中止订阅过程 与普通的[`添加订阅`/`删除订阅`](#在本群中进行配置)命令一样，在`群管理`命令中使用的`添加订阅`/`删除订阅`命令也可以使用`取消`来中止订阅过程
::: :::
### 所支持平台的 uid ### 所支持平台的 uid