Skip to content

dsh-command-context-trim

Verified

dsh-command-context-trim · v0.7.5 · MIT · Web UI

Model-free /trim for DeepSeek Harness — drop the oldest, least valuable span of context on demand (the `/trim` command) or automatically when a request hits the model's context wall, without any model call.

Install

dsh plugin add dsh-command-context-trim

Confirm the layer applied with dsh --profile default --dump-config — see the install guide.

Source

Tags

Readme

dsh-command-context-trim

English →

给 DeepSeek Harness 增加一个不调用任何模型的 /trim: 在真正溢出之前,把对话里最旧、最不重要的一段上下文裁掉,让会话能切到窗口更小的模型上继续跑;同时可以按路由 调优 DSH 自己的 compaction 触发点与工具结果裁剪阈值。

本文是 README.md 的中文同步版:同结构、同命令、同默认值、同公式、同验证事实(长段落做了压缩翻译)。 版本号见上方 synced-with-readme 标记,test/docs-sync.test.js 会检查它与 package.json 一致、且关键内容不漂移。

为什么需要它

把长会话从大窗口的云端模型切到小窗口的本地模型时,下一个请求就会超过新模型的窗口。既有做法是切换前先 /compact——而这正是痛点所在:compaction 是摘要,它的摘要请求必须既能塞进(已经变小的)窗口,又要容纳那段 正被摘要的内容;窗口越小,摘要越容易失败,或摘要质量越差(要压缩的信息越多)。/trim 换了一条路:先把最旧的 上下文裁掉,不调用模型、不产生摘要,于是后续 /compact 更便宜、也更容易成功。

它给本地模型带来什么

DSH 的压缩触发点是 min(thresholdRatio × contextWindow, contextWindow − R − headroom),其中 R 是该路由自己的输出预留,而 headroom 固定为 65536,与窗口大小无关。在百万 token 的云路由上这几乎无所谓;在本地卡上它决定一切:

  • 131072 窗口:固定 headroom 让触发点落在 37.5 %,而不是比例想要的 80 %⇒压缩来得又早又频繁;
  • 本插件把该路由的 headroom 设为 0(比例重新说了算)⇒触发点回到 104857(80 %);
  • 效果就是更少、更晚的压缩:同样一段工作,压缩次数下降、每次压缩要处理的量更小。

preset 路线是上锁的,而且必须保持可解析

会话一旦开始,它的 preset 就固定了(agent-preset/locked),fork 也继承父会话的 preset 并被同样上锁: buildForkSeed 会把父会话的 turn/start 事件复制进子会话(dsh-session/lib/index.js:884-893),而 fork 本身要求 父会话已有一个完成的 turn,于是子会话的 turnBoundary.lastTurn > 0⇒同样换不了 preset。因此:

  • 想要新参数:让进程重启即可——会话的 preset id 是粘住的(它来自会话的 agentPreset 投影,而 assertPresetUnchanged 会拒绝另一个 id),但该 id 背后的定义在每次 adopt 时都会被重新解析: createOrAdopt 与 resumeObserved 都会调用 composeAgent(presetForObservation(observation)),再把新组合交给 agents.resume,而 retain(id) 返回的是当前定义所激活的那一代。所以"改 preset 时没有在运行"的会话, 只要 resume 就会吃到调优——不需要 fork。

只有一种情形需要 fork:改定义时会话仍在运行。活着的 agent 绑在它当初组合的那一代上,那份绑定会让旧 realm 保持 存活,所以改动到不了它⇒这时才 fork(或等下一次重启)。fork 是新 session id、且自身也被锁(继承父会话的 turn/start)——但这对它无害,因为它已经在跑调优后的值。

该用哪条路线

两条路线都能设置全部压缩参数——触发点、pruner、以及摘要模型(summarizationProvider / summarizationModel 就是 compaction-basic 上的普通键,可用 modelPolicies 按路由设置)。优先 profile 平面:它每次启动都能重新调优、 且不涉及 preset 的持久性负担。

