一个基于 Python 3.12+ 和 asyncio 的事件驱动机器人框架。项目把外部输入抽象为 Source，把数据与状态包装为 Event，再由 EventBus 分发给异步 Handler。
当前版本为
3.1.1.post1正式稳定版。已文档化的公共 API 在3.x内遵守 SemVer 兼容承诺；第三方 Source 继续由应用显式装配，这是稳定的设计边界。
当前仓库内置：
- NapCat OneBot WebSocket 事件与 API；
- Bilibili 动态轮询、直播状态轮询和直播弹幕事件源；
- Source、API、Data、Type 和 Filter 扩展契约；
- 统一启动、回调排空与资源关闭流程。
ButterBot 已发布到 PyPI。发行包名是
butterbot-python，Python 导入名是 butterbot：
python -m pip install butterbot-python
uv add butterbot-python按需安装内置 adapter：
python -m pip install "butterbot-python[all]"
uv add "butterbot-python[all]"更多 extra 与安装说明见安装指南。
uv sync --locked --dev已发布 wheel 的基础安装不包含 adapter 网络依赖. 按需安装
butterbot-python[napcat]、[bilibili] 或 [all];
NapCat 和 Bilibili extra 都显式包含 aiohttp.
运行完整 Python 检查：
uv run pytest
uv run ruff check .
uv run ruff format --check .
uv run pyright不依赖外部服务的示例：
uv run examples/minimal_source_example.py预期输出 ready 并正常退出。NapCat 与 Bilibili 示例需要先复制并填写本地配置：
cp examples/config.example.yaml config.yamlconfig.yaml 可能包含凭证，已被 Git 忽略，不要提交或公开。
使用 CLI 创建、配置并运行项目：
uv run butterbot init
uv run butterbot plugin
uv run butterbot plugin check
uv run butterbot run --background
uv run butterbot status
uv run butterbot stop
uv run butterbot restartrun 默认加载 app.app 和当前目录的 config.yaml。可以用位置参数或
-path 指定其他应用入口，用 -config 指定其他 YAML：
uv run butterbot run mybot.application.app -config ./deploy/config.yaml
uv run butterbot run -path mybot.application.app -config ./deploy/config.yaml应用入口只负责接收 CLI 已解析的配置并返回 BotApp，不要在模块导入时调用
app.run()。
后台运行和重启语义见命令行指南。
本地启动 VuePress 2 + Plume 文档站：
npm install
npm run docs:dev推荐入口：
生产构建与文档检查：
npm ci
npm run docs:build
npm run docs:lint
npm run docs:links