dsh-knit 0.16.0 → 0.18.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.
@@ -18,10 +18,17 @@
18
18
  *
19
19
  * ⚠️ 本模块**不碰 Retrieval**(BM25 / IDF / 关键词抽取 / 长度归一化 / freshness 一行不改),
20
20
  * 也**不落盘、不联网、不调模型、不写 memory、不自动干预上下文**。
21
- * 读证据的唯一来源是宿主派发的 `session/event`(v0.16 起):**不再**调用
21
+ * 读证据的唯一来源是宿主派发的 `session/event`(v0.16 起):本模块**自己**从不调用
22
22
  * `session.snapshotEvents()` —— 那个 API 已被 DSH 标记 deprecated
23
23
  * (「new production calls are prohibited」),而且它在 fork 会话上会把父会话继承来的
24
- * 前缀事件也算进来。代价是:订阅之前发生的事件不回溯,只记订阅之后真实发生的读。
24
+ * 前缀事件也算进来。代价是:订阅之前发生的事件不会自动进来。
25
+ *
26
+ * v0.17 修订:闸门开晚时(真实用法:读完才想起来看面板),宿主可以在**开闸那一刻**
27
+ * 回填一次会话已有的事件(`markBackfilled()` 由宿主在 `ingestEvents()` 之后调用)。
28
+ * 本模块仍然零 I/O、零网络、零模型 —— 事件是宿主喂进来的,它只多知道一件事:
29
+ * 「这批读是补记的」。**顺序是这个机制的组成部分**:`recordRead()` 在事件入库那一刻就把
30
+ * 归因冻结,所以宿主必须**先把手上那份包 `noteSnapshot()` 掉、再喂补记的事件**,
31
+ * 否则那些读会在「一份快照都还没有」的状态下被冻成包外(规格 §6:不知道就不要说)。
25
32
  *
26
33
  * 这里**没有**:trajectory、span、runtime trace、reasoning、成功率、置信度、归一化评分、
27
34
  * quality score、memory 写入。Usage 不是分数,是计数与事实。
@@ -323,6 +330,41 @@ export function isAudited(store, sessionId) {
323
330
  return !!(store && sessionId && store.audited.has(sessionId))
324
331
  }
325
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
+
326
368
  /**
327
369
  * 取(或建)一个会话的状态,并按 LRU 触摸 —— 会话数量超上限时淘汰最久没碰的。
328
370
  * @param {object} store - store
@@ -343,6 +385,9 @@ function stateOf(store, sessionId) {
343
385
  // ⚠️ 这里**不再**有 `changes` 计数:上下文换过几次 = 最后一个 Epoch 的编号 - 1,
344
386
  // 而 Epoch 编号是单调的(被淘汰的 Epoch 也计过数),所以不需要额外记一个累计值。
345
387
  churn: { appeared: 0, disappeared: 0, moved: 0, taskChanged: 0 },
388
+ // v0.17 修订:这份状态里的读是**回填**进来的(开闸时补记的历史)。
389
+ // 它只用于「一个会话只回填一次」,不影响归因 —— 归因由宿主喂事件的顺序保证。
390
+ backfilled: false,
346
391
  }
347
392
  store.sessions.set(sessionId, state)
348
393
  }
@@ -372,6 +417,35 @@ function stateOf(store, sessionId) {
372
417
  * @param {{root?: string}} [options] - 选项
373
418
  * @returns {{ok: boolean, reads: number, cursor: number}} 结果
374
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
+ */
375
449
  export function ingestEvents(store, sessionId, events, options = {}) {
376
450
  try {
377
451
  if (!store || !sessionId) return { ok: false, reads: 0, cursor: -1 }
@@ -383,7 +457,14 @@ export function ingestEvents(store, sessionId, events, options = {}) {
383
457
  })
384
458
  state.pending = pending
385
459
  if (cursor > state.seq) state.seq = cursor
386
- for (const read of reads) recordRead(state, read)
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
+ }
387
468
  return { ok: true, reads: reads.length, cursor: state.seq }