路线 覆盖
profile 平面(headless / tui:autoTuneCompaction、/context-tune tune) 自动路径确实会触发:host 平面拥有 agent
preset 平面(web:/context-tune preset inplace + check + fork) 手动:会话 agent 在各自 preset 域里创建,其生命周期事件到不了 host 平面(已实测)

安装

# 从 npm
dsh plugin --profile web add dsh-command-context-trim

# 从 checkout
dsh plugin --profile web add file:/path/to/dsh-command-context-trim

用法

  /trim                                 # 按当前模型窗口裁剪
  /trim check                           # 只报告计划,不改动
  /trim 32k                             # 指定 32768 token 预算
  /trim 40000                           # 指定 40000 token 预算
  /trim provider:model                  # 按另一条路由的窗口计算
  /context-tune tune [check]            # 用当前活跃路由重新调优本进程的 compaction 行(profile 平面)
  /context-tune preset [check|list|default|inplace|p:m]
  /context-tune rescue <id> [--from <donor>] [--untuned]
  /context-tune reset [check] [preset-id] # 去掉本插件写进 preset 的调优行

想撤销调优用 /context-tune reset:它删掉本插件写进 profile 补丁的那些标记块,于是每个 preset 回到它 自己的定义。不带参数就是列出并删除全部;带 preset id 只删那一个;加 check 只报告不写。它靠标记块精确认出 哪些行是自己写的(不靠匹配描述文字),所以别的工具写的块会被列出来但不动。preset 锁依然有效——删除同样只对 新会话、或重启之后的会话生效。

/context-tune preset 的完整形式:

/context-tune preset              # 依据 profile 里配置的路由生成并落地一个调优 preset
/context-tune preset inplace      # 覆盖**基础 preset 自己的 id**,而不是新增一个 id(见下)
/context-tune preset check        # 打印将生成的行 + 路由覆盖率,不写任何东西
/context-tune preset list         # 会覆盖哪些路由、各自拿到什么触发点
/context-tune preset default      # 同时把它设为**新会话**的默认 preset
/context-tune preset p:m          # 本次用 p:m 作为摘要路由
/context-tune rescue <id>         # 用同 id 重建丢失的 preset(--from <donor>、--untuned)

/context-tune preset check 是过期信号:它统计当前 preset 覆盖了多少条路由,并对消息预算 ≤ 64K 却未被覆盖的路由 给出明确告警——那是唯一一种"继承顶层调优值反而打开压力触发"的情况。新增模型后跑一次 check,报缺口就重跑 /context-tune preset inplace:

coverage: 4 route(s) configured, 3 covered by this preset, 1 not covered.
⚠ uncovered SMALL route bonsai-8gb//models/mtp-lean.gguf (40960 − 8192 ≤ 65536): without a policy it inherits the
  tuned top level, which enables the pressure trigger on a route where that measured slower. Re-run /context-tune preset inplace…

工作原理

一次 trim 是两次同步相邻的追加:先写入一条替换消息(带 plugin:dsh-command-context-trim 来源标记), 再写入 token meter 的测量事件;两者之间没有 await,所以模型不会看到中间态。裁剪按从最旧开始的优先级进行, 最后一条消息降级为"尽量不裁",用户指令始终受保护。

分词器校准

DSH 的 token meter 按固定 4 字符/token 计价。真实会话比这个更密,所以 meter 少算了即将发出的请求。 在一个真实会话上实测,各路线的差距是 1.16×–1.32×(中位 1.18,p90 1.28)——足以让 meter 认为是 12 000 token 的请求, 在服务端其实是 15 800,已经越过 15 000 的窗口。

插件现在自己学出这个差距,并在整个流程里用服务端的单位工作。

因子是怎么学出来的

每一条带 usage 的 assistant/message,都是一次服务端已经计过价的请求:

