dsh-context-truth 0.1.2 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +209 -0
- package/README-en.md +77 -11
- package/README.md +138 -11
- package/lib/index.js +884 -62
- package/package.json +9 -1
- package/test/index.test.js +841 -17
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,214 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.2.0
|
|
4
|
+
|
|
5
|
+
> **能力 3(空闲边界折叠)能否工作,取决于接缝对插件是否可达——而"可达"取决于挂载组合,不是
|
|
6
|
+
> "官方 vs 第三方"。**(这一节先后写错过两次,以下是 2026-10-12 的实测版。)
|
|
7
|
+
>
|
|
8
|
+
> 最终设计的三条,都是实测逼出来的:
|
|
9
|
+
> 1. **`inject` 只声明 `['systemPrompt','tokenMeter']`。** 声明 `compaction` 会让条目**永久
|
|
10
|
+
> pending**——插件完全不加载,第 1 个能力的占用行也一起消失。已向上游报告
|
|
11
|
+
> [deepseek-harness#9425](https://github.com/deepseek-ai/deepseek-harness/discussions/9425)。
|
|
12
|
+
> 2. **服务按候选链解析,不用 `ctx.get`**:`agent.ctx` → `ctx` → 已接线服务,取第一个**真的带
|
|
13
|
+
> `compactNow`** 的(不是"第一个不是 undefined 的"——对一个本 fiber 没有的服务做属性读取会返回
|
|
14
|
+
> **诊断字符串**,早期版本把那个字符串当成"找到了",于是引擎一直可达、折叠却永不触发)。
|
|
15
|
+
> 3. **启动那行诊断只反映插件自身 ctx 的可见性**,不能用来判断折叠能否工作:本 profile 现在打印的
|
|
16
|
+
> 正是 `compaction=undefined/none`,而折叠在 2026-10-12 成功跑了两次。
|
|
17
|
+
>
|
|
18
|
+
> 实测(本 profile:`dsh-dcp` **禁用**,profile patch 末尾重新启用官方
|
|
19
|
+
> `@deepseek-ai/dsh-compaction-basic`):
|
|
20
|
+
> - 2026-10-12 **16:07** 与 **21:46** 两次**自动**空闲折叠均成功,日志为
|
|
21
|
+
> `folded at idle via service (headroom=46558 margin=50000)` / `(headroom=43789 …)`;触发都落在
|
|
22
|
+
> 回合边界上(`turn/end` 之后 13–30 毫秒),占用分别从 631K / 634K 降到 178K / 205K。
|
|
23
|
+
> - 服务通道解析到的就是官方引擎,**它会真的调用 LLM 摘要**:21:46 那次用量为输入 600 +
|
|
24
|
+
> 缓存命中 633,600 + 输出 3,743(命中 **99.9%**,折叠区域 432,321 token,墙钟 21 秒)。
|
|
25
|
+
> - 因此 dcp 时代的结论("官方不可达、只有 dcp 可达")**作废**:那是在官方后端被 dcp 的 bundle
|
|
26
|
+
> patch 整个禁用的配置下测的——引擎压根没有挂载。
|
|
27
|
+
>
|
|
28
|
+
> **折叠请求有两条通道(`foldAtIdleMethod`)**:
|
|
29
|
+
> 1. **命令通道**:`ctx.commands.execute(agent, '/compact', [], signal)` —— 走**该 agent 的 realm
|
|
30
|
+
> 视图**,因此落到该会话本该用的那个后端上(与人类敲 `/compact` 完全一致),折叠风格与会话自身一致。
|
|
31
|
+
> 2. **服务通道**:候选链里第一个带 `compactNow` 的实现,也是 realm 没注册 `compact` 命令时唯一的
|
|
32
|
+
> 办法。本 profile 显式选 `service`(最可预测),实测可用。
|
|
33
|
+
> 命令通道失败(realm 无该命令、或拒绝)会**自动回退**到服务通道;两者都不通时只记一次说明日志。
|
|
34
|
+
>
|
|
35
|
+
> **与 dsh-dcp 的分工(若你挂它)**:它的轮数触发(`roundInterval`,默认每 50 条 assistant message、
|
|
36
|
+
> 在空闲边界)是**活动驱动**的,本插件是**压力驱动**的(余量进入窗口 5%、在同一个空闲边界执行);
|
|
37
|
+
> 任何一次折叠都会重置它的轮数时钟,所以两者不会互相打转。本 profile 已禁用它,配置与回退配方见
|
|
38
|
+
> profile patch 注释。
|
|
39
|
+
>
|
|
40
|
+
> **dsh-dcp 的"关掉官方后端 + 接管接缝"只作用于它自己所在的那一层**(我们一开始也写错了):
|
|
41
|
+
> 每个 agent preset 里还有一个 `cordis:group` realm,里面**各自挂着一份** `compaction-basic` +
|
|
42
|
+
> `command-compact`。所以同一进程里可能同时存在两个后端——这也正是那个坑的来源:**只关 dcp 而不
|
|
43
|
+
> 重开官方 = 零后端;只开 dcp 而不删重开行 = 双后端同时注册 `compaction`。改它们必须成对。**
|
|
44
|
+
|
|
45
|
+
- **Capability 3: fold at the idle boundary (`foldAtIdle`, off by default).** The host's automatic
|
|
46
|
+
compaction only fires when the meter *crosses* the point, and the behaviour a model adopts as it
|
|
47
|
+
approaches — batching round trips, refusing risky edits, stopping mid-iteration to commit WIP —
|
|
48
|
+
is precisely what keeps the reading below it. Measured on a live session: **four hours with no
|
|
49
|
+
fold, every turn 2–8 steps long, three consecutive "continue" instructions unable to finish the
|
|
50
|
+
same task**, the reading parked at `Under 10K tokens of headroom remain`, and the model declining
|
|
51
|
+
a patch to a 584 KB generator because "I can't verify much in 10K". The fix is not wording (four
|
|
52
|
+
rounds of that changed narration, not the equilibrium): it is *when* the fold happens. This
|
|
53
|
+
capability calls the official `compaction.compactNow()` at the model's own turn boundary
|
|
54
|
+
(`agent/status === 'idle'`) once the headroom is within 5% of the window. The engine only accepts
|
|
55
|
+
that call while the agent is idle, so the timing is the supported one; a fold pushes the headroom
|
|
56
|
+
back into the hundreds of thousands, so it fires **once per cycle**. Failure is logged and
|
|
57
|
+
swallowed, attempts are rate-limited, and a missing compaction service warns exactly once — a
|
|
58
|
+
trigger must never break a turn.
|
|
59
|
+
- **Configuration lives in the profile patch, and applies live.** The plugin exports a Schemastery
|
|
60
|
+
`Config` and the host registers it — the settings service reports `ns=context-truth`,
|
|
61
|
+
`applies=live`, and a `value` carrying the patch's override. But this DSH build has **no generic
|
|
62
|
+
renderer** for a third-party plugin's form: every plugin whose settings page exists (subagent,
|
|
63
|
+
shell, agent-loop, web-search) ships a hand-written card in its own *client* package, and the
|
|
64
|
+
generic `plugins.row.config` slot is registered by nobody. So the switches go where `subagent`'s
|
|
65
|
+
`maxDepth` goes:
|
|
66
|
+
```yaml
|
|
67
|
+
- id: context-truth
|
|
68
|
+
config:
|
|
69
|
+
foldAtIdle: true
|
|
70
|
+
```
|
|
71
|
+
Verified live: editing that row flipped `foldAtIdle` to `true` in the running config with **no
|
|
72
|
+
restart** (`patchReload: live`). Three host details are load-bearing, and the first attempt got all
|
|
73
|
+
three wrong — it rendered no form, then silently disabled capability 2:
|
|
74
|
+
- The settings service builds its form with `volatileForm(schema)`, which keeps only nodes marked
|
|
75
|
+
`.volatile()`. Every field carries the marker now; `enabled` is the deliberate exception, because
|
|
76
|
+
it decides whether the line is registered at all.
|
|
77
|
+
- A volatile change is committed **into the running reference** (`loader._commitVolatile` →
|
|
78
|
+
`updateVolatile`) rather than by reloading the plugin. Options are therefore resolved on every
|
|
79
|
+
use instead of snapshotted in `apply`, the listeners install unconditionally and gate themselves
|
|
80
|
+
per event, and a config value that arrives as a reference cell is unwrapped exactly as the host's
|
|
81
|
+
own adapters do (`plainOptions`). Without that, an edit in the patch would have changed nothing
|
|
82
|
+
until the next restart — a worse failure than a missing form, because it looks like it worked.
|
|
83
|
+
- **A field with no schema default is materialized as `[]`**, and for `compactionRules` `[]` means
|
|
84
|
+
"append nothing" — so adding the schema switched capability 2 off silently until the default was
|
|
85
|
+
given the real rules. A test now pins every schema default against `DEFAULT_OPTIONS`.
|
|
86
|
+
This costs the plugin its zero-dependency claim: `@deepseek-ai/schemastery` is now a declared peer
|
|
87
|
+
dependency (published on npm, and already shipped by every host that runs the plugin).
|
|
88
|
+
- **The idle fold's first live trigger folded nothing: `ctx.get` is not how a service is reached.**
|
|
89
|
+
At 22:44 the trigger itself was correct — inside the 5% margin, at an idle boundary — and the log
|
|
90
|
+
said so: `foldAtIdle is enabled but no compaction service is mounted; not folding`. `ctx.get(name)`
|
|
91
|
+
resolves through `ctx.reflect`, and it returned nothing for `compaction` from this plugin's context.
|
|
92
|
+
The occupancy line had been quietly surviving on the `contextPressure` projection fallback.
|
|
93
|
+
- **The wiring went through three designs; the first two are recorded here because their failure modes
|
|
94
|
+
are the trap.** (1) `ctx.get('compaction')` returned nothing — a service is not reached that way, and
|
|
95
|
+
the occupancy line had been quietly surviving on the `contextPressure` projection fallback. (2)
|
|
96
|
+
`ctx.inject(['compaction'], cb)` never ran its callback, and **declaring `compaction` in `inject`
|
|
97
|
+
left the entry pending forever** — the plugin did not load at all, taking capability 1 with it.
|
|
98
|
+
(3) the shipped design: `inject` stays `['systemPrompt','tokenMeter']`, and the fold resolves the
|
|
99
|
+
service through a **ranked candidate chain** (`agent.ctx` → `ctx` → wired service), taking the first
|
|
100
|
+
candidate that **actually carries `compactNow`** — never "the first that is not undefined", because
|
|
101
|
+
a property read for a service this fiber does not have answers with a **diagnostic string**. Services
|
|
102
|
+
are resolved **per use**, never snapshotted, and a one-line startup diagnostic reports what the
|
|
103
|
+
plugin's own context can see. Measured 2026-10-12: two automatic idle folds resolved the official
|
|
104
|
+
engine through that chain and completed (16:07 and 21:46) while the startup line printed
|
|
105
|
+
`compaction=undefined/none` — so the diagnostic is not a readiness check for capability 3.
|
|
106
|
+
- **Capability 2 rides the seam, byte-for-byte.** Captured on both 2026-10-12 folds: the trailing
|
|
107
|
+
directive on the wire is the patched one — **2,336 characters** (1,802 original + 534 of rules), all
|
|
108
|
+
three rule markers present, and the request lands **19 ms** after `compaction-cache: aligned` logs the
|
|
109
|
+
same call (21:46:08.085 / .104) — two plugins cross-validating each other on the same `llm/stream`
|
|
110
|
+
waterfall. The patched trailing message is **not frozen** (the plugin replaces the array slot, so the
|
|
111
|
+
engine's `deepFreeze` on the appended message does not apply). Cost: **+534 characters ≈ +134 tokens
|
|
112
|
+
(+0.09%)**, appended *after* the cached prefix, so that is the only fresh full-price input a fold adds.
|
|
113
|
+
- Five more tests (49 total): the idle fold's trigger and its guards (running agent, calm session,
|
|
114
|
+
in-flight attempt, missing service, rejected call), the pure decision function it is built on, the
|
|
115
|
+
wiring that delivers the service, a reference cell flipped at runtime to prove a settings change
|
|
116
|
+
lands without a reload, and the schema-default invariant above.
|
|
117
|
+
|
|
118
|
+
## 0.1.4
|
|
119
|
+
|
|
120
|
+
- **The `tight` band stopped talking about compaction, and this is the change that matters most.**
|
|
121
|
+
Three successive wordings were tried in the field: 0.1.3 ordered a hand-off, 0.1.4 described the
|
|
122
|
+
coming fold, and both made the model *narrate* compaction in its own replies and lose momentum —
|
|
123
|
+
worst in the one band that re-injects most often. A live session made it measurable: the tight
|
|
124
|
+
band was committed **333 times**, median gap 45s with runs of 4–20s, so the model read a fresh
|
|
125
|
+
fold notice every step or two. The default (`tightAdvice: 'none'`) now adds **no closing sentence
|
|
126
|
+
at all** — the numbers are the message — `'inform'` restores the 0.1.4 sentence and `'stop'` the
|
|
127
|
+
0.1.3 imperative.
|
|
128
|
+
- **The line says outright that it is telemetry, not a task — and not an allowance to draw down.**
|
|
129
|
+
The closing clause now reads "Background telemetry from the host, and the only authority on
|
|
130
|
+
context pressure: do not mention it, do not estimate or count it down yourself — it is restated
|
|
131
|
+
whenever it changes — and take no action about compaction; the host folds between steps
|
|
132
|
+
automatically." Both halves are evidence-driven. Compaction is host-owned and needs nothing from
|
|
133
|
+
the model, so saying so removes the impulse to plan or announce it — and a live session showed why
|
|
134
|
+
the second half is needed too: the model read the figure correctly, then spent it in its head
|
|
135
|
+
across the following steps (`30K → 28K → 16K → 10K → 7K → 5K`) while the host's number sat still at
|
|
136
|
+
`About 10K` (it is restated only when it changes). Twelve minutes later it announced "Context is
|
|
137
|
+
nearly exhausted (~5K)", a figure the host never reported. A measurement has to be labelled a
|
|
138
|
+
measurement.
|
|
139
|
+
- **The line now also answers "how much context do I have left".** It always printed the headroom to
|
|
140
|
+
the fold and never the free window. A live model answered the first question with the second figure
|
|
141
|
+
and announced "Very low context" at 10K of headroom while **350K of the window was free** — both
|
|
142
|
+
numbers true, only one of them an answer. Every band now carries `About 300K of the window is still
|
|
143
|
+
free`, and **no figure was removed**: dropping the headroom near the fold was considered and
|
|
144
|
+
rejected, because both endpoints (used, and the fold point) stay printed, so the model can subtract
|
|
145
|
+
them anyway — suppressing a derivable number would re-create the original bug's precondition (no
|
|
146
|
+
ground truth) exactly where speculation is most likely. Quantized onto the same display step as
|
|
147
|
+
`used`, so it adds no re-injection of its own; `freeClause: false` removes it.
|
|
148
|
+
- **The small bands now define what the fold is.** The numbers alone left a gap a live session walked
|
|
149
|
+
into: eleven seconds after the line said `Under 10K tokens of headroom remain before it`, the model
|
|
150
|
+
wrote "Very low context. I must do this in as few commands as possible, then a short answer." It had
|
|
151
|
+
read the figure correctly — it took "room before the fold" to mean "context left", while the window
|
|
152
|
+
still held 350K and the fold only reorganizes it. The `tight` band now adds "The fold is routine,
|
|
153
|
+
not the end of the window: older turns become a summary and work continues after it", and `critical`
|
|
154
|
+
the shorter "The window is not exhausted — work continues after the fold." Both are definitions,
|
|
155
|
+
not instructions — nothing to do, nowhere to go — so neither can become the 0.1.3 "hand off" nudge.
|
|
156
|
+
`foldClause: false` removes them.
|
|
157
|
+
- **The remaining-headroom step stays coarse near the point.** It used to shrink to 2K as the room
|
|
158
|
+
ran out — precisely where the line re-injects most — so the figure ticked on nearly every step.
|
|
159
|
+
The floor is now 10% of the window quantum (10K on a 1M window): within a few tens of thousands
|
|
160
|
+
of tokens the pace estimate is the useful signal, and a remainder smaller than one step still
|
|
161
|
+
renders honestly as `Under 10K`. Over a walk from 128K of headroom down to zero the line now
|
|
162
|
+
re-commits **11 times instead of 23**.
|
|
163
|
+
- **The remaining headroom is translated into this session's own pace.** In the `tight` and
|
|
164
|
+
`critical` bands the line reports how many more steps the headroom covers — `At this
|
|
165
|
+
session's recent rate that is roughly 6 more steps.` It is measured, not guessed: the per-step
|
|
166
|
+
growth is the median of recent deltas between step boundaries, taken from the host's own
|
|
167
|
+
`(turn, step)` counter together with the meter reading the line already reports.
|
|
168
|
+
- **A fold re-base discards the pace history instead of poisoning it.** After a compaction the
|
|
169
|
+
meter re-bases (measured in a live session: 200K → under 50K within three seconds); that
|
|
170
|
+
negative delta resets the samples, so the estimate disappears and is re-earned rather than
|
|
171
|
+
averaged against a stale baseline.
|
|
172
|
+
- **Bucketed, rounded down, and settled.** The figure is bucketed onto `1 / 2 / 3 / 5 / 8 / 13 / 20+`
|
|
173
|
+
— the same direction as the headroom itself, so the line never promises more remaining steps than
|
|
174
|
+
the session's own rate supports. The first build of this feature published the rung directly and
|
|
175
|
+
a live session showed why that fails: the raw count ranged 23–38 across consecutive steps,
|
|
176
|
+
straddled a `21 / 34` boundary, and flipped the line four times in 90 seconds — one snapshot
|
|
177
|
+
re-commit caused by nothing but the flip. The top rung is therefore open-ended (`20+`, where the
|
|
178
|
+
exact figure changes no decision), and the rung settles like a band: downward takes effect at once
|
|
179
|
+
(less room is never held back), upward must clear the higher rung by `paceMargin` (0.25) so a
|
|
180
|
+
straddling estimate cannot flip the line while a genuinely slower session still gets the higher
|
|
181
|
+
figure. Replayed against the observed sequence, the rung now renders once instead of five times.
|
|
182
|
+
- **Display-only.** It never moves a band edge, the threshold, or any decision to fold. With
|
|
183
|
+
`paceEstimate: false`, or on a host that exposes no step counter, the published line is
|
|
184
|
+
byte-for-byte what 0.1.3 produced.
|
|
185
|
+
- 42 unit tests (was 28): step-boundary sampling, re-assembly inside one step, fold re-basing,
|
|
186
|
+
median robustness against a 90K tool dump, rung rounding and settling (including a replay of the
|
|
187
|
+
observed flip sequence), the two `tight` wordings, and byte-identity when the pace feature is off.
|
|
188
|
+
|
|
189
|
+
## 0.1.3
|
|
190
|
+
|
|
191
|
+
Four changes, all from capturing a real compaction request in a live session (and from the host
|
|
192
|
+
log line that capture explained):
|
|
193
|
+
|
|
194
|
+
- **A request that merely quotes the directive is no longer mistaken for a compaction call.**
|
|
195
|
+
Detection trusted a substring match on the trailing message, so an ordinary turn whose last tool
|
|
196
|
+
result dumped the engine source or a session log was treated as the summarizer call — one real
|
|
197
|
+
tool result contained 10 marker hits. A caller-set `purpose` is now authoritative, and the
|
|
198
|
+
tagless fallback requires the trailing message to *begin* with the directive.
|
|
199
|
+
- **A look-alike can no longer spend the one-shot failure warning.** In the wild it did: the
|
|
200
|
+
warning fired for an ordinary turn, which would have left a later *real* failure completely
|
|
201
|
+
silent. Only a call tagged `purpose: 'compaction'` may consume the warning now.
|
|
202
|
+
- **A reading below one display step says so instead of rendering `0`.** After a compaction the
|
|
203
|
+
meter reads 30–50K against a 50K step, so the line printed `0 / 1.00M tokens used (0%)` while
|
|
204
|
+
the same line reported ~600K of headroom — an empty window and a nearly full one at once. It now
|
|
205
|
+
prints `under 50K / 1.00M tokens used (under 5%)` (`不足 50K`), and a headroom inside its own
|
|
206
|
+
step prints `Under 2K` rather than `less than 1K`.
|
|
207
|
+
- **Rule 1 forbids quoting, not just asserting.** It now bans recording such claims quoted,
|
|
208
|
+
paraphrased, or listed as an example, and tells the summarizer to drop the wording when an
|
|
209
|
+
earlier checkpoint already carries it. The rule embeds no quotable example phrases of its own.
|
|
210
|
+
- 28 unit tests (was 21), including the real look-alike request shape and the sub-step rendering.
|
|
211
|
+
|
|
3
212
|
## 0.1.2
|
|
4
213
|
|
|
5
214
|
- Maintenance release: identical code and docs to 0.1.0. Published directly because npm staged
|
package/README-en.md
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
> Give the model its **real** context occupancy — measured by the host and re-injected every turn — and stop the false claim "context is nearly exhausted" from surviving compaction.
|
|
6
6
|
|
|
7
|
-
A DSH (DeepSeek Harness) plugin ·
|
|
7
|
+
A DSH (DeepSeek Harness) plugin · one peer dependency (the host's own `schemastery`) · needs the host services `tokenMeter` and `compaction` (both shipped by `dsh-base`) · no tools · no build step · MIT
|
|
8
8
|
|
|
9
9
|
---
|
|
10
10
|
|
|
@@ -21,7 +21,7 @@ Worse, that wrong call **survives compaction**:
|
|
|
21
21
|
|
|
22
22
|
This plugin cuts both ends of that chain.
|
|
23
23
|
|
|
24
|
-
##
|
|
24
|
+
## Three capabilities
|
|
25
25
|
|
|
26
26
|
### 1. Measured occupancy line (on by default)
|
|
27
27
|
|
|
@@ -35,21 +35,54 @@ you work. This host-measured line is the only authority on context pressure; nev
|
|
|
35
35
|
estimate it from the conversation's length.
|
|
36
36
|
```
|
|
37
37
|
|
|
38
|
-
Four bands (`ample` / `moderate` / `tight` / `critical`) keyed to the **auto-compaction point**, with 5% hysteresis. The `ample` band additionally declares that every earlier "context is nearly full" claim — including ones inside compacted checkpoints — is stale.
|
|
38
|
+
Four bands (`ample` / `moderate` / `tight` / `critical`) keyed to the **auto-compaction point**, with 5% hysteresis. The `ample` band additionally declares that every earlier "context is nearly full" claim — including ones inside compacted checkpoints — is stale. A reading that rounds below one display step renders as `under 50K / 1.00M tokens used (under 5%)` — never as a `0` that would contradict the headroom printed on the same line.
|
|
39
|
+
|
|
40
|
+
**Headroom in steps**: the `tight` and `critical` bands translate the remaining headroom into this session's own pace — `At this session's recent rate that is roughly 6 more steps.` It is measured, not guessed: per-step growth is the **median** of the deltas between step boundaries, with the step number taken from the host's own `(turn, step)` counter. One 30K tool dump therefore cannot drag it, and a fold re-base (measured: 200K → under 50K within three seconds) clears the history instead of being averaged against it. The figure is bucketed onto `1 / 2 / 3 / 5 / 8 / 13 / 20+` and rounded **down**, the same direction as the headroom itself. The top rung is open-ended on purpose: in a live session the raw count ranged 23–38 across consecutive steps, straddling the old `21 / 34` boundary and flipping the line four times in 90 seconds — one snapshot re-commit caused by nothing but the flip — while above ~20 steps the exact figure changes no decision. The rung also settles like a band, asymmetrically: **downward at once** (less room is never held back), **upward only past `paceMargin` (25%)** above the higher rung, so a straddling estimate cannot flip the line and a genuinely slower session is never frozen at a low rung. It is display-only: it moves no band edge, threshold, or folding decision — switching it off reproduces the 0.1.3 line exactly.
|
|
41
|
+
|
|
42
|
+
**The `tight` band says nothing by default.** It reports the numbers (used, threshold, remainder, roughly how many steps) and adds **no closing sentence**. Three wordings were tried in the field — 0.1.3 ordered "finish the step, then hand off", 0.1.4 described the coming fold — and both made the model narrate compaction in its own replies and lose momentum, in the band that re-injects most often (measured: 333 commits, median gap 45s, runs of 4–20s). `tightAdvice: 'inform'` restores the 0.1.4 sentence, `'stop'` the 0.1.3 imperative.
|
|
43
|
+
|
|
44
|
+
**The line says outright that it is telemetry — and not an allowance to draw down.** Its closing clause is "Background telemetry from the host, and the only authority on context pressure: do not mention it, do not estimate or count it down yourself — it is restated whenever it changes — and take no action about compaction; the host folds between steps automatically." The second half is as evidence-driven as the first: a live model quoted the figure correctly for a while and then spent it in its head (`30K → 28K → 16K → 10K → 7K → 5K`) while the host's number sat still at `About 10K` (restated only when it changes), and twelve minutes later announced "Context is nearly exhausted (~5K)" — a figure the host never reported.
|
|
45
|
+
|
|
46
|
+
**The line answers "how much context do I have left" too.** It used to print only the headroom to the fold, never the free window — and a live model answered the first question with the second figure, announcing "Very low context" at 10K of headroom while **350K of the window was free**. Both numbers were true; only one was an answer. Every band now carries `About 300K of the window is still free`, and **no figure was removed**: dropping the headroom near the fold was considered and rejected, because both endpoints (used, and the fold point) stay printed, so the model can subtract them anyway — suppressing a derivable number would re-create the original bug's precondition (no ground truth) exactly where speculation is most likely. It shares the `used` display step, so it adds no re-injection of its own; `freeClause: false` removes it.
|
|
47
|
+
|
|
48
|
+
**The two small bands define what the fold is.** Numbers alone left a gap a live model walked into: eleven seconds after the line read `Under 10K tokens of headroom remain before it`, it wrote "Very low context. I must do this in as few commands as possible, then a short answer." It had read the figure correctly and took "room before the fold" for "context left", while the window still held 350K and the fold only replaces older turns with a summary. `tight` therefore carries a **definition** (not an instruction) — "The fold is routine, not the end of the window: older turns become a summary and work continues after it" — and `critical` the short form, "The window is not exhausted — work continues after the fold." Neither contains a task instruction, so neither can regress into the 0.1.3 "wrap up and hand off" nudge. `foldClause: false` removes them.
|
|
49
|
+
|
|
50
|
+
**The headroom step stays coarse near the point.** An earlier build shrank it to 2K as the room ran out — the exact band that re-injects most — so the figure ticked on nearly every step. The floor is now 10% of the window quantum (10K on a 1M window): within a few tens of thousands of tokens the pace estimate is the useful signal, and a remainder smaller than one step still renders honestly as `Under 10K`. Over a walk from 128K of headroom to zero, the line re-commits **11 times instead of 23**.
|
|
39
51
|
|
|
40
52
|
### 2. Compaction directive rules (on by default)
|
|
41
53
|
|
|
42
|
-
The last message of a compaction call
|
|
54
|
+
The last message of a compaction call is the summarizer directive. Through the **public `llm/stream` waterfall** the plugin appends two rules to its tail — tail-only, so the cached prefix stays byte-identical:
|
|
43
55
|
|
|
44
56
|
```
|
|
45
57
|
- Never record the assistant's own statements about its remaining context, token budget, or
|
|
46
|
-
context-window pressure
|
|
47
|
-
|
|
48
|
-
|
|
58
|
+
context-window pressure — not even quoted, paraphrased, or listed as an example, and not
|
|
59
|
+
when an earlier checkpoint already carries one: drop that wording instead of copying it
|
|
60
|
+
forward. Those readings are measured by the host and delivered separately; a model's guess
|
|
61
|
+
about them is not a durable fact.
|
|
49
62
|
- Never record a plan to stop, defer, or hand off work whose only justification was context
|
|
50
63
|
pressure. Record the actual task state instead.
|
|
51
64
|
```
|
|
52
65
|
|
|
66
|
+
The call is identified by the `purpose: 'compaction'` tag its caller sets. When a deployment sets no tag, the fallback requires the trailing message to **begin** with the directive — so a tool result that merely quotes the engine (a source dump, a log excerpt, a grep hit) is never patched by mistake, and can never spend the one-shot failure warning either.
|
|
67
|
+
|
|
68
|
+
**Measured (2026-10-12, two automatic folds in a long session)**: the request carried the **patched** directive — 2,336 characters on the wire (1,802 original + 534 of rules), all three rule markers present, and the request landed on the same seam **19 ms** after `compaction-cache: aligned` logged the same call (21:46:08.085 / 21:46:08.104) — two plugins cross-validating each other. Related confirmation: the patched trailing message is **not frozen**, because the plugin replaces the array slot rather than mutating the frozen object the engine appends.
|
|
69
|
+
|
|
70
|
+
**Cost**: the directive grows from 1,802 to 2,336 characters — **+534 characters ≈ +134 tokens (+0.09%)**. It is appended *after* the cached prefix, so those 134 tokens are the only fresh full-price input a fold adds.
|
|
71
|
+
|
|
72
|
+
### 3. Fold at the idle boundary (optional, **off by default**; when it fires it resolves a `compactNow` provider through a ranked candidate chain)
|
|
73
|
+
|
|
74
|
+
The host's automatic compaction is a *crossing* trigger, and the behaviour a model adopts near the point — batching round trips, avoiding risky edits, stopping mid-iteration to commit WIP — is exactly what keeps the reading below it. Measured on one live session:
|
|
75
|
+
|
|
76
|
+
```
|
|
77
|
+
4 hours with no fold · every turn 2–8 steps long · three consecutive "continue"
|
|
78
|
+
instructions unable to finish the same task
|
|
79
|
+
the reading parked at "Under 10K tokens of headroom remain"
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
Every turn therefore starts with two to eight steps of room, and a task that needs continuous iteration — debugging a 500-line harness, say — never converges. This capability folds once at the model's **own turn boundary** (`agent/status === 'idle'`): when the reading comes within `foldAtIdleMarginPercent` (5% of the window by default — 50K on a 1M window) of the point, it calls the official `compaction.compactNow()`. The official engine only accepts that call while the agent is idle, which is exactly the moment this fires. The fold pushes the headroom back into the hundreds of thousands, so the condition stops holding: **one fold per cycle**.
|
|
83
|
+
|
|
84
|
+
**Off by default**: it spends a summarizer call and rewrites the window, which is a policy decision rather than telemetry. The switch lives on the settings page (below).
|
|
85
|
+
|
|
53
86
|
## Data sources (all host-measured — nothing is estimated)
|
|
54
87
|
|
|
55
88
|
| Item | Source |
|
|
@@ -81,7 +114,11 @@ Or write the row into a profile's own patch layer:
|
|
|
81
114
|
language: en # optional; 'en' (default) or 'zh'
|
|
82
115
|
```
|
|
83
116
|
|
|
84
|
-
The package ships `dsh.bundle.patch`, so listing it in a profile's `dsh.profile.bundles` assembles it too. **No
|
|
117
|
+
The package ships `dsh.bundle.patch`, so listing it in a profile's `dsh.profile.bundles` assembles it too. **No build step**: `lib/index.js` is both the source and the artifact.
|
|
118
|
+
|
|
119
|
+
**Host requirements**: `inject = ['systemPrompt', 'tokenMeter']` — **two**. `compaction` is *deliberately not declared*: declaring it left the entry **pending forever** (the plugin did not load at all, taking capability 1's occupancy line with it). Reported upstream as [#9425](https://github.com/deepseek-ai/deepseek-harness/discussions/9425).
|
|
120
|
+
|
|
121
|
+
Capability 3 resolves its engine itself, at fold time, through a **ranked candidate chain** — `agent.ctx` → `ctx` → wired service — taking the first candidate that **actually carries `compactNow`** (never simply "the first that is not undefined": a property read for a service this fiber does not have answers with a **diagnostic string**, which is a trap this plugin fell into once). So the startup line `compaction=undefined/none` reports **only what the plugin's own context can see — it does not mean folding is unavailable**: this profile prints exactly that, and both automatic folds on 2026-10-12 completed.
|
|
85
122
|
|
|
86
123
|
## Configuration (every key optional)
|
|
87
124
|
|
|
@@ -91,16 +128,45 @@ The package ships `dsh.bundle.patch`, so listing it in a profile's `dsh.profile.
|
|
|
91
128
|
| `language` | `en` | `en` / `zh` wording |
|
|
92
129
|
| `order` | `100` | Placement inside the runtime-context block (sandbox is 110, approval 115 — so it comes first) |
|
|
93
130
|
| `quantumPercent` | `5` | Display step as a percentage of the window; sets the re-injection cadence |
|
|
131
|
+
| `paceEstimate` | `true` | Translate the headroom into this session's pace (`tight` / `critical` bands) |
|
|
132
|
+
| `paceSamples` | `16` | Per-step deltas the median is taken over |
|
|
133
|
+
| `paceMinSamples` | `3` | Samples required before any estimate is shown |
|
|
134
|
+
| `paceMargin` | `0.25` | Margin a higher rung must clear before the line promises more steps |
|
|
94
135
|
| `thresholdRatio` | `0.8` | Mirror of `dsh-compaction-basic` |
|
|
95
136
|
| `headroomTokens` | `65536` | Mirror of `dsh-compaction-basic` |
|
|
96
137
|
| `reservedCompletionTokens` | `null` | `null` reads the routed request's own `maxTokens` |
|
|
97
138
|
| `moderateAt` / `tightAt` | `0.5` / `0.85` | Band edges, as a fraction of the compaction point |
|
|
98
139
|
| `hysteresis` | `0.05` | Margin required before leaving a band downward |
|
|
140
|
+
| `tightAdvice` | `none` | `tight` closing sentence: `none` adds none (default), `inform` states the cost, `stop` keeps the 0.1.3 imperative |
|
|
99
141
|
| `authoritative` | `true` | Append the "this line is the only authority" clause |
|
|
100
142
|
| `staleClaimClause` | `true` | Retire earlier "context is nearly full" claims in the calm band |
|
|
143
|
+
| `foldClause` | `true` | Define what the fold is in the `tight` / `critical` bands |
|
|
144
|
+
| `freeClause` | `true` | Report how much of the window is still unused |
|
|
101
145
|
| `logBandChanges` | `true` | Log one `ctx.logger.info` per band change |
|
|
102
146
|
| `patchCompactionPrompt` | `true` | Whether to extend the compaction directive |
|
|
103
147
|
| `compactionRules` | see above | Rule array; `[]` disables capability 2 |
|
|
148
|
+
| `foldAtIdle` | `false` | Enable capability 3 (fold at the idle boundary) |
|
|
149
|
+
| `foldAtIdleMarginPercent` | `5` | Fold once the headroom is within this percent of the window (50K on a 1M window) |
|
|
150
|
+
| `foldAtIdleMethod` | `auto` | Channel for the request: `auto` runs the session's own `/compact` first (realm view), then falls back to the ranked service chain; `command` / `service` force one. `service` is the most predictable of the two (this profile uses it) |
|
|
151
|
+
| `foldAtIdleCooldownMs` | `60000` | Minimum gap between attempts, so a failure cannot hammer the engine |
|
|
152
|
+
|
|
153
|
+
**Configuration goes in the profile patch** — the same place `subagent`'s `maxDepth` and `bash-terminal`'s `defaultShell` live:
|
|
154
|
+
|
|
155
|
+
```yaml
|
|
156
|
+
- id: context-truth # the id the bundle patch declares
|
|
157
|
+
name: dsh-context-truth
|
|
158
|
+
config:
|
|
159
|
+
foldAtIdle: true
|
|
160
|
+
foldAtIdleMarginPercent: 5
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
A change takes effect **immediately**: the host's volatile mechanism writes the new value straight into the running config reference (`loader._commitVolatile`) instead of reloading the plugin, which is why the plugin resolves its options per use rather than snapshotting them at mount. Verified live: editing that row flipped `foldAtIdle` to `true` in the running config with no restart.
|
|
164
|
+
|
|
165
|
+
> ⚠️ **This DSH build has no "render a form from the schema" mechanism for plugins.** Every plugin whose settings page exists (subagent, bash-terminal/shell, agent-loop, web-search) ships a **hand-written card in its own client package**, registered into the `plugins.item` slot; the generic `plugins.row.config` slot is registered by nobody. Exporting a Schemastery `Config` does make the host register the namespace (measured: `ns=context-truth`, `applies=live`) — but **no UI renders a generic form for a third-party plugin**, so the switches live in the patch.
|
|
166
|
+
>
|
|
167
|
+
> A real settings-page toggle would need a **client card package** for this plugin, modelled on `@deepseek-ai/dsh-client-ui-settings-subagent`: register a `plugins.item` cell and bind a `z.boolean()` control to the settings form. The host will not generate one.
|
|
168
|
+
|
|
169
|
+
`enabled` (the master switch) is best left to the on/off toggle on the plugin list — that one does reload the plugin.
|
|
104
170
|
|
|
105
171
|
## Cost (stated honestly)
|
|
106
172
|
|
|
@@ -114,16 +180,16 @@ What you get for it: the model stops halting or handing off because it *thinks*
|
|
|
114
180
|
|
|
115
181
|
## Compatibility & boundaries
|
|
116
182
|
|
|
117
|
-
* Measured on **dsh 0.2.0-rc.2**; only public seams are used (`systemPrompt.variable/context`, the `llm/stream` waterfall, the `tokenMeter` / `sessionProjections` services) —
|
|
183
|
+
* Measured on **dsh 0.2.0-rc.2**; only public seams are used (`systemPrompt.variable/context`, the `llm/stream` waterfall, the `tokenMeter` / `sessionProjections` services). One exception: the pace estimate reads the host's `agent.phase.{turn, step}` instance field, which is not documented — when it is absent the clause is omitted entirely and the line falls back to what 0.1.3 rendered, never to a guess.
|
|
118
184
|
* If an agent preset sets `includeRuntimeContext: false` (for example `liangshen`), the runtime suppresses **every** runtime-context contribution and capability 1 does not apply (capability 2 is unaffected).
|
|
119
|
-
* If a host froze the request envelope (this version does not), capability 2 logs one warning and skips — it never breaks a model call.
|
|
185
|
+
* If a host froze the request envelope (**this version does not** — verified by capturing a real compaction request), capability 2 logs one warning and skips — it never breaks a model call. That warning is reserved for the engine's own tagged call, so a look-alike request can never silence a later real failure.
|
|
120
186
|
* **Mounting twice in one scope does not fail**: bundle assembly plus a runtime injection are two assembly paths for the same plugin; the second instance detects the taken name, stays silent (one `info` line) and the first keeps serving — it never becomes a failed plugin row.
|
|
121
187
|
* The plugin registers no tools and does not touch the tool catalog, so it adds nothing to the first-turn prefill.
|
|
122
188
|
|
|
123
189
|
## Verify
|
|
124
190
|
|
|
125
191
|
```sh
|
|
126
|
-
npm test #
|
|
192
|
+
npm test # 51 unit tests: banding, hysteresis, quantization, free window, fold definition, idle fold and its guards, live settings changes, schema-default parity, pace estimate, degradation, directive patching, look-alike rejection, idempotence
|
|
127
193
|
```
|
|
128
194
|
|
|
129
195
|
After installing, open a new session and send one message: expanding that turn's runtime context block should show `Context occupancy (host-measured): …`, and the log carries `context-truth: none -> ample (used=… window=1000000 compactionAt=678464)`.
|
package/README.md
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
> 让模型知道自己**真实的**上下文占用——每轮由宿主实测回填,并且不让"上下文快用完了"这句错话被压缩摘要继承下去。
|
|
6
6
|
|
|
7
|
-
DSH(DeepSeek Harness)插件 ·
|
|
7
|
+
DSH(DeepSeek Harness)插件 · 单一 peer 依赖(宿主自带的 `schemastery`)· 需要宿主服务 `tokenMeter` 与 `compaction`(标准部署的 `dsh-base` 自带)· 零工具 · 免构建 · MIT
|
|
8
8
|
|
|
9
9
|
---
|
|
10
10
|
|
|
@@ -22,7 +22,7 @@ DSH(DeepSeek Harness)插件 · 零依赖 · 零工具 · 零 UI · 免构建
|
|
|
22
22
|
|
|
23
23
|
本插件同时掐断这条链的两端。
|
|
24
24
|
|
|
25
|
-
##
|
|
25
|
+
## 三个能力
|
|
26
26
|
|
|
27
27
|
### 1. 实测占用回填(默认开)
|
|
28
28
|
|
|
@@ -38,21 +38,98 @@ estimate it from the conversation's length.
|
|
|
38
38
|
|
|
39
39
|
四档语气(`ample` / `moderate` / `tight` / `critical`)按**自动压缩阈值**的比例分档,
|
|
40
40
|
带 5% 迟滞;`ample` 档额外声明"此前所有'上下文快满了'的说法(含压缩检查点里的)都已作废"。
|
|
41
|
+
读数不足一个显示台阶时渲染为 `under 50K / 1.00M tokens used (under 5%)`——不会渲染成 `0`,
|
|
42
|
+
那会和同一行里的剩余量自相矛盾。
|
|
43
|
+
|
|
44
|
+
**余量还能撑几步**:`tight` / `critical` 档会把这行余量换算成本会话自己的节奏,例如
|
|
45
|
+
`At this session's recent rate that is roughly 6 more steps.`。它是**测出来的**,不是猜的——
|
|
46
|
+
每步增量取"步边界之间读数差"的**中位数**,步号来自宿主自己的 `(turn, step)` 计数器。所以
|
|
47
|
+
一次 30K 的工具结果拖不动它;而压缩折叠会让读数重锚(实测 200K → 不足 50K,3 秒内),
|
|
48
|
+
负增量会**清空历史**、让估算重新累积,绝不与旧基线平均。档位取 `1/2/3/5/8/13/20+` 且**向下取整**
|
|
49
|
+
(与余量本身同方向:绝不承诺比真实节奏更多的步数)。顶部是开放档:实测里原始步数在 23~38 之间
|
|
50
|
+
摆动、正骑在旧的 `21/34` 边界上,90 秒内让这一行翻了 4 次(其中一次快照重发完全由翻档造成),
|
|
51
|
+
而 20 步以上那个精确数字并不改变任何决策。档位另带**单边迟滞**:向下立即生效(少承诺的余量绝不
|
|
52
|
+
拖延),向上要超出该档 25%(`paceMargin`)才改口——骑在边界上的估算翻不动它,真正变慢的会话
|
|
53
|
+
也不会被永久卡住。它纯属展示——不参与分档、阈值或任何折叠判定;关掉它就是 0.1.3 的行文本。
|
|
54
|
+
|
|
55
|
+
**`tight` 档默认什么都不说**:这一档只报数字(已用、阈值、剩余量、约合几步),**不加任何收尾句**。
|
|
56
|
+
这是被实测逼出来的结论——三种措辞试过:0.1.3 命令"收尾、交接",0.1.4 陈述"快折叠了,别让关键状态
|
|
57
|
+
只留在对话里",两者都让模型开始在回复里**反复谈论压缩**并降低工作积极性,而 tight 恰恰是重发最
|
|
58
|
+
频繁的档(实测该档提交 333 次、间隔中位数 45 秒、成串出现 4~20 秒)。`tightAdvice: 'inform'` 可
|
|
59
|
+
恢复 0.1.4 那句,`'stop'` 恢复 0.1.3 的祈使句。
|
|
60
|
+
|
|
61
|
+
**这行会明说自己是遥测——而且不是一笔可以花掉的预算**:收尾句是"本行是宿主的后台遥测……不要提起它、
|
|
62
|
+
不要凭对话长度估计压力、**不要自行倒计时**(读数变化时它会自动重述),也不要对压缩采取任何动作:
|
|
63
|
+
**折叠由宿主在步与步之间自动完成**"。后半句同样是被实测逼出来的:模型前几次还抄得准,之后就自己往下
|
|
64
|
+
减——`30K → 28K → 16K → 10K → 7K → 5K`——而宿主报的数一直停在 `About 10K`(它只在跨档时重述)。
|
|
65
|
+
12 分钟后模型宣布 "Context is nearly exhausted (~5K)",这个数宿主从未报过。
|
|
66
|
+
|
|
67
|
+
**这行同时回答"我还剩多少上下文"**:它原先只印"距折叠点的余量",从没印"窗口还剩多少"。实测里模型
|
|
68
|
+
用前者回答了后者——在余量 `Under 10K` 时写下 "Very low context",而当时**窗口还有 350K 未使用**:
|
|
69
|
+
两个数都是真的,但只有一个回答了它的问题。现在每一档都带 `About 300K of the window is still free`,
|
|
70
|
+
而且**一个数字都没删**:我们认真考虑过在临近折叠时撤掉余量数字,结论是**不能这么做**——两个端点
|
|
71
|
+
(已用量、折叠点)本来就印在行里,模型做一次减法照样能得到,撤掉一个可推导的数字只会在最需要
|
|
72
|
+
真值的时刻重建最初那个 bug 的前提(没有基准 → 凭空猜)。它与"已用"共用同一个显示台阶,因此不带来
|
|
73
|
+
额外重发;`freeClause: false` 可关闭。
|
|
74
|
+
|
|
75
|
+
**余量小的两档会定义"折叠是什么"**:光给数字还留着一个缺口,实测里模型正好踩进去——那一行报出
|
|
76
|
+
`Under 10K tokens of headroom remain before it` 之后 **11 秒**,模型写下 "Very low context. I must do
|
|
77
|
+
this in as few commands as possible, then a short answer."。数字它读对了,但它把"距折叠的余量"理解成
|
|
78
|
+
了"剩下的上下文",而当时窗口还剩 350K、折叠只是把较早的对话换成摘要。所以 `tight` 档补上一句
|
|
79
|
+
**定义**(不是指令):"折叠是例行操作,不是窗口的终点:较早的对话会被折成摘要,之后工作照常继续。"
|
|
80
|
+
`critical` 档用短版:"窗口并未耗尽——折叠之后工作照常继续。" 两句都不含任何动作要求,因此不会退化成
|
|
81
|
+
0.1.3 那种"收尾/交接"的催促。`foldClause: false` 可关闭。
|
|
82
|
+
|
|
83
|
+
**余量档位在临近阈值时保持粗粒度**:早先的实现会在余量变少时把档位缩到 2K,而那正是这一行重发最
|
|
84
|
+
频繁的区间,于是几乎每一步都跳一次。现在档位下限是窗口量子的 10%(1M 窗口即 10K):距阈值只有几
|
|
85
|
+
万 tokens 时,"约合几步"才是有效信号,而小于一档的余量仍会如实渲染成 `Under 10K`。从 128K 余量走
|
|
86
|
+
到 0,这行的重发次数由 **23 次降到 11 次**。
|
|
41
87
|
|
|
42
88
|
### 2. 压缩指令补规则(默认开)
|
|
43
89
|
|
|
44
|
-
|
|
45
|
-
|
|
90
|
+
压缩摘要调用的最后一条消息就是摘要指令。本插件通过**公开的 `llm/stream` 瀑布**在它末尾追加
|
|
91
|
+
两条规则,只改尾巴、不动被缓存的前缀:
|
|
46
92
|
|
|
47
93
|
```
|
|
48
94
|
- Never record the assistant's own statements about its remaining context, token budget, or
|
|
49
|
-
context-window pressure
|
|
50
|
-
|
|
51
|
-
|
|
95
|
+
context-window pressure — not even quoted, paraphrased, or listed as an example, and not
|
|
96
|
+
when an earlier checkpoint already carries one: drop that wording instead of copying it
|
|
97
|
+
forward. Those readings are measured by the host and delivered separately; a model's guess
|
|
98
|
+
about them is not a durable fact.
|
|
52
99
|
- Never record a plan to stop, defer, or hand off work whose only justification was context
|
|
53
100
|
pressure. Record the actual task state instead.
|
|
54
101
|
```
|
|
55
102
|
|
|
103
|
+
识别依据是调用方打的 `purpose: 'compaction'` 标记;部署没有打标记时,兜底判据要求末尾那条
|
|
104
|
+
消息**以指令开头**——所以"只是引用了引擎"的工具结果(源码转储、日志片段、grep 命中)不会被
|
|
105
|
+
误改,也不会吃掉那条一次性失败告警。
|
|
106
|
+
|
|
107
|
+
**实测(2026-10-12,长会话两次自动折叠)**:压缩请求里带上的是**补丁后**的指令,采集到的尾部
|
|
108
|
+
指令 **2,336 字符**(原指令 1,802 + 两条规则 534),三条规则特征串全部命中;同一时刻接缝上
|
|
109
|
+
`compaction-cache: aligned` 那行与本插件的请求相隔 **19 毫秒**(21:46:08.085 / 21:46:08.104),
|
|
110
|
+
两个插件互为交叉验证。附带确认:被追加的那条消息在补丁后**不是冻结对象**——本插件替换的是
|
|
111
|
+
数组槽位(而非改写原对象),所以不受引擎对追加消息的 `deepFreeze` 影响。
|
|
112
|
+
|
|
113
|
+
**代价**:指令从 1,802 涨到 2,336 字符,**+534 字符 ≈ +134 token(+0.09%)**;因为只加在
|
|
114
|
+
缓存前缀**之后**,这 134 token 就是每次折叠唯一新增的全价输入。
|
|
115
|
+
|
|
116
|
+
### 3. 空闲边界折叠(可选,**默认关**;触发时按候选链找带 `compactNow` 的实现)
|
|
117
|
+
|
|
118
|
+
宿主的自动压缩是一个**"跨过阈值"**触发器,而模型在临近阈值时的行为——合并往返、回避高风险改动、
|
|
119
|
+
改到一半就提交 WIP——**恰好使读数永远停在阈值下面**。实测一个长会话:
|
|
120
|
+
|
|
121
|
+
```
|
|
122
|
+
4 小时零折叠 · 每轮只有 2~8 步 · 连续三次"继续"仍无法完成同一个任务
|
|
123
|
+
读数长期停在 "Under 10K tokens of headroom remain"
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
于是每一轮都从"只剩 2~8 步"开始,需要连续迭代的任务(比如调试一个 500+ 行的 harness)永远收敛不了。
|
|
127
|
+
本能力在**模型自己的回合边界**(`agent/status === 'idle'`)折叠一次:读数进入 `foldAtIdleMarginPercent`
|
|
128
|
+
(默认窗口的 5%,1M 窗口即 50K)以内时调用官方 `compaction.compactNow()`。官方引擎本来就只允许在
|
|
129
|
+
idle 时压缩,所以时机正好。折完余量回到几百 K,条件不再满足 → **一个周期只折一次**。
|
|
130
|
+
|
|
131
|
+
**默认关**:它要花一次摘要调用并重写窗口,这是策略决定,不是遥测。开关就在设置页(见下)。
|
|
132
|
+
|
|
56
133
|
## 数据来源(都是宿主的真实数字,没有估算)
|
|
57
134
|
|
|
58
135
|
| 项目 | 来源 |
|
|
@@ -82,7 +159,17 @@ dsh plugin --profile web add dsh-context-truth
|
|
|
82
159
|
```
|
|
83
160
|
|
|
84
161
|
本包带 `dsh.bundle.patch`,作为 bundle 列进 profile 的 `dsh.profile.bundles` 也会自动装配。
|
|
85
|
-
|
|
162
|
+
**不需要构建**:`lib/index.js` 同时是源码和产物。
|
|
163
|
+
|
|
164
|
+
**宿主要求**:`inject = ['systemPrompt', 'tokenMeter']` —— **两个**。`compaction` 是**刻意不声明**的:
|
|
165
|
+
声明它会让条目**永久 pending**(插件完全不加载,第 1 个能力的占用行也一起消失),已向上游报告
|
|
166
|
+
[#9425](https://github.com/deepseek-ai/deepseek-harness/discussions/9425)。
|
|
167
|
+
|
|
168
|
+
第 3 个能力在折叠时自己按**候选链**去找引擎:`agent.ctx` → `ctx` → 已接线服务,取第一个**真的带
|
|
169
|
+
`compactNow`** 的实现(不是"第一个不是 undefined 的"——对一个本 fiber 没有的服务做属性读取会返回
|
|
170
|
+
**诊断字符串**而不是 `undefined`,这是踩过的坑)。所以启动诊断里那行
|
|
171
|
+
`compaction=undefined/none` **只反映插件自身 ctx 的可见性,不代表折叠不可用**:本 profile 现在
|
|
172
|
+
打印的就是 `undefined/none`,而 2026-10-12 的两次自动折叠都成功完成了。
|
|
86
173
|
|
|
87
174
|
## 配置(全部可选)
|
|
88
175
|
|
|
@@ -92,16 +179,53 @@ dsh plugin --profile web add dsh-context-truth
|
|
|
92
179
|
| `language` | `en` | `en` / `zh` 文案语言 |
|
|
93
180
|
| `order` | `100` | 在 runtime-context 里的排序(沙箱 110、审批 115,所以在最前) |
|
|
94
181
|
| `quantumPercent` | `5` | 显示台阶(窗口百分比),决定重发频率 |
|
|
182
|
+
| `paceEstimate` | `true` | 是否把余量换算成本会话节奏(`tight`/`critical` 档) |
|
|
183
|
+
| `paceSamples` | `16` | 节奏取中位数的样本数(近 N 步增量) |
|
|
184
|
+
| `paceMinSamples` | `3` | 少于此样本数不显示估算 |
|
|
185
|
+
| `paceMargin` | `0.25` | 向上换档需超出该档的比例(防抖,且不会卡死) |
|
|
95
186
|
| `thresholdRatio` | `0.8` | 与 `dsh-compaction-basic` 对齐 |
|
|
96
187
|
| `headroomTokens` | `65536` | 同上 |
|
|
97
188
|
| `reservedCompletionTokens` | `null` | 默认读路由请求自身的 `maxTokens` |
|
|
98
189
|
| `moderateAt` / `tightAt` | `0.5` / `0.85` | 分档边界(相对自动压缩点) |
|
|
99
190
|
| `hysteresis` | `0.05` | 降档迟滞 |
|
|
191
|
+
| `tightAdvice` | `none` | `tight` 档收尾句:`none` 不加(默认);`inform` 陈述后果;`stop` 用 0.1.3 的命令式 |
|
|
100
192
|
| `authoritative` | `true` | 是否附加"本行是唯一权威"那句 |
|
|
101
193
|
| `staleClaimClause` | `true` | 是否在 calm 档声明旧说法作废 |
|
|
194
|
+
| `foldClause` | `true` | 是否在 `tight`/`critical` 档定义"折叠是什么" |
|
|
195
|
+
| `freeClause` | `true` | 是否报告"窗口还剩多少未使用" |
|
|
102
196
|
| `logBandChanges` | `true` | 分档变化时写一条 `ctx.logger.info` |
|
|
103
197
|
| `patchCompactionPrompt` | `true` | 是否给压缩指令补规则 |
|
|
104
198
|
| `compactionRules` | 见上 | 规则数组;`[]` 关闭本能力 |
|
|
199
|
+
| `foldAtIdle` | `false` | 是否启用第 3 个能力(空闲边界折叠) |
|
|
200
|
+
| `foldAtIdleMarginPercent` | `5` | 余量 ≤ 窗口的百分之几时触发(1M 窗口 = 50K) |
|
|
201
|
+
| `foldAtIdleMethod` | `auto` | 折叠请求通道:`auto`=先走该会话的 `/compact`(realm 视图)再回退到服务候选链;`command`/`service` 强制其一。`service` 是最可预测的一档(本 profile 用它) |
|
|
202
|
+
| `foldAtIdleCooldownMs` | `60000` | 两次尝试之间的最小间隔(失败也不会反复撞引擎) |
|
|
203
|
+
|
|
204
|
+
**配置写在 profile patch 里**(`subagent` 的 `maxDepth`、`bash-terminal` 的 `defaultShell` 都是这样生效的):
|
|
205
|
+
|
|
206
|
+
```yaml
|
|
207
|
+
- id: context-truth # 与 bundle patch 里的行 id 相同
|
|
208
|
+
name: dsh-context-truth
|
|
209
|
+
config:
|
|
210
|
+
foldAtIdle: true
|
|
211
|
+
foldAtIdleMarginPercent: 5
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
改动**立即生效**:宿主的 volatile 机制把新值直接写进运行中的配置引用(`loader._commitVolatile`),
|
|
215
|
+
不重载插件;插件因此每次使用时才解析选项,而不是挂载时快照。实测:改完 patch 无需重启,运行中的
|
|
216
|
+
`foldAtIdle` 立刻变成 `true`。
|
|
217
|
+
|
|
218
|
+
> ⚠️ **这个 DSH 版本没有"按 schema 自动生成插件设置表单"的机制。** 官方插件(`subagent`、
|
|
219
|
+
> `bash-terminal`/shell、`agent-loop`、`web-search`)的设置界面都是**各自客户端包手写的卡片**
|
|
220
|
+
> (按条目 id 注册进 `plugins.item` 插槽),通用的 `plugins.row.config` 插槽**全应用无人注册**。
|
|
221
|
+
> 插件导出 Schemastery `Config` 会让宿主注册这个命名空间(实测 `ns=context-truth`、`applies=live`),
|
|
222
|
+
> 但**没有任何 UI 会渲染第三方插件的通用表单**——所以开关落在 profile patch 里。
|
|
223
|
+
>
|
|
224
|
+
> 想要一个真正的设置页面开关,就得给插件写一个**客户端卡片包**(照
|
|
225
|
+
> `@deepseek-ai/dsh-client-ui-settings-subagent` 的样子:注册 `plugins.item` 插槽 + 一个绑定
|
|
226
|
+
> settings 表单的 `z.boolean()` 控件)。宿主不会自动生成它。
|
|
227
|
+
|
|
228
|
+
`enabled`(总开关)用**插件列表里的开关**即可——那一个会重载插件。
|
|
105
229
|
|
|
106
230
|
## 代价(照实说)
|
|
107
231
|
|
|
@@ -117,10 +241,13 @@ runtime-context 快照**字节不变就不会重发**,所以读数按台阶量
|
|
|
117
241
|
## 兼容性与边界
|
|
118
242
|
|
|
119
243
|
* 在 **dsh 0.2.0-rc.2** 上实测;只用公开接缝(`systemPrompt.variable/context`、`llm/stream` 瀑布、
|
|
120
|
-
`tokenMeter` / `sessionProjections`
|
|
244
|
+
`tokenMeter` / `sessionProjections` 服务)。唯一例外:节奏估算读宿主的 `agent.phase.{turn,step}`
|
|
245
|
+
实例字段(未文档化)——拿不到时该子句**整段不出现**,行文本退回 0.1.3 的样子,绝不猜一个数。
|
|
121
246
|
* 若某个 agent preset 设置了 `includeRuntimeContext: false`(例如 `liangshen`),运行时会抑制
|
|
122
247
|
**所有** runtime-context 贡献,此时第 1 个能力不生效(第 2 个不受影响)。
|
|
123
|
-
*
|
|
248
|
+
* 若宿主把请求信封冻结(**本版没有**——已通过抓取真实压缩请求验证),第 2 个能力会打一条
|
|
249
|
+
warn 并跳过,绝不阻断模型调用。该告警只为引擎自己打了标记的调用保留,误报的"形似请求"
|
|
250
|
+
不可能吃掉它、让后面真失败变成静默。
|
|
124
251
|
* **同一作用域挂载两次不会失败**:bundle 装配 + 运行时注入是同一插件的两条装配路径,
|
|
125
252
|
第二个实例检测到重名后保持静默(只记一条 info),由第一个实例继续服务——不会变成
|
|
126
253
|
一行 failed 的插件记录。
|
|
@@ -129,7 +256,7 @@ runtime-context 快照**字节不变就不会重发**,所以读数按台阶量
|
|
|
129
256
|
## 验证
|
|
130
257
|
|
|
131
258
|
```sh
|
|
132
|
-
npm test #
|
|
259
|
+
npm test # 51 项单测:分档/迟滞/量化/自由窗口/折叠定义/空闲折叠与护栏/配置热更新/schema 默认值一致性/节奏估算/降级/摘要改写/形似请求排除/幂等
|
|
133
260
|
```
|
|
134
261
|
|
|
135
262
|
装好后开一个新会话发一条消息,展开该轮的 runtime context 块应看到
|