# 升级路线图（ROADMAP）

> 本文是 huahua-dsh-chatroom 的演进规划。事实基础：《运行机制研究与方案》（见 `docs/mechanism-study.md`）末尾"建议落地清单"6 项 + Q2/Q3/Q5 中暴露的扩展与容灾缺口。状态以本仓库发布为基线（M0）。

**工作量图例**（估算单位：人日，按熟悉双机调试环境的单人开发计）：
S ≤ 0.5d ｜ M 0.5–3d ｜ L > 3d

**状态图例**：✅ 已落地（本期发布）｜ 📌 约定/规范（0 开发量）｜ 🔧 开发项｜ 🔭 远期探索

**落地清单溯源**：《机制研究》建议清单 6 项 → ①使用规范→P1 ②归档提醒→P2 ③上下文观察→P3 ④Fix4 帧上限→M0（**已完成**）⑤附件引用协议→R1 ⑥主动读消息工具/notifyMode→R2；R3/R4/F1 由 Q2/Q3/Q5 的扩展与容灾缺口补充。

---

## 全景总览

| # | 里程碑 | 类型 | 状态 | 工作量 | 依赖 |
|:--|:--|:--|:--|:--|:--|
| M0 | 基线发布：Fix1–Fix4 四合一补丁 + 文档集 | 补丁/文档 | ✅ | — | — |
| P1 | 会议室使用规范（@ 点名 / @all 群议 / 不 @ 留档） | 约定 | 📌 | 0 | — |
| P2 | 归档提醒机制（2000 条窗口备份） | 约定→脚本 | 📌→🔧 | S | — |
| P3 | 上下文观察规范（compaction / 重要结论入知识库） | 约定 | 📌 | 0 | — |
| R1 | 文件传输 L1：附件引用协议 | 开发 | 🔧 实施中（路线A） | M | M0 |
| R2 | agent 主动读消息工具 + notifyMode（值班模式） | 开发 | 🔧 | M | M0 |
| R3 | 多 agent / 多机扩展工具化（批量 trust + 成员 onboarding） | 开发 | 🔧 | S | M0 |
| R4 | host 高可用与容灾迁移 | 开发 | 🔧 | M | P2 |
| F1 | 文件传输 L2：Iroh blob P2P 直传 | 开发 | 🔭 | L | R1 |

---

## M0 · 基线发布（✅ 本期交付）

**范围**：Fix1–Fix4 四合一幂等补丁（`patches/patch-weave.ps1`）+ 补丁说明 + 机制研究/使用指南 + 排障报告链（`docs/weave-integration-report.md` → `docs/weave-postmortem.md` → `docs/fix3-frame-limit-postmortem.md`）+ 全景图 + 本路线图。

**帧上限演进注记**：`64KB → 1MB(Fix3) → 4MB(Fix4)` 两次演进已在此收官。**原则：4MB 之后不再靠继续加大帧上限解决大内容** —— 帧走 JSON 文本通道，体量会挤占 2000 条消息窗口与 UI 时间线渲染；更大的内容应走 R1 附件引用协议，而不是加帧。

---

## P1 · 会议室使用规范（📌 约定，0 工作量）

- **动机**：唤醒是点对点的 —— 只有被 @ 命中的 agent 才会被投递唤醒（每唤醒一次 = 一次完整模型请求 = token + 上下文增长）。无规矩则群聊变"全员打扰"。
- **方案要点**（详见使用指南）：
  - 找人办事 → `@成员`；全员讨论/汇报 → `@all`（token × N，控制频率）；留档/通知（无需 agent 响应）→ 直接发、不 @。
  - 大段内容拆要点或放文档/路径引用，别整篇贴聊天。
- **验收**：团队内形成统一 @ 习惯；无"群聊消息淹没上下文"投诉。
- **状态**：✅ 随 M0 交付（文档已固化），持续执行。

## P2 · 归档提醒机制（📌 约定 → 🔧 S）

