dsh-context-truth

让模型知道自己真实的上下文占用——每轮由宿主实测回填，并且不让"上下文快用完了"这句错话被压缩摘要继承下去。

DSH（DeepSeek Harness）插件 · 单一 peer 依赖（宿主自带的 schemastery）· 需要宿主服务 tokenMeter 与 compaction（标准部署的 dsh-base 自带）· 零工具 · 免构建 · MIT

它解决什么问题

DSH 从不把 token 用量告诉模型。 模型只能靠"这个会话好像很长了"来猜，于是长会话里它会在真实占用 17% 的时候宣布"上下文见底了"，停止写操作、把活儿甩给子代理。

更糟的是这个错判会跨压缩存活：

模型自己写下"我的上下文快用尽了"；
这句话进入压缩摘要（实测某会话摘要原文：- Session budget is nearly exhausted; ...）；
检查点的固定引导语是 "Treat the captured context as established background"；
于是每压缩一次，这个错误信念就被当作既定背景重新注入一次——永远不会因为真实占用回落而被纠正。

本插件同时掐断这条链的两端。

三个能力

1. 实测占用回填（默认开）

一条动态 runtime-context，每轮由宿主自己的 token meter 渲染：

Context occupancy (host-measured): 300K / 1.00M tokens used (30%). Automatic compaction
fires at 678K (68% of the window). About 378K tokens of headroom remain before it.
There is still real headroom — keep going, and keep durable notes or commits current as
you work. This host-measured line is the only authority on context pressure; never
estimate it from the conversation's length.

四档语气（ample / moderate / tight / critical）按自动压缩阈值的比例分档，带 5% 迟滞；ample 档额外声明"此前所有'上下文快满了'的说法（含压缩检查点里的）都已作废"。读数不足一个显示台阶时渲染为 under 50K / 1.00M tokens used (under 5%)——不会渲染成 0，那会和同一行里的剩余量自相矛盾。

余量还能撑几步：tight / critical 档会把这行余量换算成本会话自己的节奏，例如 At this session's recent rate that is roughly 6 more steps.。它是测出来的，不是猜的—— 每步增量取"步边界之间读数差"的中位数，步号来自宿主自己的 (turn, step) 计数器。所以一次 30K 的工具结果拖不动它；而压缩折叠会让读数重锚（实测 200K → 不足 50K，3 秒内），负增量会清空历史、让估算重新累积，绝不与旧基线平均。档位取 1/2/3/5/8/13/20+ 且向下取整 （与余量本身同方向：绝不承诺比真实节奏更多的步数）。顶部是开放档：实测里原始步数在 23~38 之间摆动、正骑在旧的 21/34 边界上，90 秒内让这一行翻了 4 次（其中一次快照重发完全由翻档造成），而 20 步以上那个精确数字并不改变任何决策。档位另带单边迟滞：向下立即生效（少承诺的余量绝不拖延），向上要超出该档 25%（paceMargin）才改口——骑在边界上的估算翻不动它，真正变慢的会话也不会被永久卡住。它纯属展示——不参与分档、阈值或任何折叠判定；关掉它就是 0.1.3 的行文本。

tight 档默认什么都不说：这一档只报数字（已用、阈值、剩余量、约合几步），不加任何收尾句。这是被实测逼出来的结论——三种措辞试过：0.1.3 命令"收尾、交接"，0.1.4 陈述"快折叠了，别让关键状态只留在对话里"，两者都让模型开始在回复里反复谈论压缩并降低工作积极性，而 tight 恰恰是重发最频繁的档（实测该档提交 333 次、间隔中位数 45 秒、成串出现 4~20 秒）。tightAdvice: 'inform' 可恢复 0.1.4 那句，'stop' 恢复 0.1.3 的祈使句。

这行会明说自己是遥测——而且不是一笔可以花掉的预算：收尾句是"本行是宿主的后台遥测……不要提起它、不要凭对话长度估计压力、不要自行倒计时（读数变化时它会自动重述），也不要对压缩采取任何动作： 折叠由宿主在步与步之间自动完成"。后半句同样是被实测逼出来的：模型前几次还抄得准，之后就自己往下减——30K → 28K → 16K → 10K → 7K → 5K——而宿主报的数一直停在 About 10K（它只在跨档时重述）。 12 分钟后模型宣布 "Context is nearly exhausted (~5K)"，这个数宿主从未报过。

