dsh-knit 0.14.0 → 0.15.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.
@@ -0,0 +1,641 @@
1
+ /**
2
+ * Knit v0.15 · **Context Feedback / Context Audit**
3
+ *
4
+ * Context Pack 给了「应该先读什么」,这个模块回答**它之后真的被用了吗**。
5
+ * 只有三个事实来源,全部是确定性的:
6
+ *
7
+ * 1. **Context Snapshot** —— Knit 把一份 Context Pack 交出去的那一刻(工具调用 / 面板装配),
8
+ * 记下当时的三层排序。它代表「Knit 当时提供给 Agent 的上下文」。
9
+ * 2. **Context Delta** —— 两次 Snapshot 之间,哪些文档进 / 出 / 换了层。
10
+ * 3. **Read evidence** —— 会话事件流里**真实发生过的 `read` 工具调用**
11
+ * (`tool/call` 配对 `tool/result`,且 `message.isError !== true`)。
12
+ * 搜索命中(`grep` / `glob`)**不算读过** —— 规格 §9。
13
+ *
14
+ * Usage 就是这三者的**连接**:某次读,落在当时那份 Snapshot 的哪一层?
15
+ *
16
+ * ⚠️ 本模块**不碰 Retrieval**(BM25 / IDF / 关键词抽取 / 长度归一化 / freshness 一行不改),
17
+ * 也**不订阅 DSH event bus、不建 Event Store、不落盘、不联网、不调模型**。
18
+ * 它是纯函数 + 一个按会话分片的内存小状态(规格 §10):事件由调用方从
19
+ * `session.snapshotEvents()` 拉出来喂进来,`seq` 当幂等游标,所以 5 秒轮询重复喂同一批事件
20
+ * 不会重复计数。
21
+ *
22
+ * 这里**没有**:trajectory、span、runtime trace、reasoning、成功率、置信度、归一化评分、
23
+ * memory 写入。Usage 不是分数。
24
+ *
25
+ * @module feedback
26
+ */
27
+ import { isAbsolute, relative, resolve, sep } from 'node:path'
28
+
29
+ /** 同时保留多少个会话的状态(LRU 淘汰)。 */
30
+ export const MAX_SESSIONS = 24
31
+ /** 每个会话最多记多少篇**读过**的文档。 */
32
+ export const MAX_READS_PER_SESSION = 200
33
+ /** 每个会话最多保留几份 Snapshot(判断「读的时候是哪一层」要用最近两份)。 */
34
+ export const MAX_SNAPSHOTS_PER_SESSION = 2
35
+ /** 每个会话最多保留多少条 Delta。 */
36
+ export const MAX_DELTAS_PER_SESSION = 20
37
+ /** 最多同时挂起多少个「已调用、还没结果」的 read。 */
38
+ export const MAX_PENDING_CALLS = 64
39
+
40
+ /** 三层,顺序即「先看 → 辅助 → 背景」。 */
41
+ const TIERS = ['primary', 'supporting', 'related']
42
+ /** 唯一算「读过」的工具名。`glob` / `grep` / `bash` 一律不算。 */
43
+ const READ_TOOL = 'read'
44
+
45
+ /* ── 1. 路径 ───────────────────────────────────────────────────────── */
46
+
47
+ /**
48
+ * 把工具参数里的路径归一成**工作区相对路径**(正斜杠)。
49
+ *
50
+ * 归一化失败一律返回空串 —— 调用方据此丢弃这条证据,而不是猜一个路径出来。
51
+ * 丢弃的四种情形:非字符串 / 空串 / URL(`http://`、`file://`)/ 落在工作区根之外。
52
+ *
53
+ * 相对路径**不做** `resolve` —— 工作区里 `a/../b.md` 这种写法工具不会给,
54
+ * 而把相对路径按 DSH 进程的 cwd 去 resolve 只会得到错的东西。
55
+ *
56
+ * @param {string} root - 工作区根(绝对路径)
57
+ * @param {unknown} candidate - 工具给的路径
58
+ * @returns {string} 归一化后的相对路径,或空串
59
+ */
60
+ export function normalizeRel(root, candidate) {
61
+ if (typeof candidate !== 'string') return ''
62
+ const raw = candidate.trim()
63
+ if (!raw || raw.length > 1024) return ''
64
+ if (raw.includes('\0')) return ''
65
+ // 官方 `read` 只接受本地路径;URL 不该出现在这里,出现就丢掉
66
+ if (/^[a-z][a-z0-9+.-]*:\/\//i.test(raw)) return ''
67
+
68
+ let rel = raw
69
+ if (isAbsolute(rel)) {
70
+ // 绝对路径必须落在工作区根之内。root 未知时不猜 —— 直接丢弃。
71
+ if (typeof root !== 'string' || !root) return ''
72
+ const base = resolve(root)
73
+ const abs = resolve(rel)
74
+ if (abs !== base && !abs.startsWith(base + sep)) return ''
75
+ rel = relative(base, abs)
76
+ }
77
+
78
+ rel = rel.split(sep).join('/')
79
+ rel = rel.replace(/^\.\/+/, '').replace(/\/{2,}/g, '/')
80
+ if (!rel || rel === '.') return ''
81
+ if (rel === '..' || rel.startsWith('../')) return ''
82
+ return rel
83
+ }
84
+
85
+ /* ── 2. Snapshot / Delta ───────────────────────────────────────────── */
86
+
87
+ /**
88
+ * 把一份 Context Pack 压成 Snapshot(**只留 rel / 层 / 层内名次**)。
89
+ *
90
+ * 不留 `summary` / `reason` / `mtimeMs`:Usage 要回答的是「读没读、读的是哪一层」,
91
+ * 不是「为什么排在那儿」。少留一份数据就少一份漂移。
92
+ *
93
+ * @param {object} pack - `buildContext()` 的产物(`{primary, supporting, related, task, topic, totals}`)
94
+ * @param {{seq?: number, at?: number}} [meta] - 交出这份包的**事件 seq** 与墙钟时间
95
+ * @returns {object} Snapshot
96
+ */
97
+ export function snapshotOf(pack, meta = {}) {
98
+ const items = []
99
+ for (const tier of TIERS) {
100
+ const list = pack && Array.isArray(pack[tier]) ? pack[tier] : []
101
+ list.forEach((item, index) => {
102
+ const rel = item && typeof item.rel === 'string' ? item.rel : ''
103
+ if (!rel) return
104
+ items.push({ rel, tier, rank: index + 1 })
105
+ })
106
+ }
107
+ const task = pack && typeof pack.task === 'string' ? pack.task : ''
108
+ return {
109
+ seq: Number.isInteger(meta.seq) ? meta.seq : -1,
110
+ at: Number.isFinite(meta.at) ? meta.at : 0,
111
+ topic: (pack && typeof pack.topic === 'string') ? pack.topic : '',
112
+ task,
113
+ total: (pack && pack.totals && Number.isInteger(pack.totals.total)) ? pack.totals.total : 0,
114
+ items,
115
+ sig: signatureOf(items, task),
116
+ }
117
+ }
118
+
119
+ /**
120
+ * 给一份 Snapshot 算个身份串 —— 用来判断「这次和上次是不是同一份上下文」。
121
+ * @param {Array<{rel:string,tier:string,rank:number}>} items - 扁平条目
122
+ * @param {string} task - 任务原文
123
+ * @returns {string} 身份串
124
+ */
125
+ function signatureOf(items, task) {
126
+ return [task, ...items.map((item) => `${item.tier}:${item.rank}:${item.rel}`)].join('\u0000')
127
+ }
128
+
129
+ /**
130
+ * 比较两份 Snapshot:谁进来了、谁出去了、谁换了层。
131
+ *
132
+ * `taskChanged` 单独给一个布尔 —— 任务换了但三层恰好没变(少见但真实)时,
133
+ * 它仍是「上下文变了」,不该被算成 stable。
134
+ *
135
+ * @param {object|null} prev - 上一份 Snapshot
136
+ * @param {object|null} next - 这一份 Snapshot
137
+ * @returns {{appeared: object[], disappeared: object[], moved: object[], taskChanged: boolean, stable: boolean}} 差异
138
+ */
139
+ export function diffContext(prev, next) {
140
+ const before = indexOf(prev)
141
+ const after = indexOf(next)
142
+ const appeared = []
143
+ const disappeared = []
144
+ const moved = []
145
+
146
+ for (const [rel, to] of after) {
147
+ const from = before.get(rel)
148
+ if (!from) appeared.push({ rel, tier: to.tier, rank: to.rank })
149
+ else if (from.tier !== to.tier || from.rank !== to.rank) moved.push({ rel, from, to })
150
+ }
151
+ for (const [rel, from] of before) {
152
+ if (!after.has(rel)) disappeared.push({ rel, tier: from.tier, rank: from.rank })
153
+ }
154
+
155
+ const taskChanged = ((prev && prev.task) || '') !== ((next && next.task) || '')
156
+ return {
157
+ appeared,
158
+ disappeared,
159
+ moved,
160
+ taskChanged,
161
+ stable: appeared.length === 0 && disappeared.length === 0 && moved.length === 0 && !taskChanged,
162
+ }
163
+ }
164
+
165
+ /**
166
+ * 扁平成 `rel → {tier, rank}`。
167
+ * @param {object|null} snapshot - Snapshot
168
+ * @returns {Map<string, {tier:string,rank:number}>} 索引
169
+ */
170
+ function indexOf(snapshot) {
171
+ const map = new Map()
172
+ const items = snapshot && Array.isArray(snapshot.items) ? snapshot.items : []
173
+ for (const item of items) map.set(item.rel, { tier: item.tier, rank: item.rank })
174
+ return map
175
+ }
176
+
177
+ /* ── 3. Read evidence adapter ──────────────────────────────────────── */
178
+
179
+ /**
180
+ * 从会话事件里抽出**真实发生过的 read**。
181
+ *
182
+ * 事件流的真实形状(2026-09-30 实测 `session.v4.jsonl.zstd`):
183
+ * - `tool/call` `data = {turn, step, callId, name, arguments}`,**`arguments` 是 JSON 字符串**
184
+ * - `tool/result` `data = {turn, step, message}`,`message = {toolCallId, source:{callId}, isError, …}`
185
+ *
186
+ * 配对规则:同 `callId`,且结果的 `message.isError !== true`。失败 / 被拒的读**不记账**。
187
+ * 还没等到结果的调用挂在 `pending` 里跨轮次存活(面板 5 秒轮询时,call 与 result 常常分属两次读数)。
188
+ *
189
+ * 幂等靠 `fromSeq` 游标:只处理 `seq > fromSeq` 的事件,所以同一批事件喂两遍不会重复计数。
190
+ *
191
+ * @param {object[]} events - `session.snapshotEvents()` 的产物
192
+ * @param {{root?: string, fromSeq?: number, pending?: Map<string, object>}} [options] - 选项
193
+ * @returns {{reads: object[], cursor: number, pending: Map<string, object>}} 证据、新游标、挂起表
194
+ */
195
+ export function normalizeReadEvidence(events, options = {}) {
196
+ const root = options.root
197
+ const fromSeq = Number.isInteger(options.fromSeq) ? options.fromSeq : -1
198
+ const pending = options.pending instanceof Map ? options.pending : new Map()
199
+ const reads = []
200
+ let cursor = fromSeq
201
+ if (!Array.isArray(events)) return { reads, cursor, pending }
202
+
203
+ for (const event of events) {
204
+ if (!event || typeof event.type !== 'string') continue
205
+ const seq = Number.isInteger(event.seq) ? event.seq : -1
206
+ if (seq < 0 || seq <= fromSeq) continue
207
+ if (seq > cursor) cursor = seq
208
+
209
+ if (event.type === 'tool/call') {
210
+ const data = event.data || {}
211
+ if (data.name !== READ_TOOL) continue
212
+ const args = parseArguments(data.arguments)
213
+ const rel = normalizeRel(root, args.file_path || args.path || args.filePath)
214
+ const callId = typeof data.callId === 'string' ? data.callId : ''
215
+ if (!rel || !callId) continue
216
+ pending.set(callId, {
217
+ rel,
218
+ seq,
219
+ time: Number.isFinite(event.time) ? event.time : 0,
220
+ })
221
+ // 挂起表也要有上限:只调用不返回的会话不许把它撑大
222
+ while (pending.size > MAX_PENDING_CALLS) {
223
+ const oldest = pending.keys().next().value
224
+ if (oldest === callId) break
225
+ pending.delete(oldest)
226
+ }
227
+ } else if (event.type === 'tool/result') {
228
+ const message = (event.data && event.data.message) || {}
229
+ const callId = String(
230
+ message.toolCallId || (message.source && message.source.callId) || '',
231
+ )
232
+ if (!callId) continue
233
+ const call = pending.get(callId)
234
+ if (!call) continue
235
+ pending.delete(callId)
236
+ // 失败的读不是「读过了」—— 规格 §9
237
+ if (message.isError === true) continue
238
+ reads.push({
239
+ rel: call.rel,
240
+ callId,
241
+ callSeq: call.seq,
242
+ seq,
243
+ time: Number.isFinite(event.time) ? event.time : call.time,
244
+ })
245
+ }
246
+ }
247
+
248
+ return { reads, cursor, pending }
249
+ }
250
+
251
+ /**
252
+ * 解析 `tool/call` 的 `arguments`(实测是 JSON **字符串**)。
253
+ * 解析不出来就当没有参数 —— 这条证据会被丢弃,而不是猜一个路径。
254
+ * @param {unknown} raw - 原始参数
255
+ * @returns {object} 参数对象
256
+ */
257
+ function parseArguments(raw) {
258
+ if (raw && typeof raw === 'object') return raw
259
+ if (typeof raw !== 'string' || !raw) return {}
260
+ try {
261
+ const parsed = JSON.parse(raw)
262
+ return parsed && typeof parsed === 'object' ? parsed : {}
263
+ } catch {
264
+ return {}
265
+ }
266
+ }
267
+
268
+ /* ── 4. 按会话分片的内存状态 ───────────────────────────────────────── */
269
+
270
+ /**
271
+ * 建一个空的 feedback store(内存态,进程活着才在)。
272
+ * @returns {{sessions: Map<string, object>, order: string[], audited: Set<string>}} store
273
+ */
274
+ export function createStore() {
275
+ return { sessions: new Map(), order: [], audited: new Set() }
276
+ }
277
+
278
+ /**
279
+ * 标记这个会话「被审计了」—— 之后它的面板请求才会被记账。
280
+ *
281
+ * 默认**不记账**:没人看「使用情况」、Agent 也没要 audit 的会话,
282
+ * 不该在内存里攒快照。这一点是刻意的(内存有上限、行为可预期)。
283
+ *
284
+ * @param {object} store - store
285
+ * @param {string} sessionId - 会话 id
286
+ * @returns {boolean} 是否成功
287
+ */
288
+ export function activateAudit(store, sessionId) {
289
+ try {
290
+ if (!store || !sessionId) return false
291
+ stateOf(store, sessionId)
292
+ store.audited.add(sessionId)
293
+ while (store.audited.size > MAX_SESSIONS) {
294
+ const oldest = store.audited.values().next().value
295
+ if (oldest === sessionId) break
296
+ store.audited.delete(oldest)
297
+ }
298
+ return true
299
+ } catch {
300
+ return false
301
+ }
302
+ }
303
+
304
+ /**
305
+ * 这个会话是否在记账。
306
+ * @param {object} store - store
307
+ * @param {string} sessionId - 会话 id
308
+ * @returns {boolean} 是否记账
309
+ */
310
+ export function isAudited(store, sessionId) {
311
+ return !!(store && sessionId && store.audited.has(sessionId))
312
+ }
313
+
314
+ /**
315
+ * 取(或建)一个会话的状态,并按 LRU 触摸 —— 会话数量超上限时淘汰最久没碰的。
316
+ * @param {object} store - store
317
+ * @param {string} sessionId - 会话 id
318
+ * @returns {object} 会话状态
319
+ */
320
+ function stateOf(store, sessionId) {
321
+ let state = store.sessions.get(sessionId)
322
+ if (!state) {
323
+ state = {
324
+ seq: -1, // 已消费到的事件 seq(幂等游标)
325
+ pending: new Map(), // 已调用、还没结果的 read
326
+ snapshots: [], // 最近两份 Context Pack
327
+ deltas: [], // 最近若干条变化
328
+ reads: new Map(), // rel → 计数
329
+ readOrder: [], // rel 的插入顺序(淘汰用)
330
+ // ⚠️ `changes` 是**累计**的上下文替换次数,与 `deltas` 数组的长度无关 ——
331
+ // 数组会被上限砍掉,但「这个会话里上下文变过几次」不能被砍(那正是 churn 这个指标)。
332
+ churn: { changes: 0, appeared: 0, disappeared: 0, moved: 0, taskChanged: 0 },
333
+ }
334
+ store.sessions.set(sessionId, state)
335
+ }
336
+ const at = store.order.indexOf(sessionId)
337
+ if (at >= 0) store.order.splice(at, 1)
338
+ store.order.push(sessionId)
339
+ while (store.order.length > MAX_SESSIONS) {
340
+ const gone = store.order.shift()
341
+ store.sessions.delete(gone)
342
+ }
343
+ return state
344
+ }
345
+
346
+ /* ── 5. 入口:喂事件 / 记快照 / 取使用情况 ─────────────────────────── */
347
+
348
+ /**
349
+ * 把一批会话事件喂进去,抽出 read 并记账。
350
+ *
351
+ * **任何异常都咽掉并返回 `{ok:false}`** —— 记账失败绝不能让面板或工具失败(规格 §33)。
352
+ *
353
+ * @param {object} store - store
354
+ * @param {string} sessionId - 会话 id
355
+ * @param {object[]} events - 会话事件
356
+ * @param {{root?: string}} [options] - 选项
357
+ * @returns {{ok: boolean, reads: number, cursor: number}} 结果
358
+ */
359
+ export function ingestEvents(store, sessionId, events, options = {}) {
360
+ try {
361
+ if (!store || !sessionId) return { ok: false, reads: 0, cursor: -1 }
362
+ const state = stateOf(store, sessionId)
363
+ const { reads, cursor, pending } = normalizeReadEvidence(events, {
364
+ root: options.root,
365
+ fromSeq: state.seq,
366
+ pending: state.pending,
367
+ })
368
+ state.pending = pending
369
+ if (cursor > state.seq) state.seq = cursor
370
+ for (const read of reads) recordRead(state, read)
371
+ return { ok: true, reads: reads.length, cursor: state.seq }
372
+ } catch {
373
+ return { ok: false, reads: 0, cursor: -1 }
374
+ }
375
+ }
376
+
377
+ /**
378
+ * 记下「Knit 刚刚交出了这份 Context Pack」。
379
+ *
380
+ * 与上一份**同签名**时不记新快照(只把时间 / seq 往前推)—— 否则 5 秒轮询会把
381
+ * 同一份上下文记成几十份,Delta churn 立刻变成噪音。
382
+ *
383
+ * @param {object} store - store
384
+ * @param {string} sessionId - 会话 id
385
+ * @param {object} pack - Context Pack
386
+ * @param {{seq?: number, at?: number}} [meta] - 事件 seq 与时间
387
+ * @returns {{snapshot: object, delta: object|null}|null} 新快照与它带来的变化(无变化时 null)
388
+ */
389
+ export function noteSnapshot(store, sessionId, pack, meta = {}) {
390
+ try {
391
+ if (!store || !sessionId || !pack) return null
392
+ const state = stateOf(store, sessionId)
393
+ const next = snapshotOf(pack, meta)
394
+ const prev = state.snapshots[state.snapshots.length - 1] || null
395
+
396
+ if (prev && prev.sig === next.sig) {
397
+ if (next.at > prev.at) prev.at = next.at
398
+ if (next.seq > prev.seq) prev.seq = next.seq
399
+ return null
400
+ }
401
+
402
+ state.snapshots.push(next)
403
+ while (state.snapshots.length > MAX_SNAPSHOTS_PER_SESSION) state.snapshots.shift()
404
+
405
+ let delta = null
406
+ if (prev) {
407
+ delta = { at: next.at, seq: next.seq, ...diffContext(prev, next) }
408
+ state.deltas.push(delta)
409
+ while (state.deltas.length > MAX_DELTAS_PER_SESSION) state.deltas.shift()
410
+ state.churn.changes += 1
411
+ state.churn.appeared += delta.appeared.length
412
+ state.churn.disappeared += delta.disappeared.length
413
+ state.churn.moved += delta.moved.length
414
+ if (delta.taskChanged) state.churn.taskChanged += 1
415
+ }
416
+ return { snapshot: next, delta }
417
+ } catch {
418
+ return null
419
+ }
420
+ }
421
+
422
+ /**
423
+ * 记一次真实读。**不属于任何快照的读 = outside context**(这不是错,是信息)。
424
+ * @param {object} state - 会话状态
425
+ * @param {object} read - 归一化后的 read 证据
426
+ */
427
+ function recordRead(state, read) {
428
+ const snapshot = snapshotAt(state.snapshots, read.seq)
429
+ const hit = snapshot ? snapshot.items.find((item) => item.rel === read.rel) : null
430
+ const inside = !!hit
431
+ const tier = hit ? hit.tier : null
432
+ const rank = hit ? hit.rank : null
433
+
434
+ let entry = state.reads.get(read.rel)
435
+ if (!entry) {
436
+ entry = {
437
+ rel: read.rel,
438
+ count: 1,
439
+ firstReadAt: read.time,
440
+ firstReadSeq: read.seq,
441
+ firstTier: tier,
442
+ firstRank: rank,
443
+ lastReadAt: read.time,
444
+ lastTier: tier,
445
+ outside: !inside,
446
+ outsideCount: inside ? 0 : 1,
447
+ }
448
+ state.reads.set(read.rel, entry)
449
+ state.readOrder.push(read.rel)
450
+ while (state.readOrder.length > MAX_READS_PER_SESSION) {
451
+ state.reads.delete(state.readOrder.shift())
452
+ }
453
+ return
454
+ }
455
+
456
+ entry.count += 1
457
+ entry.lastReadAt = read.time
458
+ entry.lastTier = tier
459
+ if (!inside) {
460
+ entry.outside = true
461
+ entry.outsideCount += 1
462
+ }
463
+ if (!Number.isFinite(entry.firstReadAt) || read.time < entry.firstReadAt) {
464
+ entry.firstReadAt = read.time
465
+ entry.firstReadSeq = read.seq
466
+ entry.firstTier = tier
467
+ entry.firstRank = rank
468
+ }
469
+ }
470
+
471
+ /**
472
+ * 找出**这次读发生的那一刻**在生效的那份快照(seq ≤ 读的 seq 里最新的那份)。
473
+ * 找不到就返回 null —— 那是「Knit 还没给过上下文就自己读了」,如实记成 outside。
474
+ * @param {object[]} snapshots - 快照栈
475
+ * @param {number} seq - 读的 seq
476
+ * @returns {object|null} 快照
477
+ */
478
+ function snapshotAt(snapshots, seq) {
479
+ for (let i = snapshots.length - 1; i >= 0; i -= 1) {
480
+ if (snapshots[i].seq <= seq) return snapshots[i]
481
+ }
482
+ return null
483
+ }
484
+
485
+ /**
486
+ * 取一个会话当前的使用情况。没有记录时返回 `null`(不编造空报告)。
487
+ * @param {object} store - store
488
+ * @param {string} sessionId - 会话 id
489
+ * @returns {object|null} 使用情况
490
+ */
491
+ export function usageFor(store, sessionId) {
492
+ try {
493
+ const state = store && store.sessions.get(sessionId)
494
+ if (!state) return null
495
+ return usageFrom(state)
496
+ } catch {
497
+ return null
498
+ }
499
+ }
500
+
501
+ /**
502
+ * 纯函数版:从一个会话状态算出使用情况(测试直接用这个)。
503
+ *
504
+ * 报告里只有**计数与事实**:读了几次、落在哪一层、有几篇在快照之外、
505
+ * 上下文变了几次。**没有分数、没有百分比评分、没有「相关性」**。
506
+ *
507
+ * @param {object} state - 会话状态
508
+ * @returns {object} 使用情况
509
+ */
510
+ export function usageFrom(state) {
511
+ const snapshots = (state && state.snapshots) || []
512
+ const snapshot = snapshots[snapshots.length - 1] || null
513
+ const byTier = {
514
+ primary: { total: 0, read: 0 },
515
+ supporting: { total: 0, read: 0 },
516
+ related: { total: 0, read: 0 },
517
+ }
518
+ if (snapshot) {
519
+ for (const item of snapshot.items) {
520
+ if (byTier[item.tier]) byTier[item.tier].total += 1
521
+ }
522
+ }
523
+
524
+ const reads = []
525
+ for (const entry of state.reads.values()) {
526
+ const hit = snapshot ? snapshot.items.find((item) => item.rel === entry.rel) : null
527
+ reads.push({
528
+ rel: entry.rel,
529
+ count: entry.count,
530
+ firstReadAt: entry.firstReadAt,
531
+ firstReadSeq: entry.firstReadSeq,
532
+ firstTier: entry.firstTier || null,
533
+ tier: hit ? hit.tier : null,
534
+ rank: hit ? hit.rank : null,
535
+ outside: !hit,
536
+ outsideCount: entry.outsideCount || 0,
537
+ })
538
+ }
539
+ reads.sort((a, b) => a.firstReadSeq - b.firstReadSeq)
540
+ for (const row of reads) if (row.tier && byTier[row.tier]) byTier[row.tier].read += 1
541
+
542
+ const outside = reads.filter((row) => row.outside)
543
+ const first = reads[0] || null
544
+ const primary = snapshot ? snapshot.items.find((item) => item.tier === 'primary' && item.rank === 1) : null
545
+ const supportingTotal = byTier.supporting.total
546
+
547
+ return {
548
+ at: snapshot ? snapshot.at : 0,
549
+ seq: snapshot ? snapshot.seq : -1,
550
+ task: snapshot ? snapshot.task : '',
551
+ topic: snapshot ? snapshot.topic : '',
552
+ items: snapshot ? snapshot.items.map((item) => ({ ...item })) : [],
553
+ reads,
554
+ delta: state.deltas[state.deltas.length - 1] || null,
555
+ stats: {
556
+ reads: reads.reduce((sum, row) => sum + row.count, 0),
557
+ distinct: reads.length,
558
+ outside: outside.length,
559
+ outsideReads: outside.map((row) => row.rel),
560
+ firstReadTier: first ? first.tier : null,
561
+ firstReadRel: first ? first.rel : '',
562
+ firstReadAt: first ? first.firstReadAt : 0,
563
+ primaryRel: primary ? primary.rel : '',
564
+ // 「先看的那篇被读了吗」—— 这不是成功率,只是一次真实的命中
565
+ primaryFollowThrough: !!(primary && reads.some((row) => row.rel === primary.rel)),
566
+ byTier,
567
+ supportingCoverage: supportingTotal === 0 ? null : byTier.supporting.read / supportingTotal,
568
+ churn: {
569
+ // 累计变过几次(不受 Delta 数组上限影响)
570
+ snapshots: state.churn.changes,
571
+ deltas: state.churn.changes,
572
+ // 手上还留着几条 Delta 明细
573
+ retained: state.deltas.length,
574
+ appeared: state.churn.appeared,
575
+ disappeared: state.churn.disappeared,
576
+ moved: state.churn.moved,
577
+ taskChanged: state.churn.taskChanged,
578
+ },
579
+ },
580
+ }
581
+ }
582
+
583
+ /**
584
+ * 给 Agent 看的**极短**摘要(结构化、无分数)。
585
+ * @param {object|null} usage - `usageFrom()` 的结果
586
+ * @returns {object|null} 摘要
587
+ */
588
+ export function auditPayload(usage) {
589
+ if (!usage || !usage.stats) return null
590
+ const s = usage.stats
591
+ return {
592
+ primaryRead: !!s.primaryFollowThrough,
593
+ primaryRel: String(s.primaryRel || ''),
594
+ supportingRead: s.byTier.supporting.read,
595
+ supportingTotal: s.byTier.supporting.total,
596
+ readsOutside: s.outside,
597
+ contextChanges: s.churn.deltas,
598
+ }
599
+ }
600
+
601
+ /**
602
+ * 给 Agent 看的那一句话(`knit_docs` 渲染在末尾)。没有可说的就返回空串。
603
+ * @param {object|null} usage - `usageFrom()` 的结果
604
+ * @returns {string} 一行文本
605
+ */
606
+ export function getAuditSummary(usage) {
607
+ const payload = auditPayload(usage)
608
+ if (!payload) return ''
609
+ const parts = []
610
+ if (payload.primaryRel) {
611
+ parts.push(payload.primaryRead
612
+ ? `primary read (${payload.primaryRel})`
613
+ : `primary not read yet (${payload.primaryRel})`)
614
+ }
615
+ if (payload.supportingTotal > 0) {
616
+ parts.push(`supporting ${payload.supportingRead}/${payload.supportingTotal}`)
617
+ }
618
+ if (payload.readsOutside > 0) parts.push(`${payload.readsOutside} read outside the pack`)
619
+ if (payload.contextChanges > 0) parts.push(`context changed ${payload.contextChanges}×`)
620
+ if (parts.length === 0) return ''
621
+ return `Usage since the last pack: ${parts.join(' · ')}.`
622
+ }
623
+
624
+ /**
625
+ * 复位一个会话(或整个 store)。给测试与「重新开始记账」用。
626
+ * @param {object} store - store
627
+ * @param {string} [sessionId] - 省略则清空全部
628
+ */
629
+ export function resetStore(store, sessionId) {
630
+ if (!store) return
631
+ if (sessionId) {
632
+ store.sessions.delete(sessionId)
633
+ store.audited.delete(sessionId)
634
+ const at = store.order.indexOf(sessionId)
635
+ if (at >= 0) store.order.splice(at, 1)
636
+ return
637
+ }
638
+ store.sessions.clear()
639
+ store.order.length = 0
640
+ store.audited.clear()
641
+ }