@octopi-agent/engine 0.55.0 → 0.58.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 (105) hide show
  1. package/dist/config-schema/context.d.ts +38 -0
  2. package/dist/config-schema/context.js +39 -0
  3. package/dist/config-schema/engine.d.ts +42 -0
  4. package/dist/config-schema/engine.js +3 -1
  5. package/dist/config-schema/substrate.d.ts +5 -0
  6. package/dist/config-schema/substrate.js +11 -0
  7. package/dist/config.d.ts +44 -0
  8. package/dist/harness/agent/config-bridge.js +3 -0
  9. package/dist/harness/context/capabilities/document/backends/docx.d.ts +7 -0
  10. package/dist/harness/context/capabilities/document/backends/docx.js +67 -0
  11. package/dist/harness/context/capabilities/document/backends/office-parser.d.ts +7 -0
  12. package/dist/harness/context/capabilities/document/backends/office-parser.js +76 -0
  13. package/dist/harness/context/capabilities/document/backends/pdf.d.ts +7 -0
  14. package/dist/harness/context/capabilities/document/backends/pdf.js +86 -0
  15. package/dist/harness/context/capabilities/document/backends/plain.d.ts +7 -0
  16. package/dist/harness/context/capabilities/document/backends/plain.js +42 -0
  17. package/dist/harness/context/capabilities/document/backends/sheet.d.ts +7 -0
  18. package/dist/harness/context/capabilities/document/backends/sheet.js +90 -0
  19. package/dist/harness/context/capabilities/document/backends/xmind.d.ts +20 -0
  20. package/dist/harness/context/capabilities/document/backends/xmind.js +198 -0
  21. package/dist/harness/context/capabilities/document/errors.d.ts +27 -0
  22. package/dist/harness/context/capabilities/document/errors.js +33 -0
  23. package/dist/harness/context/capabilities/document/format.d.ts +38 -0
  24. package/dist/harness/context/capabilities/document/format.js +113 -0
  25. package/dist/harness/context/capabilities/document/html-to-md.d.ts +14 -0
  26. package/dist/harness/context/capabilities/document/html-to-md.js +97 -0
  27. package/dist/harness/context/capabilities/document/index.d.ts +21 -0
  28. package/dist/harness/context/capabilities/document/index.js +20 -0
  29. package/dist/harness/context/capabilities/document/legacy/factory.d.ts +13 -0
  30. package/dist/harness/context/capabilities/document/legacy/factory.js +23 -0
  31. package/dist/harness/context/capabilities/document/legacy/soffice.d.ts +32 -0
  32. package/dist/harness/context/capabilities/document/legacy/soffice.js +186 -0
  33. package/dist/harness/context/capabilities/document/port.d.ts +19 -0
  34. package/dist/harness/context/capabilities/document/port.js +400 -0
  35. package/dist/harness/context/capabilities/document/types.d.ts +149 -0
  36. package/dist/harness/context/capabilities/document/types.js +8 -0
  37. package/dist/harness/context/capabilities/index.d.ts +1 -0
  38. package/dist/harness/context/capabilities/index.js +1 -0
  39. package/dist/harness/context/constitution/default-agents.md +1 -0
  40. package/dist/harness/context/index.d.ts +2 -2
  41. package/dist/harness/context/index.js +1 -1
  42. package/dist/harness/context/layer-types.d.ts +26 -2
  43. package/dist/harness/context/layer-types.js +59 -11
  44. package/dist/harness/context/layers.d.ts +3 -0
  45. package/dist/harness/context/layers.js +38 -12
  46. package/dist/harness/context/system-prompt-assembler.d.ts +5 -0
  47. package/dist/harness/context/system-prompt-assembler.js +2 -0
  48. package/dist/harness/extension/plugin-ecosystem/tools/builtin.d.ts +1 -0
  49. package/dist/harness/extension/plugin-ecosystem/tools/builtin.js +10 -0
  50. package/dist/harness/extension/plugin-ecosystem/tools/document-tools.d.ts +64 -0
  51. package/dist/harness/extension/plugin-ecosystem/tools/document-tools.js +155 -0
  52. package/dist/harness/extension/plugin-ecosystem/tools/index.d.ts +1 -0
  53. package/dist/harness/extension/plugin-ecosystem/tools/index.js +1 -0
  54. package/dist/harness/extension/plugin-ecosystem/tools/knowledge.js +13 -0
  55. package/dist/harness/extension/plugin-ecosystem/tools/memory.js +3 -0
  56. package/dist/harness/extension/plugin-ecosystem/tools/tool-set.d.ts +2 -0
  57. package/dist/harness/extension/plugin-ecosystem/tools/tool-set.js +4 -1
  58. package/dist/harness/index.d.ts +3 -3
  59. package/dist/harness/index.js +2 -2
  60. package/dist/harness/knowledge/catalog-types.d.ts +4 -0
  61. package/dist/harness/knowledge/db.d.ts +4 -0
  62. package/dist/harness/knowledge/db.js +58 -3
  63. package/dist/harness/knowledge/describe.d.ts +2 -0
  64. package/dist/harness/knowledge/describe.js +5 -1
  65. package/dist/harness/knowledge/document-extract-worker.d.ts +1 -0
  66. package/dist/harness/knowledge/document-extract-worker.js +25 -0
  67. package/dist/harness/knowledge/extract-document.d.ts +17 -0
  68. package/dist/harness/knowledge/extract-document.js +62 -0
  69. package/dist/harness/knowledge/index-store.d.ts +49 -5
  70. package/dist/harness/knowledge/index-store.js +240 -32
  71. package/dist/harness/knowledge/index.d.ts +2 -0
  72. package/dist/harness/knowledge/index.js +1 -0
  73. package/dist/harness/knowledge/ingest.d.ts +123 -2
  74. package/dist/harness/knowledge/ingest.js +661 -59
  75. package/dist/harness/knowledge/retriever.d.ts +8 -0
  76. package/dist/harness/knowledge/retriever.js +33 -1
  77. package/dist/harness/knowledge/source-store.d.ts +4 -0
  78. package/dist/harness/knowledge/source-store.js +62 -6
  79. package/dist/harness/knowledge/topics.d.ts +13 -0
  80. package/dist/harness/knowledge/topics.js +48 -0
  81. package/dist/harness/memory/index.d.ts +3 -2
  82. package/dist/harness/memory/index.js +3 -1
  83. package/dist/harness/memory/retrieval-rank.d.ts +51 -0
  84. package/dist/harness/memory/retrieval-rank.js +60 -0
  85. package/dist/harness/memory/sqlite/index.d.ts +2 -2
  86. package/dist/harness/memory/sqlite/index.js +1 -1
  87. package/dist/harness/memory/sqlite/keyword-search.d.ts +20 -2
  88. package/dist/harness/memory/sqlite/keyword-search.js +40 -17
  89. package/dist/harness/memory/sqlite/memory-store.d.ts +18 -4
  90. package/dist/harness/memory/sqlite/memory-store.js +89 -39
  91. package/dist/harness/memory/store.js +39 -21
  92. package/dist/harness/memory/types.d.ts +7 -0
  93. package/dist/harness/run/runner.d.ts +1 -0
  94. package/dist/harness/run/runner.js +4 -2
  95. package/dist/harness/session/attachments/extract.d.ts +3 -2
  96. package/dist/harness/session/attachments/extract.js +19 -6
  97. package/dist/harness/session/attachments/service.d.ts +5 -1
  98. package/dist/harness/session/attachments/service.js +44 -2
  99. package/dist/harness/session/tasks/index.d.ts +1 -1
  100. package/dist/harness/session/tasks/index.js +1 -1
  101. package/dist/harness/session/tasks/render.d.ts +10 -0
  102. package/dist/harness/session/tasks/render.js +27 -0
  103. package/dist/index.d.ts +2 -2
  104. package/dist/index.js +1 -1
  105. package/package.json +8 -3
