快速开始

本页介绍 Bub，并帮你从三种使用路径中选一种，让本节其余文档按合理顺序展开。

Bub 是一个用于在共享环境中构建 agent 的小型 Python 框架。内核负责单一的 turn pipeline，其余一切都是插件：channel、tool、skill 和存储后端按需启用。

在开始之前

你需要准备：

• Python 3.12 或更高版本
• 已加入 PATH 的 uv
• 一种模型访问方式，用于 model-backed 阶段：
  • 通过 BUB_API_KEY 或提供商专用 BUB_<PROVIDER>_API_KEY 导出的 API key，或
  • 通过 uv run bub login openai 完成 OpenAI Codex OAuth，并设置 BUB_MODEL=openai:gpt-5-codex

如果只想检查 Bub 而不实际跑一次 model turn，API key 是可选的——,help 等 comma 命令无需它即可使用。

三种使用路径

Bub 服务三类受众。请挑选一条与你当前目标匹配的路径：

• 运维者 — 你想运行一个 Bub 实例、配置 channel 并部署。 阅读本节，之后转到 Operate Bub 了解配置、channel 与部署。
• 插件作者 — 你想用新的 hook、tool 或 skill 扩展 Bub。 阅读本节直至 构建你的第一个插件，之后转到 Build Plugins 查看完整扩展契约。
• 发行版作者 — 你想为某个具体场景打包 Bub 与一组精选插件。 先阅读本节，之后查看 Distribution 了解打包约定。

三类受众共享同一个起点：安装 Bub、跑一次 turn、确认运行时健康。

推荐路径

按顺序阅读以下页面：

1. 安装 Bub — 从 PyPI 或源码安装，或将 Bub 作为框架依赖固定，并用 bub hooks 验证。
2. 运行你的第一次 turn — 创建 workspace、写 AGENTS.md、发送 ,help，再跑一次 model-backed turn。
3. 编写你的第一个 skill — 在 .agents/skills/ 下编写一个项目 skill，并在 turn 中调用它。
4. 构建你的第一个插件 — 通过 Python entry points 发布最小插件并验证加载。

如果你想先理解概念模型，请在动手之前阅读 Concepts。

下一步

• 安装 Bub — 进入推荐路径。
• Concepts — 在扩展 Bub 之前理解内核模型。
• CLI 参考 — 查看本节使用的所有命令。