@octopi-agent/engine 0.56.0 → 0.65.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.
Files changed (175) hide show
  1. package/dist/config-schema/context.d.ts +1 -1
  2. package/dist/config-schema/context.js +1 -1
  3. package/dist/config-schema/engine.d.ts +43 -1
  4. package/dist/config-schema/substrate.d.ts +42 -0
  5. package/dist/config-schema/substrate.js +58 -0
  6. package/dist/config.d.ts +39 -1
  7. package/dist/harness/agent/builder.d.ts +14 -0
  8. package/dist/harness/agent/builder.js +14 -2
  9. package/dist/harness/agent/config-bridge.js +3 -0
  10. package/dist/harness/{context/capabilities → capabilities}/document/backends/docx.d.ts +1 -1
  11. package/dist/harness/{context/capabilities → capabilities}/document/backends/docx.js +1 -1
  12. package/dist/harness/{context/capabilities → capabilities}/document/backends/office-parser.d.ts +1 -1
  13. package/dist/harness/{context/capabilities → capabilities}/document/backends/office-parser.js +1 -1
  14. package/dist/harness/{context/capabilities → capabilities}/document/backends/pdf.d.ts +1 -1
  15. package/dist/harness/{context/capabilities → capabilities}/document/backends/pdf.js +13 -3
  16. package/dist/harness/{context/capabilities → capabilities}/document/backends/plain.d.ts +1 -1
  17. package/dist/harness/{context/capabilities → capabilities}/document/backends/plain.js +13 -4
  18. package/dist/harness/{context/capabilities → capabilities}/document/backends/sheet.d.ts +1 -1
  19. package/dist/harness/{context/capabilities → capabilities}/document/backends/sheet.js +25 -5
  20. package/dist/harness/{context/capabilities → capabilities}/document/backends/xmind.d.ts +1 -1
  21. package/dist/harness/{context/capabilities → capabilities}/document/backends/xmind.js +1 -1
  22. package/dist/harness/{context/capabilities → capabilities}/document/errors.d.ts +1 -1
  23. package/dist/harness/{context/capabilities → capabilities}/document/errors.js +1 -1
  24. package/dist/harness/capabilities/document/factory.d.ts +33 -0
  25. package/dist/harness/capabilities/document/factory.js +37 -0
  26. package/dist/harness/{context/capabilities → capabilities}/document/format.d.ts +1 -1
  27. package/dist/harness/{context/capabilities → capabilities}/document/format.js +1 -1
  28. package/dist/harness/{context/capabilities → capabilities}/document/html-to-md.d.ts +1 -1
  29. package/dist/harness/{context/capabilities → capabilities}/document/html-to-md.js +1 -1
  30. package/dist/harness/{context/capabilities → capabilities}/document/index.d.ts +3 -1
  31. package/dist/harness/{context/capabilities → capabilities}/document/index.js +2 -1
  32. package/dist/harness/{context/capabilities → capabilities}/document/legacy/factory.d.ts +3 -1
  33. package/dist/harness/{context/capabilities → capabilities}/document/legacy/factory.js +3 -1
  34. package/dist/harness/{context/capabilities → capabilities}/document/legacy/soffice.d.ts +3 -1
  35. package/dist/harness/{context/capabilities → capabilities}/document/legacy/soffice.js +44 -1
  36. package/dist/harness/{context/capabilities → capabilities}/document/port.d.ts +1 -1
  37. package/dist/harness/{context/capabilities → capabilities}/document/port.js +4 -4
  38. package/dist/harness/{context/capabilities → capabilities}/document/types.d.ts +11 -1
  39. package/dist/harness/{context/capabilities → capabilities}/document/types.js +1 -1
  40. package/dist/harness/capabilities/document/worker-port.d.ts +13 -0
  41. package/dist/harness/capabilities/document/worker-port.js +78 -0
  42. package/dist/harness/context/capabilities/index.d.ts +2 -2
  43. package/dist/harness/context/capabilities/index.js +2 -2
  44. package/dist/harness/context/constitution/default-agents.md +1 -0
  45. package/dist/harness/context/index.d.ts +2 -2
  46. package/dist/harness/context/index.js +1 -1
  47. package/dist/harness/context/layer-types.d.ts +26 -2
  48. package/dist/harness/context/layer-types.js +59 -11
  49. package/dist/harness/context/layers.d.ts +3 -0
  50. package/dist/harness/context/layers.js +38 -12
  51. package/dist/harness/context/system-prompt-assembler.d.ts +5 -0
  52. package/dist/harness/context/system-prompt-assembler.js +2 -0
  53. package/dist/harness/extension/plugin-ecosystem/tools/knowledge.d.ts +10 -0
  54. package/dist/harness/extension/plugin-ecosystem/tools/knowledge.js +115 -5
  55. package/dist/harness/extension/plugin-ecosystem/tools/memory.js +3 -0
  56. package/dist/harness/index.d.ts +5 -3
  57. package/dist/harness/index.js +3 -2
  58. package/dist/harness/knowledge/adapters.d.ts +8 -5
  59. package/dist/harness/knowledge/adapters.js +53 -13
  60. package/dist/harness/knowledge/catalog-types.d.ts +4 -0
  61. package/dist/harness/knowledge/client.d.ts +197 -0
  62. package/dist/harness/knowledge/client.js +237 -0
  63. package/dist/harness/knowledge/connector-fetcher.d.ts +2 -2
  64. package/dist/harness/knowledge/connectors.d.ts +3 -3
  65. package/dist/harness/knowledge/connectors.js +14 -8
  66. package/dist/harness/knowledge/db.d.ts +42 -3
  67. package/dist/harness/knowledge/db.js +466 -83
  68. package/dist/harness/knowledge/describe.d.ts +2 -0
  69. package/dist/harness/knowledge/describe.js +5 -1
  70. package/dist/harness/knowledge/document-extract-worker.d.ts +1 -0
  71. package/dist/harness/knowledge/document-extract-worker.js +68 -0
  72. package/dist/harness/knowledge/embed-runner.d.ts +53 -0
  73. package/dist/harness/knowledge/embed-runner.js +171 -0
  74. package/dist/harness/knowledge/engine-thread.d.ts +1 -0
  75. package/dist/harness/knowledge/engine-thread.js +302 -0
  76. package/dist/harness/knowledge/extract-document.d.ts +33 -0
  77. package/dist/harness/knowledge/extract-document.js +86 -0
  78. package/dist/harness/knowledge/fetchers.d.ts +14 -3
  79. package/dist/harness/knowledge/fetchers.js +52 -16
  80. package/dist/harness/knowledge/file-identity.d.ts +53 -0
  81. package/dist/harness/knowledge/file-identity.js +172 -0
  82. package/dist/harness/knowledge/file-index-store.d.ts +50 -0
  83. package/dist/harness/knowledge/file-index-store.js +132 -0
  84. package/dist/harness/knowledge/file-limits.d.ts +86 -0
  85. package/dist/harness/knowledge/file-limits.js +175 -0
  86. package/dist/harness/knowledge/fts.d.ts +60 -0
  87. package/dist/harness/knowledge/fts.js +218 -0
  88. package/dist/harness/knowledge/grounding.d.ts +3 -2
  89. package/dist/harness/knowledge/http-app.d.ts +50 -0
  90. package/dist/harness/knowledge/http-app.js +652 -0
  91. package/dist/harness/knowledge/http-bridge.d.ts +49 -0
  92. package/dist/harness/knowledge/http-bridge.js +17 -0
  93. package/dist/harness/knowledge/index-store.d.ts +166 -63
  94. package/dist/harness/knowledge/index-store.js +1025 -282
  95. package/dist/harness/knowledge/index.d.ts +47 -5
  96. package/dist/harness/knowledge/index.js +24 -2
  97. package/dist/harness/knowledge/ingest.d.ts +322 -49
  98. package/dist/harness/knowledge/ingest.js +1383 -267
  99. package/dist/harness/knowledge/job-control-state.d.ts +29 -0
  100. package/dist/harness/knowledge/job-control-state.js +44 -0
  101. package/dist/harness/knowledge/job-control.d.ts +35 -0
  102. package/dist/harness/knowledge/job-control.js +86 -0
  103. package/dist/harness/knowledge/job-queue.d.ts +62 -0
  104. package/dist/harness/knowledge/job-queue.js +173 -0
  105. package/dist/harness/knowledge/knowledge-serve-child.d.ts +1 -0
  106. package/dist/harness/knowledge/knowledge-serve-child.js +100 -0
  107. package/dist/harness/knowledge/local-stack.d.ts +27 -0
  108. package/dist/harness/knowledge/local-stack.js +63 -0
  109. package/dist/harness/knowledge/membership-store.d.ts +65 -0
  110. package/dist/harness/knowledge/membership-store.js +198 -0
  111. package/dist/harness/knowledge/network-guard.d.ts +11 -2
  112. package/dist/harness/knowledge/network-guard.js +130 -85
  113. package/dist/harness/knowledge/parse-text-in-worker.d.ts +32 -0
  114. package/dist/harness/knowledge/parse-text-in-worker.js +158 -0
  115. package/dist/harness/knowledge/query-service.d.ts +272 -0
  116. package/dist/harness/knowledge/query-service.js +326 -0
  117. package/dist/harness/knowledge/query-worker-client.d.ts +96 -0
  118. package/dist/harness/knowledge/query-worker-client.js +207 -0
  119. package/dist/harness/knowledge/query-worker.d.ts +1 -0
  120. package/dist/harness/knowledge/query-worker.js +186 -0
  121. package/dist/harness/knowledge/read-http.d.ts +35 -0
  122. package/dist/harness/knowledge/read-http.js +373 -0
  123. package/dist/harness/knowledge/retriever.d.ts +30 -5
  124. package/dist/harness/knowledge/retriever.js +98 -35
  125. package/dist/harness/knowledge/secret-scan.d.ts +13 -2
  126. package/dist/harness/knowledge/secret-scan.js +25 -2
  127. package/dist/harness/knowledge/serve.d.ts +48 -0
  128. package/dist/harness/knowledge/serve.js +336 -0
  129. package/dist/harness/knowledge/source-store.d.ts +83 -16
  130. package/dist/harness/knowledge/source-store.js +205 -78
  131. package/dist/harness/knowledge/start-service-process.d.ts +49 -0
  132. package/dist/harness/knowledge/start-service-process.js +158 -0
  133. package/dist/harness/knowledge/text-parse-worker.d.ts +1 -0
  134. package/dist/harness/knowledge/text-parse-worker.js +54 -0
  135. package/dist/harness/knowledge/topics.d.ts +13 -0
  136. package/dist/harness/knowledge/topics.js +48 -0
  137. package/dist/harness/knowledge/types.d.ts +1 -1
  138. package/dist/harness/knowledge/types.js +1 -1
  139. package/dist/harness/knowledge/vector-ann.d.ts +42 -0
  140. package/dist/harness/knowledge/vector-ann.js +68 -0
  141. package/dist/harness/knowledge/writer-lock.d.ts +13 -0
  142. package/dist/harness/knowledge/writer-lock.js +71 -0
  143. package/dist/harness/knowledge/writer-service.d.ts +194 -0
  144. package/dist/harness/knowledge/writer-service.js +355 -0
  145. package/dist/harness/knowledge/writer-worker-client.d.ts +102 -0
  146. package/dist/harness/knowledge/writer-worker-client.js +381 -0
  147. package/dist/harness/knowledge/writer-worker.d.ts +1 -0
  148. package/dist/harness/knowledge/writer-worker.js +189 -0
  149. package/dist/harness/memory/index.d.ts +3 -2
  150. package/dist/harness/memory/index.js +3 -1
  151. package/dist/harness/memory/retrieval-rank.d.ts +51 -0
  152. package/dist/harness/memory/retrieval-rank.js +60 -0
  153. package/dist/harness/memory/sqlite/embedding.d.ts +5 -2
  154. package/dist/harness/memory/sqlite/embedding.js +109 -16
  155. package/dist/harness/memory/sqlite/index.d.ts +2 -2
  156. package/dist/harness/memory/sqlite/index.js +1 -1
  157. package/dist/harness/memory/sqlite/keyword-search.d.ts +41 -2
  158. package/dist/harness/memory/sqlite/keyword-search.js +104 -17
  159. package/dist/harness/memory/sqlite/memory-store.d.ts +18 -4
  160. package/dist/harness/memory/sqlite/memory-store.js +89 -39
  161. package/dist/harness/memory/store.js +39 -21
  162. package/dist/harness/memory/types.d.ts +7 -0
  163. package/dist/harness/run/runner.d.ts +1 -0
  164. package/dist/harness/run/runner.js +4 -2
  165. package/dist/harness/session/attachments/service.d.ts +1 -1
  166. package/dist/harness/session/attachments/service.js +1 -1
  167. package/dist/harness/session/tasks/index.d.ts +1 -1
  168. package/dist/harness/session/tasks/index.js +1 -1
  169. package/dist/harness/session/tasks/render.d.ts +10 -0
  170. package/dist/harness/session/tasks/render.js +27 -0
  171. package/dist/index.d.ts +4 -2
  172. package/dist/index.js +2 -1
  173. package/dist/worker-path.d.ts +8 -0
  174. package/dist/worker-path.js +15 -0
  175. package/package.json +2 -2
