理解 botmux 的关键是搞清「一条消息落到哪个会话」——「为什么每次 @ 都像新开、丢了上下文」「新群怎么拉到历史」这类困惑，根子都在这里。适用：搞不清消息去了哪个会话、想控制新开 vs 复用、或配群内权限时。消息路由的源码实现见 im-routing。
三种群形态
| 形态 | 行为 |
|---|---|
| 话题群（THREAD） | 每个新话题 = 一个独立 CLI 会话。同一话题内的消息进同一会话，不同话题互相隔离。最推荐。 |
| 普通群（DEFAULT） | 默认不自动开话题。/t <内容> 新开话题并提交首轮任务，需要选仓时选定后开工；裸 /t 先建立话题入口：需要选仓时显示仓库选择卡，已有固定目录或没有可选项目时不启动空会话，等待话题内下一条任务或 /repo。 |
| 私聊 | 直接和机器人开聊，相当于一个长期会话。 |
关闭「任务执行时显示状态卡片」后，/t <内容> 仍会先产生一条可见的话题回复，确保飞书立即展开 thread；reaction 只作为进度提示。命令细节见 slash-commands。
Oncall 群与 chat-scope 群
- Oncall 群：
/oncall bind <path>把整个群锚定到一个项目目录，跳过仓库选择，群内任何成员 @ 即问即答，见 oncall。 - chat-scope 群：
/group <群名>一键新建一个群，整个群作为一个独立会话（见下节）。
/group：一键新建会话群
/group <群名>（别名 /g）自动新建一个飞书群、邀请你进群、转让群主，整个群作为一个独立 CLI 会话（chat-scope），适合给一个项目 / 任务单独开一个干净的协作空间：
/g 卡片竞态 bug机器人回一张卡片（「✅ 已新建群 …👉 加群链接」），点进去直接开聊。空群名时用时间戳兜底；建好后不自动开会话，进群找机器人开聊即可。
- 多机器人一起建群：命令里 @ 的机器人会被一并拉进新群（由第一个被 @ 的机器人负责建群），如
@Claude @Codex /g review 群授权。回复会列出「群内机器人：Claude、Codex」，新群天然是多机器人协作空间，@ 谁谁干活，见 multi-bot。 - Bootstrap Role Profile：若已维护可复用的协作人设，建群时加
--role-profile <profile>（如@Claude @Codex /g --role-profile collab-main review 群授权）。群创建成功后，创建者 bot 先应用自己的 entry，再在新群里发送@Codex /role profile apply collab-main --quiet给其它 bot；每个 bot 只应用自己的本地 profile entry 并 materialize 为本群 Role，缺 entry 会安全 fallback 到默认角色，见 roles。 - Dashboard 建群：
botmux dashboard的 Groups 面板可可视化建群、把指定 bot 拉进群、自动转让群主、@ 提醒，也能解散群 / 让 bot 退群（关联会话自动清理）；新建群弹窗可选 Role Profile，见 dashboard。
会话状态机
流式卡片顶部的状态指示：
- 🟡 启动中 — worker 正在拉起 CLI 进程
- 🔵 工作中 — CLI 正在思考 / 执行，输出实时刷新
- 🟢 就绪 — CLI 空闲，等你的下一条消息
每次回复创建新的流式卡片，上一轮卡片冻结在最后状态，便于回看历史，卡片机制见 cards。
权限模型（三层）
| 层级 | 能力 | 由谁控制 |
|---|---|---|
| 对话权（canTalk） | 提问、查日志、读代码 | allowedChatGroups（群内全员）/ globalGrants（全局名单）/ /grant |
| 操作权（canOperate） | 切目录 /cd、/restart、/close、点卡片按钮 | allowedUsers（owner 名单） |
| owner 专属 | /grant /revoke 授权他人 | owner |
这套分层让你能放心把机器人拉进值班群：所有人能问，但只有 owner 能改会话状态，外部成员误点也不会把会话搞乱。权限细节见 faq。
常见困惑
- 「每次 @ 都像重新开始、丢上下文」：话题群里不同话题是不同会话——你以为在追问，其实开了新话题 = 新会话。想接着聊就在同一条话题里回复。
- 新群 / 新话题拉不到之前的聊天：新会话默认从干净状态起。要它读群历史，直接说「看下之前的聊天记录」（需机器人有群消息读取权限，见 faq）。
- 想换底层 CLI 又保留上下文：目前做不到跨 CLI 无损热切——原生会话历史不会翻译到另一种 CLI。要换 CLI 就开新 bot / 新 session，并让原 bot 输出一份 handoff 摘要交接。注意边界：
/relay是把同一个会话整体搬到另一个群、不换 CLI（见 session-handoff）；/adopt是把本机已有 tmux / zellij / 可恢复会话接进飞书，也不换 CLI。