@octopi-agent/engine 0.56.0 → 0.65.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (175) hide show
  1. package/dist/config-schema/context.d.ts +1 -1
  2. package/dist/config-schema/context.js +1 -1
  3. package/dist/config-schema/engine.d.ts +43 -1
  4. package/dist/config-schema/substrate.d.ts +42 -0
  5. package/dist/config-schema/substrate.js +58 -0
  6. package/dist/config.d.ts +39 -1
  7. package/dist/harness/agent/builder.d.ts +14 -0
  8. package/dist/harness/agent/builder.js +14 -2
  9. package/dist/harness/agent/config-bridge.js +3 -0
  10. package/dist/harness/{context/capabilities → capabilities}/document/backends/docx.d.ts +1 -1
  11. package/dist/harness/{context/capabilities → capabilities}/document/backends/docx.js +1 -1
  12. package/dist/harness/{context/capabilities → capabilities}/document/backends/office-parser.d.ts +1 -1
  13. package/dist/harness/{context/capabilities → capabilities}/document/backends/office-parser.js +1 -1
  14. package/dist/harness/{context/capabilities → capabilities}/document/backends/pdf.d.ts +1 -1
  15. package/dist/harness/{context/capabilities → capabilities}/document/backends/pdf.js +13 -3
  16. package/dist/harness/{context/capabilities → capabilities}/document/backends/plain.d.ts +1 -1
  17. package/dist/harness/{context/capabilities → capabilities}/document/backends/plain.js +13 -4
  18. package/dist/harness/{context/capabilities → capabilities}/document/backends/sheet.d.ts +1 -1
  19. package/dist/harness/{context/capabilities → capabilities}/document/backends/sheet.js +25 -5
  20. package/dist/harness/{context/capabilities → capabilities}/document/backends/xmind.d.ts +1 -1
  21. package/dist/harness/{context/capabilities → capabilities}/document/backends/xmind.js +1 -1
  22. package/dist/harness/{context/capabilities → capabilities}/document/errors.d.ts +1 -1
  23. package/dist/harness/{context/capabilities → capabilities}/document/errors.js +1 -1
  24. package/dist/harness/capabilities/document/factory.d.ts +33 -0
  25. package/dist/harness/capabilities/document/factory.js +37 -0
  26. package/dist/harness/{context/capabilities → capabilities}/document/format.d.ts +1 -1
  27. package/dist/harness/{context/capabilities → capabilities}/document/format.js +1 -1
  28. package/dist/harness/{context/capabilities → capabilities}/document/html-to-md.d.ts +1 -1
  29. package/dist/harness/{context/capabilities → capabilities}/document/html-to-md.js +1 -1
  30. package/dist/harness/{context/capabilities → capabilities}/document/index.d.ts +3 -1
  31. package/dist/harness/{context/capabilities → capabilities}/document/index.js +2 -1
  32. package/dist/harness/{context/capabilities → capabilities}/document/legacy/factory.d.ts +3 -1
  33. package/dist/harness/{context/capabilities → capabilities}/document/legacy/factory.js +3 -1
  34. package/dist/harness/{context/capabilities → capabilities}/document/legacy/soffice.d.ts +3 -1
  35. package/dist/harness/{context/capabilities → capabilities}/document/legacy/soffice.js +44 -1
  36. package/dist/harness/{context/capabilities → capabilities}/document/port.d.ts +1 -1
  37. package/dist/harness/{context/capabilities → capabilities}/document/port.js +4 -4
  38. package/dist/harness/{context/capabilities → capabilities}/document/types.d.ts +11 -1
  39. package/dist/harness/{context/capabilities → capabilities}/document/types.js +1 -1
  40. package/dist/harness/capabilities/document/worker-port.d.ts +13 -0
  41. package/dist/harness/capabilities/document/worker-port.js +78 -0
  42. package/dist/harness/context/capabilities/index.d.ts +2 -2
  43. package/dist/harness/context/capabilities/index.js +2 -2
  44. package/dist/harness/context/constitution/default-agents.md +1 -0
  45. package/dist/harness/context/index.d.ts +2 -2
  46. package/dist/harness/context/index.js +1 -1
  47. package/dist/harness/context/layer-types.d.ts +26 -2
  48. package/dist/harness/context/layer-types.js +59 -11
  49. package/dist/harness/context/layers.d.ts +3 -0
  50. package/dist/harness/context/layers.js +38 -12
  51. package/dist/harness/context/system-prompt-assembler.d.ts +5 -0
  52. package/dist/harness/context/system-prompt-assembler.js +2 -0
  53. package/dist/harness/extension/plugin-ecosystem/tools/knowledge.d.ts +10 -0
  54. package/dist/harness/extension/plugin-ecosystem/tools/knowledge.js +115 -5
  55. package/dist/harness/extension/plugin-ecosystem/tools/memory.js +3 -0
  56. package/dist/harness/index.d.ts +5 -3
  57. package/dist/harness/index.js +3 -2
  58. package/dist/harness/knowledge/adapters.d.ts +8 -5
  59. package/dist/harness/knowledge/adapters.js +53 -13
  60. package/dist/harness/knowledge/catalog-types.d.ts +4 -0
  61. package/dist/harness/knowledge/client.d.ts +197 -0
  62. package/dist/harness/knowledge/client.js +237 -0
  63. package/dist/harness/knowledge/connector-fetcher.d.ts +2 -2
  64. package/dist/harness/knowledge/connectors.d.ts +3 -3
  65. package/dist/harness/knowledge/connectors.js +14 -8
  66. package/dist/harness/knowledge/db.d.ts +42 -3
  67. package/dist/harness/knowledge/db.js +466 -83
  68. package/dist/harness/knowledge/describe.d.ts +2 -0
  69. package/dist/harness/knowledge/describe.js +5 -1
  70. package/dist/harness/knowledge/document-extract-worker.d.ts +1 -0
  71. package/dist/harness/knowledge/document-extract-worker.js +68 -0
  72. package/dist/harness/knowledge/embed-runner.d.ts +53 -0
  73. package/dist/harness/knowledge/embed-runner.js +171 -0
  74. package/dist/harness/knowledge/engine-thread.d.ts +1 -0
  75. package/dist/harness/knowledge/engine-thread.js +302 -0
  76. package/dist/harness/knowledge/extract-document.d.ts +33 -0
  77. package/dist/harness/knowledge/extract-document.js +86 -0
  78. package/dist/harness/knowledge/fetchers.d.ts +14 -3
  79. package/dist/harness/knowledge/fetchers.js +52 -16
  80. package/dist/harness/knowledge/file-identity.d.ts +53 -0
  81. package/dist/harness/knowledge/file-identity.js +172 -0
  82. package/dist/harness/knowledge/file-index-store.d.ts +50 -0
  83. package/dist/harness/knowledge/file-index-store.js +132 -0
  84. package/dist/harness/knowledge/file-limits.d.ts +86 -0
  85. package/dist/harness/knowledge/file-limits.js +175 -0
  86. package/dist/harness/knowledge/fts.d.ts +60 -0
  87. package/dist/harness/knowledge/fts.js +218 -0
  88. package/dist/harness/knowledge/grounding.d.ts +3 -2
  89. package/dist/harness/knowledge/http-app.d.ts +50 -0
  90. package/dist/harness/knowledge/http-app.js +652 -0
  91. package/dist/harness/knowledge/http-bridge.d.ts +49 -0
  92. package/dist/harness/knowledge/http-bridge.js +17 -0
  93. package/dist/harness/knowledge/index-store.d.ts +166 -63
  94. package/dist/harness/knowledge/index-store.js +1025 -282
  95. package/dist/harness/knowledge/index.d.ts +47 -5
  96. package/dist/harness/knowledge/index.js +24 -2
  97. package/dist/harness/knowledge/ingest.d.ts +322 -49
  98. package/dist/harness/knowledge/ingest.js +1383 -267
  99. package/dist/harness/knowledge/job-control-state.d.ts +29 -0
  100. package/dist/harness/knowledge/job-control-state.js +44 -0
  101. package/dist/harness/knowledge/job-control.d.ts +35 -0
  102. package/dist/harness/knowledge/job-control.js +86 -0
  103. package/dist/harness/knowledge/job-queue.d.ts +62 -0
  104. package/dist/harness/knowledge/job-queue.js +173 -0
  105. package/dist/harness/knowledge/knowledge-serve-child.d.ts +1 -0
  106. package/dist/harness/knowledge/knowledge-serve-child.js +100 -0
  107. package/dist/harness/knowledge/local-stack.d.ts +27 -0
  108. package/dist/harness/knowledge/local-stack.js +63 -0
  109. package/dist/harness/knowledge/membership-store.d.ts +65 -0
  110. package/dist/harness/knowledge/membership-store.js +198 -0
  111. package/dist/harness/knowledge/network-guard.d.ts +11 -2
  112. package/dist/harness/knowledge/network-guard.js +130 -85
  113. package/dist/harness/knowledge/parse-text-in-worker.d.ts +32 -0
  114. package/dist/harness/knowledge/parse-text-in-worker.js +158 -0
  115. package/dist/harness/knowledge/query-service.d.ts +272 -0
  116. package/dist/harness/knowledge/query-service.js +326 -0
  117. package/dist/harness/knowledge/query-worker-client.d.ts +96 -0
  118. package/dist/harness/knowledge/query-worker-client.js +207 -0
  119. package/dist/harness/knowledge/query-worker.d.ts +1 -0
  120. package/dist/harness/knowledge/query-worker.js +186 -0
  121. package/dist/harness/knowledge/read-http.d.ts +35 -0
  122. package/dist/harness/knowledge/read-http.js +373 -0
  123. package/dist/harness/knowledge/retriever.d.ts +30 -5
  124. package/dist/harness/knowledge/retriever.js +98 -35
  125. package/dist/harness/knowledge/secret-scan.d.ts +13 -2
  126. package/dist/harness/knowledge/secret-scan.js +25 -2
  127. package/dist/harness/knowledge/serve.d.ts +48 -0
  128. package/dist/harness/knowledge/serve.js +336 -0
  129. package/dist/harness/knowledge/source-store.d.ts +83 -16
  130. package/dist/harness/knowledge/source-store.js +205 -78
  131. package/dist/harness/knowledge/start-service-process.d.ts +49 -0
  132. package/dist/harness/knowledge/start-service-process.js +158 -0
  133. package/dist/harness/knowledge/text-parse-worker.d.ts +1 -0
  134. package/dist/harness/knowledge/text-parse-worker.js +54 -0
  135. package/dist/harness/knowledge/topics.d.ts +13 -0
  136. package/dist/harness/knowledge/topics.js +48 -0
  137. package/dist/harness/knowledge/types.d.ts +1 -1
  138. package/dist/harness/knowledge/types.js +1 -1
  139. package/dist/harness/knowledge/vector-ann.d.ts +42 -0
  140. package/dist/harness/knowledge/vector-ann.js +68 -0
  141. package/dist/harness/knowledge/writer-lock.d.ts +13 -0
  142. package/dist/harness/knowledge/writer-lock.js +71 -0
  143. package/dist/harness/knowledge/writer-service.d.ts +194 -0
  144. package/dist/harness/knowledge/writer-service.js +355 -0
  145. package/dist/harness/knowledge/writer-worker-client.d.ts +102 -0
  146. package/dist/harness/knowledge/writer-worker-client.js +381 -0
  147. package/dist/harness/knowledge/writer-worker.d.ts +1 -0
  148. package/dist/harness/knowledge/writer-worker.js +189 -0
  149. package/dist/harness/memory/index.d.ts +3 -2
  150. package/dist/harness/memory/index.js +3 -1
  151. package/dist/harness/memory/retrieval-rank.d.ts +51 -0
  152. package/dist/harness/memory/retrieval-rank.js +60 -0
  153. package/dist/harness/memory/sqlite/embedding.d.ts +5 -2
  154. package/dist/harness/memory/sqlite/embedding.js +109 -16
  155. package/dist/harness/memory/sqlite/index.d.ts +2 -2
  156. package/dist/harness/memory/sqlite/index.js +1 -1
  157. package/dist/harness/memory/sqlite/keyword-search.d.ts +41 -2
  158. package/dist/harness/memory/sqlite/keyword-search.js +104 -17
  159. package/dist/harness/memory/sqlite/memory-store.d.ts +18 -4
  160. package/dist/harness/memory/sqlite/memory-store.js +89 -39
  161. package/dist/harness/memory/store.js +39 -21
  162. package/dist/harness/memory/types.d.ts +7 -0
  163. package/dist/harness/run/runner.d.ts +1 -0
  164. package/dist/harness/run/runner.js +4 -2
  165. package/dist/harness/session/attachments/service.d.ts +1 -1
  166. package/dist/harness/session/attachments/service.js +1 -1
  167. package/dist/harness/session/tasks/index.d.ts +1 -1
  168. package/dist/harness/session/tasks/index.js +1 -1
  169. package/dist/harness/session/tasks/render.d.ts +10 -0
  170. package/dist/harness/session/tasks/render.js +27 -0
  171. package/dist/index.d.ts +4 -2
  172. package/dist/index.js +2 -1
  173. package/dist/worker-path.d.ts +8 -0
  174. package/dist/worker-path.js +15 -0
  175. package/package.json +2 -2
