# 压缩接力 · 目标与路线图

> 版本基准：0.4.2（2026-10-25）｜状态：0.3 已发布（npm + GitHub），0.3.6 已发布，0.4.0 已发布（npm latest + GitHub tag/Release），0.4.1 已发布；**0.4.2 交接线保命补丁已实现、待验收与发布**；**0.5.0 命名反转 + 接力条 + 交接后自动归档/恢复已实现（未提交、未发布）；双向跳转的父→子入口与里程碑面板待实现（见 §三 0.5.0）**
> 维护方式：每次发布前更新"当前状态"与勾选进度；方向变化必须同时改本文件和 memory 项目页。

## 一、最终目标（North Star）

**让"上下文容量"从用户的日常决策里消失。**

任何长度的任务都能连续推进：压缩、换会话、换模型都不丢进度、不丢关键决策、不丢改过的文件；用户只需要说"继续"，不需要自己搬上下文。

定位：DSH 的**上下文接力层**——不是压缩算法，也不是仪表盘。

### 判断是否做到的四个指标

| 指标 | 目标 |
|---|---|
| 长任务中用户手动处理上下文的次数（`/bc`、`/handoff`、`/pin` 等） | 逐步趋近 0（0.5 之后只保留确认动作） |
| 交接后新会话**无需用户补充说明**即可继续工作的比例 | 0.4 ≥ 90%，0.5 ≥ 95% |
| 压缩/交接导致的进度丢失事件 | **0** |
| 交接单一次通过（无需重试）的比例 | 0.4 ≥ 90% |

## 二、设计原则

1. **人可检查、可取消**：压缩先预览、交接先出单；不静默改历史。
2. **不重复造平台能力**：压缩算法、仪表盘、自动触发已有成熟插件，我们做"接力质量"，需要时兼容/集成，不硬碰。
3. **连续性优先于省钱**：宁可多留一点原文，也不让接手者缺关键信息。
4. **可回看**：压缩前后 diff、交接链、交接单全文都要能查。
5. **小步发布 + 真机验证**：没在真实长会话验证过的功能不上默认路径。

## 三、路线图

### 0.2.5 ✅ 发布准备（2026-10-20，已完成）

- 0.2.4 之后所有修复/功能收口：窗口比例阈值、设置栏、三级颜色自适应、GitHub 教程/反馈预留。
- LICENSE / CHANGELOG / 0.2.5 版本号 / 设置页 UI e2e 入库。
- 结论：代码与归档就绪，**只差 GitHub 仓库和链接**。

### 0.3 公开可用（2026-10-20 起）

| 事项 | 状态 | 验收 |
|---|---|---|
| 版本号 0.3.0 + CHANGELOG / README / package 元信息 / .gitignore / 文件权限 | ✅ 已完成（元数据待 GitHub 账号） | `npm pack` 元数据完整 |
| 合并旧摘要 e2e（等价场景） | ✅ 已完成（`test/e2e/real-compact.mjs`，`maxSummaries=1` 触发合并分支；6+ 摘要场景同分支等价，不另造） | 合并模式真机跑通 |
| 设置 UX：恢复默认二次确认、未保存提示 | ✅ 已完成（A4） | 真机可用 |
| 设置 UX：一键复制诊断信息 | ⏳ 未做（0.4） | 真机可用 |
| GitHub 仓库、TUTORIAL、Issues 模板、`links` 配置 | ⏳ 待 GitHub 账号/仓库名拍板 | 设置页顶部两个入口变成真实链接 |
| package 元数据 `repository` / `homepage` / `bugs` | ⏳ 待 GitHub 账号 | 字段完整 |
| 真实长会话 soak（至少 3 条真实任务，含压缩→交接→继续） | ⏳ 发布后跑 | 无进度丢失、无报错 |
| 与其他上下文插件共存测试（dsh-auto-handoff / hypercompact 等） | ⏳ 发布后跑 | 不双重压缩、不抢锁、不冲突 |
| 陌生人安装路径验证（npm / git 安装 + 重启） | ⏳ 发布后跑 | 按 README 能装、能看见设置 |