realPrompt  = usage.inputTokens + usage.cacheReadTokens + usage.cacheWriteTokens
estPrompt   = 该消息之前的请求面  +  封装(工具 schema)的价格
factor      = realPrompt / estPrompt

那条 assistant 消息本身要排除:它是回答,不是产生它的那次请求的一部分。缓存字段要算进去,因为 dsh 把它们分开记 (inputTokens 是未命中缓存的部分)。

样本按 provider:model 路线分开保存,保留最近 50 条。某条路线的因子取这些样本的 p90,不是均值: 一次日志很重的请求不该改变因子,但一串这样的请求应该。因子永远不低于 1.0——meter 算多了,不是丢上下文的理由。

一条路线要积累 3 个样本才采信它的因子。在那之前、以及对所有没见过的路线,因子都是 1,插件的行为和加校准之前 完全一样。

没有学到因子的路线也不是只靠 meter 的估算。meter 一旦采用服务端的真实用量当基准,它的总量就是真实 token,而它给 每个节点定的价还是估算值——两者的比值,就是这一次正在定价的请求上量出来的密度。插件取"学到的因子"和"这个隐含 密度"里更大的那个,于是服务端已经算过账的请求,定价绝不会低于服务端实际收的数;刚切过去的路线,也能用服务端 上一次真正回答过的那个请求来定价。

用在哪里

因子把 meter 给每个节点定的价换算一遍,于是规划器比较的是同一个单位:

位置 之前 之后
/trim 的预算判断 估算值 真实大小
/trim 的"已在预算内" 估算值 真实大小
自动裁剪的梯度 失败请求的估算值 失败请求的真实大小
/trim 的汇报 估算值 真实大小

请求的封装单独计价——就是工具 schema 自己的价格——而不是拿 meter 的总量减去请求面当封装。只有在 meter 全部用估算 的时候,这个差值才等于封装;一旦 meter 采用了服务端的真实用量当基准,这个差值就是"真实"与"估算"之间的差,把它当封装 会反过来把本次要裁剪的请求撑大。

实际改变了什么

同一个会话、同一个窗口,在学到因子之前和之后的实际输出(隔离的 dsh 0.2.0-rc.2,接一个分词密度是 dsh 假设值两倍的 mock 服务端):

/trim  →  Already within budget: ~6791 / 11527 tokens for mock:mock-model (window 21000). Nothing to trim.
/trim  →  Cannot free enough for mock:mock-model (window 21000): the largest balanced span frees ~0 of the ~2408
           tokens needed. Protected content: task statement ~3044 tokens, recent tail ~3354 tokens …

第一行是 meter 在说话(估算 6791,装得下),第二行是服务端在说话(真实 13 896,装不下)。没校准时插件会认为不用裁, 然后被服务端拒掉。

表存在哪

<profile>/context-trim-calibration.json,和 profile patch 放在一起。文件里存的是原始观测值,不是因子: 把样本变成因子的策略可以改,而不必作废已经测到的东西。文件缺失或损坏都会被忽略——插件没测过的因子不能采信。

删掉这个文件就是全部忘掉、从头再来;全新 profile 本来就是空的,行为和加校准之前完全一致。

它不做什么

  • 不动压缩的触发阈值。 一个静态阈值不可能同时对"已对齐"和"未对齐"两种情况都正确:把它除以因子,会让压缩在 最常见的那种情况(dsh 自己的 meter 已经采用了服务端真实用量)下提前约 20% 触发。未对齐的情况由校准后的裁剪梯度兜底。
  • 不改上下文窗口大小。 因子纠正的是请求怎么被计数,不是窗口有多大。

上下文墙上的自动裁剪

autoTrim(默认开启)让同样的免模型裁剪在无人敲命令时发生:一个 prepend 的 agent/request-error 监听器 响应 CONTEXT_WINDOW_EXCEEDED,裁剪,然后请循环重试。它不在普通压缩时触发。

请求失败(上下文墙)
  → 裁剪并重试(最多 maxAutoTrimRetries 次)
  → 仍失败⇒交给 DSH 自己的压缩路径