@@ -12,17 +12,28 @@ import { MEMORY_TYPES } from '../types.js';
12
12
  import { mapLegacyType } from '../gates.js';
13
13
  import { AgentDatabase } from './agent-db.js';
14
14
  import { searchTopK, parseEmbedding, serializeEmbedding } from './vector-search.js';
15
- import { buildKeywordLikeSql, scoreKeywordFields, tokenizeKeywordQuery, } from './keyword-search.js';
15
+ import { buildKeywordLikeSql, scoreKeywordFields, tokenizeKeywordDetail, } from './keyword-search.js';
16
16
  import { deleteMemoryVector, ensureMemoryVecTable, searchMemoryVectors, upsertMemoryVector, } from './sqlite-vec.js';
17
+ import { DEFAULT_MIN_KEYWORD_SCORE, DEFAULT_MIN_SIMILARITY, DEFAULT_SIMILARITY_WEIGHT, blendRank, qualityScore, resolveRetrievalKnobs, } from '../retrieval-rank.js';
17
18
  function emptyTypes() {
18
19
  return { fact: 0, method: 0, norm: 0 };
19
20
  }
21
+ /** text 为空时仍允许的结构过滤浏览(type/tags/channel/status;min* 单独不算) */
22
+ function hasStructuralFilter(query) {
23
+ return (query.type !== undefined ||
24
+ (query.tags?.length ?? 0) > 0 ||
25
+ query.channel !== undefined ||
26
+ query.status !== undefined);
27
+ }
20
28
  export class SqliteMemoryStore {
21
29
  name = 'sqlite';
22
30
  db;
23
31
  embedding;
24
32
  candidateCap;
25
33
  vectorEngine;
34
+ defaultMinSimilarity;
35
+ similarityWeight;
36
+ defaultMinKeywordScore;
26
37
  vecReady = false;
27
38
  embeddingBackfillScheduled = false;
28
39
  constructor(db, options) {
@@ -30,6 +41,9 @@ export class SqliteMemoryStore {
30
41
  this.embedding = options?.embeddingProvider ?? null;
31
42
  this.candidateCap = Math.max(20, options?.candidateCap ?? 500);
32
43
  this.vectorEngine = options?.vectorEngine ?? 'auto';
44
+ this.defaultMinSimilarity = options?.minSimilarity ?? DEFAULT_MIN_SIMILARITY;
45
+ this.similarityWeight = options?.similarityWeight ?? DEFAULT_SIMILARITY_WEIGHT;
46
+ this.defaultMinKeywordScore = options?.minKeywordScore ?? DEFAULT_MIN_KEYWORD_SCORE;
33
47
  if (this.embedding && this.vectorEngine !== 'js') {
34
48
  const dims = this.embedding.dimensions;
35
49
  if (dims > 0 && (db.sqliteVecEnabled || this.vectorEngine === 'sqlite-vec' || this.vectorEngine === 'auto')) {
@@ -103,16 +117,25 @@ export class SqliteMemoryStore {
103
117
  return segments.join(' | ');
104
118
  }
105
119
  async retrieve(query) {
106
- if (this.embedding && query.text.trim()) {
120
+ const knobs = resolveRetrievalKnobs(query.minSimilarity, query.minKeywordScore, this.defaultMinSimilarity, this.defaultMinKeywordScore);
121
+ const q = { ...query, minSimilarity: knobs.minSimilarity, minKeywordScore: knobs.minKeywordScore };
122
+ if (this.embedding && q.text?.trim()) {
107
123
  await this.maybeBackfillEmbeddings();
108
- if (this.vecReady && this.vectorEngine !== 'js') {
109
- const viaVec = await this.vecRetrieveAsync(query);
110
- if (viaVec.length > 0)
111
- return viaVec;
124
+ // embedding 路径:仅在 embed 硬失败时降级关键词;过不了相关性地板则宁缺返回空
125
+ try {
126
+ if (this.vecReady && this.vectorEngine !== 'js') {
127
+ const viaVec = await this.vecRetrieveAsync(q);
128
+ if (viaVec.length > 0)
129
+ return viaVec;
130
+ // vec 命中为空:可能是 vec 表稀疏,继续 hybrid(仍用 embedding);不走关键词填充
131
+ }
132
+ return await this.hybridRetrieve(q, { allowKeywordFallback: false });
133
+ }
134
+ catch {
135
+ return this.structuredRetrieve(q);
112
136
  }
113
- return this.hybridRetrieve(query);
114
137
  }
115
- return this.structuredRetrieve(query);
138
+ return this.structuredRetrieve(q);
116
139
  }
117
140
  visibilityWhere(query) {
118
141
  const params = [];
@@ -130,7 +153,7 @@ export class SqliteMemoryStore {
130
153
  }
131
154
  return { sql, params };
132
155
  }
133
- /** sqlite-vec KNN 检索(需先 embed 查询文本) */
156
+ /** sqlite-vec KNN 检索(需先 embed 查询文本);过相关性地板后按混合分排序 */
134
157
  async vecRetrieveAsync(query) {
135
158
  if (!this.embedding || !this.vecReady)
136
159
  return [];
@@ -143,38 +166,47 @@ export class SqliteMemoryStore {
143
166
  }
144
167
  const vis = this.visibilityWhere(query);
145
168
  const k = Math.max(query.limit ?? 10, 20);
169
+ const minSim = query.minSimilarity ?? this.defaultMinSimilarity;
146
170
  const hits = searchMemoryVectors(this.db.raw, queryVec, k * 3, vis.sql, vis.params);
147
171
  if (hits.length === 0)
148
172
  return [];
149
- const entries = [];
173
+ const scored = [];
150
174
  for (const hit of hits) {
175
+ // vec0 distance_metric=cosine → distance ∈ [0,2],similarity = 1 - distance
176
+ const similarity = 1 - hit.distance;
177
+ if (similarity < minSim)
178
+ continue;
151
179
  const row = this.db.raw.prepare('SELECT * FROM memories WHERE id = ?').get(hit.id);
152
180
  if (!row)
153
181
  continue;
154
- entries.push(this.rowToEntry(row));
155
- if (entries.length >= k)
182
+ const entry = this.rowToEntry(row);
183
+ if (!this.passesApplyFilters(entry, query))
184
+ continue;
185
+ scored.push({ e: entry, similarity });
186
+ if (scored.length >= (query.limit ?? 10) * 2)
156
187
  break;
157
188
  }
158
- const filtered = this.applyFilters(entries, query);
159
- if (filtered.length === 0)
189
+ if (scored.length === 0)
160
190
  return [];
161
- return this.sortAndLimit(filtered, query);
191
+ return this.sortLimitScored(scored, query);
162
192
  }
163
193
  /**
164
- * 混合检索:SQL 预筛候选(避免全表载入 embedding)→ JS 余弦 topK
165
- * candidateCap 默认 500,可通过 SqliteMemoryStoreOptions 覆盖。
194
+ * 混合检索:SQL 预筛候选 → JS 余弦 topK → 相关性地板。
195
+ * 命中不足 limit 时**不**用无关条目填充。
196
+ * @param options.allowKeywordFallback - 仅 embed 硬失败场景允许;默认 false(宁缺)
166
197
  */
167
- async hybridRetrieve(query) {
198
+ async hybridRetrieve(query, options) {
168
199
  let queryVec;
169
200
  try {
170
201
  queryVec = await this.embedding.embed(query.text);
171
202
  }
172
203
  catch {
173
- // embedding 服务不可用:退回关键词(与 vecRetrieve / store 写入路径对称)
204
+ // embedding 服务不可用:仅此时退回关键词
174
205
  return this.structuredRetrieve(query);
175
206
  }
176
207
  const vis = this.visibilityWhere(query);
177
208
  const cap = this.candidateCap;
209
+ const minSim = query.minSimilarity ?? this.defaultMinSimilarity;
178
210
  let sql = `SELECT id, type, content, source, confidence, importance, access_count, last_accessed_at, created_at, decay_factor, tags, embedding, status, channel, future_use, anchors, evidence, deleted, deleted_at, deleted_by, deleted_reason, deleted_meta, reinforced_at
179
211
  FROM memories WHERE embedding IS NOT NULL${vis.sql}`;
180
212
  const params = [...vis.params];
@@ -200,16 +232,20 @@ export class SqliteMemoryStore {
200
232
  return { embedding: emb, item: this.rowToEntry(r) };
201
233
  })
202
234
  .filter((c) => c !== null);
203
- const vectorResults = searchTopK(queryVec, candidates, Math.min(candidates.length, Math.max(50, (query.limit ?? 10) * 5)));
204
- let filtered = this.applyFilters(vectorResults.map(r => r.item), query);
205
- if (filtered.length < (query.limit ?? 10) && candidates.length < cap) {
206
- // 候选池未打满仍不足 → 结构化降级
207
- return this.structuredRetrieve(query);
208
- }
209
- if (filtered.length === 0) {
235
+ // searchTopK 的 maxDistance = 1 - minSimilarity(cosine distance)
236
+ const vectorResults = searchTopK(queryVec, candidates, Math.min(candidates.length, Math.max(50, (query.limit ?? 10) * 5)), 1 - minSim);
237
+ const scored = vectorResults
238
+ .map(r => ({ e: r.item, similarity: 1 - r.distance }))
239
+ .filter(s => s.similarity >= minSim && this.passesApplyFilters(s.e, query));
240
+ // 有相关命中则只返回这些(宁缺毋滥,不回填关键词噪声)
241
+ if (scored.length > 0) {
242
+ return this.sortLimitScored(scored, query);
243
+ }
244
+ // 地板之下零命中:默认不降级关键词,避免「向量说无关、关键词硬填」
245
+ if (options?.allowKeywordFallback) {
210
246
  return this.structuredRetrieve(query);
211
247
  }
212
- return this.sortAndLimit(filtered, query);
248
+ return [];
213
249
  }
214
250
  structuredRetrieve(query) {
215
251
  let sql = 'SELECT * FROM memories WHERE 1=1';
@@ -235,8 +271,8 @@ export class SqliteMemoryStore {
235
271
  sql += ' AND importance >= ?';
236
272
  params.push(query.minImportance);
237
273
  }
238
- const tokens = tokenizeKeywordQuery(query.text);
239
- const like = buildKeywordLikeSql(tokens);
274
+ const tokens = tokenizeKeywordDetail(query.text);
275
+ const like = buildKeywordLikeSql(tokens.all);
240
276
  if (like.sql) {
241
277
  sql += like.sql;
242
278
  params.push(...like.params);
@@ -244,7 +280,8 @@ export class SqliteMemoryStore {
244
280
  const rows = this.db.raw.prepare(sql).all(...params);
245
281
  const entries = rows.map(r => this.rowToEntry(r));
246
282
  const filtered = this.filterByTags(entries, query);
247
- if (tokens.length > 0) {
283
+ const minKeyword = query.minKeywordScore ?? this.defaultMinKeywordScore;
284
+ if (tokens.all.length > 0) {
248
285
  const scored = filtered
249
286
  .map((e) => ({
250
287
  e,
@@ -256,10 +293,10 @@ export class SqliteMemoryStore {
256
293
  evidence: e.evidence,
257
294
  }, tokens),
258
295
  }))
259
- .filter((s) => s.score > 0);
296
+ .filter((s) => s.score >= minKeyword);
260
297
  scored.sort((a, b) => {
261
- const rankA = a.score * 10 + a.e.importance * a.e.confidence * a.e.decayFactor;
262
- const rankB = b.score * 10 + b.e.importance * b.e.confidence * b.e.decayFactor;
298
+ const rankA = a.score * 10 + qualityScore(a.e);
299
+ const rankB = b.score * 10 + qualityScore(b.e);
263
300
  return rankB - rankA;
264
301
  });
265
302
  const limit = query.limit ?? 10;
@@ -273,7 +310,15 @@ export class SqliteMemoryStore {
273
310
  }
274
311
  return Promise.resolve(results);
275
312
  }
276
- return Promise.resolve(this.sortAndLimit(filtered, query));
313
+ // 无检索词:仅结构过滤时浏览;禁止空 query 扫全库
314
+ if (!hasStructuralFilter(query))
315
+ return Promise.resolve([]);
316
+ filtered.sort((a, b) => qualityScore(b) - qualityScore(a));
317
+ return Promise.resolve(this.limitAndUpdate(filtered, query));
318
+ }
319
+ /** 单条结构化过滤(向量路径逐条判断) */
320
+ passesApplyFilters(entry, query) {
321
+ return this.applyFilters([entry], query).length > 0;
277
322
  }
278
323
  /** 与 InMemory 对齐:tags 交集过滤 */
279
324
  filterByTags(entries, query) {
@@ -299,12 +344,17 @@ export class SqliteMemoryStore {
299
344
  }
300
345
  return this.filterByTags(results, query);
301
346
  }
302
- sortAndLimit(entries, query) {
303
- entries.sort((a, b) => {
304
- const scoreA = a.importance * a.confidence * a.decayFactor;
305
- const scoreB = b.importance * b.confidence * b.decayFactor;
306
- return scoreB - scoreA;
347
+ /** 向量命中:similarity 参与排序(禁止仅按 quality 顶掉贴题条目) */
348
+ sortLimitScored(scored, query) {
349
+ const w = this.similarityWeight;
350
+ scored.sort((a, b) => {
351
+ const rankA = blendRank(a.similarity, qualityScore(a.e), w);
352
+ const rankB = blendRank(b.similarity, qualityScore(b.e), w);
353
+ return rankB - rankA;
307
354
  });
355
+ return this.limitAndUpdate(scored.map((s) => s.e), query);
356
+ }
357
+ limitAndUpdate(entries, query) {
308
358
  const limit = query.limit ?? 10;
309
359
  const results = entries.slice(0, limit);
310
360
  if (query.updateAccess !== false) {
@@ -6,10 +6,18 @@
6
6
  import { randomUUID } from 'node:crypto';
7
7
  import { MEMORY_TYPES } from './types.js';
8
8
  import { mapLegacyType } from './gates.js';
9
- import { scoreKeywordFields, tokenizeKeywordQuery, } from './sqlite/keyword-search.js';
9
+ import { scoreKeywordFields, tokenizeKeywordDetail, } from './sqlite/keyword-search.js';
10
+ import { DEFAULT_MIN_KEYWORD_SCORE, qualityScore, resolveRetrievalKnobs, } from './retrieval-rank.js';
10
11
  function emptyTypes() {
11
12
  return { fact: 0, method: 0, norm: 0 };
12
13
  }
14
+ /** 是否带结构过滤(text 为空时仍可按 type/tags/channel/status 浏览;min* 单独不算) */
15
+ function hasStructuralFilter(query) {
16
+ return (query.type !== undefined ||
17
+ (query.tags?.length ?? 0) > 0 ||
18
+ query.channel !== undefined ||
19
+ query.status !== undefined);
20
+ }
13
21
  function normalizeStatus(entry) {
14
22
  return entry.status ?? 'active';
15
23
  }
@@ -48,6 +56,7 @@ export class InMemoryMemoryStore {
48
56
  return id;
49
57
  }
50
58
  async retrieve(query) {
59
+ const { minKeywordScore } = resolveRetrievalKnobs(query.minSimilarity, query.minKeywordScore, undefined, DEFAULT_MIN_KEYWORD_SCORE);
51
60
  let results = Array.from(this.entries.values()).filter((e) => passesVisibility(e, query));
52
61
  if (query.type) {
53
62
  const types = Array.isArray(query.type) ? query.type : [query.type];
@@ -66,28 +75,37 @@ export class InMemoryMemoryStore {
66
75
  if (query.minImportance !== undefined) {
67
76
  results = results.filter((e) => e.importance >= query.minImportance);
68
77
  }
69
- const tokens = tokenizeKeywordQuery(query.text ?? '');
70
- let scored;
71
- if (tokens.length > 0) {
72
- scored = results
73
- .map((e) => ({
74
- e,
75
- score: scoreKeywordFields({
76
- content: e.content,
77
- tags: e.tags,
78
- futureUse: e.futureUse,
79
- anchors: e.anchors,
80
- evidence: e.evidence,
81
- }, tokens),
82
- }))
83
- .filter((s) => s.score > 0);
84
- }
85
- else {
86
- scored = results.map((e) => ({ e, score: 0 }));
78
+ const tokens = tokenizeKeywordDetail(query.text ?? '');
79
+ if (tokens.all.length === 0) {
80
+ // 无检索词:仅在显式结构过滤时浏览;禁止空 query 扫全库
81
+ if (!hasStructuralFilter(query))
82
+ return [];
83
+ results.sort((a, b) => qualityScore(b) - qualityScore(a));
84
+ const limit = query.limit ?? 10;
85
+ results = results.slice(0, limit);
86
+ if (query.updateAccess !== false) {
87
+ for (const entry of results) {
88
+ entry.accessCount++;
89
+ entry.lastAccessedAt = Date.now();
90
+ }
91
+ }
92
+ return results;
87
93
  }
94
+ const scored = results
95
+ .map((e) => ({
96
+ e,
97
+ score: scoreKeywordFields({
98
+ content: e.content,
99
+ tags: e.tags,
100
+ futureUse: e.futureUse,
101
+ anchors: e.anchors,
102
+ evidence: e.evidence,
103
+ }, tokens),
104
+ }))
105
+ .filter((s) => s.score >= minKeywordScore);
88
106
  scored.sort((a, b) => {
89
- const rankA = a.score * 10 + a.e.importance * a.e.confidence * a.e.decayFactor;
90
- const rankB = b.score * 10 + b.e.importance * b.e.confidence * b.e.decayFactor;
107
+ const rankA = a.score * 10 + qualityScore(a.e);
108
+ const rankB = b.score * 10 + qualityScore(b.e);
91
109
  return rankB - rankA;
92
110
  });
93
111
  const limit = query.limit ?? 10;
@@ -66,6 +66,13 @@ export interface MemoryQuery {
66
66
  includeDeleted?: boolean;
67
67
  status?: MemoryStatus | MemoryStatus[];
68
68
  channel?: MemoryChannel | MemoryChannel[];
69
+ /**
70
+ * 向量路径最低余弦相似度;低于则丢弃(宁缺毋滥)。
71
+ * 未写出时用 store 默认(注入路径偏严,search 可放宽为 0)。
72
+ */
73
+ minSimilarity?: number;
74
+ /** 关键词路径最低命中分;未写出时用 store 默认 */
75
+ minKeywordScore?: number;
69
76
  }
70
77
  /** 记忆统计 */
71
78
  export interface MemoryStats {
@@ -248,6 +248,7 @@ export declare class SessionAwareRunner {
248
248
  persona: string;
249
249
  injectedContext?: string;
250
250
  contextWindow?: number;
251
+ topicHints?: string;
251
252
  signal?: AbortSignal;
252
253
  }) => Promise<{
253
254
  systemPrompt: string;
@@ -14,7 +14,7 @@ import { createSessionStateMachine } from '../session/state-machine.js';
14
14
  import { HeuristicTokenEstimator } from '../context/index.js';
15
15
  import { extractLayerQuery } from '../context/layer-types.js';
16
16
  import { withRuntimeEnvironmentInjection } from '../context/runtime-datetime.js';
17
- import { renderSessionTasksInjection } from '../session/tasks/render.js';
17
+ import { extractTaskQueryHints, renderSessionTasksInjection } from '../session/tasks/render.js';
18
18
  import { createRunId } from './run-scope.js';
19
19
  import { DEFAULT_TOOL_ISOLATION, resolveToolIsolationCwd, } from '../extension/execution-environment/isolation.js';
20
20
  import { mkdirSync } from 'node:fs';
@@ -602,6 +602,7 @@ export class SessionAwareRunner {
602
602
  // 结果只写入 runContext / RunScope,不作为「Agent 当前会话状态」
603
603
  if (this.systemPromptAssembler) {
604
604
  try {
605
+ const topicHints = extractTaskQueryHints(session.tasks ?? []);
605
606
  const assembled = await this.systemPromptAssembler({
606
607
  sessionId,
607
608
  agentId: _agentId,
@@ -609,6 +610,7 @@ export class SessionAwareRunner {
609
610
  persona: basePrompt,
610
611
  injectedContext: effectiveRunConfig.injectedContext,
611
612
  contextWindow: effectiveRunConfig.contextWindow,
613
+ topicHints,
612
614
  signal,
613
615
  });
614
616
  runContext.systemPrompt = assembled.systemPrompt;
@@ -624,7 +626,7 @@ export class SessionAwareRunner {
624
626
  agentId: _agentId,
625
627
  manifest: assembled.manifest,
626
628
  enabledLayerIds: assembled.manifest.layers.map((l) => l.id),
627
- query: extractLayerQuery(session.messages),
629
+ query: extractLayerQuery(session.messages, { topicHints }),
628
630
  assembledAt,
629
631
  },
630
632
  });
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * 附件抽取 — 生成可读伴生文本(.extracted.md)
3
3
  *
4
- * 本期:文本类直接可读(extractPath = path);PDF/Office 无 adapter 不抽取。
4
+ * 文本类直接可读(extractPath = path);PDF/Office 经 DocumentPort 抽取写伴生文件。
5
5
  * 归属:Session 资产侧,不进 Knowledge ingest(要检索再升 source)。
6
6
  */
7
7
  import type { AttachmentKind } from './types.js';
@@ -28,8 +28,9 @@ export declare function extractText(data: Buffer, name: string, kind: Attachment
28
28
  chars: number;
29
29
  } | null;
30
30
  /**
31
- * 伴生抽取文件名(原件旁)
31
+ * 伴生抽取文件名(原件旁);保留源扩展名避免 foo.pdf / foo.docx 撞名
32
32
  *
33
33
  * @param fileName - 原件相对名
34
+ * @returns 例如 report.pdf → report.pdf.extracted.md
34
35
  */
35
36
  export declare function extractCompanionName(fileName: string): string;
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * 附件抽取 — 生成可读伴生文本(.extracted.md)
3
3
  *
4
- * 本期:文本类直接可读(extractPath = path);PDF/Office 无 adapter 不抽取。
4
+ * 文本类直接可读(extractPath = path);PDF/Office 经 DocumentPort 抽取写伴生文件。
5
5
  * 归属:Session 资产侧,不进 Knowledge ingest(要检索再升 source)。
6
6
  */
7
7
  import { extname } from 'node:path';
@@ -28,8 +28,22 @@ export function classifyAttachmentKind(name) {
28
28
  return 'code';
29
29
  if (TEXT_EXTENSIONS.has(ext))
30
30
  return 'text';
31
- if (ext === '.pdf' || ext === '.docx' || ext === '.xlsx' || ext === '.pptx')
31
+ if (ext === '.pdf' ||
32
+ ext === '.docx' ||
33
+ ext === '.xlsx' ||
34
+ ext === '.pptx' ||
35
+ ext === '.doc' ||
36
+ ext === '.xls' ||
37
+ ext === '.ppt' ||
38
+ ext === '.rtf' ||
39
+ ext === '.odt' ||
40
+ ext === '.ods' ||
41
+ ext === '.odp' ||
42
+ ext === '.odg' ||
43
+ ext === '.epub' ||
44
+ ext === '.xmind') {
32
45
  return 'document';
46
+ }
33
47
  return 'other';
34
48
  }
35
49
  /**
@@ -61,12 +75,11 @@ export function extractText(data, name, kind) {
61
75
  return { text, chars: text.length };
62
76
  }
63
77
  /**
64
- * 伴生抽取文件名(原件旁)
78
+ * 伴生抽取文件名(原件旁);保留源扩展名避免 foo.pdf / foo.docx 撞名
65
79
  *
66
80
  * @param fileName - 原件相对名
81
+ * @returns 例如 report.pdf → report.pdf.extracted.md
67
82
  */
68
83
  export function extractCompanionName(fileName) {
69
- const ext = extname(fileName);
70
- const stem = ext ? fileName.slice(0, -ext.length) : fileName;
71
- return `${stem}.extracted.md`;
84
+ return `${fileName}.extracted.md`;
72
85
  }
@@ -6,16 +6,20 @@
6
6
  * 原则:原件 + .manifest.json 为权威;抽取/索引可重建。
7
7
  */
8
8
  import { type AttachmentLimits, type AttachmentUploadInput, type SessionAttachment } from './types.js';
9
+ import type { DocumentPort } from '../../context/capabilities/document/types.js';
9
10
  export interface SessionAttachmentServiceOptions {
10
11
  /** 通常 `OCTOPI_HOME/sessions` */
11
12
  sessionsDir: string;
12
13
  limits?: Partial<AttachmentLimits>;
14
+ /** DocumentPort:PDF/Office 抽取伴生 `.extracted.md`;缺省不抽 */
15
+ documentPort?: DocumentPort | null;
13
16
  }
14
17
  export declare class SessionAttachmentService {
15
18
  private readonly sessionsDir;
16
19
  private readonly limits;
20
+ private readonly documentPort;
17
21
  /**
18
- * @param options - sessionsDir + 可选限额覆盖
22
+ * @param options - sessionsDir + 可选限额覆盖 + documentPort
19
23
  */
20
24
  constructor(options: SessionAttachmentServiceOptions);
21
25
  get limitsConfig(): AttachmentLimits;
@@ -11,16 +11,19 @@ import { mkdir, rename, rm, writeFile } from 'node:fs/promises';
11
11
  import { join } from 'node:path';
12
12
  import { resolveSessionAttachmentsPaths } from './paths.js';
13
13
  import { attachmentExtension, isPathInside, sanitizeAttachmentName } from './sanitize.js';
14
- import { classifyAttachmentKind, extractText, isPlainReadable, } from './extract.js';
14
+ import { classifyAttachmentKind, extractCompanionName, extractText, isPlainReadable, } from './extract.js';
15
15
  import { DEFAULT_ATTACHMENT_LIMITS, } from './types.js';
16
+ import { isDocumentExtractError } from '../../context/capabilities/document/errors.js';
16
17
  export class SessionAttachmentService {
17
18
  sessionsDir;
18
19
  limits;
20
+ documentPort;
19
21
  /**
20
- * @param options - sessionsDir + 可选限额覆盖
22
+ * @param options - sessionsDir + 可选限额覆盖 + documentPort
21
23
  */
22
24
  constructor(options) {
23
25
  this.sessionsDir = options.sessionsDir;
26
+ this.documentPort = options.documentPort ?? null;
24
27
  // 只合并已定义字段:`{ ...defaults, allowedExtensions: undefined }` 会把默认值抹掉
25
28
  const o = options.limits ?? {};
26
29
  this.limits = {
@@ -134,9 +137,48 @@ export class SessionAttachmentService {
134
137
  item.parse = { ok: false, error: 'binary content in text extension' };
135
138
  }
136
139
  }
140
+ else if (kind === 'document' && this.documentPort) {
141
+ const companion = extractCompanionName(uniqueName);
142
+ item.extractPath = companion;
143
+ try {
144
+ const result = await this.documentPort.extract({
145
+ data: new Uint8Array(data),
146
+ name: uniqueName,
147
+ });
148
+ const absExtract = join(root, companion);
149
+ if (!isPathInside(root, absExtract)) {
150
+ throw new Error('invalid extract path');
151
+ }
152
+ await writeFile(absExtract, result.markdown);
153
+ item.status = 'parsed';
154
+ item.parse = { ok: true, chars: result.markdown.length };
155
+ }
156
+ catch (err) {
157
+ item.status = 'parse_failed';
158
+ if (isDocumentExtractError(err)) {
159
+ item.parse = {
160
+ ok: false,
161
+ error: `${err.code}${err.requires ? ` (requires: ${err.requires.join(',')})` : ''}`,
162
+ };
163
+ }
164
+ else {
165
+ item.parse = {
166
+ ok: false,
167
+ error: err instanceof Error ? err.message : String(err),
168
+ };
169
+ }
170
+ }
171
+ }
137
172
  else if (kind === 'image') {
138
173
  item.status = 'ready';
139
174
  }
175
+ else if (kind === 'document') {
176
+ item.status = 'ready';
177
+ item.parse = {
178
+ ok: false,
179
+ error: 'document extract disabled (no DocumentPort)',
180
+ };
181
+ }
140
182
  else {
141
183
  item.status = 'ready';
142
184
  item.parse = { ok: false, error: 'no extractor for this type (see OP adapter)' };
@@ -7,5 +7,5 @@ export type { SessionTask, SessionTaskStatus, SessionTaskEventType } from './typ
7
7
  export { ACTIVE_SESSION_TASK_STATUSES } from './types.js';
8
8
  export { SessionTaskService } from './service.js';
9
9
  export type { SessionTaskListFilter, SessionTaskCommandActor } from './service.js';
10
- export { renderSessionTasksInjection } from './render.js';
10
+ export { renderSessionTasksInjection, extractTaskQueryHints } from './render.js';
11
11
  export { createSessionTaskTools, createTaskListTool, createTaskCreateTool, createTaskPlanTool, createTaskCompleteTool, createTaskPauseTool, createTaskResumeTool, createTaskDropTool, createTaskNoteTool, } from './tools.js';
@@ -5,5 +5,5 @@
5
5
  */
6
6
  export { ACTIVE_SESSION_TASK_STATUSES } from './types.js';
7
7
  export { SessionTaskService } from './service.js';
8
- export { renderSessionTasksInjection } from './render.js';
8
+ export { renderSessionTasksInjection, extractTaskQueryHints } from './render.js';
9
9
  export { createSessionTaskTools, createTaskListTool, createTaskCreateTool, createTaskPlanTool, createTaskCompleteTool, createTaskPauseTool, createTaskResumeTool, createTaskDropTool, createTaskNoteTool, } from './tools.js';
@@ -10,3 +10,13 @@ import type { SessionTask } from './types.js';
10
10
  * @returns 注入字符串;无活跃 goal 时返回空串
11
11
  */
12
12
  export declare function renderSessionTasksInjection(tasks: SessionTask[]): string;
13
+ /**
14
+ * 从会话任务提取检索主题线索(Memory/Cognition 层 query 用)。
15
+ *
16
+ * 取未闭合 goal 描述 + 当前 open step,压缩为一行,避免注入全文。
17
+ *
18
+ * @param tasks - 会话全部任务
19
+ * @param maxChars - 线索字符上限(默认 240)
20
+ * @returns 单行主题线索;无活跃任务时空串
21
+ */
22
+ export declare function extractTaskQueryHints(tasks: SessionTask[], maxChars?: number): string;
@@ -55,3 +55,30 @@ export function renderSessionTasksInjection(tasks) {
55
55
  lines.push('</session_tasks>');
56
56
  return lines.join('\n');
57
57
  }
58
+ /**
59
+ * 从会话任务提取检索主题线索(Memory/Cognition 层 query 用)。
60
+ *
61
+ * 取未闭合 goal 描述 + 当前 open step,压缩为一行,避免注入全文。
62
+ *
63
+ * @param tasks - 会话全部任务
64
+ * @param maxChars - 线索字符上限(默认 240)
65
+ * @returns 单行主题线索;无活跃任务时空串
66
+ */
67
+ export function extractTaskQueryHints(tasks, maxChars = 240) {
68
+ const goals = tasks
69
+ .filter((t) => !t.parentId && isActive(t.status))
70
+ .sort((a, b) => a.createdAt - b.createdAt);
71
+ if (goals.length === 0)
72
+ return '';
73
+ const parts = [];
74
+ for (const goal of goals.slice(0, 3)) {
75
+ parts.push(goal.description.trim());
76
+ const currentStep = tasks
77
+ .filter((t) => t.parentId === goal.id && t.status === 'open')
78
+ .sort((a, b) => (a.order ?? 0) - (b.order ?? 0))[0];
79
+ if (currentStep?.description) {
80
+ parts.push(currentStep.description.trim());
81
+ }
82
+ }
83
+ return parts.filter(Boolean).join(';').slice(0, maxChars);
84
+ }
package/dist/index.d.ts CHANGED
@@ -71,8 +71,8 @@ export type { AgentPersona, ModelConfig, AgentDefinition } from './harness/share
71
71
  export { DefaultToolBus } from './harness/extension/plugin-ecosystem/tools/tool-bus.js';
72
72
  export { getBuiltinTools, createShellTool, createFileReadTool, createFileWriteTool, createFileListTool } from './harness/extension/plugin-ecosystem/tools/builtin.js';
73
73
  export { createToolSet } from './harness/extension/plugin-ecosystem/tools/tool-set.js';
74
- export { createSummaryPort, applyToolOutputGate, createCompactEngine } from './harness/context/capabilities/index.js';
75
- export type { SummaryPort, SummaryPolicy, ContentUnit, ToolSummarySupport, CompactEngine } from './harness/context/capabilities/index.js';
74
+ export { createSummaryPort, applyToolOutputGate, createCompactEngine, createDefaultDocumentPort, DocumentExtractError } from './harness/context/capabilities/index.js';
75
+ export type { SummaryPort, SummaryPolicy, ContentUnit, ToolSummarySupport, CompactEngine, DocumentPort, ExtractResult, ExtractSource } from './harness/context/capabilities/index.js';
76
76
  export type { ToolSet, ToolSetConfig } from './harness/extension/plugin-ecosystem/tools/tool-set.js';
77
77
  export { createWebSearchTool } from './harness/extension/plugin-ecosystem/tools/web-search.js';
78
78
  export type { WebSearchToolOptions } from './harness/extension/plugin-ecosystem/tools/web-search.js';
package/dist/index.js CHANGED
@@ -47,7 +47,7 @@ export { DefaultSkillManager, FileSystemSkillSource } from './harness/extension/
47
47
  export { DefaultToolBus } from './harness/extension/plugin-ecosystem/tools/tool-bus.js';
48
48
  export { getBuiltinTools, createShellTool, createFileReadTool, createFileWriteTool, createFileListTool } from './harness/extension/plugin-ecosystem/tools/builtin.js';
49
49
  export { createToolSet } from './harness/extension/plugin-ecosystem/tools/tool-set.js';
50
- export { createSummaryPort, applyToolOutputGate, createCompactEngine } from './harness/context/capabilities/index.js';
50
+ export { createSummaryPort, applyToolOutputGate, createCompactEngine, createDefaultDocumentPort, DocumentExtractError } from './harness/context/capabilities/index.js';
51
51
  export { createWebSearchTool } from './harness/extension/plugin-ecosystem/tools/web-search.js';
52
52
  export { createSessionHistoryPort, resolveHistoryAccess, } from './harness/session/history/index.js';
53
53
  export { createSessionHistoryTools, createSessionSearchTool, createSessionReadTool, } from './harness/extension/plugin-ecosystem/tools/session-history.js';