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,257 @@
1
+ /**
2
+ * Knit · **可选混合检索**(v0.23 Phase A)的单位测试 —— `src/host/semantic.js`。
3
+ *
4
+ * 这一层只回答一个问题:**「默认不花钱、失败能回退、候选有上界」这三件事是不是真的**。
5
+ * 所以断言分四组:
6
+ * · 配置的收敛(不可信输入一律丢弃,不抛);
7
+ * · 两种协议的**形状**(用注入的假 `fetch`,不打真网络);
8
+ * · 有界与缓存(每轮最多嵌入 N 篇;第二轮不再重算);
9
+ * · 五条回退原因(`no-provider` / `probe-failed` / `timeout` / `bad-response` / `no-query`)。
10
+ *
11
+ * ⚠️ **这些都是「机制通过」,不是「语义检索有用」** —— 价值证据只能由 Phase C 的消融在
12
+ * 真 provider 上给出(方案 §9.1 的 `value-evidence: pending`)。
13
+ */
14
+
15
+ import test from 'node:test'
16
+ import assert from 'node:assert/strict'
17
+
18
+ import { fakeStorageBackend } from './fixture.mjs'
19
+ import {
20
+ cosine, createSemanticEngine, createSemanticProvider, createSemanticStore,
21
+ embedTextOf, isLoopbackBase, normalizeProviderConfig, SEM_EMBED_PER_PASS,
22
+ } from '../src/host/semantic.js'
23
+
24
+ /** 一个记数的假 fetch:按 URL 分派,可注入失败模式。 */
25
+ function fakeFetch(routes = {}) {
26
+ const calls = []
27
+ const impl = async (url, init) => {
28
+ calls.push({ url: String(url), method: (init && init.method) || 'GET', body: init && init.body })
29
+ for (const [pattern, handler] of Object.entries(routes)) {
30
+ if (String(url).includes(pattern)) return handler(url, init)
31
+ }
32
+ return { status: 404, json: async () => ({}) }
33
+ }
34
+ impl.calls = calls
35
+ return impl
36
+ }
37
+
38
+ const okJson = (body) => async () => ({ status: 200, json: async () => body })
39
+ const status = (code) => async () => ({ status: code, json: async () => ({}) })
40
+ const throwAbort = () => async () => {
41
+ const error = new Error('The operation was aborted')
42
+ error.name = 'AbortError'
43
+ throw error
44
+ }
45
+
46
+ const OLLAMA = { kind: 'ollama', base: 'http://127.0.0.1:11434', model: 'nomic-embed-text' }
47
+ const OPENAI = { kind: 'openai-compatible', base: 'https://api.example.com', model: 'text-embedding-3-small' }
48
+
49
+ test('配置收敛:只认两种协议 + http(s) base + 非空 model,其余一律 null(不抛)', () => {
50
+ assert.deepEqual(normalizeProviderConfig(OLLAMA), OLLAMA)
51
+ assert.deepEqual(normalizeProviderConfig(OPENAI), OPENAI)
52
+ // 尾部斜杠去掉(两种协议都要拼路径,留着会出现 `//`)
53
+ assert.equal(normalizeProviderConfig({ ...OLLAMA, base: 'http://127.0.0.1:11434/' }).base, 'http://127.0.0.1:11434')
54
+ for (const bad of [
55
+ null, undefined, 'ollama', 42, [],
56
+ { ...OLLAMA, kind: 'openai' }, // 不在白名单
57
+ { ...OLLAMA, base: 'file:///etc/passwd' }, // 不是 http(s)
58
+ { ...OLLAMA, model: '' }, // 空模型
59
+ { ...OLLAMA, base: 'http://127.0.0.1:11434', model: 'x'.repeat(200) }, // 过长
60
+ ]) {
61
+ assert.equal(normalizeProviderConfig(bad), null, `应被丢弃:${JSON.stringify(bad)}`)
62
+ }
63
+ })
64
+
65
+ test('isLoopbackBase:只有本机三种写法算本机(客户端据此决定要不要披露)', () => {
66
+ assert.equal(isLoopbackBase('http://127.0.0.1:11434'), true)
67
+ assert.equal(isLoopbackBase('http://localhost:1234/v1'), true)
68
+ assert.equal(isLoopbackBase('http://[::1]:8080'), true)
69
+ assert.equal(isLoopbackBase('https://api.example.com'), false)
70
+ assert.equal(isLoopbackBase('http://192.168.1.9:11434'), false)
71
+ assert.equal(isLoopbackBase('not a url'), false)
72
+ })
73
+
74
+ test('cosine:同向 = 1、正交 = 0、长度不等 / 全零 = 0(不是 NaN)', () => {
75
+ assert.equal(cosine([1, 2, 3], [1, 2, 3]), 1)
76
+ assert.equal(cosine([1, 0], [0, 1]), 0)
77
+ assert.equal(cosine([1, 0], [1, 0, 0]), 0)
78
+ assert.equal(cosine([0, 0], [1, 1]), 0)
79
+ assert.equal(cosine(null, [1]), 0)
80
+ })
81
+
82
+ test('embedTextOf:只有 title + summary(两条路径上都有),空 ⇒ null', () => {
83
+ assert.equal(embedTextOf({ title: '甲', summary: '摘要' }), '甲\n摘要')
84
+ assert.equal(embedTextOf({ title: '', summary: '摘要' }), '摘要')
85
+ assert.equal(embedTextOf({ title: '', summary: '' }), null)
86
+ assert.equal(embedTextOf({}), null)
87
+ })
88
+
89
+ test('provider · ollama:探测打 /api/tags,嵌入打 /api/embed 并读 embeddings', async () => {
90
+ const fetchImpl = fakeFetch({
91
+ '/api/tags': okJson({ models: [] }),
92
+ '/api/embed': okJson({ embeddings: [[1, 0], [0, 1]] }),
93
+ })
94
+ const provider = createSemanticProvider(OLLAMA, { fetchImpl })
95
+ assert.deepEqual(await provider.probe(), { ok: true })
96
+ const embedded = await provider.embed(['甲', '乙'])
97
+ assert.equal(embedded.ok, true)
98
+ assert.deepEqual(embedded.vectors, [[1, 0], [0, 1]])
99
+ assert.equal(fetchImpl.calls.length, 2)
100
+ assert.equal(fetchImpl.calls[1].method, 'POST')
101
+ assert.deepEqual(JSON.parse(fetchImpl.calls[1].body), { model: OLLAMA.model, input: ['甲', '乙'] })
102
+ })
103
+
104
+ test('provider · openai 兼容:探测打 /v1/models,嵌入打 /v1/embeddings 并读 data[].embedding', async () => {
105
+ const fetchImpl = fakeFetch({
106
+ '/v1/models': okJson({ data: [] }),
107
+ '/v1/embeddings': okJson({ data: [{ embedding: [0.5, 0.5] }] }),
108
+ })
109
+ const provider = createSemanticProvider(OPENAI, { fetchImpl })
110
+ assert.deepEqual(await provider.probe(), { ok: true })
111
+ const embedded = await provider.embed(['甲'])
112
+ assert.deepEqual(embedded.vectors, [[0.5, 0.5]])
113
+ })
114
+
115
+ test('provider · 失败三态:HTTP 非 2xx / 形状不对 / 被 abort,各有各的 reason', async () => {
116
+ const notOk = createSemanticProvider(OLLAMA, { fetchImpl: fakeFetch({ '/api/tags': status(500) }) })
117
+ assert.deepEqual(await notOk.probe(), { ok: false, reason: 'probe-failed' })
118
+
119
+ const badShape = createSemanticProvider(OLLAMA, { fetchImpl: fakeFetch({ '/api/embed': okJson({ nope: true }) }) })
120
+ assert.deepEqual(await badShape.embed(['甲']), { ok: false, reason: 'bad-response' })
121
+
122
+ // 条数对不上也算形状不对(少给一条比多给一条更危险:会错位)
123
+ const short = createSemanticProvider(OLLAMA, { fetchImpl: fakeFetch({ '/api/embed': okJson({ embeddings: [[1]] }) }) })
124
+ assert.deepEqual(await short.embed(['甲', '乙']), { ok: false, reason: 'bad-response' })
125
+
126
+ const aborted = createSemanticProvider(OLLAMA, { fetchImpl: throwAbort() })
127
+ assert.deepEqual(await aborted.probe(), { ok: false, reason: 'timeout' })
128
+ })
129
+
130
+ test('provider · 没有配置或没有 fetch:一律 no-provider,且一个请求都不发', async () => {
131
+ const provider = createSemanticProvider(null)
132
+ assert.deepEqual(await provider.probe(), { ok: false, reason: 'no-provider' })
133
+ const noFetch = createSemanticProvider(OLLAMA, { fetchImpl: null })
134
+ assert.deepEqual(await noFetch.probe(), { ok: false, reason: 'no-provider' })
135
+ })
136
+
137
+ test('store · 配置落盘再读回;没有后端时如实说没存储', async () => {
138
+ const backend = fakeStorageBackend({ tables: {} })
139
+ const store = createSemanticStore({ backend })
140
+ assert.equal(await store.read(), null)
141
+ assert.equal(store.persisted, true, '读成功就是证据(哪怕读回来是空)')
142
+ await store.write(OLLAMA)
143
+ assert.deepEqual(await store.read(), OLLAMA)
144
+ // 坏值写不进去:`normalizeProviderConfig` 拦在门口 ⇒ 等价于清空
145
+ await store.write({ kind: 'nope' })
146
+ assert.equal(await store.read(), null)
147
+
148
+ const none = createSemanticStore({ backend: null })
149
+ assert.equal(await none.read(), null)
150
+ assert.equal(none.persisted, false)
151
+ assert.equal(none.reason, 'no-storage')
152
+ })
153
+
154
+ test('engine · 没有配置 ⇒ no-provider,且**一次 provider 调用都不发**(判据 1)', async () => {
155
+ const fetchImpl = fakeFetch({})
156
+ const engine = createSemanticEngine({ store: null, fetchImpl })
157
+ const result = await engine.pass({ root: '/w', query: '排序', docs: [{ rel: 'a.md', title: '甲', summary: '排序' }] })
158
+ assert.equal(result.reason, 'no-provider')
159
+ assert.equal(result.candidates, 0)
160
+ assert.equal(fetchImpl.calls.length, 0)
161
+ })
162
+
163
+ test('engine · 没有查询文本 ⇒ no-query(探测都不必发)', async () => {
164
+ const fetchImpl = fakeFetch({ '/api/tags': okJson({}) })
165
+ const engine = createSemanticEngine({ store: null, fetchImpl })
166
+ await engine.configure(OLLAMA)
167
+ const result = await engine.pass({ root: '/w', query: ' ', docs: [{ rel: 'a.md', title: '甲', summary: '甲' }] })
168
+ assert.equal(result.reason, 'no-query')
169
+ assert.equal(fetchImpl.calls.length, 0)
170
+ })
171
+
172
+ test('engine · 探测失败 ⇒ probe-failed(结果与词法一致:0 候选)', async () => {
173
+ const fetchImpl = fakeFetch({ '/api/tags': status(503) })
174
+ const engine = createSemanticEngine({ store: null, fetchImpl })
175
+ await engine.configure(OLLAMA)
176
+ const result = await engine.pass({ root: '/w', query: '排序', docs: [{ rel: 'a.md', title: '甲', summary: '甲' }] })
177
+ assert.equal(result.available, false)
178
+ assert.equal(result.reason, 'probe-failed')
179
+ assert.equal(result.candidates, 0)
180
+ })
181
+
182
+ test('engine · 走通一轮:候选按相似度取,且**每轮最多嵌入 N 篇**(有界)', async () => {
183
+ const docs = Array.from({ length: SEM_EMBED_PER_PASS + 4 }, (_, i) => ({
184
+ rel: `d${i}.md`, title: `文档 ${i}`, summary: `第 ${i} 篇`,
185
+ }))
186
+ // ⚠️ 这里用**内联**假 fetch,不走 `fakeFetch()`:这一条要同时断言「调用次数」与
187
+ // 「每轮嵌入上界」,把两者绑在同一个计数器上最不容易读错。
188
+ const calls = []
189
+ const fetchImpl = async (url, init) => {
190
+ calls.push(String(url))
191
+ if (String(url).includes('/api/tags')) return { status: 200, json: async () => ({}) }
192
+ const input = JSON.parse(init.body).input
193
+ return { status: 200, json: async () => ({ embeddings: input.map(() => [1, 0]) }) }
194
+ }
195
+ const engine = createSemanticEngine({ store: null, fetchImpl })
196
+ await engine.configure(OLLAMA)
197
+
198
+ const first = await engine.pass({ root: '/w', query: '排序', docs })
199
+ assert.equal(first.available, true)
200
+ assert.equal(first.embedded, SEM_EMBED_PER_PASS, `一轮最多嵌入 ${SEM_EMBED_PER_PASS} 篇`)
201
+ assert.ok(first.candidates > 0)
202
+ assert.ok(first.candidates <= docs.length)
203
+ assert.equal(calls.length, 3, '探测 1 次 + query 1 次 + 变更批次 1 次')
204
+
205
+ // 第二轮:已缓存的不再重算(有界 + 增量)
206
+ const second = await engine.pass({ root: '/w', query: '排序', docs })
207
+ assert.equal(second.cacheHits, SEM_EMBED_PER_PASS)
208
+ assert.ok(second.embedded > 0, '池子里还没缓存的那些,这一轮继续补')
209
+ assert.ok(second.embedded <= SEM_EMBED_PER_PASS)
210
+ })
211
+
212
+ test('engine · 换 provider(模型变了)⇒ 向量缓存作废,不混用不同模型空间', async () => {
213
+ const docs = [{ rel: 'a.md', title: '甲', summary: '甲' }]
214
+ const fetchImpl = fakeFetch({
215
+ '/api/tags': okJson({}),
216
+ '/api/embed': okJson({ embeddings: [[1, 0]] }),
217
+ })
218
+ const engine = createSemanticEngine({ store: null, fetchImpl })
219
+ await engine.configure(OLLAMA)
220
+ const first = await engine.pass({ root: '/w', query: '排序', docs })
221
+ assert.equal(first.embedded, 1)
222
+ await engine.configure({ ...OLLAMA, model: '另一个模型' })
223
+ const second = await engine.pass({ root: '/w', query: '排序', docs })
224
+ assert.equal(second.cacheHits, 0, '换模型后不许复用旧向量')
225
+ assert.equal(second.embedded, 1)
226
+ })
227
+
228
+ test('engine · 嵌入失败 ⇒ 明着回退(reason 如实,候选 0),不抛', async () => {
229
+ const fetchImpl = fakeFetch({
230
+ '/api/tags': okJson({}),
231
+ '/api/embed': async (url, init) => {
232
+ const input = JSON.parse(init.body).input
233
+ // 探测之后的第一次 embed 是 query;让它失败
234
+ if (input.length === 1) return { status: 200, json: async () => ({ nope: true }) }
235
+ return { status: 200, json: async () => ({ embeddings: [[1, 0]] }) }
236
+ },
237
+ })
238
+ const engine = createSemanticEngine({ store: null, fetchImpl })
239
+ await engine.configure(OLLAMA)
240
+ const result = await engine.pass({ root: '/w', query: '排序', docs: [{ rel: 'a.md', title: '甲', summary: '甲' }] })
241
+ assert.equal(result.available, false)
242
+ assert.equal(result.reason, 'bad-response')
243
+ assert.equal(result.candidates, 0)
244
+ })
245
+
246
+ test('engine · status():配置存在但还没探测过时 available = null(不谎报可用)', async () => {
247
+ const fetchImpl = fakeFetch({ '/api/tags': okJson({}) })
248
+ const engine = createSemanticEngine({ store: null, fetchImpl })
249
+ await engine.ready()
250
+ assert.deepEqual(engine.status().provider, null)
251
+ assert.equal(engine.status().configured, false)
252
+ await engine.configure(OLLAMA)
253
+ assert.equal(engine.status().available, null, '没探测过不许说可用')
254
+ assert.equal(fetchImpl.calls.length, 0, 'status() 本身不发请求')
255
+ await engine.check()
256
+ assert.equal(engine.status().available, true)
257
+ })
@@ -190,10 +190,15 @@ test('apply: webServer 与 tools 都缺席时不抛错', () => {
190
190
 
191
191
  test('定义形状: 参数与输出 schema 与 defineTool 的编译产物一致', () => {
192
192
  const definition = knitDocsDefinition(scan)
193
- // 三个参数都可选 → 没有 required,根对象也没有 additionalProperties
193
+ // 四个参数都可选 → 没有 required,根对象也没有 additionalProperties
194
194
  // v0.15 加了 `audit`(默认 false:不传它完全不走 Context Feedback)
195
- assert.deepEqual(Object.keys(definition.parameters.properties), ['query', 'limit', 'audit'])
195
+ // v0.23 加了 `retrieval`(默认 lexical:不传它时执行路径与配额与 v0.22 逐字相同,
196
+ // 只有**入参键集**从 3 变 4 —— 这正是方案 §9.2 判据 2 写明的那个唯一例外)
197
+ assert.deepEqual(Object.keys(definition.parameters.properties), ['query', 'limit', 'audit', 'retrieval'])
196
198
  assert.equal(definition.parameters.properties.audit.type, 'boolean')
199
+ // v0.23:`retrieval` 是**闭集**(lexical / hybrid),不是自由字符串 ——
200
+ // 认不出的值不许让工具在**校验层**静默失败,也不许悄悄走语义。
201
+ assert.deepEqual(definition.parameters.properties.retrieval.enum, ['lexical', 'hybrid'])
197
202
  assert.equal(definition.parameters.type, 'object')
198
203
  assert.equal(definition.parameters.required, undefined)
199
204
  // 输出是严格的:根与 items 都 additionalProperties: false,且字段必填
@@ -214,9 +219,10 @@ test('定义形状: 参数与输出 schema 与 defineTool 的编译产物一致'
214
219
  )
215
220
  // v0.21:来源三值必须**声明**(同 `kind` 那条教训 —— 装配层每条都给,
216
221
  // schema 少声明一个字段就会在**校验层**静默失败),且不是 `source` 的替代品。
222
+ // v0.23:多一值 `semantic`(语义候选补进来的;默认词法模式下永远不会出现)。
217
223
  assert.deepEqual(
218
224
  items.properties.provenance.enum,
219
- ['retrieval', 'relation', 'manual'],
225
+ ['retrieval', 'relation', 'manual', 'semantic'],
220
226
  )
221
227
  assert.deepEqual(
222
228
  Object.keys(items.properties.relations.items.properties), ['type', 'dir', 'other', 'line'],
@@ -1124,7 +1130,7 @@ test('registerKnitDocsTool: 第五个参数(记账桥)被透传给工具定
1124
1130
  const { bridge } = fakeBridge()
1125
1131
  registerKnitDocsTool(ctx, scan, undefined, buildContextFor, bridge)
1126
1132
  assert.equal(state.definitions.length, 1)
1127
- assert.deepEqual(Object.keys(state.definitions[0].parameters.properties), ['query', 'limit', 'audit'])
1133
+ assert.deepEqual(Object.keys(state.definitions[0].parameters.properties), ['query', 'limit', 'audit', 'retrieval'])
1128
1134
  })
1129
1135
 
1130
1136
  test('renderToolText: 有 usage 时它单独占最后一行,且不影响三层正文', () => {
@@ -1144,3 +1150,52 @@ test('renderToolText: 有 usage 时它单独占最后一行,且不影响三层
1144
1150
  const without = renderToolText({ ...value, usage: undefined })
1145
1151
  assert.ok(!without.endsWith('\n'), without)
1146
1152
  })
1153
+
1154
+ /* ── v0.23 · 可选混合检索:工具面(判据 5 / 6)────────────────────────
1155
+ *
1156
+ * 工具面要守两件事:
1157
+ * ① 默认(词法)调用**一个字节都不变** —— 老调用方不必知道这一版存在;
1158
+ * ② 要了 `hybrid` 而宿主回退时,**如实说**(不许让模型以为拿到的是语义结果)。
1159
+ */
1160
+
1161
+ test('v0.23 工具面:默认(词法)调用不留痕迹 —— 值里没有 `retrieval`,渲染里没有那一行', async () => {
1162
+ const value = await runTool(fakeExec(fakeSession([userMessage(1, '相关性排序与 BM25')])))
1163
+ assert.equal('retrieval' in value, false, '不传 retrieval ⇒ 值里不许出现这个键')
1164
+ const text = renderToolText(value)
1165
+ assert.ok(!text.includes('Retrieval:'), `默认调用的输出不许提检索模式:${text.slice(0, 120)}`)
1166
+ })
1167
+
1168
+ test('v0.23 工具面:要了 `hybrid` 而没有 provider ⇒ 如实写「已回退词法」(判据 5)', async () => {
1169
+ const value = await runTool(fakeExec(fakeSession([userMessage(1, '相关性排序与 BM25')])), { retrieval: 'hybrid' })
1170
+ assert.equal(typeof value.retrieval, 'string', '要了混合就必须写出实际模式')
1171
+ assert.match(value.retrieval, /fell back from hybrid \(no-provider\)/)
1172
+ const text = renderToolText(value)
1173
+ assert.match(text, /^Retrieval: lexical — fell back from hybrid \(no-provider\)$/m)
1174
+ // ③ 同一份结果里,条目本身仍然是词法的理由 —— 回退不许把它伪装成语义命中
1175
+ for (const item of allItems(value)) assert.notEqual(item.reason.code, 'semantic')
1176
+ })
1177
+
1178
+ test('v0.23 工具面:`semantic` 理由码有自己的说法,且**不许**落进 `related` 那句兜底话(判据 6)', () => {
1179
+ const value = {
1180
+ mode: 'relevance',
1181
+ topic: '语义检索',
1182
+ totals: { matched: 1, total: 2 },
1183
+ primary: [{
1184
+ rel: 'main.md', title: '主文档', summary: '摘要', mtimeMs: 0, kind: 'md', source: 'doc',
1185
+ reason: { code: 'titleMatch', terms: ['语义检索'], fields: 1, term: '语义检索' },
1186
+ provenance: 'retrieval',
1187
+ }],
1188
+ supporting: [],
1189
+ related: [{
1190
+ rel: 'sem.md', title: '语义文档', summary: '摘要', mtimeMs: 0, kind: 'md', source: 'doc',
1191
+ reason: { code: 'semantic', terms: [], fields: 0, term: '' },
1192
+ provenance: 'semantic',
1193
+ }],
1194
+ }
1195
+ const text = renderToolText(value)
1196
+ assert.match(text, /Why: semantic candidate/)
1197
+ assert.ok(
1198
+ !text.includes('related in the current workspace'),
1199
+ '`semantic` 必须有自己的说法 —— 落进兜底那句就是「无法验证的推断」(正是需求 §九 禁止的)',
1200
+ )
1201
+ })