服务端把回答截断时

回答以 length 结束不是错误:请求成功了,是服务端停止了生成。自动裁剪只认 CONTEXT_WINDOW_EXCEEDED, 看不到这种情况,用户只会得到一轮莫名其妙少了一半的回答。

所以插件只提示,不自动裁。当一条 assistant 消息的 finish 块报 max-tokens、或 turn/end 的原因是 max-tokens 时,它往会话里写一行:

[context-trim] the provider cut the previous reply short (a length stop). The request carried 122999 tokens of a
131072-token window, over the 103219-token budget. It was allowed 16384 tokens of output and produced 1. Run /trim to
shrink the context.

这个数字用的是服务端自己报的提示词用量(含缓存读写的计费),所以不带 ~;插件按路线学到的系数只是没有 usage 时的 兜底,会带上插件自家估算惯用的 ~——那个系数是路线近期历史的先验,碰到内容密度不同的单次请求可以差很多。

关键在两个数字,因为 length 截断有两种完全不同的原因:

请求本身 是什么停了回答 提示怎么说
超出预算 大概率是上下文 让你跑 /trim
在预算之内 服务端自己的输出上限 上下文不是原因,“继续”才是

一次连招只提示一次:服务端既然截了一次,同一段里的下一条回答多半同样被截,每条都提示会把对话淹掉; 一条正常结束的回答会结束这一轮。提示是在事件之后一拍才写入的:session/event 的监听器跑在发布该事件的 commit 内部,在那里 append 会被直接拒绝;晚一拍也顺带让回合先收尾。同一行内容还会以 warn 级别写进宿主日志—— 对用户上下文的这种旁观察,也必须在那里看得见。

受保护的内容

用户指令(最后一条消息)尽量不裁;protectHeadNodes(默认 1)保护开头的节点;保留尾部(retainRatio / retainTokens / minTailTokens)逐字保留最近上下文;allowTailTrim 控制最后手段的层级。

兼容性

该装哪个插件版本

这里没有 peer 依赖来强制这条规则,所以只能写在这里、需要人去读:dsh 0.1.5 只能配本插件的 0.1.x。 0.2.0 起直接装最新版。0.1.7 和 0.2.0 差别不大,同一个构建两边都能用。

dsh 装哪个 原因
0.1.2-rc.1 0.1.x devDependency 里钉死的下限
0.1.5-rc.2 / 0.1.5-rc.3 只能用 0.1.x 设置卡片需要 configForms 和 schemastery 的 .volatile(),0.1.5 两样都没有
0.1.7-rc.2 最新版(0.6.x) 到 0.2.0 为止,本插件做的事都没变
0.2.0-rc.2 最新版(0.6.x) 第一条能在这条线上正确保存卡片写入的版本
0.2.1-rc.2 最新版(0.6.x) 已在 0.2.1-rc.2 上核对:本插件依赖的 API 没有变化,两行都能加载,两张卡片都能渲染
0.2.1-rc.5 最新版(0.7.x) 生产在跑的版本;0.2.1 线到此为止
0.2.2-rc.1 最新版(0.7.x) 已在 0.2.2-rc.1 上核对:整套测试通过、两行都能装载、卡片能渲染并能暂存写入。这条线声明 Node >= 24.9——在 22.23 上能启动,但上游不支持该运行时

0.1.5 被单独划出来而不是"降级可用":它早于卡片契约的两半。它的 web 宿主不提供 configForms 服务,没有表单可渲染、 也就无处可存;它的 schemastery 早于 .volatile(),而那是把字段放上卡片的唯一条件。插件在那里仍然能加载、/trim 仍然能用——客户端半边会检测到缺失的服务然后什么都不注册,而不是在页面里抛错——所以失败形态是"卡片悄悄不出现", 而不是启动报错。这是最不该让人去猜的一种失败,所以写在这里。