@@ -0,0 +1,197 @@
1
+ /**
2
+ * KnowledgeClient — Gateway 侧 RPC(不打开 knowledge.db)
3
+ */
4
+ export interface KnowledgeClientOptions {
5
+ baseUrl: string;
6
+ token: string;
7
+ /**
8
+ * HTTP 超时。默认 30s:索引期 FTS/写库会让 Service 短暂繁忙,
9
+ * 5s 会把正常的「忙」误报成 timeout/503。仍应通过分批让出保证 /health 可达。
10
+ */
11
+ timeoutMs?: number;
12
+ /**
13
+ * 只读 API 超时(search/list/stats)。默认 12s:
14
+ * 查询走 Query Worker,应快速失败并由 UI 重试,而不是拖到 30s。
15
+ */
16
+ readTimeoutMs?: number;
17
+ }
18
+ export declare class KnowledgeClient {
19
+ private readonly opts;
20
+ constructor(opts: KnowledgeClientOptions);
21
+ get baseUrl(): string;
22
+ get token(): string;
23
+ private request;
24
+ health(): Promise<{
25
+ ok: boolean;
26
+ service: string;
27
+ version: string;
28
+ }>;
29
+ ready(): Promise<{
30
+ ready: boolean;
31
+ sqliteVec: boolean;
32
+ }>;
33
+ ensurePrincipal(localAgentId: string, displayName?: string): Promise<unknown>;
34
+ listSources(opts?: {
35
+ scopeLevel?: 'global' | 'project' | 'session';
36
+ projectKey?: string;
37
+ sessionId?: string;
38
+ }): Promise<Array<Record<string, unknown>>>;
39
+ createSource(input: Record<string, unknown>): Promise<Record<string, unknown>>;
40
+ patchSource(sourceId: string, patch: Record<string, unknown>): Promise<Record<string, unknown>>;
41
+ deleteSource(sourceId: string): Promise<unknown>;
42
+ reindex(sourceId: string): Promise<unknown>;
43
+ /** 按路径 / 筛选强制重解析(中止态自动 resume) */
44
+ reprocess(sourceId: string, opts: {
45
+ paths?: string[];
46
+ filter?: {
47
+ status?: string;
48
+ ext?: string;
49
+ q?: string;
50
+ };
51
+ }): Promise<{
52
+ queued: number;
53
+ alreadyActive: number;
54
+ cleanedNonFiles: number;
55
+ resumed: boolean;
56
+ rejected: number;
57
+ }>;
58
+ search(agentId: string, q: string, opts?: {
59
+ sessionId?: string;
60
+ limit?: number;
61
+ }): Promise<{
62
+ hits: unknown[];
63
+ keywordHits: number;
64
+ vectorHits: number;
65
+ }>;
66
+ /** turn 级自动召回分档(与 Search Worker `autoGround` 同源) */
67
+ autoGround(agentId: string, q: string, opts?: {
68
+ sessionId?: string;
69
+ limit?: number;
70
+ recall?: 'off' | 'hint' | 'hybrid' | 'inject';
71
+ }): Promise<{
72
+ mode: 'inject' | 'hint' | 'none';
73
+ hits: unknown[];
74
+ hint?: string;
75
+ reason: string;
76
+ coverage: number;
77
+ scoreFloor: number;
78
+ }>;
79
+ stats(agentId: string): Promise<Record<string, number>>;
80
+ visibility(agentId: string, op: 'assignProject' | 'unassignProject' | 'hide' | 'unhide', body: {
81
+ projectKey?: string;
82
+ sourceId?: string;
83
+ }): Promise<unknown>;
84
+ listProjects(): Promise<Array<Record<string, unknown>>>;
85
+ createProject(input: {
86
+ projectKey: string;
87
+ displayName?: string;
88
+ visibility?: string;
89
+ }): Promise<Record<string, unknown>>;
90
+ deleteProject(projectKey: string): Promise<unknown>;
91
+ getSource(sourceId: string): Promise<Record<string, unknown>>;
92
+ /** 中止源任务;省略 sourceId = 中止本 Gateway 全部源 */
93
+ abort(sourceId?: string): Promise<unknown>;
94
+ /** 继续源任务;省略 sourceId = 继续本 Gateway 全部源 */
95
+ resume(sourceId?: string): Promise<unknown>;
96
+ listFiles(sourceId: string): Promise<Array<Record<string, unknown>>>;
97
+ listFilesPaged(sourceId: string, opts?: {
98
+ status?: 'indexed' | 'skipped' | 'error' | 'all';
99
+ ext?: string;
100
+ q?: string;
101
+ page?: number;
102
+ pageSize?: number;
103
+ }): Promise<{
104
+ items: Array<Record<string, unknown>>;
105
+ total: number;
106
+ page: number;
107
+ pageSize: number;
108
+ statusCounts: {
109
+ indexed: number;
110
+ skipped: number;
111
+ error: number;
112
+ };
113
+ extCounts: Array<{
114
+ ext: string;
115
+ n: number;
116
+ }>;
117
+ }>;
118
+ catalog(agentId: string): Promise<unknown[]>;
119
+ promotionCandidates(): Promise<unknown[]>;
120
+ describeSource(sourceId: string): Promise<{
121
+ generatedDescription: string;
122
+ source: string;
123
+ }>;
124
+ listChunks(agentId: string, sourceId: string, path: string): Promise<Array<{
125
+ id: string;
126
+ text: string;
127
+ startLine: number;
128
+ endLine: number;
129
+ ordinal: number;
130
+ path: string;
131
+ }>>;
132
+ read(agentId: string, body: {
133
+ chunkId?: string;
134
+ sourceId?: string;
135
+ path?: string;
136
+ }): Promise<{
137
+ found: boolean;
138
+ path?: string;
139
+ startLine?: number;
140
+ endLine?: number;
141
+ text?: string;
142
+ chunkCount?: number;
143
+ }>;
144
+ getVisibility(agentId: string): Promise<{
145
+ assignedProjects: string[];
146
+ hiddenSourceIds: string[];
147
+ }>;
148
+ sessionVisibility(agentId: string, sessionId: string): Promise<Array<Record<string, unknown>>>;
149
+ setSessionVisibility(agentId: string, item: {
150
+ sessionId: string;
151
+ targetType: 'project' | 'source';
152
+ targetId: string;
153
+ op: 'include' | 'exclude';
154
+ }): Promise<unknown>;
155
+ replaceSessionVisibility(agentId: string, sessionId: string, items: Array<{
156
+ targetType: 'project' | 'source';
157
+ targetId: string;
158
+ op: 'include' | 'exclude';
159
+ }>): Promise<unknown>;
160
+ clearSessionVisibility(agentId: string, sessionId: string, target?: {
161
+ targetType: 'project' | 'source';
162
+ targetId: string;
163
+ }): Promise<unknown>;
164
+ jobControl(sourceId: string): Promise<{
165
+ aborted: boolean;
166
+ jobsQueued: number;
167
+ jobsRunning: number;
168
+ jobsCancelled: number;
169
+ embedMissing: boolean;
170
+ canAbort: boolean;
171
+ canResume: boolean;
172
+ }>;
173
+ jobs(query?: {
174
+ sourceId?: string;
175
+ status?: string;
176
+ }): Promise<Array<Record<string, unknown>>>;
177
+ }
178
+ /**
179
+ * AutoGroundPort 适配器 — Gateway 侧 turn 级 grounding 走 Knowledge Service。
180
+ * 不打开 knowledge.db;分档逻辑在 Search Worker 的 KnowledgeRetriever.autoGround。
181
+ */
182
+ export declare class ClientKnowledgeGrounding {
183
+ private readonly client;
184
+ /** 缺省 recall(agents[].knowledge.recall / 全局);请求可覆盖 */
185
+ private readonly defaultRecall?;
186
+ constructor(client: KnowledgeClient,
187
+ /** 缺省 recall(agents[].knowledge.recall / 全局);请求可覆盖 */
188
+ defaultRecall?: "off" | "hint" | "hybrid" | "inject" | undefined);
189
+ autoGround(query: string, opts: {
190
+ agentId: string;
191
+ sessionId?: string;
192
+ limit?: number;
193
+ tenantId?: string;
194
+ gatewayId?: string;
195
+ recall?: 'off' | 'hint' | 'hybrid' | 'inject';
196
+ }): Promise<import('./retriever.js').AutoGroundDecision>;
197
+ }
@@ -0,0 +1,237 @@
1
+ /**
2
+ * KnowledgeClient — Gateway 侧 RPC(不打开 knowledge.db)
3
+ */
4
+ export class KnowledgeClient {
5
+ opts;
6
+ constructor(opts) {
7
+ this.opts = opts;
8
+ }
9
+ get baseUrl() {
10
+ return this.opts.baseUrl;
11
+ }
12
+ get token() {
13
+ return this.opts.token;
14
+ }
15
+ async request(method, path, body, headers, opts) {
16
+ const url = `${this.opts.baseUrl.replace(/\/+$/, '')}${path}`;
17
+ // 显式 timeoutMs 约束所有请求;readTimeoutMs 仅在未设 timeoutMs 时给只读更短缺省
18
+ const timeoutMs = opts?.read
19
+ ? (this.opts.readTimeoutMs ?? this.opts.timeoutMs ?? 12_000)
20
+ : (this.opts.timeoutMs ?? 30_000);
21
+ const ac = new AbortController();
22
+ const timeoutErr = new Error(`knowledge_http_timeout ${method} ${path} after ${timeoutMs}ms (service busy or blocked)`);
23
+ const t = setTimeout(() => ac.abort(timeoutErr), timeoutMs);
24
+ try {
25
+ const res = await fetch(url, {
26
+ method,
27
+ headers: {
28
+ authorization: `Bearer ${this.opts.token}`,
29
+ ...(body != null ? { 'content-type': 'application/json' } : {}),
30
+ ...headers,
31
+ },
32
+ body: body != null ? JSON.stringify(body) : undefined,
33
+ signal: ac.signal,
34
+ });
35
+ const json = (await res.json());
36
+ if (!res.ok || json.error) {
37
+ throw new Error(json.error?.message ?? `knowledge_http_${res.status}`);
38
+ }
39
+ return (json.data ?? json);
40
+ }
41
+ catch (err) {
42
+ if (ac.signal.aborted)
43
+ throw timeoutErr;
44
+ throw err;
45
+ }
46
+ finally {
47
+ clearTimeout(t);
48
+ }
49
+ }
50
+ health() {
51
+ return this.request('GET', '/health', undefined, undefined, { read: true });
52
+ }
53
+ ready() {
54
+ return this.request('GET', '/v1/ready', undefined, undefined, { read: true });
55
+ }
56
+ ensurePrincipal(localAgentId, displayName) {
57
+ return this.request('PUT', `/v1/principals/${encodeURIComponent(localAgentId)}`, {
58
+ displayName,
59
+ status: 'active',
60
+ });
61
+ }
62
+ listSources(opts) {
63
+ const qs = new URLSearchParams();
64
+ if (opts?.scopeLevel)
65
+ qs.set('scopeLevel', opts.scopeLevel);
66
+ if (opts?.projectKey)
67
+ qs.set('projectKey', opts.projectKey);
68
+ if (opts?.sessionId)
69
+ qs.set('sessionId', opts.sessionId);
70
+ const q = qs.toString();
71
+ return this.request('GET', `/v1/sources${q ? `?${q}` : ''}`, undefined, undefined, {
72
+ read: true,
73
+ });
74
+ }
75
+ createSource(input) {
76
+ return this.request('POST', '/v1/sources', input);
77
+ }
78
+ patchSource(sourceId, patch) {
79
+ return this.request('PATCH', `/v1/sources/${encodeURIComponent(sourceId)}`, patch);
80
+ }
81
+ deleteSource(sourceId) {
82
+ return this.request('DELETE', `/v1/sources/${encodeURIComponent(sourceId)}`);
83
+ }
84
+ reindex(sourceId) {
85
+ return this.request('POST', `/v1/sources/${encodeURIComponent(sourceId)}/reindex`);
86
+ }
87
+ /** 按路径 / 筛选强制重解析(中止态自动 resume) */
88
+ reprocess(sourceId, opts) {
89
+ return this.request('POST', `/v1/sources/${encodeURIComponent(sourceId)}/reprocess`, opts);
90
+ }
91
+ search(agentId, q, opts) {
92
+ const qs = new URLSearchParams({ q });
93
+ if (opts?.sessionId)
94
+ qs.set('sessionId', opts.sessionId);
95
+ if (opts?.limit != null)
96
+ qs.set('limit', String(opts.limit));
97
+ return this.request('GET', `/v1/principals/${encodeURIComponent(agentId)}/search?${qs}`, undefined, undefined, { read: true });
98
+ }
99
+ /** turn 级自动召回分档(与 Search Worker `autoGround` 同源) */
100
+ autoGround(agentId, q, opts) {
101
+ const qs = new URLSearchParams({ q });
102
+ if (opts?.sessionId)
103
+ qs.set('sessionId', opts.sessionId);
104
+ if (opts?.limit != null)
105
+ qs.set('limit', String(opts.limit));
106
+ if (opts?.recall)
107
+ qs.set('recall', opts.recall);
108
+ return this.request('GET', `/v1/principals/${encodeURIComponent(agentId)}/ground?${qs}`, undefined, undefined, { read: true });
109
+ }
110
+ stats(agentId) {
111
+ return this.request('GET', `/v1/principals/${encodeURIComponent(agentId)}/stats`, undefined, undefined, { read: true });
112
+ }
113
+ visibility(agentId, op, body) {
114
+ return this.request('POST', `/v1/principals/${encodeURIComponent(agentId)}/visibility`, {
115
+ op,
116
+ ...body,
117
+ });
118
+ }
119
+ listProjects() {
120
+ return this.request('GET', '/v1/projects');
121
+ }
122
+ createProject(input) {
123
+ return this.request('POST', '/v1/projects', input);
124
+ }
125
+ deleteProject(projectKey) {
126
+ return this.request('DELETE', `/v1/projects/${encodeURIComponent(projectKey)}`);
127
+ }
128
+ getSource(sourceId) {
129
+ return this.request('GET', `/v1/sources/${encodeURIComponent(sourceId)}`, undefined, undefined, { read: true });
130
+ }
131
+ /** 中止源任务;省略 sourceId = 中止本 Gateway 全部源 */
132
+ abort(sourceId) {
133
+ return sourceId
134
+ ? this.request('POST', `/v1/sources/${encodeURIComponent(sourceId)}/abort`)
135
+ : this.request('POST', '/v1/jobs/abort');
136
+ }
137
+ /** 继续源任务;省略 sourceId = 继续本 Gateway 全部源 */
138
+ resume(sourceId) {
139
+ return sourceId
140
+ ? this.request('POST', `/v1/sources/${encodeURIComponent(sourceId)}/resume`)
141
+ : this.request('POST', '/v1/jobs/resume');
142
+ }
143
+ listFiles(sourceId) {
144
+ return this.request('GET', `/v1/sources/${encodeURIComponent(sourceId)}/files`, undefined, undefined, { read: true });
145
+ }
146
+ listFilesPaged(sourceId, opts) {
147
+ const qs = new URLSearchParams();
148
+ if (opts?.status)
149
+ qs.set('status', opts.status);
150
+ if (opts?.ext)
151
+ qs.set('ext', opts.ext);
152
+ if (opts?.q)
153
+ qs.set('q', opts.q);
154
+ if (opts?.page != null)
155
+ qs.set('page', String(opts.page));
156
+ if (opts?.pageSize != null)
157
+ qs.set('pageSize', String(opts.pageSize));
158
+ const s = qs.toString();
159
+ return this.request('GET', `/v1/sources/${encodeURIComponent(sourceId)}/files${s ? `?${s}` : ''}`, undefined, undefined, { read: true });
160
+ }
161
+ catalog(agentId) {
162
+ return this.request('GET', `/v1/principals/${encodeURIComponent(agentId)}/catalog`, undefined, undefined, { read: true });
163
+ }
164
+ promotionCandidates() {
165
+ return this.request('GET', '/v1/promotion-candidates', undefined, undefined, { read: true });
166
+ }
167
+ describeSource(sourceId) {
168
+ return this.request('POST', `/v1/sources/${encodeURIComponent(sourceId)}/describe`);
169
+ }
170
+ listChunks(agentId, sourceId, path) {
171
+ const qs = new URLSearchParams({ sourceId, path });
172
+ return this.request('GET', `/v1/principals/${encodeURIComponent(agentId)}/chunks?${qs}`, undefined, undefined, { read: true });
173
+ }
174
+ read(agentId, body) {
175
+ return this.request('POST', `/v1/principals/${encodeURIComponent(agentId)}/read`, body);
176
+ }
177
+ getVisibility(agentId) {
178
+ return this.request('GET', `/v1/principals/${encodeURIComponent(agentId)}/visibility`, undefined, undefined, { read: true });
179
+ }
180
+ sessionVisibility(agentId, sessionId) {
181
+ return this.request('GET', `/v1/principals/${encodeURIComponent(agentId)}/session-visibility?sessionId=${encodeURIComponent(sessionId)}`, undefined, undefined, { read: true });
182
+ }
183
+ setSessionVisibility(agentId, item) {
184
+ return this.request('POST', `/v1/principals/${encodeURIComponent(agentId)}/session-visibility`, item);
185
+ }
186
+ replaceSessionVisibility(agentId, sessionId, items) {
187
+ return this.request('PUT', `/v1/principals/${encodeURIComponent(agentId)}/session-visibility`, {
188
+ sessionId,
189
+ items,
190
+ });
191
+ }
192
+ clearSessionVisibility(agentId, sessionId, target) {
193
+ const qs = new URLSearchParams({ sessionId });
194
+ if (target?.targetType && target?.targetId) {
195
+ qs.set('targetType', target.targetType);
196
+ qs.set('targetId', target.targetId);
197
+ }
198
+ return this.request('DELETE', `/v1/principals/${encodeURIComponent(agentId)}/session-visibility?${qs}`);
199
+ }
200
+ jobControl(sourceId) {
201
+ return this.request('GET', `/v1/jobs/control?sourceId=${encodeURIComponent(sourceId)}`, undefined, undefined, { read: true });
202
+ }
203
+ jobs(query) {
204
+ const qs = new URLSearchParams();
205
+ if (query?.sourceId)
206
+ qs.set('sourceId', query.sourceId);
207
+ if (query?.status)
208
+ qs.set('status', query.status);
209
+ const s = qs.toString();
210
+ return this.request('GET', `/v1/jobs${s ? `?${s}` : ''}`, undefined, undefined, {
211
+ read: true,
212
+ });
213
+ }
214
+ }
215
+ /**
216
+ * AutoGroundPort 适配器 — Gateway 侧 turn 级 grounding 走 Knowledge Service。
217
+ * 不打开 knowledge.db;分档逻辑在 Search Worker 的 KnowledgeRetriever.autoGround。
218
+ */
219
+ export class ClientKnowledgeGrounding {
220
+ client;
221
+ defaultRecall;
222
+ constructor(client,
223
+ /** 缺省 recall(agents[].knowledge.recall / 全局);请求可覆盖 */
224
+ defaultRecall) {
225
+ this.client = client;
226
+ this.defaultRecall = defaultRecall;
227
+ }
228
+ async autoGround(query, opts) {
229
+ await this.client.ensurePrincipal(opts.agentId).catch(() => undefined);
230
+ const recall = opts.recall ?? this.defaultRecall;
231
+ return (await this.client.autoGround(opts.agentId, query, {
232
+ ...(opts.sessionId != null ? { sessionId: opts.sessionId } : {}),
233
+ ...(opts.limit != null ? { limit: opts.limit } : {}),
234
+ ...(recall ? { recall } : {}),
235
+ }));
236
+ }
237
+ }
@@ -2,12 +2,12 @@
2
2
  * ConnectorFetcher — 将 KnowledgeConnector 适配为 SourceFetcher
