dsh-knit 0.22.0 → 0.23.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/test/harness.mjs CHANGED
@@ -105,7 +105,9 @@ export function loadClientModule(options = {}) {
105
105
  // ⚠️ 右栏那套名字(clampPackW / clampFloatPos / nearRightEdge / PACK_*)已随
106
106
  // 右栏一起删除(2026-09-29)。名字留在这里,模块一加载就 ReferenceError ——
107
107
  // 这个替身是**只增不减**的重灾区,删功能时记得同步删名字。
108
- + 'MIN_RATIO, MAX_RATIO, ALL_DOC_CAP, MEDIA_MAX_ITEMS, MEDIA_TRACK_PX, '
108
+ // v0.23(方案 A):`ALL_DOC_CAP` 已随「全部」的类型分区一起删除 ——
109
+ // 这个名单是**只增不减**的重灾区,删功能时也要同步删名字(L1 §8)。
110
+ + 'MIN_RATIO, MAX_RATIO, MEDIA_MAX_ITEMS, MEDIA_TRACK_PX, '
109
111
  + 'MEDIA_LABEL_MIN_PX, MEDIA_GAP_PX, '
110
112
  // v0.18 Context Usage Lens:纯函数与阈值(渲染层的东西仍走 DOM 断言)。
111
113
  + 'LIFE_GLYPH, lifeStatusOf, coverageOf, groupOutsideDocs, groupDelta, '
@@ -265,6 +265,29 @@ test('HTTP 端到端:/api/recent 带 context,且不泄漏装配层的内部
265
265
  }
266
266
  })
267
267
 
