会话压缩阈值 windwhiterain/dsh-compaction-threshold

dsh-compaction-threshold

为 DeepSeek Harness 提供按会话自动压缩阈值，会话运行期间可在 Web 输入框里调整。

自带的后端（@deepseek-ai/dsh-compaction-basic）把触发百分比写死在智能体预设里：预设服务的每个会话都共用同一个数字，想改只能编辑 YAML 再重载宿主。这个粒度不适合真实工作——长时间重构希望晚点压缩、原样保留历史，临时会话希望早点压缩、省点开销，而这两种情况都不该重启宿主。

本插件沿用同一套压缩事务，把百分比变成按会话生效：权限和模型标签旁边多一个标签，显示当前值；菜单一点就能改；/compaction-threshold 用键盘做同样的事；值持久化存储在会话日志旁边，重启后依然有效。分叉会话和委派的子代理继承父级的值。

本包是第三方插件，也不掩饰自己的耦合：压缩后端必须是自带引擎的子类，所以它跟只跟 Cordis 上下文打交道的插件不同，会导入 @deepseek-ai/dsh-compaction-basic 并复制其触发策略。升级 harness 之前请先读已知限制。

- 界面效果
- 快速开始
- 使用
- 继承
- 工作原理
- 模型体验
- 验证
- 针对开发宿主开发
- 已知限制

界面效果

标签和权限、模型标签并排放在输入框里，显示当前会话的百分比：

输入框里的阈值标签

菜单提供预设默认值和 30 %–100 %。这里的会话是分叉出来的，继承了父级的 70 %，所以菜单还会说明这个值来自哪里：

阈值菜单

请求测量过一次之后，标签的提示和菜单标题会报告触发条件解析出的 token 数，当前生效的百分比一目了然，不用猜。

快速开始

dsh plugin --profile web add github:windwhiterain/dsh-compaction-threshold

然后在 ~/.dsh/profiles/web/cordis.patch.yml 里接两行——一行在宿主平面，一行在每个需要可调整的智能体预设里：

host plane: the durable store, the Session projection, and the command
- insert:
- id: compaction-threshold
name: 'dsh-compaction-threshold'

agent plane: replace the shipped backend inside the preset's compaction group
- id: compaction-basic
name: '@deepseek-ai/dsh-compaction-basic' # remove this row
...and add:
- id: compaction-threshold-engine
name: 'dsh-compaction-threshold/engine'
command-compact 和 tool-result-pruner 保持原样。引擎那一行省略 thresholdRatio，跟随后端默认值（0.8）；写上它，就是给这个预设换一个起点。

只有当会话所在预设声明了引擎那一行，输入框旁的 chip 才会出现。 想让这个旋钮在哪些预设里可调，就把引擎那一行加进哪些预设，其余预设保持不加：会话所在预设如果仍然挂载 @deepseek-ai/dsh-compaction-basic，就没有 chip，此时 /compaction-threshold 会提示没有任何东西会采纳这个值，而不是把它存下来。注意，没有记录任何预设的会话会组合出部署的默认预设，所以 chip 跟随的是默认预设——如果默认预设不是你正在调整的那个，就在 agent-preset-registry 里设置 selectedDefault。

之后重启宿主。 新依赖在启动时读取，所以那一行无法在运行中的进程里解析；如果在重启之前就应用预设替换，新会话挂载的会是一行解析不了的配置。deploy/ 里放着同样的说明，一份是检查清单，一份是结构化应用这些改动的脚本：

node deploy/apply-web-wiring.mjs ~/.dsh/profiles/web/cordis.patch.yml [--write]

用法

chip 打开一个菜单，里面有 Preset default 以及 30 %–100 %。同样的改动也可以直接输入：

| 输入 | 效果 |
| /compaction-threshold | 报告当前值、它的来源，以及解析出的触发点 |
| /compaction-threshold 60 或 60% | 压力达到窗口的 60 % 时压缩本会话 |
| /compaction-threshold 0.6 | 同上，写成比值（裸值 ≤ 1 视为比值） |
| /compaction-threshold default | 丢弃该值，重新跟随预设 |

改动从下一步开始生效，对已经在进行中的一轮也会强制执行（每个步骤边界都会读取该值），并且重启后依然保留。

