dsh-context-kit 0.1.1 → 0.3.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 CHANGED
@@ -1,17 +1,19 @@
1
1
  # dsh-context-kit
2
2
 
3
- Save context tokens in DSH. One package, three parts:
3
+ Manage the automatic-compaction threshold in DSH without freezing the agent preset.
4
4
 
5
5
  | part | what it does |
6
6
  | --- | --- |
7
- | **context index** (host) | Keeps a small, stable system-prompt section listing the *pointers* that compaction would otherwise erase: recent tool artifacts and touched paths. Summaries lose content, not locations. |
8
7
  | **preset tuner** (host) | Moves the automatic-compaction trigger earlier — and does it without freezing the agent preset, by regenerating the override from the preset that ships inside the app. |
9
8
  | **Settings panel** (web) | A Context page: drag the trigger point, apply, preview, remove. No YAML editing. |
9
+ | **package entry** (host, `host.js`) | An intentionally empty plugin row that keeps `dsh-context-kit` itself present in the composed tree. DSH mounts a package's browser half by **package name**; with only subpath rows (`dsh-context-kit/tuner`) the Settings page silently fails to load. |
10
10
 
11
- Why this combination: compaction is the lever that actually moves the bill. Compacting at 524K instead of
12
- 679K avoids re-sending the region above the trigger on every step; the index then makes sure the summary
13
- that replaces that region still tells the model where things are. The two are complementary — the index
14
- alone saves nothing on its own, and earlier compaction alone loses pointers.
11
+ > The context index moved to **[dsh-token-trim](https://www.npmjs.com/package/dsh-token-trim)** in 0.3.0:
12
+ > that package now owns tool-result trimming, the context index and the “Savings” view. Install it next to
13
+ > this one if you want the pointer index back.
14
+
15
+ Why the tuner: compaction is the lever that actually moves the bill. Compacting at 410K instead of 679K
16
+ avoids re-sending the region above the trigger on every step.
15
17
 
16
18
  ## Install
17
19
 
@@ -21,11 +23,12 @@ dsh plugin add dsh-context-kit
21
23
 
22
24
  Restart DSH. You get:
23
25
 
24
- - two host plugins (`context-kit-index`, `context-kit-tuner`),
26
+ - the tuner host plugin (`context-kit-tuner`) plus the empty package row (`context-kit`),
25
27
  - a **Settings → Context** page,
26
28
  - a `preset_tuner` tool,
27
29
  - a `dsh-context-kit` CLI.
28
30
 
31
+
29
32
  ## Panel: Settings → Context
30
33
 
31
34
  - **Compact at** — the fraction of the context window that triggers compaction (default `0.5` → ~524K).
@@ -41,6 +44,7 @@ Where it stores things:
41
44
 
42
45
  ```
43
46
  <profile>/dsh-context-kit/settings.json # what the panel edits
47
+ <profile>/dsh-context-kit/usage-cache.json # parsed session stats, keyed by path+mtime+size
44
48
  <profile>/cordis.patch.yml # managed block: generated, not hand-written
45
49
  <profile>/dsh-context-kit/backups/ # every overwrite keeps the previous file (last 10)
46
50
  ```
@@ -49,6 +53,32 @@ Precedence: `settings.json` wins over the plugin's `config.presets` in the bundl
49
53
  plugin row can stay empty (`presets: {}`) and the panel is the single place where numbers live — the
50
54
  managed block in `cordis.patch.yml` always reflects what you last applied.
51
55
 
56
+ ## Effect measurement
57
+
58
+ The second card in the panel answers "did this actually save anything?" without pretending to know
59
+ more than it can.
60
+
61
+ **Measured** (read from `~/.dsh/sessions/**/session.v4.jsonl.zstd`): steps, cache-hit / cache-miss /
62
+ output tokens, compaction count, average and peak context, cost expressed in hit-equivalents
63
+ (`miss × 10`, `output × 15`, hit = 1), and a rework signal — repeated identical tool calls, which is
64
+ the first sign compaction went too deep.
65
+
66
+ **Attributed by policy.** A session that compacted at ~712K ran under a different threshold than one
67
+ that compacted at ~419K, so the ledger is split by the observed trigger height (bucketed to 8K;
68
+ sessions that never compacted are listed as unclassifiable). "Data under the current threshold" tells
69
+ you how much of the window was actually produced by the setting you are looking at — it is 0 right
70
+ after you change the knobs, and grows from there. Do not read a saving off a window whose current
71
+ policy has no data.
72
+
73
+ **Estimated** (labelled in the UI and in the CLI): the saving versus the shipped default
74
+ (`0.8 / 0.16`). It replays your real per-step growth under both policies. It is a model, not a bill:
75
+ it assumes the same work happens and the same price ratio, and it does not price lost detail. When
76
+ the current threshold has almost no measured steps the panel says so explicitly.
77
+
78
+ Privacy: local only. The plugin reads session logs, writes a cache next to `settings.json`, and never
79
+ sends anything anywhere. The first run decompresses recent sessions (a few seconds); later runs reuse
80
+ the cache. The host RPC yields between files so the UI stays responsive.
81
+
52
82
  ## Why the tuner exists (the freeze problem)
53
83
 
54
84
  The live `compaction-basic` instance lives **inside the agent preset**, in a group that is `isolate`d.
@@ -76,6 +106,7 @@ dsh-context-kit set --threshold 0.5 --retain 0.16 --preset cordis
76
106
  dsh-context-kit sync [--force --mode replace]
77
107
  dsh-context-kit preview
78
108
  dsh-context-kit clear
109
+ dsh-context-kit report [--days 7]
79
110
  ```
80
111
 
81
112
  `--resources "<DSH install>/resources"` when it cannot find the app by itself.
@@ -85,10 +116,11 @@ and points at the line numbers.
85
116
  ## Tool
86
117
 
87
118
  ```text
88
- preset_tuner(action="status" | "preview" | "sync" | "clear")
119
+ preset_tuner(action="status" | "preview" | "sync" | "clear" | "report", days?)
89
120
  ```
90
121
 
91
- `status` is read-only and reports upstream drift; `sync` writes and tells you to restart.
122
+ `status` is read-only and reports upstream drift; `sync` writes and tells you to restart;
123
+ `report` returns the same measured/estimated summary as the panel card.
92
124
 
93
125
  ## Safety
94
126
 
@@ -134,5 +134,40 @@ if (command === 'clear') {
134
134
  process.exit(0)
135
135
  }
136
136
 
137
- fail(`未知命令: ${command}(可用: status | set | preview | sync | clear)`)
137
+ if (command === 'report') {
138
+ const days = Number(args.days ?? 7)
139
+ const report = await kit.report({ days })
140
+ const t = report.totals
141
+ const big = (value) => (value >= 1e9 ? `${(value / 1e9).toFixed(2)}B` : value >= 1e6 ? `${(value / 1e6).toFixed(1)}M` : `${Math.round(value / 1e3)}K`)
142
+ console.log(`窗口 : 最近 ${report.window.days} 天(自 ${report.window.since.slice(0, 10)})`)
143
+ console.log(`规模 : ${t.sessions} 会话 / ${t.steps} 步 / ${t.compactions} 次压缩`)
144
+ for (const policy of report.policies || []) {
145
+ console.log(
146
+ ` 分期 : ${policy.triggerTokens === null ? '无压缩(无法判断)' : `触发点 ≈${fmt(policy.triggerTokens)}`}` +
147
+ ` → ${policy.totals.sessions} 会话 / ${policy.totals.steps} 步${policy.isCurrent ? '(当前阈值)' : ''}`,
148
+ )
149
+ }
150
+ if (report.coverage) {
151
+ console.log(` 覆盖 : 当前阈值实测 ${report.coverage.stepsUnderCurrent} 步(${report.coverage.sharePct.toFixed(1)}%)`)
152
+ }
153
+ console.log(`实测用量: 命中 ${big(t.hit)} · 未命中 ${big(t.miss)} · 输出 ${big(t.out)}`)
154
+ console.log(`上下文 : 平均 ${fmt(t.promptAvg)} · 峰值 ${fmt(t.promptMax)}`)
155
+ console.log(`成本 : ${big(t.cost.total)}(命中当量,未命中占 ${t.missSharePct.toFixed(1)}%)`)
156
+ if (report.savings) {
157
+ console.log(
158
+ `节省估算: ${report.savings.savedPct.toFixed(1)}%(基线 ${report.savings.baseThresholdRatio}/${report.savings.baseRetainRatio}` +
159
+ ` → 当前 ${report.savings.thresholdRatio}/${report.savings.retainRatio},压缩 ${report.savings.baseEvents}→${report.savings.currentEvents} 次)`,
160
+ )
161
+ console.log(' 这是估算,不是账单。')
162
+ if (report.coverage && report.coverage.isModelOnly) {
163
+ console.log(' ! 当前阈值下的实测样本太少,只能当方向。')
164
+ }
165
+ }
166
+ console.log(`返工 : 重复调用 ${t.duplicates} / 不同调用 ${t.distinctCalls}(${t.duplicatePct.toFixed(1)}%)`)
167
+ console.log(`解压 : 本次 ${(report.decompressedBytes / 1e6).toFixed(1)}MB,缓存 ${report.files.length} 个文件`)
168
+ console.log(report.privacy)
169
+ process.exit(0)
170
+ }
171
+
172
+ fail(`未知命令: ${command}(可用: status | set | preview | sync | clear | report)`)
138
173
  export { triggersFor }