@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,652 @@
1
+ /**
2
+ * Knowledge Service HTTP — 契约 arch/knowledge-service-http.md v2.1
3
+ *
4
+ * API 线程只编排:写走 KnowledgeWriteService(Writer Worker / Local),
5
+ * 读走 KnowledgeQueryService。**禁止**在此打开 knowledge.db。
6
+ * 纯读 GET 在主线程 `read-http.ts` 直达 Meta/Search,不经本层。
7
+ */
8
+ import { matchKnowledgeToken } from './http-bridge.js';
9
+ function json(res, status, payload) {
10
+ const buf = Buffer.from(JSON.stringify(payload), 'utf8');
11
+ res.writeHead(status, {
12
+ 'content-type': 'application/json; charset=utf-8',
13
+ 'content-length': buf.byteLength,
14
+ });
15
+ res.end(buf);
16
+ }
17
+ function err(res, status, code, message, details) {
18
+ json(res, status, { error: { code, message, details } });
19
+ }
20
+ function mapWriteError(res, e) {
21
+ const code = e.code ?? '';
22
+ const msg = e instanceof Error ? e.message : String(e);
23
+ if (code === 'not_resource_owner' || /not resource owner|not source owner|not project owner/i.test(msg)) {
24
+ err(res, 403, 'not_resource_owner', msg);
25
+ return true;
26
+ }
27
+ if (code === 'not_principal_owner' || /not principal owner/i.test(msg)) {
28
+ err(res, 403, 'not_principal_owner', msg);
29
+ return true;
30
+ }
31
+ if (code === 'principal_not_registered' || /principal not registered/i.test(msg)) {
32
+ err(res, 403, 'principal_not_registered', msg);
33
+ return true;
34
+ }
35
+ if (code === 'source_not_found' || /source not found/i.test(msg)) {
36
+ err(res, 404, 'source_not_found', msg);
37
+ return true;
38
+ }
39
+ if (code === 'project_not_empty' || /not empty|non-empty|仍有/i.test(msg)) {
40
+ err(res, 409, 'project_not_empty', msg);
41
+ return true;
42
+ }
43
+ return false;
44
+ }
45
+ async function readBody(req) {
46
+ if (req.method === 'GET' || req.method === 'HEAD')
47
+ return undefined;
48
+ const chunks = [];
49
+ for await (const c of req)
50
+ chunks.push(c);
51
+ const raw = Buffer.concat(chunks).toString('utf8');
52
+ if (!raw)
53
+ return undefined;
54
+ try {
55
+ return JSON.parse(raw);
56
+ }
57
+ catch {
58
+ return undefined;
59
+ }
60
+ }
61
+ export class KnowledgeHttpApp {
62
+ opts;
63
+ routes = [];
64
+ progressOff = null;
65
+ constructor(opts) {
66
+ this.opts = opts;
67
+ this.registerRoutes();
68
+ }
69
+ get write() {
70
+ return this.opts.write;
71
+ }
72
+ query() {
73
+ return this.opts.query;
74
+ }
75
+ identityOf(ctx) {
76
+ return { tenantId: ctx.tenantId, gatewayId: ctx.gatewayId };
77
+ }
78
+ route(method, pattern, handler) {
79
+ const keys = [];
80
+ const rx = pattern.replace(/:([a-zA-Z]+)/g, (_m, name) => {
81
+ keys.push(name);
82
+ return '([^/]+)';
83
+ });
84
+ this.routes.push({
85
+ method,
86
+ regex: new RegExp(`^${rx}$`),
87
+ keys,
88
+ handler,
89
+ });
90
+ }
91
+ registerRoutes() {
92
+ this.route('GET', '/health', (_req, res) => {
93
+ json(res, 200, { ok: true, service: 'knowledge', version: '0.60.0' });
94
+ });
95
+ this.route('GET', '/v1/ready', async (_req, res) => {
96
+ json(res, 200, await this.query().ready());
97
+ });
98
+ this.route('PUT', '/v1/principals/:agentId', async (_req, res, ctx, params, body) => {
99
+ const agentId = params.agentId;
100
+ await this.write.upsertPrincipal(this.identityOf(ctx), agentId, body ?? {});
101
+ json(res, 200, {
102
+ ok: true,
103
+ data: {
104
+ tenantId: ctx.tenantId,
105
+ gatewayId: ctx.gatewayId,
106
+ localAgentId: agentId,
107
+ ...body,
108
+ },
109
+ });
110
+ });
111
+ this.route('GET', '/v1/principals/:agentId', async (_req, res, ctx, params) => {
112
+ const row = await this.query().getPrincipal(this.identityOf(ctx), params.agentId);
113
+ if (!row)
114
+ return err(res, 404, 'principal_not_registered', 'principal not found');
115
+ json(res, 200, { ok: true, data: row });
116
+ });
117
+ this.route('GET', '/v1/projects', async (_req, res, ctx) => {
118
+ json(res, 200, {
119
+ ok: true,
120
+ data: await this.query().listProjects(this.identityOf(ctx)),
121
+ });
122
+ });
123
+ this.route('POST', '/v1/projects', async (_req, res, ctx, _p, body) => {
124
+ const b = body;
125
+ if (!b?.projectKey)
126
+ return err(res, 400, 'bad_request', 'projectKey required');
127
+ try {
128
+ const data = await this.write.createProject(this.identityOf(ctx), {
129
+ projectKey: b.projectKey,
130
+ displayName: b.displayName,
131
+ visibility: b.visibility,
132
+ });
133
+ json(res, 201, { ok: true, data });
134
+ }
135
+ catch (e) {
136
+ if (!mapWriteError(res, e)) {
137
+ err(res, 400, 'bad_request', e instanceof Error ? e.message : String(e));
138
+ }
139
+ }
140
+ });
141
+ this.route('DELETE', '/v1/projects/:projectKey', async (_req, res, ctx, params) => {
142
+ try {
143
+ const data = await this.write.removeProject(this.identityOf(ctx), params.projectKey);
144
+ json(res, 200, { ok: true, data });
145
+ }
146
+ catch (e) {
147
+ if (!mapWriteError(res, e)) {
148
+ err(res, 400, 'bad_request', e instanceof Error ? e.message : String(e));
149
+ }
150
+ }
151
+ });
152
+ this.route('GET', '/v1/events', (req, res, ctx) => {
153
+ res.writeHead(200, {
154
+ 'content-type': 'text/event-stream; charset=utf-8',
155
+ 'cache-control': 'no-cache',
156
+ connection: 'keep-alive',
157
+ });
158
+ const send = (event, data) => {
159
+ res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
160
+ };
161
+ send('hello', { tenantId: ctx.tenantId, gatewayId: ctx.gatewayId, ts: Date.now() });
162
+ const off = this.write.onProgress((evt) => {
163
+ const p = evt;
164
+ if (p?.sourceId && p.registeredBy != null) {
165
+ // 事件自带归属:禁止再 RPC Writer(重索引期会堵 abort)
166
+ if (p.tenantId && p.tenantId !== ctx.tenantId)
167
+ return;
168
+ if (p.registeredBy !== ctx.gatewayId && p.visibility !== 'public')
169
+ return;
170
+ send('knowledge.index.progress', evt);
171
+ return;
172
+ }
173
+ if (p?.sourceId) {
174
+ void this.write
175
+ .sourceVisibleToGateway(p.sourceId, ctx.gatewayId)
176
+ .then((ok) => {
177
+ if (ok)
178
+ send('knowledge.index.progress', evt);
179
+ })
180
+ .catch(() => undefined);
181
+ return;
182
+ }
183
+ send('knowledge.index.progress', evt);
184
+ });
185
+ req.on('close', () => {
186
+ off();
187
+ res.end();
188
+ });
189
+ });
190
+ this.route('GET', '/v1/sources', async (req, res, ctx) => {
191
+ const url = new URL(req.url ?? '/v1/sources', 'http://internal');
192
+ const scopeLevel = url.searchParams.get('scopeLevel');
193
+ const projectKey = url.searchParams.get('projectKey') ?? undefined;
194
+ const sessionId = url.searchParams.get('sessionId') ?? undefined;
195
+ const list = await this.query().listSources({
196
+ ...(scopeLevel === 'global' || scopeLevel === 'project' || scopeLevel === 'session'
197
+ ? { scopeLevel }
198
+ : {}),
199
+ ...(projectKey != null && projectKey !== '' ? { projectKey } : {}),
200
+ ...(sessionId != null && sessionId !== '' ? { sessionId } : {}),
201
+ identity: this.identityOf(ctx),
202
+ });
203
+ json(res, 200, { ok: true, data: list });
204
+ });
205
+ this.route('POST', '/v1/sources', async (_req, res, ctx, _p, body) => {
206
+ if (!body || typeof body !== 'object') {
207
+ return err(res, 400, 'bad_request', 'body required');
208
+ }
209
+ try {
210
+ const data = await this.write.registerSource(this.identityOf(ctx), body);
211
+ json(res, 201, { ok: true, data });
212
+ }
213
+ catch (e) {
214
+ if (!mapWriteError(res, e)) {
215
+ err(res, 400, 'bad_request', e instanceof Error ? e.message : String(e));
216
+ }
217
+ }
218
+ });
219
+ this.route('GET', '/v1/sources/:sid', async (_req, res, ctx, params) => {
220
+ const detail = await this.query().getSourceDetail(params.sid, this.identityOf(ctx));
221
+ if (!detail) {
222
+ return err(res, 404, 'source_not_found', 'source not found');
223
+ }
224
+ json(res, 200, {
225
+ ok: true,
226
+ data: {
227
+ ...detail.source,
228
+ stats: detail.stats,
229
+ jobControl: detail.jobControl,
230
+ assignedAgentIds: detail.assignedAgentIds,
231
+ hiddenForAgentIds: detail.hiddenForAgentIds,
232
+ },
233
+ });
234
+ });
235
+ this.route('PATCH', '/v1/sources/:sid', async (_req, res, ctx, params, body) => {
236
+ try {
237
+ const updated = await this.write.updateSource(this.identityOf(ctx), params.sid, body ?? {});
238
+ if (!updated)
239
+ return err(res, 404, 'source_not_found', 'source not found');
240
+ json(res, 200, { ok: true, data: updated });
241
+ }
242
+ catch (e) {
243
+ if (!mapWriteError(res, e)) {
244
+ err(res, 400, 'bad_request', e instanceof Error ? e.message : String(e));
245
+ }
246
+ }
247
+ });
248
+ this.route('DELETE', '/v1/sources/:sid', async (_req, res, ctx, params) => {
249
+ try {
250
+ const data = await this.write.removeSource(this.identityOf(ctx), params.sid);
251
+ json(res, 200, { ok: true, data });
252
+ }
253
+ catch (e) {
254
+ if (!mapWriteError(res, e)) {
255
+ err(res, 400, 'bad_request', e instanceof Error ? e.message : String(e));
256
+ }
257
+ }
258
+ });
259
+ this.route('POST', '/v1/sources/:sid/reindex', async (_req, res, ctx, params) => {
260
+ if (!(await this.write.isSourceOwner(params.sid, ctx.gatewayId))) {
261
+ return err(res, 403, 'not_resource_owner', 'not source owner');
262
+ }
263
+ await this.write.reindexSource(params.sid);
264
+ json(res, 202, { ok: true, data: { sourceId: params.sid, accepted: true } });
265
+ });
266
+ this.route('POST', '/v1/sources/:sid/reprocess', async (_req, res, ctx, params, body) => {
267
+ if (!(await this.write.isSourceOwner(params.sid, ctx.gatewayId))) {
268
+ return err(res, 403, 'not_resource_owner', 'not source owner');
269
+ }
270
+ const sid = params.sid;
271
+ const b = (body ?? {});
272
+ const paths = Array.isArray(b.paths)
273
+ ? b.paths.filter((p) => typeof p === 'string' && p.length > 0)
274
+ : [];
275
+ const filter = b.filter;
276
+ const hasFilter = filter != null &&
277
+ (filter.status != null || filter.ext != null || filter.q != null);
278
+ try {
279
+ if (paths.length > 0) {
280
+ const data = await this.write.reprocessFiles(sid, paths);
281
+ return json(res, 200, { ok: true, data });
282
+ }
283
+ if (hasFilter) {
284
+ const data = await this.write.reprocessByFilter(sid, filter);
285
+ return json(res, 200, { ok: true, data });
286
+ }
287
+ err(res, 400, 'bad_request', 'paths or filter required');
288
+ }
289
+ catch (e) {
290
+ if (!mapWriteError(res, e)) {
291
+ err(res, 400, 'bad_request', e instanceof Error ? e.message : String(e));
292
+ }
293
+ }
294
+ });
295
+ this.route('POST', '/v1/sources/:sid/abort', async (_req, res, ctx, params) => {
296
+ if (!(await this.write.isSourceOwner(params.sid, ctx.gatewayId))) {
297
+ return err(res, 403, 'not_resource_owner', 'not source owner');
298
+ }
299
+ json(res, 200, { ok: true, data: await this.write.abortSource(params.sid) });
300
+ });
301
+ this.route('POST', '/v1/sources/:sid/resume', async (_req, res, ctx, params) => {
302
+ if (!(await this.write.isSourceOwner(params.sid, ctx.gatewayId))) {
303
+ return err(res, 403, 'not_resource_owner', 'not source owner');
304
+ }
305
+ json(res, 200, { ok: true, data: await this.write.resumeSource(params.sid) });
306
+ });
307
+ this.route('POST', '/v1/sources/:sid/describe', async (_req, res, ctx, params) => {
308
+ try {
309
+ const data = await this.write.describeSource(this.identityOf(ctx), params.sid);
310
+ if (!data)
311
+ return err(res, 404, 'source_not_found', 'source not found');
312
+ json(res, 200, { ok: true, data });
313
+ }
314
+ catch (e) {
315
+ if (!mapWriteError(res, e)) {
316
+ err(res, 400, 'bad_request', e instanceof Error ? e.message : String(e));
317
+ }
318
+ }
319
+ });
320
+ this.route('POST', '/v1/jobs/abort', async (_req, res, ctx) => {
321
+ json(res, 200, { ok: true, data: await this.write.abortAllOwned(this.identityOf(ctx)) });
322
+ });
323
+ this.route('POST', '/v1/jobs/resume', async (_req, res, ctx) => {
324
+ json(res, 200, { ok: true, data: await this.write.resumeAllOwned(this.identityOf(ctx)) });
325
+ });
326
+ this.route('GET', '/v1/sources/:sid/files', async (req, res, ctx, params) => {
327
+ if (!(await this.write.isSourceOwner(params.sid, ctx.gatewayId))) {
328
+ return err(res, 403, 'not_resource_owner', 'not source owner');
329
+ }
330
+ const url = new URL(req.url ?? '/', 'http://local');
331
+ const paged = url.searchParams.has('page') ||
332
+ url.searchParams.has('pageSize') ||
333
+ url.searchParams.has('status') ||
334
+ url.searchParams.has('ext') ||
335
+ url.searchParams.has('q');
336
+ if (paged) {
337
+ const status = url.searchParams.get('status') ?? undefined;
338
+ const data = await this.query().listFilesPaged(params.sid, {
339
+ ...(status === 'indexed' || status === 'skipped' || status === 'error' || status === 'all'
340
+ ? { status }
341
+ : {}),
342
+ ...(url.searchParams.get('ext') ? { ext: url.searchParams.get('ext') } : {}),
343
+ ...(url.searchParams.get('q') ? { q: url.searchParams.get('q') } : {}),
344
+ ...(url.searchParams.get('page')
345
+ ? { page: Number(url.searchParams.get('page')) }
346
+ : {}),
347
+ ...(url.searchParams.get('pageSize')
348
+ ? { pageSize: Number(url.searchParams.get('pageSize')) }
349
+ : {}),
350
+ }, this.identityOf(ctx));
351
+ return json(res, 200, { ok: true, data });
352
+ }
353
+ json(res, 200, {
354
+ ok: true,
355
+ data: await this.query().listFiles(params.sid, this.identityOf(ctx)),
356
+ });
357
+ });
358
+ this.route('GET', '/v1/principals/:agentId/search', async (req, res, ctx, params) => {
359
+ const url = new URL(req.url ?? '/', 'http://local');
360
+ await this.write.ensurePrincipal(this.identityOf(ctx), params.agentId, this.opts.autoRegisterPrincipals ?? true);
361
+ const result = await this.query().search({
362
+ agentId: params.agentId,
363
+ q: url.searchParams.get('q') ?? '',
364
+ sessionId: url.searchParams.get('sessionId') ?? undefined,
365
+ limit: Number(url.searchParams.get('limit') ?? 8),
366
+ identity: this.identityOf(ctx),
367
+ });
368
+ json(res, 200, { ok: true, data: result });
369
+ });
370
+ this.route('GET', '/v1/principals/:agentId/ground', async (req, res, ctx, params) => {
371
+ const url = new URL(req.url ?? '/', 'http://local');
372
+ await this.write.ensurePrincipal(this.identityOf(ctx), params.agentId, this.opts.autoRegisterPrincipals ?? true);
373
+ const recallRaw = url.searchParams.get('recall');
374
+ const recall = recallRaw === 'off' || recallRaw === 'hint' || recallRaw === 'hybrid' || recallRaw === 'inject'
375
+ ? recallRaw
376
+ : undefined;
377
+ const result = await this.query().autoGround({
378
+ agentId: params.agentId,
379
+ q: url.searchParams.get('q') ?? '',
380
+ sessionId: url.searchParams.get('sessionId') ?? undefined,
381
+ limit: Number(url.searchParams.get('limit') ?? 8),
382
+ ...(recall ? { recall } : {}),
383
+ identity: this.identityOf(ctx),
384
+ });
385
+ json(res, 200, { ok: true, data: result });
386
+ });
387
+ this.route('GET', '/v1/principals/:agentId/stats', async (_req, res, ctx, params) => {
388
+ await this.write.ensurePrincipal(this.identityOf(ctx), params.agentId, this.opts.autoRegisterPrincipals ?? true);
389
+ const principal = await this.query().principalStats(params.agentId, this.identityOf(ctx));
390
+ json(res, 200, {
391
+ ok: true,
392
+ data: {
393
+ ...principal.stats,
394
+ visibility: principal.visibility,
395
+ visibleSources: principal.visibleSources,
396
+ },
397
+ });
398
+ });
399
+ this.route('GET', '/v1/principals/:agentId/catalog', async (_req, res, ctx, params) => {
400
+ await this.write.ensurePrincipal(this.identityOf(ctx), params.agentId, this.opts.autoRegisterPrincipals ?? true);
401
+ json(res, 200, {
402
+ ok: true,
403
+ data: await this.query().catalog(params.agentId, this.identityOf(ctx)),
404
+ });
405
+ });
406
+ this.route('GET', '/v1/principals/:agentId/chunks', async (req, res, ctx, params) => {
407
+ await this.write.ensurePrincipal(this.identityOf(ctx), params.agentId, this.opts.autoRegisterPrincipals ?? true);
408
+ const url = new URL(req.url ?? '/', 'http://local');
409
+ const sourceId = url.searchParams.get('sourceId') ?? '';
410
+ const path = url.searchParams.get('path') ?? '';
411
+ if (!sourceId || !path) {
412
+ return err(res, 400, 'bad_request', 'sourceId and path required');
413
+ }
414
+ const data = await this.query().listChunks(params.agentId, sourceId, path, this.identityOf(ctx), ctx.sessionId);
415
+ if (data == null) {
416
+ return err(res, 404, 'file_not_found', 'source not found');
417
+ }
418
+ json(res, 200, { ok: true, data });
419
+ });
420
+ this.route('POST', '/v1/principals/:agentId/read', async (_req, res, ctx, params, body) => {
421
+ await this.write.ensurePrincipal(this.identityOf(ctx), params.agentId, this.opts.autoRegisterPrincipals ?? true);
422
+ const b = body;
423
+ if (!b?.chunkId && (!b?.sourceId || !b?.path)) {
424
+ return err(res, 400, 'bad_request', 'chunkId or (sourceId+path) required');
425
+ }
426
+ if (b.chunkId) {
427
+ const data = await this.query().read(params.agentId, b, this.identityOf(ctx), ctx.sessionId);
428
+ if (!data.found) {
429
+ return err(res, 404, 'file_not_found', 'chunk not found');
430
+ }
431
+ return json(res, 200, { ok: true, data });
432
+ }
433
+ const chunks = await this.query().listChunks(params.agentId, b.sourceId, b.path, this.identityOf(ctx), ctx.sessionId);
434
+ if (chunks == null) {
435
+ return err(res, 404, 'source_not_found', 'source not found');
436
+ }
437
+ json(res, 200, {
438
+ ok: true,
439
+ data: {
440
+ found: chunks.length > 0,
441
+ path: b.path,
442
+ chunkCount: chunks.length,
443
+ text: chunks.map((c) => c.text).join('\n\n'),
444
+ chunks,
445
+ },
446
+ });
447
+ });
448
+ this.route('GET', '/v1/principals/:agentId/visibility', async (_req, res, ctx, params) => {
449
+ await this.write.ensurePrincipal(this.identityOf(ctx), params.agentId, this.opts.autoRegisterPrincipals ?? true);
450
+ json(res, 200, {
451
+ ok: true,
452
+ data: await this.query().visibility(params.agentId, this.identityOf(ctx)),
453
+ });
454
+ });
455
+ this.route('POST', '/v1/principals/:agentId/visibility', async (_req, res, ctx, params, body) => {
456
+ const agentId = params.agentId;
457
+ await this.write.ensurePrincipal(this.identityOf(ctx), agentId, this.opts.autoRegisterPrincipals ?? true);
458
+ await this.write.assertOwnPrincipal(this.identityOf(ctx), agentId);
459
+ const identity = this.identityOf(ctx);
460
+ const op = body?.op;
461
+ const projectKey = body?.projectKey;
462
+ const sourceId = body?.sourceId;
463
+ try {
464
+ if (op === 'assignProject' && projectKey) {
465
+ await this.write.assignProject(identity, agentId, projectKey);
466
+ }
467
+ else if (op === 'unassignProject' && projectKey) {
468
+ await this.write.unassignProject(identity, agentId, projectKey);
469
+ }
470
+ else if (op === 'hide' && sourceId) {
471
+ await this.write.hideSource(identity, agentId, sourceId);
472
+ }
473
+ else if (op === 'unhide' && sourceId) {
474
+ await this.write.unhideSource(identity, agentId, sourceId);
475
+ }
476
+ else {
477
+ return err(res, 400, 'bad_request', 'unknown visibility op');
478
+ }
479
+ json(res, 200, { ok: true, data: { op, projectKey, sourceId } });
480
+ }
481
+ catch (e) {
482
+ if (!mapWriteError(res, e)) {
483
+ err(res, 400, 'bad_request', e instanceof Error ? e.message : String(e));
484
+ }
485
+ }
486
+ });
487
+ this.route('GET', '/v1/principals/:agentId/session-visibility', async (req, res, ctx, params) => {
488
+ const agentId = params.agentId;
489
+ await this.write.ensurePrincipal(this.identityOf(ctx), agentId, this.opts.autoRegisterPrincipals ?? true);
490
+ await this.write.assertOwnPrincipal(this.identityOf(ctx), agentId);
491
+ const url = new URL(req.url ?? '/', 'http://local');
492
+ const sessionId = url.searchParams.get('sessionId') ?? '';
493
+ if (!sessionId)
494
+ return err(res, 400, 'session_required', 'sessionId required');
495
+ json(res, 200, {
496
+ ok: true,
497
+ data: await this.query().sessionVisibility(agentId, sessionId, this.identityOf(ctx)),
498
+ });
499
+ });
500
+ this.route('PUT', '/v1/principals/:agentId/session-visibility', async (_req, res, ctx, params, body) => {
501
+ const agentId = params.agentId;
502
+ await this.write.ensurePrincipal(this.identityOf(ctx), agentId, this.opts.autoRegisterPrincipals ?? true);
503
+ await this.write.assertOwnPrincipal(this.identityOf(ctx), agentId);
504
+ const b = body;
505
+ const sessionId = b?.sessionId;
506
+ if (!sessionId)
507
+ return err(res, 400, 'bad_request', 'sessionId required');
508
+ try {
509
+ const count = await this.write.replaceSessionVisibility(this.identityOf(ctx), agentId, sessionId, (b.items ?? []));
510
+ json(res, 200, { ok: true, data: { sessionId, count } });
511
+ }
512
+ catch (e) {
513
+ if (!mapWriteError(res, e)) {
514
+ err(res, 400, 'bad_request', e instanceof Error ? e.message : String(e));
515
+ }
516
+ }
517
+ });
518
+ this.route('POST', '/v1/principals/:agentId/session-visibility', async (_req, res, ctx, params, body) => {
519
+ const agentId = params.agentId;
520
+ await this.write.ensurePrincipal(this.identityOf(ctx), agentId, this.opts.autoRegisterPrincipals ?? true);
521
+ await this.write.assertOwnPrincipal(this.identityOf(ctx), agentId);
522
+ const item = body;
523
+ if (!item?.sessionId || !item.targetType || !item.targetId || !item.op) {
524
+ return err(res, 400, 'bad_request', 'sessionId/targetType/targetId/op required');
525
+ }
526
+ await this.write.setSessionVisibilityItem(this.identityOf(ctx), item.sessionId, {
527
+ targetType: item.targetType,
528
+ targetId: item.targetId,
529
+ op: item.op,
530
+ });
531
+ json(res, 200, { ok: true, data: item });
532
+ });
533
+ this.route('DELETE', '/v1/principals/:agentId/session-visibility', async (req, res, ctx, params) => {
534
+ const agentId = params.agentId;
535
+ await this.write.ensurePrincipal(this.identityOf(ctx), agentId, this.opts.autoRegisterPrincipals ?? true);
536
+ await this.write.assertOwnPrincipal(this.identityOf(ctx), agentId);
537
+ const url = new URL(req.url ?? '/', 'http://local');
538
+ const sessionId = url.searchParams.get('sessionId') ?? '';
539
+ if (!sessionId)
540
+ return err(res, 400, 'session_required', 'sessionId required');
541
+ const targetType = url.searchParams.get('targetType');
542
+ const targetId = url.searchParams.get('targetId');
543
+ if (targetType && targetId) {
544
+ await this.write.clearSessionVisibility(this.identityOf(ctx), sessionId, {
545
+ targetType: targetType,
546
+ targetId,
547
+ });
548
+ json(res, 200, { ok: true, data: { sessionId, targetType, targetId } });
549
+ return;
550
+ }
551
+ await this.write.clearSessionVisibility(this.identityOf(ctx), sessionId);
552
+ json(res, 200, { ok: true, data: { sessionId, cleared: true } });
553
+ });
554
+ this.route('GET', '/v1/jobs', async (req, res, ctx) => {
555
+ const url = new URL(req.url ?? '/', 'http://local');
556
+ json(res, 200, {
557
+ ok: true,
558
+ data: await this.query().listJobs({
559
+ identity: this.identityOf(ctx),
560
+ sourceId: url.searchParams.get('sourceId') ?? undefined,
561
+ status: url.searchParams.get('status') ?? undefined,
562
+ }),
563
+ });
564
+ });
565
+ this.route('GET', '/v1/jobs/control', async (req, res, ctx) => {
566
+ const url = new URL(req.url ?? '/', 'http://local');
567
+ const sourceId = url.searchParams.get('sourceId') ?? '';
568
+ if (!sourceId)
569
+ return err(res, 400, 'bad_request', 'sourceId required');
570
+ if (!(await this.write.isSourceOwner(sourceId, ctx.gatewayId))) {
571
+ return err(res, 403, 'not_resource_owner', 'not source owner');
572
+ }
573
+ const detail = await this.query().getSourceDetail(sourceId, this.identityOf(ctx));
574
+ if (!detail)
575
+ return err(res, 404, 'source_not_found', 'source not found');
576
+ json(res, 200, { ok: true, data: detail.jobControl });
577
+ });
578
+ this.route('GET', '/v1/promotion-candidates', async (_req, res) => {
579
+ json(res, 200, { ok: true, data: await this.query().promotionCandidates() });
580
+ });
581
+ }
582
+ /** 拉起 ingest 运行时(Service 入口调用一次;实现落在 Writer) */
583
+ startIngestRuntime() {
584
+ void this.write.startIngestRuntime().catch((e) => {
585
+ console.warn(`[Knowledge] startIngestRuntime failed: ${e instanceof Error ? e.message : String(e)}`);
586
+ });
587
+ }
588
+ dispose() {
589
+ this.progressOff?.();
590
+ this.progressOff = null;
591
+ return this.write.dispose();
592
+ }
593
+ handle = async (req, res) => {
594
+ try {
595
+ const url = new URL(req.url ?? '/', 'http://local');
596
+ const path = url.pathname.replace(/\/+$/, '') || '/';
597
+ const method = (req.method ?? 'GET').toUpperCase();
598
+ if (method === 'OPTIONS') {
599
+ res.writeHead(204);
600
+ res.end();
601
+ return;
602
+ }
603
+ const auth = this.authenticate(req);
604
+ if (!auth && path !== '/health') {
605
+ return err(res, 401, 'unauthorized', 'missing or invalid token');
606
+ }
607
+ const ctx = auth ?? {
608
+ tenantId: 'anonymous',
609
+ gatewayId: 'anonymous',
610
+ };
611
+ const headerAgent = req.headers['x-octopi-agent'];
612
+ const headerSession = req.headers['x-octopi-session'];
613
+ if (typeof headerAgent === 'string' && headerAgent)
614
+ ctx.agentId = headerAgent;
615
+ if (typeof headerSession === 'string' && headerSession)
616
+ ctx.sessionId = headerSession;
617
+ for (const r of this.routes) {
618
+ if (r.method !== method)
619
+ continue;
620
+ const m = r.regex.exec(path);
621
+ if (!m)
622
+ continue;
623
+ const params = {};
624
+ r.keys.forEach((k, i) => {
625
+ params[k] = m[i + 1] ?? '';
626
+ });
627
+ const body = await readBody(req);
628
+ await r.handler(req, res, ctx, params, body);
629
+ return;
630
+ }
631
+ err(res, 404, 'not_found', `no route ${method} ${path}`);
632
+ }
633
+ catch (e) {
634
+ if (mapWriteError(res, e))
635
+ return;
636
+ const code = e.code ?? (e instanceof Error ? e.message : 'internal_error');
637
+ err(res, 500, 'internal_error', String(code));
638
+ }
639
+ };
640
+ authenticate(req) {
641
+ const hit = matchKnowledgeToken(this.opts.tokens, req.headers.authorization);
642
+ if (!hit)
643
+ return null;
644
+ return { tenantId: hit.tenantId, gatewayId: hit.gatewayId };
645
+ }
646
+ }
647
+ /**
648
+ * 创建 HTTP 编排层(写/读端口注入;不碰 SQLite)。
649
+ */
650
+ export function createKnowledgeHttpApp(opts) {
651
+ return new KnowledgeHttpApp(opts);
652
+ }