用 Bub 和飞书搭一个更懂群聊上下文的小机器人

今天我们来借助开源项目 Bub 来搭建一个更懂你的小机器人。项目地址：github.com/bubbuild/bu...

都是小机器人，可能会有小伙伴问，它和 OpenClaw 那只龙虾有什么区别？答案是，它更懂你。Bub 不只是那种"替你点个按钮、跑下流程、完成某个任务"的打工 Agent，它更像一个长期"潜水"在群聊看大家说话的小机器人：能看到大家刚才聊了什么，也能基于上下文参与进来。

上图为我蹲在 Bub 群里截的项目作者之一 PsiACE 和 Bub 的对话。相信你能感受到这个小机器人的"懂人"之处。它和 OpenClaw 的气质完全不同，没有什么"班味"，更像是一个非常可爱的私人小助理。

Bub 官方对它的定义也是：一个面向 shared environments 的小型 Python runtime，是作者们大概在春节前后，从多人和 Agent 共处在同一个群聊场景里开发出来的产品。下图为 Bub 刚开发出来的时候，它被群友 PUA 的模样：

依稀可见现在的机灵样，由于时间关系，今天我们不做复杂的自动化，只做一个最小可用版本：先在本地跑通 Bub，再尝试把它接进飞书群，让它可以在群里被 @，并根据上下文做简短回复。

如果你对这个小机器人的记忆管理系统和产品设计初衷有兴趣，可以阅读文末收录的两位项目作者的延伸阅读和 Bub 写的日记。Bub 独特的记忆系统，是这个产品个人觉得最有亮点的地方。

安装 Bub

Bub 是 Python 项目，官方文档推荐使用 uv。在开始前，先确认本机已经有 Python 和 uv。btw，本文的开发环境为： Python 3.14.5 & uv 0.9.7。

下面采用源码安装的方式：

Plain 复制代码

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

装好之后，可以先看一下 Bub 当前加载了哪些 hook：

Plain 复制代码

uv run bub hooks

Bub 的一个核心设计就是 hook-first。简单说，一条消息进来之后，它不是直接丢给模型，而是会经过一系列处理阶段，比如解析会话、加载上下文、构建 prompt、调用模型、渲染回复、保存状态。官方文档里也把一次完整处理称为一个 turn。

不过，这部分先不展开，我们先跑起来再说。

创建一个工作目录

为了不在 bub 的源码根目录写测试文件，我们来创建一个专门的测试目录。先返回到根目录，再新建工作目录，具体指令如下：

Plain 复制代码

# 返回根目录
cd ~ 
# 新建名为 hello-bub 的工作目录
mkdir -p hello-bub
# 进入 hello-bub 目录
cd hello-bub

现在，我们先来写一个 AGENTS.md。这个文件，你可以理解为是这个小机器人的基础设定。Bub 会在 model-backed turn 里读取它，并把它拼到系统提示词中。

Plain 复制代码

cat > AGENTS.md <<'EOF'
你是这个群聊里的 Bub 小机器人。

你的任务不是替大家完成所有工作，而是理解上下文、整理讨论、补充遗漏信息。

回复规则：
- 先理解大家刚才在聊什么，再回答问题。
- 回复要简短，不要过度发挥。
- 如果信息不足，直接说明还缺什么。
EOF

如图：

需要留意的是，在这里我故意没有把它写成"万能助手"。因为本文并不是想体现 Bub 的自动化能力，而是一个更懂群聊上下文的小机器人。

配置模型

接下来配置模型访问。

Bub 可以通过环境变量读取模型配置。官方文档里提到，可以使用 BUB_API_KEY，也可以使用 provider-specific 的 API key；模型通过 BUB_MODEL 指定。模型配置可以按自己的习惯换。如果你用的是 OpenAI、OpenRouter 或其他兼容方式，只要 Bub 能正常调用就行。

还是一样，我们以七牛云的 MaaS 的配置为例。MaaS API Key 获取连接：portal.qiniu.com/ai-inferenc...

Plain 复制代码

cat > .env <<'EOF'
BUB_MODEL=openai:minimax/minimax-m2.7
BUB_OPENAI_API_BASE=https://api.qnaigc.com/v1
# 修改成你的七牛 MaaS 的 API Key
BUB_OPENAI_API_KEY=xxxxx
EOF

下面为本文的模型配置：

两个目录的作用

这里给大家先讲清楚 bub 和 hello-bub 两个目录的各自作用：

bub：负责提供源码版 Bub 命令，也就是 uv run bub
hello-bub：负责放你的测试配置，比如 AGENTS.md 和 .env

