Pre-release

This release is a pre-release and may not be stable for production use.

ButterBot

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

当前仓库内置：

NapCat OneBot WebSocket 事件与 API；
Bilibili 动态轮询、直播状态轮询和直播弹幕事件源；
Source、API、Data、Type 和 Filter 扩展契约；
统一启动、回调排空与资源关闭流程。

安装与开发

uv sync --locked --dev

运行完整 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 check
uv run butterbot run mybot.app:app --background
uv run butterbot status
uv run butterbot stop
uv run butterbot run mybot.app:app --background  # 恢复暂停的同一进程
uv run butterbot close

使用 CLI 时，应用模块只定义 app = BotApp()、Source 和 Handler，不要在模块顶层调用 app.run()。若还要支持 uv run app.py，必须写成：

if __name__ == "__main__":
    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.0.dev2.tar.gz (442.1 kB view details)

Uploaded Jul 30, 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.0.dev2-py3-none-any.whl (150.1 kB view details)

Uploaded Jul 30, 2026 Python 3

File details

Details for the file butterbot_python-3.1.0.dev2.tar.gz.

File metadata

Download URL: butterbot_python-3.1.0.dev2.tar.gz
Upload date: Jul 30, 2026
Size: 442.1 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.0.dev2.tar.gz
Algorithm	Hash digest
SHA256	`20e5f28ef0bb6e3d18b387a893cb2b490fa48b31ac7f34288876687e87ef70b5`
MD5	`9920042c888ffb49ea4a9d5e32597a17`
BLAKE2b-256	`fb68be7f54ba381237c1f244714eea8defe98147a6fdce66b73c0a352836f4a5`

See more details on using hashes here.

Provenance

The following attestation bundles were made for butterbot_python-3.1.0.dev2.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.0.dev2.tar.gz
- Subject digest: 20e5f28ef0bb6e3d18b387a893cb2b490fa48b31ac7f34288876687e87ef70b5
- Sigstore transparency entry: 2289700984
- Sigstore integration time: Jul 30, 2026
Source repository:
- Permalink: GEYUANwuqi/ButterBot@265ec6b516f8b2f39d870a2d4a3d573aefc5d25b
- Branch / Tag: refs/tags/v3.1.0.dev2
- 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@265ec6b516f8b2f39d870a2d4a3d573aefc5d25b
- Trigger Event: push