0.2.0 线上真正变化的是保存路径。0.1.7 时代的构建会把布尔值按字符串 "true" 暂存,.volatile() 过去会放行; 0.2.0 按 schema 校验这次操作并带内拒绝——没有 HTTP 错误,console 也没有输出。0.5.0 修好了,它写的是正确类型的值。 所以在拆分两行和改名之前,0.2.0 就已经需要 0.5.0 以上了。

session format v4 下的标记来源。 替换消息携带来源 kind plugin:dsh-command-context-trim——v4 要求的 plugin:<plugin id> 形状——因为 0.1.7 的准入路径会拒绝已退休的 {kind: 'plugin'} 包装,报 format v4 message requires a producer-owned source kind。

设置卡片

Plugins 页面上的卡片显示的是生效值,而不是"是否覆盖":部署没设过的字段会显示插件真正会用到的默认值——因为一片空白 的控件正是"我的新模型为什么还没调优"变成无解问题的原因。卡片分两个分区:压缩(触发阈值、摘要路由、两个自动调优 开关)与裁剪(工具结果裁剪阈值),而裁剪阈值是"选值下拉 + 数值框":只有选 Custom 时数值框才出现。

选值 落到设置面的值
Disabled 0(不动 pruner)
Auto auto(按路由窗口推导)
Custom 你填进数值框的字符数

运行时自动调优压缩阈值 上以粗体写着唯一要紧的前提:仅限 headless profile——web profile 需使用 /context-tune preset 命令来调优 (web 里会话 agent 在各自 preset 域内创建,其生命周期事件到不了 host 平面)。开关用的是壳子自带的 Switch 原语;选值框是 原生 <select>(原语没有 Select)。

配置

在 profile 补丁的 context-trim 行上覆盖(随包 cordis.patch.yml 列出了完整默认值):

键 默认值 含义
targetRatio 0.9 budget = floor((contextWindow - reserve) * targetRatio),其中 reserve = max(reserveOutputTokens, 路线自己声明的输出额度)
reserveOutputTokens 8192 留给模型自己回复的输出空间。这只是下限:路线自己的输出额度(请求里的 maxTokens,或适配器的 defaultMaxTokens)会在它之上被全额预留,因为服务端会拒绝“提示词 + 额度”超出窗口的请求:一个 32k 的服务若 maxTokens: 16384,即使提示词都装得下,提示词 + 输出也会耗尽窗口
retainRatio / retainTokens 0.16 /— 逐字保留的最近尾部(两种形式互斥)
minTailTokens 2048 该尾部的绝对下限
protectHeadNodes 1 永不裁剪的开头节点数
allowTailTrim true 启用层级 2–3(伸进保留尾部;最后手段可含末条消息)。false 表示只做层级 1,保留尾部成为硬边界
markerSlackTokens 64 加在计价标记上的余量,保证裁剪后的请求仍在预算内
autoTrim true 在 CONTEXT_WINDOW_EXCEEDED 时自动裁剪;绝不在普通压缩时触发
maxAutoTrimRetries 3 每次溢出允许的自动裁剪次数,之后交给压缩
autoTrimShrink 0.5 重复溢出后,按被拒请求的这个比例重新取预算目标(声明窗口有误时的几何下降)
preferInPlacePrune true 规划任何区间之前,先就地瘦身过大的工具结果;能用到官方 pruner 时就用它
compactionTargetRatio 0.8 /context-tune preset 写进 preset 的触发比例(只塑造 preset,从不影响本插件自己的裁剪)
compactionRoute 未设置 生成 preset 的摘要调用所用的可选 {provider, model}
reasoningBudget 0(DSH_TRIM_REASONING_BUDGET) 为思考/推理模型在 headroom 中预留的 token 数。取 headroomTokens = max(reasoningBudget, ratioHeadroom),确保触发压缩前留足思考空间
prunerThresholdChars auto(DSH_TRIM_PRUNER) 工具结果裁剪阈值。auto 按路由派生为 max(8192, min(32768, 2 × (contextWindow − maxTokens)))(各路由取最小),小窗口下一次整文件读取因此不会被裁掉(DSH 的 stock 值是 8192)。整数覆盖它;0 表示退出、保持不动。与 compaction 行同一平面,因此同样的可达性规则适用——web profile 把 pruner 放在每个会话的 preset 里,插件会报告这一点而不是写入。小窗口上这是最关键的杠杆;压力触发已启用时它会放大提示词,那里要三思
autoTuneCompaction false 重新调优本进程的 compaction 行(仅在 compaction 位于 profile 平面时)。web 或生产 profile 应该设置这一项(通过设置卡片或补丁层);覆盖它的 DSH_TRIM_AUTO_TUNE 环境变量只用于自动化/CI
pruneThresholdChars / pruneHeadChars / pruneTailChars 8192 / 4096 / 1024 就地瘦身的预算,镜像 DSH 自己的 pruner 默认值