上面我们就是在配置测试环境。需要特别说明的是，因为本次是为了搭建一个陪聊小机器人，所以这里用了主打陪伴的"Minimax-2.7"。

环境配置好之后，我们开始来跑下 Bub：

本地跑一下

这里，我们不急着接飞书。先在本地跑一下，确认 Bub runtime 和模型调用都是通的。

我们来直接执行下面这些命令：

Plain 复制代码

# 切到 bub 目录
cd ~/bub 
# Bub 会读取 ~/hello-bub 里的 AGENTS.md 和 .env，构建上下文并调用模型生成回复。
uv run bub --workspace ~/hello-bub run "用一句话介绍你是谁。"

如果配置正常，它应该会根据刚才的 AGENTS.md 回复，说明自己是这个 workspace 里的 Bub 小机器人。

到这里，本地最小版本就跑通了。既然"来都来了"，在终端和小 Bub 再聊会天，记住下面画出来的重点之后，我们接着去对接下飞书。

安装飞书插件

Bub 本体更像 runtime，不同聊天平台通过 channel 或插件接入。

Telegram 是 Bub 一开始就支持的平台。但考虑到网络环境问题，以及你的小伙伴们不一定习惯上 TG。这里我们选择开放的飞书作为 Bub 的聊天室。

飞书插件可以用社区贡献的插件 bub-feishu。顺便提一嘴，Bub Hub 和 bub-contrib 里都能看到相关 Bub 生态插件，bub install 也支持从 bub-contrib 安装扩展。不过，本文暂时只用到 bub-feishu 插件。

尝试安装飞书插件：

Plain 复制代码

# 用源码环境里的 bub 命令安装飞书插件
uv run bub install bub-feishu@main

装完后，再检查一次：

Plain 复制代码

uv run bub hooks

看这里，我们的飞书插件已经装上了。我们下面来搞下飞书平台的设置：

配置飞书应用

这一章节要前往飞书开放平台：open.feishu.cn/。大致流程是：

1、创建一个企业自建应用：

填写下信息，并提交：

2、开启机器人能力：

3、启动应用，就是点击「创建版本」，然后一路默认到底，发布：

4、应用发布之后，我们返回到首页。就能看到我们刚才发布的应用了：

5、配置事件订阅。由于时间关系，我就不一一讲解了，我们直接选事件配置里的「长连接」接收事件：

（🙋小字）：注意：这里的验证环节留在下文的「双方握手」部分

6、配置发送消息的权限和事件权限，分别后面用来发送消息，和接收消息。

先是发送消息，在权限管理里面设置，参考下图：

接着是接收消息。在「事件与回调」里点击「添加事件」，订阅机器人消息相关事件，比如「接收消息」或 im.message.receive_v1。参考下图：

上面设置完成之后，飞书这边的所有配置已经完成！！恭喜我们，搞定了最难的配置之一。

7、把机器人拉进测试群。在我们发布应用之后，你的飞书客户端就会收到一个推送消息：

现在我们拉小机器人进群，打开你要拉小机器人进去的群，点击右上角的...里面有设置:

看到上面的 Bots 之后，点击进去：

添加机器人，时间关系，我们用搜索来快速找到刚才的小机器人：

我们选择 0 号机进群:

小家伙进群了：

飞书和 Bub 的握手仪式

飞书事件订阅有两种方式：一种是「将事件发送至开发者服务器」，另一种是「使用长连接接收事件」。上面，其实我们已经选择更适合本地调试的 长连接模式。这种方式不需要配置公网回调地址，也不用准备 ngrok 或 cloudflared。只要本地的 Bub gateway 保持运行，飞书就可以通过长连接把事件推给机器人。

获取飞书的私密信息

我们来获取下 App ID、App Secret 和 Verification Token 用来和 Bub 通信。

小声：你知道的 Secret = Key，都不要外露：

上面的 3 个信息获取之后，在本地 Hello-Bub 的 .env 里加上飞书相关配置：

Plain 复制代码

cat > .env <<'EOF'
# 之前填写过的信息
BUB_MODEL=openai:minimax/minimax-m2.7
BUB_OPENAI_API_BASE=https://api.qnaigc.com/v1
# 修改成你的七牛 MaaS 的 API Key
BUB_OPENAI_API_KEY=xxxxx

# 新的信息
# App 首页有下面信息
BUB_FEISHU_APP_ID=cli_xxxxx
BUB_FEISHU_APP_SECRET=xxxxx

