概述

本插件在输入框旁提供一个 28px 的环形状态指示器，用于实时展示上下文窗口占用率与压缩评估状态，帮助用户在触发自动压缩前主动管理上下文：

• 灰色：低于最小压缩阈值，暂无需执行压缩。
• 蓝色：常规容量区间已满，可执行手动压缩以释放空间。
• 琥珀色（带缺口）：达到建议压缩点（由缺口标识），点击可预览压缩估算数据并决定是否执行。
• 红色：达到交接阈值，建议生成九段式交接文档并切换至新会话。

插件直接挂载于现有输入框旁，默认参数已针对 DSH 0.2.x 完成适配，无需改变既有操作流程。

核心功能

1. 状态可视化监控

指示环按压缩评估逻辑分段显色，只表达容量：模型或阈值判定的建议压缩点，以及 DSH 原生自动压缩线（按宿主实际 token 预算算出的触发点：deepseek-flash 约 67.8%，配置阈值默认 80%）。0.5.1 起环上不再画锁定消息的位置（位置标记归 0.6 时间线），锁定状态以悬停卡/菜单的条数显示。当上下文占用越过原生自动压缩线时，整环呈红色闪烁告警。交接提醒线晚于当前模型的实际触发线（−5pp）时，环上交接刻度旁会出现红色小警示，悬停卡与 /handoff 菜单也会同步标出「交接线已晚」。

上下文进入「可压缩区间」（最小压缩线到压缩线之间）时，插件会在系统提示里主动告诉模型当前容量与区间，模型据此判断「刚完成一个自然节点」时是否记录压缩节点（0.3.4 起；此前模型看不到容量，判断条件不可执行）。

鼠标悬停可查看详细数值：已用容量、累计压缩次数、当前操作建议、压缩判断点、原生自动压缩线及已锁定消息数量。

2. 预览与确认压缩

执行 /bc 命令（或通过指示环菜单触发）可预先查看待压缩范围、消息条数及预计释放的容量空间，需经用户二次确认后方才执行。确认前可随时取消，未提交前不会修改任何历史记录；已锁定的消息在压缩时自动跳过。

3. 结构化会话交接

执行 /handoff 命令可生成包含九个标准部分的交接文档（总体目标、约束条件、已完成项、当前进度、涉及文件、关键决策、已知问题、未完成项、下一步计划），并在当前工作区自动创建新会话、注入该文档并完成切换，原会话完整保留。

4. 关键消息锁定

执行 /pin 命令可标记压缩时必须保留的消息。锁定状态与条数显示在悬停卡（「已锁定 N 条」）和菜单（锁定行 /「已锁 N 条 · 失效 M」）里；0.5.1 起环上不再画 pin 位置块（位置标记归 0.6 时间线）。

5. 接力条：交接链与双向跳转

交接之后，输入卡上方会出现一条「已接力自 历史 N：<原名>」的接力条；点开它就是一个会话导航菜单：

• 完整交接链：点「完整交接链」才按需读取（不展开不发请求），一次列出整条链「历史 N：<原名>」（默认服务端只读持久化日志，祖先会话没打开也能读；老宿主回落逐级查询）。每行都能打开那一跳的交接单、点整行跳到那个会话（已归档的会先自动恢复）。最多回看 8 层，链路异常成环会自动停；某一层实在读不到时保留已读行 +「无法读取更早的链路 / 上一层会话未打开」，老宿主还会给「打开并继续」（打开那一层后自动续读），不影响菜单其他入口。
• 父 → 子：把接力棒交出去之后，父会话侧的接力条变成「已交接给新会话」，「去新会话」一键切回这次交接出来的新会话（新会话若被归档过，也会先恢复再切）。
• pin 失效标注：被压缩（尤其 DSH 原生自动压缩）带走的锁定消息不再凭空消失——悬停卡与菜单标「已失效 N 条（随原生压缩移除）」；原生压缩即将覆盖锁定消息时会提前提示「先交接（/handoff）或解锁」。
• 置顶确认：交接后归档旧会话会取消它的侧栏置顶（宿主行为）。旧会话置顶时，交接预览先问一次：点「交接并归档（取消置顶）」才归档，点「只交接，保留置顶」则旧会话和置顶都留着。
• 归档开关：交接预览里可以勾掉「交接后自动归档旧会话」（默认开）；首次引导里也写了这个选项。
• 强制归档（0.5.2）：旧会话还有任务在跑时，自动归档会「保留可见、不停止任务」。确实要清理时，接力条菜单里有「强制归档旧会话（会停止后台任务）」：点开还会再确认一次，确认面板明确写「会停止旧会话上正在跑的任务（turn / 子代理 / 后台任务 / 定时任务），中断后无法恢复」；旧会话在侧栏置顶时会补「归档会同时取消置顶（宿主行为）」。默认不会自动做这一步，只有你在确认面板里点「强制归档（停止任务）」才会执行。

