跳转到内容
Bub Bub Bub

安装 Bub

本页说明三种受支持的安装方式：运行 CLI、从源码贡献框架，以及在另一个包中依赖 Bub。

在开始之前

Section titled “在开始之前”

你需要准备：

  • Python 3.12 或更高版本
  • 直接安装和源码开发需要 uv；引导式安装器可以自行 bootstrap
  • 在你打算运行 Bub 的 workspace 中已可用的终端

1. 使用引导式安装器

Section titled “1. 使用引导式安装器”

独立安装器会在 Bub 尚未安装时运行。先下载脚本，以便检查它将要执行的内容：

curl -sSLO https://raw.githubusercontent.com/bubbuild/bub/main/install-bub.py
python3 install-bub.py

安装器首先要求选择一个执行界面 preset：

Preset必选插件用途
chat无终端聊天与一次性命令。
lodybub-acp-server由 Lody 启动的 ACP session。

下一屏只 toggle 与执行界面无关的可选插件：网页搜索、MCP tools 和语义记忆。preset 的必选插件不会作为 toggle 出现；选择 lody 就一定会安装 ACP server。

用于自动化、CI 或可复现的机器配置时，可以跳过全部 prompt：

python3 install-bub.py \
  --preset lody \
  --plugin web-search \
  --no-interactive

重复传入 --plugin 可以选择多个内置选项，--with REQUIREMENT 可以添加任意 Python package。使用 --dry-run 可以只输出完整的 uv 命令而不修改机器。

安装器把环境所有权交给 uv tool install。如果系统里没有 uv，它会在临时环境中 bootstrap uv，再把 uv 注入 Bub 的 tool 环境，确保后续 bub install 仍然可用。用户选择记录在 ~/.bub/install.json（或 $BUB_HOME/install.json）；实际安装状态仍以 uv receipt 为准。

确认二进制已加入 PATH：

bub --help

如果不使用引导式安装器，也可以直接安装发布包：

uv tool install bub
# 或
pip install bub

2. 从源码安装

Section titled “2. 从源码安装”

如果你想为框架贡献代码或跟随 main 分支，使用本路径：

git clone https://github.com/bubbuild/bub.git
cd bub
uv sync

uv sync 会在 .venv/ 下创建项目本地虚拟环境并装好所有开发依赖。完成后，文档中所有 uv run bub 示例都可以在仓库根目录使用。

3. 将 Bub 固定为框架依赖

Section titled “3. 将 Bub 固定为框架依赖”

插件作者与发行版作者应当像普通 Python 包那样依赖 Bub。在插件的 pyproject.toml 中声明依赖，并在 bub entry-point 组下注册一个入口：

[project]
name = "bub-my-plugin"
version = "0.1.0"
dependencies = ["bub>=0.1"]

[project.entry-points."bub"]
my-plugin = "bub_my_plugin.plugin:MyPlugin"

Bub 通过 importlib.metadata.entry_points(group="bub") 发现插件，因此活动环境中任何注册了该 entry point 的包都会在框架启动时被加载。

4. 验证安装

Section titled “4. 验证安装”

确认 Bub 加载了内置 hook 的最快方法是 bub hooks 命令：

uv run bub hooks

你应当看到一份摘要，包含 builtin 插件以及 resolve_session、build_prompt、run_model_stream、render_outbound、dispatch_outbound 等 hook 的实现。如果 builtin 缺失或被标记为失败，请重新执行 uv sync 并查看 loader 打印的错误。

下一步

Section titled “下一步”