dsh-knit 0.15.0 → 0.17.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 +380 -0
- package/README.en.md +105 -29
- package/README.md +97 -27
- package/package.json +2 -2
- package/src/client/client.js +760 -109
- package/src/host/feedback.js +537 -90
- package/src/host/index.js +241 -57
- package/src/host/tool.js +8 -9
- package/test/client.test.mjs +781 -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/document-lifecycle.test.mjs +513 -0
- package/test/harness.mjs +7 -1
- package/test/host-http.test.mjs +228 -46
- package/test/i18n.test.mjs +58 -21
- package/test/path.test.mjs +6 -6
- package/test/peek.test.mjs +80 -26
- package/test/tier1.test.mjs +4 -2
- package/test/tool.test.mjs +11 -9
- package/tools/context-feedback-eval.mjs +46 -14
package/src/host/feedback.js
CHANGED
|
@@ -1,26 +1,37 @@
|
|
|
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
|
+
* 前缀事件也算进来。代价是:订阅之前发生的事件不会自动进来。
|
|
25
|
+
*
|
|
26
|
+
* v0.17 修订:闸门开晚时(真实用法:读完才想起来看面板),宿主可以在**开闸那一刻**
|
|
27
|
+
* 回填一次会话已有的事件(`markBackfilled()` 由宿主在 `ingestEvents()` 之后调用)。
|
|
28
|
+
* 本模块仍然零 I/O、零网络、零模型 —— 事件是宿主喂进来的,它只多知道一件事:
|
|
29
|
+
* 「这批读是补记的」。**顺序是这个机制的组成部分**:`recordRead()` 在事件入库那一刻就把
|
|
30
|
+
* 归因冻结,所以宿主必须**先把手上那份包 `noteSnapshot()` 掉、再喂补记的事件**,
|
|
31
|
+
* 否则那些读会在「一份快照都还没有」的状态下被冻成包外(规格 §6:不知道就不要说)。
|
|
21
32
|
*
|
|
22
33
|
* 这里**没有**:trajectory、span、runtime trace、reasoning、成功率、置信度、归一化评分、
|
|
23
|
-
* memory 写入。Usage
|
|
34
|
+
* quality score、memory 写入。Usage 不是分数,是计数与事实。
|
|
24
35
|
*
|
|
25
36
|
* @module feedback
|
|
26
37
|
*/
|
|
@@ -30,10 +41,15 @@ import { isAbsolute, relative, resolve, sep } from 'node:path'
|
|
|
30
41
|
export const MAX_SESSIONS = 24
|
|
31
42
|
/** 每个会话最多记多少篇**读过**的文档。 */
|
|
32
43
|
export const MAX_READS_PER_SESSION = 200
|
|
33
|
-
/** 每个会话最多保留几份 Snapshot
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
44
|
+
/** 每个会话最多保留几份 Snapshot / Epoch。
|
|
45
|
+
*
|
|
46
|
+
* v0.16 由 2 提到 20:归因本身**在 Read 时结算**,保留数量不影响它的正确性;
|
|
47
|
+
* 它只决定 `continuedReadAfterExit` / `reEntry` 这两个事实能回溯多远
|
|
48
|
+
* (要能看见「离开过、又回来」就必须留着中间那几份)。
|
|
49
|
+
*/
|
|
50
|
+
export const MAX_SNAPSHOTS_PER_SESSION = 20
|
|
51
|
+
/** 每个会话最多保留多少条 Delta 明细(计数不受它影响)。 */
|
|
52
|
+
export const MAX_DELTAS_PER_SESSION = 50
|
|
37
53
|
/** 最多同时挂起多少个「已调用、还没结果」的 read。 */
|
|
38
54
|
export const MAX_PENDING_CALLS = 64
|
|
39
55
|
|
|
@@ -134,7 +150,7 @@ function signatureOf(items, task) {
|
|
|
134
150
|
*
|
|
135
151
|
* @param {object|null} prev - 上一份 Snapshot
|
|
136
152
|
* @param {object|null} next - 这一份 Snapshot
|
|
137
|
-
* @returns {{appeared: object[], disappeared: object[], moved: object[], taskChanged: boolean, stable: boolean}} 差异
|
|
153
|
+
* @returns {{appeared: object[], disappeared: object[], moved: object[], taskChanged: boolean, fromEpoch: number|null, toEpoch: number|null, stable: boolean}} 差异
|
|
138
154
|
*/
|
|
139
155
|
export function diffContext(prev, next) {
|
|
140
156
|
const before = indexOf(prev)
|
|
@@ -158,6 +174,9 @@ export function diffContext(prev, next) {
|
|
|
158
174
|
disappeared,
|
|
159
175
|
moved,
|
|
160
176
|
taskChanged,
|
|
177
|
+
// 哪两个 Epoch 之间的变化(没有上一份时 fromEpoch 为 null)
|
|
178
|
+
fromEpoch: prev && Number.isInteger(prev.epochId) ? prev.epochId : null,
|
|
179
|
+
toEpoch: next && Number.isInteger(next.epochId) ? next.epochId : null,
|
|
161
180
|
stable: appeared.length === 0 && disappeared.length === 0 && moved.length === 0 && !taskChanged,
|
|
162
181
|
}
|
|
163
182
|
}
|
|
@@ -188,7 +207,7 @@ function indexOf(snapshot) {
|
|
|
188
207
|
*
|
|
189
208
|
* 幂等靠 `fromSeq` 游标:只处理 `seq > fromSeq` 的事件,所以同一批事件喂两遍不会重复计数。
|
|
190
209
|
*
|
|
191
|
-
* @param {object[]} events - `session
|
|
210
|
+
* @param {object[]} events - 会话事件(v0.16 起由 `session/event` 订阅逐条喂进来)
|
|
192
211
|
* @param {{root?: string, fromSeq?: number, pending?: Map<string, object>}} [options] - 选项
|
|
193
212
|
* @returns {{reads: object[], cursor: number, pending: Map<string, object>}} 证据、新游标、挂起表
|
|
194
213
|
*/
|
|
@@ -264,7 +283,6 @@ function parseArguments(raw) {
|
|
|
264
283
|
return {}
|
|
265
284
|
}
|
|
266
285
|
}
|
|
267
|
-
|
|
268
286
|
/* ── 4. 按会话分片的内存状态 ───────────────────────────────────────── */
|
|
269
287
|
|
|
270
288
|
/**
|
|
@@ -276,7 +294,7 @@ export function createStore() {
|
|
|
276
294
|
}
|
|
277
295
|
|
|
278
296
|
/**
|
|
279
|
-
* 标记这个会话「被审计了」——
|
|
297
|
+
* 标记这个会话「被审计了」—— 之后它的读事件与面板请求才会被记账。
|
|
280
298
|
*
|
|
281
299
|
* 默认**不记账**:没人看「使用情况」、Agent 也没要 audit 的会话,
|
|
282
300
|
* 不该在内存里攒快照。这一点是刻意的(内存有上限、行为可预期)。
|
|
@@ -302,7 +320,8 @@ export function activateAudit(store, sessionId) {
|
|
|
302
320
|
}
|
|
303
321
|
|
|
304
322
|
/**
|
|
305
|
-
*
|
|
323
|
+
* 这个会话是否在记账。**订阅回调的第一行就用它早退** ——
|
|
324
|
+
* 没记账的会话一次 Map 查找就返回,不做任何别的工作。
|
|
306
325
|
* @param {object} store - store
|
|
307
326
|
* @param {string} sessionId - 会话 id
|
|
308
327
|
* @returns {boolean} 是否记账
|
|
@@ -311,6 +330,41 @@ export function isAudited(store, sessionId) {
|
|
|
311
330
|
return !!(store && sessionId && store.audited.has(sessionId))
|
|
312
331
|
}
|
|
313
332
|
|
|
333
|
+
/**
|
|
334
|
+
* 标记这个会话的历史**已经被回填过**(v0.17 修订)。
|
|
335
|
+
*
|
|
336
|
+
* 幂等:调用方(宿主)在开闸时用它保证「一个会话只回填一次」,之后从订阅来的新事件
|
|
337
|
+
* 照常单独入账。
|
|
338
|
+
*
|
|
339
|
+
* @param {object} store - store
|
|
340
|
+
* @param {string} sessionId - 会话 id
|
|
341
|
+
* @returns {boolean} 是否成功
|
|
342
|
+
*/
|
|
343
|
+
export function markBackfilled(store, sessionId) {
|
|
344
|
+
try {
|
|
345
|
+
if (!store || !sessionId) return false
|
|
346
|
+
stateOf(store, sessionId).backfilled = true
|
|
347
|
+
return true
|
|
348
|
+
} catch {
|
|
349
|
+
return false
|
|
350
|
+
}
|
|
351
|
+
}
|
|
352
|
+
|
|
353
|
+
/**
|
|
354
|
+
* 这个会话的历史回填过了吗。
|
|
355
|
+
* @param {object} store - store
|
|
356
|
+
* @param {string} sessionId - 会话 id
|
|
357
|
+
* @returns {boolean} 是否回填过
|
|
358
|
+
*/
|
|
359
|
+
export function isBackfilled(store, sessionId) {
|
|
360
|
+
try {
|
|
361
|
+
const state = store && sessionId ? store.sessions.get(sessionId) : null
|
|
362
|
+
return !!(state && state.backfilled)
|
|
363
|
+
} catch {
|
|
364
|
+
return false
|
|
365
|
+
}
|
|
366
|
+
}
|
|
367
|
+
|
|
314
368
|
/**
|
|
315
369
|
* 取(或建)一个会话的状态,并按 LRU 触摸 —— 会话数量超上限时淘汰最久没碰的。
|
|
316
370
|
* @param {object} store - store
|
|
@@ -321,15 +375,19 @@ function stateOf(store, sessionId) {
|
|
|
321
375
|
let state = store.sessions.get(sessionId)
|
|
322
376
|
if (!state) {
|
|
323
377
|
state = {
|
|
324
|
-
seq: -1, // 已消费到的事件 seq
|
|
378
|
+
seq: -1, // 已消费到的事件 seq(幂等游标;也是「当前水位」)
|
|
325
379
|
pending: new Map(), // 已调用、还没结果的 read
|
|
326
|
-
snapshots: [], //
|
|
380
|
+
snapshots: [], // 最近 MAX_SNAPSHOTS_PER_SESSION 份 Context Pack(每份 = 一个 Epoch)
|
|
381
|
+
epochs: [], // 与 snapshots 一一对应的 Epoch 级计数
|
|
327
382
|
deltas: [], // 最近若干条变化
|
|
328
|
-
reads: new Map(), // rel →
|
|
383
|
+
reads: new Map(), // rel → 冻结的读归因
|
|
329
384
|
readOrder: [], // rel 的插入顺序(淘汰用)
|
|
330
|
-
// ⚠️ `changes`
|
|
331
|
-
//
|
|
332
|
-
churn: {
|
|
385
|
+
// ⚠️ 这里**不再**有 `changes` 计数:上下文换过几次 = 最后一个 Epoch 的编号 - 1,
|
|
386
|
+
// 而 Epoch 编号是单调的(被淘汰的 Epoch 也计过数),所以不需要额外记一个累计值。
|
|
387
|
+
churn: { appeared: 0, disappeared: 0, moved: 0, taskChanged: 0 },
|
|
388
|
+
// v0.17 修订:这份状态里的读是**回填**进来的(开闸时补记的历史)。
|
|
389
|
+
// 它只用于「一个会话只回填一次」,不影响归因 —— 归因由宿主喂事件的顺序保证。
|
|
390
|
+
backfilled: false,
|
|
333
391
|
}
|
|
334
392
|
store.sessions.set(sessionId, state)
|
|
335
393
|
}
|
|
@@ -346,9 +404,12 @@ function stateOf(store, sessionId) {
|
|
|
346
404
|
/* ── 5. 入口:喂事件 / 记快照 / 取使用情况 ─────────────────────────── */
|
|
347
405
|
|
|
348
406
|
/**
|
|
349
|
-
*
|
|
407
|
+
* 把**一批**会话事件喂进去,抽出 read 并按「读发生的那一刻」结算归因。
|
|
350
408
|
*
|
|
351
|
-
*
|
|
409
|
+
* v0.16 起调用方通常一次只喂一条(`session/event` 订阅)。仍然是幂等的:
|
|
410
|
+
* 只处理 `seq > state.seq` 的事件,重复喂同一批不会重复计数。
|
|
411
|
+
*
|
|
412
|
+
* **任何异常都咽掉并返回 `{ok:false}`** —— 记账失败绝不能让面板或工具失败。
|
|
352
413
|
*
|
|
353
414
|
* @param {object} store - store
|
|
354
415
|
* @param {string} sessionId - 会话 id
|
|
@@ -356,6 +417,35 @@ function stateOf(store, sessionId) {
|
|
|
356
417
|
* @param {{root?: string}} [options] - 选项
|
|
357
418
|
* @returns {{ok: boolean, reads: number, cursor: number}} 结果
|
|
358
419
|
*/
|
|
420
|
+
/**
|
|
421
|
+
* 安全地取一次版本标记。**任何异常都咽掉**:记账坏了不许影响宿主。
|
|
422
|
+
* @param {(rel: string) => unknown} stat - 宿主注入的取样函数
|
|
423
|
+
* @param {string} rel - 已归一化的工作区相对路径
|
|
424
|
+
* @returns {number|null} mtimeMs,或 null(拿不到就不猜)
|
|
425
|
+
*/
|
|
426
|
+
function safeStat(stat, rel) {
|
|
427
|
+
try {
|
|
428
|
+
const value = stat(rel)
|
|
429
|
+
return Number.isFinite(value) ? value : null
|
|
430
|
+
} catch {
|
|
431
|
+
return null
|
|
432
|
+
}
|
|
433
|
+
}
|
|
434
|
+
|
|
435
|
+
/**
|
|
436
|
+
* 把**一批**会话事件喂进去,抽出 read 并按「读发生的那一刻」结算归因。
|
|
437
|
+
*
|
|
438
|
+
* v0.16 起调用方通常一次只喂一条(`session/event` 订阅)。仍然是幂等的:
|
|
439
|
+
* 只处理 `seq > state.seq` 的事件,重复喂同一批不会重复计数。
|
|
440
|
+
*
|
|
441
|
+
* **任何异常都咽掉并返回 `{ok:false}`** —— 记账失败绝不能让面板或工具失败。
|
|
442
|
+
*
|
|
443
|
+
* @param {object} store - store
|
|
444
|
+
* @param {string} sessionId - 会话 id
|
|
445
|
+
* @param {object[]} events - 会话事件
|
|
446
|
+
* @param {{root?: string, stat?: (rel: string) => unknown}} [options] - 选项(v0.17 新增 `stat`)
|
|
447
|
+
* @returns {{ok: boolean, reads: number, cursor: number}} 结果
|
|
448
|
+
*/
|
|
359
449
|
export function ingestEvents(store, sessionId, events, options = {}) {
|
|
360
450
|
try {
|
|
361
451
|
if (!store || !sessionId) return { ok: false, reads: 0, cursor: -1 }
|
|
@@ -367,7 +457,14 @@ export function ingestEvents(store, sessionId, events, options = {}) {
|
|
|
367
457
|
})
|
|
368
458
|
state.pending = pending
|
|
369
459
|
if (cursor > state.seq) state.seq = cursor
|
|
370
|
-
|
|
460
|
+
// v0.17:只在「这次读被确认成功」的时刻取一次版本标记(stat 由宿主注入,
|
|
461
|
+
// 本模块仍然零 I/O)。取样在 recordRead 之前,而 recordRead 只处理
|
|
462
|
+
// seq > fromSeq 的新事件 —— 同一事件重复派发既不重复计数,也不重复取样。
|
|
463
|
+
const stat = typeof options.stat === 'function' ? options.stat : null
|
|
464
|
+
for (const read of reads) {
|
|
465
|
+
read.mtimeMs = stat ? safeStat(stat, read.rel) : null
|
|
466
|
+
recordRead(state, read)
|
|
467
|
+
}
|
|
371
468
|
return { ok: true, reads: reads.length, cursor: state.seq }
|
|
372
469
|
} catch {
|
|
373
470
|
return { ok: false, reads: 0, cursor: -1 }
|
|
@@ -380,6 +477,9 @@ export function ingestEvents(store, sessionId, events, options = {}) {
|
|
|
380
477
|
* 与上一份**同签名**时不记新快照(只把时间 / seq 往前推)—— 否则 5 秒轮询会把
|
|
381
478
|
* 同一份上下文记成几十份,Delta churn 立刻变成噪音。
|
|
382
479
|
*
|
|
480
|
+
* `meta.seq` 省略时用会话当前的**事件水位**(`state.seq`)—— 也就是「交包这一刻,
|
|
481
|
+
* 已经发生到第几个事件」。这正是历史归因要的边界:seq ≤ 它的读算在这份包里。
|
|
482
|
+
*
|
|
383
483
|
* @param {object} store - store
|
|
384
484
|
* @param {string} sessionId - 会话 id
|
|
385
485
|
* @param {object} pack - Context Pack
|
|
@@ -390,24 +490,35 @@ export function noteSnapshot(store, sessionId, pack, meta = {}) {
|
|
|
390
490
|
try {
|
|
391
491
|
if (!store || !sessionId || !pack) return null
|
|
392
492
|
const state = stateOf(store, sessionId)
|
|
393
|
-
|
|
493
|
+
// ⚠️ 不传 `seq` 时取**当前事件水位**。回填路径下宿主必须先记包再喂事件 ——
|
|
494
|
+
// 那一刻水位还是 -1,第一份快照自然落在会话开头,补记的读才有资格归到
|
|
495
|
+
// 「我们已知最早的那份包」上(见文件头与 index.js 的 `backfillFeedback`)。
|
|
496
|
+
const seq = Number.isInteger(meta.seq) ? meta.seq : state.seq
|
|
497
|
+
const next = snapshotOf(pack, { seq, at: meta.at })
|
|
394
498
|
const prev = state.snapshots[state.snapshots.length - 1] || null
|
|
395
499
|
|
|
396
500
|
if (prev && prev.sig === next.sig) {
|
|
397
501
|
if (next.at > prev.at) prev.at = next.at
|
|
398
502
|
if (next.seq > prev.seq) prev.seq = next.seq
|
|
503
|
+
const epoch = epochIn(state, prev.epochId)
|
|
504
|
+
if (epoch && prev.seq > epoch.snapshotSeq) epoch.snapshotSeq = prev.seq
|
|
399
505
|
return null
|
|
400
506
|
}
|
|
401
507
|
|
|
508
|
+
// Epoch 编号从这里发出:新建一份上下文 = 一个新 Epoch。同签名不算新 Epoch。
|
|
509
|
+
next.epochId = prev && Number.isInteger(prev.epochId) ? prev.epochId + 1 : 1
|
|
402
510
|
state.snapshots.push(next)
|
|
403
|
-
|
|
511
|
+
state.epochs.push(createEpoch(next))
|
|
512
|
+
while (state.snapshots.length > MAX_SNAPSHOTS_PER_SESSION) {
|
|
513
|
+
state.snapshots.shift()
|
|
514
|
+
state.epochs.shift()
|
|
515
|
+
}
|
|
404
516
|
|
|
405
517
|
let delta = null
|
|
406
518
|
if (prev) {
|
|
407
519
|
delta = { at: next.at, seq: next.seq, ...diffContext(prev, next) }
|
|
408
520
|
state.deltas.push(delta)
|
|
409
521
|
while (state.deltas.length > MAX_DELTAS_PER_SESSION) state.deltas.shift()
|
|
410
|
-
state.churn.changes += 1
|
|
411
522
|
state.churn.appeared += delta.appeared.length
|
|
412
523
|
state.churn.disappeared += delta.disappeared.length
|
|
413
524
|
state.churn.moved += delta.moved.length
|
|
@@ -420,79 +531,338 @@ export function noteSnapshot(store, sessionId, pack, meta = {}) {
|
|
|
420
531
|
}
|
|
421
532
|
|
|
422
533
|
/**
|
|
423
|
-
*
|
|
534
|
+
* 给一个新 Epoch 建计数骨架(总量取自这份快照,已读量靠后续 read 累加)。
|
|
535
|
+
* @param {object} snapshot - 刚记下的快照(已带 epochId)
|
|
536
|
+
* @returns {object} Epoch 记录
|
|
537
|
+
*/
|
|
538
|
+
function createEpoch(snapshot) {
|
|
539
|
+
const counts = {
|
|
540
|
+
primary: { total: 0, read: 0 },
|
|
541
|
+
supporting: { total: 0, read: 0 },
|
|
542
|
+
related: { total: 0, read: 0 },
|
|
543
|
+
}
|
|
544
|
+
for (const item of snapshot.items) {
|
|
545
|
+
const bucket = counts[item.tier]
|
|
546
|
+
if (bucket) bucket.total += 1
|
|
547
|
+
}
|
|
548
|
+
const primary = snapshot.items.find((item) => item.tier === 'primary' && item.rank === 1)
|
|
549
|
+
return {
|
|
550
|
+
epochId: snapshot.epochId,
|
|
551
|
+
snapshotSeq: snapshot.seq,
|
|
552
|
+
topic: snapshot.topic,
|
|
553
|
+
task: snapshot.task,
|
|
554
|
+
primary: { rel: primary ? primary.rel : '', read: false },
|
|
555
|
+
supporting: counts.supporting,
|
|
556
|
+
related: counts.related,
|
|
557
|
+
outsideReads: 0,
|
|
558
|
+
continuedReadsAfterExit: 0,
|
|
559
|
+
reEntries: 0,
|
|
560
|
+
seen: new Set(), // 本 Epoch 里已经计过「读」的 `层:rel`(导出前会剥掉)
|
|
561
|
+
}
|
|
562
|
+
}
|
|
563
|
+
|
|
564
|
+
/**
|
|
565
|
+
* 按 epochId 找 Epoch 记录。找不到返回 null(早于任何快照的读就是这种)。
|
|
566
|
+
* @param {object} state - 会话状态
|
|
567
|
+
* @param {number|null} epochId - Epoch 编号
|
|
568
|
+
* @returns {object|null} Epoch 记录
|
|
569
|
+
*/
|
|
570
|
+
function epochIn(state, epochId) {
|
|
571
|
+
const list = state && Array.isArray(state.epochs) ? state.epochs : []
|
|
572
|
+
if (!Number.isInteger(epochId)) return null
|
|
573
|
+
for (let i = list.length - 1; i >= 0; i -= 1) {
|
|
574
|
+
if (list[i].epochId === epochId) return list[i]
|
|
575
|
+
}
|
|
576
|
+
return null
|
|
577
|
+
}
|
|
578
|
+
|
|
579
|
+
/**
|
|
580
|
+
* 记一次真实读。**归因在这一次调用里就结算并冻结**,之后不再重算。
|
|
581
|
+
* 不属于任何快照的读 = outside context(这不是错,是信息)。
|
|
424
582
|
* @param {object} state - 会话状态
|
|
425
583
|
* @param {object} read - 归一化后的 read 证据
|
|
426
584
|
*/
|
|
427
585
|
function recordRead(state, read) {
|
|
428
|
-
const
|
|
429
|
-
const
|
|
430
|
-
const
|
|
431
|
-
const
|
|
432
|
-
|
|
586
|
+
const at = snapshotAt(state.snapshots, read.seq)
|
|
587
|
+
const attribution = attributeRead(at, read.rel)
|
|
588
|
+
const facts = attributeReadFacts(state.snapshots, read.rel, read.seq)
|
|
589
|
+
const point = {
|
|
590
|
+
seq: read.seq,
|
|
591
|
+
at: read.time,
|
|
592
|
+
snapshotSeq: attribution.snapshotSeq,
|
|
593
|
+
epochId: attribution.epochId,
|
|
594
|
+
tier: attribution.tierAtRead,
|
|
595
|
+
rank: attribution.rankAtRead,
|
|
596
|
+
inside: attribution.insideAtRead,
|
|
597
|
+
}
|
|
433
598
|
|
|
434
599
|
let entry = state.reads.get(read.rel)
|
|
435
600
|
if (!entry) {
|
|
436
601
|
entry = {
|
|
437
602
|
rel: read.rel,
|
|
438
|
-
count:
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
603
|
+
count: 0,
|
|
604
|
+
firstRead: { ...point },
|
|
605
|
+
lastRead: { ...point },
|
|
606
|
+
insideReads: 0,
|
|
607
|
+
outsideReads: 0,
|
|
608
|
+
primaryReads: 0,
|
|
609
|
+
supportingReads: 0,
|
|
610
|
+
relatedReads: 0,
|
|
611
|
+
reEntry: false,
|
|
612
|
+
continuedReadAfterExit: false,
|
|
613
|
+
// v0.17:首次读之前没有「上一次」,三个字段的初值就是「不知道」
|
|
614
|
+
lastReadMtimeMs: null,
|
|
615
|
+
prevReadMtimeMs: null,
|
|
616
|
+
rereadAfterChange: false,
|
|
447
617
|
}
|
|
448
618
|
state.reads.set(read.rel, entry)
|
|
449
619
|
state.readOrder.push(read.rel)
|
|
450
620
|
while (state.readOrder.length > MAX_READS_PER_SESSION) {
|
|
451
621
|
state.reads.delete(state.readOrder.shift())
|
|
452
622
|
}
|
|
453
|
-
return
|
|
454
623
|
}
|
|
455
624
|
|
|
456
625
|
entry.count += 1
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
entry.
|
|
467
|
-
|
|
626
|
+
// v0.17:把「这次读观察到的版本标记」冻结下来 —— 只在成功 read 时更新,
|
|
627
|
+
// 永不被扫描或投影改写(与「归因在读那一刻冻结」是同一条纪律)。
|
|
628
|
+
entry.prevReadMtimeMs = entry.lastReadMtimeMs
|
|
629
|
+
entry.rereadAfterChange = entry.lastReadMtimeMs !== null
|
|
630
|
+
&& read.mtimeMs !== null
|
|
631
|
+
&& read.mtimeMs !== entry.lastReadMtimeMs
|
|
632
|
+
entry.lastReadMtimeMs = Number.isFinite(read.mtimeMs) ? read.mtimeMs : null
|
|
633
|
+
// 「第一次读」按**事件 seq** 认(seq 才是真相,墙钟只用来显示)
|
|
634
|
+
if (read.seq < entry.firstRead.seq || (read.seq === entry.firstRead.seq && read.time < entry.firstRead.at)) {
|
|
635
|
+
entry.firstRead = { ...point }
|
|
636
|
+
}
|
|
637
|
+
if (read.seq > entry.lastRead.seq || (read.seq === entry.lastRead.seq && read.time >= entry.lastRead.at)) {
|
|
638
|
+
entry.lastRead = { ...point }
|
|
639
|
+
}
|
|
640
|
+
if (attribution.insideAtRead) entry.insideReads += 1
|
|
641
|
+
else entry.outsideReads += 1
|
|
642
|
+
if (attribution.tierAtRead === 'primary') entry.primaryReads += 1
|
|
643
|
+
else if (attribution.tierAtRead === 'supporting') entry.supportingReads += 1
|
|
644
|
+
else if (attribution.tierAtRead === 'related') entry.relatedReads += 1
|
|
645
|
+
if (facts.continuedReadAfterExit) entry.continuedReadAfterExit = true
|
|
646
|
+
if (facts.reEntry) entry.reEntry = true
|
|
647
|
+
|
|
648
|
+
const epoch = epochIn(state, attribution.epochId)
|
|
649
|
+
if (epoch) {
|
|
650
|
+
if (!attribution.insideAtRead) epoch.outsideReads += 1
|
|
651
|
+
if (facts.continuedReadAfterExit) epoch.continuedReadsAfterExit += 1
|
|
652
|
+
if (facts.reEntry) epoch.reEntries += 1
|
|
653
|
+
if (attribution.insideAtRead && attribution.tierAtRead) {
|
|
654
|
+
const key = `${attribution.tierAtRead}:${read.rel}`
|
|
655
|
+
if (!epoch.seen.has(key)) {
|
|
656
|
+
epoch.seen.add(key)
|
|
657
|
+
const bucket = epoch[attribution.tierAtRead]
|
|
658
|
+
if (bucket) bucket.read += 1
|
|
659
|
+
}
|
|
660
|
+
if (attribution.tierAtRead === 'primary' && epoch.primary.rel === read.rel) epoch.primary.read = true
|
|
661
|
+
}
|
|
468
662
|
}
|
|
469
663
|
}
|
|
470
664
|
|
|
471
665
|
/**
|
|
472
666
|
* 找出**这次读发生的那一刻**在生效的那份快照(seq ≤ 读的 seq 里最新的那份)。
|
|
473
667
|
* 找不到就返回 null —— 那是「Knit 还没给过上下文就自己读了」,如实记成 outside。
|
|
668
|
+
*
|
|
669
|
+
* 这是 runtime 与离线回放到共用的**同一个纯函数**:两边「规则一致」靠它,
|
|
670
|
+
* 而不是靠两边的数字恰好相等(交付时刻不可观测,数字本来就不可能相等)。
|
|
671
|
+
*
|
|
474
672
|
* @param {object[]} snapshots - 快照栈
|
|
475
673
|
* @param {number} seq - 读的 seq
|
|
476
674
|
* @returns {object|null} 快照
|
|
477
675
|
*/
|
|
478
|
-
function snapshotAt(snapshots, seq) {
|
|
479
|
-
|
|
480
|
-
|
|
676
|
+
export function snapshotAt(snapshots, seq) {
|
|
677
|
+
const list = Array.isArray(snapshots) ? snapshots : []
|
|
678
|
+
for (let i = list.length - 1; i >= 0; i -= 1) {
|
|
679
|
+
if (list[i].seq <= seq) return list[i]
|
|
481
680
|
}
|
|
482
681
|
return null
|
|
483
682
|
}
|
|
484
683
|
|
|
684
|
+
/**
|
|
685
|
+
* 把「这次读」钉到一份快照上 —— 输出的是**读那一刻**的事实,不是当前视图。
|
|
686
|
+
* @param {object|null} snapshot - 读那一刻生效的快照(`snapshotAt()` 的结果)
|
|
687
|
+
* @param {string} rel - 归一化后的路径
|
|
688
|
+
* @returns {{snapshotSeq: number|null, epochId: number|null, tierAtRead: string|null, rankAtRead: number|null, insideAtRead: boolean}} 归因
|
|
689
|
+
*/
|
|
690
|
+
export function attributeRead(snapshot, rel) {
|
|
691
|
+
if (!snapshot || !Array.isArray(snapshot.items)) {
|
|
692
|
+
return { snapshotSeq: null, epochId: null, tierAtRead: null, rankAtRead: null, insideAtRead: false }
|
|
693
|
+
}
|
|
694
|
+
const hit = snapshot.items.find((item) => item.rel === rel)
|
|
695
|
+
return {
|
|
696
|
+
snapshotSeq: Number.isInteger(snapshot.seq) ? snapshot.seq : null,
|
|
697
|
+
epochId: Number.isInteger(snapshot.epochId) ? snapshot.epochId : null,
|
|
698
|
+
tierAtRead: hit ? hit.tier : null,
|
|
699
|
+
rankAtRead: hit ? hit.rank : null,
|
|
700
|
+
insideAtRead: !!hit,
|
|
701
|
+
}
|
|
702
|
+
}
|
|
703
|
+
|
|
704
|
+
/**
|
|
705
|
+
* 推导两个**事实**字段(规格 §12 / §13),只用保留窗口内的快照:
|
|
706
|
+
*
|
|
707
|
+
* - `continuedReadAfterExit`:这次读**在当时那份快照之外**,但更早的某份快照里有这篇
|
|
708
|
+
* ⇒ 「离开上下文之后它仍然被读了」。
|
|
709
|
+
* - `reEntry`:这次读**在当时那份快照之内**,更早的某份快照里也有过,但中间至少有一份
|
|
710
|
+
* 快照里没有它 ⇒ 「离开过,又回来了,而且回来之后被读了」。
|
|
711
|
+
*
|
|
712
|
+
* ⚠️ 这两个字段只是**事实**。它们**不许**被解释成「Agent 不认可新上下文」
|
|
713
|
+
* —— 那是推断,不在这个模块的职责里(规格 §5 Evidence Over Interpretation)。
|
|
714
|
+
*
|
|
715
|
+
* 只在保留窗口内推导:宁可漏记,也不猜。
|
|
716
|
+
*
|
|
717
|
+
* @param {object[]} snapshots - 快照栈
|
|
718
|
+
* @param {string} rel - 归一化后的路径
|
|
719
|
+
* @param {number} readSeq - 这次读的 seq
|
|
720
|
+
* @returns {{continuedReadAfterExit: boolean, reEntry: boolean}} 两个事实
|
|
721
|
+
*/
|
|
722
|
+
export function attributeReadFacts(snapshots, rel, readSeq) {
|
|
723
|
+
const list = Array.isArray(snapshots) ? snapshots : []
|
|
724
|
+
const empty = { continuedReadAfterExit: false, reEntry: false }
|
|
725
|
+
const at = snapshotAt(list, readSeq)
|
|
726
|
+
if (!at) return empty
|
|
727
|
+
const atIndex = list.indexOf(at)
|
|
728
|
+
if (atIndex < 0) return empty
|
|
729
|
+
|
|
730
|
+
const insideNow = at.items.some((item) => item.rel === rel)
|
|
731
|
+
let sawInside = false
|
|
732
|
+
let sawGapAfterInside = false
|
|
733
|
+
for (let i = 0; i < atIndex; i += 1) {
|
|
734
|
+
const has = list[i].items.some((item) => item.rel === rel)
|
|
735
|
+
if (has) sawInside = true
|
|
736
|
+
else if (sawInside) sawGapAfterInside = true
|
|
737
|
+
}
|
|
738
|
+
// 更早的窗口里从来没有过它 —— 那这次既不是「继续读」也不是「重新进入」
|
|
739
|
+
if (!sawInside) return empty
|
|
740
|
+
if (insideNow) return { continuedReadAfterExit: false, reEntry: sawGapAfterInside }
|
|
741
|
+
return { continuedReadAfterExit: true, reEntry: false }
|
|
742
|
+
}
|
|
743
|
+
|
|
744
|
+
/* ── 6. Lifecycle 投影(v0.17) ─────────────────────────────────────── */
|
|
745
|
+
|
|
746
|
+
/**
|
|
747
|
+
* 把一条 read entry 与**当前扫描到的版本标记**投影成一个 lifecycle 事实。
|
|
748
|
+
*
|
|
749
|
+
* 判定优先级是**硬顺序**:`changedAfterLastRead` 先于 `rereadAfterChange` ——
|
|
750
|
+
* 这就是「文件再次变化后状态回到 `读后已更新`」的实现方式。
|
|
751
|
+
*
|
|
752
|
+
* 状态值只有四个英文事实,**中文文案不进数据层**(UI 按 locale 映射):
|
|
753
|
+
* `unread` / `read` / `updated_after_read` / `reread_after_update`。
|
|
754
|
+
*
|
|
755
|
+
* 拿不到版本标记(文件被删、不在扫描结果、stat 失败)时**不做变化判断**,
|
|
756
|
+
* 状态回落到冻结的事实 —— 宁可少说,也不乱说。
|
|
757
|
+
*
|
|
758
|
+
* @param {object|null} entry - `state.reads` 里的 entry
|
|
759
|
+
* @param {number|null} [mtimeMs] - 当前扫描到的版本标记
|
|
760
|
+
* @returns {{status: string, lastReadMtimeMs: number|null, changedAfterLastRead: boolean, rereadAfterChange: boolean}} 状态
|
|
761
|
+
*/
|
|
762
|
+
export function lifecycleOf(entry, mtimeMs = null) {
|
|
763
|
+
const count = entry && Number.isInteger(entry.count) ? entry.count : 0
|
|
764
|
+
const lastReadMtimeMs = entry && Number.isFinite(entry.lastReadMtimeMs) ? entry.lastReadMtimeMs : null
|
|
765
|
+
const changedAfterLastRead = Number.isFinite(mtimeMs) && lastReadMtimeMs !== null
|
|
766
|
+
&& mtimeMs !== lastReadMtimeMs
|
|
767
|
+
let status = 'unread'
|
|
768
|
+
if (count > 0) {
|
|
769
|
+
if (changedAfterLastRead) status = 'updated_after_read'
|
|
770
|
+
else if (entry.rereadAfterChange) status = 'reread_after_update'
|
|
771
|
+
else status = 'read'
|
|
772
|
+
}
|
|
773
|
+
return {
|
|
774
|
+
status,
|
|
775
|
+
lastReadMtimeMs,
|
|
776
|
+
changedAfterLastRead,
|
|
777
|
+
rereadAfterChange: !!(entry && entry.rereadAfterChange),
|
|
778
|
+
}
|
|
779
|
+
}
|
|
780
|
+
|
|
781
|
+
/**
|
|
782
|
+
* 把 `state.reads` 摊平成数组(Map 与数组都收,测试常直接喂数组)。
|
|
783
|
+
* @param {Map<string, object>|object[]} reads - 读证据
|
|
784
|
+
* @returns {object[]} entry 列表
|
|
785
|
+
*/
|
|
786
|
+
function readEntries(reads) {
|
|
787
|
+
if (reads instanceof Map) return [...reads.values()]
|
|
788
|
+
return Array.isArray(reads) ? reads : []
|
|
789
|
+
}
|
|
790
|
+
|
|
791
|
+
/**
|
|
792
|
+
* 「最近读取」= 所有成功 read 里 `lastRead.seq` 最大的那一篇。
|
|
793
|
+
*
|
|
794
|
+
* seq 才是真相(墙钟只用来显示相对时间);seq 相同时取 `lastRead.at` 较大者,
|
|
795
|
+
* 保证同样是确定性的。**不建立第二份 read history**,完全从现有 entry 派生。
|
|
796
|
+
*
|
|
797
|
+
* @param {Map<string, object>|object[]} reads - 读证据
|
|
798
|
+
* @returns {{rel: string, at: number, seq: number, epochId: number|null, tier: string|null, rank: number|null, inside: boolean}|null} 最近读取
|
|
799
|
+
*/
|
|
800
|
+
export function latestReadOf(reads) {
|
|
801
|
+
let best = null
|
|
802
|
+
for (const entry of readEntries(reads)) {
|
|
803
|
+
if (!entry || !entry.lastRead || !(entry.count > 0)) continue
|
|
804
|
+
if (!best
|
|
805
|
+
|| entry.lastRead.seq > best.lastRead.seq
|
|
806
|
+
|| (entry.lastRead.seq === best.lastRead.seq && entry.lastRead.at > best.lastRead.at)) {
|
|
807
|
+
best = entry
|
|
808
|
+
}
|
|
809
|
+
}
|
|
810
|
+
if (!best) return null
|
|
811
|
+
return {
|
|
812
|
+
rel: best.rel,
|
|
813
|
+
at: best.lastRead.at,
|
|
814
|
+
seq: best.lastRead.seq,
|
|
815
|
+
epochId: Number.isInteger(best.lastRead.epochId) ? best.lastRead.epochId : null,
|
|
816
|
+
tier: best.lastRead.tier || null,
|
|
817
|
+
rank: Number.isInteger(best.lastRead.rank) ? best.lastRead.rank : null,
|
|
818
|
+
inside: !!best.lastRead.inside,
|
|
819
|
+
}
|
|
820
|
+
}
|
|
821
|
+
|
|
822
|
+
/**
|
|
823
|
+
* 「当前包外、且真实成功读取过」的文档明细。
|
|
824
|
+
*
|
|
825
|
+
* ⚠️ 与 v0.16 的 `stats.outside` / `stats.outsideReads` **语义不同,两个都要留**:
|
|
826
|
+
* 那个是**历史层**(至少有一次读发生在当时的包外,永不重算),
|
|
827
|
+
* 这个是**当前层**(这篇文档不在**当前**包内,但被读过)—— 当前包变了它就变。
|
|
828
|
+
*
|
|
829
|
+
* @param {Map<string, object>|object[]} reads - 读证据
|
|
830
|
+
* @param {Array<{rel: string}>} items - 当前快照的扁平条目
|
|
831
|
+
* @returns {Array<{rel: string, count: number, lastReadAt: number, seq: number}>} 包外明细(按首次读的 seq 升序)
|
|
832
|
+
*/
|
|
833
|
+
export function outsideDocsOf(reads, items) {
|
|
834
|
+
const inside = new Set()
|
|
835
|
+
for (const item of Array.isArray(items) ? items : []) {
|
|
836
|
+
if (item && typeof item.rel === 'string' && item.rel) inside.add(item.rel)
|
|
837
|
+
}
|
|
838
|
+
const rows = []
|
|
839
|
+
for (const entry of readEntries(reads)) {
|
|
840
|
+
if (!entry || !entry.rel || !(entry.count > 0) || inside.has(entry.rel)) continue
|
|
841
|
+
if (!entry.firstRead || !entry.lastRead) continue
|
|
842
|
+
rows.push({
|
|
843
|
+
rel: entry.rel,
|
|
844
|
+
count: entry.count,
|
|
845
|
+
lastReadAt: entry.lastRead.at,
|
|
846
|
+
seq: entry.firstRead.seq,
|
|
847
|
+
})
|
|
848
|
+
}
|
|
849
|
+
// 阅读顺序(首次读的 seq),同 seq 用 rel 兜底 —— 不用 localeCompare(它依赖运行环境)
|
|
850
|
+
rows.sort((a, b) => (a.seq - b.seq) || (a.rel < b.rel ? -1 : (a.rel > b.rel ? 1 : 0)))
|
|
851
|
+
return rows
|
|
852
|
+
}
|
|
853
|
+
|
|
485
854
|
/**
|
|
486
855
|
* 取一个会话当前的使用情况。没有记录时返回 `null`(不编造空报告)。
|
|
487
856
|
* @param {object} store - store
|
|
488
857
|
* @param {string} sessionId - 会话 id
|
|
858
|
+
* @param {{mtimes?: Map<string, number>|object}} [options] - v0.17:当前版本标记(rel → mtimeMs)
|
|
489
859
|
* @returns {object|null} 使用情况
|
|
490
860
|
*/
|
|
491
|
-
export function usageFor(store, sessionId) {
|
|
861
|
+
export function usageFor(store, sessionId, options = {}) {
|
|
492
862
|
try {
|
|
493
863
|
const state = store && store.sessions.get(sessionId)
|
|
494
864
|
if (!state) return null
|
|
495
|
-
return usageFrom(state)
|
|
865
|
+
return usageFrom(state, options)
|
|
496
866
|
} catch {
|
|
497
867
|
return null
|
|
498
868
|
}
|
|
@@ -501,15 +871,27 @@ export function usageFor(store, sessionId) {
|
|
|
501
871
|
/**
|
|
502
872
|
* 纯函数版:从一个会话状态算出使用情况(测试直接用这个)。
|
|
503
873
|
*
|
|
874
|
+
* 报告分两层,界线是硬的:
|
|
875
|
+
*
|
|
876
|
+
* - **历史层**(`reads[].firstRead/lastRead`、`byTier[].read`、`primaryFollowThrough`、
|
|
877
|
+
* `outside`)—— 全部来自读时冻结的归因,**永不按当前上下文重算**。
|
|
878
|
+
* - **当前层**(`items`、`byTier[].total`、`primaryRel`、`delta`)—— 反映最近一份上下文。
|
|
879
|
+
*
|
|
504
880
|
* 报告里只有**计数与事实**:读了几次、落在哪一层、有几篇在快照之外、
|
|
505
|
-
*
|
|
881
|
+
* 上下文变过几次、有几篇离开后仍被读、有几篇重新进入。**没有分数、没有百分比评分。**
|
|
506
882
|
*
|
|
507
883
|
* @param {object} state - 会话状态
|
|
884
|
+
* @param {{mtimes?: Map<string, number>|object}} [options] - v0.17:当前版本标记(rel → mtimeMs)
|
|
508
885
|
* @returns {object} 使用情况
|
|
509
886
|
*/
|
|
510
|
-
export function usageFrom(state) {
|
|
887
|
+
export function usageFrom(state, options = {}) {
|
|
511
888
|
const snapshots = (state && state.snapshots) || []
|
|
512
889
|
const snapshot = snapshots[snapshots.length - 1] || null
|
|
890
|
+
// v0.17:当前版本标记。不传 = 拿不到变化证据 = 保守(只有 read / reread_after_update)
|
|
891
|
+
const mtimes = options.mtimes instanceof Map
|
|
892
|
+
? options.mtimes
|
|
893
|
+
: new Map(Object.entries(options.mtimes || {}))
|
|
894
|
+
const epochId = snapshot && Number.isInteger(snapshot.epochId) ? snapshot.epochId : null
|
|
513
895
|
const byTier = {
|
|
514
896
|
primary: { total: 0, read: 0 },
|
|
515
897
|
supporting: { total: 0, read: 0 },
|
|
@@ -522,53 +904,115 @@ export function usageFrom(state) {
|
|
|
522
904
|
}
|
|
523
905
|
|
|
524
906
|
const reads = []
|
|
907
|
+
// v0.17:lifecycle 是**读证据 + 当前版本标记**的投影,只含有 read 证据的 rel;
|
|
908
|
+
// 没有 entry 的文档不出现在这里(UI 自行落回 unread),免得把整个工作区灌进来。
|
|
909
|
+
const lifecycle = {}
|
|
525
910
|
for (const entry of state.reads.values()) {
|
|
526
|
-
const
|
|
911
|
+
const currentMtimeMs = mtimes.has(entry.rel) ? mtimes.get(entry.rel) : null
|
|
912
|
+
const life = lifecycleOf(entry, currentMtimeMs)
|
|
913
|
+
lifecycle[entry.rel] = {
|
|
914
|
+
status: life.status,
|
|
915
|
+
count: entry.count,
|
|
916
|
+
lastReadMtimeMs: life.lastReadMtimeMs,
|
|
917
|
+
changedAfterLastRead: life.changedAfterLastRead,
|
|
918
|
+
rereadAfterChange: life.rereadAfterChange,
|
|
919
|
+
lastReadAt: entry.lastRead.at,
|
|
920
|
+
}
|
|
527
921
|
reads.push({
|
|
528
922
|
rel: entry.rel,
|
|
529
923
|
count: entry.count,
|
|
530
|
-
|
|
531
|
-
|
|
532
|
-
|
|
533
|
-
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
|
|
924
|
+
firstRead: { ...entry.firstRead },
|
|
925
|
+
lastRead: { ...entry.lastRead },
|
|
926
|
+
// 兼容别名(旧调用方与测试用的字段名):都是**首次读**的归因,历史值
|
|
927
|
+
firstReadAt: entry.firstRead.at,
|
|
928
|
+
firstReadSeq: entry.firstRead.seq,
|
|
929
|
+
firstTier: entry.firstRead.tier,
|
|
930
|
+
lastReadAt: entry.lastRead.at,
|
|
931
|
+
lastTier: entry.lastRead.tier,
|
|
932
|
+
insideReads: entry.insideReads,
|
|
933
|
+
outsideReads: entry.outsideReads,
|
|
934
|
+
outsideCount: entry.outsideReads,
|
|
935
|
+
outside: entry.outsideReads > 0,
|
|
936
|
+
reEntry: !!entry.reEntry,
|
|
937
|
+
continuedReadAfterExit: !!entry.continuedReadAfterExit,
|
|
938
|
+
// ⚠️ `tier`/`rank` 是**首次读时**的层与名次,不是「它现在在哪一层」。
|
|
939
|
+
tier: entry.firstRead.tier,
|
|
940
|
+
rank: entry.firstRead.rank,
|
|
537
941
|
})
|
|
538
942
|
}
|
|
539
|
-
reads.sort((a, b) => a.
|
|
540
|
-
|
|
943
|
+
reads.sort((a, b) => (a.firstRead.seq - b.firstRead.seq) || (a.firstRead.at - b.firstRead.at))
|
|
944
|
+
// 「这一 Epoch 的某一层里,有几篇真的被读过」—— 只认归因落在**当前 Epoch** 的读
|
|
945
|
+
for (const row of reads) {
|
|
946
|
+
if (row.firstRead.epochId === epochId && row.firstRead.inside && byTier[row.firstRead.tier]) {
|
|
947
|
+
byTier[row.firstRead.tier].read += 1
|
|
948
|
+
}
|
|
949
|
+
}
|
|
541
950
|
|
|
542
|
-
const outside = reads.filter((row) => row.
|
|
951
|
+
const outside = reads.filter((row) => row.outsideReads > 0)
|
|
543
952
|
const first = reads[0] || null
|
|
544
|
-
const
|
|
545
|
-
const
|
|
953
|
+
const epoch = epochIn(state, epochId)
|
|
954
|
+
const primaryRel = epoch && epoch.primary ? epoch.primary.rel : ''
|
|
955
|
+
const continued = reads.filter((row) => row.continuedReadAfterExit)
|
|
956
|
+
const reentries = reads.filter((row) => row.reEntry)
|
|
957
|
+
// 只取 `state.deltas` 的最后一条:与 `delta` 是**同一个对象**的两个引用,永不新建 Delta Store
|
|
958
|
+
const latestDelta = state.deltas[state.deltas.length - 1] || null
|
|
959
|
+
const lastEpochId = Number.isInteger(epochId) ? epochId : 0
|
|
960
|
+
const epochs = (Array.isArray(state.epochs) ? state.epochs : []).map((e) => ({
|
|
961
|
+
epochId: e.epochId,
|
|
962
|
+
snapshotSeq: e.snapshotSeq,
|
|
963
|
+
topic: e.topic,
|
|
964
|
+
task: e.task,
|
|
965
|
+
primary: { rel: e.primary.rel, read: e.primary.read },
|
|
966
|
+
supporting: { total: e.supporting.total, read: e.supporting.read },
|
|
967
|
+
related: { total: e.related.total, read: e.related.read },
|
|
968
|
+
outsideReads: e.outsideReads,
|
|
969
|
+
continuedReadsAfterExit: e.continuedReadsAfterExit,
|
|
970
|
+
reEntries: e.reEntries,
|
|
971
|
+
}))
|
|
546
972
|
|
|
547
973
|
return {
|
|
548
974
|
at: snapshot ? snapshot.at : 0,
|
|
549
975
|
seq: snapshot ? snapshot.seq : -1,
|
|
976
|
+
epochId,
|
|
550
977
|
task: snapshot ? snapshot.task : '',
|
|
551
978
|
topic: snapshot ? snapshot.topic : '',
|
|
552
979
|
items: snapshot ? snapshot.items.map((item) => ({ ...item })) : [],
|
|
553
980
|
reads,
|
|
554
|
-
|
|
981
|
+
// §16 Epoch 级使用情况:内部 / 离线回放 / 将来评估用,v0.16 **不上**任何 UI 与工具输出
|
|
982
|
+
epochs,
|
|
983
|
+
delta: latestDelta,
|
|
984
|
+
// ── v0.17 的四个新投影(全部是当前层派生物;`stats` 一个键都不动) ──
|
|
985
|
+
// `latestDelta` 与 `delta` 同引用,保证两处永远一致
|
|
986
|
+
latestDelta,
|
|
987
|
+
lifecycle,
|
|
988
|
+
recentRead: latestReadOf(state.reads),
|
|
989
|
+
outsideDocs: outsideDocsOf(state.reads, snapshot ? snapshot.items : []),
|
|
555
990
|
stats: {
|
|
556
991
|
reads: reads.reduce((sum, row) => sum + row.count, 0),
|
|
557
992
|
distinct: reads.length,
|
|
558
993
|
outside: outside.length,
|
|
559
994
|
outsideReads: outside.map((row) => row.rel),
|
|
560
|
-
|
|
995
|
+
// 第一条成功读落在哪一层:primary / supporting / related / outside / null
|
|
996
|
+
firstReadTier: first ? (first.firstRead.inside ? first.firstRead.tier : 'outside') : null,
|
|
561
997
|
firstReadRel: first ? first.rel : '',
|
|
562
|
-
firstReadAt: first ? first.
|
|
563
|
-
|
|
564
|
-
|
|
565
|
-
|
|
998
|
+
firstReadAt: first ? first.firstRead.at : 0,
|
|
999
|
+
firstReadEpoch: first ? first.firstRead.epochId : null,
|
|
1000
|
+
primaryRel,
|
|
1001
|
+
// 「这个 Epoch 先看的那篇被真的读了吗」—— 按 Epoch 归因的布尔,不是成功率
|
|
1002
|
+
primaryFollowThrough: !!(epoch && epoch.primary && epoch.primary.read),
|
|
566
1003
|
byTier,
|
|
567
|
-
supportingCoverage:
|
|
1004
|
+
supportingCoverage: byTier.supporting.total === 0 ? null : byTier.supporting.read / byTier.supporting.total,
|
|
1005
|
+
// 事实计数(不是「Agent 不认可新上下文」这种解释)
|
|
1006
|
+
continuedReadsAfterExit: continued.length,
|
|
1007
|
+
reEntries: reentries.length,
|
|
568
1008
|
churn: {
|
|
569
|
-
//
|
|
570
|
-
|
|
571
|
-
|
|
1009
|
+
// 观察到的**不同 Epoch 数**(= 最后一份 Epoch 的编号;被淘汰的也算过)
|
|
1010
|
+
epochs: lastEpochId,
|
|
1011
|
+
// 变化次数 = 换过几次上下文(第一份不算变化)
|
|
1012
|
+
changes: lastEpochId > 0 ? lastEpochId - 1 : 0,
|
|
1013
|
+
// ⚠️ `snapshots` 是客户端已经在用的键名(`usage.changes` 文案),保留它 = 变化次数
|
|
1014
|
+
snapshots: lastEpochId > 0 ? lastEpochId - 1 : 0,
|
|
1015
|
+
deltas: lastEpochId > 0 ? lastEpochId - 1 : 0,
|
|
572
1016
|
// 手上还留着几条 Delta 明细
|
|
573
1017
|
retained: state.deltas.length,
|
|
574
1018
|
appeared: state.churn.appeared,
|
|
@@ -594,7 +1038,10 @@ export function auditPayload(usage) {
|
|
|
594
1038
|
supportingRead: s.byTier.supporting.read,
|
|
595
1039
|
supportingTotal: s.byTier.supporting.total,
|
|
596
1040
|
readsOutside: s.outside,
|
|
597
|
-
contextChanges: s.churn.
|
|
1041
|
+
contextChanges: s.churn.changes,
|
|
1042
|
+
epochs: s.churn.epochs,
|
|
1043
|
+
continuedReadsAfterExit: s.continuedReadsAfterExit,
|
|
1044
|
+
reEntries: s.reEntries,
|
|
598
1045
|
}
|
|
599
1046
|
}
|
|
600
1047
|
|