老链（0.5.0 之前生成的会话）没有交接单路径记录，界面显示「暂无交接单」而不是猜一个——它会先向父会话只读回查一次。

指示环图例说明

指示环视觉元素	状态含义
灰色弧	低于最小压缩阈值，不建议压缩
蓝色弧	常规容量区间已满
琥珀色弧	已越过压缩判断点，适合执行压缩
红色弧	已越过交接阈值，建议切换新会话
环形缺口	建议压缩点（系统在可压缩区间主动提示模型判断；模型记录或到达压缩线时自动出现）
紫色刻度	DSH 原生自动压缩线：按 min(窗口 × thresholdRatio, 窗口 − 输出预留 − headroomTokens) 算出的实际触发点（deepseek-flash 约 67.8%；thresholdRatio 配置默认 80%，只是理论上限）
整环红色闪烁	已越过原生自动压缩线，即将触发 DSH 原生自动压缩

0.5.1 起环只表达容量，不再标注 pin 位置；「已锁定 N 条 / 已失效 M 条」在悬停卡与菜单查看（位置标记归 0.6 时间线）。

三条线（deepseek-flash 1M 默认）

线	默认值	含义	怎么调
压缩提醒线	40%	到线变琥珀色，菜单建议「压缩旧会话」	设置 → 压缩接力
交接提醒线	60%	到线内圆亮红点，菜单建议「交接新会话」	设置 → 压缩接力；硬上限 = 实际触发线 −5pp（deepseek-flash 下 62%）
原生自动压缩线	67.8%	DSH 按 token 预算真正触发自动压缩的点（配置阈值 80% 只是理论上限，deepseek-flash 的输出预留 + DSH 余量把它压到 67.8%）	profile 里 compaction-basic 的 thresholdRatio（默认 80%）

交接线为什么要留 5 个百分点：交接提醒必须早于 DSH 自己压历史，才有时间生成交接单、开新会话。所以 0.4.2 起交接线有硬上限 实际触发线 −5pp（取整到整数百分位；deepseek-flash 1M 窗口下是 62%）：超过时拒绝保存并提示目标值，不静默夹紧；已存的高值不会被偷偷改写，但设置页会常驻告警，并可点「按实际线重算」一键改成上限。实际触发线算不出（无会话 / 宿主没给）时不告警、不阻断，保存校验退回配置阈值防呆（与 0.4.1 一致）。

安装

环境要求：DSH 桌面版或 dsh web 0.2.x（已于 0.2.1-rc.2 测试通过），Node.js 22+（插件跟随 DSH 自带运行时）。若要在源码里跑测试，需要 Node 22.15+（测试脚手架用到 node:module.registerHooks）。测试已在 macOS 与 Windows 11（Node 24.22）实测全部通过。

dsh plugin --profile desktop add dsh-compact-relay

桌面版亦可打开 插件 → 添加插件 输入包名安装，或直接从 GitHub 安装：

dsh plugin --profile desktop add github:cfanzx/dsh-compact-relay

安装完成后需重启 DSH。插件内部配置项保存后立即生效，无需重启。

设置项说明

配置入口位于 设置 → 压缩接力（DSH 0.2.1+ 位于账号菜单内）：

• 压缩提示：配置最小压缩线、压缩提醒线与交接提醒线，控制告警触发时机。
• 压缩行为：配置摘要保留份数上限、近期原文保留 Token 数及交接文档存储目录。
• DSH 原生自动压缩：读取宿主阈值并换算实际触发线，支持开启或关闭 DSH 原生自动压缩（修改 profile 配置前自动生成备份，重启后生效）。
• 颜色与外观：配置五项基准色，系统将根据浅色/深色主题自动派生适配色阶。
• 帮助：提供指示环图例、使用说明、问题反馈入口、「再看一次初次引导」按钮，以及「诊断信息」（只在本机生成、可预览/复制，见下节）。
• 关于与危险操作：查看版本号、配置文件路径，支持恢复出厂默认设置。