3
3
  */
4
4
  import type { ResolvedCredential } from '../governance/credentials/types.js';
5
- import type { DiscoveredDocRef, SourceFetcher, VirtualDocument } from './fetchers.js';
5
+ import type { DiscoveredDocRef, DiscoverResult, SourceFetcher, VirtualDocument } from './fetchers.js';
6
6
  import type { ConnectorRegistry } from './connectors.js';
7
7
  import type { KnowledgeSource } from './types.js';
8
8
  export declare class ConnectorFetcher implements SourceFetcher {
9
9
  private readonly registry;
10
10
  constructor(registry: ConnectorRegistry);
11
- discover(source: KnowledgeSource, cred?: ResolvedCredential | null): Promise<DiscoveredDocRef[]>;
11
+ discover(source: KnowledgeSource, cred?: ResolvedCredential | null): Promise<DiscoverResult>;
12
12
  fetch(source: KnowledgeSource, ref: DiscoveredDocRef, cred?: ResolvedCredential | null): Promise<VirtualDocument | null>;
13
13
  }
@@ -5,7 +5,7 @@
5
5
  * 密钥经 CredentialStore(authRef)注入,配置不进 knowledge.db 明文。
6
6
  */
7
7
  import type { ResolvedCredential } from '../governance/credentials/types.js';