继承

分叉出的会话和委派出去的子代理都会在 SessionHeader.parentSession 里记录自己的直接父级，所以两者都会继承。子会话拿到的是最近一个拥有该值的祖先的快照，最多向上 16 代，此后就自己拥有该值：

| 情况 | 结果 |
| 子会话的父级有 70 %，预设默认 10 % | 子会话显示 70 %，标注 inherited from the parent session |
| 父级没有值，父级的父级有 25 % | 子会话继承 25 %（最近一个拥有该值的祖先） |
| 子会话存在之后，父级把 70 % 改成 50 % | 子会话保持 70 %：快照只取一次 |
| 子会话执行 /compaction-threshold default | 子会话回到预设默认，并且不会重新继承 |
| 没有任何祖先拥有该值 | 子会话跟随预设默认 |

承载快照的那条记录同时也是「继承已用掉」的标记，正是它让 default 在子会话里仍然有意义。该值会持久写入，并且在子会话自己的值与继承来的值不同之前，chip 会一直把来源显示出来。

工作原理

两行，因为压缩后端和配置它的接口位于不同层面：

| 行 | 层面 | 负责 |
| dsh-compaction-threshold | 宿主 | 以 Session id 为键的存储域、compactionThreshold Session 投影，以及 /compaction-threshold 命令 |
| dsh-compaction-threshold/engine | 智能体预设，位于其 compaction 组内 | ctx.compaction 服务：内置引擎，带每会话压力比 |

引擎从宿主服务同步读取该值；宿主行不存在时，回退到自身配置的 thresholdRatio。因此接线错误的组合会退化为内置行为，而不是禁用压缩。上下文溢出恢复、保留、修剪、重试和摘要都原样继承。

阈值公式

thresholdTokens = floor(contextWindow × ratio)

这里的百分比指会话在压缩前可填充的、已声明上下文窗口的份额，没有其他因素会把它缩小。

这是本插件与 @deepseek-ai/dsh-compaction-basic 唯一一处有意分歧，后者还把阈值上限设为 contextWindow − outputReservation − headroomTokens。这个上限会让较大的输出预留一次性缩小所有百分比：在 262 144 token 的窗口上，maxTokens: 131072、默认 65 536 headroom 时，上限是 65 536 token，于是从 25 % 到 100 % 的每个设置行为都完全相同，这个旋钮不再名副其实。去掉上限即可恢复完整范围：100 % 现在表示「只在窗口基本填满时才压缩」。

后果值得直说：提示词加上预留的补全内容仍必须装进服务商的真实窗口，所以高百分比可能触达服务商溢出。上游恢复路径会处理这种情况，并按设计绕过该比例——这是服务商在告诉会话空间不够，而不是阈值策略触发。

headroomTokens 仍被接受，因为继承的 schema 带着它，它也仍提供默认摘要预算，但不再影响触发点。retainRatio/retainTokens 同理，是相对于窗口的。

为什么覆盖值放在存储域，而不是会话日志

Session 持久化读取器会拒绝生成式已知类型目录之外的事件类型，除非记录带有 ignorable: true（packages/session/session-persistence/src/storage-contract.ts），而 Session.append() 无法设置该标记。因此，harness 仓库之外的插件无法添加 Session 事件：它自己的日志会停止加载。覆盖值是非会话应用数据，所以它属于 ctx.storageDomain，客户端通过 Session 投影收到通知——投影按 key 寻址，无需为每个域写客户端代码。

模型体验

每会话压缩阈值

模型看到什么

没有直接看到任何东西：插件不添加工具，也不添加提示词文本。间接地，它当 <compacted-summary> 检查点替换较早的历史时，哪些内容会改变，以及最近多少历史保持原样，都与已发布后端的做法完全一致。

token 影响

调低会话的比例会更早压缩，因此每次请求花掉的提示词 token 更少，代价是摘要更多；调高比例则更晚压缩，直到服务商自己报告请求过长为止。摘要请求本身与已发布后端发出的那个请求相同。

KV-cache 影响

摘要调用复用会话自身的前缀，与已发布后端一致。改动比例永远不会重写请求前缀，因此不会让任何服务商缓存失效；它只改变哪些请求仍然带着未压缩的前缀。