# 事件与回调的加密策略有下面信息（见下图）
BUB_FEISHU_VERIFICATION_TOKEN=你的 Verification Token
EOF

在启动 Bub 之前，记得确认 .env 里已经写好飞书和模型配置：🙋 这里修改过了

Plain 复制代码

BUB_MODEL=openai:minimax/minimax-m2.7
BUB_OPENAI_API_BASE=https://api.qnaigc.com/v1
BUB_OPENAI_API_KEY=xxxxx

BUB_FEISHU_APP_ID=cli_xxxxx
BUB_FEISHU_APP_SECRET=xxxxx
BUB_FEISHU_VERIFICATION_TOKEN=xxxxx

注意，每个环境变量都要单独一行；APP_ID 一般已经是 cli_ 开头，不要手动再加一遍。Orz 本人就在这里死了半小时才发现，自己没换行以及多加了 cli。

然后，重新加载环境变量：

Plain 复制代码

cd ~/hello-bub
set -a
source .env
set +a

回到 Bub 源码目录，启动 Feishu channel：

Plain 复制代码

cd ~/bub
uv run bub --workspace ~/hello-bub gateway --enable-channel feishu

如果看到类似输出：

Plain 复制代码

channel.manager started listening

说明 Bub 的 channel manager 已经开始监听事件。

飞书事件配置验证

上面 Bub 已经关联上了飞书的相关信息，现在我们让飞书连接下 Bub，双方验证下：

很好，通过了：

接着，我们继续保持本地 gateway 运行，回到飞书测试群里 @ 机器人。如果终端开始出现消息日志，说明飞书事件已经通过长连接进入 Bub。如果你启动 gateway 后，如果群里 @ 机器人但终端没有任何日志，通常说明事件没有推到本地进程，需要优先检查事件是否已保存、应用是否重新发布、机器人是否作为群机器人加入，以及长连接模式是否生效。

在飞书群里测试

我们来测试下，这个小机器人是否能给反应：

感觉有些......一言难尽的蠢钝。来优化一下这个小机器人的人设：

优化机器人人设

修改之前 hello-bub 中的 AGENTS 文件，全文替换成下文：

Markdown 复制代码

你是飞书群里的 Bub 小机器人，定位是一个懂上下文的聊天伙伴。

你的任务不是替用户打工，也不是像客服一样反问用户要背景，而是：
- 认真接住用户刚刚说过的话；
- 基于当前群聊上下文继续对话；
- 帮用户整理想法、指出倾向、补一句更清楚的表达。

回复规则：
- 不要轻易说"请提供更多背景"。
- 如果信息不完整，也要先基于已有内容给出一个初步判断。
- 回复要短，像群聊里的自然回复，不要写成报告。
- 用户正在测试你是否能理解上下文，所以要主动引用前文。

保存之后，重启下 Bub，重新运行以下命令：

Bash 复制代码

cd ~/hello-bub
set -a
source .env
set +a

cd ~/bub
uv run bub --workspace ~/hello-bub gateway --enable-channel feishu

来见证下奇迹：

奇迹没发生，好吧。🤔 它似乎没有 Get 到我发了两条消息，也许是它的权限出了问题。我们在飞书后台增加一个新的权限：获取所有群消息：

奇迹发生了，我把两个信息分开发，即便我在第二条信息 @它，它都能及时地给我反应：

默认只开 @ 机器人消息时，它不一定能看到普通群聊；如果想让它更像"蹲在群里"，需要开"获取群组中所有消息"权限。

小结

这次实践不追求做一个很全面的 AI 助手，而是一个能接住你所有聊天记录信息的小助手。

我们先用 Bub 搭了一个最小版本：本地跑通 runtime，写好 AGENTS.md，配置模型，再通过飞书长连接模式接入群聊，让它可以在群里被 @，并基于上下文回复。

如果你的目标是直接在飞书里做任务、调用工具、跑工作流，OpenClaw 可能更直接。

但如果你想理解一个「更懂群聊上下文的小机器人」是怎么被搭起来的，Bub 是一个很适合动手拆解的项目。它让 Agent 不只是一个问答入口，而是开始真正待在群聊现场里。

用 Bub 和飞书搭一个更懂群聊上下文的小机器人

安装 Bub

创建一个工作目录

配置模型

两个目录的作用

本地跑一下

安装飞书插件

配置飞书应用

飞书和 Bub 的握手仪式

获取飞书的私密信息

飞书事件配置验证

在飞书群里测试

优化机器人人设

小结

来自 Bub 的书信

延伸阅读