# 私聊、群聊统一时间线

## 数据与能力边界

Chat `/api/v1/chat/timeline/unified` 是私聊和群聊结构的唯一远端 owner。消息、交织、群元数据、退群、AI 润色、公开快记及微信导入按服务端总序投影。seq 继续用于消息同步与已读，不作为展示游标。个人主题、快记与 DSH 会话历史保持原有读取路径。

| 能力面 | 实现与验证 |
| --- | --- |
| Host | 统一窗口 owner，五种读取模式、加密引用、部分失败与精确窗口恢复；协议和账号隔离测试 |
| UI | 主聊天与预览使用统一窗口；历史续页、回到最新、公开快记详情、成员提示及已读悬停回归 |
| Tools | 既有 source read 支持窗口参数；正式 Cordis SessionStore/ToolRuntime 注册与调用测试 |
| SDK | 公开类型、能力发现、取消、失败语义；独立 Consumer 安装 tgz 后严格编译与调用 |
| Client/Harness | 使用未修改的官方 DSH 和独立桌面 Profile 装配 tgz；客户端无源码改动 |

## 窗口与恢复

- 事件身份与 Record 身份分离；同毫秒使用完整服务端排序键。
- initial、older、newer、around、refresh 不混用游标。正文暂不可用时保留事件位置，gap 保留上次确认内容，not_applicable 退役对应来源。
- refresh 串行读取完成后整体发布；失败保留当前已确认窗口。仅精确的窗口失效错误允许一次重新建立窗口，404 不回退旧结构接口。
- 首次进入无位置记录的对话定位最新；普通切回恢复已记录的阅读位置与历史窗口，原本停在底部则继续跟随末端。主动点击“回到最新”以及搜索、日历等显式定位按各自目标导航。首次本地缓存显示后用户主动上翻，后台结果保留阅读位置。
- 历史分页保持视口并允许继续加载；明确区分“当前窗口底部”和“回到最新”。
- 本地待发送记录独立保留；已读 metadata 不取消合法读取。Realtime 作为结构失效通知，旧 seq 通知读取不直接替换展示窗口。
- 缓存按账号、环境、会话隔离，projection 修订隔离旧展示格式。窗口、页缓存及请求容量参见 [性能复查](unified-timeline-performance-review.md)。

## 展示与交互

公开快记使用移动端式发布入口：私聊显示“对方发布了一条新的公开快记”，群聊显示“姓名 的世界有更新”。列表不预取正文；点击通过 `world.record.read` 重新确认公开状态，并复用 WorldCard 的正文、图片及评论。关闭恢复焦点，切换或关闭取消读取。UI、SDK `readWorldRecord` 和既有 `arkme_world_recent(record_ref)` 共用 WorldService。

群聊成员快照按后端合同允许为空。入群提示优先使用 `group_display_name`，缺失昵称由现有 Profile owner 按当前页去重、每批最多 50 人补齐。最多一页 100 条事件、200 个成员或操作人引用，不逐事件发请求、不读取全量成员结构。

识别权威 `join_source` / `join_actor_user_id` 并兼容历史邀请字段；双方昵称高亮，区分“邀请”与“添加”。无邀请证据时显示普通入群事件，不虚构邀请人。主聊天已有成员目录匹配时复用资料按钮，目录暂缺时保留高亮文本。

交织卡片统一管理悬浮提示；已读注册独立于悬停。刷新先消费通知，并通过 ref 读取旧接口兼容状态，避免新引用改变回调后重放相同通知。读取中收到新通知使用既有有限追赶，不新增轮询或并发刷新 owner。

## 验证与交付范围

- 开发基线：插件 `03d07a6e9649c2813055b64ab9d4b59127fc3bf3`；客户端 `691dab7af43f83da3c59dddb26d4d41a22c81f8d`。PR 合入最新 dev 后的测试结果以 PR 验证记录为准。
- 最终功能源码全量入口：`NODE_OPTIONS=--no-experimental-webstorage pnpm test --maxWorkers=2`。合入新基线前 873 文件通过、11 文件跳过，10,272 项通过、15 项跳过。类型检查与完整打包通过。
- 独立仓外 Consumer 的严格 TypeScript 编译、SDK 调用通过；正式 DSH 会话测试使用协议 fixture，不等同于生产账号验收。
- 已在 macOS 独立客户端核验公开快记打开与关闭、日历定位后续页与回到最新、切换对话回到末端、群成员昵称按钮；用户已确认持续悬停闪烁消失。具体历史邀请记录仍待同一记录实测，Windows/Linux 未实际运行。
- 验收制品 `plugin-member-join.tgz`，SHA-256 `74eb693da95e6c8652579a022ae2344614c651e4404315050b9ed243ea616a49`；运行 Profile 的 Host 与 Browser 摘要均与制品一致。该制品对应合入新基线前的功能源码。
- 保持插件版本 0.1.91；根 README、版本元数据、客户端和 DSH 源码未修改。PR 不包含生产发布或常驻实例替换。后端统一接口需已启用，离线页缓存不是全历史离线索引。