### 0.4 接力质量（2–4 周）

**这是我们的差异化，不碰压缩算法。**

**0.4.0 已发布（2026-10-25）**

- ✅ **P0-2 诊断包最小版**：本机生成、白名单 + 脱敏的诊断信息（设置页「生成并预览 / 复制 / 打开问题报告页」+ 只读 `GET /api/compact-relay-diagnostics`），并接入压缩/交接/锁定计数与耗时（commit `41699c8`；`npm test` exit 0，含 T1–T9 与真机 e2e 断言）。
- 🚧 **P0-1 判断机制加强**（代码已落地，待真实任务验收）：cue 文案 v2（4 类完成信号 + 被拒无副作用）、注入门控（10%–40%、距上次注入 ≥3 轮、按会话不落盘）、工具描述 v2（用户/模型都可调用、被拒不需要致歉、典型调用时机）、cue/mark 计量（`cueInjected` / `markCalls` / `markAccepted` / `markRejected` 直接进诊断包 counters）。验收口径不变（标准 B）：3 次真实长任务里 ≥2 次模型自发调用 `mark_compress_point`。

**0.4.2 交接线保命补丁（已实现、待 Lead 验收；发布须用户点头）**

> 范围定稿：`dcr-0.4.2-范围定稿-2026-10-25.md`｜实施规划：`docs/0.4.2-implementation-plan.md`

- ✅ **P0-1 交接线硬规矩**：硬上限 = 实际触发线 −5pp（整数百分位；deepseek-flash 1M 下 62%），共享纯函数 `core/handoff-guard.js`；违规只告警不静默改（指示灯悬停卡 + 环上交接刻度警示、`/handoff` 菜单、设置页三处）；设置页「按实际线重算」一键 + 二次确认，目标 ≤ 压缩线时拒绝并提示先降压缩线。
- ✅ **P0-2 服务端同口径**：`save()` 接受可选 `nativeRatio`，按实际线 −5pp 校验；未带退回配置阈值 −1pp 防呆（兼容 0.4.1 客户端）；超限 400 + `field` + 目标值，不落盘。
- ✅ **P1 换模型跟随**：状态刷新即重判；观察路由变化后首次违规弹一次 toast；算不出实际线不告警、不阻断。
- ✅ **P2 文档三线**：README / README.en / TUTORIAL 写清 40% / 60% / 67.8%，删掉「原生线 −1%」旧文案；CHANGELOG 0.4.2 段同步。
- ⏳ 待真机点验：设置页 max=62 与提示、环上警示、菜单 ⚠、换模型 toast、截图存档（本仓库自动化无 Chrome/CDP）。
- 明确不做（0.4.2 边界）：历史前缀 / 接力条（0.5.0）、自动触发（1.0）、改宿主触发逻辑、环上 A/B/C 画法。**自动归档旧会话已从 1.0 挪入 0.5.0**（见 §三 0.5.0 第 4 条）。

1. ✅ **交接单六段 → 九段**（0.3 已提前交付）：总体目标 / 约束 / 已完成 / 当前进度 / 改过的文件 / 关键决策 / 已知问题 / 未完成 / 下一步。
   - 文件改动、关键决策由程序收集（`core/handoff-facts.js`），模型只写 7 段、编不了。
2. ✅ **交接就绪检查**（0.3 已提前交付）：九段齐全/占位阻断，路径核对只警告；预览卡里先看再确认。
3. ✅ **压缩前后 diff 第一步（只读）**（0.3 已提前交付）：压了哪些条、摘要预览、省了多少容量；完整前后 diff 留在 0.4。
4. **接力链元数据**（0.3 已提前交付记录）：parent/child、第几次交接；时间线视图留 0.4。
5. **Memory 导出 v1（单向）**：交接单自动/手动写进 Memory 项目页。

