dsh-knit 0.15.0 → 0.16.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/CHANGELOG.md +227 -0
- package/README.en.md +26 -12
- package/README.md +30 -15
- package/package.json +2 -2
- package/src/client/client.js +151 -99
- package/src/host/feedback.js +302 -85
- package/src/host/index.js +66 -49
- package/src/host/tool.js +8 -9
- package/test/client.test.mjs +180 -31
- package/test/context-delta.test.mjs +20 -7
- package/test/context-effectiveness.test.mjs +309 -0
- package/test/context-feedback-eval.test.mjs +36 -5
- package/test/host-http.test.mjs +101 -46
- package/test/i18n.test.mjs +19 -21
- package/test/path.test.mjs +6 -6
- package/test/peek.test.mjs +80 -26
- package/test/tool.test.mjs +11 -9
- package/tools/context-feedback-eval.mjs +46 -14
package/src/host/feedback.js
CHANGED
|
@@ -1,26 +1,30 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Knit v0.
|
|
2
|
+
* Knit v0.16 · **Context Feedback / Context Effectiveness**
|
|
3
3
|
*
|
|
4
4
|
* Context Pack 给了「应该先读什么」,这个模块回答**它之后真的被用了吗**。
|
|
5
5
|
* 只有三个事实来源,全部是确定性的:
|
|
6
6
|
*
|
|
7
|
-
* 1. **Context Snapshot** —— Knit 把一份 Context Pack
|
|
8
|
-
*
|
|
9
|
-
* 2. **Context Delta** —— 两次 Snapshot 之间,哪些文档进 / 出 /
|
|
7
|
+
* 1. **Context Snapshot / Epoch** —— Knit 把一份 Context Pack 交出去的那一刻
|
|
8
|
+
* (工具调用 / 面板装配),记下当时的三层排序与它的 `epochId`。
|
|
9
|
+
* 2. **Context Delta** —— 两次 Snapshot 之间,哪些文档进 / 出 / 换了层,以及 `fromEpoch → toEpoch`。
|
|
10
10
|
* 3. **Read evidence** —— 会话事件流里**真实发生过的 `read` 工具调用**
|
|
11
11
|
* (`tool/call` 配对 `tool/result`,且 `message.isError !== true`)。
|
|
12
|
-
* 搜索命中(`grep` / `glob
|
|
12
|
+
* 搜索命中(`grep` / `glob`)**不算读过**。
|
|
13
13
|
*
|
|
14
|
-
* Usage
|
|
14
|
+
* Usage 就是这三者的**连接**,而且连接发生在**读的那一刻**:
|
|
15
|
+
* 每条 read 落库时就按 `snapshotAt(read.seq)` 结算出 `tierAtRead` / `rankAtRead` /
|
|
16
|
+
* `insideAtRead` / `epochId` 并**冻结**。之后上下文再怎么变,历史归因都不许重算 ——
|
|
17
|
+
* 「当前视图」与「历史视图」是两件事。
|
|
15
18
|
*
|
|
16
19
|
* ⚠️ 本模块**不碰 Retrieval**(BM25 / IDF / 关键词抽取 / 长度归一化 / freshness 一行不改),
|
|
17
|
-
*
|
|
18
|
-
*
|
|
19
|
-
* `session.snapshotEvents()`
|
|
20
|
-
*
|
|
20
|
+
* 也**不落盘、不联网、不调模型、不写 memory、不自动干预上下文**。
|
|
21
|
+
* 读证据的唯一来源是宿主派发的 `session/event`(v0.16 起):**不再**调用
|
|
22
|
+
* `session.snapshotEvents()` —— 那个 API 已被 DSH 标记 deprecated
|
|
23
|
+
* (「new production calls are prohibited」),而且它在 fork 会话上会把父会话继承来的
|
|
24
|
+
* 前缀事件也算进来。代价是:订阅之前发生的事件不回溯,只记订阅之后真实发生的读。
|
|
21
25
|
*
|
|
22
26
|
* 这里**没有**:trajectory、span、runtime trace、reasoning、成功率、置信度、归一化评分、
|
|
23
|
-
* memory 写入。Usage
|
|
27
|
+
* quality score、memory 写入。Usage 不是分数,是计数与事实。
|
|
24
28
|
*
|
|
25
29
|
* @module feedback
|
|
26
30
|
*/
|
|
@@ -30,10 +34,15 @@ import { isAbsolute, relative, resolve, sep } from 'node:path'
|
|
|
30
34
|
export const MAX_SESSIONS = 24
|
|
31
35
|
/** 每个会话最多记多少篇**读过**的文档。 */
|
|
32
36
|
export const MAX_READS_PER_SESSION = 200
|
|
33
|
-
/** 每个会话最多保留几份 Snapshot
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
+
/** 每个会话最多保留几份 Snapshot / Epoch。
|
|
38
|
+
*
|
|
39
|
+
* v0.16 由 2 提到 20:归因本身**在 Read 时结算**,保留数量不影响它的正确性;
|
|
40
|
+
* 它只决定 `continuedReadAfterExit` / `reEntry` 这两个事实能回溯多远
|
|
41
|
+
* (要能看见「离开过、又回来」就必须留着中间那几份)。
|
|
42
|
+
*/
|
|
43
|
+
export const MAX_SNAPSHOTS_PER_SESSION = 20
|
|
44
|
+
/** 每个会话最多保留多少条 Delta 明细(计数不受它影响)。 */
|
|
45
|
+
export const MAX_DELTAS_PER_SESSION = 50
|
|
37
46
|
/** 最多同时挂起多少个「已调用、还没结果」的 read。 */
|
|
38
47
|
export const MAX_PENDING_CALLS = 64
|
|
39
48
|
|
|
@@ -134,7 +143,7 @@ function signatureOf(items, task) {
|
|
|
134
143
|
*
|
|
135
144
|
* @param {object|null} prev - 上一份 Snapshot
|
|
136
145
|
* @param {object|null} next - 这一份 Snapshot
|
|
137
|
-
* @returns {{appeared: object[], disappeared: object[], moved: object[], taskChanged: boolean, stable: boolean}} 差异
|
|
146
|
+
* @returns {{appeared: object[], disappeared: object[], moved: object[], taskChanged: boolean, fromEpoch: number|null, toEpoch: number|null, stable: boolean}} 差异
|
|
138
147
|
*/
|
|
139
148
|
export function diffContext(prev, next) {
|
|
140
149
|
const before = indexOf(prev)
|
|
@@ -158,6 +167,9 @@ export function diffContext(prev, next) {
|
|
|
158
167
|
disappeared,
|
|
159
168
|
moved,
|
|
160
169
|
taskChanged,
|
|
170
|
+
// 哪两个 Epoch 之间的变化(没有上一份时 fromEpoch 为 null)
|
|
171
|
+
fromEpoch: prev && Number.isInteger(prev.epochId) ? prev.epochId : null,
|
|
172
|
+
toEpoch: next && Number.isInteger(next.epochId) ? next.epochId : null,
|
|
161
173
|
stable: appeared.length === 0 && disappeared.length === 0 && moved.length === 0 && !taskChanged,
|
|
162
174
|
}
|
|
163
175
|
}
|
|
@@ -188,7 +200,7 @@ function indexOf(snapshot) {
|
|
|
188
200
|
*
|
|
189
201
|
* 幂等靠 `fromSeq` 游标:只处理 `seq > fromSeq` 的事件,所以同一批事件喂两遍不会重复计数。
|
|
190
202
|
*
|
|
191
|
-
* @param {object[]} events - `session
|
|
203
|
+
* @param {object[]} events - 会话事件(v0.16 起由 `session/event` 订阅逐条喂进来)
|
|
192
204
|
* @param {{root?: string, fromSeq?: number, pending?: Map<string, object>}} [options] - 选项
|
|
193
205
|
* @returns {{reads: object[], cursor: number, pending: Map<string, object>}} 证据、新游标、挂起表
|
|
194
206
|
*/
|
|
@@ -264,7 +276,6 @@ function parseArguments(raw) {
|
|
|
264
276
|
return {}
|
|
265
277
|
}
|
|
266
278
|
}
|
|
267
|
-
|
|
268
279
|
/* ── 4. 按会话分片的内存状态 ───────────────────────────────────────── */
|
|
269
280
|
|
|
270
281
|
/**
|
|
@@ -276,7 +287,7 @@ export function createStore() {
|
|
|
276
287
|
}
|
|
277
288
|
|
|
278
289
|
/**
|
|
279
|
-
* 标记这个会话「被审计了」——
|
|
290
|
+
* 标记这个会话「被审计了」—— 之后它的读事件与面板请求才会被记账。
|
|
280
291
|
*
|
|
281
292
|
* 默认**不记账**:没人看「使用情况」、Agent 也没要 audit 的会话,
|
|
282
293
|
* 不该在内存里攒快照。这一点是刻意的(内存有上限、行为可预期)。
|
|
@@ -302,7 +313,8 @@ export function activateAudit(store, sessionId) {
|
|
|
302
313
|
}
|
|
303
314
|
|
|
304
315
|
/**
|
|
305
|
-
*
|
|
316
|
+
* 这个会话是否在记账。**订阅回调的第一行就用它早退** ——
|
|
317
|
+
* 没记账的会话一次 Map 查找就返回,不做任何别的工作。
|
|
306
318
|
* @param {object} store - store
|
|
307
319
|
* @param {string} sessionId - 会话 id
|
|
308
320
|
* @returns {boolean} 是否记账
|
|
@@ -321,15 +333,16 @@ function stateOf(store, sessionId) {
|
|
|
321
333
|
let state = store.sessions.get(sessionId)
|
|
322
334
|
if (!state) {
|
|
323
335
|
state = {
|
|
324
|
-
seq: -1, // 已消费到的事件 seq
|
|
336
|
+
seq: -1, // 已消费到的事件 seq(幂等游标;也是「当前水位」)
|
|
325
337
|
pending: new Map(), // 已调用、还没结果的 read
|
|
326
|
-
snapshots: [], //
|
|
338
|
+
snapshots: [], // 最近 MAX_SNAPSHOTS_PER_SESSION 份 Context Pack(每份 = 一个 Epoch)
|
|
339
|
+
epochs: [], // 与 snapshots 一一对应的 Epoch 级计数
|
|
327
340
|
deltas: [], // 最近若干条变化
|
|
328
|
-
reads: new Map(), // rel →
|
|
341
|
+
reads: new Map(), // rel → 冻结的读归因
|
|
329
342
|
readOrder: [], // rel 的插入顺序(淘汰用)
|
|
330
|
-
// ⚠️ `changes`
|
|
331
|
-
//
|
|
332
|
-
churn: {
|
|
343
|
+
// ⚠️ 这里**不再**有 `changes` 计数:上下文换过几次 = 最后一个 Epoch 的编号 - 1,
|
|
344
|
+
// 而 Epoch 编号是单调的(被淘汰的 Epoch 也计过数),所以不需要额外记一个累计值。
|
|
345
|
+
churn: { appeared: 0, disappeared: 0, moved: 0, taskChanged: 0 },
|
|
333
346
|
}
|
|
334
347
|
store.sessions.set(sessionId, state)
|
|
335
348
|
}
|
|
@@ -346,9 +359,12 @@ function stateOf(store, sessionId) {
|
|
|
346
359
|
/* ── 5. 入口:喂事件 / 记快照 / 取使用情况 ─────────────────────────── */
|
|
347
360
|
|
|
348
361
|
/**
|
|
349
|
-
*
|
|
362
|
+
* 把**一批**会话事件喂进去,抽出 read 并按「读发生的那一刻」结算归因。
|
|
363
|
+
*
|
|
364
|
+
* v0.16 起调用方通常一次只喂一条(`session/event` 订阅)。仍然是幂等的:
|
|
365
|
+
* 只处理 `seq > state.seq` 的事件,重复喂同一批不会重复计数。
|
|
350
366
|
*
|
|
351
|
-
* **任何异常都咽掉并返回 `{ok:false}`** ——
|
|
367
|
+
* **任何异常都咽掉并返回 `{ok:false}`** —— 记账失败绝不能让面板或工具失败。
|
|
352
368
|
*
|
|
353
369
|
* @param {object} store - store
|
|
354
370
|
* @param {string} sessionId - 会话 id
|
|
@@ -380,6 +396,9 @@ export function ingestEvents(store, sessionId, events, options = {}) {
|
|
|
380
396
|
* 与上一份**同签名**时不记新快照(只把时间 / seq 往前推)—— 否则 5 秒轮询会把
|
|
381
397
|
* 同一份上下文记成几十份,Delta churn 立刻变成噪音。
|
|
382
398
|
*
|
|
399
|
+
* `meta.seq` 省略时用会话当前的**事件水位**(`state.seq`)—— 也就是「交包这一刻,
|
|
400
|
+
* 已经发生到第几个事件」。这正是历史归因要的边界:seq ≤ 它的读算在这份包里。
|
|
401
|
+
*
|
|
383
402
|
* @param {object} store - store
|
|
384
403
|
* @param {string} sessionId - 会话 id
|
|
385
404
|
* @param {object} pack - Context Pack
|
|
@@ -390,24 +409,34 @@ export function noteSnapshot(store, sessionId, pack, meta = {}) {
|
|
|
390
409
|
try {
|
|
391
410
|
if (!store || !sessionId || !pack) return null
|
|
392
411
|
const state = stateOf(store, sessionId)
|
|
393
|
-
const next = snapshotOf(pack,
|
|
412
|
+
const next = snapshotOf(pack, {
|
|
413
|
+
seq: Number.isInteger(meta.seq) ? meta.seq : state.seq,
|
|
414
|
+
at: meta.at,
|
|
415
|
+
})
|
|
394
416
|
const prev = state.snapshots[state.snapshots.length - 1] || null
|
|
395
417
|
|
|
396
418
|
if (prev && prev.sig === next.sig) {
|
|
397
419
|
if (next.at > prev.at) prev.at = next.at
|
|
398
420
|
if (next.seq > prev.seq) prev.seq = next.seq
|
|
421
|
+
const epoch = epochIn(state, prev.epochId)
|
|
422
|
+
if (epoch && prev.seq > epoch.snapshotSeq) epoch.snapshotSeq = prev.seq
|
|
399
423
|
return null
|
|
400
424
|
}
|
|
401
425
|
|
|
426
|
+
// Epoch 编号从这里发出:新建一份上下文 = 一个新 Epoch。同签名不算新 Epoch。
|
|
427
|
+
next.epochId = prev && Number.isInteger(prev.epochId) ? prev.epochId + 1 : 1
|
|
402
428
|
state.snapshots.push(next)
|
|
403
|
-
|
|
429
|
+
state.epochs.push(createEpoch(next))
|
|
430
|
+
while (state.snapshots.length > MAX_SNAPSHOTS_PER_SESSION) {
|
|
431
|
+
state.snapshots.shift()
|
|
432
|
+
state.epochs.shift()
|
|
433
|
+
}
|
|
404
434
|
|
|
405
435
|
let delta = null
|
|
406
436
|
if (prev) {
|
|
407
437
|
delta = { at: next.at, seq: next.seq, ...diffContext(prev, next) }
|
|
408
438
|
state.deltas.push(delta)
|
|
409
439
|
while (state.deltas.length > MAX_DELTAS_PER_SESSION) state.deltas.shift()
|
|
410
|
-
state.churn.changes += 1
|
|
411
440
|
state.churn.appeared += delta.appeared.length
|
|
412
441
|
state.churn.disappeared += delta.disappeared.length
|
|
413
442
|
state.churn.moved += delta.moved.length
|
|
@@ -420,68 +449,205 @@ export function noteSnapshot(store, sessionId, pack, meta = {}) {
|
|
|
420
449
|
}
|
|
421
450
|
|
|
422
451
|
/**
|
|
423
|
-
*
|
|
452
|
+
* 给一个新 Epoch 建计数骨架(总量取自这份快照,已读量靠后续 read 累加)。
|
|
453
|
+
* @param {object} snapshot - 刚记下的快照(已带 epochId)
|
|
454
|
+
* @returns {object} Epoch 记录
|
|
455
|
+
*/
|
|
456
|
+
function createEpoch(snapshot) {
|
|
457
|
+
const counts = {
|
|
458
|
+
primary: { total: 0, read: 0 },
|
|
459
|
+
supporting: { total: 0, read: 0 },
|
|
460
|
+
related: { total: 0, read: 0 },
|
|
461
|
+
}
|
|
462
|
+
for (const item of snapshot.items) {
|
|
463
|
+
const bucket = counts[item.tier]
|
|
464
|
+
if (bucket) bucket.total += 1
|
|
465
|
+
}
|
|
466
|
+
const primary = snapshot.items.find((item) => item.tier === 'primary' && item.rank === 1)
|
|
467
|
+
return {
|
|
468
|
+
epochId: snapshot.epochId,
|
|
469
|
+
snapshotSeq: snapshot.seq,
|
|
470
|
+
topic: snapshot.topic,
|
|
471
|
+
task: snapshot.task,
|
|
472
|
+
primary: { rel: primary ? primary.rel : '', read: false },
|
|
473
|
+
supporting: counts.supporting,
|
|
474
|
+
related: counts.related,
|
|
475
|
+
outsideReads: 0,
|
|
476
|
+
continuedReadsAfterExit: 0,
|
|
477
|
+
reEntries: 0,
|
|
478
|
+
seen: new Set(), // 本 Epoch 里已经计过「读」的 `层:rel`(导出前会剥掉)
|
|
479
|
+
}
|
|
480
|
+
}
|
|
481
|
+
|
|
482
|
+
/**
|
|
483
|
+
* 按 epochId 找 Epoch 记录。找不到返回 null(早于任何快照的读就是这种)。
|
|
484
|
+
* @param {object} state - 会话状态
|
|
485
|
+
* @param {number|null} epochId - Epoch 编号
|
|
486
|
+
* @returns {object|null} Epoch 记录
|
|
487
|
+
*/
|
|
488
|
+
function epochIn(state, epochId) {
|
|
489
|
+
const list = state && Array.isArray(state.epochs) ? state.epochs : []
|
|
490
|
+
if (!Number.isInteger(epochId)) return null
|
|
491
|
+
for (let i = list.length - 1; i >= 0; i -= 1) {
|
|
492
|
+
if (list[i].epochId === epochId) return list[i]
|
|
493
|
+
}
|
|
494
|
+
return null
|
|
495
|
+
}
|
|
496
|
+
|
|
497
|
+
/**
|
|
498
|
+
* 记一次真实读。**归因在这一次调用里就结算并冻结**,之后不再重算。
|
|
499
|
+
* 不属于任何快照的读 = outside context(这不是错,是信息)。
|
|
424
500
|
* @param {object} state - 会话状态
|
|
425
501
|
* @param {object} read - 归一化后的 read 证据
|
|
426
502
|
*/
|
|
427
503
|
function recordRead(state, read) {
|
|
428
|
-
const
|
|
429
|
-
const
|
|
430
|
-
const
|
|
431
|
-
const
|
|
432
|
-
|
|
504
|
+
const at = snapshotAt(state.snapshots, read.seq)
|
|
505
|
+
const attribution = attributeRead(at, read.rel)
|
|
506
|
+
const facts = attributeReadFacts(state.snapshots, read.rel, read.seq)
|
|
507
|
+
const point = {
|
|
508
|
+
seq: read.seq,
|
|
509
|
+
at: read.time,
|
|
510
|
+
snapshotSeq: attribution.snapshotSeq,
|
|
511
|
+
epochId: attribution.epochId,
|
|
512
|
+
tier: attribution.tierAtRead,
|
|
513
|
+
rank: attribution.rankAtRead,
|
|
514
|
+
inside: attribution.insideAtRead,
|
|
515
|
+
}
|
|
433
516
|
|
|
434
517
|
let entry = state.reads.get(read.rel)
|
|
435
518
|
if (!entry) {
|
|
436
519
|
entry = {
|
|
437
520
|
rel: read.rel,
|
|
438
|
-
count:
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
521
|
+
count: 0,
|
|
522
|
+
firstRead: { ...point },
|
|
523
|
+
lastRead: { ...point },
|
|
524
|
+
insideReads: 0,
|
|
525
|
+
outsideReads: 0,
|
|
526
|
+
primaryReads: 0,
|
|
527
|
+
supportingReads: 0,
|
|
528
|
+
relatedReads: 0,
|
|
529
|
+
reEntry: false,
|
|
530
|
+
continuedReadAfterExit: false,
|
|
447
531
|
}
|
|
448
532
|
state.reads.set(read.rel, entry)
|
|
449
533
|
state.readOrder.push(read.rel)
|
|
450
534
|
while (state.readOrder.length > MAX_READS_PER_SESSION) {
|
|
451
535
|
state.reads.delete(state.readOrder.shift())
|
|
452
536
|
}
|
|
453
|
-
return
|
|
454
537
|
}
|
|
455
538
|
|
|
456
539
|
entry.count += 1
|
|
457
|
-
|
|
458
|
-
entry.
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
540
|
+
// 「第一次读」按**事件 seq** 认(seq 才是真相,墙钟只用来显示)
|
|
541
|
+
if (read.seq < entry.firstRead.seq || (read.seq === entry.firstRead.seq && read.time < entry.firstRead.at)) {
|
|
542
|
+
entry.firstRead = { ...point }
|
|
543
|
+
}
|
|
544
|
+
if (read.seq > entry.lastRead.seq || (read.seq === entry.lastRead.seq && read.time >= entry.lastRead.at)) {
|
|
545
|
+
entry.lastRead = { ...point }
|
|
546
|
+
}
|
|
547
|
+
if (attribution.insideAtRead) entry.insideReads += 1
|
|
548
|
+
else entry.outsideReads += 1
|
|
549
|
+
if (attribution.tierAtRead === 'primary') entry.primaryReads += 1
|
|
550
|
+
else if (attribution.tierAtRead === 'supporting') entry.supportingReads += 1
|
|
551
|
+
else if (attribution.tierAtRead === 'related') entry.relatedReads += 1
|
|
552
|
+
if (facts.continuedReadAfterExit) entry.continuedReadAfterExit = true
|
|
553
|
+
if (facts.reEntry) entry.reEntry = true
|
|
554
|
+
|
|
555
|
+
const epoch = epochIn(state, attribution.epochId)
|
|
556
|
+
if (epoch) {
|
|
557
|
+
if (!attribution.insideAtRead) epoch.outsideReads += 1
|
|
558
|
+
if (facts.continuedReadAfterExit) epoch.continuedReadsAfterExit += 1
|
|
559
|
+
if (facts.reEntry) epoch.reEntries += 1
|
|
560
|
+
if (attribution.insideAtRead && attribution.tierAtRead) {
|
|
561
|
+
const key = `${attribution.tierAtRead}:${read.rel}`
|
|
562
|
+
if (!epoch.seen.has(key)) {
|
|
563
|
+
epoch.seen.add(key)
|
|
564
|
+
const bucket = epoch[attribution.tierAtRead]
|
|
565
|
+
if (bucket) bucket.read += 1
|
|
566
|
+
}
|
|
567
|
+
if (attribution.tierAtRead === 'primary' && epoch.primary.rel === read.rel) epoch.primary.read = true
|
|
568
|
+
}
|
|
468
569
|
}
|
|
469
570
|
}
|
|
470
571
|
|
|
471
572
|
/**
|
|
472
573
|
* 找出**这次读发生的那一刻**在生效的那份快照(seq ≤ 读的 seq 里最新的那份)。
|
|
473
574
|
* 找不到就返回 null —— 那是「Knit 还没给过上下文就自己读了」,如实记成 outside。
|
|
575
|
+
*
|
|
576
|
+
* 这是 runtime 与离线回放到共用的**同一个纯函数**:两边「规则一致」靠它,
|
|
577
|
+
* 而不是靠两边的数字恰好相等(交付时刻不可观测,数字本来就不可能相等)。
|
|
578
|
+
*
|
|
474
579
|
* @param {object[]} snapshots - 快照栈
|
|
475
580
|
* @param {number} seq - 读的 seq
|
|
476
581
|
* @returns {object|null} 快照
|
|
477
582
|
*/
|
|
478
|
-
function snapshotAt(snapshots, seq) {
|
|
479
|
-
|
|
480
|
-
|
|
583
|
+
export function snapshotAt(snapshots, seq) {
|
|
584
|
+
const list = Array.isArray(snapshots) ? snapshots : []
|
|
585
|
+
for (let i = list.length - 1; i >= 0; i -= 1) {
|
|
586
|
+
if (list[i].seq <= seq) return list[i]
|
|
481
587
|
}
|
|
482
588
|
return null
|
|
483
589
|
}
|
|
484
590
|
|
|
591
|
+
/**
|
|
592
|
+
* 把「这次读」钉到一份快照上 —— 输出的是**读那一刻**的事实,不是当前视图。
|
|
593
|
+
* @param {object|null} snapshot - 读那一刻生效的快照(`snapshotAt()` 的结果)
|
|
594
|
+
* @param {string} rel - 归一化后的路径
|
|
595
|
+
* @returns {{snapshotSeq: number|null, epochId: number|null, tierAtRead: string|null, rankAtRead: number|null, insideAtRead: boolean}} 归因
|
|
596
|
+
*/
|
|
597
|
+
export function attributeRead(snapshot, rel) {
|
|
598
|
+
if (!snapshot || !Array.isArray(snapshot.items)) {
|
|
599
|
+
return { snapshotSeq: null, epochId: null, tierAtRead: null, rankAtRead: null, insideAtRead: false }
|
|
600
|
+
}
|
|
601
|
+
const hit = snapshot.items.find((item) => item.rel === rel)
|
|
602
|
+
return {
|
|
603
|
+
snapshotSeq: Number.isInteger(snapshot.seq) ? snapshot.seq : null,
|
|
604
|
+
epochId: Number.isInteger(snapshot.epochId) ? snapshot.epochId : null,
|
|
605
|
+
tierAtRead: hit ? hit.tier : null,
|
|
606
|
+
rankAtRead: hit ? hit.rank : null,
|
|
607
|
+
insideAtRead: !!hit,
|
|
608
|
+
}
|
|
609
|
+
}
|
|
610
|
+
|
|
611
|
+
/**
|
|
612
|
+
* 推导两个**事实**字段(规格 §12 / §13),只用保留窗口内的快照:
|
|
613
|
+
*
|
|
614
|
+
* - `continuedReadAfterExit`:这次读**在当时那份快照之外**,但更早的某份快照里有这篇
|
|
615
|
+
* ⇒ 「离开上下文之后它仍然被读了」。
|
|
616
|
+
* - `reEntry`:这次读**在当时那份快照之内**,更早的某份快照里也有过,但中间至少有一份
|
|
617
|
+
* 快照里没有它 ⇒ 「离开过,又回来了,而且回来之后被读了」。
|
|
618
|
+
*
|
|
619
|
+
* ⚠️ 这两个字段只是**事实**。它们**不许**被解释成「Agent 不认可新上下文」
|
|
620
|
+
* —— 那是推断,不在这个模块的职责里(规格 §5 Evidence Over Interpretation)。
|
|
621
|
+
*
|
|
622
|
+
* 只在保留窗口内推导:宁可漏记,也不猜。
|
|
623
|
+
*
|
|
624
|
+
* @param {object[]} snapshots - 快照栈
|
|
625
|
+
* @param {string} rel - 归一化后的路径
|
|
626
|
+
* @param {number} readSeq - 这次读的 seq
|
|
627
|
+
* @returns {{continuedReadAfterExit: boolean, reEntry: boolean}} 两个事实
|
|
628
|
+
*/
|
|
629
|
+
export function attributeReadFacts(snapshots, rel, readSeq) {
|
|
630
|
+
const list = Array.isArray(snapshots) ? snapshots : []
|
|
631
|
+
const empty = { continuedReadAfterExit: false, reEntry: false }
|
|
632
|
+
const at = snapshotAt(list, readSeq)
|
|
633
|
+
if (!at) return empty
|
|
634
|
+
const atIndex = list.indexOf(at)
|
|
635
|
+
if (atIndex < 0) return empty
|
|
636
|
+
|
|
637
|
+
const insideNow = at.items.some((item) => item.rel === rel)
|
|
638
|
+
let sawInside = false
|
|
639
|
+
let sawGapAfterInside = false
|
|
640
|
+
for (let i = 0; i < atIndex; i += 1) {
|
|
641
|
+
const has = list[i].items.some((item) => item.rel === rel)
|
|
642
|
+
if (has) sawInside = true
|
|
643
|
+
else if (sawInside) sawGapAfterInside = true
|
|
644
|
+
}
|
|
645
|
+
// 更早的窗口里从来没有过它 —— 那这次既不是「继续读」也不是「重新进入」
|
|
646
|
+
if (!sawInside) return empty
|
|
647
|
+
if (insideNow) return { continuedReadAfterExit: false, reEntry: sawGapAfterInside }
|
|
648
|
+
return { continuedReadAfterExit: true, reEntry: false }
|
|
649
|
+
}
|
|
650
|
+
|
|
485
651
|
/**
|
|
486
652
|
* 取一个会话当前的使用情况。没有记录时返回 `null`(不编造空报告)。
|
|
487
653
|
* @param {object} store - store
|
|
@@ -501,8 +667,14 @@ export function usageFor(store, sessionId) {
|
|
|
501
667
|
/**
|
|
502
668
|
* 纯函数版:从一个会话状态算出使用情况(测试直接用这个)。
|
|
503
669
|
*
|
|
670
|
+
* 报告分两层,界线是硬的:
|
|
671
|
+
*
|
|
672
|
+
* - **历史层**(`reads[].firstRead/lastRead`、`byTier[].read`、`primaryFollowThrough`、
|
|
673
|
+
* `outside`)—— 全部来自读时冻结的归因,**永不按当前上下文重算**。
|
|
674
|
+
* - **当前层**(`items`、`byTier[].total`、`primaryRel`、`delta`)—— 反映最近一份上下文。
|
|
675
|
+
*
|
|
504
676
|
* 报告里只有**计数与事实**:读了几次、落在哪一层、有几篇在快照之外、
|
|
505
|
-
*
|
|
677
|
+
* 上下文变过几次、有几篇离开后仍被读、有几篇重新进入。**没有分数、没有百分比评分。**
|
|
506
678
|
*
|
|
507
679
|
* @param {object} state - 会话状态
|
|
508
680
|
* @returns {object} 使用情况
|
|
@@ -510,6 +682,7 @@ export function usageFor(store, sessionId) {
|
|
|
510
682
|
export function usageFrom(state) {
|
|
511
683
|
const snapshots = (state && state.snapshots) || []
|
|
512
684
|
const snapshot = snapshots[snapshots.length - 1] || null
|
|
685
|
+
const epochId = snapshot && Number.isInteger(snapshot.epochId) ? snapshot.epochId : null
|
|
513
686
|
const byTier = {
|
|
514
687
|
primary: { total: 0, read: 0 },
|
|
515
688
|
supporting: { total: 0, read: 0 },
|
|
@@ -523,52 +696,93 @@ export function usageFrom(state) {
|
|
|
523
696
|
|
|
524
697
|
const reads = []
|
|
525
698
|
for (const entry of state.reads.values()) {
|
|
526
|
-
const hit = snapshot ? snapshot.items.find((item) => item.rel === entry.rel) : null
|
|
527
699
|
reads.push({
|
|
528
700
|
rel: entry.rel,
|
|
529
701
|
count: entry.count,
|
|
530
|
-
|
|
531
|
-
|
|
532
|
-
|
|
533
|
-
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
|
|
702
|
+
firstRead: { ...entry.firstRead },
|
|
703
|
+
lastRead: { ...entry.lastRead },
|
|
704
|
+
// 兼容别名(旧调用方与测试用的字段名):都是**首次读**的归因,历史值
|
|
705
|
+
firstReadAt: entry.firstRead.at,
|
|
706
|
+
firstReadSeq: entry.firstRead.seq,
|
|
707
|
+
firstTier: entry.firstRead.tier,
|
|
708
|
+
lastReadAt: entry.lastRead.at,
|
|
709
|
+
lastTier: entry.lastRead.tier,
|
|
710
|
+
insideReads: entry.insideReads,
|
|
711
|
+
outsideReads: entry.outsideReads,
|
|
712
|
+
outsideCount: entry.outsideReads,
|
|
713
|
+
outside: entry.outsideReads > 0,
|
|
714
|
+
reEntry: !!entry.reEntry,
|
|
715
|
+
continuedReadAfterExit: !!entry.continuedReadAfterExit,
|
|
716
|
+
// ⚠️ `tier`/`rank` 是**首次读时**的层与名次,不是「它现在在哪一层」。
|
|
717
|
+
tier: entry.firstRead.tier,
|
|
718
|
+
rank: entry.firstRead.rank,
|
|
537
719
|
})
|
|
538
720
|
}
|
|
539
|
-
reads.sort((a, b) => a.
|
|
540
|
-
|
|
721
|
+
reads.sort((a, b) => (a.firstRead.seq - b.firstRead.seq) || (a.firstRead.at - b.firstRead.at))
|
|
722
|
+
// 「这一 Epoch 的某一层里,有几篇真的被读过」—— 只认归因落在**当前 Epoch** 的读
|
|
723
|
+
for (const row of reads) {
|
|
724
|
+
if (row.firstRead.epochId === epochId && row.firstRead.inside && byTier[row.firstRead.tier]) {
|
|
725
|
+
byTier[row.firstRead.tier].read += 1
|
|
726
|
+
}
|
|
727
|
+
}
|
|
541
728
|
|
|
542
|
-
const outside = reads.filter((row) => row.
|
|
729
|
+
const outside = reads.filter((row) => row.outsideReads > 0)
|
|
543
730
|
const first = reads[0] || null
|
|
544
|
-
const
|
|
545
|
-
const
|
|
731
|
+
const epoch = epochIn(state, epochId)
|
|
732
|
+
const primaryRel = epoch && epoch.primary ? epoch.primary.rel : ''
|
|
733
|
+
const continued = reads.filter((row) => row.continuedReadAfterExit)
|
|
734
|
+
const reentries = reads.filter((row) => row.reEntry)
|
|
735
|
+
const lastEpochId = Number.isInteger(epochId) ? epochId : 0
|
|
736
|
+
const epochs = (Array.isArray(state.epochs) ? state.epochs : []).map((e) => ({
|
|
737
|
+
epochId: e.epochId,
|
|
738
|
+
snapshotSeq: e.snapshotSeq,
|
|
739
|
+
topic: e.topic,
|
|
740
|
+
task: e.task,
|
|
741
|
+
primary: { rel: e.primary.rel, read: e.primary.read },
|
|
742
|
+
supporting: { total: e.supporting.total, read: e.supporting.read },
|
|
743
|
+
related: { total: e.related.total, read: e.related.read },
|
|
744
|
+
outsideReads: e.outsideReads,
|
|
745
|
+
continuedReadsAfterExit: e.continuedReadsAfterExit,
|
|
746
|
+
reEntries: e.reEntries,
|
|
747
|
+
}))
|
|
546
748
|
|
|
547
749
|
return {
|
|
548
750
|
at: snapshot ? snapshot.at : 0,
|
|
549
751
|
seq: snapshot ? snapshot.seq : -1,
|
|
752
|
+
epochId,
|
|
550
753
|
task: snapshot ? snapshot.task : '',
|
|
551
754
|
topic: snapshot ? snapshot.topic : '',
|
|
552
755
|
items: snapshot ? snapshot.items.map((item) => ({ ...item })) : [],
|
|
553
756
|
reads,
|
|
757
|
+
// §16 Epoch 级使用情况:内部 / 离线回放 / 将来评估用,v0.16 **不上**任何 UI 与工具输出
|
|
758
|
+
epochs,
|
|
554
759
|
delta: state.deltas[state.deltas.length - 1] || null,
|
|
555
760
|
stats: {
|
|
556
761
|
reads: reads.reduce((sum, row) => sum + row.count, 0),
|
|
557
762
|
distinct: reads.length,
|
|
558
763
|
outside: outside.length,
|
|
559
764
|
outsideReads: outside.map((row) => row.rel),
|
|
560
|
-
|
|
765
|
+
// 第一条成功读落在哪一层:primary / supporting / related / outside / null
|
|
766
|
+
firstReadTier: first ? (first.firstRead.inside ? first.firstRead.tier : 'outside') : null,
|
|
561
767
|
firstReadRel: first ? first.rel : '',
|
|
562
|
-
firstReadAt: first ? first.
|
|
563
|
-
|
|
564
|
-
|
|
565
|
-
|
|
768
|
+
firstReadAt: first ? first.firstRead.at : 0,
|
|
769
|
+
firstReadEpoch: first ? first.firstRead.epochId : null,
|
|
770
|
+
primaryRel,
|
|
771
|
+
// 「这个 Epoch 先看的那篇被真的读了吗」—— 按 Epoch 归因的布尔,不是成功率
|
|
772
|
+
primaryFollowThrough: !!(epoch && epoch.primary && epoch.primary.read),
|
|
566
773
|
byTier,
|
|
567
|
-
supportingCoverage:
|
|
774
|
+
supportingCoverage: byTier.supporting.total === 0 ? null : byTier.supporting.read / byTier.supporting.total,
|
|
775
|
+
// 事实计数(不是「Agent 不认可新上下文」这种解释)
|
|
776
|
+
continuedReadsAfterExit: continued.length,
|
|
777
|
+
reEntries: reentries.length,
|
|
568
778
|
churn: {
|
|
569
|
-
//
|
|
570
|
-
|
|
571
|
-
|
|
779
|
+
// 观察到的**不同 Epoch 数**(= 最后一份 Epoch 的编号;被淘汰的也算过)
|
|
780
|
+
epochs: lastEpochId,
|
|
781
|
+
// 变化次数 = 换过几次上下文(第一份不算变化)
|
|
782
|
+
changes: lastEpochId > 0 ? lastEpochId - 1 : 0,
|
|
783
|
+
// ⚠️ `snapshots` 是客户端已经在用的键名(`usage.changes` 文案),保留它 = 变化次数
|
|
784
|
+
snapshots: lastEpochId > 0 ? lastEpochId - 1 : 0,
|
|
785
|
+
deltas: lastEpochId > 0 ? lastEpochId - 1 : 0,
|
|
572
786
|
// 手上还留着几条 Delta 明细
|
|
573
787
|
retained: state.deltas.length,
|
|
574
788
|
appeared: state.churn.appeared,
|
|
@@ -594,7 +808,10 @@ export function auditPayload(usage) {
|
|
|
594
808
|
supportingRead: s.byTier.supporting.read,
|
|
595
809
|
supportingTotal: s.byTier.supporting.total,
|
|
596
810
|
readsOutside: s.outside,
|
|
597
|
-
contextChanges: s.churn.
|
|
811
|
+
contextChanges: s.churn.changes,
|
|
812
|
+
epochs: s.churn.epochs,
|
|
813
|
+
continuedReadsAfterExit: s.continuedReadsAfterExit,
|
|
814
|
+
reEntries: s.reEntries,
|
|
598
815
|
}
|
|
599
816
|
}
|
|
600
817
|
|