dsh-knit 0.22.0 → 0.23.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,379 @@
1
+ /**
2
+ * Knit v0.23 · **固定检索语料**(版本化、确定性、不打网络)。
3
+ *
4
+ * 用途只有一个:让「语义候选到底有没有把词法漏掉的东西补回来」这句话**可以被量**。
5
+ * 所以这里放三样东西 —— **文档**(真的写成临时工作区去跑 `scan()`)、**任务查询**、
6
+ * 以及每条查询**人工标注的「该命中谁」**(`expected`)。
7
+ *
8
+ * ⚠️ 三条诚实纪律(写这个文件时先读一遍):
9
+ * 1. `expected` 是**人写的答案**,不是「跑出来什么就算什么」。改语料必须重新想一遍标注。
10
+ * 2. 语料里刻意放了**词法必漏**的样本(同义 / 命名不一致 / 中英错位),也刻意放了
11
+ * **hard negative**(话题相近、意图不同)。
12
+ * 3. `fakeEmbed()` 是**确定性替身**,不是模型 —— 它是一个「加权同义词表」向量:
13
+ * 能证明**管道**(候选算得出来、进得了包、有界、可复现),**不能**证明**价值**
14
+ * (真实 embedding 的召回质量)。任何把它跑出来的数字写成「语义检索提升召回」的说法
15
+ * 都是错的 —— 见方案 §9.1 的诚实标注。
16
+ *
17
+ * 向量设计(为什么长这样):同义词组一维,**泛化词权重低**(如「缓存」很多文档都提),
18
+ * 词组权重高(如「失效 / TTL / stale」)。这是为了在语料里同时造出两种真实情况:
19
+ * · 「TTL 与 stale」这篇与查询「缓存失效策略」**共享具体概念** ⇒ 余弦高 ⇒ 会被语义补回来(该补);
20
+ * · 「缓存大小与内存占用」这篇与查询**只共享泛化词** ⇒ 余弦低 ⇒ 不该被补(hard negative)。
21
+ * 这个设计是**为这份语料造的**,不要拿它去推断真模型的行为。
22
+ */
23
+
24
+ export const CORPUS_VERSION = 1
25
+
26
+ /* ── 文档(会真的写进临时工作区;`title` 会成为 H1,也是 BM25 的标题槽)── */
27
+
28
+ export const DOCS = [
29
+ // ① 缓存族(同义表达:查询说「缓存失效」,正文只说 TTL / stale / 逐出)
30
+ {
31
+ rel: 'docs/cache-design.md',
32
+ title: '缓存设计总览',
33
+ body: '整体设计:读写路径、失效策略与逐出顺序。这里会出现「失效」二字,所以词法能命中。\n',
34
+ },
35
+ {
36
+ rel: 'docs/cache-ttl.md',
37
+ title: 'TTL 与 stale 数据',
38
+ body: '过期数据怎么处理:TTL、stale-while-revalidate、逐出与作废顺序。\n',
39
+ },
40
+ {
41
+ rel: 'docs/cache-size.md',
42
+ title: '大小与内存占用',
43
+ body: '容量上限、淘汰阈值与内存占用统计。与「过期」无关,是 hard negative。\n',
44
+ },
45
+ // ② 语义 / 向量族(命名不一致:代码文件名说 semantic,正文说 cosine)
46
+ {
47
+ rel: 'src/host/semantic.js',
48
+ title: 'semantic.js',
49
+ body: "// 余弦相似度与候选缓存\nconst TOP = 24\nexport function cosine(a, b) { /* dot / norm */ }\n",
50
+ },
51
+ {
52
+ rel: 'docs/semantic-notes.md',
53
+ title: '语义候选笔记',
54
+ body: '记录一次实验:嵌入输入只取标题与摘要;候选有上界;失败要如实回退。\n',
55
+ },
56
+ // ③ 索引族(长 changelog 噪声 + 增量对账)
57
+ {
58
+ rel: 'docs/index-reconcile.md',
59
+ title: '增量对账',
60
+ body: '重启后复用索引;用内容指纹做有界对账,只重读真正变了的记录。\n',
61
+ },
62
+ {
63
+ rel: 'CHANGELOG.md',
64
+ title: '变更日志',
65
+ body: ('索引、增量、对账、重读、指纹、缓存、向量、语义、载荷、预算这些词在这里反复出现,' +
66
+ '但这一篇不是任何查询的答案 —— 它专门用来制造「词频高但无关」的噪声。\n').repeat(12),
67
+ },
68
+ // ④ 关系族(代码 + 文档混合)
69
+ {
70
+ rel: 'src/host/relations.js',
71
+ title: 'relations.js',
72
+ body: "// 引用图:出度 out / 入度 in\nexport function neighboursOf(graph, rel) { return graph.out.get(rel) }\n",
73
+ },
74
+ {
75
+ rel: 'docs/relations.md',
76
+ title: '关系事实',
77
+ body: '每条关系只写可核验的事实:类型、箭头方向、对方路径与行号。\n',
78
+ },
79
+ // ⑤ 控制族(排除 / 固定;hard negative:.gitignore 也讲「排除」)
80
+ {
81
+ rel: 'docs/control-exclude.md',
82
+ title: '排除与固定',
83
+ body: '固定与排除互斥;排除先于检索生效,被排除的文件不得从任何路径回到包里。\n',
84
+ },
85
+ {
86
+ rel: 'docs/gitignore-style.md',
87
+ title: '忽略规则写法',
88
+ body: '讲 .gitignore 的排除写法与通配符优先级 —— 与 Knit 的控制层无关。\n',
89
+ },
90
+ // ⑥ 载荷 / 预算
91
+ {
92
+ rel: 'docs/payload-budget.md',
93
+ title: '载荷预算',
94
+ body: '面板载荷硬上界 16 KB;工具输出不得超过基线的 1.4 倍,加字段必须重测。\n',
95
+ },
96
+ // ⑦ 使用反馈
97
+ {
98
+ rel: 'docs/feedback-attribution.md',
99
+ title: '读归因',
100
+ body: '归因在读那一刻结算并冻结:先记快照再入库,之后换多少份上下文都不会改口。\n',
101
+ },
102
+ // ⑧ 媒体
103
+ {
104
+ rel: 'docs/media-grid.md',
105
+ title: '媒体网格',
106
+ body: '视频取首帧当海报,角标给时长;缩略图格子基准固定 104px,纵向不封顶。\n',
107
+ },
108
+ // ⑨ 插件恢复
109
+ {
110
+ rel: 'docs/plugin-recovery.md',
111
+ title: '插件不见了',
112
+ body: '装不进去先别重装:多半是宿主换了独占的 profile,按手册判机制再修。\n',
113
+ },
114
+ // ⑩ 发布通道
115
+ {
116
+ rel: 'docs/release-oidc.md',
117
+ title: '可信发布',
118
+ body: '先推成功、三处对齐、最后才发;通道用 OIDC,绝不设 npm token。\n',
119
+ },
120
+ // ⑪ 预览高亮
121
+ {
122
+ rel: 'docs/preview-highlight.md',
123
+ title: '语法高亮',
124
+ body: '预览里的代码走官方高亮器,只给命中段那一带上色,超出窗口回落纯文本。\n',
125
+ },
126
+ // ⑫ 一批纯噪声(防止「随便什么都算命中」)
127
+ {
128
+ rel: 'docs/noise-a.md',
129
+ title: '样本变更 A',
130
+ body: '第三篇样本。\n',
131
+ },
132
+ {
133
+ rel: 'docs/noise-b.md',
134
+ title: '样本笔记 B',
135
+ body: '第二篇样本,用来凑数。\n',
136
+ },
137
+ ]
138
+
139
+ /* ── 任务查询 + 人工标注 ─────────────────────────────
140
+ * `expected`:这条查询**正确答案**(人工标注)。
141
+ * `case`:这条查询想考什么(对应方案 §9.1 的七类)。
142
+ */
143
+
144
+ export const QUERIES = [
145
+ {
146
+ id: 'synonym-cache',
147
+ case: '同义表达',
148
+ query: '缓存失效策略',
149
+ expected: ['docs/cache-design.md'],
150
+ rescue: ['docs/cache-ttl.md'], // 词法必漏(正文没有「缓存 / 失效」),语义该救回来
151
+ note: '词法只能找到写了「失效」的那篇;写 TTL / stale 的那篇要靠语义。',
152
+ },
153
+ {
154
+ id: 'naming-vector',
155
+ case: '自然语言 ↔ 代码命名',
156
+ query: '向量召回接口',
157
+ expected: ['src/host/semantic.js', 'docs/semantic-notes.md'],
158
+ rescue: ['src/host/semantic.js', 'docs/semantic-notes.md'],
159
+ note: '代码文件里没有「向量 / 召回」这几个字(只有 cosine / TOP),词法必漏。',
160
+ },
161
+ {
162
+ id: 'exact-match',
163
+ case: '关键词完全匹配(防退化)',
164
+ query: '逐出顺序',
165
+ expected: ['docs/cache-design.md'],
166
+ rescue: [],
167
+ note: '字面命中:词法必须找得到,语义不许把结果弄丢。',
168
+ },
169
+ {
170
+ id: 'long-changelog-noise',
171
+ case: '长 changelog 噪声',
172
+ query: '增量对账 指纹',
173
+ expected: ['docs/index-reconcile.md'],
174
+ rescue: [],
175
+ note: 'CHANGELOG 里这些词出现上百次,词法靠 IDF 应当仍然压住它。',
176
+ },
177
+ {
178
+ id: 'mixed-code-doc',
179
+ case: '代码 + Markdown 混合',
180
+ query: '引用关系',
181
+ expected: ['src/host/relations.js', 'docs/relations.md'],
182
+ rescue: [],
183
+ note: '代码与文档在同一套 BM25 里竞争,两边都该出现(词法就该拿到它们)。',
184
+ },
185
+ {
186
+ id: 'hard-negative-size',
187
+ case: 'hard negative(语义容易犯错)',
188
+ query: '缓存大小',
189
+ expected: ['docs/cache-size.md'],
190
+ rescue: [],
191
+ note: '只共享泛化词「缓存」;讲 TTL / stale 的那篇与「大小」无关,语义**不许**把它补进来。',
192
+ },
193
+ {
194
+ id: 'hard-negative-exclude',
195
+ case: 'hard negative(词法侧)',
196
+ query: '排除 忽略规则',
197
+ expected: ['docs/control-exclude.md'],
198
+ rescue: [],
199
+ note: '两篇都讲「排除」:控制层那篇是答案,.gitignore 那篇是同词不同义的干扰项。',
200
+ },
201
+ {
202
+ id: 'payload-budget',
203
+ case: '预算 / 上界',
204
+ query: '载荷 预算 上限',
205
+ expected: ['docs/payload-budget.md'],
206
+ rescue: [],
207
+ note: '纯词法就能解决,用来确认语义没有帮倒忙。',
208
+ },
209
+ {
210
+ id: 'feedback-freeze',
211
+ case: '同义表达',
212
+ query: '读归因冻结',
213
+ expected: ['docs/feedback-attribution.md'],
214
+ rescue: [],
215
+ note: '正文没写「冻结」二字(写的是「改口」),考一次近义。',
216
+ },
217
+ {
218
+ id: 'media-poster',
219
+ case: '同义表达',
220
+ query: '视频缩略图海报',
221
+ expected: ['docs/media-grid.md'],
222
+ rescue: [],
223
+ note: '「缩略图 / 海报」都在正文里,词法应当命中。',
224
+ },
225
+ {
226
+ id: 'plugin-profile',
227
+ case: '自然语言 ↔ 术语',
228
+ query: '插件装不进去 profile',
229
+ expected: ['docs/plugin-recovery.md'],
230
+ rescue: [],
231
+ note: '「插件」二字在标题里 ⇒ 词法就能命中;这条用来确认语义没把它弄丢。',
232
+ },
233
+ {
234
+ id: 'release-channel',
235
+ case: '中英错位',
236
+ query: '可信发布通道',
237
+ expected: ['docs/release-oidc.md'],
238
+ rescue: [],
239
+ note: '正文有「通道」与「可信发布」拆开两处,词法可命中。',
240
+ },
241
+ {
242
+ id: 'preview-window',
243
+ case: '同义表达',
244
+ query: '高亮窗口回落',
245
+ expected: ['docs/preview-highlight.md'],
246
+ rescue: [],
247
+ note: '「窗口」「回落」都在正文里。',
248
+ },
249
+ ]
250
+
251
+ /* ── 确定性替身嵌入(加权同义词表;**不是模型**)──────── */
252
+
253
+ /** 同义词组。`weight` 越大越「具体」;泛化词的权重刻意压低。 */
254
+ export const CONCEPT_GROUPS = [
255
+ { weight: 1.0, forms: ['失效', '过期', 'stale', 'ttl', '逐出', 'evict', '作废', 'invalidation'] },
256
+ { weight: 0.3, forms: ['缓存', 'cache'] },
257
+ { weight: 1.0, forms: ['向量', 'vector', '嵌入', 'embed', 'embedding'] },
258
+ { weight: 0.6, forms: ['召回', 'recall', '语义', 'semantic', '相似度', 'similarity', '余弦', 'cosine'] },
259
+ { weight: 1.0, forms: ['索引', 'index', '对账', 'reconcile', '指纹', 'fingerprint'] },
260
+ { weight: 0.5, forms: ['增量', 'incremental', '重读', '重算'] },
261
+ { weight: 1.0, forms: ['相关度', '排序', 'rank', 'ranking', 'bm25', 'idf', '词法', 'lexical'] },
262
+ { weight: 1.0, forms: ['排除', 'exclude', '固定', 'pin', '控制层'] },
263
+ { weight: 0.8, forms: ['忽略', 'gitignore', '通配符'] },
264
+ { weight: 1.0, forms: ['大小', '容量', '内存', 'memory', 'size', '占用', '阈值'] },
265
+ { weight: 1.0, forms: ['载荷', 'payload', '字段', 'field', 'schema', '契约'] },
266
+ { weight: 1.0, forms: ['预算', 'budget', '上限', '字节', 'byte', 'kb'] },
267
+ { weight: 1.0, forms: ['关系', 'relation', 'relations', '引用', 'reference', '出度', '入度', '链接', 'link'] },
268
+ { weight: 1.0, forms: ['归因', '快照', 'snapshot', 'epoch', '冻结', '阅读', 'read'] },
269
+ { weight: 1.0, forms: ['缩略图', '海报', 'poster', '媒体', 'media', '视频', 'video', '图片', 'image'] },
270
+ // ⚠️ 刻意**不放** 'host':代码文档的摘要位就是目录(`src/host/`),放了会把每一篇代码
271
+ // 都往「插件」这一维上拉(实测:`src/host/semantic.js` 因此被稀释到 0.265,反而漏掉)。
272
+ { weight: 1.0, forms: ['插件', 'plugin', 'profile', '装不进去', '不见了'] },
273
+ { weight: 1.0, forms: ['发布', 'publish', 'npm', 'oidc', 'token', '版本', 'tag'] },
274
+ { weight: 1.0, forms: ['高亮', 'highlight', '窗口', '回落', '语法'] },
275
+ ]
276
+
277
+ /**
278
+ * 确定性「嵌入」:同义词组命中数 × 组权重,L2 归一化。
279
+ *
280
+ * @param {string} text - 会被 `embedTextOf()` 拼成「标题 + 摘要」
281
+ * @returns {number[]} 固定长度向量(长度 = 词组数)
282
+ */
283
+ export function fakeEmbed(text) {
284
+ const lower = String(text || '').toLowerCase()
285
+ const vec = CONCEPT_GROUPS.map((group) => {
286
+ let hits = 0
287
+ for (const form of group.forms) {
288
+ if (matchesForm(lower, form)) hits += 1
289
+ }
290
+ return hits * group.weight
291
+ })
292
+ const norm = Math.sqrt(vec.reduce((sum, v) => sum + v * v, 0))
293
+ return norm > 0 ? vec.map((v) => v / norm) : vec
294
+ }
295
+
296
+ /**
297
+ * 一个词形有没有出现在文本里。
298
+ *
299
+ * ⚠️ 纯 ASCII 的词形必须按**词边界**判:`includes('read')` 会咬中 `README`,
300
+ * `includes('ttl')` 会咬中 `nettl` 之类 —— 假替身因此凭空多出相似度(实测踩到过:
301
+ * README 被当成「使用反馈」的候选)。中文按子串即可(没有词边界这回事)。
302
+ *
303
+ * @param {string} lower - 已小写化的文本
304
+ * @param {string} form - 词形
305
+ * @returns {boolean}
306
+ */
307
+ function matchesForm(lower, form) {
308
+ const needle = form.toLowerCase()
309
+ if (!/^[a-z0-9][a-z0-9-]*$/.test(needle)) return lower.includes(needle)
310
+ return new RegExp(`\\b${needle}\\b`).test(lower)
311
+ }
312
+
313
+ /** 假 fetch 的默认 provider 配置(回环地址,永远不会被真的连)。 */
314
+ export const FAKE_PROVIDER = { kind: 'ollama', base: 'http://127.0.0.1:11434', model: 'corpus-standin-v1' }
315
+
316
+ /**
317
+ * 确定性假 provider 的 `fetchImpl`(注入给 `createSemanticEngine`)。
318
+ *
319
+ * 回答两种请求:`/api/tags`(探测)与 `/api/embed`(嵌入)。
320
+ * `calls` 会记下每一次调用 —— 判据「默认零调用」「每轮嵌入有上界」都靠它。
321
+ *
322
+ * @param {{probeStatus?: number, embedStatus?: number}} [options]
323
+ * @returns {Function} fetch 替身(带 `calls` 数组)
324
+ */
325
+ export function createFakeFetch(options = {}) {
326
+ const calls = []
327
+ const impl = async (url, init) => {
328
+ const target = String(url)
329
+ calls.push({ url: target, method: (init && init.method) || 'GET' })
330
+ if (target.includes('/api/tags')) {
331
+ const status = options.probeStatus || 200
332
+ return { status, json: async () => ({ models: [] }) }
333
+ }
334
+ if (options.embedStatus && options.embedStatus !== 200) {
335
+ return { status: options.embedStatus, json: async () => ({}) }
336
+ }
337
+ const input = JSON.parse((init && init.body) || '{"input":[]}').input
338
+ return { status: 200, json: async () => ({ embeddings: input.map((text) => fakeEmbed(text)) }) }
339
+ }
340
+ impl.calls = calls
341
+ return impl
342
+ }
343
+
344
+
345
+ /* ── 驱动 `scan()` 用的假会话 ─────────────────────────
346
+ * ⚠️ 为什么不用 `scan({ query })` 这条更短的路:显式 query 路径**没有 task**
347
+ * (`index.js` 里那条注释说得很清楚:模型自己知道在问什么,把 query 当任务「是编的」),
348
+ * 于是语义引擎拿到的查询文本会退化成 `keywords.join(' ')` —— 而 `extractKeywords()`
349
+ * 会给长词去重叠(`失效策` 吃掉 `失效`),实际传给 provider 的就只剩几个碎片。
350
+ * 面板与带会话的工具走的是**会话路径**:`task` = 用户原话 ⇒ 语义查询文本就是原话。
351
+ * 量尺要量的是那条路,所以这里造一个最小会话。
352
+ */
353
+
354
+ /**
355
+ * 造一个最小假会话(只需要 `header` 与 `snapshotEvents()`)。
356
+ * @param {string} text - 用户那句话
357
+ * @param {string} cwd - 工作区根
358
+ * @returns {object} 假会话
359
+ */
360
+ export function fakeSession(text, cwd) {
361
+ return {
362
+ header: { cwd, id: 'sess-corpus-eval' },
363
+ snapshotEvents: () => [
364
+ {
365
+ seq: 1,
366
+ type: 'user/message',
367
+ // ⚠️ 事件形状要跟宿主一致:`data` **本身就是那条 message**(`role` + `content`),
368
+ // `source` 挂在同一层。写成 `data.message` 的话 `messageText()` 取不到文本,
369
+ // 会话路径会静默退化成「没有对话」⇒ 整条查询变成时间序(踩过一次)。
370
+ data: { role: 'user', content: [{ type: 'text', text }], source: { kind: 'user' } },
371
+ },
372
+ ],
373
+ }
374
+ }
375
+
376
+ /** 把 `DOCS` 变成 `makeWorkspace()` 要的 `[rel, 内容]` 列表。 */
377
+ export function corpusFiles() {
378
+ return DOCS.map((doc) => [doc.rel, `# ${doc.title}\n\n${doc.body}`])
379
+ }
@@ -0,0 +1,231 @@
1
+ /**
2
+ * Knit v0.23 · **四路径量尺的机器**(指标 + 跑一条路径 + provider 探测)。
3
+ *
4
+ * ⚠️ 为什么机器在 `test/` 而不是 `tools/`:**`tools/` 不随 npm 包发布**
5
+ * (`package.json` 的 `files` 白名单只有两个脚本),而 `test/hybrid-eval.test.mjs`
6
+ * 要引它。v0.20.0 就是这么翻车的 —— `test/deep-scale.test.mjs` 当时从
7
+ * `tools/deep-benchmark.mjs` 取语料,发出去的包里 `npm test` 直接 638/1。
8
+ * 修法也照抄那一次:**测试要用的东西放 `test/`**(语料 `retrieval-corpus.mjs` 同理)。
9
+ *
10
+ * CLI 与四路径报告在 `tools/hybrid-retrieval-eval.mjs`(那一份不进包,随便跑)。
11
+ */
12
+
13
+ import { scan, setSemanticEngine, publicScanPayload } from '../src/host/index.js'
14
+ import { buildContext } from '../src/host/context.js'
15
+ import { clearVectors, SEM_EMBED_PER_PASS } from '../src/host/semantic.js'
16
+ import { DOCS, QUERIES, fakeSession } from './retrieval-corpus.mjs'
17
+
18
+ /** 冷启动要跑几轮「像面板那样每 5 秒轮询一次」才能把语料铺满向量缓存。 */
19
+ export const WARMUP_PASSES = Math.ceil(DOCS.length / SEM_EMBED_PER_PASS)
20
+
21
+ /* ── 指标(纯函数,测试直接引这几个)────────────────────
22
+ * 口径写在名字里:**都按「包内顺序」算** —— 包才是用户与 agent 真正拿到的东西,
23
+ * `ranked` 只是内部名次。K 默认 5(包通常就 5–15 条)。
24
+ */
25
+
26
+ /**
27
+ * 前 K 条里命中了多少条标注答案。
28
+ * @param {string[]} packRels - 包内 rel(按阅读顺序)
29
+ * @param {string[]} expected - 人工标注的正确答案
30
+ * @param {number} [k] - 只看前 K 条
31
+ * @returns {number} 0..1;`expected` 为空时返回 0(没有答案就没有召回率可言)
32
+ */
33
+ export function recallAt(packRels, expected, k = 5) {
34
+ const want = Array.isArray(expected) ? expected : []
35
+ if (want.length === 0) return 0
36
+ const top = packRels.slice(0, k)
37
+ let hit = 0
38
+ for (const rel of want) if (top.includes(rel)) hit += 1
39
+ return hit / want.length
40
+ }
41
+
42
+ /**
43
+ * 第一条命中的倒数排名(MRR)。
44
+ * @param {string[]} packRels - 包内 rel(按阅读顺序)
45
+ * @param {string[]} expected - 人工标注的正确答案
46
+ * @returns {number} 1/rank;一条都没命中返回 0
47
+ */
48
+ export function mrr(packRels, expected) {
49
+ const want = new Set(Array.isArray(expected) ? expected : [])
50
+ if (want.size === 0) return 0
51
+ for (let i = 0; i < packRels.length; i += 1) {
52
+ if (want.has(packRels[i])) return 1 / (i + 1)
53
+ }
54
+ return 0
55
+ }
56
+
57
+ /**
58
+ * 前 K 条里有多少条**不在**标注答案里(无关候选率)。
59
+ * @param {string[]} packRels - 包内 rel
60
+ * @param {string[]} expected - 正确答案
61
+ * @param {number} [k] - 只看前 K 条
62
+ * @returns {number} 0..1
63
+ */
64
+ export function unrelatedRateAt(packRels, expected, k = 5) {
65
+ const top = packRels.slice(0, k)
66
+ if (top.length === 0) return 0
67
+ const want = new Set(Array.isArray(expected) ? expected : [])
68
+ return top.filter((rel) => !want.has(rel)).length / top.length
69
+ }
70
+
71
+ /** 包内 rel(按阅读顺序:主要 → 辅助 → 相关)。 */
72
+ export function packRels(pack) {
73
+ return [...pack.primary, ...pack.supporting, ...pack.related].map((item) => item.rel)
74
+ }
75
+
76
+ /** 命中层分布:这条 rel 落在哪一层(不在包里返回 null)。 */
77
+ export function tierOf(pack, rel) {
78
+ if (pack.primary.some((i) => i.rel === rel)) return 'primary'
79
+ if (pack.supporting.some((i) => i.rel === rel)) return 'supporting'
80
+ if (pack.related.some((i) => i.rel === rel)) return 'related'
81
+ return null
82
+ }
83
+
84
+ /* ── 装配:把一次 `scan()` 的结果变成包 ─────────────────── */
85
+
86
+ export const assemble = (payload) => buildContext({
87
+ ranked: payload.ranked,
88
+ topic: payload.topic,
89
+ task: payload.task,
90
+ total: payload.total,
91
+ graph: null,
92
+ })
93
+
94
+ /**
95
+ * 把 fetch 包一层计数(「provider 调用次数」就数它 —— 引擎只会通过注入的 fetchImpl 出去)。
96
+ * @param {Function} inner - 真的 fetch(替身或全局)
97
+ * @returns {Function} 带 `count` 的 fetch
98
+ */
99
+ export function countingFetch(inner) {
100
+ const fn = async (url, init) => {
101
+ fn.count += 1
102
+ return inner(url, init)
103
+ }
104
+ fn.count = 0
105
+ return fn
106
+ }
107
+
108
+ /**
109
+ * 跑一条路径上的全部查询。
110
+ *
111
+ * @param {object} options - `{ root, retrieval, engine, label, counter }`
112
+ * `engine` 为 null 表示不装语义引擎(纯词法);`counter` 是计数 fetch(可无)。
113
+ * @returns {Promise<{rows: object[], wallMs: number, calls: number}>}
114
+ */
115
+ export async function runPath(options) {
116
+ const { root, retrieval, engine, label, counter } = options
117
+ clearVectors()
118
+ if (engine) setSemanticEngine(engine)
119
+ else setSemanticEngine(null)
120
+
121
+ const rows = []
122
+ const started = Date.now()
123
+ for (const q of QUERIES) {
124
+ const session = fakeSession(q.query, root)
125
+ // ⚠️ 每条查询**换一个 sessionId**:`convCache` 按 sessionId + seq 键控,
126
+ // 复用同一个 id 会让第二条查询拿到第一条的关键词(踩过一次)。
127
+ const args = {
128
+ session, sessionId: `corpus-${label}-${q.id}`,
129
+ sort: 'relevance', kind: 'context', retrieval,
130
+ }
131
+ let last = null
132
+ let lastCalls = 0
133
+ // 词法路径不需要预热(没有向量缓存这回事);混合路径要,模拟面板每 5 秒轮询。
134
+ const passes = engine ? WARMUP_PASSES + 1 : 1
135
+ for (let pass = 0; pass < passes; pass += 1) {
136
+ const before = counter ? counter.count : 0
137
+ last = await scan(root, 40, args)
138
+ lastCalls = (counter ? counter.count : 0) - before
139
+ }
140
+ const pack = assemble(last)
141
+ const rels = packRels(pack)
142
+ const semantic = last.semantic || {}
143
+ const lexicalRels = (last.ranked || []).filter((d) => (Number(d.raw) || 0) > 0).map((d) => d.rel)
144
+ const zeroHit = (last.ranked || []).filter((d) => (Number(d.raw) || 0) === 0).map((d) => d.rel)
145
+ rows.push({
146
+ id: q.id, case: q.case, query: q.query,
147
+ expected: q.expected, rescue: q.rescue,
148
+ rels,
149
+ // 分层结构与面板载荷都留着给测试用(判据 8a/8b 要逐字比它们)
150
+ tiers: {
151
+ primary: pack.primary.map((i) => i.rel),
152
+ supporting: pack.supporting.map((i) => i.rel),
153
+ related: pack.related.map((i) => i.rel),
154
+ },
155
+ publicPayload: publicScanPayload(last),
156
+ tier: q.expected.map((rel) => `${rel}=${tierOf(pack, rel) || '缺'}`).join(' '),
157
+ lexicalRels, zeroHit,
158
+ appended: rels.slice(0, 0), // 由调用方与 L 对比后填
159
+ semantic: {
160
+ mode: semantic.mode, reason: semantic.reason,
161
+ candidates: semantic.candidates,
162
+ configured: semantic.configured,
163
+ },
164
+ passCalls: lastCalls,
165
+ })
166
+ }
167
+ setSemanticEngine(null)
168
+ return { rows, wallMs: Date.now() - started, calls: counter ? counter.count : 0 }
169
+ }
170
+
171
+ /** 打印一张表(纯文本,列宽自适应)。 */
172
+ /** 纯文本等宽表(CLI 打印指标用;同样必须导出,理由见 `summarize()`)。 */
173
+ export function table(headers, rows) {
174
+ const widths = headers.map((h, i) => Math.max(h.length, ...rows.map((r) => String(r[i] ?? '').length)))
175
+ const line = (cells) => cells.map((c, i) => String(c ?? '').padEnd(widths[i])).join(' ')
176
+ return [line(headers), widths.map((w) => '-'.repeat(w)).join(' '), ...rows.map(line)].join('\n')
177
+ }
178
+
179
+ /** 一条查询的指标聚合。 */
180
+ /**
181
+ * 把一组「每条查询的命中情况」收成一行指标。
182
+ *
183
+ * ⚠️ **必须导出**:`tools/hybrid-retrieval-eval.mjs`(CLI)也要用它 —— 它原来是个私有函数,
184
+ * 于是 CLI 一跑就 `ReferenceError: summarize is not defined`(2026-10-12 实测抓到)。
185
+ * 机器住 `test/`(`tools/` 不进包、而测试要引它),CLI 只做打印。
186
+ */
187
+ export function summarize(rows) {
188
+ const n = rows.length
189
+ const avg = (fn) => rows.reduce((sum, r) => sum + fn(r), 0) / (n || 1)
190
+ return {
191
+ queries: n,
192
+ recall5: avg((r) => recallAt(r.rels, r.expected, 5)),
193
+ recall10: avg((r) => recallAt(r.rels, r.expected, 10)),
194
+ mrr: avg((r) => mrr(r.rels, r.expected)),
195
+ unrelated5: avg((r) => unrelatedRateAt(r.rels, r.expected, 5)),
196
+ avgPack: avg((r) => r.rels.length),
197
+ }
198
+ }
199
+
200
+ /** 探测一个真 provider 在不在(只发一个 GET,不装引擎)。H1 靠它决定「跑」还是「如实 skip」。 */
201
+ export async function probeProvider(config) {
202
+ const url = config.kind === 'ollama'
203
+ ? `${config.base}/api/tags`
204
+ : `${config.base}/v1/models`
205
+ try {
206
+ const controller = typeof AbortController === 'function' ? new AbortController() : null
207
+ const timer = controller ? setTimeout(() => controller.abort(), 1500) : null
208
+ const res = await fetch(url, controller ? { signal: controller.signal } : {})
209
+ if (timer) clearTimeout(timer)
210
+ return res.status >= 200 && res.status < 300
211
+ } catch {
212
+ return false
213
+ }
214
+ }
215
+
216
+ /** 真 provider 模式的配置:`KNIT_EVAL_PROVIDER`(JSON)优先,否则本机 Ollama 默认值。 */
217
+ export function providerFromEnv(env = process.env) {
218
+ const raw = env.KNIT_EVAL_PROVIDER
219
+ if (raw) {
220
+ try {
221
+ const parsed = JSON.parse(raw)
222
+ if (parsed && parsed.kind && parsed.base && parsed.model) return parsed
223
+ } catch { /* 落回默认值 */ }
224
+ }
225
+ return {
226
+ kind: 'ollama',
227
+ base: env.KNIT_EVAL_BASE || 'http://127.0.0.1:11434',
228
+ model: env.KNIT_EVAL_MODEL || 'nomic-embed-text',
229
+ }
230
+ }
231
+