Bison 的模块化构想

[AzideCupric]

就目前 Bison 的各功能实现来看，不少功能都存在较多的上下游调用依赖问题。比如 Bison 最主要的消息轮询业务，从 Schduler 开始，内部直接调用到 Platform、Site、Theme、MessageSend 四大功能，Bison 插件近乎所有的模块全都在这里耦合，导致整个结构缺乏灵活性和可扩展性，对单一功能的修改容易会波及到其余部分，也导致消息发送部分与蹲饼部分结合的过于紧密，以及渲染部分可能因为耗时过长而将调度循环阻塞。

实现目标

旨在从“ monolithic ”的调度器向“基于事件总线（Courier）”的松散耦合架构演变，大致包括：

1. 解耦核心模块，将调度、解析、渲染、发送等职责分离，从而简化调度实现
2. 提高可扩展性，通过标准化接口支持插件化扩展
3. 提升可维护性，明确模块边界，降低修改复杂度

成为一个更符合组织名的插件

模块拆分说明

Scheduler（调度器）
仅负责按计划触发各个 Platform 的数据获取，不关心具体的数据处理和消息发送，如果本次调度获取到原始报文（RawPost），则通过 Courier 发送，然后立即继续调度下一个任务。

Platform（平台适配器）

1. 提供 fetch-api: () -> RawPost(s) | None，获取是否有新的 RawPost
2. 提供 parse-api: RawPost -> Post，解析传入的 RawPost 为正式报文（Post）
3. 声明特定依赖条件和特定平台配置元数据

Site（站点）
是对 Platform 的分类，调度器按 Site 为单位划分轮询循环执行轮询任务，同一个 Site 下的 Platforms 在同一循环中执行。

Theme（主题渲染器）
接收标准化 Post，根据运行实际、用户配置、Platform 默认配置将 Post 渲染为具体消息格式以备发送，支持多种可配置的消息模板和样式

Sender（发送器）
将渲染好的消息放入消息队列，负责将最终消息发送到目标平台（QQ/TG 等）

数据流图

按照上一节所述内容，大致可以由以下图示进行描绘:

sequenceDiagram
    participant S as Scheduler
    participant C as Courier
    participant W as Platform/Weibo
    participant T as Theme
    participant Sd as Sender

    Note over S, Sd: 阶段1: 调度和数据获取
    S->>C: Parcel:<br/>- payload: {content: xxx}<br/>- metadata: {platform: weibo}<br/>- dest: fetcher<br/>- channel: main
    C->>W: 路由(fetcher, main)
    W->>W: 调用微博API(fetch-api)
    W->>W: 生成RawPost列表
    loop 每个RawPost
        W->>C: Parcel:<br/>- payload: RawPost<br/>- metadata: {platform: weibo}<br/>- dest: normalizer<br/>- channel: main
    end

    Note over S, Sd: 阶段2: 数据解析
    C->>W: 路由(normalizer, main)
    W->>W: 解析为Post(parse-api)
    W->>C: Parcel:<br/>- payload: Post<br/>- metadata: {platform: weibo}<br/>- dest: renderer<br/>- channel: render

    Note over S, Sd: 阶段3: 消息渲染
    C->>T: 路由(renderer, render)
    T->>T: 选择Theme
    T->>T: 渲染为Message
    T->>C: Parcel:<br/>- payload: Message<br/>- metadata: {target: xxx}<br/>- dest: sender<br/>- channel: message

    Note over S, Sd: 阶段4: 消息发送
    C->>Sd: 路由(sender, message)
    Sd->>Sd: 进入发送队列构建可发送消息
    Sd->>Sd: 发送到QQ群/TG等

Loading

信使（Courier）机制

