@octopi-agent/engine 0.58.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 (142) 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 +38 -1
  4. package/dist/config-schema/substrate.d.ts +37 -0
  5. package/dist/config-schema/substrate.js +47 -0
  6. package/dist/config.d.ts +30 -1
  7. package/dist/harness/agent/builder.d.ts +14 -0
  8. package/dist/harness/agent/builder.js +14 -2
  9. package/dist/harness/{context/capabilities → capabilities}/document/backends/docx.d.ts +1 -1
  10. package/dist/harness/{context/capabilities → capabilities}/document/backends/docx.js +1 -1
  11. package/dist/harness/{context/capabilities → capabilities}/document/backends/office-parser.d.ts +1 -1
  12. package/dist/harness/{context/capabilities → capabilities}/document/backends/office-parser.js +1 -1
  13. package/dist/harness/{context/capabilities → capabilities}/document/backends/pdf.d.ts +1 -1
  14. package/dist/harness/{context/capabilities → capabilities}/document/backends/pdf.js +13 -3
  15. package/dist/harness/{context/capabilities → capabilities}/document/backends/plain.d.ts +1 -1
  16. package/dist/harness/{context/capabilities → capabilities}/document/backends/plain.js +13 -4
  17. package/dist/harness/{context/capabilities → capabilities}/document/backends/sheet.d.ts +1 -1
  18. package/dist/harness/{context/capabilities → capabilities}/document/backends/sheet.js +25 -5
  19. package/dist/harness/{context/capabilities → capabilities}/document/backends/xmind.d.ts +1 -1
  20. package/dist/harness/{context/capabilities → capabilities}/document/backends/xmind.js +1 -1
  21. package/dist/harness/{context/capabilities → capabilities}/document/errors.d.ts +1 -1
  22. package/dist/harness/{context/capabilities → capabilities}/document/errors.js +1 -1
  23. package/dist/harness/capabilities/document/factory.d.ts +33 -0
  24. package/dist/harness/capabilities/document/factory.js +37 -0
  25. package/dist/harness/{context/capabilities → capabilities}/document/format.d.ts +1 -1
  26. package/dist/harness/{context/capabilities → capabilities}/document/format.js +1 -1
  27. package/dist/harness/{context/capabilities → capabilities}/document/html-to-md.d.ts +1 -1
  28. package/dist/harness/{context/capabilities → capabilities}/document/html-to-md.js +1 -1
  29. package/dist/harness/{context/capabilities → capabilities}/document/index.d.ts +3 -1
  30. package/dist/harness/{context/capabilities → capabilities}/document/index.js +2 -1
  31. package/dist/harness/{context/capabilities → capabilities}/document/legacy/factory.d.ts +3 -1
  32. package/dist/harness/{context/capabilities → capabilities}/document/legacy/factory.js +3 -1
  33. package/dist/harness/{context/capabilities → capabilities}/document/legacy/soffice.d.ts +3 -1
  34. package/dist/harness/{context/capabilities → capabilities}/document/legacy/soffice.js +44 -1
  35. package/dist/harness/{context/capabilities → capabilities}/document/port.d.ts +1 -1
  36. package/dist/harness/{context/capabilities → capabilities}/document/port.js +4 -4
  37. package/dist/harness/{context/capabilities → capabilities}/document/types.d.ts +11 -1
  38. package/dist/harness/{context/capabilities → capabilities}/document/types.js +1 -1
  39. package/dist/harness/capabilities/document/worker-port.d.ts +13 -0
  40. package/dist/harness/capabilities/document/worker-port.js +78 -0
  41. package/dist/harness/context/capabilities/index.d.ts +2 -2
  42. package/dist/harness/context/capabilities/index.js +2 -2
  43. package/dist/harness/extension/plugin-ecosystem/tools/knowledge.d.ts +10 -0
  44. package/dist/harness/extension/plugin-ecosystem/tools/knowledge.js +102 -5
  45. package/dist/harness/index.d.ts +4 -2
  46. package/dist/harness/index.js +2 -1
  47. package/dist/harness/knowledge/adapters.d.ts +8 -5
  48. package/dist/harness/knowledge/adapters.js +53 -13
  49. package/dist/harness/knowledge/client.d.ts +197 -0
  50. package/dist/harness/knowledge/client.js +237 -0
  51. package/dist/harness/knowledge/connector-fetcher.d.ts +2 -2
  52. package/dist/harness/knowledge/connectors.d.ts +3 -3
  53. package/dist/harness/knowledge/connectors.js +14 -8
  54. package/dist/harness/knowledge/db.d.ts +40 -5
  55. package/dist/harness/knowledge/db.js +441 -113
  56. package/dist/harness/knowledge/document-extract-worker.js +55 -12
  57. package/dist/harness/knowledge/embed-runner.d.ts +53 -0
  58. package/dist/harness/knowledge/embed-runner.js +171 -0
  59. package/dist/harness/knowledge/engine-thread.d.ts +1 -0
  60. package/dist/harness/knowledge/engine-thread.js +302 -0
  61. package/dist/harness/knowledge/extract-document.d.ts +21 -5
  62. package/dist/harness/knowledge/extract-document.js +32 -8
  63. package/dist/harness/knowledge/fetchers.d.ts +14 -3
  64. package/dist/harness/knowledge/fetchers.js +52 -16
  65. package/dist/harness/knowledge/file-identity.d.ts +53 -0
  66. package/dist/harness/knowledge/file-identity.js +172 -0
  67. package/dist/harness/knowledge/file-index-store.d.ts +50 -0
  68. package/dist/harness/knowledge/file-index-store.js +132 -0
  69. package/dist/harness/knowledge/file-limits.d.ts +86 -0
  70. package/dist/harness/knowledge/file-limits.js +175 -0
  71. package/dist/harness/knowledge/fts.d.ts +60 -0
  72. package/dist/harness/knowledge/fts.js +218 -0
  73. package/dist/harness/knowledge/grounding.d.ts +3 -2
  74. package/dist/harness/knowledge/http-app.d.ts +50 -0
  75. package/dist/harness/knowledge/http-app.js +652 -0
  76. package/dist/harness/knowledge/http-bridge.d.ts +49 -0
  77. package/dist/harness/knowledge/http-bridge.js +17 -0
  78. package/dist/harness/knowledge/index-store.d.ts +158 -93
  79. package/dist/harness/knowledge/index-store.js +982 -441
  80. package/dist/harness/knowledge/index.d.ts +45 -5
  81. package/dist/harness/knowledge/index.js +23 -2
  82. package/dist/harness/knowledge/ingest.d.ts +262 -87
  83. package/dist/harness/knowledge/ingest.js +1072 -480
  84. package/dist/harness/knowledge/job-control-state.d.ts +29 -0
  85. package/dist/harness/knowledge/job-control-state.js +44 -0
  86. package/dist/harness/knowledge/job-control.d.ts +35 -0
  87. package/dist/harness/knowledge/job-control.js +86 -0
  88. package/dist/harness/knowledge/job-queue.d.ts +62 -0
  89. package/dist/harness/knowledge/job-queue.js +173 -0
  90. package/dist/harness/knowledge/knowledge-serve-child.d.ts +1 -0
  91. package/dist/harness/knowledge/knowledge-serve-child.js +100 -0
  92. package/dist/harness/knowledge/local-stack.d.ts +27 -0
  93. package/dist/harness/knowledge/local-stack.js +63 -0
  94. package/dist/harness/knowledge/membership-store.d.ts +65 -0
  95. package/dist/harness/knowledge/membership-store.js +198 -0
  96. package/dist/harness/knowledge/network-guard.d.ts +11 -2
  97. package/dist/harness/knowledge/network-guard.js +130 -85
  98. package/dist/harness/knowledge/parse-text-in-worker.d.ts +32 -0
  99. package/dist/harness/knowledge/parse-text-in-worker.js +158 -0
  100. package/dist/harness/knowledge/query-service.d.ts +272 -0
  101. package/dist/harness/knowledge/query-service.js +326 -0
  102. package/dist/harness/knowledge/query-worker-client.d.ts +96 -0
  103. package/dist/harness/knowledge/query-worker-client.js +207 -0
  104. package/dist/harness/knowledge/query-worker.d.ts +1 -0
  105. package/dist/harness/knowledge/query-worker.js +186 -0
  106. package/dist/harness/knowledge/read-http.d.ts +35 -0
  107. package/dist/harness/knowledge/read-http.js +373 -0
  108. package/dist/harness/knowledge/retriever.d.ts +22 -5
  109. package/dist/harness/knowledge/retriever.js +66 -35
  110. package/dist/harness/knowledge/secret-scan.d.ts +13 -2
  111. package/dist/harness/knowledge/secret-scan.js +25 -2
  112. package/dist/harness/knowledge/serve.d.ts +48 -0
  113. package/dist/harness/knowledge/serve.js +336 -0
  114. package/dist/harness/knowledge/source-store.d.ts +80 -17
  115. package/dist/harness/knowledge/source-store.js +160 -89
  116. package/dist/harness/knowledge/start-service-process.d.ts +49 -0
  117. package/dist/harness/knowledge/start-service-process.js +158 -0
  118. package/dist/harness/knowledge/text-parse-worker.d.ts +1 -0
  119. package/dist/harness/knowledge/text-parse-worker.js +54 -0
  120. package/dist/harness/knowledge/types.d.ts +1 -1
  121. package/dist/harness/knowledge/types.js +1 -1
  122. package/dist/harness/knowledge/vector-ann.d.ts +42 -0
  123. package/dist/harness/knowledge/vector-ann.js +68 -0
  124. package/dist/harness/knowledge/writer-lock.d.ts +13 -0
  125. package/dist/harness/knowledge/writer-lock.js +71 -0
  126. package/dist/harness/knowledge/writer-service.d.ts +194 -0
  127. package/dist/harness/knowledge/writer-service.js +355 -0
  128. package/dist/harness/knowledge/writer-worker-client.d.ts +102 -0
  129. package/dist/harness/knowledge/writer-worker-client.js +381 -0
  130. package/dist/harness/knowledge/writer-worker.d.ts +1 -0
  131. package/dist/harness/knowledge/writer-worker.js +189 -0
  132. package/dist/harness/memory/sqlite/embedding.d.ts +5 -2
  133. package/dist/harness/memory/sqlite/embedding.js +109 -16
  134. package/dist/harness/memory/sqlite/keyword-search.d.ts +21 -0
  135. package/dist/harness/memory/sqlite/keyword-search.js +64 -0
  136. package/dist/harness/session/attachments/service.d.ts +1 -1
  137. package/dist/harness/session/attachments/service.js +1 -1
  138. package/dist/index.d.ts +4 -2
  139. package/dist/index.js +2 -1
  140. package/dist/worker-path.d.ts +8 -0
  141. package/dist/worker-path.js +15 -0
  142. package/package.json +2 -2