@@ -0,0 +1,60 @@
1
+ /**
2
+ * Memory 检索排序与相关性地板
3
+ *
4
+ * 向量路径必须先过相似度地板再按「相关性 + 质量」混合排序;
5
+ * 无命中时宁缺毋滥返回空,禁止用高 quality 无关条目填满 limit。
6
+ *
7
+ * @module harness/memory/retrieval-rank
8
+ */
9
+ /** 向量路径默认最低余弦相似度(低于则丢弃) */
10
+ export const DEFAULT_MIN_SIMILARITY = 0.35;
11
+ /** 混合排序中相似度权重(其余给 quality = importance×confidence×decay) */
12
+ export const DEFAULT_SIMILARITY_WEIGHT = 0.65;
13
+ /** 关键词路径最低字段命中分(strong content=3 / weak content=1.5) */
14
+ /** 默认 3:strong 单命中可通过;仅 weak 二元组(×0.5)不足以过关 */
15
+ export const DEFAULT_MIN_KEYWORD_SCORE = 3;
16
+ /**
17
+ * 记忆质量分(与相关性无关的「值不值得注入」)
18
+ *
19
+ * @param entry - 记忆条目
20
+ * @returns importance × confidence × decayFactor,范围约 [0,1]
21
+ */
22
+ export function qualityScore(entry) {
23
+ return entry.importance * entry.confidence * entry.decayFactor;
24
+ }
25
+ /**
26
+ * 混合排序分:相关性与质量线性加权
27
+ *
28
+ * @param similarity - 余弦相似度 [0,1]
29
+ * @param quality - qualityScore
30
+ * @param similarityWeight - 相似度权重 [0,1]
31
+ * @returns 越大越优先
32
+ */
33
+ export function blendRank(similarity, quality, similarityWeight = DEFAULT_SIMILARITY_WEIGHT) {
34
+ const w = Math.min(1, Math.max(0, similarityWeight));
35
+ return w * similarity + (1 - w) * quality;
36
+ }
37
+ /**
38
+ * 是否达到向量相关性地板
39
+ *
40
+ * @param similarity - 余弦相似度
41
+ * @param minSimilarity - 地板;undefined 用默认
42
+ */
43
+ export function passesSimilarityFloor(similarity, minSimilarity) {
44
+ const floor = minSimilarity ?? DEFAULT_MIN_SIMILARITY;
45
+ return similarity >= floor;
46
+ }
47
+ /**
48
+ * 解析检索相关性旋钮(query 覆盖 options / 默认)
49
+ *
50
+ * @param queryMin - MemoryQuery.minSimilarity
51
+ * @param queryMinKeyword - MemoryQuery.minKeywordScore
52
+ * @param optionsMin - store 选项 minSimilarity
53
+ * @param optionsMinKeyword - store 选项 minKeywordScore
54
+ */
55
+ export function resolveRetrievalKnobs(queryMin, queryMinKeyword, optionsMin, optionsMinKeyword) {
56
+ return {
57
+ minSimilarity: queryMin ?? optionsMin ?? DEFAULT_MIN_SIMILARITY,
58
+ minKeywordScore: queryMinKeyword ?? optionsMinKeyword ?? DEFAULT_MIN_KEYWORD_SCORE,
59
+ };
60
+ }
@@ -17,9 +17,12 @@ export interface EmbeddingProvider {
17
17
  readonly name: string;
18
18
  /** 向量维度 */
19
19
  readonly dimensions: number;
20
- /** 生成 embedding */
20
+ /** 生成 embedding;输入超模型上下文时由实现做截断回退 */
21
21
  embed(text: string): Promise<number[]>;
22
- /** 批量生成 embedding */
22
+ /**
23
+ * 批量生成 embedding。
24
+ * 与入参等长;失败条目为空数组,由调用方按条续试(禁止静默丢条)。
25
+ */
23
26
  embedBatch(texts: string[]): Promise<number[][]>;
24
27
  }