验证

node probe/probe.mjs

这个探针在没有宿主的情况下驱动纯策略模块：窗口比例及其保留量、命令语法、范围选择、继承遍历（直接父级、跳过祖先、不可用值、循环安全、深度上限）、引擎品牌跨模块代际的存活，以及决定芯片出现在哪里的预设门控。28 个探针全部通过。

后续探针不需要浏览器。probe/session-tools.mjs 解码 zstd 分帧的会话日志，并报告每个已存会话的预设、工具目录和委派深度。probe/session-detail.mjs 报告单个会话选中的预设、路由、token 计数和压缩事件，probe/surface-tokens.mjs 用 harness 自己的估算器为其表面定价——这一对就是「压缩没有触发」报告背后的依据。probe/tsx-identity.mjs 证明：在源码启动的宿主下，checkout 之外的插件与宿主共享同一批 BasicCompactionEngine 和 Service 对象。

浏览器探针通过 playwright-core 驱动已安装的 Edge，并针对 dev 宿主验证：芯片能渲染、菜单通过命令写入、值按会话隔离、default 会清除它、清除后不会重新继承、fork 会继承、被委派的子级会继承：

node probe/dev-ui.mjs http://127.0.0.1:3081/?token=…
node probe/dev-fork.mjs http://127.0.0.1:3081/?token=… 70
node probe/dev-subagent.mjs http://127.0.0.1:3081/?token=… 80
node probe/dev-chip.mjs http://127.0.0.1:3081/?token=… 4

针对 dev 宿主开发

要验证客户端那一半渲染出的任何东西，都需要一个 dev 宿主，而且它绝不能和主宿主共用端口。第二个宿主如果继承默认端口，就会尝试绑定同一个地址，而在 Windows 上，第二次绑定可能把监听器从正在运行的宿主手里抢走——正在运行的宿主随后就会死掉。先检查端口，再用显式端口启动：

Get-NetTCPConnection -State Listen -LocalPort 3081 -ErrorAction SilentlyContinue # expect nothing
./scripts/dev-host.ps1 # DSH_HOME + profile + 127.0.0.1:3081 + --no-open
./scripts/dev-host.ps1 -Checkout C:/path/to/deepseek-harness # boot from source through tsx
scripts/dev-host.ps1 会拒绝主端口，拒绝已在监听的端口，拒绝把 ~/.dsh 当作 DSH_HOME，并且只绑定 loopback。它保证的三重隔离：

| 资源 | 主宿主 | 开发宿主 |
| 端口 | 部署自己的端口 | 显式指定的空闲端口，127.0.0.1 |
| DSH_HOME | ~/.dsh | 单独的目录 |
| 浏览器 | 由 harness 打开 | --no-open，所以没有窗口抢焦点 |

这里还有几条规则值得注意：

- --port 0 让操作系统分配空闲端口，完全不会冲突。
- --from-default-profile web 会启动它初始化的配置档，不是只做初始化的开关。端口参数要写在同一条命令里。
- 配置档的 cordis.patch.yml 会热重载，但新增依赖只在启动时读取，所以装完插件后开发宿主需要重启一次。
- 凭据按 home 存放：把 .credentials.yaml 复制进开发 home，或者在启动前把服务商的 key 导出到环境变量里。
- 文件级 hmr 根目录可以重载宿主那一半，不用重启；加完根目录后，要 touch 一下文件，因为 watcher 是对变更做出反应的。宿主运行期间往实时补丁里加根目录列表，同样不是可靠信号——接好之后重启一次，此后根目录就一直生效。
- watch 只重载宿主平面的行。 dsh-compaction-threshold（store、projection、command）在文件变更时重载；engine 那一行挂在智能体预设的 realm 里，重载不会重新导入它，所以 engine 有改动就得重新挂载预设——重启宿主，或者改一次预设、让它重新绑定会话。改动碰到 engine.js 或 lib/policy.js 时，直接重启。

已知限制

