dsh-context-truth 0.2.0 → 0.3.1

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 CHANGED
@@ -1,5 +1,62 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.3.1
4
+
5
+ * **`handoff_ready` 只在 `handoff` 模式下注册。** `off` / `idle` 下它从工具目录里移除(用
6
+ `tools.register()` 返回的注销 disposer),切回 handoff 时在**下一个请求**重新注册;插件被销毁时
7
+ 也会注销。`off` / `idle` 的工具目录与没有这个能力时完全一致,不再为首轮 prefill 承担一个
8
+ 永远只会拒绝的工具定义。
9
+ * 日志分别记 `handoff_ready registered (fold mode is handoff)` /
10
+ `handoff_ready removed (fold mode is <mode>)`,模式切换在日志里可见。
11
+ * 测试:70(新增“工具跟随实时模式”用例;变异“去掉注销调用”恰好只让它失败,恢复后字节一致)。
12
+
13
+ ## 0.3.0
14
+
15
+ > **新增能力 3 的第二形态:交接式折叠(`foldMode: handoff`,实验性)。** 默认模式改为 `idle`
16
+ > (即本插件此前的空闲边界折叠)。详细的背景、实测与护栏见 README 的「交接式折叠」一节。
17
+
18
+ ### 新增
19
+
20
+ * **`handoff` 折叠模式(实验性)**:读数到达准备点(`handoffAt` × 折叠点,默认 85%)时注入提醒,
21
+ 给出唯一允许的交接档路径(`$DSH_HOME/handoffs/<sessionId>/<fold#>.handoff.md`,绝不进工作区);
22
+ 模型写完档后调用新工具 `handoff_ready` 登记;该轮结束时插件真正调用 `compactNow()`;折叠后
23
+ `followup` **只激活一轮**,第一条指令就是先读档再继续。基线:143 次折叠里 81 次(57%)在折叠后
24
+ 重新读取了自己刚写过的文件,合计 225 次——这个机制针对的就是这部分重复劳动。
25
+ * **设置卡**(`lib/client.js` + `package.json` 的 `dsh.client` / `exports["./client"]`):在插件页
26
+ 注册 `plugins.bundle.config`(key = 包名),渲染“折叠模式”下拉框,读写走
27
+ `settings.describe()` / `settings.mutate()`。DSH 不会按 `Config` schema 自动生成插件设置表单,
28
+ 没有这张卡时只能改 profile patch。
29
+ * 工具 `handoff_ready` 在所有模式下都注册(设置卡需要能随时切换模式),只在 `handoff` 模式下生效。
30
+
31
+ ### 变更
32
+
33
+ * **默认模式改为 `idle`**:没写过 `foldMode` 的配置按 `idle` 解析(它就是此前的行为,当时由
34
+ `foldAtIdle: true` 打开);显式 `foldAtIdle: false` 仍解析为 `off`,不会被这次改默认值带走。
35
+ * **模式切换立即生效**:`foldMode` 是 volatile 配置,设置卡写进运行中的引用,插件每次调用重新解析
36
+ 选项。实测:面板切到 `handoff` 后,运行中的实例在下一次调用就按 handoff 执行(`handoff_ready`
37
+ 直接给出了本会话的交接档路径,而不是“不在 handoff 模式”的拒绝)。切换本身不会触发折叠。
38
+ * README/README-en:更正“不注册工具”“无客户端”“无落盘状态”等已过时的表述,补上工具、设置卡、
39
+ handoff 状态文件与实验性标签。
40
+
41
+ ### 修复(均来自实机演练)
42
+
43
+ * **回收不再删掉激活目标**:准备轮 N+1 发生在激活轮 N 里,旧实现会把 fold N 的交接档当旧档删掉,
44
+ 激活轮第一条 `read` 得到 `FS_NOT_FOUND`(实测时间线:激活 18:39:58.877 → 回收 18:40:03.431 →
45
+ 读档 18:40:04.983)。现在按编号保留当前折叠的档。
46
+ * **提醒不再等人开口**:`agent.inject` 只排进下一次请求;提醒落在模型最后一步时,会话空闲后
47
+ 要等人类发消息才会被读到(实测:18:48:04.482 注入,直到人发消息才出现)。现在轮末若已过准备点
48
+ 且没登记,会用 `followup` 唤醒一轮把提醒送到,次数计入同一份提醒预算。
49
+ * **唤醒轮不再叠第二条提醒**:唤醒时把该轮记为“已提醒”,同一轮后续 step 不再注入。
50
+ * **`handoff prep` 日志的数值**:之前打印的是准备点却写成 “fold point”,现在打印真正的折叠点。
51
+
52
+ ### 验证
53
+
54
+ * `npm run check` 通过;`npm test` **69/69**。
55
+ * 变异测试:去掉“保留当前折叠档”的判定 → 3 条测试失败;把轮末 `followup` 改成 `inject` → 1 条失败;
56
+ 去掉唤醒轮的“已提醒”标记 → 1 条失败;每次恢复后按字节比对一致。
57
+ * 实机:准备提醒 → 写档 → 登记 → 轮末真实折叠(`folded … at the round end via service (fold #1)`)
58
+ → 插件自行激活唯一一轮 → 激活轮首条动作是读档。
59
+
3
60
  ## 0.2.0