环境变量(供自动化/CI 覆盖对应配置项):DSH_TRIM_AUTO_TUNE、DSH_TRIM_PRUNER、DSH_TRIM_REASONING_BUDGET。

权限与失败边界

插件触碰了什么,写在这里以免审阅者靠猜:

  • 只写两条会话事件(替换消息 + 测量),不调用模型;
  • 读取 profile 补丁、会话记录与 token meter;
  • 读取服务端回报的 usage 以校准分词密度,并把学到的表写到 <profile>/context-trim-calibration.json(原子写;缺失或损坏时忽略);
  • /context-tune preset 与 /context-tune rescue 会写 profile 补丁(写前备份为 <patch>.bak-trim-preset);
  • 自动路径只在 profile 平面可达时写入;不可达时只报告,不静默失败。

边界

  • 它是丢弃内容,不是摘要。 被裁掉的细节从模型视野里消失(仍在日志里)。想要摘要就用 /compact;两者互补 (先 /trim 会让之后的 /compact 更便宜、更可能成功)。
  • 最后一条消息尽量不裁(见 allowTailTrim):保护用户指令优先于塞进预算。
  • /trim 不改变 preset,preset 也不能在会话中途更换——要新参数就 fork 或新开会话。

调优压缩触发点(/context-tune preset)

DSH 依据 thresholdTokens = min(contextWindow × thresholdRatio, messageBudget − headroomTokens) 决定何时压缩, headroomTokens 默认 65536。在约 370k 以下的任何窗口上,决定触发点的是这个默认值而不是比例:131072 的路由在 37.5 % 就压缩,而不是 80 %。单靠比例改不动它,而 compaction 的策略是在 preset isolate realm 里组合时读取的, 插件无法在运行时改动它。因此 /context-tune preset 写的是一个 preset:

# >>> dsh-command-context-trim: preset-standard (generated; delete this block to drop the preset) >>>
- id: preset-standard
  name: '@deepseek-ai/dsh-agent-preset'
  config:
    id: standard
    plugins:
      - id: compaction-basic
        name: '@deepseek-ai/dsh-compaction-basic'
        config:
          thresholdRatio: 0.8
          headroomTokens: 0
          modelPolicies:
            - provider: b70-sycl
              model: /models/q.gguf
              thresholdRatio: 0.8
              headroomTokens: 0
# <<< dsh-command-context-trim: preset-standard <<<

inplace 写的是裸覆盖行(- id: preset-<base> + 完整 config:):补丁层按 id 整块替换该行的 config, 所以它顶掉随包 preset 的插件清单,新会话继续用同一个 preset id、不需要任何人去挑。代价:随包那份每次升级都会 被覆盖,而这一行会遮蔽它,直到你删掉这段标记块。

运行时重新调优(/context-tune tune)

