bub

用钩子机制精细控制 AI 代理，让人机协作更安全可靠

Bub 是一个以钩子（hook）为核心的智能体运行时，专为与人类协作共存的 AI 代理设计。它解决的是传统智能体框架中代理行为难以精细控制和与用户实时交互的问题。其核心能力包括：通过钩子机制在代理执行的关键节点（如工具调用、消息生成）注入自定义逻辑，实现实时干预、权限控制和状态追踪；支持长时运行的任务，代理可以暂停、恢复，并持久化状态；提供简洁的 Python API，便于开发者快速构建和部署。Bub 强调代理与人的共生关系，让代理不仅能自主执行任务，还能在需要时请求人类确认或反馈，从而提升任务完成的安全性和可靠性。项目处于成长阶段，社区活跃，适合探索下一代人机协作代理的开发者。

开源 unknown 智能体

访问官网 ↗ GitHub ↗ 文档 ↗

GitHub 星标 ★ 1671

维护状态活跃

是否开源是

定价模式 unknown

项目数据

分类智能体

开发团队bubbuild

所属国家

官网地址https://bub.build

GitHubhttps://github.com/bubbuild/bub

定价模式unknown

价格说明定价信息待确认

访问状态

是否开源是

开源协议Apache-2.0

主要语言Python

技术栈/模型agent,agents,ai,ai-agents,aiagentframework,bub,llms,python

GitHub 星标★ 1671

30天Star增速

HF 下载量

上线时间2025-07-13 00:00:00

最近更新2026-09-23 00:00:00

维护状态活跃

中文支持

访问方式

移动端支持

综合评分

收录时间2026-08-09

浏览次数3

使用教程

难度：入门约 10 分钟部署方式：命令行工具 8 步

环境要求

macOS、Linux 或 Windows 系统（提供对应安装脚本）
需要能访问网络的终端（下载安装脚本与依赖）
从源码安装需要 git 与 uv 工具链
使用模型服务需要对应的 API Key（可选，也可用 bub login openai）

安装与启动步骤

1一键安装（macOS/Linux）

官方交互式安装脚本，会提供预设选择器、可追加插件依赖，并在安装后自动执行 bub onboard 引导。
```
curl -fsSL https://bub.build/install.sh | bash
```
2一键安装（Windows）

Windows 用户在 PowerShell 中执行对应安装脚本，效果与 macOS/Linux 安装脚本一致。
```
powershell -ExecutionPolicy ByPass -c "irm https://bub.build/install.ps1 | iex"
```
3非交互式安装

自动化场景需显式指定 preset；非交互安装会跳过 onboard 引导，可用 --dependency 追加插件。
```
curl -fsSL https://bub.build/install.sh | bash -s -- --preset recommended --dependency extra-plugin
```
4从源码安装

克隆仓库后进入目录，用 uv sync 同步依赖即可从源码运行 Bub；本地开发可改用 make install。
```
git clone https://github.com/bubbuild/bub.git
cd bub
uv sync
```
5配置模型与密钥

通过环境变量指定模型与 API Key，默认模型为 openrouter:openrouter/free；也可用 bub login openai 登录。
```
export BUB_MODEL=openrouter:openrouter/free
export BUB_API_KEY=sk-xxxxxxxx
```
6启动交互会话

运行 bub chat 进入交互式对话，可直接验证安装与模型配置是否生效。
```
bub chat
```
7执行一次性任务

用 bub run 加上任务描述，让代理完成单次任务后返回结果。
```
bub run "summarize this repo"
```
8启动频道监听

以 bub gateway 运行频道监听模式，同一运行时也可驱动 Telegram 等自定义频道。
```
bub gateway
```

关键配置

配置项	必填	说明	示例
`BUB_MODEL`	否	模型标识符，默认 openrouter:openrouter/free	`openrouter:openrouter/free`
`BUB_API_KEY`	否	模型服务商密钥，使用 bub login openai 时可省略	`sk-xxxxxxxx`
`BUB_API_BASE`	否	自定义模型服务商端点地址	`https://api.openai.com/v1`
`BUB_CLIENT_ARGS`	否	转发给底层模型客户端的 JSON 对象	`{"timeout":30}`
`BUB_MAX_STEPS`	否	工具调用循环上限，必须为正整数，默认不限	`20`
`BUB_MAX_TOKENS`	否	单次模型调用的最大 token 数，默认 16384	`16384`

如何确认成功

执行 bub chat 能进入交互式会话并正常收到回复，即表示安装与模型配置成功。

常见问题

Q：安装脚本会自动配置好吗？

A：交互式安装会运行 bub onboard 引导完成初始配置；非交互式安装会跳过该步骤，需自行设置 BUB_MODEL、BUB_API_KEY 等环境变量。

Q：没有 API Key 可以用吗？

A：可以，README 说明 BUB_API_KEY 是可选的，用 bub login openai 登录后即可使用，无需手动填写密钥。

Q：从源码运行和安装脚本有什么区别？

A：uv sync 已足够从源码运行 Bub；若要做本地开发，应改用 make install，以便同时装上网站工具链和 prek 钩子。

Q：工具输出太长会怎样？

A：默认超过约 4096 估算 token 时工具输出会被 spill，可通过 BUB_SPILL_THRESHOLD 调整，设为 0 可禁用该行为。

注意事项

默认模型为 openrouter:openrouter/free，若使用其他服务商需同步修改 BUB_MODEL 与密钥。
BUB_MAX_STEPS 必须为正整数，配置错误可能导致启动或运行失败。
Bub 基于 agents.md 与 Agent Skills 构建，每一轮阶段都是 pluggy 钩子，内置实现可被替换。
同一运行时驱动 CLI、Telegram 及你自行添加的频道，bub gateway 即频道监听模式。

核心亮点

钩子式架构：在代理关键节点注入逻辑，实现实时干预和权限控制，远超黑盒式框架
支持长时运行任务：代理可暂停、恢复，状态持久化，适合复杂工作流
人机协作设计：代理可请求人类确认，提升任务安全性和可靠性

不足之处

项目较新，文档和生态尚待完善
钩子机制有学习曲线，需理解事件流

适用场景

需要精细控制 AI 代理行为的自动化工作流
涉及敏感操作需人工审批的智能体应用
构建长期运行、可中断恢复的 AI 助手

替代项目

LangChain、AutoGen、CrewAI

项目介绍

bub 是智能体领域的开源项目，由 bubbuild 开发，2025 年首次发布。

在全站 13,014 个收录项目中，它的 GitHub 星标数（1,671）位列前 30%，在智能体分类中处于中上游。

近 45 天，它的 GitHub 星标从 1,571 增加到 1,671，净增 100。

项目目前处于活跃维护状态，最近一次代码更新于 2026-09-23。从国内网络环境看，可直接访问。

它主要面向的使用场景是：需要精细控制AI代理行为的自动化工作流。同类可对比的替代方案包括 LangChain、AutoGen、CrewAI。

上一篇：Grok-UI

下一篇：claude-code-skills

bub