4
61
 
5
62
  > **能力 3(空闲边界折叠)能否工作,取决于接缝对插件是否可达——而"可达"取决于挂载组合,不是
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 · 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
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`) · 1 tool in handoff mode (`handoff_ready`) · 1 client settings card · no build step · MIT
8
8
 
9
9
  ---
10
10
 
@@ -69,7 +69,7 @@ The call is identified by the `purpose: 'compaction'` tag its caller sets. When
69
69
 
70
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
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)
72
+ ### 3. Fold at the turn boundary: `idle` (default) / `handoff` (experimental)
73
73
 
74
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
75
 
@@ -79,9 +79,30 @@ instructions unable to finish the same task
79
79
  the reading parked at "Under 10K tokens of headroom remain"
80
80
  ```
81
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**.
82
+ `foldMode` decides what this plugin does at the model's **own turn boundary** (`agent/status === 'idle'`):
83
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).
84
+ | Mode | Behaviour |
85
+ |---|---|
86
+ | `off` | Report only, never fold. Use it to leave folding entirely to the host's pressure trigger. |
87
+ | `idle` | **Default.** 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**. |
88
+ | `handoff` | **Experimental.** The model writes a handoff note first, then the fold runs, then exactly one turn is activated to read that note back. See below. |
89
+
90
+ > Compatibility: a config that never set `foldMode` resolves to `idle` (that is the behaviour this plugin always had, behind `foldAtIdle: true`); a config that explicitly set `foldAtIdle: false` still resolves to `off` and is not dragged along by the new default. An explicit `foldMode` always wins.
91
+
92
+ #### Handoff folding (`handoff`, experimental)
93
+
94
+ What actually costs a long task is not the summary but **the repeated work after the fold**: the model cannot know when it will be folded, then rebuilds its picture from the summary and redoes what it already did. Baseline (143 folds): **81 folds (57%) were followed by the model re-reading a file it had just written, 225 occurrences**.
95
+
96
+ The chain is:
97
+
98
+ 1. At the **prep point** (`handoffAt` × the fold point, 85% by default) the plugin injects a reminder naming the **one** allowed note path (`$DSH_HOME/handoffs/<sessionId>/<fold#>.handoff.md`, never the workspace);
99
+ 2. the model writes everything the post-fold self needs (goal, settled decisions, evidence, next action, dead ends) and calls `handoff_ready`;
100
+ 3. at the end of that round the plugin calls `compactNow()`;
101
+ 4. after the fold it uses `followup` to activate **exactly one** turn whose first instruction is to read that note before touching the task.
102
+
103
+ Guards: at most 3 reminders per cycle; if a round ends past the prep point with no note registered, the plugin **wakes** a round with `followup` to deliver the reminder (`agent.inject` only queues for the next request, so a reminder that lands on the model's last step would otherwise wait for a human — measured, and that is why the wake exists); notes are temporary, recycled when the next handoff is created with a 7-day sweep; a registered note whose fold did not happen is kept and never activates a turn.
104
+
105
+ **Switching modes takes effect immediately, with no restart**: `foldMode` is volatile config, the settings card writes straight into the running reference, and the plugin resolves its options per use (verified live: after the panel switched to `handoff`, the running instance acted on it on its next call). Switching does **not** trigger a fold by itself — the fold still waits for the reading to reach the point.
85
106
 
86
107
  ## Data sources (all host-measured — nothing is estimated)
87
108
 
@@ -145,7 +166,11 @@ Capability 3 resolves its engine itself, at fold time, through a **ranked candid
145
166
  | `logBandChanges` | `true` | Log one `ctx.logger.info` per band change |
146
167
  | `patchCompactionPrompt` | `true` | Whether to extend the compaction directive |
147
168
  | `compactionRules` | see above | Rule array; `[]` disables capability 2 |
148
- | `foldAtIdle` | `false` | Enable capability 3 (fold at the idle boundary) |
169
+ | `foldMode` | `idle` | Turn-boundary fold mode: `off` / `idle` (default) / `handoff` (experimental). The settings card writes this key and the change is live |
170
+ | `handoffAt` | `0.85` | Prep point for the handoff reminder, as a fraction of the **fold point** (not the window) |
171
+ | `handoffDir` | `''` | Note directory; empty means `$DSH_HOME/handoffs`, a relative path also resolves under `$DSH_HOME`, never the workspace |
172
+ | `handoffReminders` | `3` | Reminders per cycle, wake included |
173
+ | `foldAtIdle` | `false` | Legacy switch, equivalent to `foldMode: idle`; an explicit `false` means `off`. Only matters for a config that never set `foldMode` |
149
174
  | `foldAtIdleMarginPercent` | `5` | Fold once the headroom is within this percent of the window (50K on a 1M window) |
150
175
  | `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
176
  | `foldAtIdleCooldownMs` | `60000` | Minimum gap between attempts, so a failure cannot hammer the engine |
@@ -156,15 +181,13 @@ Capability 3 resolves its engine itself, at fold time, through a **ranked candid
156
181
  - id: context-truth # the id the bundle patch declares
157
182
  name: dsh-context-truth
158
183
  config:
159
- foldAtIdle: true
184
+ foldMode: idle # off / idle (default) / handoff (experimental)
160
185
  foldAtIdleMarginPercent: 5
161
186
  ```
162
187
 
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.
188
+ 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 the running config's `foldMode` with no restart (see "Switching modes takes effect immediately" above).
164
189
 
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.
190
+ > **The settings card is not generated — this plugin ships one.** This DSH build does not render a form from a plugin's `Config` schema; the host only wires the *registrations* into plugin pages (`plugins.bundle.config` / `plugins.row.config`). Since 0.3.0 this package carries `lib/client.js` (declared through `dsh.client` and `exports["./client"]`), which registers `plugins.bundle.config` with key `dsh-context-truth` and renders a fold-mode select wired to `settings.describe()` / `settings.mutate()`. It appears in the plugin page's detail view. Without that card the only way to switch is the profile patch above.
168
191
 
169
192
  `enabled` (the master switch) is best left to the on/off toggle on the plugin list — that one does reload the plugin.
170
193
 
@@ -184,19 +207,20 @@ What you get for it: the model stops halting or handing off because it *thinks*
184
207
  * 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).
