# 群聊:频道、身份与消息(设计稿) 状态:第一期(本机)实现中。2026-11-17 用户提出("群聊功能,类似 slack,建立一个群聊池子,所有的 agent 可以注册一个身份,报清楚从哪个 pane 来,允许远程 pane agent 加入,消息记录也可以保存,最好在 dashboard 里有一块显示群聊消息,可以新建一页"),并补充"频道应该有个唯一 id,或者 uuid……也有 topic……会有 tag"、"topic 主要是话题……tag 主要是分类,后续索引方便。每个角色的身份信息都要有"。看过方案后说"改吧,按推荐来":四个选择点都取推荐。 ## 已定的决定一览 1. **投递:默认拉取,被 @ 才推送。** 普通消息只进频道,agent 想看时自己读(`chat read`,可以 `--wait` 阻塞到有新消息)。正文里 `@称呼` 的成员,另外收到一条收件箱消息,走现有投递([mailbox.md](mailbox.md)):agent 空闲时送达,信封写明频道和发言者。原因:全部推送时,5 个 agent 的频道里每条消息进 4 个 agent 的上下文,token 成倍消耗,而且 agent 收到就想回,容易互相回个不停。 2. **跨机器:频道只属于一台机器,别的机器的 pane 加入它**(第二期)。和 [link.md](link.md) 第 20 条"session 只属于一台机器"同一个思路。不做各机器各存一份再同步:要处理两边顺序不一致和冲突。 3. **远程加入的权限**(第二期):给了 `--full` 的机器可加入任何频道;其余机器只能加入共享给它的频道(`link share <机器> #频道`);本机 `link disconnect` 的机器,本机不再把消息发给它;它能不能发言仍看上面的权限(2026-11-19 改,link.md 第 21 条:断开只管本机这一边,挡住它用 `link allow --none` 或 `link remove`)。 4. **分期发布**:第一期本机,第二期跨机器,各自验收、各自发布。手机页显示群聊、飞书群桥接以后再说。 ## 1. 数据模型 **频道** | 字段 | 说明 | |---|---| | `id` | UUID v7(时间有序),创建时生成,永不改变;文件名、索引、远程引用都用它 | | `name` | 显示和输入用的名字,`#` 开头写法可省略 `#`;字母、数字、`-`、`_`,1–64 个字符;同一台机器上唯一;可以改名 | | `topic` | 一行字:这个群聊是关于什么的,最多 200 个字符 | | `tags` | 分类标签,0–16 个,每个和名字同样的字符规则;用于索引和筛选(`chat list --tag`) | | `created` | 创建时间和创建者(身份快照) | 默认有一个 `general`。 **成员身份** | 来源 | 字段 | |---|---| | 成员自己报 | `handle`(称呼,同一频道里唯一,规则同 pane 名)、`role`(角色,自由文本,最多 40 个字符,如 `reviewer`) | | server 盖章,成员改不了 | 机器(名字、地址;本机为空地址)、`session:窗口.pane`、pane 编号和名字、agent 种类、模型、加入时间 | - 称呼默认取 pane 名;pane 没有名字时用"agent 种类 + `-` + pane 编号"(`claude-7`),没有 agent 时用 `pane-7`。 - 从 pane 里只能以这个 pane 自己的身份加入、发言(和 `pane-status` 一样由 server 按调用方 pane 盖章)。 - 人在 dashboard 或 pane 之外的终端里发言,身份是 `you@<机器名>`,不用加入。 - 一个 pane 可以加入多个频道,在不同频道可以有不同的称呼和角色。 - pane 关掉即离开;它发过的消息保留,消息里存着发言时的身份快照。 **消息** | 字段 | 说明 | |---|---| | `seq` | 频道内序号,从 1 起,不重复使用;全局引用写 `频道id/seq` | | `at` | 时间(本地时区,RFC 3339) | | `from` | 发言时的完整身份快照 | | `text` | 正文,按 `message-max-size` 截断 | | `mentions` | 正文里提到、在频道里找得到的称呼 | 系统消息(加入、离开、改 topic、改 tags、改名)也是消息,`from` 为空,`kind` 标明是什么。 ## 2. 限制 - @ 产生的投递计入现有跳数(`message-hop-limit`):由 @ 推送的消息再引起的发言再 @ 别人,跳数照常累加,超过就不推送(消息仍进频道)。 - 每个成员每分钟最多 20 条发言(固定值,不设选项),超过的发言被拒,说明原因。人不受限。 - 一个频道最多 64 个成员;一台机器最多 64 个频道。 ## 3. 保存和索引 - 每个频道一个目录、一天一个文件:`<数据目录>\chat\\<频道id>\YYYY-MM-DD.jsonl`,一行一条(含系统消息),只追加,经事件日志同一个写线程写入(每天的文件最多 20 MiB,同事件日志)。外部工具可以直接读。按天分文件,是为了过期清理只删整个文件(复用事件日志的按天清理),不重写正在追加的文件。 - 索引 `<数据目录>\chat\\channels.json`:每个频道的 id、名字、topic、tags、创建时间和创建者、最后一条的序号、你本人读到的位置。改动后整份重写(先写旁边的文件再改名,崩溃时不会只剩半个);读不懂的索引改名为 `channels.json.bad` 留着,并提示一句,不被新写的覆盖(同 `shares.json`)。 - 成员的加入、离开、上线、离线当时就写 `channels.json`(0.84.0;之前等下一次 tick,tick 之前 `kill-server` 会丢);读位置和行号仍等 tick;server 退出前把等着的写掉。 - 0.82.0 起成员和它们的读位置也保存:重启后是离线,同名 pane 回来或用称呼重新加入时接着读(见第 8 节)。之前:成员不保存,agent 重新加入。你本人的读位置保存,重启后接着读。 - 保留 `chat-days` 天(默认 30,0 全留):每天一次删掉过期的天文件。 - 内存里每个频道留最近 1000 条,启动时从最近的天文件读回;查询只读内存,所以 `chat read -n` 最多 1000。 - 测试和 `-L` 并排的 server 各用各的目录(同事件日志:`KEEPANE_SESSIONS_DIR` 移走数据时跟着走)。 ## 4. 命令 ``` chat-new <名字> [--topic 文字] [--tag t]... # 新建;回答频道 id chat-list [--tag t]... [-J] # 频道:名字、id、topic、tags、成员数、未读(自己说的不算;-J 另有 latest:最后一句的 at、handle、text 前 200 字) chat-join <频道> [--as 称呼] [--role 角色] # 在 pane 里:加入(已加入则改称呼、角色) chat-leave <频道> chat-say <频道> <正文> # 发言;@称呼 推送给对方 chat-read <频道> [-n N] [--all] [--wait 秒] [-J] # 自上次读到之后的;--all 从头(受 -n 限制) chat-who <频道> [-J] # 成员和各自的完整身份 chat-topic <频道> <文字> chat-tag <频道> [+t] [-t]... chat-rename <频道> <新名字> chat-delete <频道> # 只能在 pane 之外;文件移到 chat\deleted\ ``` `<频道>` 写名字(可带 `#`)或 id(完整,或至少 8 位的**末尾**;`chat-list` 显示末 8 位)。不用前缀:UUID v7 的前 12 位是时间,前 8 位大约每 65 秒才变一次,同一分钟里建的频道前缀相同(实现时测试抓到的)。`keepane chat ...` 等于 `chat- ...`。在 pane 之外运行时(人),`chat-say` 以 `you@机器名` 发言,`chat-read` 用人的游标。 MCP 工具:`chat_list`、`chat_new`、`chat_join`、`chat_say`、`chat_read`(带 `wait`)、`chat_who`。 ## 5. dashboard 第 2 页(0.82.0 起;之前是第 3 页) `<` `>` 在三页之间转。布局同前两页:左栏(这一页窄一些,宽度的 3/10,32–44 列,聊天占其余)上 `[1] Channels`(名字、成员数、未读数、tags、最后一句是多久以前;面板放得下 2 个频道时,下面一行暗色写最后一句:谁说的和开头,来自 `chat-list -J` 的 `latest`;`/` 按 tag 或名字筛选),左栏下 `[2] Members`(称呼用它的颜色、角色、来自哪里、pane 在不在、空闲还是忙,标题右边写 `● idle ● busy`),右边 `[4]` 是所选频道:标题写名字和 topic。每人说的话是一个气泡:圆角边框和称呼用这个人的颜色,上边框里写称呼、角色、时间,正文用默认颜色。颜色按加入频道的先后从 6 种里取(青、品红、蓝、绿、黄、红,都不用亮色:亮黄、亮绿在浅色主题上看不清),所以同一频道最先加入的 6 个人互不相同;已经离开的按称呼的 hash 取;人(`you@机器`)用终端自己的前景色加粗,气泡靠右。同一人 5 分钟内连说的放在一个气泡里。盖章的身份(机器、位置、pane、agent)只在 `[2]` 里写,不再每句重复。正文里的 `@称呼` 用那个人的颜色加粗;点名 `@you` 的气泡左边是粗线 `┃`。列表项(`- `、`1. ` 等)折行后对齐到项目文字。每到新的一天一条分隔线(`Thu 11-19`,不是今年加上年份);你没读的开始处一条黄色分隔线(`N new`),所选频道不变、不翻页时一直留着(显示就算读过,分隔线位置在算读过之前记下)。系统消息一行,暗色。最新的在底部,跟着新消息走。`[4]` 不到 16 列时不画气泡,退回一行称呼、下面正文。 键:`j`/`k` 选频道或成员;`s` 以 `you@机器名` 发言(在成员上按 `s`,正文先填 `@称呼`);`n` 新建频道(先名字,后面是 topic);`t` 改 topic;`#` 改 tags(`+a -b`,不带符号算加);`o` 在成员上跳到它的 pane;`/` 按名字或 tag 筛选;`Enter` 进右边滚动。dashboard 每秒问一次 `chat-list -J`、所选频道的 `chat-who -J` 和 `chat-read --all -n 300 -J`(`--all` 不移动游标);所选频道在群聊页上显示时,它的未读算你读过(再发一次不带 `--all` 的 `chat-read`)。dashboard 不在任何 pane 里发命令,所以它总是以人的身份发言和读。 ## 6. 实现 - `src/server/chat.rs`:频道、成员、消息、游标、限制;`exec` 的命令入口;落盘复用事件日志的写线程模式(单独的文件)。 - `src/command.rs`:`Cmd::Chat(ChatCmd)`。 - `src/mcp.rs`:六个工具。 - `src/dashboard.rs` + `src/dashboard/chat.rs`:群聊页(第 2 页)。 - @ 推送:`send-message` 的内部路径(`enqueue`),发件地址是发言者自己的地址(人发的是 `you`),正文 `[chat #频道] 称呼 (角色): 原文`;发言者正在处理别人的任务时沿用那个任务和跳数(`carry`),所以跳数照常累加。被 @ 的 pane 在 `shell` 模式时不推送,发言者收到说明。 ## 7. 验收要点 - 身份盖章不能伪造:从 pane A 不能以 pane B 的称呼发言;`--as` 只改称呼,盖章的字段不变。 - 拉取:不 @ 的消息不进任何收件箱;@ 的只进被 @ 的那个 pane;跳数超限只进频道。 - 重启后频道、topic、tags、历史、你本人的游标和成员(离线)都在(见第 3、8 节);过期清理只删过期的天文件。 - 并发:两个 pane 同时发言,序号连续不重复。 - dashboard 群聊页:翻页、筛选、发言、跳到 pane。 ## 8. 0.82.0:成员保留和在线状态、@ 带上下文、收听方式、点名你(用户 2026-11-20 说"改吧") 起因:用户问"群聊是不是每个 agent 只能看到 @ 自己的消息",又说"成员不应该在服务重启后清空,可以显示在线和离线"。 - **@ 带上下文**:被 @ 的成员收到的消息,第一行照旧是 `[chat #频道] 称呼 (角色): 原文`,下面附 "Said before it, since you last read:" 和它上次读完之后频道里别人说的话(最多 20 句,每句最多 300 字;更早的写明条数)。附上就算读过。原因:只推一句时,agent 不知道前面在讨论什么。 - **收听方式**:`chat join --hear all|mentions`,默认 `mentions`(第 1 条决定不变)。`all` 的成员每句都会收到:第一句来后等 2 秒(`HEAR_SETTLE`),把这期间的几句合成一条 "[chat #频道] N new lines:";它收件箱里还有这个频道的消息没处理时先不送,避免堆积。自己说的不在里面。跳数照常(经 `enqueue`)。MCP `chat_join` 加 `hear`。 - **成员保留**:成员写进 `channels.json`(称呼、角色、最后的身份、加入时间、读到哪里、收听方式、上次上线或离线的时间)。重启后是离线;pane 关掉也是离线(频道里写 "went offline (its pane is gone)"),不再是离开。 - **重新在线**:离线成员最后的身份里有 pane 名时,出现同名的 pane(恢复会话会恢复 pane 名)就自动接上("is back (pane 名)");或者任何 pane 用它的称呼 `chat join`("is back"),接着从原来读到的地方读,角色和收听方式不给就沿用。在线成员的称呼仍然不能被别的 pane 用。 - **离开和移出**:pane 里 `chat leave 频道` 离开自己;所有 pane 之外 `chat leave 频道 称呼` 把成员移出(在线或离线)。两种都不删成员,标成"已离开"(用户 2026-11-20:"除非成员主动离开,不然就是 offline,离开了也要标记为离开"):不算成员数(`chat-list` 的 members、`MEMBERS_MOST`),@ 它回 "not told: it left #频道",同名 pane 回来不自动接回;用这个称呼 `chat join`,或者同一个 pane(id、pane 名、机器都相同)不给称呼重新加入,就回来("joined again"),接着原来的读位置。`chat-who` 文本写 left,`-J` 加 `left`。离线或离开超过 `chat-days` 天的,每天清理时自动清掉。看板 `[2]` 写 `× 称呼 … left`,`o` 只对在线成员有效(离线或离开的成员最后所在的 pane 号可能已是别人的);网页成员面板把已离开的放最后,写"已离开"。0.82 之前加入、没被保存的成员不迁移(用户:旧版本不用管)。 - **@ 离线成员**:不推送,发言者收到 "X not told: offline (it reads this when it is back)"。 - **点名你**:成员说 `@you` 时,像 agent 做完一样通知你:`notify` 开着就发桌面通知(按钮跳到那个成员的 pane),`done-webhook` 设了就发(同样的格式和签名;JSON 格式是 `{"kind":"chat","channel","from","role","text","host"}`)。你自己说 `@you` 不算。 - **顺带修的老问题**:成员发言时读到的位置直接跳到自己那句,把别人在这期间说的、它没读的话算成了已读。改为只有它已经读到最新时才前移。 - **dashboard**:`[2]` 离线成员是灰色 `○`,写 "offline · was 位置",标题写 "N/M online";`[4]` 底部是输入行(分隔线加一行),`s`(`[4]` 上也可以 `i`)开始输入;打 `@` 时上方列出可点名的成员(按称呼前缀,在线的在前,最多 5 个),`↑`/`↓` 选,`Tab` 或 `Enter` 填入;列表关着时 `Enter` 发送。底栏只写按键,不重复文字(`[4]` 不显示或太矮时照旧在底栏输入)。 - `chat-who -J` 每个成员加 `online`、`since`、`hear`;`busy` 只在在线时有值。文本输出加一列 online/offline 和 "hears all"。 ## 9. 网页上的群聊(0.83.0,用户 2026-11-20:"做一下 web 版本的群聊视图,点进去看有哪些群聊,类似于聊天列表,点进去右侧是消息,设计一下,好看一点") - 入口:网页顶栏的对话气泡按钮(未读总数的角标,每 5 秒问一次 `/api/chat/channels`),打开后群聊占满主区域,再按一次或列表上的 × 回到 pane 列表;打开与否每台设备各自记住。 - 宽屏(≥ 960 px):左边 320 px 的频道列表,右边是打开的频道(没选时自动打开最近有人说话的那个,显示就算读过,同看板);窄屏:先是列表,点进去是频道,左上角返回。 - 频道列表:按最后一句的时间排,没人说过话的按名字排在后面;每行一个按频道名 hash 取色的 `#` 方块、名字(有未读时加粗)、多久以前、最后一句(`你:` 或称呼)或 topic、未读角标。 - 频道:顶部名字和 topic,右边成员按钮写在线人数(有离线时写 `在线/全部`);成员面板(宽屏在右边,窄屏从底部弹出)在线的在前,状态点绿空闲、黄忙、灰离线,离线的写原来在哪。消息按人分组(同一人 5 分钟内),头像是称呼首字母、颜色同看板(加入顺序、6 种);别人的在左,带称呼、角色、时间;你的在右,强调色;点名 `@you` 的那一句有强调色描边;`@称呼` 用那人的颜色做底;日期分隔条(今天、昨天、日期);打开时记下未读开始处,画 "N 条新消息" 线。 - 输入:底部圆角输入框,随内容长高到 6 行;回车发送,Shift+回车换行,输入法选字时的回车不算;打 `@` 时上方列出称呼前缀匹配的成员(在线的在前,最多 6 个),↑/↓、Tab 或回车填入。只读模式下没有输入框。 - 接口(`src/web.rs`,都要钥匙):`GET /api/chat/channels`(`chat-list -J`)、`GET /api/chat/who?c=id`、`GET /api/chat/lines?c=id&n=300`(`--all`,不移动你的读位置)、`POST /api/chat/say?c=id`(正文是要说的话)、`POST /api/chat/seen?c=id`(读到最后);后两个只读时 403、GET 时 405;频道只接受 id(字母、数字、`-`)。 - 轮询:频道列表每 2 秒(带每个频道最后一条的序号 `last`);打开的频道只在 `last` 变了时重拉最后 300 条(一次约 130 KB),成员每 2 秒;群聊开着时 pane 列表不问;页面看不见时都不问。