验收：真实长任务交接后新会话**无需补充说明**即可继续；交接单一次通过率 ≥90%。

### 0.5.0 无痕交接（命名反转 + 接力条 + 自动归档/恢复已实现；父→子跳转/里程碑面板待实现）

> 范围口径：`default-workspace/dcr-版本路线图-2026-10-26.md` + `dcr-无痕handoff-运行目标与地基层-2026-10-25.md`。0.5.0 是用户可见的第一次大更新；**地基本身不单独发版**，随 0.5.0 一起发。

**用户能看到的变化（0.5.0 范围）：**

1. **命名反转**：交接后旧会话改名「历史 N：<原名>」，新会话继承原名；旧链（交接第 N 次）一个字符不动；列表读起来是一条对话。
2. **接力条**：新会话输入框上方一行「已接力自 历史 1 ▾」，下拉含查看交接单 / 回到原会话 / 恢复旧会话 / 路线图占位；落位 `conversation.input.dock`（输入框单行时间线；早期审查记录的 `conversation.composer.dock` 同属输入框区域，宿主两个槽都在）。
3. **双向跳转**：接力条回父会话（已实现，已归档时先自动恢复）；父会话侧回子会话（待实现，需要父会话接力记录/入口）。
4. **交接后自动归档旧会话**：交接成功（子会话已建、旧会话已改名、record 已落盘）即归档旧会话；交接完成提示 + 接力条「恢复旧会话」两处告知，一键恢复（正式 unarchive API），恢复后回原位；旧会话仍有 turn/subagent/job/schedule 时**不自动停止任务**，有限等待后保留可见并提示；失败不阻断交接。

**命名反转（第一个用户可见功能，已实现、未提交）：**

- 新链：旧会话「历史 N：<原名>」，新会话继承干净原名；第 2 次为「历史 2：X / 历史 1：X / X」。
- 旧链：交接第 N 次 / 0.3 旧 record / 旧堆叠前缀继续旧命名，旧会话标题一个字符不改（链级 cutover）。
- 数据面：父/子 relay record 都写 `scheme` + `titleSeq`，新链父记录带 `historyTitle`；链号只从 record 续。
- 80 字节：前缀先计入、超长只缩 base；`renameHistoryOf` 幂等 + flush，失败只 warn。
- 测试：`test/handoff-naming.mjs`（7 组）+ F5 期望更新；接力条 `test/relay-bar.mjs`；自动归档/恢复 `test/archive.mjs`。`npm test` **257 PASS / 0 FAIL**。

**地基进度（数据面 / 纯函数 / 测试）：**

| # | 内容 | 状态 |
|---|---|---|
| F1 | 历史前缀纯函数：`HISTORY_PREFIX` / `historyTitleOf` / `splitHandoffTitle` 返回 `scheme`（`handoff-n` / `history-n` / `legacy`） | ✅ 已提交 `5397863` |
| F2 | relay record 白名单放行 `scheme` / `titleSeq` / `historyTitle`（旧记录读成 null；父会话记录写出形状不变） | ✅ 已提交 `5397863` |
| F3 | 建子会话时往**子会话**写 relay record（ordinal/baseTitle/scheme/titleSeq）——不做这步第 2 次交接序号会重复 | ✅ 已提交 `b4878b8` |
| F4 | `readState.relay` 扩成只读 `chain`（ordinal/baseTitle/parentId/childId/scheme/path），旧字段原样保留 | ✅ 已提交 `cc6f86d` |
| F5 | 链不变量测试 `test/relay-chain.mjs`（三跳 1→2→3、双写形状、scheme 不混、旧链逐字节、chain 投影），并入 `npm test` | ✅ 已完成（未提交） |
| F6 | ROADMAP / CHANGELOG / ARCHITECTURE 登记 0.5.0 地基 | ✅ 本次（未提交） |
| 命名反转 | 旧会话「历史 N」/新会话继承原名/旧链 cutover（`dsh/sessions.js` + `actions/handoff.js`） | ✅ 已实现（未提交） |
| 自动归档/恢复 | 交接成功后 `workspaceRegistry.archiveSession`（不 stopActivity）+ `recover` 动作 + 接力条「恢复旧会话」+ `readState.parentArchived` | ✅ 已实现（未提交） |