185
208
  * 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.
186
209
  * **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.
187
- * The plugin registers no tools and does not touch the tool catalog, so it adds nothing to the first-turn prefill.
210
+ * The plugin registers **one tool only in `handoff` mode**: `handoff_ready` (register a handoff note). In `off` / `idle` it is removed from the tool catalog again, so the catalog is exactly what a deployment without this capability has; a switch lands on the **next request** (the plugin reconciles inside `agent/request` through the disposer `tools.register()` returns). Folding itself never goes through a model tool call (the plugin calls `compaction.compactNow()` directly), so in `off` / `idle` modes the model sees neither the tool nor any folding activity.
211
+ * The plugin ships **one client module** (`lib/client.js`, the settings card). It only reads `settings.describe()` and writes `settings.mutate()`; it touches no workspace and makes no network requests.
188
212
 
189
213
  ## Verify
190
214
 
191
215
  ```sh
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
216
+ npm test # 69 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, handoff folding (reminder, registration, round-end fold, single activation, restart recovery, recycling, round-end wake), client card shape
193
217
  ```
194
218
 
195
219
  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)`.
196
220
 
197
221
  ## Uninstall
198
222
 
199
- Remove the row from the profile patch / bundles list; a restart leaves nothing behind — no tools, no client, no state on disk.
223
+ Remove the row from the profile patch / bundles list; a restart leaves nothing behind — with one exception: handoff mode writes notes and a state file under `$DSH_HOME/handoffs/<sessionId>/`, and deleting that directory clears them.
200
224
 
201
225
  ## License
202
226
 
package/README.md CHANGED
@@ -1,10 +1,12 @@
1
1
  # dsh-context-truth
2
2
 
3
+ [![Listed on dsh-plugin.org](https://dsh-plugin.org/badges/listed.svg)](https://dsh-plugin.org/plugins/deepseekv41flash/dsh-context-truth)
4
+
3
5
  [English](README-en.md) · [简体中文](README.md)
4
6
 
5
7
  > 让模型知道自己**真实的**上下文占用——每轮由宿主实测回填,并且不让"上下文快用完了"这句错话被压缩摘要继承下去。
6
8
 
7
- DSH(DeepSeek Harness)插件 · 单一 peer 依赖(宿主自带的 `schemastery`)· 需要宿主服务 `tokenMeter` 与 `compaction`(标准部署的 `dsh-base` 自带)· 零工具 · 免构建 · MIT
9
+ DSH(DeepSeek Harness)插件 · 单一 peer 依赖(宿主自带的 `schemastery`)· 需要宿主服务 `tokenMeter` 与 `compaction`(标准部署的 `dsh-base` 自带)· handoff 模式下 1 个工具(`handoff_ready`)· 1 个客户端设置卡片 · 免构建 · MIT
8
10
 
9
11
  ---
10
12
 
@@ -113,7 +115,7 @@ this in as few commands as possible, then a short answer."。数字它读对了
113
115
  **代价**:指令从 1,802 涨到 2,336 字符,**+534 字符 ≈ +134 token(+0.09%)**;因为只加在
114
116
  缓存前缀**之后**,这 134 token 就是每次折叠唯一新增的全价输入。
115
117
 
116
- ### 3. 空闲边界折叠(可选,**默认关**;触发时按候选链找带 `compactNow` 的实现)
118
+ ### 3. 轮末折叠:`idle`(默认)/ `handoff`(实验性)
117
119
 
118
120
  宿主的自动压缩是一个**"跨过阈值"**触发器,而模型在临近阈值时的行为——合并往返、回避高风险改动、
119
121
  改到一半就提交 WIP——**恰好使读数永远停在阈值下面**。实测一个长会话:
@@ -123,12 +125,40 @@ this in as few commands as possible, then a short answer."。数字它读对了
123
125
  读数长期停在 "Under 10K tokens of headroom remain"
124
126
  ```
