dsh-knit 0.14.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 +279 -0
- package/README.en.md +81 -23
- package/README.md +71 -20
- package/package.json +3 -2
- package/src/client/client.js +237 -98
- package/src/host/feedback.js +858 -0
- package/src/host/index.js +171 -7
- package/src/host/tool.js +63 -3
- package/test/client.test.mjs +279 -31
- package/test/context-delta.test.mjs +322 -0
- package/test/context-effectiveness.test.mjs +309 -0
- package/test/context-feedback-eval.test.mjs +220 -0
- package/test/feedback.test.mjs +247 -0
- package/test/host-http.test.mjs +249 -3
- package/test/i18n.test.mjs +22 -23
- package/test/path.test.mjs +6 -6
- package/test/peek.test.mjs +80 -26
- package/test/tool.test.mjs +132 -5
- package/tools/context-feedback-eval.mjs +362 -0
|
@@ -0,0 +1,858 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Knit v0.16 · **Context Feedback / Context Effectiveness**
|
|
3
|
+
*
|
|
4
|
+
* Context Pack 给了「应该先读什么」,这个模块回答**它之后真的被用了吗**。
|
|
5
|
+
* 只有三个事实来源,全部是确定性的:
|
|
6
|
+
*
|
|
7
|
+
* 1. **Context Snapshot / Epoch** —— Knit 把一份 Context Pack 交出去的那一刻
|
|
8
|
+
* (工具调用 / 面板装配),记下当时的三层排序与它的 `epochId`。
|
|
9
|
+
* 2. **Context Delta** —— 两次 Snapshot 之间,哪些文档进 / 出 / 换了层,以及 `fromEpoch → toEpoch`。
|
|
10
|
+
* 3. **Read evidence** —— 会话事件流里**真实发生过的 `read` 工具调用**
|
|
11
|
+
* (`tool/call` 配对 `tool/result`,且 `message.isError !== true`)。
|
|
12
|
+
* 搜索命中(`grep` / `glob`)**不算读过**。
|
|
13
|
+
*
|
|
14
|
+
* Usage 就是这三者的**连接**,而且连接发生在**读的那一刻**:
|
|
15
|
+
* 每条 read 落库时就按 `snapshotAt(read.seq)` 结算出 `tierAtRead` / `rankAtRead` /
|
|
16
|
+
* `insideAtRead` / `epochId` 并**冻结**。之后上下文再怎么变,历史归因都不许重算 ——
|
|
17
|
+
* 「当前视图」与「历史视图」是两件事。
|
|
18
|
+
*
|
|
19
|
+
* ⚠️ 本模块**不碰 Retrieval**(BM25 / IDF / 关键词抽取 / 长度归一化 / freshness 一行不改),
|
|
20
|
+
* 也**不落盘、不联网、不调模型、不写 memory、不自动干预上下文**。
|
|
21
|
+
* 读证据的唯一来源是宿主派发的 `session/event`(v0.16 起):**不再**调用
|
|
22
|
+
* `session.snapshotEvents()` —— 那个 API 已被 DSH 标记 deprecated
|
|
23
|
+
* (「new production calls are prohibited」),而且它在 fork 会话上会把父会话继承来的
|
|
24
|
+
* 前缀事件也算进来。代价是:订阅之前发生的事件不回溯,只记订阅之后真实发生的读。
|
|
25
|
+
*
|
|
26
|
+
* 这里**没有**:trajectory、span、runtime trace、reasoning、成功率、置信度、归一化评分、
|
|
27
|
+
* quality score、memory 写入。Usage 不是分数,是计数与事实。
|
|
28
|
+
*
|
|
29
|
+
* @module feedback
|
|
30
|
+
*/
|
|
31
|
+
import { isAbsolute, relative, resolve, sep } from 'node:path'
|
|
32
|
+
|
|
33
|
+
/** 同时保留多少个会话的状态(LRU 淘汰)。 */
|
|
34
|
+
export const MAX_SESSIONS = 24
|
|
35
|
+
/** 每个会话最多记多少篇**读过**的文档。 */
|
|
36
|
+
export const MAX_READS_PER_SESSION = 200
|
|
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
|
|
46
|
+
/** 最多同时挂起多少个「已调用、还没结果」的 read。 */
|
|
47
|
+
export const MAX_PENDING_CALLS = 64
|
|
48
|
+
|
|
49
|
+
/** 三层,顺序即「先看 → 辅助 → 背景」。 */
|
|
50
|
+
const TIERS = ['primary', 'supporting', 'related']
|
|
51
|
+
/** 唯一算「读过」的工具名。`glob` / `grep` / `bash` 一律不算。 */
|
|
52
|
+
const READ_TOOL = 'read'
|
|
53
|
+
|
|
54
|
+
/* ── 1. 路径 ───────────────────────────────────────────────────────── */
|
|
55
|
+
|
|
56
|
+
/**
|
|
57
|
+
* 把工具参数里的路径归一成**工作区相对路径**(正斜杠)。
|
|
58
|
+
*
|
|
59
|
+
* 归一化失败一律返回空串 —— 调用方据此丢弃这条证据,而不是猜一个路径出来。
|
|
60
|
+
* 丢弃的四种情形:非字符串 / 空串 / URL(`http://`、`file://`)/ 落在工作区根之外。
|
|
61
|
+
*
|
|
62
|
+
* 相对路径**不做** `resolve` —— 工作区里 `a/../b.md` 这种写法工具不会给,
|
|
63
|
+
* 而把相对路径按 DSH 进程的 cwd 去 resolve 只会得到错的东西。
|
|
64
|
+
*
|
|
65
|
+
* @param {string} root - 工作区根(绝对路径)
|
|
66
|
+
* @param {unknown} candidate - 工具给的路径
|
|
67
|
+
* @returns {string} 归一化后的相对路径,或空串
|
|
68
|
+
*/
|
|
69
|
+
export function normalizeRel(root, candidate) {
|
|
70
|
+
if (typeof candidate !== 'string') return ''
|
|
71
|
+
const raw = candidate.trim()
|
|
72
|
+
if (!raw || raw.length > 1024) return ''
|
|
73
|
+
if (raw.includes('\0')) return ''
|
|
74
|
+
// 官方 `read` 只接受本地路径;URL 不该出现在这里,出现就丢掉
|
|
75
|
+
if (/^[a-z][a-z0-9+.-]*:\/\//i.test(raw)) return ''
|
|
76
|
+
|
|
77
|
+
let rel = raw
|
|
78
|
+
if (isAbsolute(rel)) {
|
|
79
|
+
// 绝对路径必须落在工作区根之内。root 未知时不猜 —— 直接丢弃。
|
|
80
|
+
if (typeof root !== 'string' || !root) return ''
|
|
81
|
+
const base = resolve(root)
|
|
82
|
+
const abs = resolve(rel)
|
|
83
|
+
if (abs !== base && !abs.startsWith(base + sep)) return ''
|
|
84
|
+
rel = relative(base, abs)
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
rel = rel.split(sep).join('/')
|
|
88
|
+
rel = rel.replace(/^\.\/+/, '').replace(/\/{2,}/g, '/')
|
|
89
|
+
if (!rel || rel === '.') return ''
|
|
90
|
+
if (rel === '..' || rel.startsWith('../')) return ''
|
|
91
|
+
return rel
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
/* ── 2. Snapshot / Delta ───────────────────────────────────────────── */
|
|
95
|
+
|
|
96
|
+
/**
|
|
97
|
+
* 把一份 Context Pack 压成 Snapshot(**只留 rel / 层 / 层内名次**)。
|
|
98
|
+
*
|
|
99
|
+
* 不留 `summary` / `reason` / `mtimeMs`:Usage 要回答的是「读没读、读的是哪一层」,
|
|
100
|
+
* 不是「为什么排在那儿」。少留一份数据就少一份漂移。
|
|
101
|
+
*
|
|
102
|
+
* @param {object} pack - `buildContext()` 的产物(`{primary, supporting, related, task, topic, totals}`)
|
|
103
|
+
* @param {{seq?: number, at?: number}} [meta] - 交出这份包的**事件 seq** 与墙钟时间
|
|
104
|
+
* @returns {object} Snapshot
|
|
105
|
+
*/
|
|
106
|
+
export function snapshotOf(pack, meta = {}) {
|
|
107
|
+
const items = []
|
|
108
|
+
for (const tier of TIERS) {
|
|
109
|
+
const list = pack && Array.isArray(pack[tier]) ? pack[tier] : []
|
|
110
|
+
list.forEach((item, index) => {
|
|
111
|
+
const rel = item && typeof item.rel === 'string' ? item.rel : ''
|
|
112
|
+
if (!rel) return
|
|
113
|
+
items.push({ rel, tier, rank: index + 1 })
|
|
114
|
+
})
|
|
115
|
+
}
|
|
116
|
+
const task = pack && typeof pack.task === 'string' ? pack.task : ''
|
|
117
|
+
return {
|
|
118
|
+
seq: Number.isInteger(meta.seq) ? meta.seq : -1,
|
|
119
|
+
at: Number.isFinite(meta.at) ? meta.at : 0,
|
|
120
|
+
topic: (pack && typeof pack.topic === 'string') ? pack.topic : '',
|
|
121
|
+
task,
|
|
122
|
+
total: (pack && pack.totals && Number.isInteger(pack.totals.total)) ? pack.totals.total : 0,
|
|
123
|
+
items,
|
|
124
|
+
sig: signatureOf(items, task),
|
|
125
|
+
}
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
/**
|
|
129
|
+
* 给一份 Snapshot 算个身份串 —— 用来判断「这次和上次是不是同一份上下文」。
|
|
130
|
+
* @param {Array<{rel:string,tier:string,rank:number}>} items - 扁平条目
|
|
131
|
+
* @param {string} task - 任务原文
|
|
132
|
+
* @returns {string} 身份串
|
|
133
|
+
*/
|
|
134
|
+
function signatureOf(items, task) {
|
|
135
|
+
return [task, ...items.map((item) => `${item.tier}:${item.rank}:${item.rel}`)].join('\u0000')
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
/**
|
|
139
|
+
* 比较两份 Snapshot:谁进来了、谁出去了、谁换了层。
|
|
140
|
+
*
|
|
141
|
+
* `taskChanged` 单独给一个布尔 —— 任务换了但三层恰好没变(少见但真实)时,
|
|
142
|
+
* 它仍是「上下文变了」,不该被算成 stable。
|
|
143
|
+
*
|
|
144
|
+
* @param {object|null} prev - 上一份 Snapshot
|
|
145
|
+
* @param {object|null} next - 这一份 Snapshot
|
|
146
|
+
* @returns {{appeared: object[], disappeared: object[], moved: object[], taskChanged: boolean, fromEpoch: number|null, toEpoch: number|null, stable: boolean}} 差异
|
|
147
|
+
*/
|
|
148
|
+
export function diffContext(prev, next) {
|
|
149
|
+
const before = indexOf(prev)
|
|
150
|
+
const after = indexOf(next)
|
|
151
|
+
const appeared = []
|
|
152
|
+
const disappeared = []
|
|
153
|
+
const moved = []
|
|
154
|
+
|
|
155
|
+
for (const [rel, to] of after) {
|
|
156
|
+
const from = before.get(rel)
|
|
157
|
+
if (!from) appeared.push({ rel, tier: to.tier, rank: to.rank })
|
|
158
|
+
else if (from.tier !== to.tier || from.rank !== to.rank) moved.push({ rel, from, to })
|
|
159
|
+
}
|
|
160
|
+
for (const [rel, from] of before) {
|
|
161
|
+
if (!after.has(rel)) disappeared.push({ rel, tier: from.tier, rank: from.rank })
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
const taskChanged = ((prev && prev.task) || '') !== ((next && next.task) || '')
|
|
165
|
+
return {
|
|
166
|
+
appeared,
|
|
167
|
+
disappeared,
|
|
168
|
+
moved,
|
|
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,
|
|
173
|
+
stable: appeared.length === 0 && disappeared.length === 0 && moved.length === 0 && !taskChanged,
|
|
174
|
+
}
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
/**
|
|
178
|
+
* 扁平成 `rel → {tier, rank}`。
|
|
179
|
+
* @param {object|null} snapshot - Snapshot
|
|
180
|
+
* @returns {Map<string, {tier:string,rank:number}>} 索引
|
|
181
|
+
*/
|
|
182
|
+
function indexOf(snapshot) {
|
|
183
|
+
const map = new Map()
|
|
184
|
+
const items = snapshot && Array.isArray(snapshot.items) ? snapshot.items : []
|
|
185
|
+
for (const item of items) map.set(item.rel, { tier: item.tier, rank: item.rank })
|
|
186
|
+
return map
|
|
187
|
+
}
|
|
188
|
+
|
|
189
|
+
/* ── 3. Read evidence adapter ──────────────────────────────────────── */
|
|
190
|
+
|
|
191
|
+
/**
|
|
192
|
+
* 从会话事件里抽出**真实发生过的 read**。
|
|
193
|
+
*
|
|
194
|
+
* 事件流的真实形状(2026-09-30 实测 `session.v4.jsonl.zstd`):
|
|
195
|
+
* - `tool/call` `data = {turn, step, callId, name, arguments}`,**`arguments` 是 JSON 字符串**
|
|
196
|
+
* - `tool/result` `data = {turn, step, message}`,`message = {toolCallId, source:{callId}, isError, …}`
|
|
197
|
+
*
|
|
198
|
+
* 配对规则:同 `callId`,且结果的 `message.isError !== true`。失败 / 被拒的读**不记账**。
|
|
199
|
+
* 还没等到结果的调用挂在 `pending` 里跨轮次存活(面板 5 秒轮询时,call 与 result 常常分属两次读数)。
|
|
200
|
+
*
|
|
201
|
+
* 幂等靠 `fromSeq` 游标:只处理 `seq > fromSeq` 的事件,所以同一批事件喂两遍不会重复计数。
|
|
202
|
+
*
|
|
203
|
+
* @param {object[]} events - 会话事件(v0.16 起由 `session/event` 订阅逐条喂进来)
|
|
204
|
+
* @param {{root?: string, fromSeq?: number, pending?: Map<string, object>}} [options] - 选项
|
|
205
|
+
* @returns {{reads: object[], cursor: number, pending: Map<string, object>}} 证据、新游标、挂起表
|
|
206
|
+
*/
|
|
207
|
+
export function normalizeReadEvidence(events, options = {}) {
|
|
208
|
+
const root = options.root
|
|
209
|
+
const fromSeq = Number.isInteger(options.fromSeq) ? options.fromSeq : -1
|
|
210
|
+
const pending = options.pending instanceof Map ? options.pending : new Map()
|
|
211
|
+
const reads = []
|
|
212
|
+
let cursor = fromSeq
|
|
213
|
+
if (!Array.isArray(events)) return { reads, cursor, pending }
|
|
214
|
+
|
|
215
|
+
for (const event of events) {
|
|
216
|
+
if (!event || typeof event.type !== 'string') continue
|
|
217
|
+
const seq = Number.isInteger(event.seq) ? event.seq : -1
|
|
218
|
+
if (seq < 0 || seq <= fromSeq) continue
|
|
219
|
+
if (seq > cursor) cursor = seq
|
|
220
|
+
|
|
221
|
+
if (event.type === 'tool/call') {
|
|
222
|
+
const data = event.data || {}
|
|
223
|
+
if (data.name !== READ_TOOL) continue
|
|
224
|
+
const args = parseArguments(data.arguments)
|
|
225
|
+
const rel = normalizeRel(root, args.file_path || args.path || args.filePath)
|
|
226
|
+
const callId = typeof data.callId === 'string' ? data.callId : ''
|
|
227
|
+
if (!rel || !callId) continue
|
|
228
|
+
pending.set(callId, {
|
|
229
|
+
rel,
|
|
230
|
+
seq,
|
|
231
|
+
time: Number.isFinite(event.time) ? event.time : 0,
|
|
232
|
+
})
|
|
233
|
+
// 挂起表也要有上限:只调用不返回的会话不许把它撑大
|
|
234
|
+
while (pending.size > MAX_PENDING_CALLS) {
|
|
235
|
+
const oldest = pending.keys().next().value
|
|
236
|
+
if (oldest === callId) break
|
|
237
|
+
pending.delete(oldest)
|
|
238
|
+
}
|
|
239
|
+
} else if (event.type === 'tool/result') {
|
|
240
|
+
const message = (event.data && event.data.message) || {}
|
|
241
|
+
const callId = String(
|
|
242
|
+
message.toolCallId || (message.source && message.source.callId) || '',
|
|
243
|
+
)
|
|
244
|
+
if (!callId) continue
|
|
245
|
+
const call = pending.get(callId)
|
|
246
|
+
if (!call) continue
|
|
247
|
+
pending.delete(callId)
|
|
248
|
+
// 失败的读不是「读过了」—— 规格 §9
|
|
249
|
+
if (message.isError === true) continue
|
|
250
|
+
reads.push({
|
|
251
|
+
rel: call.rel,
|
|
252
|
+
callId,
|
|
253
|
+
callSeq: call.seq,
|
|
254
|
+
seq,
|
|
255
|
+
time: Number.isFinite(event.time) ? event.time : call.time,
|
|
256
|
+
})
|
|
257
|
+
}
|
|
258
|
+
}
|
|
259
|
+
|
|
260
|
+
return { reads, cursor, pending }
|
|
261
|
+
}
|
|
262
|
+
|
|
263
|
+
/**
|
|
264
|
+
* 解析 `tool/call` 的 `arguments`(实测是 JSON **字符串**)。
|
|
265
|
+
* 解析不出来就当没有参数 —— 这条证据会被丢弃,而不是猜一个路径。
|
|
266
|
+
* @param {unknown} raw - 原始参数
|
|
267
|
+
* @returns {object} 参数对象
|
|
268
|
+
*/
|
|
269
|
+
function parseArguments(raw) {
|
|
270
|
+
if (raw && typeof raw === 'object') return raw
|
|
271
|
+
if (typeof raw !== 'string' || !raw) return {}
|
|
272
|
+
try {
|
|
273
|
+
const parsed = JSON.parse(raw)
|
|
274
|
+
return parsed && typeof parsed === 'object' ? parsed : {}
|
|
275
|
+
} catch {
|
|
276
|
+
return {}
|
|
277
|
+
}
|
|
278
|
+
}
|
|
279
|
+
/* ── 4. 按会话分片的内存状态 ───────────────────────────────────────── */
|
|
280
|
+
|
|
281
|
+
/**
|
|
282
|
+
* 建一个空的 feedback store(内存态,进程活着才在)。
|
|
283
|
+
* @returns {{sessions: Map<string, object>, order: string[], audited: Set<string>}} store
|
|
284
|
+
*/
|
|
285
|
+
export function createStore() {
|
|
286
|
+
return { sessions: new Map(), order: [], audited: new Set() }
|
|
287
|
+
}
|
|
288
|
+
|
|
289
|
+
/**
|
|
290
|
+
* 标记这个会话「被审计了」—— 之后它的读事件与面板请求才会被记账。
|
|
291
|
+
*
|
|
292
|
+
* 默认**不记账**:没人看「使用情况」、Agent 也没要 audit 的会话,
|
|
293
|
+
* 不该在内存里攒快照。这一点是刻意的(内存有上限、行为可预期)。
|
|
294
|
+
*
|
|
295
|
+
* @param {object} store - store
|
|
296
|
+
* @param {string} sessionId - 会话 id
|
|
297
|
+
* @returns {boolean} 是否成功
|
|
298
|
+
*/
|
|
299
|
+
export function activateAudit(store, sessionId) {
|
|
300
|
+
try {
|
|
301
|
+
if (!store || !sessionId) return false
|
|
302
|
+
stateOf(store, sessionId)
|
|
303
|
+
store.audited.add(sessionId)
|
|
304
|
+
while (store.audited.size > MAX_SESSIONS) {
|
|
305
|
+
const oldest = store.audited.values().next().value
|
|
306
|
+
if (oldest === sessionId) break
|
|
307
|
+
store.audited.delete(oldest)
|
|
308
|
+
}
|
|
309
|
+
return true
|
|
310
|
+
} catch {
|
|
311
|
+
return false
|
|
312
|
+
}
|
|
313
|
+
}
|
|
314
|
+
|
|
315
|
+
/**
|
|
316
|
+
* 这个会话是否在记账。**订阅回调的第一行就用它早退** ——
|
|
317
|
+
* 没记账的会话一次 Map 查找就返回,不做任何别的工作。
|
|
318
|
+
* @param {object} store - store
|
|
319
|
+
* @param {string} sessionId - 会话 id
|
|
320
|
+
* @returns {boolean} 是否记账
|
|
321
|
+
*/
|
|
322
|
+
export function isAudited(store, sessionId) {
|
|
323
|
+
return !!(store && sessionId && store.audited.has(sessionId))
|
|
324
|
+
}
|
|
325
|
+
|
|
326
|
+
/**
|
|
327
|
+
* 取(或建)一个会话的状态,并按 LRU 触摸 —— 会话数量超上限时淘汰最久没碰的。
|
|
328
|
+
* @param {object} store - store
|
|
329
|
+
* @param {string} sessionId - 会话 id
|
|
330
|
+
* @returns {object} 会话状态
|
|
331
|
+
*/
|
|
332
|
+
function stateOf(store, sessionId) {
|
|
333
|
+
let state = store.sessions.get(sessionId)
|
|
334
|
+
if (!state) {
|
|
335
|
+
state = {
|
|
336
|
+
seq: -1, // 已消费到的事件 seq(幂等游标;也是「当前水位」)
|
|
337
|
+
pending: new Map(), // 已调用、还没结果的 read
|
|
338
|
+
snapshots: [], // 最近 MAX_SNAPSHOTS_PER_SESSION 份 Context Pack(每份 = 一个 Epoch)
|
|
339
|
+
epochs: [], // 与 snapshots 一一对应的 Epoch 级计数
|
|
340
|
+
deltas: [], // 最近若干条变化
|
|
341
|
+
reads: new Map(), // rel → 冻结的读归因
|
|
342
|
+
readOrder: [], // rel 的插入顺序(淘汰用)
|
|
343
|
+
// ⚠️ 这里**不再**有 `changes` 计数:上下文换过几次 = 最后一个 Epoch 的编号 - 1,
|
|
344
|
+
// 而 Epoch 编号是单调的(被淘汰的 Epoch 也计过数),所以不需要额外记一个累计值。
|
|
345
|
+
churn: { appeared: 0, disappeared: 0, moved: 0, taskChanged: 0 },
|
|
346
|
+
}
|
|
347
|
+
store.sessions.set(sessionId, state)
|
|
348
|
+
}
|
|
349
|
+
const at = store.order.indexOf(sessionId)
|
|
350
|
+
if (at >= 0) store.order.splice(at, 1)
|
|
351
|
+
store.order.push(sessionId)
|
|
352
|
+
while (store.order.length > MAX_SESSIONS) {
|
|
353
|
+
const gone = store.order.shift()
|
|
354
|
+
store.sessions.delete(gone)
|
|
355
|
+
}
|
|
356
|
+
return state
|
|
357
|
+
}
|
|
358
|
+
|
|
359
|
+
/* ── 5. 入口:喂事件 / 记快照 / 取使用情况 ─────────────────────────── */
|
|
360
|
+
|
|
361
|
+
/**
|
|
362
|
+
* 把**一批**会话事件喂进去,抽出 read 并按「读发生的那一刻」结算归因。
|
|
363
|
+
*
|
|
364
|
+
* v0.16 起调用方通常一次只喂一条(`session/event` 订阅)。仍然是幂等的:
|
|
365
|
+
* 只处理 `seq > state.seq` 的事件,重复喂同一批不会重复计数。
|
|
366
|
+
*
|
|
367
|
+
* **任何异常都咽掉并返回 `{ok:false}`** —— 记账失败绝不能让面板或工具失败。
|
|
368
|
+
*
|
|
369
|
+
* @param {object} store - store
|
|
370
|
+
* @param {string} sessionId - 会话 id
|
|
371
|
+
* @param {object[]} events - 会话事件
|
|
372
|
+
* @param {{root?: string}} [options] - 选项
|
|
373
|
+
* @returns {{ok: boolean, reads: number, cursor: number}} 结果
|
|
374
|
+
*/
|
|
375
|
+
export function ingestEvents(store, sessionId, events, options = {}) {
|
|
376
|
+
try {
|
|
377
|
+
if (!store || !sessionId) return { ok: false, reads: 0, cursor: -1 }
|
|
378
|
+
const state = stateOf(store, sessionId)
|
|
379
|
+
const { reads, cursor, pending } = normalizeReadEvidence(events, {
|
|
380
|
+
root: options.root,
|
|
381
|
+
fromSeq: state.seq,
|
|
382
|
+
pending: state.pending,
|
|
383
|
+
})
|
|
384
|
+
state.pending = pending
|
|
385
|
+
if (cursor > state.seq) state.seq = cursor
|
|
386
|
+
for (const read of reads) recordRead(state, read)
|
|
387
|
+
return { ok: true, reads: reads.length, cursor: state.seq }
|
|
388
|
+
} catch {
|
|
389
|
+
return { ok: false, reads: 0, cursor: -1 }
|
|
390
|
+
}
|
|
391
|
+
}
|
|
392
|
+
|
|
393
|
+
/**
|
|
394
|
+
* 记下「Knit 刚刚交出了这份 Context Pack」。
|
|
395
|
+
*
|
|
396
|
+
* 与上一份**同签名**时不记新快照(只把时间 / seq 往前推)—— 否则 5 秒轮询会把
|
|
397
|
+
* 同一份上下文记成几十份,Delta churn 立刻变成噪音。
|
|
398
|
+
*
|
|
399
|
+
* `meta.seq` 省略时用会话当前的**事件水位**(`state.seq`)—— 也就是「交包这一刻,
|
|
400
|
+
* 已经发生到第几个事件」。这正是历史归因要的边界:seq ≤ 它的读算在这份包里。
|
|
401
|
+
*
|
|
402
|
+
* @param {object} store - store
|
|
403
|
+
* @param {string} sessionId - 会话 id
|
|
404
|
+
* @param {object} pack - Context Pack
|
|
405
|
+
* @param {{seq?: number, at?: number}} [meta] - 事件 seq 与时间
|
|
406
|
+
* @returns {{snapshot: object, delta: object|null}|null} 新快照与它带来的变化(无变化时 null)
|
|
407
|
+
*/
|
|
408
|
+
export function noteSnapshot(store, sessionId, pack, meta = {}) {
|
|
409
|
+
try {
|
|
410
|
+
if (!store || !sessionId || !pack) return null
|
|
411
|
+
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
|
+
})
|
|
416
|
+
const prev = state.snapshots[state.snapshots.length - 1] || null
|
|
417
|
+
|
|
418
|
+
if (prev && prev.sig === next.sig) {
|
|
419
|
+
if (next.at > prev.at) prev.at = next.at
|
|
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
|
|
423
|
+
return null
|
|
424
|
+
}
|
|
425
|
+
|
|
426
|
+
// Epoch 编号从这里发出:新建一份上下文 = 一个新 Epoch。同签名不算新 Epoch。
|
|
427
|
+
next.epochId = prev && Number.isInteger(prev.epochId) ? prev.epochId + 1 : 1
|
|
428
|
+
state.snapshots.push(next)
|
|
429
|
+
state.epochs.push(createEpoch(next))
|
|
430
|
+
while (state.snapshots.length > MAX_SNAPSHOTS_PER_SESSION) {
|
|
431
|
+
state.snapshots.shift()
|
|
432
|
+
state.epochs.shift()
|
|
433
|
+
}
|
|
434
|
+
|
|
435
|
+
let delta = null
|
|
436
|
+
if (prev) {
|
|
437
|
+
delta = { at: next.at, seq: next.seq, ...diffContext(prev, next) }
|
|
438
|
+
state.deltas.push(delta)
|
|
439
|
+
while (state.deltas.length > MAX_DELTAS_PER_SESSION) state.deltas.shift()
|
|
440
|
+
state.churn.appeared += delta.appeared.length
|
|
441
|
+
state.churn.disappeared += delta.disappeared.length
|
|
442
|
+
state.churn.moved += delta.moved.length
|
|
443
|
+
if (delta.taskChanged) state.churn.taskChanged += 1
|
|
444
|
+
}
|
|
445
|
+
return { snapshot: next, delta }
|
|
446
|
+
} catch {
|
|
447
|
+
return null
|
|
448
|
+
}
|
|
449
|
+
}
|
|
450
|
+
|
|
451
|
+
/**
|
|
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(这不是错,是信息)。
|
|
500
|
+
* @param {object} state - 会话状态
|
|
501
|
+
* @param {object} read - 归一化后的 read 证据
|
|
502
|
+
*/
|
|
503
|
+
function recordRead(state, read) {
|
|
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
|
+
}
|
|
516
|
+
|
|
517
|
+
let entry = state.reads.get(read.rel)
|
|
518
|
+
if (!entry) {
|
|
519
|
+
entry = {
|
|
520
|
+
rel: read.rel,
|
|
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,
|
|
531
|
+
}
|
|
532
|
+
state.reads.set(read.rel, entry)
|
|
533
|
+
state.readOrder.push(read.rel)
|
|
534
|
+
while (state.readOrder.length > MAX_READS_PER_SESSION) {
|
|
535
|
+
state.reads.delete(state.readOrder.shift())
|
|
536
|
+
}
|
|
537
|
+
}
|
|
538
|
+
|
|
539
|
+
entry.count += 1
|
|
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
|
+
}
|
|
569
|
+
}
|
|
570
|
+
}
|
|
571
|
+
|
|
572
|
+
/**
|
|
573
|
+
* 找出**这次读发生的那一刻**在生效的那份快照(seq ≤ 读的 seq 里最新的那份)。
|
|
574
|
+
* 找不到就返回 null —— 那是「Knit 还没给过上下文就自己读了」,如实记成 outside。
|
|
575
|
+
*
|
|
576
|
+
* 这是 runtime 与离线回放到共用的**同一个纯函数**:两边「规则一致」靠它,
|
|
577
|
+
* 而不是靠两边的数字恰好相等(交付时刻不可观测,数字本来就不可能相等)。
|
|
578
|
+
*
|
|
579
|
+
* @param {object[]} snapshots - 快照栈
|
|
580
|
+
* @param {number} seq - 读的 seq
|
|
581
|
+
* @returns {object|null} 快照
|
|
582
|
+
*/
|
|
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]
|
|
587
|
+
}
|
|
588
|
+
return null
|
|
589
|
+
}
|
|
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
|
+
|
|
651
|
+
/**
|
|
652
|
+
* 取一个会话当前的使用情况。没有记录时返回 `null`(不编造空报告)。
|
|
653
|
+
* @param {object} store - store
|
|
654
|
+
* @param {string} sessionId - 会话 id
|
|
655
|
+
* @returns {object|null} 使用情况
|
|
656
|
+
*/
|
|
657
|
+
export function usageFor(store, sessionId) {
|
|
658
|
+
try {
|
|
659
|
+
const state = store && store.sessions.get(sessionId)
|
|
660
|
+
if (!state) return null
|
|
661
|
+
return usageFrom(state)
|
|
662
|
+
} catch {
|
|
663
|
+
return null
|
|
664
|
+
}
|
|
665
|
+
}
|
|
666
|
+
|
|
667
|
+
/**
|
|
668
|
+
* 纯函数版:从一个会话状态算出使用情况(测试直接用这个)。
|
|
669
|
+
*
|
|
670
|
+
* 报告分两层,界线是硬的:
|
|
671
|
+
*
|
|
672
|
+
* - **历史层**(`reads[].firstRead/lastRead`、`byTier[].read`、`primaryFollowThrough`、
|
|
673
|
+
* `outside`)—— 全部来自读时冻结的归因,**永不按当前上下文重算**。
|
|
674
|
+
* - **当前层**(`items`、`byTier[].total`、`primaryRel`、`delta`)—— 反映最近一份上下文。
|
|
675
|
+
*
|
|
676
|
+
* 报告里只有**计数与事实**:读了几次、落在哪一层、有几篇在快照之外、
|
|
677
|
+
* 上下文变过几次、有几篇离开后仍被读、有几篇重新进入。**没有分数、没有百分比评分。**
|
|
678
|
+
*
|
|
679
|
+
* @param {object} state - 会话状态
|
|
680
|
+
* @returns {object} 使用情况
|
|
681
|
+
*/
|
|
682
|
+
export function usageFrom(state) {
|
|
683
|
+
const snapshots = (state && state.snapshots) || []
|
|
684
|
+
const snapshot = snapshots[snapshots.length - 1] || null
|
|
685
|
+
const epochId = snapshot && Number.isInteger(snapshot.epochId) ? snapshot.epochId : null
|
|
686
|
+
const byTier = {
|
|
687
|
+
primary: { total: 0, read: 0 },
|
|
688
|
+
supporting: { total: 0, read: 0 },
|
|
689
|
+
related: { total: 0, read: 0 },
|
|
690
|
+
}
|
|
691
|
+
if (snapshot) {
|
|
692
|
+
for (const item of snapshot.items) {
|
|
693
|
+
if (byTier[item.tier]) byTier[item.tier].total += 1
|
|
694
|
+
}
|
|
695
|
+
}
|
|
696
|
+
|
|
697
|
+
const reads = []
|
|
698
|
+
for (const entry of state.reads.values()) {
|
|
699
|
+
reads.push({
|
|
700
|
+
rel: entry.rel,
|
|
701
|
+
count: entry.count,
|
|
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,
|
|
719
|
+
})
|
|
720
|
+
}
|
|
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
|
+
}
|
|
728
|
+
|
|
729
|
+
const outside = reads.filter((row) => row.outsideReads > 0)
|
|
730
|
+
const first = reads[0] || null
|
|
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
|
+
}))
|
|
748
|
+
|
|
749
|
+
return {
|
|
750
|
+
at: snapshot ? snapshot.at : 0,
|
|
751
|
+
seq: snapshot ? snapshot.seq : -1,
|
|
752
|
+
epochId,
|
|
753
|
+
task: snapshot ? snapshot.task : '',
|
|
754
|
+
topic: snapshot ? snapshot.topic : '',
|
|
755
|
+
items: snapshot ? snapshot.items.map((item) => ({ ...item })) : [],
|
|
756
|
+
reads,
|
|
757
|
+
// §16 Epoch 级使用情况:内部 / 离线回放 / 将来评估用,v0.16 **不上**任何 UI 与工具输出
|
|
758
|
+
epochs,
|
|
759
|
+
delta: state.deltas[state.deltas.length - 1] || null,
|
|
760
|
+
stats: {
|
|
761
|
+
reads: reads.reduce((sum, row) => sum + row.count, 0),
|
|
762
|
+
distinct: reads.length,
|
|
763
|
+
outside: outside.length,
|
|
764
|
+
outsideReads: outside.map((row) => row.rel),
|
|
765
|
+
// 第一条成功读落在哪一层:primary / supporting / related / outside / null
|
|
766
|
+
firstReadTier: first ? (first.firstRead.inside ? first.firstRead.tier : 'outside') : null,
|
|
767
|
+
firstReadRel: first ? first.rel : '',
|
|
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),
|
|
773
|
+
byTier,
|
|
774
|
+
supportingCoverage: byTier.supporting.total === 0 ? null : byTier.supporting.read / byTier.supporting.total,
|
|
775
|
+
// 事实计数(不是「Agent 不认可新上下文」这种解释)
|
|
776
|
+
continuedReadsAfterExit: continued.length,
|
|
777
|
+
reEntries: reentries.length,
|
|
778
|
+
churn: {
|
|
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,
|
|
786
|
+
// 手上还留着几条 Delta 明细
|
|
787
|
+
retained: state.deltas.length,
|
|
788
|
+
appeared: state.churn.appeared,
|
|
789
|
+
disappeared: state.churn.disappeared,
|
|
790
|
+
moved: state.churn.moved,
|
|
791
|
+
taskChanged: state.churn.taskChanged,
|
|
792
|
+
},
|
|
793
|
+
},
|
|
794
|
+
}
|
|
795
|
+
}
|
|
796
|
+
|
|
797
|
+
/**
|
|
798
|
+
* 给 Agent 看的**极短**摘要(结构化、无分数)。
|
|
799
|
+
* @param {object|null} usage - `usageFrom()` 的结果
|
|
800
|
+
* @returns {object|null} 摘要
|
|
801
|
+
*/
|
|
802
|
+
export function auditPayload(usage) {
|
|
803
|
+
if (!usage || !usage.stats) return null
|
|
804
|
+
const s = usage.stats
|
|
805
|
+
return {
|
|
806
|
+
primaryRead: !!s.primaryFollowThrough,
|
|
807
|
+
primaryRel: String(s.primaryRel || ''),
|
|
808
|
+
supportingRead: s.byTier.supporting.read,
|
|
809
|
+
supportingTotal: s.byTier.supporting.total,
|
|
810
|
+
readsOutside: s.outside,
|
|
811
|
+
contextChanges: s.churn.changes,
|
|
812
|
+
epochs: s.churn.epochs,
|
|
813
|
+
continuedReadsAfterExit: s.continuedReadsAfterExit,
|
|
814
|
+
reEntries: s.reEntries,
|
|
815
|
+
}
|
|
816
|
+
}
|
|
817
|
+
|
|
818
|
+
/**
|
|
819
|
+
* 给 Agent 看的那一句话(`knit_docs` 渲染在末尾)。没有可说的就返回空串。
|
|
820
|
+
* @param {object|null} usage - `usageFrom()` 的结果
|
|
821
|
+
* @returns {string} 一行文本
|
|
822
|
+
*/
|
|
823
|
+
export function getAuditSummary(usage) {
|
|
824
|
+
const payload = auditPayload(usage)
|
|
825
|
+
if (!payload) return ''
|
|
826
|
+
const parts = []
|
|
827
|
+
if (payload.primaryRel) {
|
|
828
|
+
parts.push(payload.primaryRead
|
|
829
|
+
? `primary read (${payload.primaryRel})`
|
|
830
|
+
: `primary not read yet (${payload.primaryRel})`)
|
|
831
|
+
}
|
|
832
|
+
if (payload.supportingTotal > 0) {
|
|
833
|
+
parts.push(`supporting ${payload.supportingRead}/${payload.supportingTotal}`)
|
|
834
|
+
}
|
|
835
|
+
if (payload.readsOutside > 0) parts.push(`${payload.readsOutside} read outside the pack`)
|
|
836
|
+
if (payload.contextChanges > 0) parts.push(`context changed ${payload.contextChanges}×`)
|
|
837
|
+
if (parts.length === 0) return ''
|
|
838
|
+
return `Usage since the last pack: ${parts.join(' · ')}.`
|
|
839
|
+
}
|
|
840
|
+
|
|
841
|
+
/**
|
|
842
|
+
* 复位一个会话(或整个 store)。给测试与「重新开始记账」用。
|
|
843
|
+
* @param {object} store - store
|
|
844
|
+
* @param {string} [sessionId] - 省略则清空全部
|
|
845
|
+
*/
|
|
846
|
+
export function resetStore(store, sessionId) {
|
|
847
|
+
if (!store) return
|
|
848
|
+
if (sessionId) {
|
|
849
|
+
store.sessions.delete(sessionId)
|
|
850
|
+
store.audited.delete(sessionId)
|
|
851
|
+
const at = store.order.indexOf(sessionId)
|
|
852
|
+
if (at >= 0) store.order.splice(at, 1)
|
|
853
|
+
return
|
|
854
|
+
}
|
|
855
|
+
store.sessions.clear()
|
|
856
|
+
store.order.length = 0
|
|
857
|
+
store.audited.clear()
|
|
858
|
+
}
|