dsh-context-kit 0.1.0 → 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/lib/usage.mjs ADDED
@@ -0,0 +1,448 @@
1
+ // 效果统计:读本机会话日志,给出「实测台账 + 估算节省 + 返工信号」。
2
+ //
3
+ // 三条原则:
4
+ // 1. 只读本地文件,不联网、不上报任何内容。
5
+ // 2. 实测与估算分开标注:token 用量是实测,节省百分比是模型估算(反事实无法观测)。
6
+ // 3. 解析函数是纯函数(吃 JSONL 文本),便于测试;读文件与解压是薄薄一层。
7
+ import fs from 'node:fs'
8
+ import path from 'node:path'
9
+ import { decompress } from '../vendor/fzstd/index.mjs'
10
+
11
+ /** 价格比(DeepSeek 公开价:命中/未命中/输出)。只用于把用量折算成可比较的"命中当量"。 */
12
+ export const PRICES = { hit: 1, miss: 10, out: 15 }
13
+
14
+ /** DSH 默认压缩参数,作为"不装本插件"的基线。 */
15
+ export const BASE_POLICY = { thresholdRatio: 0.8, retainRatio: 0.16 }
16
+
17
+ export const DEFAULT_CONTEXT_WINDOW = 1048576
18
+
19
+ /** 从工具参数里取一个"做什么"的签名,用于识别重复劳动。 */
20
+ export function toolKey(name, args) {
21
+ let parsed = args
22
+ if (typeof args === 'string') {
23
+ try {
24
+ parsed = JSON.parse(args)
25
+ } catch {
26
+ parsed = null
27
+ }
28
+ }
29
+ const pick = (value) => (typeof value === 'string' && value.trim() ? value.trim() : '')
30
+ if (parsed && typeof parsed === 'object') {
31
+ const interesting =
32
+ pick(parsed.path) ||
33
+ pick(parsed.file_path) ||
34
+ pick(parsed.command) ||
35
+ pick(parsed.pattern) ||
36
+ pick(parsed.query) ||
37
+ pick(parsed.url)
38
+ if (interesting) return `${name}|${interesting}`
39
+ try {
40
+ return `${name}|${JSON.stringify(parsed).slice(0, 120)}`
41
+ } catch {
42
+ return `${name}|`
43
+ }
44
+ }
45
+ return `${name}|`
46
+ }
47
+
48
+ const num = (value) => (Number.isFinite(Number(value)) ? Number(value) : 0)
49
+
50
+ /**
51
+ * 解析一个会话的 JSONL 文本。
52
+ * 纯函数:不碰文件系统,测试直接喂字符串。
53
+ */
54
+ export function parseSessionJsonl(text) {
55
+ const steps = []
56
+ const deltas = []
57
+ const compactionTriggers = []
58
+ const calls = new Map()
59
+ let compactions = 0
60
+ let summaryTokens = 0
61
+ let prompt = 0
62
+ let previousPrompt = 0
63
+ let firstTime = 0
64
+ let lastTime = 0
65
+
66
+ for (const line of String(text).split('\n')) {
67
+ if (!line) continue
68
+ let event
69
+ try {
70
+ event = JSON.parse(line)
71
+ } catch {
72
+ continue
73
+ }
74
+ if (!event || typeof event !== 'object') continue
75
+ if (Number.isFinite(event.time)) {
76
+ if (!firstTime) firstTime = event.time
77
+ lastTime = event.time
78
+ }
79
+ const type = event.type
80
+
81
+ if (type === 'tool/call') {
82
+ const data = event.data || {}
83
+ const key = toolKey(String(data.name ?? 'unknown'), data.arguments)
84
+ calls.set(key, (calls.get(key) ?? 0) + 1)
85
+ continue
86
+ }
87
+
88
+ if (type === 'compaction/start') {
89
+ // 压缩发生时的 prompt 高度 ≈ 当时的阈值:用它给这次会话的运行策略分期
90
+ if (previousPrompt > 0) compactionTriggers.push(previousPrompt)
91
+ continue
92
+ }
93
+
94
+ if (type === 'compaction/summary') {
95
+ compactions += 1
96
+ const blocks = event.data?.summary
97
+ if (Array.isArray(blocks)) {
98
+ for (const block of blocks) if (typeof block?.text === 'string') summaryTokens += Math.ceil(block.text.length / 4)
99
+ }
100
+ continue
101
+ }
102
+
103
+ if (type !== 'assistant/message') continue
104
+ const usage = event.data?.usage
105
+ if (!usage) continue
106
+ const hit = num(usage.cacheReadTokens)
107
+ const miss = num(usage.inputTokens)
108
+ const out = num(usage.outputTokens)
109
+ prompt = hit + miss
110
+ const delta = prompt - previousPrompt
111
+ // 压缩后 prompt 会变短,这一步的负增量不参与回放(否则会把压缩当成"缩水")
112
+ if (delta > 0) deltas.push(delta)
113
+ steps.push({ hit, miss, out, prompt })
114
+ previousPrompt = prompt
115
+ }
116
+
117
+ let duplicates = 0
118
+ let reused = 0
119
+ for (const count of calls.values()) {
120
+ if (count > 1) {
121
+ duplicates += count - 1
122
+ reused += 1
123
+ }
124
+ }
125
+
126
+ return {
127
+ steps,
128
+ deltas,
129
+ compactionTriggers,
130
+ compactions,
131
+ summaryTokens,
132
+ duplicates,
133
+ distinctCalls: calls.size,
134
+ repeatedGroups: reused,
135
+ firstTime,
136
+ lastTime,
137
+ }
138
+ }
139
+
140
+ /** 把解析结果压成紧凑统计(缓存只存这个,别存完整 steps)。 */
141
+ export function compactSession(parsed) {
142
+ const compact = {
143
+ stepCount: parsed.steps.length,
144
+ hit: 0,
145
+ miss: 0,
146
+ out: 0,
147
+ promptMax: 0,
148
+ compactions: parsed.compactions,
149
+ duplicates: parsed.duplicates,
150
+ distinctCalls: parsed.distinctCalls,
151
+ deltas: parsed.deltas,
152
+ compactionTriggers: parsed.compactionTriggers ?? [],
153
+ }
154
+ for (const step of parsed.steps) {
155
+ compact.hit += step.hit
156
+ compact.miss += step.miss
157
+ compact.out += step.out
158
+ if (step.prompt > compact.promptMax) compact.promptMax = step.prompt
159
+ }
160
+ return compact
161
+ }
162
+
163
+ /** 把多个会话的紧凑统计汇总成台账。 */
164
+ export function summarize(parsed) {
165
+ const totals = { sessions: parsed.length, steps: 0, hit: 0, miss: 0, out: 0, compactions: 0, duplicates: 0, distinctCalls: 0, promptMax: 0 }
166
+ for (const session of parsed) {
167
+ totals.steps += session.stepCount
168
+ totals.hit += session.hit
169
+ totals.miss += session.miss
170
+ totals.out += session.out
171
+ totals.compactions += session.compactions
172
+ totals.duplicates += session.duplicates
173
+ totals.distinctCalls += session.distinctCalls
174
+ if (session.promptMax > totals.promptMax) totals.promptMax = session.promptMax
175
+ }
176
+ const cost = {
177
+ hit: totals.hit * PRICES.hit,
178
+ miss: totals.miss * PRICES.miss,
179
+ out: totals.out * PRICES.out,
180
+ }
181
+ cost.total = cost.hit + cost.miss + cost.out
182
+ const promptTotal = totals.hit + totals.miss
183
+ return {
184
+ ...totals,
185
+ promptAvg: totals.steps > 0 ? Math.round(promptTotal / totals.steps) : 0,
186
+ cost,
187
+ missSharePct: cost.total > 0 ? (cost.miss / cost.total) * 100 : 0,
188
+ duplicatePct: totals.distinctCalls > 0 ? (totals.duplicates / (totals.distinctCalls + totals.duplicates)) * 100 : 0,
189
+ }
190
+ }
191
+
192
+ const triggerFor = (window, ratio) => Math.min(Math.floor(window * ratio), window - 256000 - 65536)
193
+
194
+ /**
195
+ * 这次会话当时跑的是哪套压缩策略?
196
+ * 只看得到副作用:压缩发生时的 prompt 高度。没有压缩事件的会话无法判断(记为 no-compaction)。
197
+ *
198
+ * 注意:阈值和触发点是多对一的(ratio 超过预算后触发点被 727040 截断),
199
+ * 所以按「触发点的整数高度」分期,不硬猜 ratio。
200
+ */
201
+ export function classifySession(session, options = {}) {
202
+ const contextWindow = options.contextWindow ?? DEFAULT_CONTEXT_WINDOW
203
+ const budget = contextWindow - 256000 - 65536
204
+ const triggers = (session.compactionTriggers ?? []).filter((value) => Number.isFinite(value) && value > 0)
205
+ if (triggers.length === 0) return { key: 'no-compaction', triggerTokens: null, thresholdRatio: null }
206
+ const sorted = [...triggers].sort((a, b) => a - b)
207
+ const median = sorted[Math.floor(sorted.length / 2)]
208
+ const bucket = Math.max(8192, Math.round(median / 8192) * 8192)
209
+ return {
210
+ key: `t${bucket}`,
211
+ triggerTokens: bucket,
212
+ // 触发点贴着预算上限时,无法反推 ratio(任何更大的 ratio 都给同一个触发点)
213
+ thresholdRatio: bucket >= budget - 8192 ? null : Math.round((bucket / contextWindow) * 100) / 100,
214
+ }
215
+ }
216
+
217
+ /**
218
+ * 按观测到的策略分期。这是「实测归因」的核心:
219
+ * 历史数据里混着旧阈值跑出来的会话,不能整体当作当前配置的效果。
220
+ */
221
+ export function groupByPolicy(sessions, options = {}) {
222
+ const contextWindow = options.contextWindow ?? DEFAULT_CONTEXT_WINDOW
223
+ const budget = contextWindow - 256000 - 65536
224
+ const currentRatio = options.thresholdRatio ?? 0.4
225
+ const currentTrigger = Math.min(Math.floor(contextWindow * currentRatio), budget)
226
+ const groups = new Map()
227
+ for (const session of sessions) {
228
+ const policy = classifySession(session, { contextWindow })
229
+ const group = groups.get(policy.key) ?? { ...policy, members: [] }
230
+ group.members.push(session)
231
+ groups.set(policy.key, group)
232
+ }
233
+ return [...groups.values()]
234
+ .map((group) => ({
235
+ key: group.key,
236
+ triggerTokens: group.triggerTokens,
237
+ thresholdRatio: group.thresholdRatio,
238
+ isCurrent:
239
+ group.triggerTokens !== null && Math.abs(group.triggerTokens - currentTrigger) <= 32768,
240
+ totals: summarize(group.members),
241
+ }))
242
+ .sort((a, b) => b.totals.steps - a.totals.steps)
243
+ }
244
+
245
+ /**
246
+ * 反事实回放:同一批"每步新增量",分别按当前阈值和基线阈值压缩,比较总成本。
247
+ * 这是估算:假设工作量不变、价格比固定、摘要规模与实测同比例。面板里必须标注"估算"。
248
+ */
249
+ export function estimateSavings(deltas, options = {}) {
250
+ const window = options.contextWindow ?? DEFAULT_CONTEXT_WINDOW
251
+ const current = { thresholdRatio: options.thresholdRatio ?? 0.4, retainRatio: options.retainRatio ?? 0.12 }
252
+ const base = { thresholdRatio: options.baseThresholdRatio ?? BASE_POLICY.thresholdRatio, retainRatio: options.baseRetainRatio ?? BASE_POLICY.retainRatio }
253
+ const summaryRatio = options.summaryRatio ?? 0.005
254
+ const steps = deltas.filter((value) => Number.isFinite(value) && value > 0)
255
+ if (steps.length === 0) return null
256
+
257
+ const replay = (policy) => {
258
+ const trigger = triggerFor(window, policy.thresholdRatio)
259
+ const retain = Math.floor(window * policy.retainRatio)
260
+ let prompt = 0
261
+ let cost = 0
262
+ let events = 0
263
+ for (const step of steps) {
264
+ const previous = prompt
265
+ prompt += step
266
+ if (prompt > trigger && prompt - retain > 20000) {
267
+ const shadowed = prompt - retain
268
+ const summary = Math.max(60, Math.round(shadowed * summaryRatio))
269
+ if (summary < shadowed) {
270
+ cost += shadowed * PRICES.miss + summary * PRICES.out
271
+ events += 1
272
+ prompt = retain + summary
273
+ cost += prompt * PRICES.miss
274
+ continue
275
+ }
276
+ }
277
+ cost += previous * PRICES.hit + step * PRICES.miss
278
+ }
279
+ return { cost, events }
280
+ }
281
+
282
+ const currentRun = replay(current)
283
+ const baseRun = replay(base)
284
+ return {
285
+ estimate: true,
286
+ baseThresholdRatio: base.thresholdRatio,
287
+ baseRetainRatio: base.retainRatio,
288
+ thresholdRatio: current.thresholdRatio,
289
+ retainRatio: current.retainRatio,
290
+ baseCost: baseRun.cost,
291
+ currentCost: currentRun.cost,
292
+ baseEvents: baseRun.events,
293
+ currentEvents: currentRun.events,
294
+ savedPct: baseRun.cost > 0 ? ((baseRun.cost - currentRun.cost) / baseRun.cost) * 100 : 0,
295
+ steps: steps.length,
296
+ }
297
+ }
298
+
299
+ const CACHE_VERSION = 2
300
+
301
+ function readCache(cachePath) {
302
+ try {
303
+ const parsed = JSON.parse(fs.readFileSync(cachePath, 'utf8'))
304
+ if (parsed && parsed.version === CACHE_VERSION && parsed.files && typeof parsed.files === 'object') return parsed
305
+ } catch {}
306
+ return { version: CACHE_VERSION, files: {} }
307
+ }
308
+
309
+ function writeCache(cachePath, cache) {
310
+ try {
311
+ fs.mkdirSync(path.dirname(cachePath), { recursive: true })
312
+ const tmp = `${cachePath}.tmp`
313
+ fs.writeFileSync(tmp, JSON.stringify(cache), 'utf8')
314
+ fs.renameSync(tmp, cachePath)
315
+ } catch {}
316
+ }
317
+
318
+ function collectSessionFiles(home, since, limits) {
319
+ const root = path.join(home, 'sessions')
320
+ const files = []
321
+ const walk = (dir, depth) => {
322
+ if (depth > 3) return
323
+ let entries
324
+ try {
325
+ entries = fs.readdirSync(dir, { withFileTypes: true })
326
+ } catch {
327
+ return
328
+ }
329
+ for (const entry of entries) {
330
+ const full = path.join(dir, entry.name)
331
+ if (entry.isDirectory()) walk(full, depth + 1)
332
+ else if (entry.name === 'session.v4.jsonl.zstd') {
333
+ try {
334
+ const stat = fs.statSync(full)
335
+ if (stat.mtimeMs >= since && stat.size <= limits.maxBytes) {
336
+ files.push({ file: full, mtimeMs: stat.mtimeMs, size: stat.size })
337
+ }
338
+ } catch {}
339
+ }
340
+ }
341
+ }
342
+ walk(root, 0)
343
+ files.sort((a, b) => b.mtimeMs - a.mtimeMs)
344
+ return files.slice(0, limits.maxFiles)
345
+ }
346
+
347
+ /**
348
+ * 读取近期会话并汇总。
349
+ * 生成器形式:每个文件之后让出一次,供同步/异步两个入口复用——
350
+ * 同步入口用于 CLI/测试,异步入口用于宿主 RPC(避免解压大日志时卡住事件循环)。
351
+ */
352
+ function* collectReport(options = {}) {
353
+ const home = options.home
354
+ const cachePath = options.cachePath
355
+ const days = options.days ?? 7
356
+ const limits = { maxFiles: options.maxFiles ?? 40, maxBytes: options.maxBytes ?? 16 * 1024 * 1024 }
357
+ const since = Date.now() - days * 24 * 3600 * 1000
358
+ const cache = readCache(cachePath)
359
+ const sessions = []
360
+ const files = []
361
+ const skipped = []
362
+ let decompressed = 0
363
+
364
+ for (const item of collectSessionFiles(home, since, limits)) {
365
+ const key = item.file
366
+ const cached = cache.files[key]
367
+ if (cached && cached.mtimeMs === item.mtimeMs && cached.size === item.size && cached.compact) {
368
+ sessions.push(cached.compact)
369
+ files.push(cached.summary)
370
+ yield
371
+ continue
372
+ }
373
+ try {
374
+ const raw = decompress(fs.readFileSync(item.file))
375
+ decompressed += raw.length
376
+ const parsed = parseSessionJsonl(Buffer.from(raw).toString('utf8'))
377
+ const compact = compactSession(parsed)
378
+ const summary = {
379
+ sessionId: path.basename(path.dirname(item.file)),
380
+ mtimeMs: item.mtimeMs,
381
+ size: item.size,
382
+ steps: compact.stepCount,
383
+ compactions: compact.compactions,
384
+ duplicates: compact.duplicates,
385
+ }
386
+ cache.files[key] = { mtimeMs: item.mtimeMs, size: item.size, compact, summary }
387
+ sessions.push(compact)
388
+ files.push(summary)
389
+ } catch (error) {
390
+ skipped.push({ file: path.basename(path.dirname(item.file)), reason: String(error?.message ?? error) })
391
+ }
392
+ yield
393
+ }
394
+ writeCache(cachePath, cache)
395
+
396
+ const totals = summarize(sessions)
397
+ const deltas = []
398
+ for (const session of sessions) for (const delta of session.deltas) deltas.push(delta)
399
+
400
+ const policies = groupByPolicy(sessions, {
401
+ contextWindow: options.contextWindow,
402
+ thresholdRatio: options.thresholdRatio,
403
+ })
404
+ const currentPolicy = policies.find((policy) => policy.isCurrent) ?? null
405
+ const savings = estimateSavings(deltas, {
406
+ contextWindow: options.contextWindow,
407
+ thresholdRatio: options.thresholdRatio,
408
+ retainRatio: options.retainRatio,
409
+ })
410
+
411
+ return {
412
+ generatedAt: new Date().toISOString(),
413
+ window: { days, since: new Date(since).toISOString() },
414
+ home,
415
+ totals,
416
+ policies,
417
+ // 归因:只有「观测到压缩触发点≈当前阈值」的会话,才算当前配置下的实测数据
418
+ coverage: {
419
+ currentThresholdRatio: options.thresholdRatio ?? null,
420
+ sessionsUnderCurrent: currentPolicy?.totals.sessions ?? 0,
421
+ stepsUnderCurrent: currentPolicy?.totals.steps ?? 0,
422
+ sharePct: totals.steps > 0 ? ((currentPolicy?.totals.steps ?? 0) / totals.steps) * 100 : 0,
423
+ isModelOnly: (currentPolicy?.totals.steps ?? 0) < 200,
424
+ },
425
+ savings,
426
+ files,
427
+ skipped,
428
+ decompressedBytes: decompressed,
429
+ privacy: 'local-only: 只读 ~/.dsh/sessions 下的日志并按路径缓存统计结果;不联网、不上报正文。',
430
+ }
431
+ }
432
+
433
+ export function loadReport(options = {}) {
434
+ const iterator = collectReport(options)
435
+ for (;;) {
436
+ const result = iterator.next()
437
+ if (result.done) return result.value
438
+ }
439
+ }
440
+
441
+ export async function loadReportAsync(options = {}) {
442
+ const iterator = collectReport(options)
443
+ for (;;) {
444
+ const result = iterator.next()
445
+ if (result.done) return result.value
446
+ await new Promise((resolve) => setImmediate(resolve))
447
+ }
448
+ }
package/package.json CHANGED
@@ -1,65 +1,66 @@
1
- {
2
- "name": "dsh-context-kit",
3
- "version": "0.1.0",
4
- "description": "Save context tokens in DSH: a compaction-safe context index, and a tuner that lifts the auto-compaction trigger without freezing the preset — plus a Settings panel for both.",
5
- "type": "module",
6
- "main": "index.js",
7
- "license": "MIT",
8
- "repository": {
9
- "type": "git",
10
- "url": "https://github.com/LISHUANGXI1412/dsh-context-kit"
11
- },
12
- "author": "LISHUANGXI1412",
13
- "keywords": [
14
- "dsh",
15
- "dsh-plugin",
16
- "context",
17
- "compaction",
18
- "agent-preset",
19
- "tokens",
20
- "index"
21
- ],
22
- "engines": {
23
- "node": ">=22"
24
- },
25
- "exports": {
26
- ".": "./index.js",
27
- "./tuner": "./tuner.js",
28
- "./client": "./client/panel.js",
29
- "./icon": "./icon.svg"
30
- },
31
- "files": [
32
- "index.js",
33
- "tuner.js",
34
- "lib/",
35
- "bin/",
36
- "client/",
37
- "cordis.patch.yml",
38
- "icon.svg",
39
- "README.md",
40
- "LICENSE"
41
- ],
42
- "bin": {
43
- "dsh-context-kit": "./bin/dsh-context-kit.mjs"
44
- },
45
- "scripts": {
46
- "test": "node --test"
47
- },
48
- "dsh": {
49
- "bundle": {
50
- "patch": "./cordis.patch.yml"
51
- },
52
- "client": {
53
- "platform": "web",
54
- "inject": [
55
- "@deepseek-ai/dsh-client-runtime",
56
- "@deepseek-ai/dsh-client-ui-slots",
57
- "@deepseek-ai/dsh-client-ui-settings",
58
- "@deepseek-ai/dsh-client-connection"
59
- ]
60
- }
61
- },
62
- "dependencies": {
63
- "@deepseek-ai/dsh-typert-protocol": "0.2.1-rc.2"
64
- }
65
- }
1
+ {
2
+ "name": "dsh-context-kit",
3
+ "version": "0.2.0",
4
+ "description": "Save context tokens in DSH: a compaction-safe context index, and a tuner that lifts the auto-compaction trigger without freezing the preset — plus a Settings panel for both.",
5
+ "type": "module",
6
+ "main": "index.js",
7
+ "license": "MIT",
8
+ "repository": {
9
+ "type": "git",
10
+ "url": "https://github.com/LISHUANGXI1412/dsh-context-kit"
11
+ },
12
+ "author": "LISHUANGXI1412",
13
+ "keywords": [
14
+ "dsh",
15
+ "dsh-plugin",
16
+ "context",
17
+ "compaction",
18
+ "agent-preset",
19
+ "tokens",
20
+ "index"
21
+ ],
22
+ "engines": {
23
+ "node": ">=22"
24
+ },
25
+ "exports": {
26
+ ".": "./index.js",
27
+ "./tuner": "./tuner.js",
28
+ "./client": "./client/panel.js",
29
+ "./icon": "./icon.svg"
30
+ },
31
+ "files": [
32
+ "index.js",
33
+ "tuner.js",
34
+ "lib/",
35
+ "bin/",
36
+ "client/",
37
+ "vendor/",
38
+ "cordis.patch.yml",
39
+ "icon.svg",
40
+ "README.md",
41
+ "LICENSE"
42
+ ],
43
+ "bin": {
44
+ "dsh-context-kit": "./bin/dsh-context-kit.mjs"
45
+ },
46
+ "scripts": {
47
+ "test": "node --test"
48
+ },
49
+ "dsh": {
50
+ "bundle": {
51
+ "patch": "./cordis.patch.yml"
52
+ },
53
+ "client": {
54
+ "platform": "web",
55
+ "inject": [
56
+ "@deepseek-ai/dsh-client-runtime",
57
+ "@deepseek-ai/dsh-client-ui-slots",
58
+ "@deepseek-ai/dsh-client-ui-settings",
59
+ "@deepseek-ai/dsh-client-connection"
60
+ ]
61
+ }
62
+ },
63
+ "dependencies": {
64
+ "@deepseek-ai/dsh-typert-protocol": "0.2.1-rc.2"
65
+ }
66
+ }