**宿主侧没有接缝（0.5.0 不追）：**

- **消息流拼接不可行**：`conversation.chat.flow` 是 `single` 槽且已被宿主 ChatFlow 注册，`conversation.chat.node` 只按宿主 entryKey 渲染 —— 旧消息拼不进新会话，只能「接力条 + 跳旧会话」。
- **通栏接力条不可行**：宿主 header 没有通栏 band，接力条落在输入框内的 `conversation.input.dock`（单行；早期审查记录的 `conversation.composer.dock` 同区域）。

**验收：** 交接 2 次后列表为 `历史 2：X / 历史 1：X / X`；接力条「查看交接单 / 回到原会话 / 恢复旧会话 / 路线图占位」可用；旧会话自动归档且能从接力条恢复；旧链标题不变；`npm test` 全绿 + 真机截图。

### 0.5 项目记忆（1–2 月）

> 0.5.0 实际范围是上面的「无痕交接」；本节为早期规划，不随 0.5.0 交付。

1. **项目上下文包**：目标 / 关键决策 / 待办 / 改过的文件，新会话自动带上。
2. **接力链视图**：父子会话树/时间线，一键跳转。
3. **Memory 双向**：读取项目页作为上下文，写回交接单（先跑稳单向再开）。
4. **跨会话任务/决策追踪**：哪些做完了、哪些还欠着、为什么这么定。

验收：多天项目不用回忆"上次做到哪"，直接继续。

### 评审建议的落位（2026-10-20 小潇拍板）

> 来源：2026-10-20 首条外部评审（Gemini）+ 小潇讨论。拍板结论：先收尾发布闭环（市场 PR / 陌生人安装验证 / soak），再进 0.4 首批。

**0.4 首批（已确认，四项）**
1. **压缩预览里的「建议锁定」提示**：预览时高亮「包含关键决策 / 报错堆栈 / 明确要求别改」的消息，提示用户先 `/pin` 再压；只提示，不自动锁（不替用户做主）。
2. **设置页一行「累计压缩 X 次 / 腾出 Y tokens」**：不做独立成本面板（见 §四），只做一行正反馈数字。
3. **交接预览可编辑**：只允许改「下一步计划 / 约束条件」两段；程序生成的段落不可改（防编造），改完再确认切换。
4. **接力链元数据补全**：A5 记录已存在，补全 parent/child、第几次、时间线字段，为 0.5 的接力链视图铺路（视图本身仍留 0.5）。

**低优先（0.4 观察，有数据再动）**
- **阶段边界「只读提示」**：识别「子任务收尾」的对话边界，在缺口旁只读标注「可能处于阶段收尾」，暂不改变压缩范围；误判风险大，先只提示。
- **场景化交接模板**：等 3+ 真实用户提同一诉求再做。
- **简化模式（降低认知负荷）**：可选开关，暂不排期。

**研究项（先探边界，不做承诺）**
- **DSH 公开消息钩子**：确认宿主是否提供官方钩子可供桥接链路做文本级提醒；没有就维持 §四「不接管 headless/桥接链路」。dcr 目前只用 `ctx.on('session/event')` 观察事件，不修改模型回复。

**维持观察**
- **i18n（英文界面）**：README 已有英文版；界面英文等 0.5 再评估。

### 1.0 上下文生命周期自动化（远期）

- 自动化等级：建议 → 一键确认 → 在 Step 边界自动执行（可配置）。
- 换模型建议（窗口/成本更优）。
- 多 agent / subagent 接力。
- 零丢失、可观测、可恢复。

验收：用户不再主动想"上下文会不会满"。