在 compaction 位于 profile 平面的地方——任何基于 dsh-base 的组合,即 headless 与 tui——它的阈值就是某一行 的普通 config,cordis 通过重启 fiber 来应用 config 变更(Fiber.update() 解析新配置并调用 restart(),即 dispose 加一次全新 apply)。所以 /context-tune tune 是有效的:它改的是那一行。web profile 里 compaction 在会话的 preset 域内, host 平面碰不到它——插件会报告这一点(/context-tune preset 才是那里的答案)。

自动化调优阈值(headless 运行)

headless profile 自己组合 compaction——它的树在 profile 平面上带 compaction-basic、command-compact 与 tool-result-pruner,而且它从不解析会话 preset(只有 session API、web 客户端与 agent-preset 行会)。 实测(干净 DSH_HOME):在路由上声明 contextWindow 并设 DSH_TRIM_AUTO_TUNE=1 后,该行的 thresholdRatio/headroomTokens 与 pruner 的 thresholdChars 都会被写成派生值,且带 context-trim/tuned 记录 可审计。web 侧对应的是手动流程(见该用哪条路线)。

读会话日志

compaction/prune 有两个生产者,只有一个是本插件:本插件在就地瘦身时写入自己的记录,DSH 官方的 tool-result-pruner 也写同名事件。区分办法是看事件的来源与伴随字段;本插件还会写 context-trim/tuned 记录, 里面带有它算出的 thresholdChars(这也是我们验证 Bonsai 2 那次"17 → 2"的依据)。

开发

它放在 fixtures/ 而不是 test/ 下是有意的:node --test 会执行 test/ 下的每个 JavaScript 文件,把服务器放在那里 会让测试挂住。

端到端溢出检查(不需要模型)

fixtures/mock-overflow-server.mjs 是一个有状态的 OpenAI 兼容端点:它强制一个比告诉 harness 的 contextWindow 更低的真实上限,并且对前 TOOL_STEPS 个请求回以工具调用,于是一个 turn 会不断循环、越过真实上限——这就是 上下文墙,且不需要切换模型。

前端卡片开发工作流(src/client/ → lib/client.js)

设置页面的前端卡片源码按模块维护在 src/client/ 目录下(包含常量、i18n 多语言、辅助函数、表单控制器、卡片组件及生命周期注入)。

切勿直接修改 lib/client.js。修改前端代码后,需运行:

npm run build:client

测试套件(test/client-bundle.test.js)会在 npm test 中对 lib/client.js 与 src/client/ 组装产物进行逐字节一致性校验,任何未构建的改动或直接修改打包产物的行为都会导致测试失败。

验证状态

见英文 README.md 的 Verification status 表(200 个测试、隔离实例验证、0.3.9–0.4.4 的各项证据,以及 Bonsai 2 headless 的前后对比:thresholdChars: 32768、compaction/prune 17 → 2)。中文版不重复该表以免两处漂移; test/docs-sync.test.js 会检查本节仍然指向它。

分词器校准这一项的证据也在那张表里:生产会话上实测的各路线系数(1.013–1.324)、17 个单元测试、8 个跑在真实 dsh-token-meter 上的集成测试,以及隔离 dsh 0.2.0-rc.2 里对 mock 服务端(分词密度是 dsh 假设值两倍)的端到端验证—— 同一个会话、同一个窗口,学到因子前后 /trim 给出的是相反的判断。

0.7.2 起还有两项新证据在表里:输出预留(预算会预留路线自己的输出额度,4 个测试)和截断提示(length 截断的成因 分得清、只提示不裁剪,7 个测试,其中一个跑在真实的 SessionStore commit 边界上)。

许可证

MIT


计算细节

本插件算出的每个数字,以及它从哪个默认值出发。token↔字符换算用 DSH 自己的 CHARS_PER_TOKEN = 4 (@deepseek-ai/dsh-token-meter)。

1. 裁剪预算(/trim 把请求面塞进多少)

