@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,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,111 +82,178 @@ 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
  */
164
+ removePathTreeAsync(sourceId: KnowledgeSourceId | string, path: string, opts?: {
165
+ yieldEvery?: number;
166
+ }): Promise<number>;
167
+ removePathTree(sourceId: KnowledgeSourceId | string, path: string): void;
168
+ /**
169
+ * 清空源认领:分批 purge,避免一次清数千 File 堵死事件循环。
170
+ */
171
+ clearSourceAsync(sourceId: KnowledgeSourceId | string, opts?: {
172
+ yieldEvery?: number;
173
+ }): Promise<number>;
80
174
  clearSource(sourceId: KnowledgeSourceId | string): void;
81
- removeFile(sourceId: KnowledgeSourceId | string, path: 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;
82
183
  /**
83
- * 差量 prune:删除本轮 discover **未出现** 的 path(含 chunks)。
84
- * 仅在 discover 成功后调用;keepPaths 为空集时 no-op(防误清全库)。
184
+ * purge + 分批让出。大文件数千 chunk 时 dropChunks 同步段仍可能秒级——批间 setImmediate。
185
+ * 与 upsertFile 共用 File 写锁,避免让出窗口被 parse 插入后残留孤儿 FTS。
186
+ */
187
+ private purgeFileRowAsync;
188
+ private dropChunks;
189
+ private dropChunksAsync;
190
+ private dropChunksBatch;
191
+ private deleteKnowledgeVec;
192
+ /**
193
+ * 对账差量删除:批量路径,内部让出事件循环。
85
194
  *
86
- * @returns 删除的文件数
195
+ * @returns 删除条数
87
196
  */
88
- pruneMissing(sourceId: KnowledgeSourceId | string, keepPaths: ReadonlySet<string> | Iterable<string>): number;
197
+ pruneMissingAsync(sourceId: KnowledgeSourceId | string, keepPaths: ReadonlySet<string> | Iterable<string>, opts?: {
198
+ allowEmptyKeep?: boolean;
199
+ yieldEvery?: number;
200
+ }): Promise<number>;
201
+ pruneMissing(sourceId: KnowledgeSourceId | string, keepPaths: ReadonlySet<string> | Iterable<string>, opts?: {
202
+ allowEmptyKeep?: boolean;
203
+ }): number;
89
204
  sourceStats(sourceId: KnowledgeSourceId | string): {
90
205
  files: number;
91
206
  chunks: number;
207
+ embeddableChunks: number;
208
+ embeddings: number;
92
209
  errors: number;
93
210
  skipped: number;
94
211
  };
212
+ private computeSourceStats;
95
213
  /**
96
- * 关键词检索(CJK 二元组 + Latin);限定 sourceIds(可见集)
214
+ * 关键词检索。sourceIds = 可见 Membership;chunk 按 file 去重。
97
215
  */
98
216
  search(query: string, opts: {
99
217
  sourceIds: KnowledgeSourceId[];
100
218
  limit?: number;
101
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;
102
232
  /**
103
- * 按 chunk id 读取
233
+ * 批量写入嵌入。pairs: `[chunkId, number[]]`;空向量 = secret-skip 墓碑。
104
234
  */
105
- getChunkById(chunkId: KnowledgeChunkId | string): {
106
- id: KnowledgeChunkId;
107
- 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;
108
244
  path: string;
109
245
  text: string;
110
246
  startLine: number;
111
247
  endLine: number;
112
248
  } | null;
113
- /**
114
- * 按路径列出 chunks(可选行窗)
115
- */
116
- listChunksByPath(sourceId: KnowledgeSourceId | string, path: string, opts?: {
117
- startLine?: number;
118
- endLine?: number;
119
- }): Array<{
120
- id: KnowledgeChunkId;
121
- path: string;
249
+ listChunksByPath(sourceId: KnowledgeSourceId | string, path: string): Array<{
250
+ id: string;
122
251
  text: string;
123
252
  startLine: number;
124
253
  endLine: number;
125
- }>;
126
- /**
127
- * 写入 chunk 向量(JSON 冗余;P3 用 JS cosine)
128
- */
129
- setChunkEmbedding(chunkId: KnowledgeChunkId | string, embedding: number[]): void;
130
- /**
131
- * 列出待嵌入 chunk(无向量行)
132
- */
133
- listChunksMissingEmbedding(sourceId: KnowledgeSourceId | string, limit?: number): Array<{
134
- id: KnowledgeChunkId;
135
- text: string;
254
+ ordinal: number;
136
255
  path: string;
137
256
  }>;
138
- /**
139
- * 向量覆盖度(0–1;无 chunk 时为 1)
140
- */
141
- embeddingCoverage(sourceId: KnowledgeSourceId | string): number;
142
- /**
143
- * 向量检索(JS cosine);embeddingJson 不可用的 chunk 跳过
144
- */
145
- vectorSearch(queryEmbedding: number[], opts: {
146
- sourceIds: KnowledgeSourceId[];
147
- limit?: number;
148
- }): ChunkHit[];
257
+ countEmbeddings(): number;
149
258
  }
150
- /**
151
- * 内容指纹(新鲜度判断)
152
- *
153
- * @param content - UTF-8 文本或原始字节(二进制文档用 bytes)
154
- * @returns sha256 hex
155
- */
156
259
  export declare function hashContent(content: string | Uint8Array): string;