构建具备上下文理解能力的群聊机器人：基于Bub与飞书的实践指南
本文将介绍如何利用开源项目 Bub 创建一个能够理解群聊上下文的智能机器人。项目地址：https://github.com/bubbuild/bub
与普通的任务型机器人不同，Bub 专注于理解对话上下文，更像是一个长期潜伏在群聊中的智能助手。它不仅能执行简单的指令，还能理解群聊历史，提供更自然的交互体验。
![]()
上图展示了 Bub 与开发者的对话场景，体现了其对上下文的理解能力。与传统的任务型机器人相比，Bub 更像一个私人助理，能够理解对话脉络并提供相关回应。
官方将 Bub 定义为面向共享环境的小型 Python 运行时，专为多用户与 AI 助手共存于同一群聊的场景设计。下面是 Bub 早期开发阶段的交互示例：
![]()
本文将指导您完成一个基础版本的搭建：首先在本地运行 Bub，然后将其接入飞书群聊，使其能够响应 @ 提醒并基于上下文进行回复。
环境准备
Bub 是一个 Python 项目，官方推荐使用 uv 进行安装。在开始前，请确保已安装 Python 和 uv。本文的开发环境为：Python 3.14.5 & uv 0.9.7。
通过源码方式安装：
git clone https://github.com/bubbuild/bub.git
cd bub
uv sync
uv run bub --help
![]()
安装完成后，可以查看当前加载的钩子：
uv run bub hooks
![]()
Bub 采用钩子优先的设计理念。当收到消息时，会经过多个处理阶段，包括会话解析、上下文加载、提示词构建、模型调用、回复渲染和状态保存。官方将这一完整处理流程称为一个"轮次"。
创建工作空间
为了避免在源码目录中直接操作，我们创建一个独立的工作目录：
# 返回用户主目录
cd ~
# 创建名为 my-bub-bot 的工作目录
mkdir -p my-bub-bot
# 进入新创建的目录
cd my-bub-bot
接下来，创建一个 AGENT_PROFILE.md 文件，用于定义机器人的基本角色设定：
cat > AGENT_PROFILE.md <<'EOF'
你是群聊中的 Bub 智能助手。
主要职责是理解对话上下文、整理讨论内容、补充缺失信息。
回复准则：
- 首先理解之前的对话内容，再回答问题
- 保持回复简洁，避免过度扩展
- 信息不足时，明确说明需要什么
EOF
![]()
注意，这里我们将其定位为理解上下文的助手，而非全能型问题解答器。
配置模型参数
Bub 支持通过环境变量配置模型访问。可以使用 BUB_API_KEY 或特定提供商的 API 密钥；模型通过 BUB_MODEL 指定。以下以七牛云 MaaS 为例：
cat > .env <<'EOF'
BUB_MODEL=openai:minimax/minimax-m2.7
BUB_OPENAI_API_BASE=https://api.qnaigc.com/v1
# 替换为你的七牛 MaaS API 密钥
BUB_OPENAI_API_KEY=your_api_key_here
EOF
![]()
这里需要说明两个目录的作用：
- bub：提供 Bub 源码和命令行工具
- my-bub-bot：存放测试配置文件，如 AGENT_PROFILE.md 和 .env
环境配置完成后，我们可以进行本地测试：
本地测试
在接入飞书之前，先在本地测试 Bub 运行时和模型调用是否正常：
# 切换到 bub 目录
cd ~/bub
# Bub 将读取 ~/my-bub-bot 中的配置文件并生成回复
uv run bub --workspace ~/my-bub-bot run "请用一句话介绍你自己。"
配置正确的话，机器人会根据 AGENT_PROFILE.md 中的设定回复，表明自己是工作空间中的 Bub 智能助手。
![]()
本地测试通过后，我们可以继续进行飞书集成：
安装飞书插件
Bub 本身是一个运行时环境，通过不同的通道或插件接入各种聊天平台。Telegram 是 Bub 最初支持的平台，但考虑到网络环境和用户习惯，我们选择飞书作为聊天平台。
安装社区提供的飞书插件：
# 使用源码环境中的 bub 命令安装飞书插件
uv run bub install bub-feishu@main
安装后，再次检查已加载的钩子：
uv run bub hooks
![]()
飞书插件已成功安装。接下来进行飞书平台的配置：
配置飞书应用
访问飞书开放平台：https://open.feishu.cn/，按以下步骤操作：
1. 创建企业自建应用：
![]()
填写应用信息并提交：
![]()
2. 启用机器人功能：
![]()
3. 发布应用：
点击「创建版本」，使用默认设置并发布：
![]()
![]()
4. 查看已发布应用：
返回首页，可以看到刚刚发布的应用：
![]()
5. 配置事件订阅：
选择「长连接」接收事件模式：
![]()
6. 配置权限：
首先配置发送消息权限：
![]()
然后配置接收消息权限，在「事件与回调」中添加相关事件，如「接收消息」或 im.message.receive_v1：
![]()
飞书平台配置完成后，将机器人添加到测试群：
![]()
在群设置中添加机器人：
![]()
![]()
通过搜索找到刚创建的机器人：
![]()
选择机器人并添加到群聊：
![]()
机器人已成功加入群聊：
![]()
连接 Bub 与飞书
飞书事件订阅支持两种模式：服务器接收和长连接模式。我们选择了更适合本地调试的长连接模式，无需配置公网回调地址。
获取飞书应用凭证：
从应用页面获取 App ID、App Secret 和 Verification Token：
![]()
![]()
在本地工作空间的 .env 文件中添加飞书相关配置：
cat > .env <<'EOF'
# 之前的模型配置
BUB_MODEL=openai:minimax/minimax-m2.7
BUB_OPENAI_API_BASE=https://api.qnaigc.com/v1
# 替换为你的七牛 MaaS API 密钥
BUB_OPENAI_API_KEY=your_api_key_here
# 飞书应用配置
BUB_FEISHU_APP_ID=cli_your_app_id
BUB_FEISHU_APP_SECRET=your_app_secret
# 事件验证令牌
BUB_FEISHU_VERIFICATION_TOKEN=your_verification_token
EOF
![]()
确保 .env 文件中已正确配置所有参数：
BUB_MODEL=openai:minimax/minimax-m2.7
BUB_OPENAI_API_BASE=https://api.qnaigc.com/v1
BUB_OPENAI_API_KEY=your_api_key_here
BUB_FEISHU_APP_ID=cli_your_app_id
BUB_FEISHU_APP_SECRET=your_app_secret
BUB_FEISHU_VERIFICATION_TOKEN=your_verification_token
重新加载环境变量：
cd ~/my-bub-bot
set -a
source .env
set +a
回到 Bub 源码目录，启动飞书通道：
cd ~/bub
uv run bub --workspace ~/my-bub-bot gateway --enable-channel feishu
看到类似以下输出表示启动成功：
channel.manager started listening
![]()
验证飞书事件配置：
在飞书开放平台完成事件订阅验证：
![]()
验证通过后：
![]()
保持本地网关运行，回到飞书测试群中 @ 机器人。如果终端显示消息日志，说明飞书事件已成功推送到 Bub。如果没有日志输出，需检查事件配置、应用发布状态、机器人是否已加入群聊以及长连接模式是否生效。
飞书群聊测试
测试机器人是否能正常响应：
![]()
初始响应可能不够理想，我们可以优化机器人的人设：
优化机器人角色设定
修改工作空间中的 AGENT_PROFILE.md 文件：
cat > AGENT_PROFILE.md <<'EOF'
你是飞书群聊中的 Bub 智能助手，专注于理解对话上下文。
你的职责不是执行任务或像客服一样询问背景信息，而是：
- 理解用户之前的发言内容
- 基于当前群聊上下文继续对话
- 帮助整理思路、指出观点倾向、提供更清晰的表达
回复准则：
- 避免要求"提供更多背景信息"
- 即使信息不完整，也要基于已有内容给出初步判断
- 保持回复简短自然，像群聊中的正常交流
- 主动引用前文内容，展示对上下文的理解
EOF
保存后，重启 Bub：
cd ~/my-bub-bot
set -a
source .env
set +a
cd ~/bub
uv run bub --workspace ~/my-bub-bot gateway --enable-channel feishu
测试优化后的效果：
![]()
如果机器人仍无法获取完整上下文，可能需要额外权限。在飞书后台添加"获取所有群消息"权限：
![]()
添加权限后，机器人能够更好地理解群聊上下文：
![]()
注意：默认情况下，机器人只能接收 @ 提醒消息。要使其能够理解完整群聊上下文，需要开启"获取群组中所有消息"权限。
总结
本文介绍了如何构建一个能够理解群聊上下文的智能助手。我们使用 Bub 创建了一个基础版本：在本地运行运行时，配置机器人角色设定，设置 AI 模型，通过飞书长连接模式接入群聊，使其能够响应 @ 提醒并基于上下文回复。
如果您的目标是在飞书中执行任务、调用工具或运行工作流，OpenClaw 可能更适合。但如果您想了解如何构建一个"理解群聊上下文的智能助手"，Bub 是一个很好的实践项目。它使 AI 助手不再仅仅是问答入口，而是真正融入群聊环境。
![]()
扩展阅读
- 产品思考：
- 记忆系统设计：