@@ -0,0 +1,49 @@
1
+ /**
2
+ * HTTP 桥 — 主线程 ↔ Engine Worker 的请求/响应 DTO
3
+ *
4
+ * 主线程不得跑 Knowledge 业务/SQLite;只转发,保证 /health 在引擎忙时仍可答。
5
+ */
6
+ export interface KnowledgeTokenInfo {
7
+ token: string;
8
+ tenantId: string;
9
+ gatewayId: string;
10
+ }
11
+ /**
12
+ * Token → (tenant, gateway)。主线程 401 快速拒绝 + Engine 再验(同一实现)。
13
+ */
14
+ export declare function matchKnowledgeToken(tokens: readonly KnowledgeTokenInfo[], authorizationHeader: string | string[] | undefined): KnowledgeTokenInfo | null;
15
+ export interface HttpBridgeRequest {
16
+ method: string;
17
+ url: string;
18
+ headers: Record<string, string | string[] | undefined>;
19
+ /** utf8;GET/HEAD 为空 */
20
+ body?: string;
21
+ }
22
+ export type HttpBridgeOutbound = {
23
+ type: 'end';
24
+ status: number;
25
+ headers: Record<string, string | number | string[]>;
26
+ body: string;
27
+ } | {
28
+ type: 'sse-start';
29
+ status: number;
30
+ headers: Record<string, string | number | string[]>;
31
+ } | {
32
+ type: 'sse-write';
33
+ chunk: string;
34
+ } | {
35
+ type: 'sse-end';
36
+ };
37
+ export interface HttpBridgeWorkerInbound {
38
+ id: number;
39
+ type: 'http';
40
+ req: HttpBridgeRequest;
41
+ }
42
+ export interface HttpBridgeWorkerReady {
43
+ type: 'ready';
44
+ portHint?: number;
45
+ }
46
+ export interface HttpBridgeWorkerError {
47
+ type: 'error';
48
+ message: string;
49
+ }
@@ -0,0 +1,17 @@
1
+ /**
2
+ * HTTP 桥 — 主线程 ↔ Engine Worker 的请求/响应 DTO
3
+ *
4
+ * 主线程不得跑 Knowledge 业务/SQLite;只转发,保证 /health 在引擎忙时仍可答。
5
+ */
6
+ /**
7
+ * Token → (tenant, gateway)。主线程 401 快速拒绝 + Engine 再验(同一实现)。
8
+ */
9
+ export function matchKnowledgeToken(tokens, authorizationHeader) {
10
+ const header = Array.isArray(authorizationHeader)
11
+ ? authorizationHeader[0]
12
+ : authorizationHeader;
13
+ if (!header || !header.startsWith('Bearer '))
14
+ return null;
15
+ const token = header.slice('Bearer '.length).trim();
16
+ return tokens.find((t) => t.token === token) ?? null;
17
+ }
@@ -1,7 +1,8 @@
1
1
  /**
2
- * KnowledgeIndexStore — files / chunks 投影 + 关键词检索(Phase A)
2
+ * KnowledgeIndexStore — File 本位索引投影
3
3
  *
4
- * Index 非权威;可整库重跑。检索用 Memory 同款 CJK 二元组分词。
4
+ * chunk/file 挂 file_id;logical path 在 Membership。
5
+ * sourceId+path 的 API 保留为「Membership 视图」,内部按 identity 去重。
5
6
  */
