From 5906cc5b829a27a4509c34dd6f5c73eb4433ad6c Mon Sep 17 00:00:00 2001 From: Azide Date: Tue, 24 May 2022 15:10:49 +0800 Subject: [PATCH] =?UTF-8?q?=E5=AE=8C=E5=96=84=E6=96=87=E6=A1=A3=EF=BC=8C?= =?UTF-8?q?=E8=A1=A5=E5=85=85=E9=85=8D=E7=BD=AE=E9=A1=B9=E7=9A=84=E9=85=8D?= =?UTF-8?q?=E7=BD=AE=E6=96=B9=E6=B3=95=E8=AF=B4=E6=98=8E=EF=BC=8C=E8=A1=A5?= =?UTF-8?q?=E5=85=85=E5=BC=80=E5=8F=91=E6=96=87=E6=A1=A3=E4=B8=AD=E9=80=82?= =?UTF-8?q?=E9=85=8D=E6=96=B0=E7=BD=91=E7=AB=99=E7=9A=84=E4=BB=8B=E7=BB=8D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/dev/README.md | 54 ++++++++++++++++++++++++++++++++++++++++---- docs/usage/README.md | 32 ++++++++++++++++---------- 2 files changed, 70 insertions(+), 16 deletions(-) diff --git a/docs/dev/README.md b/docs/dev/README.md index 945e47c..5cf6d4d 100644 --- 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 diff --git a/docs/usage/README.md b/docs/usage/README.md index cb34657..39bf8e6 100644 --- 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:`，例如`local:/usr/bin/google-chrome-stable` - 如果不进行配置，那么会在启动时候自动进行安装，在官方的 docker 镜像中已经安装了浏览器 + - 使用本地安装的 Chrome，设置为`local:`，例如`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