每项配置均附带功能定义与参数修改影响说明；帮助区内置五个动态示例环图例，随当前配色与阈值实时更新。

首次打开会话时，指示环将触发动态高亮与简要功能说明（仅自动触发一次，可通过设置页按钮重新调用）。

诊断信息与隐私

设置 → 压缩接力 → 帮助 →「诊断信息」：

• 点【生成并预览】：只在本机生成一份 Markdown + JSON 诊断信息，先弹层预览；再点【复制 Markdown】/【复制 JSON】复制，自己决定粘贴到哪（例如 GitHub issue）。
• 点【打开问题报告页】：打开预填了版本/平台短字段的 GitHub issue 页，不会把诊断信息直接贴进去——是否粘贴、粘贴什么由你决定。

诊断包里有什么：插件版本、DSH 版本（拿不到就留空）、Node / 操作系统 / 架构 / 语言环境；配置的阈值、保留量、超时与颜色模式；当前状态的数值摘要（窗口、已用、摘要数、锁定数等）；本次加载后的压缩/交接/锁定计数、耗时 p50/p95，以及最近 20 条错误码。

绝不包含：聊天内容、摘要、交接单正文、工具参数/结果、文件路径、用户名、hostname、会话 id、密钥/token/cookie、其他插件清单或自定义链接。产物在宿主进程内按白名单逐字段构造，并额外做一遍正则脱敏（命中只替换为 [REDACTED]、只记数量，不保留原文）。

三条隐私说明：

1. 诊断信息只在本机生成：插件没有任何自动上传、遥测或外发网络请求；诊断端点只提供只读 GET，没有上传通道。
2. 不碰对话内容：只采集数值、枚举、布尔与错误码，不读取消息、摘要或交接单正文。
3. 打开 issue 页只是打开浏览器；issue 默认公开，是否粘贴、粘贴到哪由你决定。插件不加网络能力，也不会上报任何数据。

命令列表

命令	功能说明
/bc	预览压缩：显示目标范围、消息条数及预计释放容量
/bc confirm	执行已预览的压缩操作
/handoff	生成九段式交接文档并创建、切换至新会话
/pin / /unpin	锁定或解锁指定消息，锁定后跳过压缩
/bctest	小范围空跑测试（仅供开发调试）

功能边界与限制

• 不替代 DSH 原生压缩机制：原生压缩仍由 DSH 宿主控制；本插件仅负责读取阈值、显示告警并在设置页提供开关选项。
• 不篡改提示词与模型回复：插件仅在用户明确确认压缩或执行交接时替换对应历史记录。
• 摘要质量取决于底层模型：摘要生成采用九段式结构化模板并包含格式校验与单次重试机制，但最终产出质量仍受限于所选模型的能力。
• 纯本地存储：插件状态保存于 ~/.dsh/compact-relay.json，交接文档保存于 ~/.dsh/handoffs/，无任何外部数据同步。
• 依附桌面输入框：环形指示器、/bc、/handoff 依附 DSH 的输入框与斜杠命令；headless 会话或 QQ / 微信等桥接链路不会加载它们，在这些链路里发 /bc 会被当成普通消息——这是桥接链路的能力边界，不是插件故障。
• 界面语言限制：当前版本用户界面仅提供简体中文，英文界面已列入后续计划（排期未定）。
• 模型判断提示的前置：可压缩区间的动态提示依赖 DSH 0.2.x 的根服务 systemPrompt（与 memory 等插件同款）；它是启发式提示，不保证模型每次都会记录压缩节点，但条件从「不可判断」变成「可判断」。
• 接力链只认单亲血缘：链记录只有 parentId/childId，「分叉 → 各走一条链 → 再合并」没有定义（fork 出来的副本与 subagent 会话不参与接力链，按各自独立处理）。「去新会话」只指向最近一次交接出来的会话（同一会话交接过两次时，更早的那个下一代请从侧栏找）。0.5.0 之前的老链由会话头 + 标题兜底合成，没有交接单路径，界面显示「暂无交接单」（不伪造、不猜）。
• 归档与置顶互斥：宿主归档会话时会同时取消置顶。插件在自动归档前置顶会话会先问（见上），但你在侧栏手动归档置顶会话时，那一步的确认归宿主。
• 交接单的程序段随现场变化：有锁定消息时，「当前进度」程序段会列出锁定条数与锚点摘要，所以不同 pin 状态下重新生成交接单，程序段内容会变（这是有意的：交接单要反映交接那一刻的事实）。
• 完整交接链是按需读取：展开才查（默认一次 /api/compact-relay-chain 由服务端只读持久化 header/日志，最多 8 层；祖先未加载也能读；不展开零额外请求）。老宿主没有该端点时回落逐级 state 查询；某层未加载会显示「上一层会话未打开」+「打开并继续」。归档会话的记录能读，但跳转前会先恢复（否则会被宿主拒绝）。

