@elvisw/dsh-magic-context 0.13.0 → 0.14.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/README.md +92 -43
- package/README.zh-CN.md +65 -35
- package/lib/client.js +569 -86
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -41,7 +41,13 @@ a `web` profile). The package ships compiled — install straight from the npm r
|
|
|
41
41
|
dsh plugin --profile web add @elvisw/dsh-magic-context
|
|
42
42
|
```
|
|
43
43
|
|
|
44
|
-
|
|
44
|
+
> Package identity: the unscoped `dsh-magic-context` on npm is an unrelated
|
|
45
|
+
> implementation by another maintainer, not this fork or its upstream. This fork
|
|
46
|
+
> is published only as `@elvisw/dsh-magic-context`; keep the `@elvisw/` scope in
|
|
47
|
+
> every install command.
|
|
48
|
+
|
|
49
|
+
`0.13.0` introduced this package name; the current release is `0.14.0`, which adds the
|
|
50
|
+
top-level Settings page. If you installed
|
|
45
51
|
`@elvisw/dsh-plugin-magic-context` (0.12.x) or the upstream
|
|
46
52
|
`dsh-plugin-magic-context`, remove it first: all three use the same loader row id
|
|
47
53
|
(`magic-context-dsh`), so co-install is unsupported: the loader keeps one row and
|
|
@@ -62,7 +68,8 @@ version hot-loads. In your next session:
|
|
|
62
68
|
|
|
63
69
|
- Tool results carry `§N§` tags; a **telemetry badge** appears in the overlay showing live
|
|
64
70
|
context occupancy, with a panel of live metrics and an operation record behind it.
|
|
65
|
-
- A **
|
|
71
|
+
- A **Settings → Magic Context** page edits the options the card exposes; the same card is still
|
|
72
|
+
available on the GUI Plugins page as the legacy location/fallback.
|
|
66
73
|
- The `ctx_reduce` / `ctx_expand` / `ctx_memory` tools are registered for the agent;
|
|
67
74
|
project memory is **on by default** — facts distilled by the historian persist across
|
|
68
75
|
sessions and surface where the model reads them.
|
|
@@ -98,7 +105,7 @@ last five manage the context window (full design in [Architecture](#architecture
|
|
|
98
105
|
| **Pressure scheduling** | Persistent usage (incl. cache reads/writes) → pressure score → execute/defer decisions (65% threshold, 5 min cache TTL, 85% force band); `CONTEXT_WINDOW_EXCEEDED` triggers emergency reclaim + retry; tiered reduce-guidance nudges |
|
|
99
106
|
| **Historian (out-of-band digest)** | One LLM call replays the real prefix (KV cache preserved) → four-tier p1–p4 summary + facts/events, **writes the store only, never touches the wire**; published in the execute band as a `[compacted §C<n>§]` range replacement; `/ctx-recomp` redoes compacted history in place |
|
|
100
107
|
| **Compaction seam** | `registerCompactionEngine` can take over `ctx.compaction` (real `compaction/start\|summary\|replace\|end` protocol); **off by default** — the host compaction-basic stays in place |
|
|
101
|
-
| **UI integration** | Settings
|
|
108
|
+
| **UI integration** | Top-level **Settings → Magic Context** page plus the legacy Plugins-page card (volatile fields, save = live); catalog-backed Historian reasoning-effort picker; `shell.overlay` telemetry badge + capsule panel (live metrics + operation record); `session-notice` rows in the session stream; Chinese/English instant switching for every card-owned string |
|
|
102
109
|
|
|
103
110
|
## Installation
|
|
104
111
|
|
|
@@ -149,17 +156,20 @@ the profile patch), or `dsh plugin --profile web remove @elvisw/dsh-magic-contex
|
|
|
149
156
|
## Configuration
|
|
150
157
|
|
|
151
158
|
Two ways to change configuration, with different semantics (see the
|
|
152
|
-
[
|
|
153
|
-
|
|
154
|
-
- **GUI settings
|
|
155
|
-
timeout), `historianEnabled`, `registerCompactionEngine`,
|
|
156
|
-
`historian.*` and other volatile fields. The two
|
|
157
|
-
(maintenance verify, historian generation) prefer a
|
|
158
|
-
configured model catalog** (client
|
|
159
|
-
"Auto = follow the session route" and clearing;
|
|
160
|
-
plain text (values remain hand-editable).
|
|
161
|
-
|
|
162
|
-
|
|
159
|
+
[Settings UI contract](docs/dsh-plugin-settings-ui-contract.md)):
|
|
160
|
+
|
|
161
|
+
- **GUI settings page (Settings → Magic Context)**: exposes `policy.*` (incl. historian
|
|
162
|
+
generation cap / ceiling / timeout), `historianEnabled`, `registerCompactionEngine`,
|
|
163
|
+
`journal.*`, `maintenance.*`, `historian.*` and other volatile fields. The two
|
|
164
|
+
provider/model **route pins** (maintenance verify, historian generation) prefer a
|
|
165
|
+
dropdown fed by the **host's configured model catalog** (client
|
|
166
|
+
`remote.session.modelCatalog()`), with "Auto = follow the session route" and clearing;
|
|
167
|
+
shells without that RPC fall back to plain text (values remain hand-editable). The
|
|
168
|
+
Historian reasoning-effort field is the same catalog-backed picker: `Default`, the
|
|
169
|
+
routed model's advertised ids, and `Custom` for legacy/unknown values; an Auto route
|
|
170
|
+
keeps the text input. Writes go through the settings chain: non-volatile keys are
|
|
171
|
+
preserved untouched, untouched fields never materialize into override rows — **saving
|
|
172
|
+
takes effect immediately** (the host side always reads through
|
|
163
173
|
`liveNumber/liveBoolean/liveString/liveRoute` at the decision point).
|
|
164
174
|
- **Hand-written profile override rows**: `config` **replaces** the package patch's config
|
|
165
175
|
wholesale — it is **not** a deep merge. Writing only `memory:` erases
|
|
@@ -188,7 +198,7 @@ writable as profile override rows unless noted):
|
|
|
188
198
|
| Master switches | `enabled` (true) · `registerTools` (true) · `registerStatusCommand` (true) · `sessionNotices` (true) · `reduceGuidance` (true) · `searchHint` (true) | `enabled: false` stays loaded but fully inert; `sessionNotices` controls the management notice rows in the session stream |
|
|
189
199
|
| Compaction seam | `registerCompactionEngine` (code default: mount when resolvable; **ships false in the bundle**) · `compactionBase` (host-injected base class) | Taking over requires disabling compaction-basic too; pre-step `reconcileEngine` mounts/unmounts dynamically every step |
|
|
190
200
|
| Pressure policy | `policy.*`: `executeThreshold` (65) · `forceThreshold` (85) · `ttlMs` (5 min) · `assumedContextWindow` (256k) · `protectedToolResults` (8) · `historianTimeoutMs` (120 s) · `historianMaxTokens` (8192, raised to 8192 if set lower) · `historianMaxTokensCeiling` (32768) · `baselineTokens` (2000) · `memoryBudgetTokens` (8000) · `memoryLimit` (40) · `forceWaitReadyMs` (0) | Thresholds take effect at the next decision point (incl. `/ctx-status` and the compaction-engine paths). `compartmentGuardMode` / `compartmentEntrantTokens` (publish guards) were retired and are no longer configurable |
|
|
191
|
-
| historian | `historianEnabled` (true) · `historian.{provider, model}` (**pinned as a pair**; empty = follow the session's last route) · `historian.reasoningEffort` (optional, blank = model default) | Generation route for out-of-band digests and `/compact` summaries; the GUI
|
|
201
|
+
| historian | `historianEnabled` (true) · `historian.{provider, model}` (**pinned as a pair**; empty = follow the session's last route) · `historian.reasoningEffort` (optional, blank = model default) | Generation route for out-of-band digests and `/compact` summaries; the GUI Settings page has "Historian provider/model" dropdowns (Auto = follow session, recommended) and a catalog-backed reasoning-effort picker: `Default`, the routed model's advertised ids, and `Custom` for legacy/unknown values. The Auto route keeps a text input because the session model is unknown there; an unadvertised id is never silently remapped or clamped. A provider-level `OUTPUT_TOKEN_LIMIT` empty completion is retried with the normal cap escalation. The only LLM spend besides verify |
|
|
192
202
|
| Project memory | `memory.{}`: `enabled` (true, on by default since 0.9.0 — opt out with `enabled: false`) · `dbPath` · `project` (omitted = session cwd) · `domainProjects` · `shareCategories` · `autoPromote` (true) · `write` (true) | `write: false` makes `ctx_memory` read-only |
|
|
193
203
|
| Retrieval / vectors | `memory.embedBackfill` (true, query-side inline backfill) · `memory.vectorBackfill` (true, maintenance-tick backfill) · `memory.vectorBackfillLimit` (24 rows/tick) | Any vector-lane failure fails open to FTS |
|
|
194
204
|
| S(t) decay | `memory.scoring.{enabled (true), alpha (0.4), beta (0.2), archiveThreshold (2), halfLives}` | Stats are always collected; the distribution default enabled=true takes over ranking; profile-JSON only, not on the settings card |
|
|
@@ -223,8 +233,10 @@ Slash commands (`registerStatusCommand: false` disables this command surface):
|
|
|
223
233
|
Both UI capabilities ride the same browser half (`src/client/index.js`, copied verbatim to
|
|
224
234
|
`lib/client.js` at build time):
|
|
225
235
|
|
|
226
|
-
- **Settings
|
|
227
|
-
saving takes effect immediately (see "Configuration").
|
|
236
|
+
- **Settings → Magic Context** (top-level Settings page): visual editing of the volatile
|
|
237
|
+
config above; saving takes effect immediately (see "Configuration"). The same card stays
|
|
238
|
+
on the Plugins page as the legacy location and fallback for hosts without the
|
|
239
|
+
`settings.section` slot.
|
|
228
240
|
|
|
229
241
|
|
|
230
242
|
|
|
@@ -246,11 +258,14 @@ Both UI capabilities ride the same browser half (`src/client/index.js`, copied v
|
|
|
246
258
|
- `GET /mc-telemetry/events` — SSE live tail
|
|
247
259
|
- **Security**: the routes are loopback-only with no token auth, so they **emit counts and
|
|
248
260
|
one-line summaries only** — no message bodies, no file paths, no credentials.
|
|
249
|
-
- **Languages**: browser-side `magic-context` namespace dictionaries (zh/en);
|
|
250
|
-
|
|
251
|
-
|
|
261
|
+
- **Languages**: browser-side `magic-context` namespace dictionaries (zh/en); every
|
|
262
|
+
card-owned label, hint, route placeholder, summary, form frame and picker caption follows
|
|
263
|
+
Settings → General instantly without a refresh. Host catalog values (provider/model/effort
|
|
264
|
+
names) stay as the host sends them. The `session-notice` rows written into the session
|
|
265
|
+
stream (model-visible) stay English constants (to avoid cached-prefix churn from
|
|
252
266
|
mid-session language switches). Mechanics in the
|
|
253
|
-
[UI
|
|
267
|
+
[Settings UI contract](docs/dsh-plugin-settings-ui-contract.md) and the
|
|
268
|
+
[historical UI telemetry host analysis](docs/dsh-plugin-ui-telemetry-contract.md).
|
|
254
269
|
|
|
255
270
|
## Observability & operations
|
|
256
271
|
|
|
@@ -342,31 +357,62 @@ package's structural answer):
|
|
|
342
357
|
|
|
343
358
|
## Documentation index
|
|
344
359
|
|
|
345
|
-
|
|
360
|
+
The linked documents are maintained in this repository; most are written in
|
|
361
|
+
Chinese and a few are English.
|
|
362
|
+
|
|
363
|
+
### Current documentation maintained by this fork
|
|
364
|
+
|
|
365
|
+
- [Magic Context Settings UI contract](docs/dsh-plugin-settings-ui-contract.md) (English) — the
|
|
366
|
+
current top-level Settings page, Plugins fallback, zh/en copy, and catalog-backed effort picker.
|
|
367
|
+
- [Operations runbook](docs/dsh-plugin-operations-runbook-2026-10-10.md) — daily/weekly checks,
|
|
368
|
+
thresholds, recovery, and backup commands.
|
|
369
|
+
- [Upgrade follow-up](docs/dsh-plugin-upgrade-followup.md) — the current re-alignment procedure.
|
|
370
|
+
Its §1 baseline is v0.49.30 and is **not** a v0.49.55 parity claim.
|
|
371
|
+
- [Independent package release](docs/independent-package-release.md) — package identity, migration,
|
|
372
|
+
and release procedure for `@elvisw/dsh-magic-context`.
|
|
373
|
+
|
|
374
|
+
### Historical research and upstream snapshots
|
|
375
|
+
|
|
376
|
+
These are preserved for provenance. They are **not current guarantees**; each file has its own
|
|
377
|
+
`> Status:` header with the evidence baseline.
|
|
378
|
+
|
|
379
|
+
**Historical contracts**
|
|
380
|
+
|
|
381
|
+
- [Memory write contract](docs/dsh-plugin-memory-write-contract.md) — mixed 2026-10 storage snapshot;
|
|
382
|
+
the current corpus is `memories.db`, and §8 authority is historical.
|
|
383
|
+
- [Memory promotion contract](docs/dsh-plugin-memory-promotion-contract.md) — upstream promotion research.
|
|
384
|
+
- [Memory acceptance](docs/dsh-plugin-memory-acceptance.md) — 2026-10 evidence (v6/v94 era).
|
|
385
|
+
- [Config UI contract](docs/dsh-plugin-config-ui-contract.md) — historical; its plugin-specific
|
|
386
|
+
conclusions are superseded by the current Settings UI contract.
|
|
387
|
+
- [UI telemetry contract](docs/dsh-plugin-ui-telemetry-contract.md) — historical host-seam analysis.
|
|
388
|
+
- [Hooks coverage (2026-10-08)](docs/dsh-plugin-hooks-coverage-2026-10-08.md) — historical coverage audit.
|
|
389
|
+
|
|
390
|
+
**Design decisions**
|
|
391
|
+
|
|
392
|
+
- [Port feasibility (seam map)](docs/dsh-port-feasibility-2026-10-06.md)
|
|
393
|
+
- [Platform takeover & global domains](docs/dsh-plugin-platform-takeover-and-global-domains-2026-10-09.md)
|
|
394
|
+
- [Dreamer vector decision](docs/dsh-plugin-dreamer-vector-decision-2026-10-08.md)
|
|
395
|
+
- [Memory mechanisms inventory](docs/memory-mechanisms-inventory-2026-10-09.md)
|
|
396
|
+
- [Upstream source analysis](docs/upstream-source-analysis-2026-10-09.md)
|
|
397
|
+
- [Global-domain source finding](docs/global-domain-source-finding-2026-10-10.md)
|
|
398
|
+
- [Memory architecture challenge](docs/memory-architecture-challenge-2026-10-10.md)
|
|
399
|
+
- [Domain naming decision (2026-10-25)](docs/domain-naming-work-global-2026-10-25.md)
|
|
400
|
+
|
|
401
|
+
**Audits & retrospectives**
|
|
402
|
+
|
|
403
|
+
- [Test design audit](docs/dsh-plugin-test-design-audit-2026-10-07.md)
|
|
404
|
+
- [Surface write audit](docs/dsh-surface-write-audit-2026-10-09.md)
|
|
405
|
+
- [Local embedding runtime audit](docs/local-embedding-runtime-audit-2026-10-15.md)
|
|
346
406
|
|
|
347
|
-
**
|
|
348
|
-
[memory promotion](docs/dsh-plugin-memory-promotion-contract.md) ·
|
|
349
|
-
[memory acceptance](docs/dsh-plugin-memory-acceptance.md) ·
|
|
350
|
-
[config UI](docs/dsh-plugin-config-ui-contract.md) ·
|
|
351
|
-
[UI telemetry](docs/dsh-plugin-ui-telemetry-contract.md) ·
|
|
352
|
-
[upgrade follow-up](docs/dsh-plugin-upgrade-followup.md) ·
|
|
353
|
-
[hooks coverage](docs/dsh-plugin-hooks-coverage-2026-10-08.md)
|
|
407
|
+
**Reports**
|
|
354
408
|
|
|
355
|
-
|
|
356
|
-
[
|
|
357
|
-
[dreamer vector decision](docs/dsh-plugin-dreamer-vector-decision-2026-10-08.md) ·
|
|
358
|
-
[memory mechanisms inventory](docs/memory-mechanisms-inventory-2026-10-09.md) ·
|
|
359
|
-
[upstream source analysis](docs/upstream-source-analysis-2026-10-09.md) ·
|
|
360
|
-
[global-domain source finding](docs/global-domain-source-finding-2026-10-10.md) ·
|
|
361
|
-
[memory architecture challenge](docs/memory-architecture-challenge-2026-10-10.md)
|
|
409
|
+
- [Dreamer token usage](docs/reports/dreamer-token-usage.md)
|
|
410
|
+
- [Memory solutions comparison](docs/reports/memory-solutions-comparison.md)
|
|
362
411
|
|
|
363
|
-
**
|
|
364
|
-
[operations runbook](docs/dsh-plugin-operations-runbook-2026-10-10.md) ·
|
|
365
|
-
[surface write audit](docs/dsh-surface-write-audit-2026-10-09.md) ·
|
|
366
|
-
[local embedding runtime audit](docs/local-embedding-runtime-audit-2026-10-15.md)
|
|
412
|
+
**Upstream handoffs**
|
|
367
413
|
|
|
368
|
-
|
|
369
|
-
[
|
|
414
|
+
- [Upstream follow-up v0.46.0 → v0.49.30](docs/upstream-followup-2026-10-30.md)
|
|
415
|
+
- [/ctx-flush research handoff (0.11.1)](docs/research-handoff-ctx-flush-2026-11-11.md)
|
|
370
416
|
|
|
371
417
|
## Known limits
|
|
372
418
|
|
|
@@ -402,7 +448,7 @@ and publishes as **`@elvisw/dsh-magic-context`** from `0.13.0`. Its versions and
|
|
|
402
448
|
fork. The upstream repository and npm package remain under their original maintainer; this fork does
|
|
403
449
|
not modify them.
|
|
404
450
|
|
|
405
|
-
Differences from upstream `0.11.2`, accumulated through `0.
|
|
451
|
+
Differences from upstream `0.11.2`, accumulated through `0.14.0`:
|
|
406
452
|
|
|
407
453
|
- **Recovery semantics**: `ctx_expand` no longer rewrites placeholders in place. It reads the persisted
|
|
408
454
|
original `tool/result`, returns it as a new tool result, and assigns a new tag. The old placeholder is
|
|
@@ -419,6 +465,9 @@ Differences from upstream `0.11.2`, accumulated through `0.13.0`:
|
|
|
419
465
|
- **Tag retention**: the mount-time 30-day tag prune, the `tags.retentionDays` config, and
|
|
420
466
|
`AdapterStores.pruneTags` are removed. An old profile's key is kept but ignored, with at most one warning
|
|
421
467
|
per process.
|
|
468
|
+
- **Settings UI**: the plugin registers a top-level `settings.section` (Magic Context) with
|
|
469
|
+
zh/en copy and a catalog-backed Historian reasoning-effort picker; the card on the GUI Plugins
|
|
470
|
+
page remains as the legacy location/fallback.
|
|
422
471
|
- **Schema and package name**: the plugin DB moves to v11 (`pending_drops.flush_requested`, automatic v10
|
|
423
472
|
migration). The npm package was `@elvisw/dsh-plugin-magic-context` in `0.12.x`; `0.13.0` renames it to
|
|
424
473
|
`@elvisw/dsh-magic-context` without changing the loader row id `magic-context-dsh`, the settings
|
package/README.zh-CN.md
CHANGED
|
@@ -28,7 +28,9 @@
|
|
|
28
28
|
dsh plugin --profile web add @elvisw/dsh-magic-context
|
|
29
29
|
```
|
|
30
30
|
|
|
31
|
-
`
|
|
31
|
+
> 包名说明：npm 上无 scope 的 `dsh-magic-context` 是另一位维护者的独立实现，不是本 fork，也不是它的上游；本 fork 只以 `@elvisw/dsh-magic-context` 发布。所有安装命令都必须保留 `@elvisw/` scope。
|
|
32
|
+
|
|
33
|
+
`0.13.0` 引入本包名；当前发布是 `0.14.0`，新增顶层设置页。如果之前装过 `@elvisw/dsh-plugin-magic-context`（0.12.x）或上游
|
|
32
34
|
`dsh-plugin-magic-context`，请先移除旧包：三者使用同一个 loader row id（`magic-context-dsh`），不支持共装；共装时只会加载一行，设置页可能消失。
|
|
33
35
|
从 0.12.x 升级还需要一次性迁移 profile patch 的包名，见
|
|
34
36
|
[docs/independent-package-release.md](docs/independent-package-release.md)；迁移脚本随 npm tarball 与 hand-out 一起发布。
|
|
@@ -41,7 +43,7 @@ dsh plugin --profile web add @elvisw/dsh-magic-context
|
|
|
41
43
|
|
|
42
44
|
- 工具结果带上 `§N§` 标签；overlay 里出现**遥测徽标**，显示实时上下文占用，点开是
|
|
43
45
|
指标面板与操作记录。
|
|
44
|
-
- GUI
|
|
46
|
+
- 「设置 → Magic Context」顶层设置页可编辑卡片列出的 volatile 选项；同一张卡片仍保留在 GUI「插件」页，作为旧位置与缺少 `settings.section` 槽位时的回退。
|
|
45
47
|
- `ctx_reduce` / `ctx_expand` / `ctx_memory` 三个工具已注册；项目记忆**默认开启**——
|
|
46
48
|
historian 提炼的事实跨会话沉淀，注入模型读取的位置。
|
|
47
49
|
|
|
@@ -74,7 +76,7 @@ dsh plugin --profile web add @elvisw/dsh-magic-context
|
|
|
74
76
|
| **压力调度** | 持久 usage（含 cache 读写）→ 压力分 → execute/defer 决策（65% 阈值、5 min cache TTL、85% 强制带）；`CONTEXT_WINDOW_EXCEEDED` 触发紧急回收 + retry；reduce-guidance 分级引导 |
|
|
75
77
|
| **historian（带外摘要）** | 一次 LLM 调用重放真前缀（保 KV cache）→ 四层摘要 p1–p4 + facts/events，**只写 store 不动线缆**；execute 带内发布为 `[compacted §C<n>§]` 范围替换；`/ctx-recomp` 原地重做已压缩历史 |
|
|
76
78
|
| **压缩接缝** | `registerCompactionEngine` 可接管 `ctx.compaction`（真实 `compaction/start\|summary\|replace\|end` 协议）；**默认关**，宿主 compaction-basic 保持原位 |
|
|
77
|
-
| **界面集成** |
|
|
79
|
+
| **界面集成** | 顶层「设置 → Magic Context」页 + 旧「插件」页卡片（volatile 字段保存即生效）；catalog-backed Historian 推理强度选择器；`shell.overlay` 遥测徽标 + 胶囊面板（实时指标 + 操作记录）；`session-notice` 会话流提示；卡片自有文案中英即时切换 |
|
|
78
80
|
|
|
79
81
|
## 安装
|
|
80
82
|
|
|
@@ -117,13 +119,14 @@ dsh plugin --profile web add <本仓库路径> # 应用自带 CLI；spec 可
|
|
|
117
119
|
|
|
118
120
|
## 配置
|
|
119
121
|
|
|
120
|
-
改配置有两种途径，语义不同（详见[
|
|
122
|
+
改配置有两种途径，语义不同（详见[设置界面契约](docs/dsh-plugin-settings-ui-contract.md)）：
|
|
121
123
|
|
|
122
|
-
- **GUI
|
|
124
|
+
- **GUI 设置页（设置 → Magic Context）**：暴露 `policy.*`（含 historian 生成上限 / 上限抬升 / 超时）、
|
|
123
125
|
`historianEnabled`、`registerCompactionEngine`、`journal.*`、`maintenance.*`、`historian.*` 等 volatile 字段。
|
|
124
126
|
两组 provider/model **路由钉**（maintenance 的 verify、historian 的生成）优先从**宿主已配置的模型目录**
|
|
125
127
|
（客户端 `remote.session.modelCatalog()`）下拉选择，并带「Auto = 跟随会话路由」与清空；宿主不提供该
|
|
126
|
-
RPC 的 shell
|
|
128
|
+
RPC 的 shell 退回纯文本输入（值仍可手填）。Historian 推理强度字段使用同一个 catalog-backed 选择器：
|
|
129
|
+
`默认`、路由模型实际公布的 id，以及用于旧值/未知值的 `自定义`；Auto 路由保留文本输入。写回走 settings
|
|
127
130
|
链路：非 volatile 键原样保留、未触碰的字段不会 materialize 进覆盖行——**保存即生效**
|
|
128
131
|
（host 侧读取一律经 `liveNumber/liveBoolean/liveString/liveRoute` 在决策点现取）。
|
|
129
132
|
- **手写 profile 覆盖行**：`config` 是**整体替换**包内 patch 的 config，**不是深合并**。只写
|
|
@@ -149,7 +152,7 @@ bundle 自带配置只有一行：`registerCompactionEngine: false`——保守
|
|
|
149
152
|
| 总开关 | `enabled` (true) · `registerTools` (true) · `registerStatusCommand` (true) · `sessionNotices` (true) · `reduceGuidance` (true) · `searchHint` (true) | `enabled: false` 保持加载但完全惰性；`sessionNotices` 控制会话流内的管理提示行 |
|
|
150
153
|
| 压缩接缝 | `registerCompactionEngine`（代码默认可解析即挂；**bundle 随发 false**）· `compactionBase`（宿主注入基类） | 接管需同时禁用 compaction-basic；pre-step 每步 `reconcileEngine` 动态挂/卸 |
|
|
151
154
|
| 压力策略 | `policy.*`：`executeThreshold` (65) · `forceThreshold` (85) · `ttlMs` (5 min) · `assumedContextWindow` (256k) · `protectedToolResults` (8) · `historianTimeoutMs` (120 s) · `historianMaxTokens` (8192，低于会被抬到 8192) · `historianMaxTokensCeiling` (32768) · `baselineTokens` (2000) · `memoryBudgetTokens` (8000) · `memoryLimit` (40) · `forceWaitReadyMs` (0) | 阈值在下一个决策点生效（含 `/ctx-status` 与 compaction engine 路径）。`compartmentGuardMode` / `compartmentEntrantTokens`（发布护栏）已退役，不再是可配置项 |
|
|
152
|
-
| historian | `historianEnabled` (true) · `historian.{provider, model}`（**成对钉住**；空 = 跟随会话最后路由）· `historian.reasoningEffort`（可选，留空 = 模型默认） | 带外摘要与 `/compact` 摘要的生成路由；GUI
|
|
155
|
+
| historian | `historianEnabled` (true) · `historian.{provider, model}`（**成对钉住**；空 = 跟随会话最后路由）· `historian.reasoningEffort`（可选，留空 = 模型默认） | 带外摘要与 `/compact` 摘要的生成路由；GUI 设置页有「Historian provider/model」下拉（Auto = 跟随会话，推荐）和 catalog-backed 推理强度选择器：`默认`、路由模型实际公布的 id，以及用于旧值/未知值的 `自定义`。Auto 路由下仍保留文本输入（此时不知道会话模型）；未公布的 id 不会被静默改写或夹取。provider 级 `OUTPUT_TOKEN_LIMIT` 空补全会走正常的预算翻倍重试。verify 之外的唯一 LLM 消耗点 |
|
|
153
156
|
| 项目记忆 | `memory.{}`：`enabled`（true，0.9.0 起默认开启——`enabled: false` 退出）· `dbPath` · `project`（省略用会话 cwd）· `domainProjects` · `shareCategories` · `autoPromote` (true) · `write` (true) | `write: false` 让 `ctx_memory` 退回只读 |
|
|
154
157
|
| 检索 / 向量 | `memory.embedBackfill` (true，查询侧内嵌补分) · `memory.vectorBackfill` (true，维护 tick 回填) · `memory.vectorBackfillLimit` (24 行/tick) | 向量车道任何失败 fail-open 降级 FTS |
|
|
155
158
|
| S(t) 衰减 | `memory.scoring.{enabled (true)，alpha (0.4)，beta (0.2)，archiveThreshold (2)，halfLives}` | 统计恒收集；分发缺省 enabled=true 接管排序；profile-JSON only，不进设置卡片 |
|
|
@@ -183,7 +186,7 @@ Agent 工具（挂载时注册；`registerTools: false` 可关）：
|
|
|
183
186
|
|
|
184
187
|
两个界面能力都靠同一个浏览器半侧（`src/client/index.js`，构建时原样拷为 `lib/client.js`）：
|
|
185
188
|
|
|
186
|
-
-
|
|
189
|
+
- **「设置 → Magic Context」顶层设置页**：上文 volatile 配置项的可视化编辑，保存即生效（见“配置”一节）。同一张卡片保留在「插件」页，作为旧位置与没有 `settings.section` 槽位时的回退。
|
|
187
190
|
|
|
188
191
|
|
|
189
192
|
|
|
@@ -201,9 +204,7 @@ Agent 工具（挂载时注册；`registerTools: false` 可关）：
|
|
|
201
204
|
- `GET /mc-telemetry/events` — SSE 实时尾
|
|
202
205
|
- **安全**：路由仅 loopback、无 token 鉴权，因此**只输出计数与单行摘要**——不含消息正文、
|
|
203
206
|
不含文件路径、不含凭据。
|
|
204
|
-
- **多语言**：浏览器侧 `magic-context` 命名空间字典（zh/en
|
|
205
|
-
写进会话流、模型可见的 `session-notice` 保持英文常量（避免同会话中途换语言造成 cached prefix
|
|
206
|
-
抖动）。机制见[主界面遥测契约](docs/dsh-plugin-ui-telemetry-contract.md)。
|
|
207
|
+
- **多语言**：浏览器侧 `magic-context` 命名空间字典（zh/en）；卡片的全部自有文案——字段 label/hint、路由占位、摘要、表单框架与选择器说明——跟随「设置 → 通用」即时切换、无需刷新。宿主 catalog 的值（provider/model/effort 名称）保持宿主原文。写进会话流、模型可见的 `session-notice` 保持英文常量（避免同会话中途换语言造成 cached prefix 抖动）。机制见[设置界面契约](docs/dsh-plugin-settings-ui-contract.md)与[主界面遥测契约（历史）](docs/dsh-plugin-ui-telemetry-contract.md)。
|
|
207
208
|
|
|
208
209
|
## 观测与运维
|
|
209
210
|
|
|
@@ -280,29 +281,57 @@ src/
|
|
|
280
281
|
|
|
281
282
|
## 文档索引
|
|
282
283
|
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
[
|
|
288
|
-
|
|
289
|
-
[
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
[
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
[
|
|
301
|
-
|
|
302
|
-
[
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
[
|
|
284
|
+
链接文档随本仓库维护；多数为中文，少数为英文。
|
|
285
|
+
|
|
286
|
+
### 本 fork 维护的当前文档
|
|
287
|
+
|
|
288
|
+
- [Magic Context 设置界面契约](docs/dsh-plugin-settings-ui-contract.md)（英文）——当前顶层设置页、
|
|
289
|
+
Plugins 回退入口、中英文案与 catalog-backed effort 选择器。
|
|
290
|
+
- [运维手册](docs/dsh-plugin-operations-runbook-2026-10-10.md)——每日/每周检查、阈值、故障处置与备份命令。
|
|
291
|
+
- [升级跟随](docs/dsh-plugin-upgrade-followup.md)——当前重新对齐流程；§1 是 v0.49.30 历史基线，
|
|
292
|
+
**不**代表已经完成 v0.49.55 parity。
|
|
293
|
+
- [独立包名与发布](docs/independent-package-release.md)——`@elvisw/dsh-magic-context` 的包身份、迁移与发布流程。
|
|
294
|
+
|
|
295
|
+
### 历史研究与上游快照
|
|
296
|
+
|
|
297
|
+
以下文档仅作溯源保留，**不是当前保证**；每份文件标题后都有自己的 `> Status:` 与证据基线。
|
|
298
|
+
|
|
299
|
+
**历史契约**
|
|
300
|
+
|
|
301
|
+
- [记忆写契约](docs/dsh-plugin-memory-write-contract.md)——混合的 2026-10 存储快照；
|
|
302
|
+
当前语料库是 `memories.db`，§8 authority 已属历史。
|
|
303
|
+
- [记忆提升契约](docs/dsh-plugin-memory-promotion-contract.md)——上游提升机制研究。
|
|
304
|
+
- [记忆验收](docs/dsh-plugin-memory-acceptance.md)——2026-10 证据（v6/v94 时期）。
|
|
305
|
+
- [配置界面契约](docs/dsh-plugin-config-ui-contract.md)——历史文档；插件相关结论已由当前设置界面契约取代。
|
|
306
|
+
- [主界面遥测契约](docs/dsh-plugin-ui-telemetry-contract.md)——历史宿主接缝分析。
|
|
307
|
+
- [hooks 覆盖（2026-10-08）](docs/dsh-plugin-hooks-coverage-2026-10-08.md)——历史覆盖审计。
|
|
308
|
+
|
|
309
|
+
**设计决策**
|
|
310
|
+
|
|
311
|
+
- [移植可行性（接缝地图）](docs/dsh-port-feasibility-2026-10-06.md)
|
|
312
|
+
- [平台接管与全域](docs/dsh-plugin-platform-takeover-and-global-domains-2026-10-09.md)
|
|
313
|
+
- [dreamer 向量决策](docs/dsh-plugin-dreamer-vector-decision-2026-10-08.md)
|
|
314
|
+
- [记忆机制清单](docs/memory-mechanisms-inventory-2026-10-09.md)
|
|
315
|
+
- [上游源码分析](docs/upstream-source-analysis-2026-10-09.md)
|
|
316
|
+
- [全域来源调查](docs/global-domain-source-finding-2026-10-10.md)
|
|
317
|
+
- [记忆架构挑战](docs/memory-architecture-challenge-2026-10-10.md)
|
|
318
|
+
- [域命名决定（2026-10-25）](docs/domain-naming-work-global-2026-10-25.md)
|
|
319
|
+
|
|
320
|
+
**复盘与审计**
|
|
321
|
+
|
|
322
|
+
- [测试设计审计](docs/dsh-plugin-test-design-audit-2026-10-07.md)
|
|
323
|
+
- [surface 写审计](docs/dsh-surface-write-audit-2026-10-09.md)
|
|
324
|
+
- [本地向量运行时审计](docs/local-embedding-runtime-audit-2026-10-15.md)
|
|
325
|
+
|
|
326
|
+
**报告**
|
|
327
|
+
|
|
328
|
+
- [dreamer token 用量](docs/reports/dreamer-token-usage.md)
|
|
329
|
+
- [记忆方案对比](docs/reports/memory-solutions-comparison.md)
|
|
330
|
+
|
|
331
|
+
**上游交接**
|
|
332
|
+
|
|
333
|
+
- [上游跟进 v0.46.0 → v0.49.30](docs/upstream-followup-2026-10-30.md)
|
|
334
|
+
- [/ctx-flush 研究交接（0.11.1）](docs/research-handoff-ctx-flush-2026-11-11.md)
|
|
306
335
|
|
|
307
336
|
## 已知边界
|
|
308
337
|
|
|
@@ -332,13 +361,14 @@ typecheck → test → build → check:i18n。
|
|
|
332
361
|
`0.13.0` 起以 **`@elvisw/dsh-magic-context`** 发布；版本与 tag 归本 fork。
|
|
333
362
|
上游仓库和上游 npm 包仍由原维护者维护，本 fork 不修改它们。
|
|
334
363
|
|
|
335
|
-
相对上游 `0.11.2`，累计到 `0.
|
|
364
|
+
相对上游 `0.11.2`，累计到 `0.14.0` 的主要差异：
|
|
336
365
|
|
|
337
366
|
- **恢复语义**：`ctx_expand` 不再原地改写占位符，而是读取持久化的原始 `tool/result`，作为新的工具结果返回并分配新 tag；旧占位符保持不变，旧 tag 仍是 dropped，再次 `ctx_reduce` 是 no-op（`already dropped`）。这是 breaking change。
|
|
338
367
|
- **Historian 之后仍可读原文**：`ctx_expand` 新增 `message` 定位，接受当前会话的 DSH log event seq（包括被 Historian shadow 的原始 `tool/result`）；不重跑原工具、不改写摘要或 compartment。
|
|
339
368
|
- **手动 flush**：新增 `/ctx-flush`，只把当前会话已 pending 的 drop 标记为下一次 preStep 落地；不启动 Historian、recomp、摘要或模型调用。
|
|
340
369
|
- **持久 drop 状态**：`ctx_reduce`/`ctx_expand` 以 `pending_drops` 的 `none`/`pending`/`landed` 状态判定，而不是依赖当前 surface 上是否还有占位符；旧 tag 在 restore 后不会再显示假的 “Queued”。
|
|
341
370
|
- **tag 保留策略**：移除挂载时的 30 天 tag prune、`tags.retentionDays` 配置与 `AdapterStores.pruneTags`；旧 profile 里的该键保留但被忽略，且每进程最多告警一次。
|
|
371
|
+
- **设置界面**：插件注册顶层 `settings.section`（Magic Context），字段文案与选择器支持中英文，Historian 推理强度从当前模型 catalog 读取；GUI「插件」页卡片保留为旧位置与回退。
|
|
342
372
|
- **schema 与包名**：插件数据库升到 v11（`pending_drops.flush_requested`，v10 自动迁移）；npm 包名在 `0.12.x` 为
|
|
343
373
|
`@elvisw/dsh-plugin-magic-context`，`0.13.0` 改为 `@elvisw/dsh-magic-context`，但 loader row id
|
|
344
374
|
`magic-context-dsh`、settings namespace、插件数据目录 `magic-context-dsh-poc`、schema 与存储格式不变。
|