OpenBot群聊协作指南:多个AI同事同Channel对话、@交接与线程隔离机制
OpenBot群聊协作指南:多个AI同事同Channel对话、@交接与线程隔离机制
OpenBot 是一个开源 AI 同事(AI coworkers)平台:每个 AI 同事都拥有自己的"电脑"(浏览器、文件与工具),并支持把任意 AG-UI 协议的 Agent 接入进来。本指南带你掌握 OpenBot 群聊协作的核心玩法——让多个 AI 同事在同一个 Channel 中对话、通过 @交接 把任务转给队友,以及理解底层的线程隔离机制。
什么是 AI 同事群聊
在 OpenBot 中,一个 Channel(频道) 就是一段对话。当你在发起对话时选择不止一个 Bot,这个 Channel 就变成了"群聊"——多个 AI 同事与团队成员共处一间"会议室":
- 群聊的第一条消息会发送给群里所有 Bot,而不是只发给某一个;
- 每个人看到的内容是共享 transcript(
group_messages表,一人/一 Bot 一行,每条回复都标注说话者); - 成员管理在群聊顶栏的"人"按钮中完成(添加、移出成员、离开),权限每次请求都会实时校验,不缓存。
👉 核心规则:谁在群里、谁有权看到它,由 channel_memberships 决定,非成员连"频道是否存在"都探测不到。
相关页面与源码:
- 群聊路由:group/$channelId.tsx
- 群聊组件:group-chat.tsx
- 成员管理组件:group-people.tsx
- 新频道/群组入口:channel/new.tsx
一键创建多 Bot 群聊的步骤
- 在侧边栏点击发起新对话,进入 channel/new 页面;
- 选择第一个 Bot 后,继续"Add another Bot for a group…";
- 输入第一条消息并发送——此时 Channel 即成为群组,消息按你挑选的顺序送达各 Bot;
- 在群聊顶栏通过 GroupPeopleButton 管理真人成员。
选 1 个 Bot 是普通私聊频道(/channel/$channelId),选 2 个及以上才是群聊(/group/$channelId),两者在界面上就是同一套频道列表,区别只在于参与者的数量。
@交接机制:如何让 AI 同事之间互相递活
这是 OpenBot 群聊协作最精彩的部分:一个 Bot 在回复里 @同事名,就把对话交给了那位同事,就像在真实团队群里 @ 一个人接手问题一样。
@交接的识别规则
服务端用 mentionedPeers 函数解析每条回复中被点名的同事,规则很严格,避免"误伤":
| 规则 | 说明 |
|---|---|
| 全名匹配 | 必须是 Bot 花名册里的完整名字(大小写不敏感) |
| 词边界 | @Ops 不会命中一个叫 "Opsgenie" 的 Bot |
| 不认邮箱 | jo@sam.com 不会点名 Sam(前面已有 @ 的不算) |
| 长名优先 | 同一 @ 起头时,"Ops Lead" 优先于 "Ops" |
| 顺序保留 | 一条回复里 @ 了多个同事,按书写顺序依次交接 |
@交接复用的是同一套"交接台"
@交接 不是另起炉灶,而是直接复用 OpenBot 的 handoff desk(Bot 间交接权限体系):同一套 Bot-to-Bot 授权(mayAddress)、同一套深度上限、同一套每条回复的扇出上限、同一条带租约的持久化队列、同一批 agent.handoff_* 审计行。没有任何额外的"编排器"参与其中。
见群聊模块头部的这段设计说明:group.ts
结构化交接工具 message_bot
除了群聊里的 @,OpenBot 还提供了 message_bot 工具,供 Bot 以"字段化"的方式把活递给另一个 Bot,参数被刻意设计成结构化而非自由文本:
bot:接活同事的名字(须在其花名册可见范围内);task:一两句话描述任务;constraints(可选):日期范围、要查的系统、不能违反的规则;expecting(可选):什么样的回答算"好答案"(清单、数字、带理由的建议……)。
为什么不用一段自由文本?源码注释说得很直白:自由文本是多智能体系统悄悄出错的最常见方式——接活方靠猜意图、猜约束,猜错了也不会报错,而是"自信地答了别的东西"。
四个关键安全属性(详见 docs/architecture.md):
- 接活人是谁:对照发起者可见的花名册解析,Bot 不能触达其主人看不到的 Bot;"不存在"和"不可见"用同样的话拒绝,无法枚举花名册;
- 答案落到哪里:由签名的运行断言决定,防止 Bot 把回复塞进它不在场的对话;
- 谁在发问:由部署方写入的记录盖章,Bot 不能冒充他人;
- 链条有多深:同样来自断言,阻止 A→B→C→A 无限循环。
交接的上限与开关
| 参数 | 作用 |
|---|---|
BOT_HANDOFF_MAX_DEPTH |
交接链最大深度,设为 0 即关闭整个交接能力 |
BOT_HANDOFF_MAX_PER_RUN |
单次运行最多派发给几个 Bot |
两个上限都是"直接拒绝而非截断"。交接结果全部进入审计轨迹:offered、refused(哪个上限或哪项授权挡住了它)、delivered、failed、retried——其中"被拒绝"这条记录最有价值,因为成功的交接在 transcript 里可见,被拒的否则只在审计里留痕。
线程隔离机制:为什么每个 Bot 有自己的一条线
这是理解 OpenBot 群聊"为什么这样设计"的关键,答案在 docs/architecture.md:
An Intelligence thread admits exactly one agent.
CopilotKit Intelligence 的线程(thread)一次只容纳一个 Agent。所以一个有两个 Bot 的 Channel 不可能是"一个线程两个说话人"。OpenBot 的解法是双轨存储:
群聊 Channel
├── 每个 Bot 一条私有线程 → group_bot_threads 表
│ (每轮对话走标准 headless AG-UI 路径跑进这条线程)
└── 共享 transcript → group_messages 表
(群成员看到的是这一层,每条消息标注说话者)
带来的实际效果:
- 上下文互不污染:每个 Bot 只带着自己那条线程的记忆回答,学习(learning)、治理、审批、分析等机制对群聊回合的生效方式与普通任务完全一致;
- 交接的答案落在接活方的对话里:不是回到提问的那条线,而是被点名 Bot 与你的对话置顶并带上未读标记——你两半都能收到:提问的对话说明"活去了哪",接活的对话给出答案;
- 私有上下文不串味:发问对话的历史会作为上下文给被点名 Bot 阅读,但不会重复写进共享 transcript;
- 对比私聊:单个 Channel 对应一条 Intelligence 线程(
intelligence_channel_mappings表),两个同 Bot 的 Channel 也相互独立,见 docs/coworkers.md。
交接失败与 ask_person:安全出口的设计
两个细节让群聊协作"不会悄悄停摆":
- 永久失败的交接会被大声说出来:当一个 hop 用完尝试次数,发起方会被送回你正在看的对话,明确告诉你"没有收到回复"。否则"被交出去却永不回答的问题"和"只是慢的问题"无法区分,对话会莫名其妙地停住;
- ask_person 工具:与
message_bot并列提供。当 Bot 遇到自己判断不了的问题时,应停下来问你,而不是硬猜,或把问题横向甩给同样拍不了板的另一个 Bot。找到已在对话里的人,零成本且不可能指向你看不见的地方——详见 handoff-tool.ts 与 escalation.ts。
群聊回复中交接成功/路由成功的"第一句话"标记由 shared/handoff-markers.ts 单点声明(Handed to 与 Put to ),前后端共用同一份契约。
上手清单:群聊协作速查
| 目标 | 怎么做 | 关键位置 |
|---|---|---|
| 建群 | 新建频道时选 ≥2 个 Bot | channel/new.tsx |
| 管理真人成员 | 群顶栏"人"按钮 | group-people.tsx |
| Bot 间 @交接 | 回复中写 @全名 |
group.ts |
| 查看交接治理 | 深度/扇出上限、审计行 | docs/architecture.md |
| 关闭交接能力 | BOT_HANDOFF_MAX_DEPTH=0 |
部署配置 |
| Bot 问人 | ask_person 工具 |
escalation.ts |
总结
OpenBot 的群聊协作可以浓缩成三句话:
- 一个 Channel,多个 AI 同事——共享 transcript + 逐人发言归属;
@交接= 复用交接台的完整治理——授权、深度上限、扇出上限、审计一行不少;- 线程隔离是平台属性而非取舍——每个 Bot 一条私有线程,上下文干净、答案各归其位。
配合 docs/architecture.md 与 docs/coworkers.md,你可以进一步理解 Bot 可见性、Team Bot 发布、Computer 网关策略等配套机制,把 OpenBot 真正变成你团队里"看得见、管得住"的 AI 同事班子。