ButterBot

一个基于 Python 3.12+ 和 asyncio 的事件驱动机器人框架。项目把外部输入抽象为 Source，把数据与状态包装为 Event，再由 EventBus 分发给异步 Handler。

当前版本为 3.1.1 正式稳定版。已文档化的公共 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.yaml

config.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 restart

run 默认加载 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

许可证

GPL-3.0

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

butterbot_python-3.1.1.tar.gz (569.5 kB view details)

Uploaded Aug 10, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

butterbot_python-3.1.1-py3-none-any.whl (234.5 kB view details)

Uploaded Aug 10, 2026 Python 3

File details

Details for the file butterbot_python-3.1.1.tar.gz.

File metadata

Download URL: butterbot_python-3.1.1.tar.gz
Upload date: Aug 10, 2026
Size: 569.5 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for butterbot_python-3.1.1.tar.gz
Algorithm	Hash digest
SHA256	`aae9af237524d0ba9a030a68c797117024529a7572ccccbdc1efe91ca47921eb`
MD5	`e7d5469bfbcb504efc46b6b2a01c1e22`
BLAKE2b-256	`41808897c76e8773c77bda693ce83f5811280e516ca9707fc14d9d8a8464de05`

See more details on using hashes here.

Provenance

The following attestation bundles were made for butterbot_python-3.1.1.tar.gz:

Publisher: release-on-version.yml on GEYUANwuqi/ButterBot

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: butterbot_python-3.1.1.tar.gz
- Subject digest: aae9af237524d0ba9a030a68c797117024529a7572ccccbdc1efe91ca47921eb
- Sigstore transparency entry: 2410254348
- Sigstore integration time: Aug 10, 2026
Source repository:
- Permalink: GEYUANwuqi/ButterBot@6456b976c409eee66cbb19736dec8a434cc7ae55
- Branch / Tag: refs/tags/v3.1.1
- Owner: https://github.com/GEYUANwuqi
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release-on-version.yml@6456b976c409eee66cbb19736dec8a434cc7ae55
- Trigger Event: push