125
127
 
126
- 于是每一轮都从"只剩 2~8 步"开始,需要连续迭代的任务(比如调试一个 500+ 行的 harness)永远收敛不了。
127
- 本能力在**模型自己的回合边界**(`agent/status === 'idle'`)折叠一次:读数进入 `foldAtIdleMarginPercent`
128
- (默认窗口的 5%,1M 窗口即 50K)以内时调用官方 `compaction.compactNow()`。官方引擎本来就只允许在
129
- idle 时压缩,所以时机正好。折完余量回到几百 K,条件不再满足 → **一个周期只折一次**。
128
+ `foldMode` 决定本插件在**模型自己的回合边界**(`agent/status === 'idle'`)做什么:
129
+
130
+ | 模式 | 行为 |
131
+ |---|---|
132
+ | `off` | 只报告占用,从不折叠。想完全交给宿主的压力触发时用它。 |
133
+ | `idle` | **默认。** 读数进入 `foldAtIdleMarginPercent`(默认窗口的 5%,1M 窗口即 50K)以内时调用官方 `compaction.compactNow()`。官方引擎本来就只允许在 idle 时压缩,所以时机正好。折完余量回到几百 K,条件不再满足 → **一个周期只折一次**。 |
134
+ | `handoff` | **实验性。** 先让模型写交接档,再折叠,折叠后自动开唯一一轮把档读回来。见下。 |
135
+
136
+ > 兼容性:没写过 `foldMode` 的旧配置按 `idle` 处理(它就是本插件此前的行为,当时由 `foldAtIdle: true` 打开);
137
+ > 显式写过 `foldAtIdle: false` 的配置仍然解析成 `off`,不会被这次改默认值带走。显式 `foldMode` 永远优先。
138
+
139
+ #### 交接式折叠(`handoff`,实验性)
130
140
 