- 有一处与随包发布的后端不同，这是有意为之。 阈值就是一个普通的窗口比例；随包发布的后端会把它上限压到 window − outputReservation − headroomTokens，这会把旋钮整个 25 %–100 % 的区间压缩成一个值。区间选择、摘要事务、保留、裁剪、重试仍然照抄自 @deepseek-ai/dsh-compaction-basic 0.1.7-rc.1（src/region.ts 的 selectCompactableRange 和 engine 的事务）。这些内部实现没有导出，所以上游一改，这里只能手工同步，Config schema 也是从已安装的包里继承来的，不归自己所有。探针锁定的是算术，不是上游文件内容。
- 百分比调得再高，也可能撞上服务商的溢出。 请求必须连同预留的 completion 一起塞进服务商的窗口，而上游的恢复路径在服务商确认溢出时就会压缩，根本不看这个比例。百分比控制的是阈值；上限由服务商自己控制。
- 阈值修不了藏在工具 schema 里的压力。 只有预算被越过时才会尝试压缩，而事务会拒绝一个摘要不得小于它所替换的内容。在声明的窗口仅比自身工具目录略大的部署里，引擎会裁剪、尝试生成摘要，然后如实报告 summary is not smaller than the shadowed content。比例改变的是引擎何时尝试；它无法凭空造出表面装不下的余量。
- 快照在子会话首次观察时拍摄，而不是在分叉时。 Session 存储不发出创建或分叉事件，因此谱系从 SessionHeader.parentSession 读取，复制发生在子会话首次被读取时（引擎的压力检查或投影）。祖先在分叉与首次观察之间改变的值，就是子会话继承的值；尚未拥有任何记录的子会话仍会继承祖先之后设置的值；一旦拥有记录，继承就永久消耗掉了。
- 子会话只在引擎挂载处继承。 子会话保留父会话的智能体预设，所以这适用于带有引擎行的预设；预设的子会话若仍运行随附后端，则没有 chip，也没有继承。
- 包刻意不声明依赖。 @deepseek-ai/cordis、 @deepseek-ai/dsh-compaction 和 @deepseek-ai/dsh-compaction-basic 必须从宿主解析，和随附行完全一样；DSH 配置档内的 link: 或 git 安装会通过该配置档解析它们，于是插件共享宿主的模块实例，而不是加载引擎和 Service 的第二份副本。因此在宿主之外运行 import('dsh-compaction-threshold') 会因这些说明符失败，这是预期行为。
- 会话删除时记录从不做垃圾回收。 /compaction-threshold default 清除单个会话的值，整个域可以通过删除其存储单元文件来丢弃。
- 没有存储域就没有持久化。 没有 ctx.storageDomain 时，值只存在于进程内存中（插件记录一条警告），引擎继续工作。
- 没有引擎行的预设不显示 chip，并拒绝该命令。 对于自身 compaction 服务不是此引擎的会话，投影视图返回 null，chip 将其读作「未提供」；/compaction-threshold 报告同样内容，而不是存储一个无人会遵守的值。门控在每次读取时求值，而不是在折叠中，因此切换预设立即生效，并且它通过 agentPresets.serviceFor 读取该引擎：预设修订版将其服务发布在 isolate 领域之后，所以 agent.ctx.get('compaction') 在该领域之外解析，找到的是宿主平面。缺失是 null，绝不是省略或 undefined 值：注册表无条件分配该键，而 SessionSummary 通过 api-session/added 转发这些值，其无损 JSON 检查会拒绝 undefined 成员。
- 本进程没运行过的会话，由它声明的预设决定，而不是由活着的智能体决定。 这种会话没有智能体可问，它的组成就是头部记录的内容——头部没写名字时，就用部署默认值，所以默认预设带引擎时，这个标签理应出现。名册是某一时刻的读取结果，会缓存，并在 agent-preset/selected 时丢弃；在注册表给出答复之前，以及对于没有任何声明的预设，这道门会保留控件，而不是把它从仍在组成中的会话上撤掉。对每个未注册会话都回答 true，而不是去读名册，会让标签铺满整个侧边栏——任何主机重启后都是如此，这个版本就是这样发出去的；lib/policy.js 里的 presetMountsEngine 是纯决策，探针覆盖了边界两侧。
- 标签渲染在上下文计量器旁边，而不是里面。 内置计量器的弹出层没有扩展槽位，所以有效触发器在这个标签自己的工具提示和菜单标题里重复了一遍。

License

MIT — see LICENSE.