25
28
  /** HTTP 请求/响应字段映射(type=http 或覆盖 openai/ollama 默认) */
@@ -37,6 +37,25 @@ function asEmbedding(value) {
37
37
  // float32 buffer 等情况暂不支持
38
38
  return null;
39
39
  }
40
+ /** 服务端提示输入超过模型上下文(Ollama/TEI/OpenAI 措辞不一) */
41
+ function isContextLengthError(err) {
42
+ const msg = err instanceof Error ? err.message : String(err);
43
+ return /context length|input length|prompt is too long|maximum context|too many tokens|exceeds the (max|context)|max_?tokens|token limit/i.test(msg);
44
+ }
45
+ /**
46
+ * 为 embedding 缩短输入:保头 72% + 尾 28%(表头/结论都在),中间用省略号衔接。
47
+ * 全文仍留在检索侧;这里只影响向量语义覆盖面。
48
+ */
49
+ function shrinkEmbedText(text, maxChars) {
50
+ const t = text.trim();
51
+ if (t.length <= maxChars)
52
+ return t;
53
+ const marker = '\n…\n';
54
+ const budget = Math.max(48, maxChars - marker.length);
55
+ const head = Math.ceil(budget * 0.72);
56
+ const tail = Math.floor(budget * 0.28);
57
+ return `${t.slice(0, head)}${marker}${t.slice(t.length - tail)}`;
58
+ }
40
59
  function defaultPath(type, custom) {
41
60
  if (custom)
42
61
  return custom;
@@ -181,8 +200,8 @@ class HttpEmbeddingProvider {
181
200
  continue;
182
201
  }
183
202
  const vec = asEmbedding(getByPath(item, mapping.itemEmbeddingPath));
184
- if (vec)
185
- out.push(vec);
203
+ // 保留空槽对齐下标;调用方按条重试,禁止静默丢条
204
+ out.push(vec ?? []);
186
205
  }