131
- **默认关**:它要花一次摘要调用并重写窗口,这是策略决定,不是遥测。开关就在设置页(见下)。
141
+ 长任务真正贵的不是摘要本身,而是**折叠后的重复劳动**:模型不知道什么时候会被折,折叠后又
142
+ 基于摘要重建画面,于是把上一轮已经做过的事再做一遍。基线测量(143 次折叠):**81 次(57%)
143
+ 折叠后重新读取了自己刚写过的文件,合计 225 次**。
144
+
145
+ 这条链路是:
146
+
147
+ 1. 读数到达**准备点**(`handoffAt` × 折叠点,默认 85%)时,插件往本会话注入一条提醒,给出**唯一**
148
+ 允许的交接档路径(`$DSH_HOME/handoffs/<sessionId>/<fold#>.handoff.md`,绝不写进工作区);
149
+ 2. 模型把"折叠后的自己需要知道的一切"写进这份档(目标、已定案、证据、下一步、走过的死路),
150
+ 然后调用 `handoff_ready` 登记;
151
+ 3. 这一轮结束时插件调用 `compactNow()` 真正折叠;
152
+ 4. 折叠后插件用 `followup` **只自动激活一轮**,第一条指令就是"先读这份档,再从它的下一步继续"。
153
+
154
+ 护栏:提醒每周期最多 3 次;某个回合结束时如果模型还没登记、但已过准备点,插件会用
155
+ `followup` **唤醒**一轮把提醒送到(`agent.inject` 只排进下一次请求,轮次结束时没人再发请求,
156
+ 提醒就会一直等人类开口——实测踩过);交接档是临时文件,下一次交接生成时回收旧的、7 天兜底清理;
157
+ 登记了档但没折成(引擎拒绝、被别的东西先折了)时不会激活,档保留。
158
+
159
+ **切换模式立即生效,不需要重启**:`foldMode` 是 volatile 配置,设置卡直接写进运行中的引用,
160
+ 插件每次调用都重新解析选项(实测:面板切到 `handoff` 后,运行中的实例在下一次调用就按 handoff 执行)。
161
+ 但切换本身**不会触发折叠**——折叠仍要等读数到点。
132
162
 
133
163
  ## 数据来源(都是宿主的真实数字,没有估算)
134
164
 
@@ -196,7 +226,11 @@ dsh plugin --profile web add dsh-context-truth
196
226
  | `logBandChanges` | `true` | 分档变化时写一条 `ctx.logger.info` |
197
227
  | `patchCompactionPrompt` | `true` | 是否给压缩指令补规则 |
198
228
  | `compactionRules` | 见上 | 规则数组;`[]` 关闭本能力 |
199
- | `foldAtIdle` | `false` | 是否启用第 3 个能力(空闲边界折叠) |
229
+ | `foldMode` | `idle` | 轮末折叠模式:`off` / `idle`(默认)/ `handoff`(实验性)。设置卡直接写这个键,切换立即生效 |
230
+ | `handoffAt` | `0.85` | 交接提醒的准备点,作为**折叠点**的比例(不是窗口比例) |
231
+ | `handoffDir` | `''` | 交接档目录;空=`$DSH_HOME/handoffs`,相对路径也落在 `$DSH_HOME` 下,绝不进工作区 |
232
+ | `handoffReminders` | `3` | 每个周期最多提醒几次(含轮末唤醒) |
233
+ | `foldAtIdle` | `false` | 旧开关,等价于 `foldMode: idle`;显式 `false` 等价于 `off`,只对没写过 `foldMode` 的配置生效 |
200
234
  | `foldAtIdleMarginPercent` | `5` | 余量 ≤ 窗口的百分之几时触发(1M 窗口 = 50K) |
