dsh-compact-relay 0.0.0-stage → 0.3.1

package/CHANGELOG.md

@@ -0,0 +1,93 @@
+# Changelog
+
+## Unreleased
+
+（暂无新改动）
+
+## 0.3.1 — 2026-10-20（首个公开版：安全修复 + 架构调整 + M4/M5 体验 + 测试台 + UX 修复）
+
+> 0.3.1 是首个公开版本（0.3.0 只用于内部发布准备、从未公开发布），汇总 0.2.x 以来的全部实现与真机验证。分四块：**安全与正确性修复**（M1/M2 安全修复、P3-01～14、BUG-001/004/007/008、P2-3/4）、**功能**（A1 九段交接单/预览卡、A4 配置 schema、A5 接力链、A6 压缩历史、A8 client 可维护性、A9 边界回正）、**体验**（M4 浮层材质/焦点/取消、菜单瘦身、设置页两行说明与三级颜色）、**测试与工程**（A7 mock/契约测试台、P2-T3/T4、e2e 真实压缩 + P2-T1 旧摘要合并、A10 状态帧成本基线）。
+
+- **P3-01～14 清理（14 条：13 修 / 1 确认无需修）**：摘要失败文案带具体原因（不再「详见日志」却没日志）、`maxSummaries` 改正整数（0 会同时触发恒交接+恒合并，已拒绝）、`pin` 的 toggle 与写入统一按「当前 surface 仍有效」口径（快照过期时不再把「锁定」执行成「解锁」）、`gitInfo` 的 `.git/HEAD` ref 只认 `refs/` 白名单（堵住 `../` 读任意文件）、state 帧加单调 `revision`（浏览器丢弃晚到的旧帧）、交接成功文案不再谎称「旧会话原样保留」、`changed` 错误文案带「请重新预览」。P3-08（交接注入消息 `form` 字段）确认运行时合法（v4 只要求 producer-owned `kind`），不改。
+- **BUG-004 交接前置压缩静默跳过**：摘要模型返回工具调用时也带「只输出正文」提示重试一次；仍失败时交接完成提示写清具体原因并建议「可先手动 /bc 再交接」（以前只有「日志有记录」）。
+- **0.3.1 UX 修复（P0/P1，来自用户视角审查）**：
+  - **锁定消息可视化（权重最高）**：锁定的消息在指示灯环上按「消息在历史里的相对位置」画**锁定块**（默认品红、外侧比环粗；多条锁定显示多个块，支持设置「锁定颜色」）。`state` 的 `pins` 新增 `marks: [{seq, ratio}]`；菜单顺序改为「压缩 → **锁定** → 交接 → 标记」，首次引导文案点名「锁定重要消息」并解释「重要的结论/路径先锁定，压缩时才不会被压掉」。
+  - **标记进度已删除（作者拍板）**：用户手动入口（`/stage` 命令、菜单项、「保留阶段标记数」设置项、HTTP action）全部移除；判断改由两条自动路径完成——**模型判断**「这里适合压缩」（`mark_stage` 工具：最小线 < 当前 < 压缩线时记录断点）与**阈值**（到压缩线自动出断点）。
+  - **环按「压缩判断」分段 + 断点**：正常区（0→断点1）未走满灰、走满蓝；断点1→交接线琥珀（压缩区）；交接线→当前红（交接区）；断点=小缺口（模型判断位置或压缩线），交接线断点固定；压缩后环变短、断点自然消失；断点位置随阈值设置实时变化。视觉规则抽成纯函数 `core/ring.js`（可单测）。
+  - **最小压缩线**：新增 `thresholds.minRatio`（默认 5%，随「保留近期原文」和窗口自动抬高——小窗口下 5% 压不出净收益），低于它模型不判断压缩、环上不出断点；后端校验必须小于压缩线。
+  - **DSH 原生自动压缩线**：读 profile 配置（`compaction-basic.thresholdRatio`，默认 80%）随状态下发；环上 80% 处画粗刻度，越过交接线后 80%→100% 亮半透明警告区、越过 80% 后已走段实色提醒；首次引导会告诉你当前原生线；设置页可一键关闭/恢复原生自动压缩（写 profile 配置前备份、需重启生效、带确认环节），原生开启时交接线上限自动压到「原生阈值 −1%」并由后端强校验。
+  - **设置页教学卡片**：新增「指示灯怎么看」示意（5 个示例环：未满灰/走满蓝/压缩区琥珀/交接区红/原生线），随用户配色与阈值实时变。
+  - **转交后收尾（2026-10-20 晚，BUG-009 / UI-003 / UI-002）**：
+    - **BUG-009 教学卡片图例修正**：5 个示例环按各自语义单独构造参数（以前共用同一个假断点，5 个环的断点全挤在 ≈17%、颜色与说明不符）；「走满正常区」在压缩线上补断点示意，原生线示例画 80% 原生刻度。
+    - **UI-003 原生自动压缩开关**：根因是设置页请求缺 `sessionId`，被动作接口 400 拒绝（所以永远写不进 profile、也没有可见反馈）。`native-auto` 改成不要求会话（它是 profile 级开关）；控件改成 `role=switch` 的开关 + 状态常显 + 结果就地显示在开关旁 + 确认块自动滚入视野。
+    - **UI-002 设置页信息架构**：按权重分区块（压缩提示 → 压缩行为 → DSH 原生自动压缩 → 颜色与外观 → 帮助 → 关于与危险操作）；教学卡片与教程/反馈移入「帮助」；颜色行按环的阅读顺序重排（默认→填满→调整→上限→锁定，编号 ①–⑤）；「关于」区补版本与设置文件路径，恢复默认归入「危险操作」。
+    - **原生线视觉（作者 2026-10-20 反馈）**：原生自动压缩线标记从「同色短弧」改成**紫色径向刻度 + 底色描边**（不再和红色分段糊在一起，任何配色下都看得清）；越过原生线后**整环红色闪烁**（1s 呼吸；`prefers-reduced-motion` 下改为常亮红色）；教学卡片同步：「还没到最小线」的灰弧加长到 ≈5% 可见，原生示例演示整环闪烁。
+
+    - **设置页层级（作者 2026-10-20 反馈：首行缩进 / 区分菜单等级）**：每个区块的内容统一缩进 16px + 左侧 1px 层级引导线，区块标题保持一级不缩进，条目与标题的主次一眼可分。
+
+    - **设置页标题说明（作者 2026-10-20 反馈）**：「压缩接力」标题下加一句话把「功能 + 边界」说清——看容量、到线提醒并帮你压缩旧会话 / 交接新会话、锁定重要消息；只动本插件的压缩与交接历史，不改模型回复，也不接管 DSH 原生自动压缩（只在本页开关、改了要重启）。
+    - **初次引导可重播**：「帮助」区新增「再看一次初次引导」按钮，通过 window 事件触发（组件解耦）；手动重播给更长时长（光晕 9s / 提示 20s），首次仍只在第一次打开会话时自动弹一次（localStorage 记住）。
+    - **初次引导回归**：隔离 DSH 全新 Chrome profile 实测——首次自动弹（呼吸光晕 4.8s + 提示 15s）→ 光晕停、提示还在 → 刷新不再弹 → 设置页按钮重播生效；按步骤截图存档。
+    - **首次使用引导**：第一次打开会话时指示灯做几次呼吸光晕 + 一条提示（「点它能压缩旧会话 / 交接新会话 / 锁定重要消息」），localStorage 只出现一次；空闲态中心点也从「完全透明」改成可见的灰点（以前新用户根本看不出这里有个按钮）。
+  - **小范围压缩预警**：预览阶段就判定（<800 tokens）并提示「这段偏小，压了可能反而更大」，确认按钮直接禁用，不再让用户白点一次、白等一次模型调用；`/bc` 预览文案同步。
+  - **失败提示带下一步**：「摘要比被替换的内容还大」改为「先继续聊几轮，或把『保留近期原文』调小一点，再来压缩」。
+  - **短会话交接提醒**：就绪检查新增「会话内容很少（少于 8 条消息）」警告；交接提示词补「不要把系统指令/输出格式要求当成会话内容」。
+  - **交接预览可读性**：`## 标题` 渲染成加粗行（不再直接显示 markdown 源码），就绪警告在卡片里可见。
+  - **菜单**：容量数字带单位（`约 1.4K tokens`）；压缩/交接/标记项补命令名（`/bc`、`/handoff`、`/stage`）。
+- **e2e 真实压缩 + P2-T1 旧摘要合并**：新增 `test/e2e/real-compact.mjs`（`npm run test:e2e:compact`）——隔离 DSH 里用真实模型调用攒历史（GUI 发消息），第一次真实压缩把 3 条旧会话压成 1 条摘要（`summaries` 0→1、pressure 下降），第二次在 `maxSummaries=1` 下走「合并旧摘要」分支（提示「同时合并了旧摘要」，`summaries` 记 +1），6 项断言全过、约 20s。踩坑记录：`pressure` 在用户消息入 surface 时就涨，不能当「模型回复结束」判据（此时压缩会 409 正在回复中），要用 GUI 页面文本稳定（`waitReplyDone`）。
+- 测试：smoke **53/53**、handoff **35/35**、plugin-load **13/13**、contract **17/17**、compact-log PASS；新增回归覆盖环分段/断点/最小线/压缩判断记录/原生配置读写、P3-01/02/03/07/12/14 与 BUG-004。
+- **A8 client 可维护性**：单文件契约不变，但源码拆成 `lib/client/*.js` 十个有序片段，新增零依赖 `scripts/build-client.mjs` 拼成 `lib/client.js`；`npm test` 第一步 `build-client --check`（改了片段没重建直接红）。颜色纯数学上移 `core/colors.js`（首次可单测：HSL 派生 + WCAG 3:1、归一化、旧扁平结构兼容），host 在 state（`colors.palette`）/settings（`palettes`）一次性下发浅/深两套派生结果，浏览器半只按界面明暗挑一套，设置页未保存编辑仍走同一份纯函数（构建时内联，单一来源）。真机验证：client bundle 热加载已含新代码、菜单/指示灯正常、零 console 错误。`scripts/` 与 `lib/client/` 不进 npm 发布包（发布只带构建产物）。
+- **A10 状态帧成本基线（只测量不优化）**：用真实大会话日志（某 6000+ 事件 / 400+ surface 节点 / 35 万 token 压力的大会话）+ 从 app.asar 解包的真实 DSH tokenMeter/compaction 代码重放：稳态 measure 0.45ms（p95 0.49）、countSummaries 0.12ms、selectCompactableRange 0.12ms、整帧 readState 0.64ms（p95 0.94）；首次全量 fold 21.7ms（一次性）。真机端点 `/api/compact-relay-state?sessionId=<大会话>` 端到端 p50≈1.8ms、max 2.5ms。离「p95>8ms 或节点>1500」触发线很远 → 不做 detail 拆分/WeakMap 缓存，只留基线备 0.4 用。
+- **A6 压缩历史**：新增 `lib/dsh/compaction-log.js`（只读配对 summary/end/replace，输出最近 N 次压缩的范围、摘要预览 ≤200 字、容量、已提交/失败/未闭合）与 `GET /api/compact-relay-diff`；菜单「查看上次压缩」打开只读面板。已提交口径与 `countSummaries` 一致；兼容真实 DSH 的块数组摘要（`[{type:'text',text}]` 归一为预览）。
+- **菜单瘦身（B 方案）**：压缩/交接保留两行说明，锁定/查看交接单/查看上次压缩改为单行 + 右侧状态（未标记/未锁定/›），菜单高度 342→288px、6 项不再滚动；说明原文保留在悬停 title。
+- **A1 九段交接单**：交接单从六段升级为九段（总体目标/约束/已完成/当前进度/改过的文件/关键决策/已知问题/未完成/下一步）；标题唯一来源 `core/handoff-spec.js`，提示词/校验/渲染/客户端文案全部由规格表派生。新增 `core/handoff-facts.js`（程序收集「当前进度」「改过的文件」）与 `core/readiness.js`（就绪检查：缺段/占位阻断，路径核对只警告）；`dsh/session-files.js` 从会话日志的写文件工具调用收集改过的路径（不跑 git status）。模型只写 7 段，程序段不可编造。新增 `handoff-preview` action 与菜单「交接预览卡」：九段草稿 + 就绪清单，确认后才压缩/写盘/建会话。浮层定位改为按估计高度判断翻转并夹在视口内（矮视口不再顶出屏幕）；就绪检查的路径告警会去掉尾部反引号/标点。
+- **A7 测试台**：新增 `test/harness/{host,session,llm,dsh-stubs}.mjs` 统一 mock；smoke/handoff/plugin-load 的重复手搓 mock 迁入（当时：smoke 1108→1041、handoff 1044→783、plugin-load 648→515 行）；新增 `test/contract.mjs`（17 条契约：fake replace/故障注入语义 + 用真实替换事务跑成功/失败路径 + 冻结 engine 9 个符号）。（最终计数见本节开头基线。）
+- **P2-3 幽灵摘要**：`countSummaries` 改为「summary + 无 error end + 覆盖它的 replace」配对计数，失败事务不再算已压缩。
+- **P2-4 模型路由**：`routeOf(ctx, session, agent)` 优先 DSH `modelSelection` 投影（pending→lastUsed），切模型后摘要/交接/子会话不再沿用旧 requestHeader。
+- **M4 client 修复**：交接卡区分 opening/opened/failed（刷新后不再误报成功、失败可重试打开）；toast 单 timer（新提示清旧 timer，4/5/6/8s）；交接单详情请求带序号 + AbortController（防乱序/关闭后重新撑开）；浮层定位滚动/缩放重算复核通过。
+- **BUG-001 浮层底色**：悬停卡/菜单/确认卡/交接单/toast 改用 DSH 官方弹层材质 token（`--dsw-menu-surface-fill` + `--dsw-menu-backdrop-filter`，实测与官方账号菜单完全一致：浅 `rgba(248,249,250,.58)`、深 `rgba(67,69,74,.45)`，`blur(40px) saturate(150%)`），文字/边框用 `label-*`/`border-l3`；theme observer 监听 `data-ds-theme-source` / `data-ds-dark-theme`。
+- **P2-A1～A3**：小字对比度交给 DSH 次级文字 token；菜单/确认卡/交接单加 role+aria-label、打开进焦点、Esc 关闭后焦点回指示灯；悬停卡允许换行、窄窗收边（320px）。
+- **BUG-007/008 命名**：入口改「压缩预估」、确认卡「确认压缩」+「只估算范围和容量，摘要确认后才生成」；`/bc` 输出、命令描述、README/TUTORIAL 统一。
+- **P2-T3/T4**：`npm test` 先 `node --check lib/client.js`；`test/e2e/action.mjs` 按动作判成功（compact 需「压缩完成」、handoff 需 childId+path，`compacted:false` 标 noop）。
+- 测试（当时）：`smoke 42/42`、`handoff 31/31`、`plugin-load 13/13`；隔离 e2e `settings-ui`/`smoke` 均 PASS（最终基线见本节开头）。
+
+- **A4 配置 schema**：新增 `core/config-schema.js` 单表派生默认值/校验/中文文案/设置页白名单/公开视图；用户设置文件「合法 JSON + 非法值」不再让插件整体不激活（回落默认 + 设置页显示 `settingsError`）；设置文件升级为 `{v:1,config}` 信封（旧扁平兼容）；设置页「恢复默认」加二次确认、未保存修改提示。
+- **A5 接力链**：交接成功时在父会话写 `plugin:compact-relay/relay` 结构化记录（parent/child/index/path/planId），下一次交接标题/序号优先读记录，标题解析只做旧数据兜底；`readState` 下发 `relay`；命令卡优先用结构化 `childId`（文本 `#child=` 兜底）。
+- **A9 边界回正**：`dsh/state-hub` 的 `readState` 由装配层注入（dsh 不再反向 import actions）；`adapters/http` 的交接单读取与 `pickAgent` 改走 `actions/handoff-docs` / `actions/state.resolveTarget`；设置拆成 `dsh/settings-file`（读写）+ `actions/settings`（合并/校验/热替换），旧 `settings-store.js` 保留兼容 shim。
+- **P2-6 e2e 隔离**：隔离 home 不再复用真实 `compact-relay.json`/交接目录，写入最小设置（`handoffDir=/tmp/relay-e2e/handoffs`）并清空复制来的交接单；启动时断言 `handoffDir` 在隔离目录下。工作区 cwd 暂保持真实（改 workspace path 会让 GUI 停在「选择工作区」，e2e 拿不到指示灯）；e2e 只建会话 + 调插件 HTTP 动作，不执行写工作区的工具/命令，M5 用工作区副本收紧。
+
+### 安全修复（M1/M2）
+
+- **P0**：`/api/compact-relay-*` 五个端点接上宿主 `connection.requestRejection`，不再绕过宿主 `/api` 的 Host/Origin 校验与浏览器 token 认证（此前无 cookie 的 GET 能读设置/状态/交接单，伪造 Host 也放行）。HTTP 端点现在 `inject` 宿主 `connection` 服务。
+- **P1**：修复 `Origin: null` 的跨站 POST 被当同源（sandbox iframe / no-cors 可绕过 CSRF）；`sameOrigin` 现在先拒 `null`、cross-site 一律拒绝（仅自定义协议白名单）。
+- **P1-2**：占位判定由枚举白名单改为「句式 + 整篇内容量」——「无明确未决问题」「No open questions.」这类自然语言空话不再能绕过；空壳摘要/交接单仍会被拒。
+- **P1-3（架构 A3）**：预览返回 `planId`；确认带 `expected`，重算范围不一致以 `changed` 拒绝并让客户端重开确认卡；`/bc confirm` 从 5 分钟预览缓存取范围。
+- **P1-4（架构 A2）**：新增 `lib/dsh/llm-call.js`——预算预检 + 默认 180s 超时（可配置 `timeouts.llmMs`）+ 网络/5xx/限流重试一次 + 可取消；`/handoff` 登记 inflight，UI 交接中也能取消；交接先做目录可写 preflight，建会话失败会清掉刚写的交接单。
+- **P2-1/P2-2/P2-5**：取消不再谎报「历史没改」（commit/persistence 原样上报）；`reasoningEffort` 按模型目录能力决定，不再硬编码 `off`。
+- 测试（当时）：`smoke 37/37`（新增占位句/内容量回归）、`handoff 30/30`（新增 A2/A3、交接取消、preflight、非推理模型）、`plugin-load 13/13`。
+
+## 0.2.5 — 2026-10-20
+
+发布准备与产品化收尾（功能与 0.2.4 之后累积的改动一致）：
+
+- 设置栏：DSH「设置 → 压缩接力」，可调压缩线/交接线（窗口比例）、摘要份数上限、保留近期原文、交接单目录、颜色模式与颜色。
+- 三级颜色：默认/调整/上限 + 可选阶段色；只选基准色，浅色/深色两套自动派生（HSL 明度钳制 + WCAG 对比度 ≥3:1），保存即时生效。
+- 阈值改为窗口比例（`compactRatio=0.4` / `handoffRatio=0.6`），换小窗口模型自动缩放；兼容旧绝对阈值写法。
+- 设置页每个设置两行小字：「作用」+「调整后」；顶部预留 GitHub 教程/反馈入口，底部「关于」含简介、版本、致谢。
+- 新增 `TUTORIAL.md`（3 分钟教程草稿）；`links.tutorial` / `links.feedback` 填 URL 后设置页自动变可点链接。
+- 修复：空壳摘要覆盖历史、长会话交接单回放截断、合并模式钉住失效、确认卡容量字段错位等（详见仓库提交记录与 BUG 台账）。
+- 工程：补 `LICENSE`（MIT）、`CHANGELOG.md`、`ROADMAP.md`、设置页 UI e2e 脚本 `test/e2e/settings-ui.mjs`、npm scripts。
+
+## 0.2.4 — 2026-10-19
+
+- 交接会话标题改为「交接第 N 次：<原题>」，不再叠前缀。
+- 注释整理、界面文案统一白话。
+
+## 0.2.3 — 2026-10-18
+
+- 修确认卡「undefined 条 / — 容量」字段错位。
+
+## 0.2.0–0.2.2
+
+- M6：压缩预览/确认/取消、交接单入口 + 现场快照、手动阶段标记、锁定重要消息。
+- 界面命名统一：压缩旧会话 / 交接新会话 / 标记进度 / 锁定重要消息 / 查看交接单。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-compact-relay contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,148 @@
+<div align="center">
+
+# dsh-compact-relay
+
+**Context window indicator and session management plugin for the DeepSeek Harness composer.**
+
+[简体中文](README.md) · English
+
+[![DSH](https://img.shields.io/badge/DSH-0.2.x-4d6bfe)](https://www.deepseek.com/harness/)
+[![license](https://img.shields.io/badge/license-MIT-yellow)](LICENSE)
+[![version](https://img.shields.io/badge/version-0.3.1-blue)](CHANGELOG.md)
+
+</div>
+
+![The indicator ring with its hover readout](assets/hero-ring.jpg)
+
+## Overview
+
+This plugin adds a 28px ring indicator beside the composer. It reports context occupancy and compression-assessment state in real time so that context can be managed before automatic compaction is triggered:
+
+- **Gray**: below the minimum compression threshold; compaction is not required.
+- **Blue**: the normal capacity zone is full; manual compaction is available to free space.
+- **Amber (with notch)**: the suggested compression point has been reached (identified by the notch); click to preview the compression estimate and decide whether to run it.
+- **Red**: the handoff threshold has been reached; generating a nine-section handoff document and switching to a new session is recommended.
+
+The plugin mounts beside the existing composer. Default parameters are tuned for DSH 0.2.x; no change to the existing workflow is required.
+
+## Core capabilities
+
+### 1. Occupancy visualization
+
+The ring is colored in segments according to the compression-assessment logic: the suggested compression point determined by the model or configured threshold, the positions of pinned messages, and the DSH native auto-compaction line (80% by default). When occupancy crosses the native auto-compaction line, the ring flashes red.
+
+Hovering over the ring displays exact values: capacity used, cumulative compaction count, current suggestion, compression point, native auto-compaction line, and the number of pinned messages.
+
+### 2. Preview-then-confirm compaction
+
+Running `/bc` (or using the ring menu) previews the range to be compacted, the message count, and the estimated capacity to be freed. Execution requires explicit confirmation. The operation can be cancelled before confirmation, and no history is modified until it is committed; pinned messages are skipped automatically.
+
+![Compaction preview with confirm and cancel](assets/compact-preview.jpg)
+
+### 3. Structured session handoff
+
+Running `/handoff` generates a handoff document with nine standard sections (overall goal, constraints, completed items, current progress, files involved, key decisions, known issues, open items, next steps), creates a new session in the current workspace, injects the document, and switches to it. The original session is retained intact.
+
+### 4. Message pinning
+
+Running `/pin` marks messages that must be preserved during compaction. Pinned messages appear as magenta blocks on the ring and as locked rows in the menu.
+
+![The indicator ring menu](assets/menu.jpg)
+
+## Ring legend
+
+| Ring element | Meaning |
+| --- | --- |
+| Gray arc | Below the minimum compression threshold; compaction not recommended |
+| Blue arc | The normal capacity zone is full |
+| Amber arc | The compression point has been passed; compaction is suitable |
+| Red arc | The handoff threshold has been passed; switching to a new session is recommended |
+| Ring notch | Suggested compression point (determined by model assessment or the configured threshold) |
+| Violet tick | DSH native auto-compaction line (reads `compaction-basic.thresholdRatio`, 80% by default) |
+| Magenta blocks | Distribution of pinned messages in the history |
+| Full-ring red flash | The native auto-compaction line has been crossed; DSH native auto-compaction is imminent |
+
+![Crossing the native auto-compaction line](assets/native-alert.jpg)
+
+## Installation
+
+**Requirements**: DSH Desktop or `dsh web` 0.2.x (tested on 0.2.1-rc.2), Node.js 22+.
+
+```sh
+dsh plugin --profile desktop add dsh-compact-relay
+```
+
+In the desktop app, the plugin can also be installed from **Plugins → Add plugin** by package name, or directly from GitHub:
+
+```sh
+dsh plugin --profile desktop add github:cfanzx/dsh-compact-relay
+```
+
+Restart DSH after installation. Configuration changes saved inside the plugin take effect immediately and do not require a restart.
+
+## Settings
+
+Configuration is available under **Settings → 压缩接力** (in the account menu on DSH 0.2.1+):
+
+- **Compaction hints**: configure the minimum compression line, compression line, and handoff line to control when warnings are emitted.
+- **Compaction behaviour**: configure the summary retention limit, the recent-token retention count, and the handoff document directory.
+- **DSH native auto-compaction**: read the host's current threshold and enable or disable DSH native auto-compaction (a backup is created before the profile configuration is modified; a restart is required for the change to take effect).
+- **Colors & appearance**: configure five base colors; the system derives adapted shades for the light and dark themes automatically.
+- **Help**: ring legend, usage notes, feedback links, and a "show the onboarding again" button.
+- **About / dangerous operations**: version number, configuration file path, and factory reset.
+
+![Settings](assets/settings.jpg)
+
+Each setting includes a definition and a description of the effect of changing it. The help section contains five dynamic example rings that update in real time with the current colors and thresholds.
+
+![Ring legend teaching card](assets/teaching-card.jpg)
+
+The first time a session is opened, the ring plays a brief highlight animation with a short functional description (triggered automatically once only; it can be replayed from the Settings page).
+
+![First-run onboarding](assets/onboarding.jpg)
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `/bc` | Preview compaction: target range, message count, and estimated capacity to be freed |
+| `/bc confirm` | Execute the previewed compaction |
+| `/handoff` | Generate a nine-section handoff document, then create and switch to a new session |
+| `/pin` / `/unpin` | Pin or unpin a message; pinned messages are skipped during compaction |
+| `/bctest` | Small dry-run test (development debugging only) |
+
+## Scope and limitations
+
+- **Does not replace DSH native compaction**: native compaction remains under DSH host control; this plugin only reads the threshold, displays warnings, and provides a toggle in Settings.
+- **Does not modify prompts or model replies**: history is replaced only when the user explicitly confirms a compaction or runs a handoff.
+- **Summary quality depends on the underlying model**: summaries use a structured nine-section template with format validation and a single retry, but output quality remains limited by the selected model.
+- **Local storage only**: plugin state is stored in `~/.dsh/compact-relay.json` and handoff documents in `~/.dsh/handoffs/`; no external data is synchronized.
+- **UI language limitation**: the current UI is Simplified Chinese only; an English UI is planned with no fixed schedule.
+
+## Version and license
+
+- **Current version**: 0.3.1 (first public release), tested on macOS against DSH 0.2.1-rc.2 and using only public DSH exports. See [CHANGELOG.md](CHANGELOG.md) for changes, [ROADMAP.md](ROADMAP.md) for plans and known limitations, and [DEVELOPMENT.md](https://github.com/cfanzx/dsh-compact-relay/blob/main/DEVELOPMENT.md) for build and release workflows.
+- **License**: [MIT](LICENSE). Feedback and Pull Requests are welcome via [GitHub Issues](https://github.com/cfanzx/dsh-compact-relay/issues).
+
+## Credits
+
+The design of this plugin references the public implementations of the following DSH community plugins and projects (ideas only; no code copied):
+
+- [DeepSeek Harness](https://www.deepseek.com/harness/) — the host platform this plugin runs on; all host capabilities used here come from its public exports.
+- [dsh-clear-mind](https://github.com/john-walks-slow/dsh-clear-mind) (MIT) — replacement transaction and boundary/lock checks.
+- [dsh-handoff-compaction](https://github.com/knighthongyu/dsh-handoff-compaction) (MIT) — summary structure validation, retry and cache alignment.
+- [dsh-compaction-policy](https://github.com/zyd232/dsh-compaction-policy) (MIT) — runtime gating of the preset-scoped engine.
+- [context-vista](https://github.com/GooodWei/context-vista) (MIT) — ring drawing and session projections subscriptions.
+- [dsh-session-handoff](https://github.com/WeiYe6/dsh-session-handoff) (MIT) — `/handoff` session creation and auto-switch flow.
+- [dsh-smart-compact](https://github.com/hoyyang/dsh-smart-compact) (BSD-3-Clause) — budget measurement and handoff anchor design.
+- [dsh-toolong-warning](https://github.com/Hjdd14/dsh-toolong-warning) (MIT) — compaction counting and reminders.
+- [dsh-compaction-instant](https://github.com/TsFreddie/dsh-compaction-instant) (MIT) — transaction error classification contract.
+- [dsh-plugin-memory](https://github.com/LittleBlackTong/dsh-plugin-memory) — settings-panel registration and rendering approach in DSH.
+- [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin) / [dsh-market](https://github.com/dsh-market/dsh-market) — community plugin catalog and in-app market.
+
+Thanks to the authors above for publishing their work, and to everyone who tested the plugin and sent feedback.
+
+## Contact
+
+- **Official channel**: the GitHub repository <https://github.com/cfanzx/dsh-compact-relay> and [Issues](https://github.com/cfanzx/dsh-compact-relay/issues) — bug reports, feature requests and release announcements.
+- **Developer email**: cfanzx@136.com — collaboration, security reports, and anything better discussed privately.

package/README.md

@@ -1,3 +1,148 @@
-# Temporary Holding Version
+<div align="center">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# dsh-compact-relay · 压缩接力
+
+**DeepSeek Harness 输入框上下文状态指示与会话管理插件。**
+
+简体中文 · [English](README.en.md)
+
+[![DSH](https://img.shields.io/badge/DSH-0.2.x-4d6bfe)](https://www.deepseek.com/harness/)
+[![license](https://img.shields.io/badge/license-MIT-yellow)](LICENSE)
+[![version](https://img.shields.io/badge/version-0.3.1-blue)](CHANGELOG.md)
+
+</div>
+
+![指示环与悬停数据](assets/hero-ring.jpg)
+
+## 概述
+
+本插件在输入框旁提供一个 28px 的环形状态指示器，用于实时展示上下文窗口占用率与压缩评估状态，帮助用户在触发自动压缩前主动管理上下文：
+
+- **灰色**：低于最小压缩阈值，暂无需执行压缩。
+- **蓝色**：常规容量区间已满，可执行手动压缩以释放空间。
+- **琥珀色（带缺口）**：达到建议压缩点（由缺口标识），点击可预览压缩估算数据并决定是否执行。
+- **红色**：达到交接阈值，建议生成九段式交接文档并切换至新会话。
+
+插件直接挂载于现有输入框旁，默认参数已针对 DSH 0.2.x 完成适配，无需改变既有操作流程。
+
+## 核心功能
+
+### 1. 状态可视化监控
+
+指示环按压缩评估逻辑分段显色，分别标识模型或阈值判定的建议压缩点、已锁定消息位置，以及 DSH 原生自动压缩线（默认 80%）。当上下文占用越过原生自动压缩线时，整环呈红色闪烁告警。
+
+鼠标悬停可查看详细数值：已用容量、累计压缩次数、当前操作建议、压缩判断点、原生自动压缩线及已锁定消息数量。
+
+### 2. 预览与确认压缩
+
+执行 `/bc` 命令（或通过指示环菜单触发）可预先查看待压缩范围、消息条数及预计释放的容量空间，需经用户二次确认后方才执行。确认前可随时取消，未提交前不会修改任何历史记录；已锁定的消息在压缩时自动跳过。
+
+![压缩预览与确认](assets/compact-preview.jpg)
+
+### 3. 结构化会话交接
+
+执行 `/handoff` 命令可生成包含九个标准部分的交接文档（总体目标、约束条件、已完成项、当前进度、涉及文件、关键决策、已知问题、未完成项、下一步计划），并在当前工作区自动创建新会话、注入该文档并完成切换，原会话完整保留。
+
+### 4. 关键消息锁定
+
+执行 `/pin` 命令可标记压缩时必须保留的消息。被锁定的消息在指示环上显示为品红色块，在菜单列表中显示为锁定行。
+
+![指示环菜单](assets/menu.jpg)
+
+## 指示环图例说明
+
+| 指示环视觉元素 | 状态含义 |
+| --- | --- |
+| 灰色弧 | 低于最小压缩阈值，不建议压缩 |
+| 蓝色弧 | 常规容量区间已满 |
+| 琥珀色弧 | 已越过压缩判断点，适合执行压缩 |
+| 红色弧 | 已越过交接阈值，建议切换新会话 |
+| 环形缺口 | 建议压缩点（由模型评估或配置阈值决定） |
+| 紫色刻度 | DSH 原生自动压缩线（读取 `compaction-basic.thresholdRatio`，默认 80%） |
+| 品红色块 | 已锁定消息在历史记录中的分布位置 |
+| 整环红色闪烁 | 已越过原生自动压缩线，即将触发 DSH 原生自动压缩 |
+
+![越过原生自动压缩线](assets/native-alert.jpg)
+
+## 安装
+
+**环境要求**：DSH 桌面版或 `dsh web` 0.2.x（已于 0.2.1-rc.2 测试通过），Node.js 22+。
+
+```sh
+dsh plugin --profile desktop add dsh-compact-relay
+```
+
+桌面版亦可打开 **插件 → 添加插件** 输入包名安装，或直接从 GitHub 安装：
+
+```sh
+dsh plugin --profile desktop add github:cfanzx/dsh-compact-relay
+```
+
+安装完成后需重启 DSH。插件内部配置项保存后立即生效，无需重启。
+
+## 设置项说明
+
+配置入口位于 **设置 → 压缩接力**（DSH 0.2.1+ 位于账号菜单内）：
+
+- **压缩提示**：配置最小压缩线、压缩提醒线与交接提醒线，控制告警触发时机。
+- **压缩行为**：配置摘要保留份数上限、近期原文保留 Token 数及交接文档存储目录。
+- **DSH 原生自动压缩**：读取宿主当前阈值，支持开启或关闭 DSH 原生自动压缩（修改 profile 配置前自动生成备份，重启后生效）。
+- **颜色与外观**：配置五项基准色，系统将根据浅色/深色主题自动派生适配色阶。
+- **帮助**：提供指示环图例、使用说明、问题反馈入口及「再看一次初次引导」按钮。
+- **关于与危险操作**：查看版本号、配置文件路径，支持恢复出厂默认设置。
+
+![设置页](assets/settings.jpg)
+
+每项配置均附带功能定义与参数修改影响说明；帮助区内置五个动态示例环图例，随当前配色与阈值实时更新。
+
+![指示环图例教学卡片](assets/teaching-card.jpg)
+
+首次打开会话时，指示环将触发动态高亮与简要功能说明（仅自动触发一次，可通过设置页按钮重新调用）。
+
+![首次引导](assets/onboarding.jpg)
+
+## 命令列表
+
+| 命令 | 功能说明 |
+| --- | --- |
+| `/bc` | 预览压缩：显示目标范围、消息条数及预计释放容量 |
+| `/bc confirm` | 执行已预览的压缩操作 |
+| `/handoff` | 生成九段式交接文档并创建、切换至新会话 |
+| `/pin` / `/unpin` | 锁定或解锁指定消息，锁定后跳过压缩 |
+| `/bctest` | 小范围空跑测试（仅供开发调试） |
+
+## 功能边界与限制
+
+- **不替代 DSH 原生压缩机制**：原生压缩仍由 DSH 宿主控制；本插件仅负责读取阈值、显示告警并在设置页提供开关选项。
+- **不篡改提示词与模型回复**：插件仅在用户明确确认压缩或执行交接时替换对应历史记录。
+- **摘要质量取决于底层模型**：摘要生成采用九段式结构化模板并包含格式校验与单次重试机制，但最终产出质量仍受限于所选模型的能力。
+- **纯本地存储**：插件状态保存于 `~/.dsh/compact-relay.json`，交接文档保存于 `~/.dsh/handoffs/`，无任何外部数据同步。
+- **界面语言限制**：当前版本用户界面仅提供简体中文，英文界面已列入后续计划（排期未定）。
+
+## 版本状态与开源许可
+
+- **当前版本**：0.3.1（首个公开版本），已于 macOS 环境下基于 DSH 0.2.1-rc.2 完成测试，仅调用 DSH 公开导出接口。变更记录详见 [CHANGELOG.md](CHANGELOG.md)，后续规划与已知限制详见 [ROADMAP.md](ROADMAP.md)，构建与发布流程详见 [DEVELOPMENT.md](https://github.com/cfanzx/dsh-compact-relay/blob/main/DEVELOPMENT.md)。
+- **开源许可**：采用 [MIT](LICENSE) 许可证，欢迎通过 [GitHub Issues](https://github.com/cfanzx/dsh-compact-relay/issues) 与 Pull Requests 提交反馈。
+
+## 参考与致谢
+
+本插件的设计参考了以下 DSH 社区插件与项目的公开实现（仅借鉴思路，未复制代码）：
+
+- [DeepSeek Harness](https://www.deepseek.com/harness/) — 插件运行的宿主平台；本插件的全部宿主能力均来自其公开导出接口。
+- [dsh-clear-mind](https://github.com/john-walks-slow/dsh-clear-mind) (MIT) — 自建替换事务与边界/锁检查的写法参照。
+- [dsh-handoff-compaction](https://github.com/knighthongyu/dsh-handoff-compaction) (MIT) — 摘要结构校验、重试与缓存对齐。
+- [dsh-compaction-policy](https://github.com/zyd232/dsh-compaction-policy) (MIT) — preset 作用域引擎的运行时门控思路。
+- [context-vista](https://github.com/GooodWei/context-vista) (MIT) — 环形图绘制与 session projections 实时订阅。
+- [dsh-session-handoff](https://github.com/WeiYe6/dsh-session-handoff) (MIT) — `/handoff` 建会话与自动切换流程。
+- [dsh-smart-compact](https://github.com/hoyyang/dsh-smart-compact) (BSD-3-Clause) — 预算测量与交接锚点设计。
+- [dsh-toolong-warning](https://github.com/Hjdd14/dsh-toolong-warning) (MIT) — 压缩计数与提醒。
+- [dsh-compaction-instant](https://github.com/TsFreddie/dsh-compaction-instant) (MIT) — 事务错误分类契约。
+- [dsh-plugin-memory](https://github.com/LittleBlackTong/dsh-plugin-memory) — 设置栏在 DSH 中的注册与渲染方式参考。
+- [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin) / [dsh-market](https://github.com/dsh-market/dsh-market) — 社区插件目录与可视化市场。
+
+感谢以上作者公开实现；也感谢所有帮忙测试、提反馈的朋友。
+
+## 联系方式
+
+- **官方渠道**：GitHub 仓库 <https://github.com/cfanzx/dsh-compact-relay> 与 [Issues](https://github.com/cfanzx/dsh-compact-relay/issues)（问题反馈、功能建议、发布公告）。
+- **开发者邮箱**：cfanzx@136.com（合作、安全问题，以及其他不便公开讨论的事项）。

package/ROADMAP.md

@@ -0,0 +1,125 @@
+# 压缩接力 · 目标与路线图
+
+> 版本基准：0.3.1（2026-10-20）｜状态：0.3 发布准备中
+> 维护方式：每次发布前更新"当前状态"与勾选进度；方向变化必须同时改本文件和 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 周）
+
+**这是我们的差异化，不碰压缩算法。**
+
+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 项目记忆（1–2 月）
+
+1. **项目上下文包**：目标 / 关键决策 / 待办 / 改过的文件，新会话自动带上。
+2. **接力链视图**：父子会话树/时间线，一键跳转。
+3. **Memory 双向**：读取项目页作为上下文，写回交接单（先跑稳单向再开）。
+4. **跨会话任务/决策追踪**：哪些做完了、哪些还欠着、为什么这么定。
+
+验收：多天项目不用回忆"上次做到哪"，直接继续。
+
+### 1.0 上下文生命周期自动化（远期）
+
+- 自动化等级：建议 → 一键确认 → 在 Step 边界自动执行（可配置）。
+- 换模型建议（窗口/成本更优）。
+- 多 agent / subagent 接力。
+- 零丢失、可观测、可恢复。
+
+验收：用户不再主动想"上下文会不会满"。
+
+## 四、明确切掉 / 不做
+
+| 方向 | 原因 |
+|---|---|
+| 自研压缩算法、工具输出/图片压缩 | 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) | 仓库 | 内容类型压缩 + 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。
+- ✅ 真实压缩 e2e：`test/e2e/real-compact.mjs`（真实模型 + 真实压缩事务 + `maxSummaries=1` 合并旧摘要分支）6 项断言通过。
+- ✅ P3-01～14（13 修/1 确认无需修）+ BUG-004 + P2-T1 已收口。
+- ⏳ 待一次重启复核：state 帧单调 `revision` 真机下发；待一次真交接复核：交接成功文案。
+- ⏳ 发布动作（待拍板）：GitHub 账号/仓库名 → 填 `repository`/`homepage`/`bugs` 与 `links`、发布渠道（npm / GitHub / 插件市场）。

package/TUTORIAL.md

@@ -0,0 +1,65 @@
+# 压缩接力 · 3 分钟教程
+
+给 DeepSeek Harness 输入框加一个**上下文指示灯**：告诉你现在还剩多少容量、什么时候该压缩旧会话、什么时候该交接新会话，并帮你把重要消息锁住。
+
+> 这个文件预留给 GitHub 教程页；建好仓库后，设置页「帮助」区的「使用教程」会直接链到这里。
+
+## 1. 先看环怎么读
+
+指示灯在输入框底部工具行（「完全权限」右侧），外环是容量进度，内圆是交接信号：
+
+| 区域/颜色 | 意思 | 你该做什么 |
+|---|---|---|
+| 灰（默认色） | 正常区还没走满（没到第一个断点） | 继续聊 |
+| 蓝（填满色） | 正常区走满了（到了断点1） | 这里是「该压缩」的位置 |
+| 琥珀（调整色） | 压缩区（断点1 → 交接线） | 点指示灯 →「压缩旧会话」，或输入 `/bc` |
+| 红（上限色 / 内圆红点） | 交接区（交接线之后），或摘要太多 | 点指示灯 →「交接新会话」，或输入 `/handoff` |
+| 警示红（原生线） | 80% 处的 DSH 原生自动压缩线（紫色径向刻度）；越过 80% 后整环红色闪烁 | 再往前 DSH 会自己压历史，先压缩或交接 |
+| 品红（锁定色） | 这里锁了一条重要消息（按它在对话里的位置显示，可多个） | 知道「我锁的东西在哪」 |
+
+**断点**（环上的小缺口）=「我判断这里适合压缩」的位置：模型判断（上下文超过最小压缩线、还没到压缩线、正到自然节点）或到压缩线时自动出现；压缩后环变短，断点自然消失。
+
+把鼠标放到指示灯上，会显示具体数字：`会话容量已用 xx.x%（xxxK / 1.00M），已压缩 n 次｜建议压缩 / 建议交接 / 正常｜压缩判断点 x%｜原生自动压缩线 80%｜已锁定 n 条`。
+
+**第一次用**会看到一条提示：点指示灯能压缩旧会话、**锁定重要消息**、交接新会话；会顺带告诉你 DSH 原生自动压缩线是多少，以及环上的小缺口什么意思。重要的结论/路径先锁定，压缩时才不会被压掉。
+
+这条引导只自动出现一次。想再看：**设置 → 压缩接力 → 帮助 →「再看一次初次引导」**，点完关掉设置页就会重新播放（手动重播时长更长：光晕 9 秒 / 提示 20 秒）。
+
+## 2. 记住三条命令
+
+| 命令 | 作用 |
+|---|---|
+| `/bc` | 压缩旧会话：**先看压缩预估**（压哪段、多少条、多少容量），再 `/bc confirm` 才真正执行 |
+| `/handoff` | 交接新会话：生成九段交接单（先出预览卡）→ 建新会话 → 自动切过去，旧会话保留 |
+| `/pin` | 锁定重要消息，压缩时**不碰**它们；`/pin clear` 或 `/unpin` 解锁 |
+
+菜单里也有同名入口，效果一样。
+
+## 3. 设置在哪
+
+打开 DSH「设置」→ 左侧「压缩接力」。页面标题下有一句话说明这页做什么、边界在哪（只动本插件的压缩/交接历史，不改模型回复）；6 个区块：压缩提示 → 压缩行为 → DSH 原生自动压缩 → 颜色与外观 → 帮助 → 关于与危险操作。
+
+- **指示灯怎么看**：设置页「帮助」区顶部的教学卡片，5 个示意环（未满灰 / 走满蓝 / 压缩区琥珀 / 交接区红 / 原生线），随你的配色和阈值实时变
+- **再看一次初次引导**：「帮助」区的按钮，点了关掉设置页就会重播引导（手动重播时长更长）
+- **最小压缩线**：低于它压缩不划算（默认 5%，会随保留量和窗口自动抬高）
+- **压缩提醒线 / 交接提醒线**：按上下文窗口的百分比算（1M 窗口默认 40% / 60%），换小窗口模型自动缩放
+- **摘要份数上限**：压到几份摘要后建议交接（默认 6）
+- **保留近期原文**：压缩时这段 token 内的近期消息保持原文（默认 40K）
+- **DSH 原生自动压缩**：状态 + 一键关闭/恢复（会先确认，改 profile 配置前备份，重启生效）；原生开着时交接线最高只能设到「原生线 −1%」
+- **交接单目录**：九段交接单保存位置
+- **颜色**：选 5 个基准色（默认/填满/调整/上限/锁定），浅色/深色两套自动派生；每行都有「作用」和「调整后」两行说明
+
+改完点「保存」，**立即生效，不需要重启**。
+
+## 4. 常见问题
+
+- **指示灯显示「上下文未知」**：会话刚打开，等半秒到 1.5 秒会自己出数。
+- **没有「可压」内容**：会话太短，或近期内容需要保留原文，或锁定把范围挡住了（先 `/unpin`）。
+- **压缩到一半取消了**：历史不会变、锁会释放；已发出的模型请求可能仍计费。
+- **换模型后阈值变了**：阈值按窗口比例算，小窗口模型会自动变小，这是预期。
+- **设置保存了但没变**：设置栏保存即时生效；改代码或 profile 配置才需要重启 DSH。
+
+## 5. 更多
+
+- 安装、完整说明见仓库 `README.md`；设计文档见 `ARCHITECTURE.md`。
+- 遇到 bug / 想提改进：到仓库 Issues 提一条（设置页「帮助」区的「反馈」入口建好后会直接打开）。