187
206
  }
188
207
  if (out.length === 0) {
@@ -193,33 +212,87 @@ class HttpEmbeddingProvider {
193
212
  // 协议异常时以实际返回条数为准,由调用方决定是否串行重试
194
213
  return out;
195
214
  }
196
- async embed(text) {
215
+ /** 单次请求;不做截断回退 */
216
+ async embedRaw(text) {
197
217
  const res = await fetch(this.opts.url, {
198
218
  method: 'POST',
199
219
  headers: this.buildHeaders(),
200
220
  body: JSON.stringify(this.buildBody(text)),
201
221
  signal: AbortSignal.timeout(this.opts.timeoutMs),
202
222
  });
223
+ const rawText = await res.text().catch(() => '');
224
+ let data = {};
225
+ if (rawText) {
226
+ try {
227
+ data = JSON.parse(rawText);
228
+ }
229
+ catch {
230
+ data = {};
231
+ }
232
+ }
233
+ else if (typeof res.json === 'function') {
234
+ // 测试桩可能只实现 json();真响应 body 空则维持 {}
235
+ data = await res.json().catch(() => ({}));
236
+ }
203
237
  if (!res.ok) {
204
- const detail = await res.text().catch(() => '');
205
- throw new Error(`Embedding request failed: ${res.status} ${res.statusText} ${detail.slice(0, 200)}`);
238
+ const errText = typeof data?.error === 'string'
239
+ ? data.error
240
+ : rawText.slice(0, 200);
241
+ throw new Error(`Embedding request failed: ${res.status} ${res.statusText} ${errText}`.slice(0, 400));
242
+ }
243
+ const apiErr = data?.error;
244
+ if (typeof apiErr === 'string' && apiErr) {
245
+ throw new Error(`Embedding request failed: ${apiErr}`);
206
246
  }
207
- const data = (await res.json());
208
247
  const vec = this.extractOne(data);
209
248
  if (!vec || vec.length === 0) {
210
249
  throw new Error(`Embedding response missing vector at path "${this.opts.mapping.embeddingsPath}"`);
211
250
  }
212
251
  return vec;
213
252
  }
253
+ async embed(text) {
254
+ try {
255
+ return await this.embedRaw(text);
256
+ }
257
+ catch (err) {
258
+ // 模型上下文按 token 计:同字数中文密度不同,有的 2400 字能进有的不能
259
+ if (!isContextLengthError(err))
260
+ throw err;
261
+ let size = Math.min(text.trim().length, 1600);
262
+ while (size >= 200) {
263
+ try {
264
+ return await this.embedRaw(shrinkEmbedText(text, size));
265
+ }
266
+ catch (e2) {
267
+ if (!isContextLengthError(e2))
268
+ throw e2;
269
+ size = Math.floor(size * 0.7);
270
+ }
271
+ }
272
+ throw err;
273
+ }
274
+ }
214
275
  async embedBatch(texts) {
215
276
  if (texts.length === 0)
216
277
  return [];
217
278
  if (!this.opts.supportsBatch) {
218
- // 串行调用 embed,避免并发压垮单条接口
279
+ // 串行调用 embed(含截断回退);单条失败不拖垮同批其它条
219
280
  const out = [];
281
+ let lastErr;
282
+ let ok = 0;
220
283
  for (const t of texts) {
221
- out.push(await this.embed(t));
284
+ try {
285
+ const vec = await this.embed(t);
286
+ out.push(vec);
287
+ ok += 1;
288
+ }
289
+ catch (e) {
290
+ lastErr = e;
291
+ out.push([]);
292
+ }
222
293
  }
294
+ if (ok === 0 && lastErr)
295
+ throw lastErr;
223
296
  return out;
224
297
  }
225
298
  // 服务端批次上限(如百炼 qwen3.7-text-embedding = 20);超出切片
@@ -248,21 +321,41 @@ class HttpEmbeddingProvider {
248
321
  }
249
322
  const data = (await res.json());
250
323
  const many = this.extractMany(data);
251
- if (many.length >= 1) {
252
- if (many.length === texts.length)
253
- return many;
254
- if (texts.length > 1)
255
- return this.embedSerial(texts);
256
- return many.slice(0, 1);
324
+ if (many.length === texts.length) {
325
+ // 对齐后仍有空槽:按条补齐(embed 内含上下文截断回退);单条失败留空槽给上层续试
326
+ for (let i = 0; i < many.length; i++) {
327
+ if (many[i]?.length)
328
+ continue;
329
+ try {
330
+ many[i] = await this.embed(texts[i]);
331
+ }
332
+ catch {
333
+ many[i] = [];
334
+ }
335
+ }
336
+ return many;
257
337
  }
258
- return this.embedSerial(texts);
338
+ if (texts.length > 1)
339
+ return this.embedSerial(texts);
340
+ return many.slice(0, 1);
259
341
  }
260
342
  /** 串行单条(批量失败回退;避免并发风暴触发限流) */
261
343
  async embedSerial(texts) {
262
344
  const out = [];
345
+ let lastErr;
346
+ let ok = 0;
263
347
  for (const t of texts) {
264
- out.push(await this.embed(t));
348
+ try {
349
+ out.push(await this.embed(t));
350
+ ok += 1;
351
+ }
352
+ catch (e) {
353
+ lastErr = e;
354
+ out.push([]);
355
+ }
265
356
  }
357
+ if (ok === 0 && lastErr)
358
+ throw lastErr;
266
359
  return out;
267
360
  }
268
361
  }
@@ -11,8 +11,8 @@ export { createEmbeddingProviderFromModels, resolveEmbeddingRuntime, isEmbedding
11
11
  export type { ResolvedEmbeddingRuntime } from './embedding-from-models.js';
12
12
  export { cosineSimilarity, cosineDistance, searchTopK, parseEmbedding, serializeEmbedding } from './vector-search.js';
13
13
  export type { VectorSearchResult } from './vector-search.js';
14
- export { tokenizeKeywordQuery, scoreKeywordFields, buildKeywordLikeSql, } from './keyword-search.js';
15
- export type { KeywordFields } from './keyword-search.js';
14
+ export { tokenizeKeywordQuery, tokenizeKeywordDetail, scoreKeywordFields, buildKeywordLikeSql, } from './keyword-search.js';
15
+ export type { KeywordFields, KeywordTokens } from './keyword-search.js';
16
16
  export { tryLoadSqliteVec, ensureMemoryVecTable, upsertMemoryVector, deleteMemoryVector, searchMemoryVectors, MEMORY_VEC_TABLE, } from './sqlite-vec.js';
17
17
  export { SqliteMemoryStore } from './memory-store.js';
18
18
  export type { SqliteMemoryStoreOptions } from './memory-store.js';
@@ -7,7 +7,7 @@ export { AgentDatabase } from './agent-db.js';
7
7
  export { createEmbeddingProvider } from './embedding.js';
8
8
  export { createEmbeddingProviderFromModels, resolveEmbeddingRuntime, isEmbeddingEnabled, resolveEmbeddingEndpoint, } from './embedding-from-models.js';
9
9
  export { cosineSimilarity, cosineDistance, searchTopK, parseEmbedding, serializeEmbedding } from './vector-search.js';
10
- export { tokenizeKeywordQuery, scoreKeywordFields, buildKeywordLikeSql, } from './keyword-search.js';
10
+ export { tokenizeKeywordQuery, tokenizeKeywordDetail, scoreKeywordFields, buildKeywordLikeSql, } from './keyword-search.js';
11
11
  export { tryLoadSqliteVec, ensureMemoryVecTable, upsertMemoryVector, deleteMemoryVector, searchMemoryVectors, MEMORY_VEC_TABLE, } from './sqlite-vec.js';
12
12
  export { SqliteMemoryStore } from './memory-store.js';
13
13
  export { SqliteWisdomStore } from './wisdom-store.js';
@@ -15,16 +15,55 @@ export interface KeywordFields {
15
15
  /**
16
16
  * 查询分词:空白/标点切分;连续 CJK 片段额外产出二元组。
17
17
  *
18
+ * 丢弃长度 &lt; 2 的 token:单字母/单字 `includes` 会命中任意子串(`is`⊂`this`)。
19
+ * 派生二元组(长 CJK 滑窗)记入 weak:单独命中不足以过相关性地板。
20
+ *
18
21
  * @param text - 原始查询
19
- * @returns 去重后的检索词(小写)
22
+ * @returns 去重后的检索词(小写);与 {@link tokenizeKeywordDetail}.all 一致
20
23
  */
21
24
  export declare function tokenizeKeywordQuery(text: string): string[];
25
+ /** 分词明细:strong=整词/整段;weak=长 CJK 滑窗二元组 */
26
+ export interface KeywordTokens {
27
+ all: string[];
28
+ strong: string[];
29
+ weak: string[];
30
+ }
31
+ /**
32
+ * 分词并区分强弱 token。
33
+ *
34
+ * @param text - 原始查询
35
+ */
36
+ export declare function tokenizeKeywordDetail(text: string): KeywordTokens;
37
+ /**
38
+ * 查询是否有足够语义信号做自动召回(grounding)。
39
+ *
40
+ * - ≥2 个 strong 词 → 有
41
+ * - 单个 CJK 整段长度 ≥3(如「技术栈选择」)→ 视为多概念
42
+ * - 否则(「继续」「好的」「ok」)→ 无
43
+ *
44
+ * @param tokens - {@link tokenizeKeywordDetail} 结果
45
+ */
46
+ export declare function hasEnoughQuerySignal(tokens: KeywordTokens | string[]): boolean;
47
+ /**
48
+ * 绝对关键词相关度(0–1):查询 token 被正文/路径覆盖的加权比例。
49
+ *
50
+ * 与结果集无关,供 inject/hint 地板使用;**不要**再做组内 min-max。
51
+ * strong 权重 1,weak(CJK 滑窗二元组)0.5;命中字段:content 1.0 / tags 0.6 / 其它 0.3。
52
+ *
53
+ * @param fields - 可检索字段
54
+ * @param tokens - 查询分词
55
+ * @returns 0–1;无 token 时 0
56
+ */
57
+ export declare function scoreKeywordCoverage(fields: KeywordFields, tokens: string[] | KeywordTokens): number;
22
58
  /**
23
59
  * 单条记忆的关键词命中得分。
24
60
  *
61
+ * 字段权重:content > future_use/tags > evidence/anchors。
62
+ * weak token(CJK 滑窗二元组)命中权重减半,避免「什么/好处」类弱重叠单独过关。
63
+ *
25
64
  * @returns 0 表示无命中;字段权重相加
26
65
  */
27
- export declare function scoreKeywordFields(fields: KeywordFields, tokens: string[]): number;
66
+ export declare function scoreKeywordFields(fields: KeywordFields, tokens: string[] | KeywordTokens): number;
28
67
  /**
29
68
  * 构造 SQLite 多字段 LIKE 条件(OR 各 token × 各字段)。
30
69
  *
@@ -11,29 +11,45 @@ function isCjk(ch) {
11
11
  /**
12
12
  * 查询分词:空白/标点切分;连续 CJK 片段额外产出二元组。
13
13
  *
14
+ * 丢弃长度 &lt; 2 的 token:单字母/单字 `includes` 会命中任意子串(`is`⊂`this`)。
15
+ * 派生二元组(长 CJK 滑窗)记入 weak:单独命中不足以过相关性地板。
16
+ *
14
17
  * @param text - 原始查询
15
- * @returns 去重后的检索词(小写)
18
+ * @returns 去重后的检索词(小写);与 {@link tokenizeKeywordDetail}.all 一致
16
19
  */
17
20
  export function tokenizeKeywordQuery(text) {
21
+ return tokenizeKeywordDetail(text).all;
22
+ }
23
+ /**
24
+ * 分词并区分强弱 token。
25
+ *
26
+ * @param text - 原始查询
27
+ */
28
+ export function tokenizeKeywordDetail(text) {
18
29
  const raw = (text ?? '').trim().toLowerCase();
19
30
  if (!raw)
20
- return [];
21
- const tokens = new Set();
31
+ return { all: [], strong: [], weak: [] };
32
+ const strong = new Set();
33
+ const weak = new Set();
22
34
  const parts = raw.split(/[^\p{L}\p{N}_]+/u).filter(Boolean);
23
35
  for (const part of parts) {
24
- if (part.length >= 1)
25
- tokens.add(part);
36
+ if (part.length >= 2)
37
+ strong.add(part);
26
38
  if (!isCjk(part[0] ?? ''))
27
39
  continue;
28
- // CJK 连续段:按段再切,生成二元组(保留整段词)
29
40
  let run = '';
30
41
  const flush = () => {
31
42
  if (!run)
32
43
  return;
33
44
  if (run.length >= 2)
34
- tokens.add(run);
35
- for (let i = 0; i + 1 < run.length; i++) {
36
- tokens.add(run.slice(i, i + 2));
45
+ strong.add(run);
46
+ // 仅长段的滑窗二元组算 weak(整段本身已进 strong)
47
+ if (run.length > 2) {
48
+ for (let i = 0; i + 1 < run.length; i++) {
49
+ const bi = run.slice(i, i + 2);
50
+ if (!strong.has(bi))
51
+ weak.add(bi);
52
+ }
37
53
  }
38
54
  run = '';
39
55
  };
@@ -45,7 +61,72 @@ export function tokenizeKeywordQuery(text) {
45
61
  }
46
62
  flush();
47
63
  }
48
- return [...tokens].filter((t) => t.length > 0);
64
+ const all = [...new Set([...strong, ...weak])].filter((t) => t.length >= 2);
65
+ return { all, strong: [...strong].filter((t) => t.length >= 2), weak: [...weak] };
66
+ }
67
+ /**
68
+ * 查询是否有足够语义信号做自动召回(grounding)。
69
+ *
70
+ * - ≥2 个 strong 词 → 有
71
+ * - 单个 CJK 整段长度 ≥3(如「技术栈选择」)→ 视为多概念
72
+ * - 否则(「继续」「好的」「ok」)→ 无
73
+ *
74
+ * @param tokens - {@link tokenizeKeywordDetail} 结果
75
+ */
76
+ export function hasEnoughQuerySignal(tokens) {
77
+ const strong = Array.isArray(tokens) ? tokens : tokens.strong;
78
+ const usable = strong.filter((t) => t.length >= 2);
79
+ if (usable.length >= 2)
80
+ return true;
81
+ return usable.some((t) => t.length >= 3 && isCjk(t[0] ?? ''));
82
+ }
83
+ /**
84
+ * 绝对关键词相关度(0–1):查询 token 被正文/路径覆盖的加权比例。
85
+ *
86
+ * 与结果集无关,供 inject/hint 地板使用;**不要**再做组内 min-max。
87
+ * strong 权重 1,weak(CJK 滑窗二元组)0.5;命中字段:content 1.0 / tags 0.6 / 其它 0.3。
88
+ *
89
+ * @param fields - 可检索字段
90
+ * @param tokens - 查询分词
91
+ * @returns 0–1;无 token 时 0
92
+ */
93
+ export function scoreKeywordCoverage(fields, tokens) {
94
+ const detail = Array.isArray(tokens)
95
+ ? {
96
+ all: tokens,
97
+ strong: tokens,
98
+ weak: [],
99
+ }
100
+ : tokens;
101
+ const list = detail.all;
102
+ if (list.length === 0)
103
+ return 0;
104
+ const weakSet = new Set(detail.weak);
105
+ const content = (fields.content ?? '').toLowerCase();
106
+ const futureUse = (fields.futureUse ?? '').toLowerCase();
107
+ const tags = asText(fields.tags).toLowerCase();
108
+ const anchors = asText(fields.anchors).toLowerCase();
109
+ const evidence = (fields.evidence ?? '').toLowerCase();
110
+ let totalW = 0;
111
+ let hitW = 0;
112
+ for (const token of list) {
113
+ if (!token)
114
+ continue;
115
+ const tw = weakSet.has(token) ? 0.5 : 1;
116
+ totalW += tw;
117
+ if (content.includes(token)) {
118
+ hitW += tw * 1.0;
119
+ }
120
+ else if (tags.includes(token)) {
121
+ hitW += tw * 0.6;
122
+ }
123
+ else if (futureUse.includes(token) || anchors.includes(token) || evidence.includes(token)) {
124
+ hitW += tw * 0.3;
125
+ }
126
+ }
127
+ if (totalW === 0)
128
+ return 0;
129
+ return Math.min(1, hitW / totalW);
49
130
  }
50
131
  function asText(v) {
51
132
  if (v == null)
@@ -57,30 +138,36 @@ function asText(v) {
57
138
  /**
58
139
  * 单条记忆的关键词命中得分。
59
140
  *
141
+ * 字段权重:content > future_use/tags > evidence/anchors。
142
+ * weak token(CJK 滑窗二元组)命中权重减半,避免「什么/好处」类弱重叠单独过关。
143
+ *
60
144
  * @returns 0 表示无命中;字段权重相加
61
145
  */
62
146
  export function scoreKeywordFields(fields, tokens) {
63
- if (tokens.length === 0)
147
+ const list = Array.isArray(tokens) ? tokens : tokens.all;
148
+ if (list.length === 0)
64
149
  return 0;
150
+ const weakSet = new Set(Array.isArray(tokens) ? [] : tokens.weak);
65
151
  const content = (fields.content ?? '').toLowerCase();
66
152
  const futureUse = (fields.futureUse ?? '').toLowerCase();
67
153
  const tags = asText(fields.tags).toLowerCase();
68
154
  const anchors = asText(fields.anchors).toLowerCase();
69
155
  const evidence = (fields.evidence ?? '').toLowerCase();
70
156
  let score = 0;
71
- for (const token of tokens) {
157
+ for (const token of list) {
72
158
  if (!token)
73
159
  continue;
160
+ const w = weakSet.has(token) ? 0.5 : 1;
74
161
  if (content.includes(token))
75
- score += 3;
162
+ score += 3 * w;
76
163
  if (futureUse.includes(token))
77
- score += 2;
164
+ score += 2 * w;
78
165
  if (tags.includes(token))
79
- score += 2;
166
+ score += 2 * w;
80
167
  if (anchors.includes(token))
81
- score += 1;
168
+ score += 1 * w;
82
169
  if (evidence.includes(token))
83
- score += 1;
170
+ score += 1 * w;
84
171
  }
85
172
  return score;
86
173
  }
@@ -18,6 +18,12 @@ export interface SqliteMemoryStoreOptions {
18
18
  candidateCap?: number;
19
19
  /** 向量引擎;auto=优先 sqlite-vec(需 db 已 load 扩展),否则 JS */
20
20
  vectorEngine?: VectorEngineChoice;
21
+ /** 向量路径默认相关性地板(query.minSimilarity 可覆盖) */
22
+ minSimilarity?: number;
23
+ /** 混合排序相似度权重;其余为 quality */
24
+ similarityWeight?: number;
25
+ /** 关键词路径默认最低命中分 */
26
+ minKeywordScore?: number;
21
27
  }
22
28
  export declare class SqliteMemoryStore implements MemoryStore {
23
29
  readonly name = "sqlite";
@@ -25,6 +31,9 @@ export declare class SqliteMemoryStore implements MemoryStore {
25
31
  private embedding;
26
32
  private readonly candidateCap;
27
33
  private readonly vectorEngine;
34
+ private readonly defaultMinSimilarity;
35
+ private readonly similarityWeight;
36
+ private readonly defaultMinKeywordScore;
28
37
  private vecReady;
29
38
  private embeddingBackfillScheduled;
30
39
  constructor(db: AgentDatabase, options?: SqliteMemoryStoreOptions);
@@ -36,18 +45,23 @@ export declare class SqliteMemoryStore implements MemoryStore {
36
45
  private embedText;
37
46
  retrieve(query: MemoryQuery): Promise<MemoryEntry[]>;
38
47
  private visibilityWhere;
39
- /** sqlite-vec KNN 检索(需先 embed 查询文本) */
48
+ /** sqlite-vec KNN 检索(需先 embed 查询文本);过相关性地板后按混合分排序 */
40
49
  private vecRetrieveAsync;
41
50
  /**
42
- * 混合检索:SQL 预筛候选(避免全表载入 embedding)→ JS 余弦 topK
43
- * candidateCap 默认 500,可通过 SqliteMemoryStoreOptions 覆盖。
51
+ * 混合检索:SQL 预筛候选 → JS 余弦 topK → 相关性地板。
52
+ * 命中不足 limit 时**不**用无关条目填充。
53
+ * @param options.allowKeywordFallback - 仅 embed 硬失败场景允许;默认 false(宁缺)
44
54
  */
45
55
  private hybridRetrieve;
46
56
  private structuredRetrieve;
57
+ /** 单条结构化过滤(向量路径逐条判断) */
58
+ private passesApplyFilters;
47
59
  /** 与 InMemory 对齐:tags 交集过滤 */
48
60
  private filterByTags;
49
61
  private applyFilters;
50
- private sortAndLimit;
62
+ /** 向量命中:similarity 参与排序(禁止仅按 quality 顶掉贴题条目) */
63
+ private sortLimitScored;
64
+ private limitAndUpdate;
51
65
  /**
52
66
  * 回填缺失 embedding(历史数据 / 关键词时代写入)。
53
67
  *