388
469
  } catch {
389
470
  return { ok: false, reads: 0, cursor: -1 }
@@ -409,10 +490,11 @@ export function noteSnapshot(store, sessionId, pack, meta = {}) {
409
490
  try {
410
491
  if (!store || !sessionId || !pack) return null
411
492
  const state = stateOf(store, sessionId)
412
- const next = snapshotOf(pack, {
413
- seq: Number.isInteger(meta.seq) ? meta.seq : state.seq,
414
- at: meta.at,
415
- })
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 })
416
498
  const prev = state.snapshots[state.snapshots.length - 1] || null
417
499
 
418
500
  if (prev && prev.sig === next.sig) {
@@ -528,6 +610,10 @@ function recordRead(state, read) {
528
610
  relatedReads: 0,
529
611
  reEntry: false,
530
612
  continuedReadAfterExit: false,
613
+ // v0.17:首次读之前没有「上一次」,三个字段的初值就是「不知道」
614
+ lastReadMtimeMs: null,
615
+ prevReadMtimeMs: null,
616
+ rereadAfterChange: false,
531
617
  }
532
618
  state.reads.set(read.rel, entry)
533
619
  state.readOrder.push(read.rel)
@@ -537,6 +623,13 @@ function recordRead(state, read) {
537
623
  }
538
624
 
539
625
  entry.count += 1
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
540
633
  // 「第一次读」按**事件 seq** 认(seq 才是真相,墙钟只用来显示)
541
634
  if (read.seq < entry.firstRead.seq || (read.seq === entry.firstRead.seq && read.time < entry.firstRead.at)) {
542
635
  entry.firstRead = { ...point }
@@ -648,17 +741,128 @@ export function attributeReadFacts(snapshots, rel, readSeq) {
648
741
  return { continuedReadAfterExit: true, reEntry: false }
649
742
  }
650
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
+
651
854
  /**
652
855
  * 取一个会话当前的使用情况。没有记录时返回 `null`(不编造空报告)。
653
856
  * @param {object} store - store
654
857
  * @param {string} sessionId - 会话 id
858
+ * @param {{mtimes?: Map<string, number>|object}} [options] - v0.17:当前版本标记(rel → mtimeMs)
655
859
  * @returns {object|null} 使用情况
656
860
  */
657
- export function usageFor(store, sessionId) {
861
+ export function usageFor(store, sessionId, options = {}) {
658
862
  try {
659
863
  const state = store && store.sessions.get(sessionId)
660
864
  if (!state) return null
661
- return usageFrom(state)
865
+ return usageFrom(state, options)
662
866
  } catch {
663
867
  return null
664
868
  }
@@ -677,11 +881,16 @@ export function usageFor(store, sessionId) {
677
881
  * 上下文变过几次、有几篇离开后仍被读、有几篇重新进入。**没有分数、没有百分比评分。**
678
882
  *
679
883
  * @param {object} state - 会话状态
884
+ * @param {{mtimes?: Map<string, number>|object}} [options] - v0.17:当前版本标记(rel → mtimeMs)
680
885
  * @returns {object} 使用情况
681
886
  */
682
- export function usageFrom(state) {
887
+ export function usageFrom(state, options = {}) {
683
888
  const snapshots = (state && state.snapshots) || []
684
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 || {}))
685
894
  const epochId = snapshot && Number.isInteger(snapshot.epochId) ? snapshot.epochId : null
686
895
  const byTier = {
687
896
  primary: { total: 0, read: 0 },
@@ -695,7 +904,20 @@ export function usageFrom(state) {
695
904
  }
696
905
 
697
906
  const reads = []
907
+ // v0.17:lifecycle 是**读证据 + 当前版本标记**的投影,只含有 read 证据的 rel;
908
+ // 没有 entry 的文档不出现在这里(UI 自行落回 unread),免得把整个工作区灌进来。
909
+ const lifecycle = {}
698
910
  for (const entry of state.reads.values()) {
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
+ }
699
921
  reads.push({
700
922
  rel: entry.rel,
701
923
  count: entry.count,
@@ -732,6 +954,8 @@ export function usageFrom(state) {
732
954
  const primaryRel = epoch && epoch.primary ? epoch.primary.rel : ''
733
955
  const continued = reads.filter((row) => row.continuedReadAfterExit)
734
956
  const reentries = reads.filter((row) => row.reEntry)
957
+ // 只取 `state.deltas` 的最后一条:与 `delta` 是**同一个对象**的两个引用,永不新建 Delta Store
958
+ const latestDelta = state.deltas[state.deltas.length - 1] || null
735
959
  const lastEpochId = Number.isInteger(epochId) ? epochId : 0
736
960
  const epochs = (Array.isArray(state.epochs) ? state.epochs : []).map((e) => ({
737
961
  epochId: e.epochId,
@@ -756,7 +980,13 @@ export function usageFrom(state) {
756
980
  reads,
757
981
  // §16 Epoch 级使用情况:内部 / 离线回放 / 将来评估用,v0.16 **不上**任何 UI 与工具输出
758
982
  epochs,
759
- delta: state.deltas[state.deltas.length - 1] || null,
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 : []),
760
990
  stats: {
761
991
  reads: reads.reduce((sum, row) => sum + row.count, 0),
762
992
  distinct: reads.length,
package/src/host/index.js CHANGED
@@ -14,7 +14,7 @@
14
14
  * 零模型、零网络出口:只读本地文件与会话日志。
15
15
  */
16
16
  import { readFile, readdir, stat } from 'node:fs/promises'
17
- import { createReadStream } from 'node:fs'
17
+ import { createReadStream, statSync } from 'node:fs'
18
18
  import { join, relative, resolve, sep } from 'node:path'
19
19
  import { homedir } from 'node:os'
20
20
  import { extractKeywords, rankByRelevance, topicLabel } from './relevance.js'
@@ -31,6 +31,7 @@ import { buildContext } from './context.js'
31
31
  // 把两者接起来算 Usage。**不订阅 event bus、不落盘、不联网、不调模型、不改 Retrieval。**
32
32
  import {
33
33
  createStore, activateAudit, isAudited, ingestEvents, noteSnapshot, usageFor, getAuditSummary,
34
+ markBackfilled, isBackfilled,
34
35
  } from './feedback.js'
35
36
 
36
37
  export const name = 'dsh-knit'
@@ -681,6 +682,9 @@ export async function scan(root, limit, options = {}) {
681
682
  // `context.task` 已经把这个值带出去了,顶层再来一份是重复。
682
683
  task: mode === 'relevance' ? task : '',
683
684
  docs: ordered.slice(0, limit).map(publicDoc),
685
+ // 全量列表(未按 limit 切片)。**内部输入**:v0.17 的 lifecycle 需要「被读过但
686
+ // 不一定落在当前页」的文档的当前 mtime。由 `publicScanPayload()` 剥掉。
687
+ allDocs: ordered,
684
688
  }
685
689
  }
686
690
 
@@ -697,9 +701,10 @@ export async function scan(root, limit, options = {}) {
697
701
  */
698
702
  export function publicScanPayload(payload) {
699
703
  if (!payload || typeof payload !== 'object') return payload
700
- const { ranked, task, ...rest } = payload
704
+ const { ranked, task, allDocs, ...rest } = payload
701
705
  void ranked
702
706
  void task
707
+ void allDocs
703
708
  return rest
704
709
  }
705
710
 
@@ -1071,10 +1076,13 @@ function sendMedia(req, res, info) {
1071
1076
  * 2. 把刚交出去的 Context Pack 记成 Context Snapshot(带 `epochId`);
1072
1077
  * 3. 给面板与 `knit_docs` 提供「**上一份**包之后发生了什么」。
1073
1078
  *
1074
- * ⚠️ v0.16 起**不再**从 `session.snapshotEvents()` 拉事件:那个 API 已被 DSH 标记
1075
- * deprecated(「new production calls are prohibited」),而且它会把这个会话从父会话
1076
- * fork 继承来的前缀事件也算进来。代价是:订阅之前发生过的事件不回溯 —— 宁可少记,
1077
- * 也不去猜一段没法按当时上下文归因的历史。
1079
+ * ⚠️ 读证据走**订阅**(`session/event`),不拿 `session.snapshotEvents()` 当审计来源:
1080
+ * 那个 API 已被 DSH 标记 deprecated(「new production calls are prohibited」)。
1081
+ * 代价是闸门打开**之前**已经发生的读不在订阅范围内,所以**开闸时回填一次**(v0.17 修订,用户拍板):
1082
+ * 闸门只在你打开开关时才开,而真实用法是读完才看面板 —— 不回填就只能把真实发生过的读
1083
+ * 显示成「未读」,那是假话(规格 §3)。回填的代价被三条边界锁住:一个会话只做一次、
1084
+ * 只在开闸那一 tick、仍然零 I/O 零网络零模型且只在内存里。已知的不精确:回填的读按
1085
+ * 「我们已知最早的那份包」(= 开闸时看到的那份)归因,更早的包无从得知,所以**宁可少说**。
1078
1086
  *
1079
1087
  * 记账只在**被显式打开**的会话里发生(面板的「使用情况」开关,或 `knit_docs` 的
1080
1088
  * `audit: true`)—— 默认一条事件的处理成本就是一次 Map 查找。
@@ -1084,6 +1092,52 @@ function sendMedia(req, res, info) {
1084
1092
  /** 进程内唯一的 feedback store(按会话分片,会话数与篇数都有硬上限)。 */
1085
1093
  const feedbackStore = createStore()
1086
1094
 
1095
+ /**
1096
+ * 宿主会话注册表(`webCtx.sessions`)的引用,只给**工具**那条路用。
1097
+ *
1098
+ * 面板那条路拿得到 `webCtx`;`knit_docs` 的 `audit: true` 走的是 `auditBridge`,
1099
+ * 它也需要在开闸时回填历史(见 `backfillFeedback`),所以在这里留一份引用。
1100
+ */
1101
+ let sessionsRef = null
1102
+
1103
+ /**
1104
+ * 按会话 id 取宿主会话对象(拿不到就 undefined —— 回填只是「能补就补」)。
1105
+ * @param {string} sessionId - 会话 id
1106
+ * @returns {object|undefined} 会话
1107
+ */
1108
+ function sessionFor(sessionId) {
1109
+ try {
1110
+ if (!sessionId || !sessionsRef || typeof sessionsRef.get !== 'function') return undefined
1111
+ return sessionsRef.get(sessionId)
1112
+ } catch {
1113
+ return undefined
1114
+ }
1115
+ }
1116
+
1117
+ /**
1118
+ * 取一个**已归一化**的工作区相对路径的版本标记(`mtimeMs`)。
1119
+ *
1120
+ * v0.17 用它回答「这篇文档被读过之后改过吗」。只接受走过 `normalizeRel` 的 `rel`
1121
+ * (无 `..`、无绝对路径逃逸、无 URL scheme),再 `resolve` 到 root 之下 `statSync` ——
1122
+ * 不新增任何用户可控的路径来源。任何异常 / 非有限值都返回 `null`:拿不到证据就不说。
1123
+ *
1124
+ * ⚠️ `feedback.js` 保持零 I/O,所以取样只能由宿主注入(`options.stat`)。
1125
+ *
1126
+ * @param {string} root - 工作区根(绝对路径)
1127
+ * @param {string} rel - 已归一化的工作区相对路径
1128
+ * @returns {number|null} mtimeMs,或 null
1129
+ */
1130
+ function mtimeOf(root, rel) {
1131
+ try {
1132
+ if (typeof root !== 'string' || !root) return null
1133
+ if (typeof rel !== 'string' || !rel) return null
1134
+ const st = statSync(resolve(root, rel))
1135
+ return Number.isFinite(st.mtimeMs) ? st.mtimeMs : null
1136
+ } catch {
1137
+ return null
1138
+ }
1139
+ }
1140
+
1087
1141
  /**
1088
1142
  * 订阅宿主的会话事件流,把真实的读记进 store。
1089
1143
  *
@@ -1101,17 +1155,81 @@ function onSessionEvent(session, event) {
1101
1155
  const sessionId = session && typeof session.id === 'string' ? session.id : ''
1102
1156
  if (!sessionId || !event) return
1103
1157
  if (!isAudited(feedbackStore, sessionId)) return
1104
- ingestEvents(feedbackStore, sessionId, [event], { root: rootOfSession(session) })
1158
+ const root = rootOfSession(session)
1159
+ // v0.17:成功读被确认的那一刻取一次版本标记。取样只发生在**新事件**上,
1160
+ // 所以同一事件重复派发既不重复计数,也不重复取样。
1161
+ ingestEvents(feedbackStore, sessionId, [event], {
1162
+ root,
1163
+ stat: (rel) => mtimeOf(root, rel),
1164
+ })
1105
1165
  } catch { /* 记账坏了不许影响宿主 */ }
1106
1166
  }
1107
1167
 
1108
1168
  /**
1109
- * 打开某个会话的记账(面板的「使用情况」开关走它)。
1169
+ * 把会话**已经发生**的事件补进 store(v0.17 修订,用户拍板)。
1170
+ *
1171
+ * 为什么需要:记账闸门只在面板带 `usage=1`(或 `knit_docs` 传 `audit: true`)那一刻才开,
1172
+ * 而真实用法是**读完才想起来看面板**。那些读发生在闸门外,Knit 手上零证据,面板只能把它们
1173
+ * 显示成「未读」—— 那是**假话**(规格 §3:只讲事实,不讲推断)。所以开闸时把会话已有的历史
1174
+ * 一次性补进 store:宁可补记,不可诬告。
1175
+ *
1176
+ * ⚠️ 顺序是这个函数的一部分:**先记下手上这份包,再喂事件**。`recordRead()` 在事件入库那一刻
1177
+ * 就把归因(`tier` / `inside` / `epochId`)结算并**冻结**,之后不再重算。若先喂事件,那些读会在
1178
+ * 「一份快照都还没有」的状态下被冻成包外,而「它当时不在 Context Pack 里」正是我们**不知道**的事。
1179
+ * 先记包则快照 seq 自然是 `-1`(此刻 `state.seq` 也是 `-1`),补记的读归到「我们已知最早的那份包」。
1180
+ *
1181
+ * 代价与边界(都写在这里,免得日后被误解成「全量扫描」):
1182
+ * - 只在**开闸那一刻**读一次 `snapshotEvents()`,一个会话只做一次(`isBackfilled`);
1183
+ * - 仍然**零 I/O、零网络、零模型**:事件来自宿主内存,版本标记来自一次 `statSync`;
1184
+ * - 仍然只在内存里(重启即丢),也仍然只在有人看的时候才发生;
1185
+ * - `ingestEvents` 自己按 `seq` 水位去重,所以回填过的事件稍后再从订阅派发一次
1186
+ * 也不会重复计数(规格 §18 Case 12 的幂等性照旧)。
1187
+ *
1110
1188
  * @param {string} sessionId - 会话 id
1189
+ * @param {object} session - 宿主会话(要有 `snapshotEvents()`)
1190
+ * @param {object|null} [pack] - 此刻手上这份 Context Pack;给了就先记成第一份快照
1191
+ * @returns {number} 补进来的读条数(拿不到 / 已回填过 → 0)
1192
+ */
1193
+ function backfillFeedback(sessionId, session, pack = null) {
1194
+ try {
1195
+ if (!sessionId || !session) return 0
1196
+ if (typeof session.snapshotEvents !== 'function') return 0
1197
+ if (isBackfilled(feedbackStore, sessionId)) return 0
1198
+ const events = session.snapshotEvents()
1199
+ if (!Array.isArray(events) || events.length === 0) return 0
1200
+ const root = rootOfSession(session)
1201
+ // 先记包(见上面的顺序说明):快照 seq 会是 -1,于是补记的读能归到它身上。
1202
+ // ⚠️ 不传 `at`:这份包代表的是「会话开始时的那份上下文」,与 seq = -1 同一口径。
1203
+ // 传此刻的墙钟会让第一次记账的 `usage.at` 从「还没有上一份」(0) 变成一个假的具体时间,
1204
+ // 而这一请求真正的交包时间由下面 `auditBridge.note()` 那次去重更新写进去。
1205
+ if (pack) noteSnapshot(feedbackStore, sessionId, pack)
1206
+ const result = ingestEvents(feedbackStore, sessionId, events, {
1207
+ root,
1208
+ stat: (rel) => mtimeOf(root, rel),
1209
+ })
1210
+ if (!result.ok) return 0
1211
+ markBackfilled(feedbackStore, sessionId)
1212
+ return result.reads
1213
+ } catch {
1214
+ return 0
1215
+ }
1216
+ }
1217
+
1218
+ /**
1219
+ * 打开某个会话的记账(面板的「使用情况」开关走它),并顺手回填已有历史。
1220
+ *
1221
+ * ⚠️ 回填**必须**发生在开闸之后、同一个 tick 里:开闸前的事件由回填补,
1222
+ * 开闸后的事件走订阅,两者在 `seq` 上严丝合缝,不会漏也不会重。
1223
+ *
1224
+ * @param {string} sessionId - 会话 id
1225
+ * @param {object} [session] - 宿主会话;省略则只开闸不回填
1226
+ * @param {object|null} [pack] - 此刻手上的 Context Pack,交给回填当第一份快照
1111
1227
  * @returns {boolean} 是否成功
1112
1228
  */
1113
- export function activateFeedback(sessionId) {
1114
- return activateAudit(feedbackStore, sessionId)
1229
+ export function activateFeedback(sessionId, session = null, pack = null) {
1230
+ const ok = activateAudit(feedbackStore, sessionId)
1231
+ if (ok) backfillFeedback(sessionId, session, pack)
1232
+ return ok
1115
1233
  }
1116
1234
 
1117
1235
  /**
@@ -1124,23 +1242,46 @@ export function feedbackActive(sessionId) {
1124
1242
  }
1125
1243
 
1126
1244
  /**
1127
- * 线路上的紧凑使用情况:面板只需要**计数**与最近一次变化,不需要 200 条明细。
1245
+ * 线路上的紧凑使用情况:面板只需要**计数**、**四态生命周期**与最近一次变化,
1246
+ * 不需要 200 条明细。
1128
1247
  * @param {object|null} usage - `usageFor()` 的结果
1129
1248
  * @param {number} [limit] - 明细最多带几条
1249
+ * @param {Set<string>|null} [rels] - v0.17:本次真正要渲染的文档(当前页 ∪ 包外明细);
1250
+ * 省略/为 null 时不裁剪 lifecycle(测试与其它调用方兼容)
1130
1251
  * @returns {object|null} 紧凑视图
1131
1252
  */
1132
- export function publicUsage(usage, limit = 20) {
1253
+ export function publicUsage(usage, limit = 20, rels = null) {
1133
1254
  if (!usage || !usage.stats) return null
1255
+ const delta = usage.delta ? {
1256
+ appeared: usage.delta.appeared.slice(0, limit),
1257
+ disappeared: usage.delta.disappeared.slice(0, limit),
1258
+ moved: usage.delta.moved.slice(0, limit),
1259
+ taskChanged: !!usage.delta.taskChanged,
1260
+ } : null
1261
+
1262
+ // v0.17:lifecycle 每个条目只带 UI 要用的三个字段(状态值仍是英文事实,
1263
+ // 中文只在客户端词典里)。按 rels 裁剪是刻意的:只发真正会渲染的那些行。
1264
+ const source = usage.lifecycle && typeof usage.lifecycle === 'object' ? usage.lifecycle : {}
1265
+ const lifecycle = {}
1266
+ for (const rel of Object.keys(source)) {
1267
+ if (rels && !rels.has(rel)) continue
1268
+ const row = source[rel]
1269
+ if (!row) continue
1270
+ lifecycle[rel] = { status: row.status, count: row.count, lastReadAt: row.lastReadAt }
1271
+ }
1272
+
1134
1273
  return {
1135
1274
  at: usage.at,
1136
1275
  epochId: usage.epochId,
1137
1276
  stats: { ...usage.stats, outsideReads: usage.stats.outsideReads.slice(0, limit) },
1138
- delta: usage.delta ? {
1139
- appeared: usage.delta.appeared.slice(0, limit),
1140
- disappeared: usage.delta.disappeared.slice(0, limit),
1141
- moved: usage.delta.moved.slice(0, limit),
1142
- taskChanged: !!usage.delta.taskChanged,
1143
- } : null,
1277
+ delta,
1278
+ // v0.17 新增(`latestDelta` 与 `delta` 同值:前者是 UI 唯一读的那个键)
1279
+ latestDelta: delta,
1280
+ recentRead: usage.recentRead ? { ...usage.recentRead } : null,
1281
+ outsideDocs: (Array.isArray(usage.outsideDocs) ? usage.outsideDocs : [])
1282
+ .slice(0, limit)
1283
+ .map((row) => ({ ...row })),
1284
+ lifecycle,
1144
1285
  }
1145
1286
  }
1146
1287
 
@@ -1153,10 +1294,11 @@ export function publicUsage(usage, limit = 20) {
1153
1294
  * 交包只是记一份快照(`seq` 用 store 自己的事件水位)。
1154
1295
  */
1155
1296
  const auditBridge = {
1156
- usage(sessionId) {
1297
+ usage(sessionId, mtimes) {
1157
1298
  try {
1158
1299
  if (!sessionId) return null
1159
- return usageFor(feedbackStore, sessionId)
1300
+ // mtimes:v0.17 的当前版本标记(rel → mtimeMs)。不传就是保守投影(拿不到变化证据)。
1301
+ return usageFor(feedbackStore, sessionId, { mtimes })
1160
1302
  } catch {
1161
1303
  return null
1162
1304
  }
@@ -1174,7 +1316,10 @@ const auditBridge = {
1174
1316
  if (!sessionId || !pack) return null
1175
1317
  // 走到这里说明记账是**显式**的(面板带了 `usage=1`,或 agent 传了 `audit: true`
1176
1318
  // 且 `tool.js` 只在那一刻调 note)—— 所以在这里开闸是安全的。
1319
+ // v0.17 修订:开闸的同时回填会话已有的事件,否则「读完才打开」的那些读
1320
+ // 会被显示成「未读」——那是假话。
1177
1321
  activateAudit(feedbackStore, sessionId)
1322
+ backfillFeedback(sessionId, sessionFor(sessionId), pack)
1178
1323
  // 不传 `seq`:noteSnapshot 用会话当前的**事件水位**,也就是「交这份包时
1179
1324
  // 已经发生到第几个事件」—— seq ≤ 它的读才算在这份包里。
1180
1325
  return noteSnapshot(feedbackStore, sessionId, pack, { at: Date.now() })
@@ -1196,6 +1341,8 @@ export function apply(ctx) {
1196
1341
  ctx.on('session/event', onSessionEvent, { global: true })
1197
1342
 
1198
1343
  ctx.inject(['webServer', 'sessions'], (webCtx) => {
1344
+ // v0.17 修订:工具那条路(`knit_docs audit:true`)也要能回填,所以留一份引用。
1345
+ sessionsRef = webCtx.sessions
1199
1346
  const handler = async (req, res) => {
1200
1347
  if (!isLoopback(req.socket?.remoteAddress)) {
1201
1348
  sendJson(res, 403, { ok: false, code: ERROR_CODES.loopbackOnly })
@@ -1224,12 +1371,32 @@ export function apply(ctx) {
1224
1371
  // ⚠️ 带上 `context` 是**可选**的(老客户端忽略它),而 `docs` 一字未动。
1225
1372
  body.context = await contextPayload(root, payload, sort, kind)
1226
1373
  // v0.15:面板把「使用情况」开关打开后,请求会带 `usage=1` —— 那一刻开始记账。
1374
+ // v0.17 修订:开闸的同时**回填**这个会话已经发生的事件(闸门开晚时,
1375
+ // 前面那些真实发生过的读不该被显示成「未读」——那是假话,见 `backfillFeedback`)。
1227
1376
  // ⚠️ 默认(不带这个参数且本会话从未打开过)**一个字节都不记**。
1228
- if (sessionId && url.searchParams.get('usage') === '1') activateFeedback(sessionId)
1377
+ if (sessionId && url.searchParams.get('usage') === '1') {
1378
+ // 交上此刻手上的包,回填才能把补记的读归到「我们已知最早的那份包」,而不是包外。
1379
+ activateFeedback(sessionId, sessionOf(webCtx, sessionId), body.context)
1380
+ }
1229
1381
  if (sessionId && feedbackActive(sessionId)) {
1230
1382
  // ⚠️ 顺序是刻意的:先取 usage(它报告的是**上一份**包之后发生了什么),
1231
1383
  // 再把这一份包记成新快照 —— 从下一次请求起,它才是「上一份」。
1232
- body.usage = publicUsage(auditBridge.usage(sessionId))
1384
+ //
1385
+ // v0.17:当前版本标记用**全量**扫描结果建立,不是被 limit 截断的这一页 ——
1386
+ // 否则一篇被读过、但没落在当前页的文档拿不到当前 mtime,会永远停在「已读」。
1387
+ const full = Array.isArray(payload.allDocs) && payload.allDocs.length > 0
1388
+ ? payload.allDocs
1389
+ : payload.docs
1390
+ const mtimes = new Map(full.map((doc) => [doc.rel, doc.mtimeMs]))
1391
+ const usage = auditBridge.usage(sessionId, mtimes)
1392
+ // lifecycle 只发真正会渲染的那些行:当前页 ∪ 包外明细(后者的「已读 ×N」
1393
+ // 也要显示,只按当前页裁剪会把它们的状态丢掉)。
1394
+ const rels = new Set([
1395
+ ...body.docs.map((doc) => doc.rel),
1396
+ ...((usage && Array.isArray(usage.outsideDocs) ? usage.outsideDocs : [])
1397
+ .map((row) => row.rel)),
1398
+ ])
1399
+ body.usage = publicUsage(usage, 20, rels)
1233
1400
  if (body.context) auditBridge.note(sessionId, body.context)
1234
1401
  }
1235
1402
  sendJson(res, 200, body)