@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,186 @@
1
+ /**
2
+ * Query Worker — Knowledge 只读查询线程
3
+ *
4
+ * 独立 DatabaseSync 连接 + WAL:Engine 写事务阻塞时本线程仍可应答 search/list/stats。
5
+ * 无任何写路径。
6
+ */
7
+ import { parentPort, workerData } from 'node:worker_threads';
8
+ import { KnowledgeDatabase } from './db.js';
9
+ import { KnowledgeSourceStore } from './source-store.js';
10
+ import { KnowledgeIndexStore } from './index-store.js';
11
+ import { KnowledgeRetriever } from './retriever.js';
12
+ import { LocalKnowledgeQueryService, } from './query-service.js';
13
+ /** meta:列表/控制面(UI 轮询必须稳);search:检索/catalog(可慢) */
14
+ const META_METHODS = new Set([
15
+ 'listProjects',
16
+ 'listSources',
17
+ 'getSource',
18
+ 'getSourceDetail',
19
+ 'getPrincipal',
20
+ 'isPrincipalForeign',
21
+ 'isSourceOwner',
22
+ 'ready',
23
+ 'listJobs',
24
+ 'jobControlState',
25
+ 'visibility',
26
+ 'sessionVisibility',
27
+ 'dbStats',
28
+ 'promotionCandidates',
29
+ ]);
30
+ const SEARCH_METHODS = new Set([
31
+ 'search',
32
+ 'autoGround',
33
+ 'catalog',
34
+ 'listChunks',
35
+ 'read',
36
+ 'listFiles',
37
+ 'listFilesPaged',
38
+ 'principalStats',
39
+ // boot 握手探活(WorkerQueryService.start)
40
+ 'dbStats',
41
+ ]);
42
+ async function main() {
43
+ const boot = workerData;
44
+ const port = parentPort;
45
+ if (!port)
46
+ throw new Error('knowledge query worker requires parentPort');
47
+ const role = boot.role ?? 'all';
48
+ const allowed = role === 'meta'
49
+ ? META_METHODS
50
+ : role === 'search'
51
+ ? SEARCH_METHODS
52
+ : new Set([...META_METHODS, ...SEARCH_METHODS]);
53
+ // 只读连接:跳过 DDL,不与 Writer 争写锁;唯一写者是 Writer Worker
54
+ const db = await KnowledgeDatabase.create({
55
+ dbPath: boot.dbPath,
56
+ readOnly: true,
57
+ skipMigrate: true,
58
+ sqliteVec: boot.sqliteVecExtensionPath
59
+ ? { extensionPath: boot.sqliteVecExtensionPath }
60
+ : true,
61
+ });
62
+ let embeddingProvider = null;
63
+ if (boot.embeddingModels) {
64
+ const { resolveEmbeddingRuntime } = await import('../memory/sqlite/embedding-from-models.js');
65
+ const runtime = resolveEmbeddingRuntime(boot.embeddingModels);
66
+ embeddingProvider = runtime?.provider ?? null;
67
+ }
68
+ const sources = new KnowledgeSourceStore(db);
69
+ const index = new KnowledgeIndexStore(db);
70
+ const retriever = new KnowledgeRetriever({
71
+ sourceStore: sources,
72
+ indexStore: index,
73
+ embeddingProvider: embeddingProvider,
74
+ });
75
+ const svc = new LocalKnowledgeQueryService({
76
+ db,
77
+ sources,
78
+ index,
79
+ retriever,
80
+ embeddingEnabled: Boolean(embeddingProvider),
81
+ });
82
+ port.on('message', (msg) => {
83
+ void (async () => {
84
+ const id = msg?.id;
85
+ if (id == null)
86
+ return;
87
+ try {
88
+ let data;
89
+ if (msg.method === 'shutdown') {
90
+ try {
91
+ db.close();
92
+ }
93
+ catch {
94
+ /* already closed */
95
+ }
96
+ port.postMessage({ id, ok: true, data: null });
97
+ port.close();
98
+ return;
99
+ }
100
+ if (!allowed.has(msg.method)) {
101
+ throw new Error(`query_method_not_in_role:${msg.method}:${role}`);
102
+ }
103
+ switch (msg.method) {
104
+ case 'search':
105
+ data = await svc.search(msg.query);
106
+ break;
107
+ case 'autoGround':
108
+ data = await svc.autoGround(msg.query);
109
+ break;
110
+ case 'listSources':
111
+ data = await svc.listSources(msg.query);
112
+ break;
113
+ case 'listProjects':
114
+ data = await svc.listProjects(msg.identity);
115
+ break;
116
+ case 'getSource':
117
+ data = await svc.getSource(msg.sourceId, msg.identity);
118
+ break;
119
+ case 'listFiles':
120
+ data = await svc.listFiles(msg.sourceId, msg.identity);
121
+ break;
122
+ case 'listFilesPaged':
123
+ data = await svc.listFilesPaged(msg.sourceId, msg.opts, msg.identity);
124
+ break;
125
+ case 'principalStats':
126
+ data = await svc.principalStats(msg.agentId, msg.identity);
127
+ break;
128
+ case 'catalog':
129
+ data = await svc.catalog(msg.agentId, msg.identity);
130
+ break;
131
+ case 'listChunks':
132
+ data = await svc.listChunks(msg.agentId, msg.sourceId, msg.path, msg.identity, msg.sessionId);
133
+ break;
134
+ case 'read':
135
+ data = await svc.read(msg.agentId, msg.body, msg.identity, msg.sessionId);
136
+ break;
137
+ case 'visibility':
138
+ data = await svc.visibility(msg.agentId, msg.identity);
139
+ break;
140
+ case 'sessionVisibility':
141
+ data = await svc.sessionVisibility(msg.agentId, msg.sessionId, msg.identity);
142
+ break;
143
+ case 'dbStats':
144
+ data = await svc.dbStats();
145
+ break;
146
+ case 'getSourceDetail':
147
+ data = await svc.getSourceDetail(msg.sourceId, msg.identity);
148
+ break;
149
+ case 'getPrincipal':
150
+ data = await svc.getPrincipal(msg.identity, msg.agentId);
151
+ break;
152
+ case 'isPrincipalForeign':
153
+ data = await svc.isPrincipalForeign(msg.identity, msg.agentId);
154
+ break;
155
+ case 'isSourceOwner':
156
+ data = await svc.isSourceOwner(msg.sourceId, msg.gatewayId);
157
+ break;
158
+ case 'ready':
159
+ data = await svc.ready();
160
+ break;
161
+ case 'listJobs':
162
+ data = await svc.listJobs(msg.query);
163
+ break;
164
+ case 'promotionCandidates':
165
+ data = await svc.promotionCandidates();
166
+ break;
167
+ default:
168
+ throw new Error(`unknown_query_method`);
169
+ }
170
+ port.postMessage({ id, ok: true, data });
171
+ }
172
+ catch (err) {
173
+ port.postMessage({
174
+ id,
175
+ ok: false,
176
+ error: err instanceof Error ? err.message : String(err),
177
+ });
178
+ }
179
+ })();
180
+ });
181
+ port.postMessage({ id: 0, ok: true, data: { type: 'ready' } });
182
+ }
183
+ main().catch((err) => {
184
+ const message = err instanceof Error ? err.message : String(err);
185
+ parentPort?.postMessage({ id: 0, ok: false, error: message });
186
+ });
@@ -0,0 +1,35 @@
1
+ /**
2
+ * Knowledge 只读 HTTP — 主线程直达 Meta/Search Query Worker
3
+ *
4
+ * 禁止在此碰写连接或同步 SQLite。鉴权后的纯读请求不再进 Engine Worker,
5
+ * ingest 占死写线程时列表/详情仍应答。
6
+ */
7
+ import type { IncomingMessage, ServerResponse } from 'node:http';
8
+ import type { KnowledgeQueryService } from './query-service.js';
9
+ import type { KnowledgeServiceToken } from './http-app.js';
10
+ export interface ReadHttpDeps {
11
+ /** meta:projects / sources / detail / jobs / ready */
12
+ meta: KnowledgeQueryService;
13
+ /** search:search / catalog / chunks / files */
14
+ search: KnowledgeQueryService;
15
+ tokens: KnowledgeServiceToken[];
16
+ /** autoRegister=false 时 principal 必须已登记;只读路径永不写库 */
17
+ autoRegisterPrincipals?: boolean;
18
+ }
19
+ type AuthContext = {
20
+ tenantId: string;
21
+ gatewayId: string;
22
+ agentId?: string;
23
+ sessionId?: string;
24
+ };
25
+ /** 纯读路由表(method + path pattern)— 与 serve 分类共用 */
26
+ export declare function isPureReadRoute(method: string, path: string): boolean;
27
+ /**
28
+ * 处理纯读请求。
29
+ *
30
+ * @returns 是否已应答(false = 非只读路由,调用方应转 Engine)
31
+ */
32
+ export declare function handleKnowledgeReadHttp(deps: ReadHttpDeps, req: IncomingMessage, res: ServerResponse, auth: AuthContext): Promise<boolean>;
33
+ /** 主线程鉴权(与 Engine 同一 token 表) */
34
+ export declare function authenticateRead(tokens: KnowledgeServiceToken[], req: IncomingMessage): AuthContext | null;
35
+ export {};
@@ -0,0 +1,373 @@
1
+ /**
2
+ * Knowledge 只读 HTTP — 主线程直达 Meta/Search Query Worker
3
+ *
4
+ * 禁止在此碰写连接或同步 SQLite。鉴权后的纯读请求不再进 Engine Worker,
5
+ * ingest 占死写线程时列表/详情仍应答。
6
+ */
7
+ import { matchKnowledgeToken } from './http-bridge.js';
8
+ function json(res, status, payload) {
9
+ const buf = Buffer.from(JSON.stringify(payload), 'utf8');
10
+ res.writeHead(status, {
11
+ 'content-type': 'application/json; charset=utf-8',
12
+ 'content-length': buf.byteLength,
13
+ });
14
+ res.end(buf);
15
+ }
16
+ function err(res, status, code, message, details) {
17
+ json(res, status, { error: { code, message, details } });
18
+ }
19
+ function identityOf(ctx) {
20
+ return { tenantId: ctx.tenantId, gatewayId: ctx.gatewayId };
21
+ }
22
+ /** 纯读路由表(method + path pattern)— 与 serve 分类共用 */
23
+ export function isPureReadRoute(method, path) {
24
+ if (method === 'GET' || method === 'HEAD') {
25
+ if (path === '/v1/ready')
26
+ return true;
27
+ if (path === '/v1/projects')
28
+ return true;
29
+ if (path === '/v1/sources')
30
+ return true;
31
+ if (/^\/v1\/sources\/[^/]+$/.test(path))
32
+ return true;
33
+ if (/^\/v1\/sources\/[^/]+\/files$/.test(path))
34
+ return true;
35
+ if (/^\/v1\/principals\/[^/]+$/.test(path))
36
+ return true;
37
+ if (/^\/v1\/principals\/[^/]+\/search$/.test(path))
38
+ return true;
39
+ if (/^\/v1\/principals\/[^/]+\/ground$/.test(path))
40
+ return true;
41
+ if (/^\/v1\/principals\/[^/]+\/stats$/.test(path))
42
+ return true;
43
+ if (/^\/v1\/principals\/[^/]+\/catalog$/.test(path))
44
+ return true;
45
+ if (/^\/v1\/principals\/[^/]+\/chunks$/.test(path))
46
+ return true;
47
+ if (/^\/v1\/principals\/[^/]+\/visibility$/.test(path))
48
+ return true;
49
+ if (/^\/v1\/principals\/[^/]+\/session-visibility$/.test(path))
50
+ return true;
51
+ if (path === '/v1/jobs')
52
+ return true;
53
+ if (path === '/v1/jobs/control')
54
+ return true;
55
+ if (path === '/v1/promotion-candidates')
56
+ return true;
57
+ return false;
58
+ }
59
+ // POST read 是语义只读
60
+ if (method === 'POST' && /^\/v1\/principals\/[^/]+\/read$/.test(path))
61
+ return true;
62
+ return false;
63
+ }
64
+ /**
65
+ * 处理纯读请求。
66
+ *
67
+ * @returns 是否已应答(false = 非只读路由,调用方应转 Engine)
68
+ */
69
+ export async function handleKnowledgeReadHttp(deps, req, res, auth) {
70
+ const method = (req.method ?? 'GET').toUpperCase();
71
+ const url = new URL(req.url ?? '/', 'http://internal');
72
+ const path = url.pathname.replace(/\/+$/, '') || '/';
73
+ if (!isPureReadRoute(method, path))
74
+ return false;
75
+ const ctx = { ...auth };
76
+ const headerAgent = req.headers['x-octopi-agent'];
77
+ const headerSession = req.headers['x-octopi-session'];
78
+ if (typeof headerAgent === 'string' && headerAgent)
79
+ ctx.agentId = headerAgent;
80
+ if (typeof headerSession === 'string' && headerSession)
81
+ ctx.sessionId = headerSession;
82
+ const { meta, search } = deps;
83
+ try {
84
+ if (path === '/v1/ready') {
85
+ json(res, 200, await meta.ready());
86
+ return true;
87
+ }
88
+ if (path === '/v1/projects') {
89
+ json(res, 200, { ok: true, data: await meta.listProjects(identityOf(ctx)) });
90
+ return true;
91
+ }
92
+ if (path === '/v1/sources') {
93
+ const scopeLevel = url.searchParams.get('scopeLevel');
94
+ const projectKey = url.searchParams.get('projectKey') ?? undefined;
95
+ const sessionId = url.searchParams.get('sessionId') ?? undefined;
96
+ const query = {
97
+ ...(scopeLevel === 'global' || scopeLevel === 'project' || scopeLevel === 'session'
98
+ ? { scopeLevel }
99
+ : {}),
100
+ ...(projectKey != null && projectKey !== '' ? { projectKey } : {}),
101
+ ...(sessionId != null && sessionId !== '' ? { sessionId } : {}),
102
+ identity: identityOf(ctx),
103
+ };
104
+ json(res, 200, { ok: true, data: await meta.listSources(query) });
105
+ return true;
106
+ }
107
+ const sourceMatch = /^\/v1\/sources\/([^/]+)$/.exec(path);
108
+ if (sourceMatch) {
109
+ const detail = await meta.getSourceDetail(sourceMatch[1], identityOf(ctx));
110
+ if (!detail) {
111
+ err(res, 404, 'source_not_found', 'source not found');
112
+ return true;
113
+ }
114
+ json(res, 200, {
115
+ ok: true,
116
+ data: {
117
+ ...detail.source,
118
+ stats: detail.stats,
119
+ jobControl: detail.jobControl,
120
+ assignedAgentIds: detail.assignedAgentIds,
121
+ hiddenForAgentIds: detail.hiddenForAgentIds,
122
+ },
123
+ });
124
+ return true;
125
+ }
126
+ const filesMatch = /^\/v1\/sources\/([^/]+)\/files$/.exec(path);
127
+ if (filesMatch) {
128
+ const sid = filesMatch[1];
129
+ const owned = await meta.isSourceOwner(sid, ctx.gatewayId);
130
+ if (!owned) {
131
+ err(res, 403, 'not_resource_owner', 'not source owner');
132
+ return true;
133
+ }
134
+ const paged = url.searchParams.has('page') ||
135
+ url.searchParams.has('pageSize') ||
136
+ url.searchParams.has('status') ||
137
+ url.searchParams.has('ext') ||
138
+ url.searchParams.has('q');
139
+ if (paged) {
140
+ const status = url.searchParams.get('status') ?? undefined;
141
+ const data = await search.listFilesPaged(sid, {
142
+ ...(status === 'indexed' || status === 'skipped' || status === 'error' || status === 'all'
143
+ ? { status }
144
+ : {}),
145
+ ...(url.searchParams.get('ext') ? { ext: url.searchParams.get('ext') } : {}),
146
+ ...(url.searchParams.get('q') ? { q: url.searchParams.get('q') } : {}),
147
+ ...(url.searchParams.get('page')
148
+ ? { page: Number(url.searchParams.get('page')) }
149
+ : {}),
150
+ ...(url.searchParams.get('pageSize')
151
+ ? { pageSize: Number(url.searchParams.get('pageSize')) }
152
+ : {}),
153
+ }, identityOf(ctx));
154
+ json(res, 200, { ok: true, data });
155
+ return true;
156
+ }
157
+ json(res, 200, { ok: true, data: await search.listFiles(sid, identityOf(ctx)) });
158
+ return true;
159
+ }
160
+ const principalMatch = /^\/v1\/principals\/([^/]+)$/.exec(path);
161
+ if (principalMatch) {
162
+ const row = await meta.getPrincipal(identityOf(ctx), principalMatch[1]);
163
+ if (!row) {
164
+ err(res, 404, 'principal_not_registered', 'principal not found');
165
+ return true;
166
+ }
167
+ json(res, 200, { ok: true, data: row });
168
+ return true;
169
+ }
170
+ const agentPath = /^\/v1\/principals\/([^/]+)(\/.*)?$/.exec(path);
171
+ if (agentPath) {
172
+ const agentId = agentPath[1];
173
+ const sub = agentPath[2] ?? '';
174
+ const principal = await meta.getPrincipal(identityOf(ctx), agentId);
175
+ if (!principal && deps.autoRegisterPrincipals === false) {
176
+ err(res, 403, 'principal_not_registered', 'principal not registered');
177
+ return true;
178
+ }
179
+ // 只读路径不得写库,但仍须拒绝他方已登记的同名 principal(session-visibility 等)
180
+ if ((sub === '/session-visibility' || sub === '/visibility') &&
181
+ (await meta.isPrincipalForeign(identityOf(ctx), agentId))) {
182
+ err(res, 403, 'not_principal_owner', 'not principal owner');
183
+ return true;
184
+ }
185
+ if (sub === '/search') {
186
+ const q = url.searchParams.get('q') ?? '';
187
+ const limit = Number(url.searchParams.get('limit') ?? 8);
188
+ const sessionId = url.searchParams.get('sessionId') ?? undefined;
189
+ json(res, 200, {
190
+ ok: true,
191
+ data: await search.search({
192
+ agentId,
193
+ q,
194
+ sessionId,
195
+ limit,
196
+ identity: identityOf(ctx),
197
+ }),
198
+ });
199
+ return true;
200
+ }
201
+ if (sub === '/ground') {
202
+ const q = url.searchParams.get('q') ?? '';
203
+ const limit = Number(url.searchParams.get('limit') ?? 8);
204
+ const sessionId = url.searchParams.get('sessionId') ?? undefined;
205
+ const recallRaw = url.searchParams.get('recall');
206
+ const recall = recallRaw === 'off' || recallRaw === 'hint' || recallRaw === 'hybrid' || recallRaw === 'inject'
207
+ ? recallRaw
208
+ : undefined;
209
+ json(res, 200, {
210
+ ok: true,
211
+ data: await search.autoGround({
212
+ agentId,
213
+ q,
214
+ sessionId,
215
+ limit,
216
+ ...(recall ? { recall } : {}),
217
+ identity: identityOf(ctx),
218
+ }),
219
+ });
220
+ return true;
221
+ }
222
+ if (sub === '/stats') {
223
+ const principalStats = await search.principalStats(agentId, identityOf(ctx));
224
+ json(res, 200, {
225
+ ok: true,
226
+ data: {
227
+ ...principalStats.stats,
228
+ visibility: principalStats.visibility,
229
+ visibleSources: principalStats.visibleSources,
230
+ },
231
+ });
232
+ return true;
233
+ }
234
+ if (sub === '/catalog') {
235
+ json(res, 200, {
236
+ ok: true,
237
+ data: await search.catalog(agentId, identityOf(ctx)),
238
+ });
239
+ return true;
240
+ }
241
+ if (sub === '/chunks') {
242
+ const sourceId = url.searchParams.get('sourceId') ?? '';
243
+ const pathParam = url.searchParams.get('path') ?? '';
244
+ if (!sourceId || !pathParam) {
245
+ err(res, 400, 'bad_request', 'sourceId and path required');
246
+ return true;
247
+ }
248
+ const data = await search.listChunks(agentId, sourceId, pathParam, identityOf(ctx), ctx.sessionId);
249
+ if (data == null) {
250
+ err(res, 404, 'file_not_found', 'source not found');
251
+ return true;
252
+ }
253
+ json(res, 200, { ok: true, data });
254
+ return true;
255
+ }
256
+ if (sub === '/visibility' && method === 'GET') {
257
+ json(res, 200, {
258
+ ok: true,
259
+ data: await meta.visibility(agentId, identityOf(ctx)),
260
+ });
261
+ return true;
262
+ }
263
+ if (sub === '/session-visibility' && method === 'GET') {
264
+ const sessionId = url.searchParams.get('sessionId') ?? '';
265
+ if (!sessionId) {
266
+ err(res, 400, 'session_required', 'sessionId required');
267
+ return true;
268
+ }
269
+ json(res, 200, {
270
+ ok: true,
271
+ data: await meta.sessionVisibility(agentId, sessionId, identityOf(ctx)),
272
+ });
273
+ return true;
274
+ }
275
+ if (sub === '/read' && method === 'POST') {
276
+ const raw = await readJsonBody(req);
277
+ const b = raw;
278
+ if (!b?.chunkId && (!b?.sourceId || !b?.path)) {
279
+ err(res, 400, 'bad_request', 'chunkId or (sourceId+path) required');
280
+ return true;
281
+ }
282
+ if (b.chunkId) {
283
+ const data = await search.read(agentId, b, identityOf(ctx), ctx.sessionId);
284
+ if (!data.found) {
285
+ err(res, 404, 'file_not_found', 'chunk not found');
286
+ return true;
287
+ }
288
+ json(res, 200, { ok: true, data });
289
+ return true;
290
+ }
291
+ const chunks = await search.listChunks(agentId, b.sourceId, b.path, identityOf(ctx), ctx.sessionId);
292
+ if (chunks == null) {
293
+ err(res, 404, 'source_not_found', 'source not found');
294
+ return true;
295
+ }
296
+ json(res, 200, {
297
+ ok: true,
298
+ data: {
299
+ found: chunks.length > 0,
300
+ path: b.path,
301
+ chunkCount: chunks.length,
302
+ text: chunks.map((c) => c.text).join('\n\n'),
303
+ chunks,
304
+ },
305
+ });
306
+ return true;
307
+ }
308
+ }
309
+ if (path === '/v1/jobs') {
310
+ json(res, 200, {
311
+ ok: true,
312
+ data: await meta.listJobs({
313
+ identity: identityOf(ctx),
314
+ sourceId: url.searchParams.get('sourceId') ?? undefined,
315
+ status: url.searchParams.get('status') ?? undefined,
316
+ }),
317
+ });
318
+ return true;
319
+ }
320
+ if (path === '/v1/jobs/control') {
321
+ const sourceId = url.searchParams.get('sourceId') ?? '';
322
+ if (!sourceId) {
323
+ err(res, 400, 'bad_request', 'sourceId required');
324
+ return true;
325
+ }
326
+ const owned = await meta.isSourceOwner(sourceId, ctx.gatewayId);
327
+ if (!owned) {
328
+ err(res, 403, 'not_resource_owner', 'not source owner');
329
+ return true;
330
+ }
331
+ const detail = await meta.getSourceDetail(sourceId, identityOf(ctx));
332
+ if (!detail) {
333
+ err(res, 404, 'source_not_found', 'source not found');
334
+ return true;
335
+ }
336
+ json(res, 200, { ok: true, data: detail.jobControl });
337
+ return true;
338
+ }
339
+ if (path === '/v1/promotion-candidates') {
340
+ json(res, 200, { ok: true, data: await meta.promotionCandidates() });
341
+ return true;
342
+ }
343
+ err(res, 404, 'not_found', `no route ${method} ${path}`);
344
+ return true;
345
+ }
346
+ catch (e) {
347
+ err(res, 500, 'internal_error', e instanceof Error ? e.message : String(e));
348
+ return true;
349
+ }
350
+ }
351
+ async function readJsonBody(req) {
352
+ if (req.method === 'GET' || req.method === 'HEAD')
353
+ return undefined;
354
+ const chunks = [];
355
+ for await (const c of req)
356
+ chunks.push(c);
357
+ const raw = Buffer.concat(chunks).toString('utf8');
358
+ if (!raw)
359
+ return undefined;
360
+ try {
361
+ return JSON.parse(raw);
362
+ }
363
+ catch {
364
+ return undefined;
365
+ }
366
+ }
367
+ /** 主线程鉴权(与 Engine 同一 token 表) */
368
+ export function authenticateRead(tokens, req) {
369
+ const hit = matchKnowledgeToken(tokens, req.headers.authorization);
370
+ if (!hit)
371
+ return null;
372
+ return { tenantId: hit.tenantId, gatewayId: hit.gatewayId };
373
+ }
@@ -12,12 +12,17 @@ export interface HybridSearchOptions {
12
12
  limit?: number;
13
13
  /** 仅关键词(跳过 embedding query) */
14
14
  keywordOnly?: boolean;
15
+ /** 跨 Gateway 隔离:registered_by ∪ public */
16
+ tenantId?: string;
17
+ gatewayId?: string;
15
18
  /**
16
19
  * 可选源过滤(与可见集求交,禁止越权)。
17
20
  * `sourceIds` 精确 id;`source` 为 displayName/id 模糊(单源)。
18
21
  */
19
22
  sourceIds?: string[];
20
23
  source?: string;
24
+ /** 覆盖实例级 recall(agents[].knowledge.recall / 全局) */
25
+ recall?: KnowledgeRecallMode;
21
26
  }