## 四、明确切掉 / 不做
- **不接管 headless / 桥接链路**：指示灯与 `/bc`、`/handoff` 依附 DSH 输入框和命令系统；headless 会话、QQ / 微信桥接里不加载（那里发 `/bc` 会被当成普通消息）。只保证插件加载不报错、不额外烧模型调用。

| 方向 | 原因 |
|---|---|
| 自研压缩算法、工具输出/图片压缩 | hypercompact、dsh-compressor、context-guard 已覆盖，重造性价比低 |
| 上下文仪表盘、成本面板 | dsh-context、context-vista 已覆盖 |
| 自动压缩/自动交接（自研） | dsh-auto-handoff、@ohmejj/dsh-auto-compact、faster-compress 已覆盖；先兼容，1.0 再考虑 |
| 压缩"回滚" | 会话日志 append-only，真正回滚不现实；只做 diff/预览 |
| 多级摘要/摘要索引 | DSH 单 checkpoint 模型限制大，用户感知弱，暂缓 |
| 本地小模型 `/trim` 调优 | dsh-command-context-trim 已覆盖 |
| 多 agent 交接 | DSH 自身在演进，等 1.0 |
| i18n、自定义导航图标 | 面向外部用户后再做 |

## 五、竞品快照（2026-10-19/20 npm/仓库实测）