268
+ test('v0.23「全部」档:/api/recent 给得出 Context Pack,且媒体**不进任何层**', async () => {
269
+ const { base, close } = await startKnitServer(
270
+ sessionWithEvents([userMessage(1, 'hub 这份文档,还有 screenshot')]), 's-all',
271
+ )
272
+ try {
273
+ const r = await fetch(`${base}/api/recent?sessionId=s-all&kind=all&sort=relevance&limit=40`)
274
+ const body = await r.json()
275
+ assert.equal(body.mode, 'relevance')
276
+ assert.ok(body.context, '「全部」档必须给包 —— 它现在是「整份包的原样」')
277
+ const tiers = [...body.context.primary, ...body.context.supporting, ...body.context.related]
278
+ // 证伪点:媒体能靠**文件名**命中查询词并拿到 `raw > 0`(实测 `docs/screenshot.png` 就会),
279
+ // 它绝不许出现在层里 —— 但**必须**还留在载荷里(客户端末尾那个网格要用它)。
280
+ assert.ok(body.docs.some((d) => d.rel === 'docs/screenshot.png'), '媒体照旧在载荷里')
281
+ assert.ok(tiers.every((i) => i.kind !== 'image' && i.kind !== 'video'), '媒体不进任何层')
282
+ assert.ok(!tiers.some((i) => i.rel === 'docs/screenshot.png'), '靠文件名命中的媒体也不进层')
283
+ // 媒体档:永远没有包(媒体不进上下文是结构性的)
284
+ const rm = await fetch(`${base}/api/recent?sessionId=s-all&kind=media&sort=relevance&limit=40`)
285
+ assert.equal((await rm.json()).context, null, '媒体档不给包')
286
+ } finally {
287
+ await close()
288
+ }
289
+ })
290
+
268
291
  test('HTTP 端到端:/api/context 返回同一份 Context Model', async () => {
269
292
  const { base, close } = await startKnitServer()
270
293
  try {
@@ -0,0 +1,184 @@
1
+ /**
2
+ * Knit v0.23 · **把四路径量尺钉成测试**(`tools/hybrid-retrieval-eval.mjs` 的可证伪版)。
3
+ *
4
+ * 为什么要有这个文件:量尺是「一次性脚本」,跑完就没人记得它当时输出了什么。
5
+ * 这里把**四条判据**变成每次 `npm test` 都会重跑的断言:
6
+ *
7
+ * ① **回退逐字一致**:`hybrid + provider 探测失败`(H2)的面板载荷与 `lexical`(L)**完全相同**;
8
+ * ② **只追加、不改既有**:H0 的「主要 / 辅助」两层与 L 一字不差,「相关」层是 L 的前缀 + 追加,
9
+ * 且标注里「词法必漏、语义该救」的样本真的被补回来了;
10
+ * ③ **有界**:每轮 provider 调用 ≤ 3(探测 1 + 查询 1 + 文档批 1),且冷启一轮最多嵌 `SEM_EMBED_PER_PASS` 篇;
11
+ * ④ **指标函数算得对**:用几个能手算的例子钉住 `recallAt` / `mrr` / `unrelatedRateAt`。
12
+ *
13
+ * ⚠️ **H1(真 provider)刻意不进测试** —— 它会打网络、依赖本机装没装模型,
14
+ * 那属于「离线量尺」,不属于必须可复现的回归。缺 provider 时它由脚本如实打印 skip。
15
+ *
16
+ * ⚠️ 这份测试**只证明机制**:向量来自 `retrieval-corpus.mjs` 的确定性替身(加权同义词表),
17
+ * 不是模型。**判定「语义检索有没有价值」不在这份文件的能力范围内**。
18
+ */
19
+
20
+ import test from 'node:test'
21
+ import assert from 'node:assert/strict'
22
+
23
+ import { makeWorkspace } from './fixture.mjs'
24
+ import { createSemanticEngine, SEM_EMBED_PER_PASS } from '../src/host/semantic.js'
25
+ // ⚠️ 从 `test/` 引,**不是** `tools/` —— `tools/` 不随包发布(v0.20.0 的 tarball 内自测
26
+ // 就是因为测试引了 `tools/` 里的东西而 638/1)。机器与语料都在会进包的那一半。
27
+ import {
28
+ WARMUP_PASSES, recallAt, mrr, unrelatedRateAt,
29
+ runPath, countingFetch, probeProvider, providerFromEnv,
30
+ } from './retrieval-eval.mjs'
31
+ import { FAKE_PROVIDER, QUERIES, corpusFiles, createFakeFetch } from './retrieval-corpus.mjs'
32
+
33
+ const root = makeWorkspace(corpusFiles())
34
+
35
+ /**
36
+ * 剥掉状态行之后的面板载荷(判据 8a 要逐字比它)。
37
+ *
38
+ * ⚠️ `sessionId` 也要剥:它是**请求参数**(每条路径的会话 id 不同,见 `runPath`),
39
+ * 不是检索结果的一部分。第一版没剥,断言红在 `corpus-L-…` vs `corpus-H2-…` 上 ——
40
+ * 那是量尺自己的噪声,不是回退不一致。
41
+ */
42
+ const stripSemantic = (payload) => {
43
+ const { semantic, sessionId, ...rest } = payload
44
+ void semantic
45
+ void sessionId
46
+ return JSON.stringify(rest)
47
+ }
48
+
49
+ /** L:词法基线(不装引擎 ⇒ 零 provider 调用)。 */
50
+ const L = await runPath({ root, retrieval: 'lexical', engine: null, label: 'L' })
51
+
52
+ /** H0:混合 + 确定性替身(调用次数数在 fetch 上)。 */
53
+ const h0Fetch = countingFetch(createFakeFetch())
54
+ const h0Engine = createSemanticEngine({ store: null, fetchImpl: h0Fetch })
55
+ await h0Engine.configure(FAKE_PROVIDER)
56
+ const H0 = await runPath({ root, retrieval: 'hybrid', engine: h0Engine, label: 'H0', counter: h0Fetch })
57
+
58
+ /** H2:混合 + provider 探测失败(真 fetch 打一个关着的端口)。 */
59
+ const h2Fetch = countingFetch(createFakeFetch({ probeStatus: 503 }))
60
+ const h2Engine = createSemanticEngine({ store: null, fetchImpl: h2Fetch, probeTtlMs: 1 })
61
+ await h2Engine.configure(FAKE_PROVIDER)
62
+ const H2 = await runPath({ root, retrieval: 'hybrid', engine: h2Engine, label: 'H2', counter: h2Fetch })
63
+
64
+ const byId = (run, id) => {
65
+ const row = run.rows.find((r) => r.id === id)
66
+ assert.ok(row, `语料里必须有 ${id} 这条查询`)
67
+ return row
68
+ }
69
+
70
+ test('判据 8a:provider 探测失败时,混合结果与词法**逐字一致**(面板载荷 + 包内 rel)', () => {
71
+ assert.equal(H2.rows.length, L.rows.length)
72
+ for (const row of L.rows) {
73
+ const other = byId(H2, row.id)
74
+ assert.deepEqual(other.rels, row.rels, `${row.id}:包内顺序必须一模一样`)
75
+ assert.equal(
76
+ stripSemantic(other.publicPayload),
77
+ stripSemantic(row.publicPayload),
78
+ `${row.id}:除状态行外的面板载荷必须逐字相同`,
79
+ )
80
+ assert.equal(other.semantic.mode, 'lexical', `${row.id}:实际生效模式必须如实回词法`)
81
+ assert.notEqual(other.semantic.reason, null, `${row.id}:必须写明回退原因`)
82
+ }
83
+ })
84
+
85
+ test('判据 8b:H0 只「追加」在相关层 —— 主要 / 辅助两层与 L 一字不差,相关层以 L 为前缀', () => {
86
+ let appendedTotal = 0
87
+ for (const row of L.rows) {
88
+ const other = byId(H0, row.id)
89
+ assert.deepEqual(other.tiers.primary, row.tiers.primary, `${row.id}:主要层不许变`)
90
+ assert.deepEqual(other.tiers.supporting, row.tiers.supporting, `${row.id}:辅助层不许变`)
91
+ assert.deepEqual(
92
+ other.tiers.related.slice(0, row.tiers.related.length),
93
+ row.tiers.related,
94
+ `${row.id}:相关层的既有条目必须原样在前`,
95
+ )
96
+ appendedTotal += other.rels.length - row.rels.length
97
+ }
98
+ assert.ok(appendedTotal > 0, '这份语料里必须至少有一条真的被语义补进来,否则上面两条断言是空转的')
99
+ })
100
+
101
+ test('判据 8b-2:标注为「词法必漏、语义该救」的样本,H0 真的补回来了', () => {
102
+ const rescued = QUERIES.filter((q) => q.rescue.length > 0)
103
+ assert.ok(rescued.length >= 2, '语料里至少要有两条这样的查询,这条守卫才有意义')
104
+ for (const q of rescued) {
105
+ const l = byId(L, q.id)
106
+ const h = byId(H0, q.id)
107
+ for (const rel of q.rescue) {
108
+ assert.ok(!l.rels.includes(rel), `${q.id}:${rel} 在词法路径上**不该**被找到(否则它不是「漏」)`)
109
+ assert.ok(h.rels.includes(rel), `${q.id}:${rel} 应当被语义候选补回来`)
110
+ assert.ok(h.tiers.related.includes(rel), `${q.id}:${rel} 只许落在「相关」层`)
111
+ }
112
+ }
113
+ })
114
+
115
+ test('判据 8c:有界 —— 每轮 provider 调用 ≤ 3(探测 + 查询 + 一批文档)', async () => {
116
+ const counter = countingFetch(createFakeFetch())
117
+ const engine = createSemanticEngine({ store: null, fetchImpl: counter })
118
+ await engine.configure(FAKE_PROVIDER)
119
+ // 冷启动一轮:探测 1 + 查询 1 + 文档批 1
120
+ const cold = await runSingle(engine, counter, 'bounded-cold')
121
+ assert.ok(cold.calls >= 2, `冷启至少要有「探测 + 查询」两次调用,实测 ${cold.calls}`)
122
+ assert.ok(cold.calls <= 3, `冷启不许超过 3 次调用(每轮最多嵌 ${SEM_EMBED_PER_PASS} 篇),实测 ${cold.calls}`)
123
+ // 第二轮:探测有 TTL、文档已缓存 ⇒ 只剩查询那一次
124
+ const warm = await runSingle(engine, counter, 'bounded-warm')
125
+ assert.ok(warm.calls <= 2, `热身之后每轮只该有查询那一次(±1),实测 ${warm.calls}`)
126
+ assert.ok(warm.embedded <= SEM_EMBED_PER_PASS, `单轮嵌入不许超过 ${SEM_EMBED_PER_PASS} 篇`)
127
+ })
128
+
129
+ /** 跑一次扫描,返回这一轮的 provider 调用次数与候选数。 */
130
+ async function runSingle(engine, counter, sessionId) {
131
+ const { scan, setSemanticEngine } = await import('../src/host/index.js')
132
+ const { fakeSession } = await import('./retrieval-corpus.mjs')
133
+ setSemanticEngine(engine)
134
+ const before = counter.count
135
+ const payload = await scan(root, 40, {
136
+ session: fakeSession('缓存失效策略', root),
137
+ sessionId,
138
+ sort: 'relevance',
139
+ kind: 'context',
140
+ retrieval: 'hybrid',
141
+ })
142
+ setSemanticEngine(null)
143
+ return { calls: counter.count - before, embedded: payload.semantic.candidates }
144
+ }
145
+
146
+ test('判据 8d:局部指标函数算得对(手算例子)', () => {
147
+ // Recall@K:分母是标注答案数,分子是「前 K 条里的答案数」
148
+ assert.equal(recallAt(['a', 'b', 'c'], ['b', 'z'], 3), 0.5, '2 个答案命中 1 个 ⇒ 0.5')
149
+ assert.equal(recallAt(['a', 'b', 'c'], ['c'], 2), 0, 'K=2 时 c 在第 3 位 ⇒ 0')
150
+ assert.equal(recallAt(['a', 'b', 'c'], ['c'], 3), 1, 'K=3 时命中')
151
+ assert.equal(recallAt([], ['a'], 5), 0, '空包 ⇒ 0')
152
+ assert.equal(recallAt(['a'], [], 5), 0, '没有标注答案 ⇒ 0(不是 1)')
153
+ // MRR:第一条命中的倒数排名
154
+ assert.equal(mrr(['x', 'b'], ['b']), 0.5, '第 2 位命中 ⇒ 1/2')
155
+ assert.equal(mrr(['b', 'x'], ['b']), 1, '第 1 位命中 ⇒ 1')
156
+ assert.equal(mrr(['x', 'y'], ['b']), 0, '一条都没命中 ⇒ 0')
157
+ // 无关候选率:前 K 条里不在答案里的比例
158
+ assert.equal(unrelatedRateAt(['a', 'b', 'x', 'y'], ['a', 'b'], 4), 0.5, '4 条里 2 条无关 ⇒ 0.5')
159
+ assert.equal(unrelatedRateAt([], ['a'], 5), 0, '空包 ⇒ 0')
160
+ // 量尺本身的自洽:这份语料上 H0 的召回不该低于 L(同输入、同标注)
161
+ const avg = (rows, fn) => rows.reduce((sum, r) => sum + fn(r), 0) / rows.length
162
+ const lRecall = avg(L.rows, (r) => recallAt(r.rels, r.expected, 5))
163
+ const hRecall = avg(H0.rows, (r) => recallAt(r.rels, r.expected, 5))
164
+ assert.ok(
165
+ hRecall >= lRecall,
166
+ `在这份语料上 H0 的 R@5(${hRecall.toFixed(3)})不该低于 L(${lRecall.toFixed(3)})——`
167
+ + '「只追加不改既有」意味着它可以相等,但不可能更低',
168
+ )
169
+ assert.ok(WARMUP_PASSES >= 1)
170
+ })
171
+
172
+ test('判据 8e:H1 的配置解析与探测可用(真 provider 的跑动**故意不在测试里**)', async () => {
173
+ // 默认值:本机 Ollama
174
+ assert.deepEqual(providerFromEnv({}), { kind: 'ollama', base: 'http://127.0.0.1:11434', model: 'nomic-embed-text' })
175
+ // 环境变量给的 JSON 优先
176
+ assert.deepEqual(
177
+ providerFromEnv({ KNIT_EVAL_PROVIDER: '{"kind":"openai-compatible","base":"http://127.0.0.1:9/v1","model":"m"}' }),
178
+ { kind: 'openai-compatible', base: 'http://127.0.0.1:9/v1', model: 'm' },
179
+ )
180
+ // 畸形 JSON 落回默认值,而不是抛
181
+ assert.equal(providerFromEnv({ KNIT_EVAL_PROVIDER: '{oops' }).kind, 'ollama')
182
+ // 探测一个**必然打不通**的回环端口 ⇒ false(H1 因此会如实 skip,而不是假装跑了)
183
+ assert.equal(await probeProvider({ kind: 'ollama', base: 'http://127.0.0.1:9' }), false)
184
+ })
@@ -0,0 +1,313 @@
1
+ /**
2
+ * Knit · **可选混合检索**(v0.23 Phase A + B)的端到端测试。
3
+ *
4
+ * Phase A 的立论是「加了这条通道,默认路径一分钱不花」;**Phase B** 的立论是
5
+ * 「语义条目只能**补进「相关」层**,而且只能**追加在最后**」—— 两层立论都要能被证伪。
6
+ *
7
+ * 判据对照(方案 §9.2):
8
+ * · 1 —— 词法模式下**一次 provider 调用都不发**(哪怕配置好了);
9
+ * · 2 —— `lexical` 与 v0.22 一致;`hybrid` = 既有条目原样 + 语义条目追加;
10
+ * · 2c —— `capRelated` 满时**先挤掉语义条目**,既有条目的成员与顺序不动;
11
+ * · 3 —— 被排除的文件**不可能**经语义路径回来;
12
+ * · 3b —— 零命中的语义条目**进得了包**(拿掉标记必然消失 = 证伪用例);
13
+ * · 5 —— 五种失败各自收敛成一个 `reason`,结果与词法一致;
14
+ * · 6 —— 理由/来源只写可复核的事实:语义条目 `terms` 为空、来源 `semantic`;
15
+ * 同时有词法证据的**按词法**(语义不许盖住它);
16
+ * · 7 —— 公开文档的字段集合不受影响(内部标记不许漏出去)。
17
+ *
18
+ * ⚠️ 这里证明的是**机制**,不是「语义检索有用」—— 价值证据要等 Phase C 的消融(真 provider)。
19
+ */
20
+
21
+ import test from 'node:test'
22
+ import assert from 'node:assert/strict'
23
+
24
+ import { makeWorkspace } from './fixture.mjs'
25
+ import { scan, setSemanticEngine } from '../src/host/index.js'
26
+ import { buildContext } from '../src/host/context.js'
27
+ import { createSemanticEngine, SEM_MIN_SIM } from '../src/host/semantic.js'
28
+
29
+ const CONFIG = { kind: 'ollama', base: 'http://127.0.0.1:11434', model: 'nomic-embed-text' }
30
+ /** 一个能被语义命中的工作区:`secret.md` 的摘要与查询最像,用来验判据 3。 */
31
+ const WORKSPACE = [
32
+ ['docs/alpha.md', '# 甲文档\n\n讲的是排序与相关性。\n'],
33
+ ['docs/beta.md', '# 乙文档\n\n讲的是别的主题。\n'],
34
+ ['docs/secret.md', '# 丙文档\n\n语义检索 语义候选 语义补充\n'],
35
+ ]
36
+
37
+ /** 假 provider:任何输入都给 `[1,0]`(于是与 query 的余弦 = 1,恒过阈值)。 */
38
+ function fakeProvider(options = {}) {
39
+ const calls = []
40
+ const impl = async (url, init) => {
41
+ calls.push({ url: String(url), method: (init && init.method) || 'GET' })
42
+ const path = String(url).replace(CONFIG.base, '')
43
+ if (path === '/api/tags') {
44
+ if (options.probeStatus) return { status: options.probeStatus, json: async () => ({}) }
45
+ return { status: 200, json: async () => ({ models: [] }) }
46
+ }
47
+ if (options.embedGarbage) return { status: 200, json: async () => ({ nope: true }) }
48
+ const input = JSON.parse(init.body).input
49
+ return { status: 200, json: async () => ({ embeddings: input.map(() => [1, 0]) }) }
50
+ }
51
+ impl.calls = calls
52
+ return impl
53
+ }
54
+
55
+ /** 装一个引擎(可带缓存好的 provider 配置),返回 `{engine, calls}`。 */
56
+ async function withEngine(options = {}) {
57
+ const fetchImpl = fakeProvider(options)
58
+ const engine = createSemanticEngine({ store: null, fetchImpl })
59
+ if (options.configure !== false) await engine.configure(CONFIG)
60
+ setSemanticEngine(engine)
61
+ return { engine, calls: fetchImpl.calls }
62
+ }
63
+
64
+ const baseOptions = { sort: 'relevance', kind: 'context', query: '语义检索 语义候选' }
65
+
66
+ /** 把一次扫描装配成 Context Pack(生产同一条路径:`buildContext`)。 */
67
+ const packOf = (payload) => buildContext({
68
+ ranked: payload.ranked,
69
+ topic: payload.topic,
70
+ task: payload.task,
71
+ total: payload.total,
72
+ graph: null,
73
+ })
74
+
75
+ /** 造一条 ranked 记录(形状与 `rankByRelevance()` 的产物一致)。 */
76
+ const record = (rel, raw, terms = [], extra = {}) => ({
77
+ rel,
78
+ title: extra.title === undefined ? rel : extra.title,
79
+ summary: extra.summary === undefined ? '' : extra.summary,
80
+ mtimeMs: 0,
81
+ kind: 'md',
82
+ raw,
83
+ matchedTerms: terms,
84
+ ...(extra.semantic === true ? { semantic: true } : {}),
85
+ })
86
+
87
+ const bodyHit = (term) => ({ term, fields: { body: true, bodyTf: 1 } })
88
+ const titleHit = (term) => ({ term, fields: { title: true } })
89
+
90
+ test('判据 1:词法模式下**一次 provider 调用都不发**(哪怕 provider 配置好了)', async () => {
91
+ const root = makeWorkspace(WORKSPACE)
92
+ const { calls } = await withEngine()
93
+ const payload = await scan(root, 20, { ...baseOptions, retrieval: 'lexical' })
94
+ assert.equal(calls.length, 0, '默认路径不许有任何 provider 调用(连探测都不许)')
95
+ assert.equal(payload.semantic.mode, 'lexical')
96
+ assert.equal(payload.semantic.available, null, '本轮没探测过 ⇒ 不许谎报可用')
97
+ assert.equal(payload.semantic.configured, true)
98
+ assert.equal(payload.semantic.candidates, 0)
99
+ assert.equal(payload.ranked.filter((doc) => doc.semantic === true).length, 0, '词法路径不许标任何语义条目')
100
+ setSemanticEngine(null)
101
+ })
102
+
103
+ test('判据 2:`lexical` 与 v0.22 一致;`hybrid` = 既有条目原样 + 语义条目**追加**在「相关」层', async () => {
104
+ const root = makeWorkspace(WORKSPACE)
105
+ await withEngine()
106
+
107
+ const lexical = await scan(root, 20, { ...baseOptions, retrieval: 'lexical' })
108
+ const hybrid = await scan(root, 20, { ...baseOptions, retrieval: 'hybrid' })
109
+
110
+ assert.equal(hybrid.semantic.mode, 'hybrid')
111
+ assert.equal(hybrid.semantic.available, true)
112
+ assert.ok(hybrid.semantic.candidates > 0, '假 provider 恒回 [1,0],必须有候选')
113
+
114
+ const lexPack = packOf(lexical)
115
+ const hybPack = packOf(hybrid)
116
+ const lexRels = [...lexPack.primary, ...lexPack.supporting, ...lexPack.related].map((i) => i.rel)
117
+ const hybRels = [...hybPack.primary, ...hybPack.supporting, ...hybPack.related].map((i) => i.rel)
118
+
119
+ // ① 既有条目的成员与顺序一个不差,而且都在**前面**(追加语义不许插队)
120
+ assert.deepEqual(hybRels.slice(0, lexRels.length), lexRels)
121
+ assert.deepEqual(hybPack.primary.map((i) => i.rel), lexPack.primary.map((i) => i.rel))
122
+ assert.deepEqual(hybPack.supporting.map((i) => i.rel), lexPack.supporting.map((i) => i.rel))
123
+
124
+ // ② 追加的只能是语义条目,而且只能落在「相关」层
125
+ const appended = hybRels.slice(lexRels.length)
126
+ assert.ok(appended.length > 0, '这一轮必须真的补进了语义条目,否则上面两条断言是空转的')
127
+ for (const rel of appended) {
128
+ const item = hybPack.related.find((row) => row.rel === rel)
129
+ assert.ok(item, `${rel} 只许出现在「相关」层`)
130
+ assert.equal(item.provenance, 'semantic')
131
+ }
132
+ // ③ 词法那一份里一个语义条目都没有(同一份语料、只差 `retrieval`)
133
+ assert.equal(lexPack.related.filter((i) => i.provenance === 'semantic').length, 0)
134
+ setSemanticEngine(null)
135
+ })
136
+
137
+ test('判据 3:被排除的文件**不可能**经语义路径回来(哪怕它是语义上最像的那篇)', async () => {
138
+ const root = makeWorkspace(WORKSPACE)
139
+ await withEngine()
140
+ const excluded = new Set(['docs/secret.md'])
141
+ const payload = await scan(root, 20, { ...baseOptions, excluded, retrieval: 'hybrid' })
142
+ const rels = payload.stats.semantic.rels
143
+ assert.ok(rels.length > 0, '语义候选本身要真的算出来了,这条断言才有意义')
144
+ assert.ok(!rels.includes('docs/secret.md'), '被排除的文件不许出现在语义候选里')
145
+ const pack = packOf(payload)
146
+ const all = [...pack.primary, ...pack.supporting, ...pack.related].map((i) => i.rel)
147
+ assert.ok(!all.includes('docs/secret.md'), '也不许出现在包里')
148
+ setSemanticEngine(null)
149
+ })
150
+
151
+ test('判据 3b:零命中的语义条目**进得了包**,但只进「相关」层;拿掉标记它必然消失(证伪)', () => {
152
+ const main = record('main.md', 9, [titleHit('语义检索')], { title: '主文档', summary: '语义检索' })
153
+ const sem = record('sem.md', 0, [], { title: '语义文档', summary: '语义', semantic: true })
154
+
155
+ const pack = buildContext({ ranked: [main, sem], topic: '语义检索', total: 2, graph: null })
156
+ assert.deepEqual(pack.primary.map((i) => i.rel), ['main.md'])
157
+ assert.deepEqual(pack.supporting.map((i) => i.rel), [], '语义条目不许进「辅助」')
158
+ assert.deepEqual(pack.related.map((i) => i.rel), ['sem.md'], '零命中的语义条目只许落在「相关」')
159
+ assert.equal(pack.related[0].provenance, 'semantic')
160
+ assert.equal(pack.related[0].reason.code, 'semantic')
161
+
162
+ // 证伪:把准入门槛上那个标记拿掉 ⇒ 它必然消失(`raw === 0` 的文档本来进不了任何一层)
163
+ const without = buildContext({
164
+ ranked: [main, record('sem.md', 0, [], { title: '语义文档', summary: '语义' })],
165
+ topic: '语义检索',
166
+ total: 2,
167
+ graph: null,
168
+ })
169
+ assert.deepEqual(without.related.map((i) => i.rel), [], '拿掉标记后它必须消失 —— 这条就是守卫的证伪')
170
+ assert.equal(without.totals.matched, 1, '`matched` 仍是**词法**命中数,语义不许把它灌大')
171
+ })
172
+
173
+ test('判据 6:语义条目的理由是「语义」且**不冒充关键词命中**;同时有词法证据的按词法分层', () => {
174
+ const sem = record('sem.md', 0, [], { title: '语义文档', summary: '语义', semantic: true })
175
+ const both = record('both.md', 7, [titleHit('语义检索')], { title: '两者都有', summary: '语义检索', semantic: true })
176
+ const pack = buildContext({ ranked: [both, sem], topic: '语义检索', total: 2, graph: null })
177
+
178
+ // 语义-only:理由码是 `semantic`,`terms` 必须为空(不许伪装成「正文命中」)
179
+ const semItem = [...pack.related, ...pack.supporting, ...pack.primary].find((i) => i.rel === 'sem.md')
180
+ assert.equal(semItem.reason.code, 'semantic')
181
+ assert.deepEqual(semItem.reason.terms, [])
182
+ assert.equal(semItem.provenance, 'semantic')
183
+
184
+ // 词法 + 语义同时命中:**按词法分层、来源如实写词法**(语义不许盖住它)
185
+ const bothItem = pack.primary.find((i) => i.rel === 'both.md')
186
+ assert.ok(bothItem, '有落脚点的条目仍然按词法进「主要」')
187
+ assert.equal(bothItem.provenance, 'retrieval')
188
+ assert.notEqual(bothItem.reason.code, 'semantic')
189
+ })
190
+
191
+ test('判据 2c:`capRelated` 满的时候,被挤掉的是**语义**条目,不是既有条目', () => {
192
+ const lexicalThree = [
193
+ record('lex1.md', 3, [bodyHit('tsk')]),
194
+ record('lex2.md', 2, [bodyHit('tsk')]),
195
+ record('lex3.md', 1, [bodyHit('tsk')]),
196
+ ]
197
+ const semanticTwo = [
198
+ record('sem1.md', 0, [], { semantic: true }),
199
+ record('sem2.md', 0, [], { semantic: true }),
200
+ ]
201
+ const tight = buildContext({ ranked: [...lexicalThree, ...semanticTwo], topic: 'tsk', total: 5, graph: null, maxRelated: 3 })
202
+ assert.deepEqual(tight.related.map((i) => i.rel), ['lex1.md', 'lex2.md', 'lex3.md'], '既有条目先占坑')
203
+ assert.equal(tight.related.filter((i) => i.provenance === 'semantic').length, 0, '名额不够时先牺牲语义')
204
+
205
+ const roomy = buildContext({ ranked: [...lexicalThree, ...semanticTwo], topic: 'tsk', total: 5, graph: null, maxRelated: 5 })
206
+ const rels = roomy.related.map((i) => i.rel)
207
+ assert.deepEqual(rels.slice(0, 3), ['lex1.md', 'lex2.md', 'lex3.md'], '既有条目的顺序仍然不动')
208
+ assert.deepEqual(rels.slice(3).sort(), ['sem1.md', 'sem2.md'], '剩下的名额才轮到语义,且追加在最后')
209
+ })
210
+
211
+ test('判据 5:没有配置 ⇒ no-provider(结果与词法一致,且不发任何请求)', async () => {
212
+ const root = makeWorkspace(WORKSPACE)
213
+ const { calls } = await withEngine({ configure: false })
214
+ const hybrid = await scan(root, 20, { ...baseOptions, retrieval: 'hybrid' })
215
+ const lexical = await scan(root, 20, { ...baseOptions, retrieval: 'lexical' })
216
+ assert.equal(hybrid.semantic.reason, 'no-provider')
217
+ assert.equal(hybrid.semantic.available, false)
218
+ assert.deepEqual(hybrid.docs, lexical.docs)
219
+ assert.equal(calls.length, 0, '没有配置 ⇒ 连探测都不发')
220
+ setSemanticEngine(null)
221
+ })
222
+
223
+ test('判据 5:探测失败 / 形状不对 / 没有查询文本,各有各的 reason,且结果与词法一致', async () => {
224
+ const root = makeWorkspace(WORKSPACE)
225
+
226
+ await withEngine({ probeStatus: 503 })
227
+ const probeFailed = await scan(root, 20, { ...baseOptions, retrieval: 'hybrid' })
228
+ assert.equal(probeFailed.semantic.reason, 'probe-failed')
229
+
230
+ await withEngine({ embedGarbage: true })
231
+ const badShape = await scan(root, 20, { ...baseOptions, retrieval: 'hybrid' })
232
+ assert.equal(badShape.semantic.reason, 'bad-response')
233
+
234
+ // ⚠️ `no-query` 现在只在**相关序**里才可能出现(时间序整层不适用,见下面那条专门用例),
235
+ // 而且相关序的 `scan()` 必然有关键词 ⇒ 那条分支由 `semantic.test.mjs` 的引擎单测直接覆盖。
236
+ const lexical = await scan(root, 20, { ...baseOptions, retrieval: 'lexical' })
237
+ assert.deepEqual(probeFailed.docs, lexical.docs)
238
+ assert.deepEqual(badShape.docs, lexical.docs)
239
+ // 回退时**一个语义标记都不许留下**(「与词法一致」是逐字一致,不是「差不多」)
240
+ for (const payload of [probeFailed, badShape]) {
241
+ assert.equal(payload.ranked.filter((doc) => doc.semantic === true).length, 0)
242
+ }
243
+ setSemanticEngine(null)
244
+ })
245
+
246
+ test('判据 7:公开文档的字段集合不受影响(没有偷偷加字段 —— 含 `semantic` 标记)', async () => {
247
+ const root = makeWorkspace(WORKSPACE)
248
+ await withEngine()
249
+ const lexical = await scan(root, 20, { ...baseOptions, retrieval: 'lexical' })
250
+ const hybrid = await scan(root, 20, { ...baseOptions, retrieval: 'hybrid' })
251
+ assert.ok(lexical.docs.length > 0)
252
+ assert.deepEqual(Object.keys(hybrid.docs[0]).sort(), Object.keys(lexical.docs[0]).sort())
253
+ // 内部标记不许漏到浏览器那一份上
254
+ for (const doc of hybrid.docs) assert.equal('semantic' in doc, false, '`semantic` 是宿主内部字段')
255
+ setSemanticEngine(null)
256
+ })
257
+
258
+ test('修订 · 时间序下语义整层不适用:**一次 provider 调用都不发**,如实回 `not-applicable`', async () => {
259
+ const root = makeWorkspace(WORKSPACE)
260
+ const { calls } = await withEngine()
261
+ const payload = await scan(root, 20, { sort: 'time', kind: 'context', query: '语义检索', retrieval: 'hybrid' })
262
+ assert.equal(calls.length, 0, '时间序没有分层结构 ⇒ 语义这一轮连探测都不该发')
263
+ assert.equal(payload.semantic.mode, 'lexical')
264
+ assert.equal(payload.semantic.requested, 'hybrid')
265
+ assert.equal(payload.semantic.reason, 'not-applicable')
266
+ assert.equal(payload.semantic.candidates, 0)
267
+ assert.equal(payload.ranked.length, 0, '时间序本来就没有 ranked')
268
+ setSemanticEngine(null)
269
+ })
270
+
271
+ test('修订 · 嵌入用的查询文本是**用户原话**,不是抽完关键词后的 3-gram 碎片(Phase C 量尺发现)', async () => {
272
+ const root = makeWorkspace(WORKSPACE)
273
+ // 故意选一句会被 `extractKeywords()` 切成碎片的长句:显式 query 路径原来就是这么退化的
274
+ const sentence = '失效策略怎么定才稳妥'
275
+ const seen = []
276
+ const fetchImpl = async (url, init) => {
277
+ if (String(url).endsWith('/api/tags')) return { status: 200, json: async () => ({}) }
278
+ const input = JSON.parse(init.body).input
279
+ seen.push(input[0])
280
+ return { status: 200, json: async () => ({ embeddings: input.map(() => [1, 0]) }) }
281
+ }
282
+ const engine = createSemanticEngine({ store: null, fetchImpl })
283
+ await engine.configure(CONFIG)
284
+ setSemanticEngine(engine)
285
+
286
+ // 走**显式 query** 那条路(`knit_docs(query=…)` / 工具的路径):`task` 为空
287
+ const payload = await scan(root, 20, { sort: 'relevance', kind: 'context', query: sentence, retrieval: 'hybrid' })
288
+ assert.equal(payload.semantic.mode, 'hybrid')
289
+ assert.ok(seen.length > 0, '要真的发过嵌入请求')
290
+ assert.equal(seen[0], sentence, `嵌入的查询文本必须是原话;实际是 ${JSON.stringify(seen[0])}`)
291
+ // 证伪:抽出来的关键词确实是碎片(说明「原话优先」这条不是空转的守卫)
292
+ assert.ok(!payload.keywords.includes(sentence))
293
+ setSemanticEngine(null)
294
+ })
295
+
296
+ test('语义阈值:低于 `SEM_MIN_SIM` 的候选不计入(阈值是计数口径)', async () => {
297
+ const root = makeWorkspace(WORKSPACE)
298
+ const fetchImpl = async (url, init) => {
299
+ if (String(url).endsWith('/api/tags')) return { status: 200, json: async () => ({}) }
300
+ const input = JSON.parse(init.body).input
301
+ // query 那一次只有一条输入 ⇒ 给 [1,0];文档批次(>1 条)全给 [0,1](与 query 正交 ⇒ 余弦 0)
302
+ const vectors = input.map(() => (input.length === 1 ? [1, 0] : [0, 1]))
303
+ return { status: 200, json: async () => ({ embeddings: vectors }) }
304
+ }
305
+ const engine = createSemanticEngine({ store: null, fetchImpl })
306
+ await engine.configure(CONFIG)
307
+ setSemanticEngine(engine)
308
+ const payload = await scan(root, 20, { ...baseOptions, retrieval: 'hybrid' })
309
+ assert.equal(payload.semantic.available, true)
310
+ assert.equal(payload.semantic.candidates, 0, `正交向量不许达到 ${SEM_MIN_SIM} 阈值`)
311
+ assert.equal(payload.ranked.filter((doc) => doc.semantic === true).length, 0, '没有候选就不许标任何条目')
312
+ setSemanticEngine(null)
313
+ })