- **动机**：host 权威存储是 **2000 条滚动窗口**，超过即裁剪最老消息（历史有界）。Q1 实测 58 条 ≈ 70KB，但高频会议很快就会触及窗口；被裁掉的最老消息若不备份即永久丢失。
- **方案要点**：
  1. host 定期备份 `~/.dsh/dsh-chat/rooms.json`（全量聊天 + 投递状态，复制即备份）—— 小脚本 + 计划任务（每日/消息数阈值）；
  2. 窗口接近上限（如 ≥1800 条）时提醒 host 人工归档（导出 md / 知识库）；
  3. 可选：备份文件名带日期滚动保留 N 份。
- **工作量**：S（纯脚本化 0.5d；若只做约定则 0）。
- **依赖**：无。**建议最先落地** —— 它是 R4 容灾的地基。

## P3 · 上下文观察规范（📌 约定，0 工作量）

- **动机**：被 @ 投递的消息像普通对话一样占模型上下文窗口；token 达窗口 80% 会自动 compaction（早期历史压成摘要 + 保留尾部 16% 原文）。压缩是正常现象，但关键结论若只存在会话里会随摘要变淡。
- **方案要点**：高频 @ 会话留意摘要压缩节点；重要结论/决策及时归档进知识库（如 gbrain）；压缩后仍可从全量日志（`~/.dsh/sessions/...`）回查。
- **验收**：重要结论有会话外落点。
- **状态**：随 M0 交付并持续执行。

## R1 · 文件传输 L1：附件引用协议（🔧 M · 实施中，路线 A）

> **2026-09-06 启动实施**：规格见 [`docs/FILE-TRANSFER-L1.md`](FILE-TRANSFER-L1.md)。路线 A=零 dsh-chat 改动：kit 插件承载附件存储（`~/.dsh/dsh-chat/attachments/<roomId>/`）与 HTTP 端点（默认端口 3090）+ `chatroom_file_upload/fetch` agent 工具；消息走规范文本（`[文件] 名称 (大小) <url>`）。验收同下（>1MB / 窗口仅增几十字节 / sha256）。

- **动机**：Q5 —— 现状**不支持文件传输**：dsh-chat 消息模型只有 text（`ensureText`），无附件字段；weave 帧是 JSON 文本通道（Fix4 后 4MB，base64 嵌入实际可用 ~3MB 且挤占消息窗口）；现有 dsh-at-file / dsh-share 都不是房间内文件传输。
- **方案要点**（消息传元数据，文件走 HTTP）：
  ```
  发件人：文件 ──> host 附件存储（~/.dsh/dsh-chat/attachments/<roomId>/）
                       │ 生成 {name, size, sha256, url: http://<host>:<port>/chat-file/<id>}
  消息文本 = "[文件] 报告.pdf (2.3MB) <url>"
  收件 agent：识别 url ──> HTTP 下载到本地 ──> 处理
  ```
  - weave 只传几十字节元数据，帧限制无压力；文件本体走局域网 HTTP（快、可靠、支持大文件）。
  - 改动点：dsh-chat 加附件字段 + host 提供静态文件端点 + UI 拖拽上传 + agent 端识别下载（前后端各一块）。
- **工作量**：M（改动中等）。
- **验收**：房间内 A→B 传 >1MB 文件成功；消息窗口只增几十字节；下载校验 sha256。
- **过渡方案 L0**（零开发，今天可用）：<1MB 文本直接贴/base64；路径引用（共享盘）；图片/文档走现有通道（文件回传/桌面/IM），房间内发"已发 xx"通知。

## R2 · agent 主动读消息工具 + notifyMode（🔧 M）

- **动机**：Q4 缺口 —— 现状"不 @ = 全体 agent 无感知"，无法满足"值班 agent 监听房间"需求（如：想让某 agent 对房间每一条消息都感知、或按时间汇总）。
- **方案要点**：
  1. **agent 主动读消息工具**：把 host 本地 RPC `/dsh-chat/messages` 封装为 agent 工具（按 cursor 增量拉取 + 按消息 id 去重），agent 可主动拉历史/增量；
  2. **静默摘要（方案 B）**：agent 端定期（每 N 分钟或消息积压达阈值）拉一次增量，把新消息压成紧凑摘要进上下文，不逐条唤醒；
  3. **notifyMode（方案 C）**：房间级配置 `off`（现状）/ `mention`（默认，只 @ 唤醒）/ `all`（全员每条投递 —— **谨慎，token 线性爆炸**）。