这行同时回答"我还剩多少上下文"：它原先只印"距折叠点的余量"，从没印"窗口还剩多少"。实测里模型用前者回答了后者——在余量 Under 10K 时写下 "Very low context"，而当时窗口还有 350K 未使用：两个数都是真的，但只有一个回答了它的问题。现在每一档都带 About 300K of the window is still free，而且一个数字都没删：我们认真考虑过在临近折叠时撤掉余量数字，结论是不能这么做——两个端点（已用量、折叠点）本来就印在行里，模型做一次减法照样能得到，撤掉一个可推导的数字只会在最需要真值的时刻重建最初那个 bug 的前提（没有基准 → 凭空猜）。它与"已用"共用同一个显示台阶，因此不带来额外重发；freeClause: false 可关闭。

余量小的两档会定义"折叠是什么"：光给数字还留着一个缺口，实测里模型正好踩进去——那一行报出 Under 10K tokens of headroom remain before it 之后 11 秒，模型写下 "Very low context. I must do this in as few commands as possible, then a short answer."。数字它读对了，但它把"距折叠的余量"理解成了"剩下的上下文"，而当时窗口还剩 350K、折叠只是把较早的对话换成摘要。所以 tight 档补上一句定义（不是指令）："折叠是例行操作，不是窗口的终点：较早的对话会被折成摘要，之后工作照常继续。" critical 档用短版："窗口并未耗尽——折叠之后工作照常继续。" 两句都不含任何动作要求，因此不会退化成 0.1.3 那种"收尾/交接"的催促。foldClause: false 可关闭。

余量档位在临近阈值时保持粗粒度：早先的实现会在余量变少时把档位缩到 2K，而那正是这一行重发最频繁的区间，于是几乎每一步都跳一次。现在档位下限是窗口量子的 10%（1M 窗口即 10K）：距阈值只有几万 tokens 时，"约合几步"才是有效信号，而小于一档的余量仍会如实渲染成 Under 10K。从 128K 余量走到 0，这行的重发次数由 23 次降到 11 次。

2. 压缩指令补规则（默认开）

压缩摘要调用的最后一条消息就是摘要指令。本插件通过公开的 llm/stream 瀑布在它末尾追加两条规则，只改尾巴、不动被缓存的前缀：

- Never record the assistant's own statements about its remaining context, token budget, or
  context-window pressure — not even quoted, paraphrased, or listed as an example, and not
  when an earlier checkpoint already carries one: drop that wording instead of copying it
  forward. Those readings are measured by the host and delivered separately; a model's guess
  about them is not a durable fact.
- Never record a plan to stop, defer, or hand off work whose only justification was context
  pressure. Record the actual task state instead.

识别依据是调用方打的 purpose: 'compaction' 标记；部署没有打标记时，兜底判据要求末尾那条消息以指令开头——所以"只是引用了引擎"的工具结果（源码转储、日志片段、grep 命中）不会被误改，也不会吃掉那条一次性失败告警。

实测（2026-10-12，长会话两次自动折叠）：压缩请求里带上的是补丁后的指令，采集到的尾部指令 2,336 字符（原指令 1,802 + 两条规则 534），三条规则特征串全部命中；同一时刻接缝上 compaction-cache: aligned 那行与本插件的请求相隔 19 毫秒（21:46:08.085 / 21:46:08.104），两个插件互为交叉验证。附带确认：被追加的那条消息在补丁后不是冻结对象——本插件替换的是数组槽位（而非改写原对象），所以不受引擎对追加消息的 deepFreeze 影响。

代价：指令从 1,802 涨到 2,336 字符，+534 字符 ≈ +134 token（+0.09%）；因为只加在缓存前缀之后，这 134 token 就是每次折叠唯一新增的全价输入。

3. 空闲边界折叠（可选，默认关；触发时按候选链找带 `compactNow` 的实现）

宿主的自动压缩是一个**"跨过阈值"**触发器，而模型在临近阈值时的行为——合并往返、回避高风险改动、改到一半就提交 WIP——恰好使读数永远停在阈值下面。实测一个长会话：

4 小时零折叠 · 每轮只有 2~8 步 · 连续三次"继续"仍无法完成同一个任务
读数长期停在 "Under 10K tokens of headroom remain"