201
235
  | `foldAtIdleMethod` | `auto` | 折叠请求通道:`auto`=先走该会话的 `/compact`(realm 视图)再回退到服务候选链;`command`/`service` 强制其一。`service` 是最可预测的一档(本 profile 用它) |
202
236
  | `foldAtIdleCooldownMs` | `60000` | 两次尝试之间的最小间隔(失败也不会反复撞引擎) |
@@ -207,23 +241,21 @@ dsh plugin --profile web add dsh-context-truth
207
241
  - id: context-truth # 与 bundle patch 里的行 id 相同
208
242
  name: dsh-context-truth
209
243
  config:
210
- foldAtIdle: true
244
+ foldMode: idle # off / idle(默认)/ handoff(实验性)
211
245
  foldAtIdleMarginPercent: 5
212
246
  ```
213
247
 
214
248
  改动**立即生效**:宿主的 volatile 机制把新值直接写进运行中的配置引用(`loader._commitVolatile`),
215
249
  不重载插件;插件因此每次使用时才解析选项,而不是挂载时快照。实测:改完 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()` 控件)。宿主不会自动生成它。
250
+ `foldMode` 立刻变成新模式(见上文"切换模式立即生效")。
251
+
252
+ > **设置卡不是自动生成的,但这个插件自己带了一张。** 这个 DSH 版本不会按 `Config` schema 自动生成
253
+ > 插件设置表单:官方插件都是各自客户端包手写的卡片,宿主只负责把 `plugins.bundle.config` /
254
+ > `plugins.row.config` 这些插槽的**注册**接进插件页。本包自 0.3.0 起带 `lib/client.js`
255
+ > (`package.json` 里声明 `dsh.client` + `exports["./client"]`),注册的是
256
+ > `plugins.bundle.config`(key = 包名 `dsh-context-truth`),渲染一个"折叠模式"下拉框,
257
+ > 读写走 `settings.describe()` / `settings.mutate()`。它出现在插件页 dsh-context-truth 的详情里。
258
+ > 没有这张卡时,只能改 profile patch(上面那种写法)。
227
259
 
228
260
  `enabled`(总开关)用**插件列表里的开关**即可——那一个会重载插件。
229
261
 
@@ -251,12 +283,18 @@ runtime-context 快照**字节不变就不会重发**,所以读数按台阶量
251
283
  * **同一作用域挂载两次不会失败**:bundle 装配 + 运行时注入是同一插件的两条装配路径,
252
284
  第二个实例检测到重名后保持静默(只记一条 info),由第一个实例继续服务——不会变成
253
285
  一行 failed 的插件记录。
254
- * 本插件不注册任何工具、不改工具目录,因此不增加首轮 prefill。
286
+ * 本插件**只在 `handoff` 模式下注册 1 个工具**:`handoff_ready`(交接档登记)。
287
+ `off` / `idle` 下它会从工具目录里移除,工具目录与没有这个能力时完全一致;切换在**下一个请求**生效
288
+ (插件在 `agent/request` 里对账,用的是 `tools.register()` 返回的注销 disposer)。
289
+ 折叠本身不经过模型工具调用(插件直接调 `compaction.compactNow()`),所以 `off`/`idle` 模式下
290
+ 模型侧看不到任何折叠活动,也没有这个工具。
291
+ * 本插件带 **1 个客户端模块**(`lib/client.js`,插件页的设置卡)。它只读 `settings.describe()`、
292
+ 写 `settings.mutate()`,不碰工作区、不发网络请求。
255
293
 
256
294
  ## 验证
257
295
 