- **工作量**：M（agent 工具封装 + 房间配置 + 摘要调度）。
- **依赖**：M0；与 R1 无冲突可并行。
- **验收**：值班 agent 在房间不 @ 的情况下按周期感知新消息；notifyMode 三档均可切换并如实计费（token 可观测）。

## R3 · 多 agent / 多机扩展工具化（🔧 S）

- **动机**：Q2 —— 房间成员模型本就是多 agent 设计（members 同时容纳本地 session 与远端 weave 主机会话，新成员加入不需改协议），但**无自动发现**：新机需手动 trust + 添加，机器 <5 时够用，>5 后 onboarding 成本线性上升。
- **方案要点**：把"新增一台 agent/机器"流程固化为脚本/清单：
  1. 新机装 DSH + dsh-weave，固定端口 64605 → 互换 weave ticket 并 `weave_trust` → peers.json 持久化（只做一次）；
  2. host 在会议室 Settings → Add session 添加远端会话为成员；
  3. 批量 trust 脚本（多机场景）。
- **工作量**：S。
- **验收**：脚本化后新机入房 <5 分钟。
- **已知限制备忘**：@all 成本随 N 线性放大（默认点名）；成员粒度是"会话"不是"机器"（一台机可多会话入房，需分别添加）。

## R4 · host 高可用与容灾迁移（🔧 M）

- **动机**：Q2/Q3 —— **host 单点**：host 关机则消息发不出、历史拉不到（其余成员只能看本地缓存 rooms.json 已拉取部分）。对依赖会议室的协作，这是最高风险点。
- **方案要点**：
  1. **约定 host 常开**（近期零成本），或重要讨论的另一方也建 host 房间做归档（双写）；
  2. **迁移手册**：新 host 拿到 `rooms.json`（全量 + 投递状态）+ 重建成员邀请即可续用 —— 把该流程写成 runbook；
  3. **备份自动化**：复用 P2 的定期备份，做"备份 → 可切换"的容灾闭环（P2 是 R4 的地基）。
- **工作量**：M（runbook + 备份/切换脚本；不引入双活）。
- **验收**：模拟 host 故障，按 runbook 在 <30 分钟内于另一台机恢复房间并续聊。

## F1 · 文件传输 L2：Iroh blob P2P 直传（🔭 远期探索）

- **动机**：Q5 远期 —— R1 走 host 中转，大文件仍依赖 host 在线与带宽；weave 底层即 Iroh（原生支持 content-addressed blob 分发、断点续传、多端拉取），可做到**不经 host 的 P2P 直传**。
- **方案要点**：扩展 dsh-weave 暴露 `sendBlob(peerId, path)`，利用 Iroh blob 协议传输。
- **工作量**：L（改动最深，不建议近期投入）。
- **前置**：R1 落地后按需再评估。

---

## 推荐实施顺序与依赖

```
M0（已完成）
 └─ P1/P3 约定随用随守（0 成本）
 └─ P2 归档提醒（S）──────────────┐
     └─ R4 host 容灾迁移（M）＜────┘（复用 P2 备份）
M0 → R2 值班模式（M）‖ R1 附件协议（M）  ← 无互相依赖，可并行
M0 → R3 多机 onboarding（S）随时可做
R1 → F1 P2P blob（L，远期评估）
```

**排序建议**：P2（防丢）→ R2/R1（能力补齐，按需求急迫度）→ R3（规模化）→ R4（容灾，可与 P2 合并推进）→ F1（观望）。

---

## 变更记录

| 日期 | 变更 |
|:--|:--|
| 2026-09-04 | 初版：基于机制研究落地清单 6 项扩展为 M0–F1 里程碑（新增 R3 多机 onboarding、R4 host 容灾；Fix4 由"建议项"转为 M0 已落地）。 |
| 2026-09-06 | R1 启动实施（路线 A：零 dsh-chat 改动，kit 承载附件存储+HTTP+agent 工具）；新增规格 `docs/FILE-TRANSFER-L1.md`；全景表状态列同步。 |

*本文档随发布演进更新；事实溯源见 `docs/mechanism-study.md` 与各 `reports/` 报告。*