版本状态与开源许可

• 当前版本：0.5.2（已发布）。版本线：0.3.1 首个公开版本；0.3.2 修设置页链接与联系方式；0.3.3 Windows 适配；0.3.4 修判断机制并补交接单渲染；0.3.5 修无活 agent 时压缩按钮误禁；0.3.6 修原生压缩线解析作用域（BUG-012）；0.4.0 判断机制加强（cue 文案 v2 + 注入门控 + 计量）、诊断包、压缩预览建议锁定、pin 保留契约、轻账本累计、交接预览两段可编辑、接力链元数据、原生自动压缩真实触发线；0.4.1 统一原生压缩线显示口径；0.4.2 交接线保命补丁（硬上限 = 实际触发线 −5pp、三处告警 + 一键重算）；0.5.0 无痕交接（命名反转「历史 N」+ 新会话继承原名、输入框上方接力条、交接后自动归档旧会话 + 恢复入口）；0.5.1 收尾（祖先会话交接后接力条消失、0.5.0 前老链无条、归档入口死路与文案；pin 失效标注、原生压缩提前保护、置顶确认、归档开关、完整交接链、父→子入口；完整链在祖先未加载时只显示 1 层——改为服务端只读持久化日志一次读全，老宿主保留「打开并继续」兜底；设计定稿环只表达容量，pin 位置标记归 0.6 时间线）；0.5.2 契约快照 golden、record 形状唯一构造器、强制归档旧会话入口 + 二次确认/置顶确认、摘要缓存对齐（对话模型沿用主循环推理档位，生产命中 2–5% → 99.7%）。已在 macOS（DSH 0.2.1-rc.2）与 Windows 11（Node 24.22）完成测试，仅调用 DSH 公开导出接口。变更记录详见 CHANGELOG.md，后续规划与已知限制详见 ROADMAP.md，构建与发布流程详见 DEVELOPMENT.md。
• 开源许可：采用 MIT 许可证，欢迎通过 GitHub Issues 与 Pull Requests 提交反馈。

参考与致谢

本插件的设计参考了以下 DSH 社区插件与项目的公开实现（仅借鉴思路，未复制代码）：

• DeepSeek Harness — 插件运行的宿主平台；本插件的全部宿主能力均来自其公开导出接口。
• dsh-clear-mind (MIT) — 自建替换事务与边界/锁检查的写法参照。
• dsh-handoff-compaction (MIT) — 摘要结构校验、重试与缓存对齐。
• dsh-compaction-policy (MIT) — preset 作用域引擎的运行时门控思路。
• context-vista (MIT) — 环形图绘制与 session projections 实时订阅。
• dsh-session-handoff (MIT) — /handoff 建会话与自动切换流程。
• dsh-smart-compact (BSD-3-Clause) — 预算测量与交接锚点设计。
• dsh-toolong-warning (MIT) — 压缩计数与提醒。
• dsh-compaction-instant (MIT) — 事务错误分类契约。
• dsh-plugin-memory — 设置栏在 DSH 中的注册与渲染方式参考。
• awesome-dsh-plugin / dsh-market — 社区插件目录与可视化市场。

感谢以上作者公开实现；也感谢所有帮忙测试、提反馈的朋友。

联系方式

• 官方渠道：GitHub 仓库 https://github.com/cfanzx/dsh-compact-relay 与 Issues（问题反馈、功能建议、发布公告）。
• 开发者邮箱：[email protected]（合作、安全问题，以及其他不便公开讨论的事项）。