258
296
  ```sh
259
- npm test # 51 项单测:分档/迟滞/量化/自由窗口/折叠定义/空闲折叠与护栏/配置热更新/schema 默认值一致性/节奏估算/降级/摘要改写/形似请求排除/幂等
297
+ npm test # 69 项单测:分档/迟滞/量化/自由窗口/折叠定义/空闲折叠与护栏/配置热更新/schema 默认值一致性/节奏估算/降级/摘要改写/形似请求排除/幂等/交接式折叠(提醒、登记、轮末折叠、单次激活、重启恢复、回收、轮末唤醒)/客户端设置卡结构
260
298
  ```
261
299
 
262
300
  装好后开一个新会话发一条消息,展开该轮的 runtime context 块应看到
@@ -265,7 +303,8 @@ npm test # 51 项单测:分档/迟滞/量化/自由窗口/折叠定
265
303
 
266
304
  ## 卸载
267
305
 
268
- 从 profile patch / bundles 里删掉那一行即可,重启即净——没有工具、没有客户端、没有落盘状态。
306
+ 从 profile patch / bundles 里删掉那一行即可,重启即净——没有落盘状态(例外:handoff 模式在
307
+ `$DSH_HOME/handoffs/<sessionId>/` 下写交接档和一份状态文件,删掉那个目录即净)。
269
308
 
270
309
  ## License
271
310
 