在上文的模块拆分中可以发现，有些数据会被一个模块产出，接着被一个模块接收，对于这一个统一的行为，可以封装出一个模块来处理，考虑到本项目的由来和名称，可以将该模块称之为信使（Courier，这下终于物流了），这个模块提供一个统一入口，模块投递被包装为包裹（Parcel）的数据，Courier 将其派送到对应的处理点。这些处理点在各自的模块进行注册和实现，通过声明处理点的地址（Tag）、特定信道（Channel），处理点接收可以处理的包裹，并对包裹合法性进行验证，根据需要消费或者加工后转派，实现模块间数据流的链接。信使模块也可以认为是一种总线（Bus）模块间的数据流转在这里进行。

模块间的数据流转由 Courier 统一负责，这样各个模块只消保证 Parcel 出入口能够与其他模块对接，数据流就可以保持联通，内部的实现可以有更大程度的自主性。这使得各个模块的子插件化成为可能，Bison可以通过子插件加载，甚至直接在pyproject.toml中按需加载子插件，就能注册不同的处理点，实现可按需组合的数据流。当然这是比较高级的玩法了（

信使的派送机制也为插件的扩展/定制化提供可能，下游用户只需要自行注册替换一个默认处理点，就可以实现原有数据流的变更，提升了定制化空间。另外只要构建出符合接收条件的 Parcel，数据就能被处理，这样我们就拥有了几乎在程序的各个位置发送通知消息的能力 —— 构造一个消息包裹交给信使派送即可。

核心概念

Courier（信使）：模块间通信的总线系统，负责路由和派送数据包。
Parcel（包裹）：数据的标准包装格式，包含：

• data: 实际被处理的数据（RawPost、Post、Message 等）
• metadata: 控制待处理数据行为的数据，这些数据不是被直接处理的数据
• dest: 目标地址（Tag）。
• channel: 信道类型（Channel），声明 Parcel 通过哪个信道发送。

Tag（地址）：处理点的标识符，如 fetcher、parser、sender 等。声明 Parcel 需要发送到哪里。

Channel（信道）：数据类型或处理阶段的标识，如 main、message、render 等。对于一些繁忙的地址，可以为其创建一个单独的 Channel 来传输包裹，减少等待处理 Parcel 的时间。

工作机制

# 注册处理函数示例
@Courier.receive_from(Tag("fetcher"), Channel("main"))
async def handle_fetch(parcel: Parcel): # 也支持解包传入，复用 nb 的依赖注入
    # 处理数据获取
    pass

# 发送数据示例
parcel = Parcel(
    metadata={"platform": "weibo"},
    payload="xxx<br/>xxxxxxx"
    destination=Tag("normalize"),
    channel=Channel("main")
)
await Courier.post(parcel)

Platform/Theme 的按需加载（子插件化）

之所以提出这两大功能的子插件化，是因为在开发过程中适配不用的 Platform、Theme 时，总是会引入只有这个极小部分才需要的依赖，而用户在实际使用时，有些 Platform 和 Theme 完全不会被使用，这些依赖就变成了累赘，也使得项目的依赖项数显得过于的多~~（不好看！）~~。
在设计之初 Theme 就天然支持外部注册，其实现参考于 Platform，因此 Platform 自然不难。
因此考虑将目前项目中 builtin 的 Platform、Theme 迁移到 extra_plugins 目录中，使用 uv 的 monorepo 结构进行管理，使用子插件的形式，启动时将子插件中的 Platform 注册到本体的平台管理器中。

requier("nonebot_bison")
from nonebot_bison import PlatformManager

class WeiboPlatform(Platform):
    name = "weibo"
    # ...
    

# ...

PlatformManager.register(WeiboPlatform)

Bison Core 与非核心模块

将原有代码文件结构重新进行整理，提出 Core 的概念。Core 是 Bison 业务实现的最小组成，不包含特定的通信协议或者框架依赖，Schduler、 Platform(Abstract)、Site、Theme(Abstract)、Courier 的模块在这里实现。

Abstract 指的是仅在此定义其公共变量、类型、接口等，不做具体的实现

而诸如订阅处理、Cookie处理、Web API以及具体的消息发送处理，则是非核心，依赖某些特定框架协议的模块，不进入Core部分。