allowance = max(route.defaultMaxTokens,        # 路线自己声明的输出额度
                the logged header's maxTokens) # 本次会话实际请求的额度
reserve  = max(reserveOutputTokens, allowance) # reserveOutputTokens: 8192,是下限
usable   = contextWindow − reserve
budget   = max(1, floor(usable × targetRatio)) # targetRatio: 0.9
retain   = max(minTailTokens,                           # minTailTokens: 2048
              floor(contextWindow × retainRatio))      # retainRatio: 0.16

预留的是路线全部的输出额度,而不是猜出来的:请求加上它可能生成的输出必须装得进窗口,否则服务端直接拒绝 (context window exceeds limit);推理模型更是在写出正文之前就把这段额度花掉了。

2. 规划器在比较什么

surfaceTokens  = Σ node.heuristicTokens                       # token meter 给每个请求面节点的定价
envelopeTokens = measurement.totalTokens − measurement.surfaceTokens   # 工具 schema 等固定请求数据
totalTokens    = envelopeTokens + surfaceTokens

3. 压缩触发点(自动调优与 /context-tune preset 写入的值)

镜像 @deepseek-ai/dsh-compaction-basic 的 resolveCompactSpec(按 dsh 0.1.7-rc.2 读取):

reservedCompletion = 该路由请求的 maxTokens      # 输出预留,从 request/header 读
messageBudget      = contextWindow − reservedCompletion
headroom           = headroomTokens             # stock 65536;我们写 0
pressureBudget     = messageBudget − headroom
thresholdTokens    = floor(min(contextWindow × thresholdRatio, pressureBudget))

4. 工具结果裁剪阈值(0.3.5 起由自动调优派生)

prunerThresholdChars = max(8192, min(32768, 2 × (contextWindow − maxTokens)))

即一条工具结果最多可占该路由消息预算的一半,上限 32 KB、下限为 DSH 的 stock 8192。各路由取最小,因此 最严格的那条说了算。

5. 样例

路由 stock 触发点 调优后
Bonsai 40960 / 8192 无(32384 ≤ 65536,无主动触发) 32768(80 %)
Bonsai 40960 / 16384 无(24576 ≤ 65536,无主动触发) 24576(60 %)
131072 / 16384 49152(37.5 %) 104857(80 %)
1000000 / 256000 678464(67.8 %) 744000(74.4 %)

前两行以前会被跳过、保持 stock,现在是照常调优:没有主动触发点意味着只有真的撞墙才压缩,而那不是罕见情况而是 系统性缺口——没有任何预定时刻,任务能不能恢复取决于它自己的上下文恰好落在哪里。「少压缩」因此不是省事:一次 209–372 秒的等待是有界的代价,任务卡住不是。

6. 自动裁剪

autoTrim: true 通过缩小预算来重试失败的请求: nextCeiling = max(1, floor(failingTotal × (1 − autoTrimShrink))),autoTrimShrink: 0.5,最多 maxAutoTrimRetries: 3 次,之后放弃并报告它测到的东西。

failingTotal 是刚刚被拒那次请求的真实大小——meter 的估算值乘上该路线的校准因子。若拿估算值算上限, 得到的就是一个服务端根本没见过的数字,梯度会一直瞄准一个仍然超出真实窗口的目标。

7. 校准因子

realPrompt = usage.inputTokens + usage.cacheReadTokens + usage.cacheWriteTokens
estPrompt  = 该 assistant 消息之前的请求面  +  estimateEnvelopeTokens(header)
factor     = clamp(p90(各次 realPrompt / estPrompt 的样本), ≥ 1.0)      # 按 provider:model 路线
  • 样本:每次完成的请求一条,按路线各留最近 50 条。
  • 门槛:3 个样本,否则因子为 1。
  • p90,不是均值:一串日志很重的请求会推动因子,单个不会。
  • 永远不低于 1.0:算多了不是丢上下文的理由。
  • 封装是工具 schema 自己的价格:ceil(JSON.stringify(header.tools).length / 4) + 4。

因子乘在 meter 给每个节点定的价上,于是规划器的 need(真实)与 freedTokens(真实)是同一个单位, 插件汇报的请求总量就是请求的真实大小。