@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,158 @@
1
+ /**
2
+ * parseTextInWorker — 文本/MD/代码 读盘+hash+切块+FTS token 的线程入口
3
+ *
4
+ * 与 document extract worker 同一原则:CPU 密集步骤不得占 Service/Gateway 事件循环。
5
+ */
6
+ import { Worker } from 'node:worker_threads';
7
+ import { resolveWorkerUrl } from '../../worker-path.js';
8
+ const DEFAULT_TEXT_CONCURRENCY = 4;
9
+ let textInFlight = 0;
10
+ const textWaiters = [];
11
+ /**
12
+ * 槽位移交式信号量:release 唤醒 waiter 时 **不减计数**(槽交给对方),
13
+ * 避免「减后再 +」窗口被第三方 acquire 插队导致超卖。
14
+ */
15
+ async function acquireTextSlot(max) {
16
+ if (textInFlight < max) {
17
+ textInFlight += 1;
18
+ return;
19
+ }
20
+ await new Promise((resolve) => textWaiters.push(resolve));
21
+ }
22
+ function releaseTextSlot() {
23
+ const next = textWaiters.shift();
24
+ if (next) {
25
+ next();
26
+ return;
27
+ }
28
+ textInFlight = Math.max(0, textInFlight - 1);
29
+ }
30
+ /**
31
+ * 在 worker 中完成文本文件的 hash + 切块 + FTS token。
32
+ *
33
+ * @param filePath - 本地文件路径
34
+ * @param options - 截断策略 / 超时 / 中止 / 并发
35
+ * @returns contentHash + chunks(含 ftsToks)
36
+ */
37
+ /**
38
+ * 已有文本内容的切块 + ftsToks(虚拟文档 / DocumentPort 回退)。
39
+ *
40
+ * @param text - UTF-8 文本
41
+ * @param path - 用于 adapter 启发式与 FTS 路径 token
42
+ * @returns chunks(含 ftsToks)
43
+ */
44
+ export function chunkTextWithFtsToks(text, path, signal, adapterId, timeoutMs = 60_000) {
45
+ return (async () => {
46
+ await acquireTextSlot(DEFAULT_TEXT_CONCURRENCY);
47
+ try {
48
+ return await new Promise((resolve, reject) => {
49
+ if (signal?.aborted) {
50
+ reject(new Error('parse_aborted'));
51
+ return;
52
+ }
53
+ let settled = false;
54
+ const worker = new Worker(resolveWorkerUrl('./text-parse-worker.js', import.meta.url), {
55
+ workerData: {
56
+ inlineText: text,
57
+ path,
58
+ adapterId,
59
+ sizeDecision: 'ok',
60
+ },
61
+ });
62
+ const finish = (fn) => {
63
+ if (settled)
64
+ return;
65
+ settled = true;
66
+ clearTimeout(timer);
67
+ signal?.removeEventListener('abort', onAbort);
68
+ void worker.terminate();
69
+ fn();
70
+ };
71
+ const onAbort = () => finish(() => reject(new Error('parse_aborted')));
72
+ signal?.addEventListener('abort', onAbort, { once: true });
73
+ const timer = setTimeout(() => {
74
+ finish(() => reject(new Error(`text_parse_timeout after ${timeoutMs}ms`)));
75
+ }, timeoutMs);
76
+ worker.on('message', (msg) => {
77
+ if (msg?.ok && msg.chunks) {
78
+ finish(() => resolve(msg.chunks));
79
+ }
80
+ else {
81
+ finish(() => reject(new Error(msg?.error?.message ?? 'text_parse_failed')));
82
+ }
83
+ });
84
+ worker.on('error', (err) => finish(() => reject(err)));
85
+ worker.on('exit', (code) => {
86
+ if (code !== 0)
87
+ finish(() => reject(new Error(`text_parse_worker_exit ${code}`)));
88
+ });
89
+ });
90
+ }
91
+ finally {
92
+ releaseTextSlot();
93
+ }
94
+ })();
95
+ }
96
+ export function parseTextInWorker(filePath, options = {}) {
97
+ const timeoutMs = options.timeoutMs ?? 60_000;
98
+ const max = options.concurrency ?? DEFAULT_TEXT_CONCURRENCY;
99
+ return (async () => {
100
+ await acquireTextSlot(max);
101
+ try {
102
+ return await new Promise((resolve, reject) => {
103
+ if (options.signal?.aborted) {
104
+ reject(new Error('parse_aborted'));
105
+ return;
106
+ }
107
+ let settled = false;
108
+ const worker = new Worker(resolveWorkerUrl('./text-parse-worker.js', import.meta.url), {
109
+ workerData: {
110
+ path: filePath,
111
+ sizeDecision: options.sizeDecision ?? 'ok',
112
+ maxTextChars: options.maxTextChars,
113
+ },
114
+ });
115
+ const finish = (fn) => {
116
+ if (settled)
117
+ return;
118
+ settled = true;
119
+ clearTimeout(timer);
120
+ options.signal?.removeEventListener('abort', onAbort);
121
+ void worker.terminate();
122
+ fn();
123
+ };
124
+ const onAbort = () => {
125
+ finish(() => reject(new Error('parse_aborted')));
126
+ };
127
+ options.signal?.addEventListener('abort', onAbort, { once: true });
128
+ const timer = setTimeout(() => {
129
+ finish(() => reject(new Error(`text_parse_timeout after ${timeoutMs}ms`)));
130
+ }, timeoutMs);
131
+ worker.on('message', (msg) => {
132
+ if (msg?.ok && msg.contentHash && msg.chunks && msg.adapterId) {
133
+ finish(() => resolve({
134
+ contentHash: msg.contentHash,
135
+ contentLength: msg.contentLength ?? 0,
136
+ adapterId: msg.adapterId,
137
+ chunks: msg.chunks,
138
+ }));
139
+ }
140
+ else {
141
+ finish(() => reject(new Error(msg?.error?.message ?? 'text_parse_failed')));
142
+ }
143
+ });
144
+ worker.on('error', (err) => {
145
+ finish(() => reject(err));
146
+ });
147
+ worker.on('exit', (code) => {
148
+ if (code !== 0) {
149
+ finish(() => reject(new Error(`text_parse_worker_exit ${code}`)));
150
+ }
151
+ });
152
+ });
153
+ }
154
+ finally {
155
+ releaseTextSlot();
156
+ }
157
+ })();
158
+ }
@@ -0,0 +1,272 @@
1
+ /**
2
+ * KnowledgeQueryService — 只读查询面(search / list / stats / catalog…)
3
+ *
4
+ * 生产:Query Worker + 独立只读连接(WAL 一写多读),与 ingest 写路径线程分离。
5
+ * 测试 / :memory::LocalKnowledgeQueryService(同连接,小库可接受)。
6
+ *
7
+ * **禁止**在此接口上实现任何写路径(唯一写者是 Writer Worker / LocalKnowledgeWriteService)。
8
+ */
9
+ import type { KnowledgeDatabase } from './db.js';
10
+ import type { KnowledgeSourceStore } from './source-store.js';
11
+ import type { KnowledgeIndexStore, IndexedFileRecord } from './index-store.js';
12
+ import type { KnowledgeRetriever, HybridSearchResult, AutoGroundDecision, KnowledgeRecallMode } from './retriever.js';
13
+ import type { KnowledgeSource } from './types.js';
14
+ import type { KnowledgeCatalogItem } from './catalog-types.js';
15
+ import { type KnowledgeJobControlState } from './job-control-state.js';
16
+ import { type PromotionCandidate } from './hit-log.js';
17
+ export interface QueryIdentity {
18
+ tenantId?: string;
19
+ gatewayId?: string;
20
+ }
21
+ export interface SearchQuery {
22
+ agentId: string;
23
+ q: string;
24
+ sessionId?: string;
25
+ limit?: number;
26
+ keywordOnly?: boolean;
27
+ sourceIds?: string[];
28
+ source?: string;
29
+ identity?: QueryIdentity;
30
+ }
31
+ export interface AutoGroundQuery {
32
+ agentId: string;
33
+ q: string;
34
+ sessionId?: string;
35
+ limit?: number;
36
+ /** 覆盖全局/实例 recall */
37
+ recall?: KnowledgeRecallMode;
38
+ identity?: QueryIdentity;
39
+ }
40
+ export interface ListSourcesQuery {
41
+ scopeLevel?: 'global' | 'project' | 'session';
42
+ projectKey?: string;
43
+ sessionId?: string;
44
+ /** 管理面全量(不过滤 agent 可见)+ gateway 可见 */
45
+ identity?: QueryIdentity;
46
+ agentId?: string;
47
+ }
48
+ export interface SourceStatsBundle {
49
+ files: number;
50
+ chunks: number;
51
+ embeddableChunks: number;
52
+ embeddings: number;
53
+ errors: number;
54
+ skipped: number;
55
+ }
56
+ export interface SourceDetail {
57
+ source: KnowledgeSource;
58
+ stats: SourceStatsBundle;
59
+ jobControl: KnowledgeJobControlState;
60
+ assignedAgentIds: string[];
61
+ hiddenForAgentIds: string[];
62
+ }
63
+ export interface ListJobsQuery {
64
+ identity: QueryIdentity;
65
+ sourceId?: string;
66
+ status?: string;
67
+ limit?: number;
68
+ }
69
+ export interface ReadySnapshot {
70
+ ready: true;
71
+ sqliteVec: boolean;
72
+ fts: boolean;
73
+ ftsBackfill: {
74
+ running: boolean;
75
+ pendingChunks: number;
76
+ };
77
+ stats: Record<string, number>;
78
+ }
79
+ export interface PrincipalStats {
80
+ stats: Record<string, number>;
81
+ visibility: {
82
+ assignedProjects: string[];
83
+ hiddenSourceIds: string[];
84
+ };
85
+ visibleSources: number;
86
+ }
87
+ export interface ReadChunkResult {
88
+ found: boolean;
89
+ path?: string;
90
+ startLine?: number;
91
+ endLine?: number;
92
+ text?: string;
93
+ chunkCount?: number;
94
+ chunks?: Array<{
95
+ id: string;
96
+ text: string;
97
+ startLine: number;
98
+ endLine: number;
99
+ ordinal: number;
100
+ path: string;
101
+ }>;
102
+ }
103
+ /**
104
+ * 只读查询门面。实现必须无写副作用。
105
+ */
106
+ export interface KnowledgeQueryService {
107
+ search(query: SearchQuery): Promise<HybridSearchResult>;
108
+ /** turn 级自动召回分档(GroundingAssembler / client grounding) */
109
+ autoGround(query: AutoGroundQuery): Promise<AutoGroundDecision>;
110
+ listSources(query: ListSourcesQuery): Promise<KnowledgeSource[]>;
111
+ listProjects(identity?: QueryIdentity): Promise<Array<Record<string, unknown>>>;
112
+ getSource(sourceId: string, identity?: QueryIdentity): Promise<{
113
+ source: KnowledgeSource;
114
+ stats: SourceStatsBundle;
115
+ } | null>;
116
+ listFiles(sourceId: string, identity?: QueryIdentity): Promise<IndexedFileRecord[]>;
117
+ listFilesPaged(sourceId: string, opts?: {
118
+ status?: 'indexed' | 'skipped' | 'error' | 'all';
119
+ ext?: string;
120
+ q?: string;
121
+ page?: number;
122
+ pageSize?: number;
123
+ }, identity?: QueryIdentity): Promise<{
124
+ items: Array<IndexedFileRecord & {
125
+ ext: string;
126
+ }>;
127
+ total: number;
128
+ page: number;
129
+ pageSize: number;
130
+ statusCounts: {
131
+ indexed: number;
132
+ skipped: number;
133
+ error: number;
134
+ };
135
+ extCounts: Array<{
136
+ ext: string;
137
+ n: number;
138
+ }>;
139
+ }>;
140
+ principalStats(agentId: string, identity?: QueryIdentity): Promise<PrincipalStats>;
141
+ catalog(agentId: string, identity?: QueryIdentity): Promise<KnowledgeCatalogItem[]>;
142
+ listChunks(agentId: string, sourceId: string, path: string, identity?: QueryIdentity, sessionId?: string): Promise<Array<{
143
+ id: string;
144
+ text: string;
145
+ startLine: number;
146
+ endLine: number;
147
+ ordinal: number;
148
+ path: string;
149
+ }> | null>;
150
+ read(agentId: string, body: {
151
+ chunkId?: string;
152
+ sourceId?: string;
153
+ path?: string;
154
+ }, identity?: QueryIdentity, sessionId?: string): Promise<ReadChunkResult>;
155
+ visibility(agentId: string, identity?: QueryIdentity): Promise<{
156
+ assignedProjects: string[];
157
+ hiddenSourceIds: string[];
158
+ }>;
159
+ sessionVisibility(agentId: string, sessionId: string, identity?: QueryIdentity): Promise<Array<Record<string, unknown>>>;
160
+ dbStats(): Promise<Record<string, number>>;
161
+ /** 源详情(stats + jobControl + 项目/隐藏 agent)— 禁止走写连接 */
162
+ getSourceDetail(sourceId: string, identity?: QueryIdentity): Promise<SourceDetail | null>;
163
+ getPrincipal(identity: QueryIdentity, agentId: string): Promise<Record<string, unknown> | null>;
164
+ /** 是否被**其他** gateway 登记了同名 principal(只读鉴权用) */
165
+ isPrincipalForeign(identity: QueryIdentity, agentId: string): Promise<boolean>;
166
+ isSourceOwner(sourceId: string, gatewayId: string): Promise<boolean>;
167
+ ready(): Promise<ReadySnapshot>;
168
+ listJobs(query: ListJobsQuery): Promise<Array<Record<string, unknown>>>;
169
+ promotionCandidates(): Promise<PromotionCandidate[]>;
170
+ dispose(): Promise<void> | void;
171
+ }
172
+ export interface LocalQueryDeps {
173
+ db: KnowledgeDatabase;
174
+ sources: KnowledgeSourceStore;
175
+ index: KnowledgeIndexStore;
176
+ retriever: KnowledgeRetriever;
177
+ /** jobControl.embedMissing 语义:无 embedding provider 时应 false */
178
+ embeddingEnabled?: boolean;
179
+ }
180
+ /**
181
+ * 进程内只读实现(测试 / 共享 :memory:)。
182
+ * 与 Worker 实现同接口;生产 Engine 线程应使用 Worker 以隔离写阻塞。
183
+ */
184
+ export declare class LocalKnowledgeQueryService implements KnowledgeQueryService {
185
+ private readonly deps;
186
+ constructor(deps: LocalQueryDeps);
187
+ search(query: SearchQuery): Promise<HybridSearchResult>;
188
+ autoGround(query: AutoGroundQuery): Promise<AutoGroundDecision>;
189
+ listSources(query: ListSourcesQuery): Promise<KnowledgeSource[]>;
190
+ listProjects(identity?: QueryIdentity): Promise<Array<Record<string, unknown>>>;
191
+ getSource(sourceId: string, identity?: QueryIdentity): Promise<{
192
+ source: KnowledgeSource;
193
+ stats: SourceStatsBundle;
194
+ } | null>;
195
+ listFiles(sourceId: string, identity?: QueryIdentity): Promise<IndexedFileRecord[]>;
196
+ listFilesPaged(sourceId: string, opts?: {
197
+ status?: 'indexed' | 'skipped' | 'error' | 'all';
198
+ ext?: string;
199
+ q?: string;
200
+ page?: number;
201
+ pageSize?: number;
202
+ }, identity?: QueryIdentity): Promise<{
203
+ items: Array<IndexedFileRecord & {
204
+ ext: string;
205
+ }>;
206
+ total: number;
207
+ page: number;
208
+ pageSize: number;
209
+ statusCounts: {
210
+ indexed: number;
211
+ skipped: number;
212
+ error: number;
213
+ };
214
+ extCounts: Array<{
215
+ ext: string;
216
+ n: number;
217
+ }>;
218
+ }>;
219
+ principalStats(agentId: string, identity?: QueryIdentity): Promise<PrincipalStats>;
220
+ catalog(agentId: string, identity?: QueryIdentity): Promise<KnowledgeCatalogItem[]>;
221
+ listChunks(agentId: string, sourceId: string, path: string, identity?: QueryIdentity, sessionId?: string): Promise<Array<{
222
+ id: string;
223
+ text: string;
224
+ startLine: number;
225
+ endLine: number;
226
+ ordinal: number;
227
+ path: string;
228
+ }> | null>;
229
+ read(agentId: string, body: {
230
+ chunkId?: string;
231
+ sourceId?: string;
232
+ path?: string;
233
+ }, identity?: QueryIdentity, sessionId?: string): Promise<ReadChunkResult>;
234
+ visibility(agentId: string, identity?: QueryIdentity): Promise<{
235
+ assignedProjects: string[];
236
+ hiddenSourceIds: string[];
237
+ }>;
238
+ sessionVisibility(agentId: string, sessionId: string, identity?: QueryIdentity): Promise<Array<Record<string, unknown>>>;
239
+ dbStats(): Promise<Record<string, number>>;
240
+ getSourceDetail(sourceId: string, identity?: QueryIdentity): Promise<SourceDetail | null>;
241
+ getPrincipal(identity: QueryIdentity, agentId: string): Promise<Record<string, unknown> | null>;
242
+ isPrincipalForeign(identity: QueryIdentity, agentId: string): Promise<boolean>;
243
+ isSourceOwner(sourceId: string, gatewayId: string): Promise<boolean>;
244
+ ready(): Promise<ReadySnapshot>;
245
+ listJobs(query: ListJobsQuery): Promise<Array<Record<string, unknown>>>;
246
+ promotionCandidates(): Promise<PromotionCandidate[]>;
247
+ dispose(): void;
248
+ private gatewayVisible;
249
+ }
250
+ /**
251
+ * 组装只读服务。
252
+ *
253
+ * - `mode: 'worker'`:文件库 + 独立线程(生产 Engine);WAL 一写多读,与 ingest 写隔离。
254
+ * - `mode: 'local'`:同连接进程内实现。**`:memory:` 必须用 local**——内存库无法跨连接共享,
255
+ * Worker 会各自打开空库导致检索为空。
256
+ *
257
+ * @param opts - dbPath / 本地 deps / embeddingModels(Worker 内重建 provider)
258
+ */
259
+ export type QueryWorkerRole = 'meta' | 'search' | 'all';
260
+ export declare function createKnowledgeQueryService(opts: {
261
+ dbPath: string;
262
+ mode: 'worker' | 'local';
263
+ local?: LocalQueryDeps;
264
+ embeddingModels?: {
265
+ providers?: Record<string, unknown>;
266
+ embedding?: unknown;
267
+ } | null;
268
+ sqliteVecExtensionPath?: string;
269
+ /** Worker 角色:meta=列表/控制面,search=检索/catalog,all=单 Worker 全量 */
270
+ role?: QueryWorkerRole;
271
+ queryTimeoutMs?: number;
272
+ }): Promise<KnowledgeQueryService>;