Core 模块（框架无关）

核心职责：

• 定义基础接口和数据类型
• 实现核心业务逻辑
• 提供插件管理机制

包含组件：

• Courier: 消息总线系统
  • Parcel/Tag/Channel 基础数据类型
• Scheduler: 任务调度器
• Platform/Site/Theme 抽象基类

非核心模块（框架特定）

适配层组件：

• 订阅管理（依赖 NoneBot 的消息交互机制）
• Web API（依赖具体的 web 框架）
• 消息发送器（依赖具体的统一消息实现插件）

设计原则：

• Core 模块不依赖任何特定框架
• 非核心模块通过适配器模式与 Core 交互
• 支持多种消息协议和存储后端

未来展望（做不完了）

• 配置机制增强，通过 Config 机制将调度间隔、样式控制等配置暴露为 BISON__PLATFORM__XXX 环境变量，或者支持一个配置文件集中配置
• 实现更智能的调度策略，支持优先级和权重配置的真正实装
• 未尽事项可以参考 issue##382

[AzideCupric]

目前 next 分支的计划是这样的
@felinae98 @suyiiyii @he0119

[suyiiyii]

看起来是 #478 的超级增强版

感觉整体就像是一个事件循环，而信使（Courier）就像是任务队列和调度器
问一个之前群主提到过的问题，全部解耦之后，如何知晓一个包在各个组件之间的具体流向，可以方便的调试吗（一直点下一步可以走完这个Parcel的生命流程）

(怎么有一点trace的味道了)

还有个问题，非核心模块支持声明自己的存储吗。换句话说，cookie应该怎么存储，cookie类的定义应该是放到非核心模块里面还是放到core里面

[AzideCupric]

问一个之前群主提到过的问题，全部解耦之后，如何知晓一个包在各个组件之间的具体流向，可以方便的调试吗（一直点下一步可以走完这个Parcel的生命流程）
(怎么有一点trace的味道了)

可以的，parcel的运输是可以追踪的，不然feat/courier2分支中的单测怎么写（
以及添加了一个邮戳机制，每送达一个处理点，都会记录到邮戳里，每个parcel在投递时也会生成一个回执，通过这个回执也可以一定程度上获取到包裹的状态

还有个问题，非核心模块支持声明自己的存储吗。换句话说，cookie应该怎么存储，cookie类的定义应该是放到非核心模块里面还是放到core里面

好问题...cookie应该是platform或者site的下属产物？platform、site在core中仅有抽象基类和管理器的实现，在没有具体实现platform时，cookie会存在吗？不过印象里有个cookiemanager，可能这个应该要放到core里

[felinae98]

def exec_loop(ctx):
    posts = platform.get_new_posts(ctx)
    for p in posts:
        rendered = theme.render(p)
        sender.send(rendered)

其实总线的可靠性和可读性其实不如上面的伪代码简单

[felinae98]

当然上面函数的缺点是整个 render 和 send 都放在函数里了，如果后两个阶段用的时间比较长，会拖慢整个函数的效率。在“爬取”和“渲染”做一个消息队列、在“渲染“和”发送”之间做一个消息队列是河里的。和总线相比我觉得专用管道会好一点（你也不喜欢装过汽油的管道运输食用油吧）

[AzideCupric]

按现在的实现而言(anyio的message_stream)，只要channel是只有一个处理点声明接收的，他就是一条专用管道
客货混装（共用main）是考虑到有些部分的流量并不是很大，所以就一起传输了

[felinae98]

这里还需要明确一个问题，就是 site 的语义。
当前 site 的语义是“风控域”，对同一个风控域会有一个最小访问间隔的限制。即每两次请求之间需要间隔某个时间。
但是现在 cookie 的有效域和风控域是相同的，未来可能会分开它们。

[felinae98]

还有一个问题是，platform 和 site 的爬取 API（类的定义）可能需要好好梳理一下

[AzideCupric]

platform内部的api乱的不想看(