MSG 消息与会话

August 11, 2026 · View on GitHub

当前状态：已实现 基线：工作树 2026-08-11 平台：桌面端与网页版

1. 目标

提供兼容 Rocket.Chat 的确定性沟通界面，让团队讨论、原始上下文、来源链接和文件留在消息系统中；AI 可以读取被授权的上下文，但不能替代消息真源。

2. 范围

包含

  • 房间、频道、私聊和 Discussion 列表；
  • 收发、引用、编辑、删除、反应、线程与已读；
  • 历史分页、实时更新和断线恢复；
  • 快速搜索、房间内/全局消息搜索、用户/频道/文件筛选；
  • 文件上传、下载、文件索引和桌面下载记录；
  • 置顶、收藏、提及、成员、信息等右侧面板；
  • 本地草稿、会话分组、别名等个人整理能力；
  • 私聊头像和会话项的在线状态提示。

不包含

  • 自建一套与 Rocket.Chat 分离的消息库；
  • 保证搜索到服务器权限范围外或已删除的内容；
  • 网页版直接打开任意本地路径或系统文件管理器。

3. 入口与前置条件

  • 用户已登录 Rocket.Chat。
  • 左侧“消息”进入会话列表；顶部/侧栏搜索进入快速搜索或全局搜索。
  • 文件上传需要所在房间允许上传；编辑、删除等动作受 Rocket.Chat 权限控制。

4. 主流程

  1. 登录后加载订阅和最近会话，未读、提及、置顶及在线状态随实时事件更新。
  2. 用户普通打开会话时创建独立 generation；历史与容器就绪后贴到最新消息，并在布局复核通过后完成本次打开事务。
  3. 用户发送文本、图片或文件；成功后以 Rocket.Chat 返回消息为真源。
  4. 用户可引用、反应、进入线程、编辑或删除有权限的消息。
  5. 用户搜索中文名字时，用户目录按服务器可见范围返回并展示匹配用户。
  6. 用户搜索消息/文件时，可组合范围和类型筛选，并从结果跳回原会话。
  7. 私聊会话列表和会话标题头像显示在线、离线等状态；无状态数据时不伪造在线。

5. 状态与交互

  • 连接中：保留可用缓存，避免把旧内容显示成最新状态。
  • 就绪：实时事件更新消息、房间和用户状态。
  • 加载更早：保持滚动锚点，避免列表跳动。
  • 普通打开：首次打开、同房间重复打开和缓存重开均生成新事务；旧历史、旧帧和旧尺寸观察回调不能修改当前会话。
  • 消息定位：搜索、提及和通知使用 locate 事务，优先于普通贴底；用户主动滚动后停止强制贴底。
  • 空会话/空搜索：说明当前范围没有结果，并保留修改筛选入口。
  • 发送失败：明确失败消息，不把本地乐观项当作已发送。
  • 断线：显示连接状态，恢复后重新同步必要数据。

6. 平台与依赖

场景当前状态行为
桌面端已实现使用 Rocket.Chat API，并增加原生文件保存/打开/定位能力
网页版已实现使用浏览器上传下载；建议同源反向代理以避免 CORS
中文用户搜索已实现受用户目录权限和服务端搜索结果限制
中文消息子串搜索受限可用服务器需允许正则/子串搜索配置

7. 数据与同步

  • 消息、线程、房间、成员和在线状态以 Rocket.Chat 服务端为真源。
  • 本地缓存、草稿、文件索引、下载记录和个人会话整理按服务器与用户隔离。
  • 下载记录只记录用户已执行的本机下载，不代表服务端文件仍存在。
  • 实时断线恢复后必须以 REST/实时事件重新校准，不依赖单次本地快照。

8. 权限与安全

  • 只能读取当前账号有权访问的房间和文件。
  • 编辑、删除、置顶和成员操作由 Rocket.Chat 权限最终裁决。
  • 消息内容、文件名和 Markdown 均作为不可信输入渲染，不能执行内嵌脚本。
  • AI 托管读取消息时沿用当前用户可见上下文，不扩大服务器权限。

9. 失败与降级

场景用户可见结果副作用与恢复
实时连接中断显示离线/重连状态不丢弃输入；恢复后同步
发送请求失败消息标为失败或提示错误不宣称已送达；允许重试
搜索 API 不支持中文子串返回零结果或服务端错误，并提示服务器限制可改为精确词或联系管理员开启配置
在线状态缺失不显示在线绿点或显示未知不用最后消息时间推断在线
文件无权限/已删除下载失败提示不创建有效下载记录；重新获取权限后重试
浏览器跨域阻止请求显示连接失败通过同源部署/代理修复，不降级到不安全绕过

10. 验收标准

  • MSG-AC-01：收发、引用、反应、线程、编辑和删除均以服务端确认后的结果为准。
  • MSG-AC-02：加载更早消息时，用户当前阅读位置不发生不可控跳动。
  • MSG-AC-03：中文姓名可从用户搜索和通讯录结果进入私聊，不因仅按用户名匹配而漏掉显示名。
  • MSG-AC-04：私聊会话项与会话标题头像使用同一真实在线状态；离线用户不显示在线标记。
  • MSG-AC-05：搜索筛选可区分消息、文件、用户和频道，并能回到来源。
  • MSG-AC-06：桌面文件下载可保存到用户选择位置并写入当前账号的下载记录；网页版使用浏览器下载。
  • MSG-AC-07：断线恢复后新消息和房间状态能重新同步，不要求用户刷新整个应用。
  • MSG-AC-08：普通打开在布局稳定后 bottomGap <= 2px；消息定位、翻页锚点和用户主动离底不被覆盖，滚动诊断可随桌面诊断日志脱敏导出。

11. 实现与测试证据

  • 实现：apps/web/src/stores/chat.ts、apps/web/src/lib/client.ts
  • 实现：apps/web/src/components/ChatArea.tsx、会话列表、搜索和右侧面板组件
  • 自动化：scripts/regressions/quick-search.test.ts、scripts/regressions/search-filters.test.ts
  • 自动化：scripts/regressions/user-search.test.ts、scripts/regressions/user-directory.test.ts
  • 自动化：scripts/regressions/file-index.test.ts、scripts/regressions/download-history.test.ts
  • 自动化：scripts/regressions/message-scroll.test.ts、scripts/regressions/diagnostics.test.ts
  • UI：tests/ui/core-flows.spec.ts、tests/ui/download-history.spec.ts

12. 已知差距与目标

  • 中文消息子串搜索仍依赖 Rocket.Chat 服务端设置，客户端不能在未下载的全量历史上可靠补偿。
  • 在线状态在服务端不提供或权限受限时只能显示未知，不能做推测。
  • Windows WebView2 正式安装包仍需连续切换缓存/未缓存房间并记录 bottomGap；macOS/Linux 同步做桌面冒烟。