22
27
  export interface HybridSearchResult {
23
28
  hits: ChunkHit[];
@@ -27,6 +32,8 @@ export interface HybridSearchResult {
27
32
  /** 0–1:索引文件覆盖粗度(P2)× 向量覆盖(有 provider 时) */
28
33
  coverage: number;
29
34
  sourceIds: import('./types.js').KnowledgeSourceId[];
35
+ /** 向量后端(百万级应为 sqlite-vec) */
36
+ vectorBackend?: 'sqlite-vec' | 'js-bucket' | 'disabled';
30
37
  }
31
38
  export interface AutoGroundDecision {
32
39
  mode: GroundingMode;
@@ -36,15 +43,22 @@ export interface AutoGroundDecision {
36
43
  coverage: number;
37
44
  scoreFloor: number;
38
45
  }
46
+ /**
47
+ * 自动召回端口 — GroundingAssembler 只依赖此口。
48
+ * 本进程 KnowledgeRetriever 或 Knowledge Client 适配器均可实现。
49
+ */
50
+ export interface AutoGroundPort {
51
+ autoGround(query: string, opts: HybridSearchOptions): Promise<AutoGroundDecision>;
52
+ }
39
53
  export interface KnowledgeRetrieverOptions {
40
54
  sourceStore: KnowledgeSourceStore;
41
55
  indexStore: KnowledgeIndexStore;
42
56
  embeddingProvider?: EmbeddingProvider | null;
43
57
  /** hybrid 权重:keyword 相对(默认 0.45) */
44
58
  keywordWeight?: number;
45
- /** auto-inject 最低分(默认 0.78,语义分归一后) */
59
+ /** auto-inject 最低分(默认 0.72;绝对相关度空间) */
46
60
  injectMinScore?: number;
47
- /** hint 最低分(默认 0.55) */
61
+ /** hint 最低分(默认 0.50) */
48
62
  hintMinScore?: number;
49
63
  /** coverage 低于此值时抬高地板(默认 0.5) */
50
64
  minCoverage?: number;
@@ -75,7 +89,10 @@ export declare class KnowledgeRetriever {
75
89
  /**
76
90
  * 可见 sourceId 列表
77
91
  */
78
- visibleSourceIds(agentId: string, sessionId?: string): import('./types.js').KnowledgeSourceId[];
92
+ visibleSourceIds(agentId: string, sessionId?: string, identity?: {
93
+ tenantId?: string;
94
+ gatewayId?: string;
95
+ }): import('./types.js').KnowledgeSourceId[];
79
96
  /** 可见集 ∩ 请求过滤;无过滤时原样返回可见集 */
80
97
  private filterSourceIds;
81
98
  /**
@@ -83,8 +100,8 @@ export declare class KnowledgeRetriever {
83
100
  */
84
101
  search(query: string, opts: HybridSearchOptions): Promise<HybridSearchResult>;
85
102
  /**
86
- * auto-ground 分档(高分注入 / 中分 hint / 低分忽略);coverage 低时抬地板
87
- * 受 recall 模式约束:off/hint 会压制 inject
103
+ * auto-ground 分档(高分注入 / 中分 hint / 低分忽略);indexCoverage 低时抬地板
104
+ * 受 recall 模式约束:off/hint 会压制 inject;闲聊短查询直接 none
88
105
  */
89
106
  autoGround(query: string, opts: HybridSearchOptions): Promise<AutoGroundDecision>;
90
107
  private coverageFor;