于是每一轮都从"只剩 2~8 步"开始，需要连续迭代的任务（比如调试一个 500+ 行的 harness）永远收敛不了。本能力在模型自己的回合边界（agent/status === 'idle'）折叠一次：读数进入 foldAtIdleMarginPercent （默认窗口的 5%，1M 窗口即 50K）以内时调用官方 compaction.compactNow()。官方引擎本来就只允许在 idle 时压缩，所以时机正好。折完余量回到几百 K，条件不再满足 → 一个周期只折一次。

默认关：它要花一次摘要调用并重写窗口，这是策略决定，不是遥测。开关就在设置页（见下）。

数据来源（都是宿主的真实数字，没有估算）

项目	来源
已用	`tokenMeter.measure(session).totalTokens` —— 宿主对下一次请求的计价，也是自动压缩实际比较的那个数
窗口	`session.requestContext().contextWindow`
兜底	`contextPressure` 投影（provider 上报的 prompt 侧用量）——与 Web UI 那个上下文环同源
自动压缩点	`min(window × thresholdRatio, window − 保留输出 − headroom)`，与 `dsh-compaction-basic` 同式
摘要指令	`llm/stream` 瀑布里 `purpose: 'compaction'` 请求的最后一条消息

安装

# npm
dsh plugin --profile web add dsh-context-truth

或直接写进 profile 的 patch 层：

# <DSH home>/profiles/<profile>/cordis.patch.yml
- insert:
    - id: context-truth
      name: dsh-context-truth
      config:
        language: zh        # 可选：中文文案

本包带 dsh.bundle.patch，作为 bundle 列进 profile 的 dsh.profile.bundles 也会自动装配。 不需要构建：lib/index.js 同时是源码和产物。

宿主要求：inject = ['systemPrompt', 'tokenMeter'] —— 两个。compaction 是刻意不声明的：声明它会让条目永久 pending（插件完全不加载，第 1 个能力的占用行也一起消失），已向上游报告 #9425。

第 3 个能力在折叠时自己按候选链去找引擎：agent.ctx → ctx → 已接线服务，取第一个真的带 compactNow 的实现（不是"第一个不是 undefined 的"——对一个本 fiber 没有的服务做属性读取会返回 诊断字符串而不是 undefined，这是踩过的坑）。所以启动诊断里那行 compaction=undefined/none 只反映插件自身 ctx 的可见性，不代表折叠不可用：本 profile 现在打印的就是 undefined/none，而 2026-10-12 的两次自动折叠都成功完成了。

配置（全部可选）

键	默认	说明
`enabled`	`true`	总开关（只关第 1 个能力）
`language`	`en`	`en` / `zh` 文案语言
`order`	`100`	在 runtime-context 里的排序（沙箱 110、审批 115，所以在最前）
`quantumPercent`	`5`	显示台阶（窗口百分比），决定重发频率
`paceEstimate`	`true`	是否把余量换算成本会话节奏（`tight`/`critical` 档）
`paceSamples`	`16`	节奏取中位数的样本数（近 N 步增量）
`paceMinSamples`	`3`	少于此样本数不显示估算
`paceMargin`	`0.25`	向上换档需超出该档的比例（防抖，且不会卡死）
`thresholdRatio`	`0.8`	与 `dsh-compaction-basic` 对齐
`headroomTokens`	`65536`	同上
`reservedCompletionTokens`	`null`	默认读路由请求自身的 `maxTokens`
`moderateAt` / `tightAt`	`0.5` / `0.85`	分档边界（相对自动压缩点）
`hysteresis`	`0.05`	降档迟滞
`tightAdvice`	`none`	`tight` 档收尾句：`none` 不加（默认）；`inform` 陈述后果；`stop` 用 0.1.3 的命令式
`authoritative`	`true`	是否附加"本行是唯一权威"那句
`staleClaimClause`	`true`	是否在 calm 档声明旧说法作废
`foldClause`	`true`	是否在 `tight`/`critical` 档定义"折叠是什么"
`freeClause`	`true`	是否报告"窗口还剩多少未使用"
`logBandChanges`	`true`	分档变化时写一条 `ctx.logger.info`
`patchCompactionPrompt`	`true`	是否给压缩指令补规则
`compactionRules`	见上	规则数组；`[]` 关闭本能力
`foldAtIdle`	`false`	是否启用第 3 个能力（空闲边界折叠）
`foldAtIdleMarginPercent`	`5`	余量 ≤ 窗口的百分之几时触发（1M 窗口 = 50K）
`foldAtIdleMethod`	`auto`	折叠请求通道：`auto`＝先走该会话的 `/compact`（realm 视图）再回退到服务候选链；`command`／`service` 强制其一。`service` 是最可预测的一档（本 profile 用它）
`foldAtIdleCooldownMs`	`60000`	两次尝试之间的最小间隔（失败也不会反复撞引擎）