package/lib/client.js ADDED
@@ -0,0 +1,154 @@
1
+ /**
2
+ * Browser half of dsh-context-truth: the fold-mode panel on the plugin's page.
3
+ *
4
+ * Why this file exists: DSH does not auto-render a plugin's `Config` as a settings
5
+ * form. A plugin row gets a configure panel only when a client module registers a
6
+ * `plugins.bundle.config` (bundle level) or `plugins.row.config` slot key — see
7
+ * `dsh-client-ui-plugin-manager`'s config ledger. `dsh-auto-retry` and the official
8
+ * cot-translation bundle both ship a `./client` module for exactly that reason, so
9
+ * this plugin needs one too, otherwise its 29-field schema is unreachable from the UI.
10
+ *
11
+ * The panel talks to the settings Remote directly:
12
+ * settings.describe() -> { ok, value: { namespaces: [{ ns, revision, value, ... }] } }
13
+ * settings.mutate(ns, ops, expectedRevision)
14
+ * Both are the same calls the built-in settings page makes.
15
+ */
16
+ window.__ModuleLoader__.load({
17
+ id: 'dsh-context-truth',
18
+ factory: (require) => {
19
+ const module = { exports: {} }
20
+ const exports = module.exports
21
+ const React = require('react')
22
+
23
+ const NS = 'context-truth'
24
+ const LABEL = {
25
+ title: '折叠模式 / Fold mode',
26
+ hint:
27
+ '默认 idle:到点后在模型自己的轮次边界折叠。' +
28
+ ' handoff 为实验特性:先写交接档、折叠后自动回读一次。' +
29
+ ' 切换立即生效,不需要重启;但切换本身不会触发折叠。',
30
+ off: 'off — 只报告,不折叠',
31
+ idle: 'idle — 自动闲时压缩(默认)',
32
+ handoff: 'handoff — 交接式折叠(实验性)',
33
+ saving: '保存中…',
34
+ saved: '已保存',
35
+ }
36
+
37
+ const messageOf = (error) =>
38
+ error === null || error === undefined ? 'unknown error' : error.message ?? String(error)
39
+
40
+ /** One row: a mode select bound to the `foldMode` field of the live config. */
41
+ function FoldModePanel(props) {
42
+ const [state, setState] = React.useState({ status: 'loading', revision: 0, mode: undefined, note: null })
43
+
44
+ const load = React.useCallback(async () => {
45
+ try {
46
+ const response = await props.settings.describe()
47
+ if (!response.ok) throw new Error(`settings.describe failed: ${messageOf(response.error)}`)
48
+ const view = (response.value.namespaces || []).find((row) => row.ns === NS)
49
+ if (view === undefined) throw new Error(`settings namespace "${NS}" is not served`)
50
+ setState({
51
+ status: 'ready',
52
+ revision: view.revision,
53
+ mode: view.value === undefined ? undefined : view.value.foldMode,
54
+ note: null,
55
+ })
56
+ } catch (error) {
57
+ setState((previous) => ({ ...previous, status: 'error', note: messageOf(error) }))
58
+ }
59
+ }, [props.settings])
60
+
61
+ React.useEffect(() => {
62
+ load()
63
+ }, [load])
64
+
65
+ const choose = React.useCallback(
66
+ async (event) => {
67
+ const value = event.target.value
68
+ setState((previous) => ({ ...previous, status: 'saving', note: LABEL.saving }))
69
+ try {
70
+ const ops = [{ op: 'set', path: ['foldMode'], value }]
71
+ const response = await props.settings.mutate(NS, ops, state.revision)
72
+ if (!response.ok) throw new Error(`settings.mutate failed: ${messageOf(response.error)}`)
73
+ // On success the Remote returns the fresh namespace view, so no second
74
+ // describe() is needed (the built-in form controller relies on the same).
75
+ const view = response.value
76
+ setState({
77
+ status: 'ready',
78
+ revision: view === undefined ? state.revision : view.revision,
79
+ mode: view === undefined || view.value === undefined ? undefined : view.value.foldMode,
80
+ note: LABEL.saved,
81
+ })
82
+ } catch (error) {
83
+ setState((previous) => ({ ...previous, status: 'error', note: messageOf(error) }))
84
+ }
85
+ },
86
+ [props.settings, state.revision],
87
+ )
88
+
89
+ const current = state.mode === undefined ? 'idle' : state.mode
90
+ const busy = state.status === 'saving'
91
+ const note = state.note
92
+ return React.createElement(
93
+ 'div',
94
+ { style: { display: 'flex', flexDirection: 'column', gap: '6px', padding: '4px 0' } },
95
+ React.createElement(
96
+ 'label',
97
+ { style: { display: 'flex', alignItems: 'center', gap: '8px', fontSize: '13px' } },
98
+ React.createElement('span', { style: { fontWeight: 600 } }, LABEL.title),
99
+ React.createElement(
100
+ 'select',
101
+ {
102
+ value: current,
103
+ disabled: busy,
104
+ onChange: choose,
105
+ 'aria-label': LABEL.title,
106
+ style: { minWidth: '220px', padding: '2px 4px' },
107
+ },
108
+ React.createElement('option', { value: 'off' }, LABEL.off),
109
+ React.createElement('option', { value: 'idle' }, LABEL.idle),
110
+ React.createElement('option', { value: 'handoff' }, LABEL.handoff),
111
+ ),
112
+ ),
113
+ React.createElement('span', { style: { fontSize: '12px', opacity: 0.65 } }, LABEL.hint),
114
+ note === null
115
+ ? null
116
+ : React.createElement(
117
+ 'span',
118
+ {
119
+ role: state.status === 'error' ? 'alert' : 'status',
120
+ style: { fontSize: '12px', color: state.status === 'error' ? '#e5534b' : 'inherit', opacity: state.status === 'error' ? 1 : 0.75 },
121
+ },
122
+ note,
123
+ ),
124
+ )
125
+ }
126
+
127
+ /** Client services: slots to register the panel, remote.settings to read/write it. */
128
+ const inject = ['slots', 'remote', 'remote.settings']
129
+
130
+ function apply(ctx) {
131
+ ctx.effect(
132
+ () =>
133
+ ctx.slots.inject('plugins.bundle.config', () =>
134
+ ctx.slots.register(
135
+ {
136
+ name: 'plugins.bundle.config',
137
+ id: 'context-truth-fold',
138
+ // The ledger matches this key against the bundle package name.
139
+ key: 'dsh-context-truth',
140
+ order: 10,
141
+ inject: () => ({ settings: ctx.remote.settings }),
142
+ },
143
+ FoldModePanel,
144
+ ),
145
+ ),
146
+ 'context-truth: fold mode panel',
147
+ )
148
+ }
149
+
150
+ exports.apply = apply
151
+ exports.inject = inject
152
+ return module.exports
153
+ },
154
+ })