8
- import type { DiscoveredDocRef, VirtualDocument } from './fetchers.js';
8
+ import type { DiscoveredDocRef, DiscoverResult, VirtualDocument } from './fetchers.js';
9
9
  import type { KnowledgeSource, KnowledgeSourceNetwork } from './types.js';
10
10
  export interface ConnectorContext {
11
11
  /** 源 location(list 入口或配置引用) */
@@ -17,7 +17,7 @@ export interface ConnectorContext {
17
17
  }
18
18
  export interface KnowledgeConnector {
19
19
  id: string;
20
- discover(ctx: ConnectorContext, source: KnowledgeSource): Promise<DiscoveredDocRef[]>;
20
+ discover(ctx: ConnectorContext, source: KnowledgeSource): Promise<DiscoverResult>;
21
21
  fetch(ctx: ConnectorContext, source: KnowledgeSource, ref: DiscoveredDocRef): Promise<VirtualDocument | null>;
22
22
  }
23
23
  /** generic REST list+get 配置(location 可为 JSON 串,或纯 listUrl) */
@@ -40,7 +40,7 @@ export interface RestConnectorConfig {
40
40
  /** generic REST list + content/get */
41
41
  export declare class RestConnector implements KnowledgeConnector {
42
42
  readonly id = "rest";
43
- discover(ctx: ConnectorContext, source: KnowledgeSource): Promise<DiscoveredDocRef[]>;
43
+ discover(ctx: ConnectorContext, source: KnowledgeSource): Promise<DiscoverResult>;
44
44
  fetch(ctx: ConnectorContext, source: KnowledgeSource, ref: DiscoveredDocRef): Promise<VirtualDocument | null>;
45
45
  }
46
46
  export declare class ConnectorRegistry {
@@ -6,7 +6,7 @@
6
6
  */
7
7
  import { createHash } from 'node:crypto';
8
8
  import { htmlToStructuredText, looksLikeHtml } from './html.js';
9
- import { guardedFetch } from './network-guard.js';
9
+ import { authHeadersForUrl, guardedFetch } from './network-guard.js';
10
10
  function dig(obj, path) {
11
11
  if (!path)
12
12
  return obj;
@@ -76,19 +76,21 @@ export class RestConnector {
76
76
  headers: { ...(ctx.auth?.headers ?? {}), accept: 'application/json' },
77
77
  });
78
78
  const body = JSON.parse(res.body);
79
- const items = pickItems(body, cfg.itemsPath).slice(0, maxPages);
79
+ const allItems = pickItems(body, cfg.itemsPath);
80
+ const items = allItems.slice(0, maxPages);
80
81
  const out = [];
81
82
  items.forEach((raw, index) => {
82
83
  if (!raw || typeof raw !== 'object')
83
84
  return;
84
85
  const item = raw;
85
86
  const path = itemPath(item, cfg, index);
87
+ // contentField 条目无独立页面 URL:不得共用 listUrl 当 identity
86
88
  const externalUrl = cfg.urlField
87
- ? String(dig(item, cfg.urlField) ?? cfg.listUrl)
88
- : cfg.listUrl;
89
- out.push({ path, externalUrl });
89
+ ? String(dig(item, cfg.urlField) ?? '')
90
+ : undefined;
91
+ out.push({ path, externalUrl: externalUrl || undefined });
90
92
  });
91
- return out;
93
+ return { docs: out, complete: allItems.length <= maxPages };
92
94
  }
93
95
  async fetch(ctx, source, ref) {
94
96
  const cfg = parseRestConfig(ctx.location);
@@ -111,7 +113,7 @@ export class RestConnector {
111
113
  return null;
112
114
  const item = hit;
113
115
  let content = '';
114
- let externalUrl = ref.externalUrl ?? cfg.listUrl;
116
+ let externalUrl = ref.externalUrl;
115
117
  if (cfg.contentField) {
116
118
  const raw = dig(item, cfg.contentField);
117
119
  content = raw == null ? '' : String(raw);
@@ -123,8 +125,10 @@ export class RestConnector {
123
125
  if (!pageUrl)
124
126
  return null;
125
127
  externalUrl = pageUrl;
128
+ // 凭证只跟 listUrl 同源;被投毒列表指向的外域不得带走 token
129
+ const listOrigin = new URL(cfg.listUrl).origin;
126
130
  const page = await guardedFetch(pageUrl, networkFrom(ctx, source), {
127
- headers: ctx.auth?.headers,
131
+ headers: authHeadersForUrl(listOrigin, pageUrl, ctx.auth?.headers),
128
132
  });
129
133
  content = looksLikeHtml(page.body, page.contentType)
130
134
  ? htmlToStructuredText(page.body)
@@ -147,6 +151,8 @@ function networkFrom(ctx, source) {
147
151
  return {
148
152
  allowPrivateNetwork: source.network?.allowPrivateNetwork === true,
149
153
  maxResponseBytes: source.network?.maxResponseBytes,
154
+ timeoutMs: source.network?.timeoutMs,
155
+ maxRedirects: source.network?.maxRedirects,
150
156
  };
151
157
  }
152
158
  export class ConnectorRegistry {
@@ -1,25 +1,64 @@
1
1
  /**
2
2
  * KnowledgeDatabase — OCTOPI_HOME/knowledge/knowledge.db
3
3
  *
4
- * 全 scope Source 权威 + Project 挂载 + Global 屏蔽。
5
- * 不存 chunk/vector(Index 可重建投影,P2+)。
4
+ * Source 权威 + Project 挂载 + Global 屏蔽 + **Index 投影**
5
+ * (files/chunks/embeddings/FTS/jobs/control)。Index 非权威,可整库 rebuild。
6
6
  */
7
7
  import type { DatabaseSync } from 'node:sqlite';
8
8
  export interface KnowledgeDatabaseOptions {
9
9
  dbPath?: string;
10
10
  wal?: boolean;
11
11
  busyTimeoutMs?: number;
12
+ /** 尝试加载 sqlite-vec(默认 true;失败则 JS 余弦);可指定扩展路径 */
13
+ sqliteVec?: boolean | {
14
+ extensionPath?: string;
15
+ };
16
+ /**
17
+ * 只读打开(Query Worker / Engine 残留短读):跳过 DDL/升列,不抢写锁。
18
+ * 业务写路径必须走 Writer Worker 唯一写者;此模式仅用于同库只读连接。
19
+ */
20
+ readOnly?: boolean;
21
+ /** 跳过 createTables/upgrade(默认 false;readOnly 时强制 true) */
22
+ skipMigrate?: boolean;
12
23
  }
13
24
  export declare class KnowledgeDatabase {
14
25
  private db;
26
+ private _sqliteVec;
15
27
  private constructor();
28
+ get sqliteVecEnabled(): boolean;
16
29
  /**
17
30
  * 打开/创建 knowledge.db(Node >= 24 node:sqlite)
18
31
  */
19
32
  static create(options?: KnowledgeDatabaseOptions): Promise<KnowledgeDatabase>;
20
33
  private createTables;
21
- /** 幂等迁移:外源 ingest / 凭证引用列 */
34
+ /**
35
+ * 旧库升级:补缺失列 + 重建 File identity 投影。
36
+ * 必须在 CREATE INDEX 之前跑,否则旧表上建新列索引会 `no such column`。
37
+ */
38
+ private upgradeLegacySchema;
39
+ /**
40
+ * 旧 projects PK(project_key) / project_agents PK(project_key,agent_id) → 复合键
41
+ * (含 tenant/gateway),否则 ON CONFLICT(tenant_id, project_key) 会炸。
42
+ */
43
+ private rebuildLegacyProjectTables;
44
+ /** 旧列 agent_id / session_id → local_* 回填(best-effort) */
45
+ private backfillLegacyAgentColumns;
46
+ /**
47
+ * 保证 embeddings 表含 `bucket` 列并建索引。
48
+ *
49
+ * 必须在任何 `INSERT … bucket` / `WHERE bucket` **之前**调用;
50
+ * 且不得与 `CREATE INDEX … (bucket)` 同批执行(旧表无该列时会先炸索引)。
51
+ */
52
+ ensureEmbeddingSchema(): void;
53
+ /**
54
+ * 幂等迁移:createTables 已跑 upgradeLegacySchema;此处仅兜底
55
+ */
22
56
  private migrate;
57
+ /**
58
+ * v2 旧库检测:knowledge_files 仍为 (source_id,path) 且无 identity_key / memberships。
59
+ * Index 非权威 → 迁 membership + identity;失败则重建空索引(源登记保留)。
60
+ */
61
+ private migrateLegacyFileIdentitySchema;
23
62
  get raw(): DatabaseSync;
24
63
  close(): void;
25
64
  stats(): Record<string, number>;