配置写在 profile patch 里（subagent 的 maxDepth、bash-terminal 的 defaultShell 都是这样生效的）：

- id: context-truth            # 与 bundle patch 里的行 id 相同
  name: dsh-context-truth
  config:
    foldAtIdle: true
    foldAtIdleMarginPercent: 5

改动立即生效：宿主的 volatile 机制把新值直接写进运行中的配置引用（loader._commitVolatile），不重载插件；插件因此每次使用时才解析选项，而不是挂载时快照。实测：改完 patch 无需重启，运行中的 foldAtIdle 立刻变成 true。

⚠️ 这个 DSH 版本没有"按 schema 自动生成插件设置表单"的机制。 官方插件（subagent、 bash-terminal/shell、agent-loop、web-search）的设置界面都是各自客户端包手写的卡片 （按条目 id 注册进 plugins.item 插槽），通用的 plugins.row.config 插槽全应用无人注册。插件导出 Schemastery Config 会让宿主注册这个命名空间（实测 ns=context-truth、applies=live），但没有任何 UI 会渲染第三方插件的通用表单——所以开关落在 profile patch 里。

想要一个真正的设置页面开关，就得给插件写一个客户端卡片包（照 @deepseek-ai/dsh-client-ui-settings-subagent 的样子：注册 plugins.item 插槽 + 一个绑定 settings 表单的 z.boolean() 控件）。宿主不会自动生成它。

enabled（总开关）用插件列表里的开关即可——那一个会重载插件。

代价（照实说）

runtime-context 快照字节不变就不会重发，所以读数按台阶量化。实测（1M 窗口、678K 压缩点、 quantumPercent: 5）：

一个完整周期（0 → 678K）文字变化 52 次，约每 13K tokens 一次；
单条占用行 ≈ 124 tokens，加上同一条快照里其它 section ≈ 250 tokens；
合计约占该周期预算 < 2%。

换来的是模型不再因为"以为自己快没上下文了"而停手或甩锅。要更省可以调大 quantumPercent。

兼容性与边界

在 dsh 0.2.0-rc.2 上实测；只用公开接缝（systemPrompt.variable/context、llm/stream 瀑布、 tokenMeter / sessionProjections 服务）。唯一例外：节奏估算读宿主的 agent.phase.{turn,step} 实例字段（未文档化）——拿不到时该子句整段不出现，行文本退回 0.1.3 的样子，绝不猜一个数。
若某个 agent preset 设置了 includeRuntimeContext: false（例如 liangshen），运行时会抑制所有 runtime-context 贡献，此时第 1 个能力不生效（第 2 个不受影响）。
若宿主把请求信封冻结（本版没有——已通过抓取真实压缩请求验证），第 2 个能力会打一条 warn 并跳过，绝不阻断模型调用。该告警只为引擎自己打了标记的调用保留，误报的"形似请求" 不可能吃掉它、让后面真失败变成静默。
同一作用域挂载两次不会失败：bundle 装配 + 运行时注入是同一插件的两条装配路径，第二个实例检测到重名后保持静默（只记一条 info），由第一个实例继续服务——不会变成一行 failed 的插件记录。
本插件不注册任何工具、不改工具目录，因此不增加首轮 prefill。

验证

npm test          # 51 项单测：分档/迟滞/量化/自由窗口/折叠定义/空闲折叠与护栏/配置热更新/schema 默认值一致性/节奏估算/降级/摘要改写/形似请求排除/幂等

装好后开一个新会话发一条消息，展开该轮的 runtime context 块应看到 Context occupancy (host-measured): …；日志里会有 context-truth: none -> ample (used=… window=1000000 compactionAt=678464)。

卸载

从 profile patch / bundles 里删掉那一行即可，重启即净——没有工具、没有客户端、没有落盘状态。

License

MIT

dsh-context-truth

Install

README