ButterBot

异步、事件驱动的 Python 机器人框架

将外部数据输入抽象为事件源，通过类型安全的事件总线连接异步处理器。

快速开始查看 API GitHub

明确的异步生命周期

BotApp 统一启动事件源，并按固定顺序排空回调、关闭 API 资源。

事件与订阅

使用 BaseType 声明状态，通过枚举、正则和内容过滤器注册异步回调。

可扩展事件源

基于 BaseSource、BaseApi 与 AppContext 接入新的平台或数据输入。

内置适配

当前仓库提供 NapCat、Bilibili 与飞书事件源、数据模型和 API 封装。

最小安装

uv add butterbot-python

项目要求 Python 3.12 或更高版本。仓库开发环境使用 uv 和锁文件管理。

最小运行模型

下面的结构展示了推荐入口。完整、可直接运行且不依赖外部服务的版本见快速开始。

import asyncio

from butterbot.app import BotApp, RuntimeConfig


async def main() -> None:
    app = BotApp(RuntimeConfig())
    async with app:
        # 在这里等待业务完成，或由事件源持续产生事件。
        await asyncio.sleep(0)


if __name__ == "__main__":
    asyncio.run(main())

生命周期

stop() 只停止事件源；close() 还会排空事件回调并释放 API 资源。应用所有权在当前函数中时，优先使用 async with app。

从哪里开始

第一次使用：从安装和快速开始开始。
选择独立进程或嵌入模式：查看运行模式。
接入 NapCat、Bilibili 或飞书：查看事件源指南。
开发自定义事件源：查看扩展开发。
查询签名和异常：查看API 参考。
排查关闭、超时或悬挂任务：查看故障排除。