| 插件 | 版本/更新 | 做什么 | 对我们的含义 |
|---|---|---|---|
| [dsh-context](https://www.npmjs.com/package/dsh-context) | 0.73.3 / 10-19 | 上下文生命周期仪表盘、Fleet、`/context` | 仪表盘不做 |
| [dsh-context-rollover](https://www.npmjs.com/package/dsh-context-rollover) | 0.2.2 / 09-16 | 模型主动换窗、notes、无摘要 | 另一条路线，可借鉴 notes |
| [dsh-hypercompact](https://www.npmjs.com/package/dsh-hypercompact) | 0.2.4 / 10-05 | 零 LLM 字节预算压缩 + recall | 压缩算法不做 |
| [dsh-auto-handoff](https://www.npmjs.com/package/dsh-auto-handoff) | 0.2.0 / 10-18 | 九段交接单 + 阈值自动迁移 | 交接单模板要对齐；自动触发不自研 |
| [@ohmejj/dsh-auto-compact](https://www.npmjs.com/package/@ohmejj/dsh-auto-compact) | 0.1.0 / 10-07 | 设置页配置原生自动压缩 | 自动压缩已有 |
| [dsh-faster-compress](https://www.npmjs.com/package/dsh-faster-compress) | 0.2.3 / 10-19 | 后台预压缩 + 压缩历史 | 后台压缩已有；我们只做 diff |
| [dsh-command-context-trim](https://www.npmjs.com/package/dsh-command-context-trim) | 0.6.6 / 10-03 | 无模型 `/trim`、小窗口切换 | 切掉 |
| [context-vista](https://www.npmjs.com/package/context-vista) | 0.1.0 / 08-14 | 环图、成本估算 | 仪表盘不做 |
| [dsh-compressor](https://www.npmjs.com/package/dsh-compressor) | 0.1.0 / 08-15 | 工具结果压缩 + retrieve | 压缩不做 |
| dsh-context-guard（原 https://github.com/wood20100715-collab/dsh-context-guard 已失效，2026-10-25 核查 404） | 仓库 | 内容类型压缩 + CCR + 高保真摘要 | 智能保留不自研 |
| [dsh-session-handoff](https://github.com/snow-The/dsh-session-handoff) | GitHub | 结构化交接文档 + 官方 compaction API | 交接同赛道；我们做"检查 + 链 + 记忆" |

## 六、已定决策

1. **自动化等级**：默认人工确认；自动压缩/交接只在 1.0 作为 opt-in，不做无确认改历史。
2. **Memory 联动**：先单向导出（0.4），跑稳再双向（0.5）。
3. **发布节奏**：0.3 公开后按功能批次升版本；每批必须真机验证 + 归档。

## 七、当前状态 / 下一步

- ✅ 0.3.1 发布包已就绪：版本号 / CHANGELOG / README 安装段 / .gitignore / npm `files` 收窄 / 文件权限归一；测试基线 smoke 50、handoff 35、plugin-load 13、contract 17、compact-log PASS。
- ✅ 0.3.1 已发布：npm `dsh-compact-relay@0.3.1` + GitHub tag/Release；0.3.2 补设置页链接与联系方式；0.3.3 完成 Windows 适配（Win11 + Node 24.22 全测试通过）。
- ✅ 0.3.4 判断机制修复（BUG-010：`mark_compress_point` + systemPrompt 可压缩区间提示 + 状态缓存；427 会话数据佐证旧工具 0 调用）+ BUG-005/BUG-006 小 bug；npm latest 待本次发布。
- ✅ 0.3.5 补丁：修复「无活 agent 时压缩按钮误禁 + 文案误导」（state 增加 `compactRangeReason='no_agent'`；客户端提示「会话未激活：发一条消息唤醒 agent 后可压 N 条」）。
- ✅ 0.4.0 已发布（2026-10-25，npm latest + GitHub tag/Release）：P0-1 判断机制加强（cue 文案 v2 + 10%–40% 注入门控 + cue/mark 计量）、P0-2 诊断包（脱敏诊断信息预览/复制/问题报告页，零网络）、P1-1 压缩预览建议锁定、P1-2 pin 保留契约、P1-3 轻账本累计、P2-1 交接预览两段可编辑、P2-2 接力链元数据、P2-3 原生自动压缩真实触发线（按 route 算）。真机验证全绿（Mac 0.3.6→0.4.0）；Mac/Win 均已装 0.4.0 并核对版本。
- ✅ 0.3.6 已发布（BUG-012）：原生压缩线解析只认 `config:` 直接子键（按缩进判断），修复 `modelPolicies` 嵌套 `thresholdRatio` 被误报为全局线（Windows 真实会话误显示 50%）；真实触发线按模型 route 计算留 0.4。
- ✅ 0.4.0 判断机制与诊断包（2026-10-24 完成）：P0-2 诊断包最小版已交付（commit `41699c8`，`npm test` 全绿 + 隔离 e2e 真机验证）；P0-1 判断机制加强（cue 文案 v2 + 注入门控 10%–40%/≥3 轮 + 工具描述 v2 + cue/mark 计量）代码已落地、测试全绿，标准 B 已达标（3/3）并随 0.4.0 发布。
- ✅ 真实压缩 e2e：`test/e2e/real-compact.mjs`（真实模型 + 真实压缩事务 + `maxSummaries=1` 合并旧摘要分支）6 项断言通过。
- ✅ 0.5.0 功能已落地（**未发布**）：F1–F6 地基 + 命名反转 + 接力条 + 交接后自动归档/恢复入口；`test/relay-chain.mjs`、`test/relay-bar.mjs`、`test/archive.mjs` 并入 `npm test`（当前 **257 PASS / 0 FAIL**）。剩余：父→子跳转入口、里程碑面板。
- ✅ P3-01～14（13 修/1 确认无需修）+ BUG-004 + P2-T1 已收口。
- ⏳ 市场收录 PR：仓库满 1 天（2026-10-21 19:09 后）提，yml 与说明已备。
- ⏳ 陌生人安装路径验证（npm 安装 → 重启 → 设置/指示灯）—— 发布后第一次外部用户安装时一并确认。
- ⏳ 真实长会话 soak（至少 3 条真实任务，含压缩→交接→继续）—— 建议下一批功能开发时顺带跑（dogfooding）。
- ⏳ 与其他上下文插件共存测试（dsh-auto-handoff / hypercompact 等）—— 等市场收录后有用户反馈再做。
- ⏳ 真机复核残留：交接成功文案（0.3.1 起文案已改，待一次真交接确认）。