6
7
  import { KnowledgeDatabase } from './db.js';
7
8
  import type { KnowledgeChunkId, KnowledgeSourceId } from './types.js';
@@ -14,7 +15,7 @@ export interface IndexedFileRecord {
14
15
  size: number;
15
16
  mtime: number;
16
17
  adapterId: string | null;
17
- status: 'indexed' | 'skipped' | 'error';
18
+ status: 'indexed' | 'indexing' | 'skipped' | 'error';
18
19
  error?: string;
19
20
  chunkCount: number;
20
21
  indexedAt: number;
@@ -31,12 +32,47 @@ export interface ChunkHit {
31
32
  startLine: number;
32
33
  endLine: number;
33
34
  score: number;
35
+ /** 共享 File 的全部可见绑定 */
36
+ sourceIds?: string[];
37
+ /** sourceId → logical path */
38
+ logicalPaths?: Record<string, string>;
34
39
  }
35
40
  export declare class KnowledgeIndexStore {
36
41
  private readonly db;
42
+ private readonly fts;
43
+ private ftsBackfillPromise;
44
+ private vecTableReady;
45
+ /** 同 File 写序(upsert ∥ purge):键 = identity_key */
46
+ private readonly writeLocks;
47
+ /** 大库 COUNT 短 TTL:UI 轮询 / jobControl 不必每请求全表 JOIN */
48
+ private readonly statsCache;
49
+ private static readonly STATS_TTL_MS;
37
50
  constructor(db: KnowledgeDatabase);
51
+ private cached;
52
+ /** 写路径后立刻让统计可见(收尾 force 也可走此绕过 TTL) */
53
+ invalidateStatsCache(): void;
38
54
  /**
39
- * 写入/替换某文件的 chunks(幂等:先删旧 chunk 与向量)
55
+ * 按 File identity 串行写(upsert / purge)。
56
+ * purge 在 dropChunks 让出窗口内与 upsert 交错会留下孤儿 FTS / 悬空 membership。
57
+ */
58
+ private withFileWriteLock;
59
+ get ftsAvailable(): boolean;
60
+ get ftsBackfillRunning(): boolean;
61
+ ensureFtsBackfill(): Promise<number>;
62
+ /** 解析或创建 File(identity 去重)+ Membership */
63
+ private resolveFile;
64
+ /** 按 identity_key 查已有 File(不建行);供 job 入队绑定 file_id */
65
+ findFileIdByIdentity(identityKey: string, tenantId?: string): string | null;
66
+ /** 只挂 Membership(共享 File:已有 parse 在途时补认领,禁止双 parse) */
67
+ attachMembership(sourceId: string, fileId: string, path: string): void;
68
+ /**
69
+ * 替换文件索引。chunk/FTS **分批**写入并让出事件循环,
70
+ * 大 xlsx 数千 chunk 不得整文件一个同步事务堵死 Service。
71
+ *
72
+ * 语义:旧 chunk 先清;`status='indexing'` 直到全部批次落库后才 `indexed`。
73
+ * 检索不认 `indexing`(半成品)。批次失败/中止会清掉 partial chunks,
74
+ * 并留在 `indexing`(chunk_count=0)供 gap 扫描重试——不得把半成品标成 `error`
75
+ * 而让 partial 变得可搜。
40
76
  */
41
77
  upsertFile(input: {
42
78
  sourceId: KnowledgeSourceId | string;
@@ -46,61 +82,122 @@ export declare class KnowledgeIndexStore {
46
82
  mtime: number;
47
83
  adapterId: string;
48
84
  chunks: KnowledgeChunkDraft[];
85
+ identityKey?: string;
49
86
  externalUrl?: string;
50
87
  etag?: string;
51
88
  lastModified?: string;
52
- }): IndexedFileRecord;
89
+ }, opts?: {
90
+ batchSize?: number;
91
+ signal?: AbortSignal;
92
+ }): Promise<IndexedFileRecord>;
93
+ private upsertFileLocked;
53
94
  /**
54
- * 标记 skipped — **不删** 已有 chunks(瞬时/边界失败保旧索引);仅元数据。
95
+ * 半写入收尾:清掉已落地的 partial chunks,回到可重试的 `indexing`。
96
+ * 不得标成 `error`——error 行上的 partial 会被检索捞出。
55
97
  */
56
- markFileSkipped(sourceId: KnowledgeSourceId | string, path: string, reason: string): void;
98
+ private markUpsertIncomplete;
99
+ markFileSkipped(sourceId: KnowledgeSourceId | string, path: string, reason: string, size?: number, identityKey?: string): void;
100
+ markFileError(sourceId: KnowledgeSourceId | string, path: string, error: string, size?: number, identityKey?: string): void;
57
101
  /**
58
- * 标记 error — **不删** 已有 chunks(网络抖动不得清库);仅元数据。
59
- * 成功 `upsertFile` 才替换 chunks。
102
+ * 标记 skipped/error — **不删** 已有 chunks。
103
+ * 若已有 membership,只改状态;**不得**用 path-identity 新建 File 顶掉带 chunk 的行。
60
104
  */
61
- markFileError(sourceId: KnowledgeSourceId | string, path: string, error: string): void;
62
105
  private markFileNonIndexed;
63
106
  /**
64
- * 文件是否已用同一 contentHash 索引(且确有 chunk,防半写入)
107
+ * 清零认领的 path: 降级 File(错误路径与成功路径 identity 分裂残留)。
108
+ *
109
+ * @returns 删除的 File 行数
65
110
  */
111
+ purgeOrphanPathIdentityFiles(): number;
66
112
  isFresh(sourceId: KnowledgeSourceId | string, path: string, contentHash: string): boolean;
113
+ invalidateFileForReparse(sourceId: KnowledgeSourceId | string, path: string): void;
67
114
  getFile(sourceId: KnowledgeSourceId | string, path: string): IndexedFileRecord | null;
68
115
  listFiles(sourceId: KnowledgeSourceId | string): IndexedFileRecord[];
116
+ listFilesPaged(sourceId: KnowledgeSourceId | string, opts?: {
117
+ status?: 'indexed' | 'skipped' | 'error' | 'all';
118
+ ext?: string;
119
+ q?: string;
120
+ page?: number;
121
+ pageSize?: number;
122
+ }): {
123
+ items: Array<IndexedFileRecord & {
124
+ ext: string;
125
+ }>;
126
+ total: number;
127
+ page: number;
128
+ pageSize: number;
129
+ statusCounts: {
130
+ indexed: number;
131
+ skipped: number;
132
+ error: number;
133
+ };
134
+ extCounts: Array<{
135
+ ext: string;
136
+ n: number;
137
+ }>;
138
+ };
139
+ listFilePathsFiltered(sourceId: KnowledgeSourceId | string, filter?: {
140
+ status?: string;
141
+ ext?: string;
142
+ max?: number;
143
+ }): string[];
144
+ /** 解绑 path;File 仅在零认领时 purge(单文件同步语义,供测试/轻量路径) */
145
+ removeFile(sourceId: KnowledgeSourceId | string, path: string): void;
69
146
  /**
70
- * 单文件 purge(合规):chunks + embeddings + files 行
147
+ * 解绑 path + 可能的 purge(异步让出)。
148
+ * 单文件 purge 也可能删数千 chunk——必须让出,否则 Engine 调度不了 HTTP 回包。
71
149
  */
72
- purgePath(sourceId: KnowledgeSourceId | string, path: string): void;
150
+ removeFileAsync(sourceId: KnowledgeSourceId | string, path: string, opts?: {
151
+ yieldEvery?: number;
152
+ }): Promise<void>;
73
153
  /**
74
- * 源级 purge
154
+ * 批量解绑:每 `yieldEvery` 条让出事件循环。
155
+ * 删大目录(数百文件)时同步连环 DELETE 会堵死 Engine,HTTP/Query 回包都无法调度。
75
156
  */
76
- purgeSource(sourceId: KnowledgeSourceId | string): void;
157
+ removeFilesAsync(sourceId: KnowledgeSourceId | string, paths: string[], opts?: {
158
+ yieldEvery?: number;
159
+ }): Promise<number>;
160
+ removeFiles(sourceId: KnowledgeSourceId | string, paths: string[]): void;
77
161
  /**
78
- * 删除源下全部 index(卸载 / rebuild)
162
+ * 删除 path 及子树:先收集 logical_path,再分批异步解绑 + purge。
79
163
  */
80
- clearSource(sourceId: KnowledgeSourceId | string): void;
81
- removeFile(sourceId: KnowledgeSourceId | string, path: string): void;
164
+ removePathTreeAsync(sourceId: KnowledgeSourceId | string, path: string, opts?: {
165
+ yieldEvery?: number;
166
+ }): Promise<number>;
167
+ removePathTree(sourceId: KnowledgeSourceId | string, path: string): void;
82
168
  /**
83
- * 批量删除 path(同一事务,减少 sync 往返)
84
- *
85
- * @param sourceId - 知识源 id
86
- * @param paths - 精确 path 列表
169
+ * 清空源认领:分批 purge,避免一次清数千 File 堵死事件循环。
87
170
  */
88
- removeFiles(sourceId: KnowledgeSourceId | string, paths: string[]): void;
171
+ clearSourceAsync(sourceId: KnowledgeSourceId | string, opts?: {
172
+ yieldEvery?: number;
173
+ }): Promise<number>;
174
+ clearSource(sourceId: KnowledgeSourceId | string): void;
175
+ purgePath(sourceId: KnowledgeSourceId | string, path: string): void;
176
+ /** 按 fileId 物理删除(membership 已清) */
177
+ purgeFile(fileId: string): void;
178
+ purgeFileAsync(fileId: string, opts?: {
179
+ yieldEvery?: number;
180
+ }): Promise<void>;
181
+ purgeSource(sourceId: KnowledgeSourceId | string): void;
182
+ private purgeFileRow;
89
183
  /**
90
- * 删除路径及子树(目录被移出 / 删除)
91
- *
92
- * @param sourceId - 知识源 id
93
- * @param path - 文件或目录绝对路径
184
+ * purge + 分批让出。大文件数千 chunk 时 dropChunks 同步段仍可能秒级——批间 setImmediate。
185
+ * 与 upsertFile 共用 File 写锁,避免让出窗口被 parse 插入后残留孤儿 FTS。
94
186
  */
95
- removePathTree(sourceId: KnowledgeSourceId | string, path: string): void;
187
+ private purgeFileRowAsync;
188
+ private dropChunks;
189
+ private dropChunksAsync;
190
+ private dropChunksBatch;
191
+ private deleteKnowledgeVec;
96
192
  /**
97
- * 差量 prune:删除本轮 discover **未出现** 的 path(含 chunks)。
98
- * 仅在 discover 成功后调用;keepPaths 为空集时 no-op(防误清全库)。
193
+ * 对账差量删除:批量路径,内部让出事件循环。
99
194
  *
100
- * @param keepPaths - 应保留的 path 集
101
- * @param opts.allowEmptyKeep - walk 成功且目录为空时允许清空(默认 false)
102
- * @returns 删除的文件数
195
+ * @returns 删除条数
103
196
  */
197
+ pruneMissingAsync(sourceId: KnowledgeSourceId | string, keepPaths: ReadonlySet<string> | Iterable<string>, opts?: {
198
+ allowEmptyKeep?: boolean;
199
+ yieldEvery?: number;
200
+ }): Promise<number>;
104
201
  pruneMissing(sourceId: KnowledgeSourceId | string, keepPaths: ReadonlySet<string> | Iterable<string>, opts?: {
105
202
  allowEmptyKeep?: boolean;
106
203
  }): number;
@@ -112,83 +209,51 @@ export declare class KnowledgeIndexStore {
112
209
  errors: number;
113
210
  skipped: number;
114
211
  };
212
+ private computeSourceStats;
115
213
  /**
116
- * 关键词检索(CJK 二元组 + Latin);限定 sourceIds(可见集)
214
+ * 关键词检索。sourceIds = 可见 Membership;chunk 按 file 去重。
117
215
  */
118
216
  search(query: string, opts: {
119
217
  sourceIds: KnowledgeSourceId[];
120
218
  limit?: number;
121
219
  }): ChunkHit[];
220
+ vectorBackend(): 'sqlite-vec' | 'js-bucket' | 'disabled';
221
+ vectorSearch(embedding: Float32Array | number[], opts: {
222
+ sourceIds: KnowledgeSourceId[];
223
+ limit?: number;
224
+ buckets?: number[];
225
+ }): ChunkHit[];
226
+ listChunksMissingEmbedding(sourceId: KnowledgeSourceId | string, limit?: number): Array<{
227
+ chunkId: string;
228
+ text: string;
229
+ }>;
230
+ /** 是否仍有缺向量 chunk(EXISTS,不拉正文) */
231
+ hasChunksMissingEmbedding(sourceId: KnowledgeSourceId | string): boolean;
122
232
  /**
123
- * 按 chunk id 读取
233
+ * 批量写入嵌入。pairs: `[chunkId, number[]]`;空向量 = secret-skip 墓碑。
124
234
  */
125
- getChunkById(chunkId: KnowledgeChunkId | string): {
126
- id: KnowledgeChunkId;
127
- sourceId: KnowledgeSourceId | string;
235
+ setChunkEmbeddings(pairs: Array<[string, number[]]>): void;
236
+ setChunkEmbedding(chunkId: string, embedding: number[]): void;
237
+ private writeKnowledgeVec;
238
+ embeddingCoverage(sourceId?: KnowledgeSourceId | string): number;
239
+ private computeEmbeddingCoverage;
240
+ backfillVecFromEmbeddings(batch?: number): number;
241
+ getChunk(chunkId: string): {
242
+ id: string;
243
+ sourceId: string;
128
244
  path: string;
129
245
  text: string;
130
246
  startLine: number;
131
247
  endLine: number;
132
248
  } | null;
133
- /**
134
- * 按路径列出 chunks(可选行窗)
135
- */
136
- listChunksByPath(sourceId: KnowledgeSourceId | string, path: string, opts?: {
137
- startLine?: number;
138
- endLine?: number;
139
- }): Array<{
140
- id: KnowledgeChunkId;
141
- path: string;
249
+ listChunksByPath(sourceId: KnowledgeSourceId | string, path: string): Array<{
250
+ id: string;
142
251
  text: string;
143
252
  startLine: number;
144
253
  endLine: number;
145
- }>;
146
- /**
147
- * 写入 chunk 向量(Float32 BLOB;sqlite-vec 可用时同步进 vec 表)
148
- */
149
- setChunkEmbedding(chunkId: KnowledgeChunkId | string, embedding: number[]): void;
150
- /**
151
- * 批量写向量(单事务,减少与 parse 写路径的锁竞争)
152
- *
153
- * @param rows - [chunkId, embedding] 列表
154
- */
155
- setChunkEmbeddings(rows: Array<[string, number[]]>): void;
156
- /** sqlite-vec 表名 */
157
- private static readonly VEC_TABLE;
158
- /** 确保 vec0 虚拟表(维度首次写入时确定) */
159
- private ensureVecTable;
160
- private upsertKnowledgeVec;
161
- /**
162
- * 列出待嵌入 chunk(无向量行)
163
- *
164
- * **代码不进向量**:原文件已可 file_search;片段易失真。
165
- * 仅文档/正文类(text / markdown / document:* 等)参与 embedding。
166
- */
167
- listChunksMissingEmbedding(sourceId: KnowledgeSourceId | string, limit?: number): Array<{
168
- id: KnowledgeChunkId;
169
- text: string;
254
+ ordinal: number;
170
255
  path: string;
171
256
  }>;
172
- /**
173
- * 向量覆盖度(0–1;无可嵌入 chunk 时为 1)
174
- */
175
- embeddingCoverage(sourceId: KnowledgeSourceId | string): number;
176
- /**
177
- * 向量检索:优先 sqlite-vec KNN;否则 JS cosine(BLOB)
178
- */
179
- vectorSearch(queryEmbedding: number[], opts: {
180
- sourceIds: KnowledgeSourceId[];
181
- limit?: number;
182
- }): ChunkHit[];
183
- /** sqlite-vec KNN(不可用时返回 null) */
184
- private vectorSearchVec;
185
- /** JS 余弦(Float32 BLOB;无 JSON.parse) */
186
- private vectorSearchJs;
257
+ countEmbeddings(): number;
187
258
  }
188
- /**
189
- * 内容指纹(新鲜度判断)
190
- *
191
- * @param content - UTF-8 文本或原始字节(二进制文档用 bytes)
192
- * @returns sha256 hex
193
- */
194
259
  export declare function hashContent(content: string | Uint8Array): string;