@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
@@ -133,7 +133,7 @@ export declare const DocumentsConfigSchema: z.ZodObject<{
133
133
  cacheDir: z.ZodOptional<z.ZodNullable<z.ZodString>>;
134
134
  cacheMaxBytes: z.ZodOptional<z.ZodNumber>;
135
135
  timeoutMs: z.ZodOptional<z.ZodNumber>;
136
- allowTextScrape: z.ZodOptional<z.ZodBoolean>;
136
+ maxInputBytes: z.ZodOptional<z.ZodNumber>;
137
137
  }, z.core.$strip>>;
138
138
  markitdown: z.ZodOptional<z.ZodObject<{
139
139
  enabled: z.ZodOptional<z.ZodBoolean>;
@@ -107,7 +107,7 @@ export const DocumentsConfigSchema = z.object({
107
107
  cacheDir: z.string().nullable().optional(),
108
108
  cacheMaxBytes: z.number().int().positive().optional(),
109
109
  timeoutMs: z.number().int().positive().optional(),
110
- allowTextScrape: z.boolean().optional(),
110
+ maxInputBytes: z.number().int().positive().optional(),
111
111
  })
112
112
  .optional(),
113
113
  markitdown: z
@@ -324,7 +324,7 @@ export declare const engineConfigSchema: z.ZodObject<{
324
324
  cacheDir: z.ZodOptional<z.ZodNullable<z.ZodString>>;
325
325
  cacheMaxBytes: z.ZodOptional<z.ZodNumber>;
326
326
  timeoutMs: z.ZodOptional<z.ZodNumber>;
327
- allowTextScrape: z.ZodOptional<z.ZodBoolean>;
327
+ maxInputBytes: z.ZodOptional<z.ZodNumber>;
328
328
  }, z.core.$strip>>;
329
329
  markitdown: z.ZodOptional<z.ZodObject<{
330
330
  enabled: z.ZodOptional<z.ZodBoolean>;
@@ -341,6 +341,15 @@ export declare const engineConfigSchema: z.ZodObject<{
341
341
  }, z.core.$strip>>;
342
342
  }, z.core.$strip>>;
343
343
  knowledge: z.ZodOptional<z.ZodObject<{
344
+ service: z.ZodOptional<z.ZodObject<{
345
+ baseUrl: z.ZodOptional<z.ZodString>;
346
+ token: z.ZodOptional<z.ZodString>;
347
+ manageLocal: z.ZodOptional<z.ZodBoolean>;
348
+ port: z.ZodOptional<z.ZodNumber>;
349
+ timeoutMs: z.ZodOptional<z.ZodNumber>;
350
+ connectTimeoutMs: z.ZodOptional<z.ZodNumber>;
351
+ }, z.core.$strip>>;
352
+ required: z.ZodOptional<z.ZodBoolean>;
344
353
  recall: z.ZodOptional<z.ZodEnum<{
345
354
  off: "off";
346
355
  hint: "hint";
@@ -376,6 +385,11 @@ export declare const engineConfigSchema: z.ZodObject<{
376
385
  index: z.ZodOptional<z.ZodObject<{
377
386
  embedding: z.ZodOptional<z.ZodBoolean>;
378
387
  hybridKeyword: z.ZodOptional<z.ZodBoolean>;
388
+ embedSecretPolicy: z.ZodOptional<z.ZodEnum<{
389
+ allow: "allow";
390
+ redact: "redact";
391
+ skip: "skip";
392
+ }>>;
379
393
  phaseA: z.ZodOptional<z.ZodObject<{
380
394
  concurrency: z.ZodOptional<z.ZodNumber>;
381
395
  debounceMs: z.ZodOptional<z.ZodNumber>;
@@ -388,6 +402,29 @@ export declare const engineConfigSchema: z.ZodObject<{
388
402
  queue: z.ZodOptional<z.ZodObject<{
389
403
  maxDepth: z.ZodOptional<z.ZodNumber>;
390
404
  }, z.core.$strip>>;
405
+ files: z.ZodOptional<z.ZodObject<{
406
+ oversize: z.ZodOptional<z.ZodEnum<{
407
+ skip: "skip";
408
+ partial: "partial";
409
+ }>>;
410
+ maxFileBytes: z.ZodOptional<z.ZodNumber>;
411
+ hardMaxFileBytes: z.ZodOptional<z.ZodNumber>;
412
+ maxBytes: z.ZodOptional<z.ZodObject<{
413
+ text: z.ZodOptional<z.ZodNumber>;
414
+ pdf: z.ZodOptional<z.ZodNumber>;
415
+ officeDoc: z.ZodOptional<z.ZodNumber>;
416
+ sheet: z.ZodOptional<z.ZodNumber>;
417
+ }, z.core.$strip>>;
418
+ partial: z.ZodOptional<z.ZodObject<{
419
+ maxSheets: z.ZodOptional<z.ZodNumber>;
420
+ maxRowsPerSheet: z.ZodOptional<z.ZodNumber>;
421
+ maxPdfPages: z.ZodOptional<z.ZodNumber>;
422
+ maxTextChars: z.ZodOptional<z.ZodNumber>;
423
+ }, z.core.$strip>>;
424
+ parseTimeoutMs: z.ZodOptional<z.ZodNumber>;
425
+ parseTimeoutPerMBMs: z.ZodOptional<z.ZodNumber>;
426
+ maxParseTimeoutMs: z.ZodOptional<z.ZodNumber>;
427
+ }, z.core.$strip>>;
391
428
  }, z.core.$strip>>;
392
429
  load: z.ZodOptional<z.ZodObject<{
393
430
  parseConcurrency: z.ZodOptional<z.ZodNumber>;
@@ -6,6 +6,15 @@
6
6
  import { z } from 'zod';
7
7
  /** Knowledge 全局缺省(agents[].knowledge.recall 覆盖) */
8
8
  export declare const KnowledgeConfigSchema: z.ZodObject<{
9
+ service: z.ZodOptional<z.ZodObject<{
10
+ baseUrl: z.ZodOptional<z.ZodString>;
11
+ token: z.ZodOptional<z.ZodString>;
12
+ manageLocal: z.ZodOptional<z.ZodBoolean>;
13
+ port: z.ZodOptional<z.ZodNumber>;
14
+ timeoutMs: z.ZodOptional<z.ZodNumber>;
15
+ connectTimeoutMs: z.ZodOptional<z.ZodNumber>;
16
+ }, z.core.$strip>>;
17
+ required: z.ZodOptional<z.ZodBoolean>;
9
18
  recall: z.ZodOptional<z.ZodEnum<{
10
19
  off: "off";
11
20
  hint: "hint";
@@ -41,6 +50,11 @@ export declare const KnowledgeConfigSchema: z.ZodObject<{
41
50
  index: z.ZodOptional<z.ZodObject<{
42
51
  embedding: z.ZodOptional<z.ZodBoolean>;
43
52
  hybridKeyword: z.ZodOptional<z.ZodBoolean>;
53
+ embedSecretPolicy: z.ZodOptional<z.ZodEnum<{
54
+ allow: "allow";
55
+ redact: "redact";
56
+ skip: "skip";
57
+ }>>;
44
58
  phaseA: z.ZodOptional<z.ZodObject<{
45
59
  concurrency: z.ZodOptional<z.ZodNumber>;
46
60
  debounceMs: z.ZodOptional<z.ZodNumber>;
@@ -53,6 +67,29 @@ export declare const KnowledgeConfigSchema: z.ZodObject<{
53
67
  queue: z.ZodOptional<z.ZodObject<{
54
68
  maxDepth: z.ZodOptional<z.ZodNumber>;
55
69
  }, z.core.$strip>>;
70
+ files: z.ZodOptional<z.ZodObject<{
71
+ oversize: z.ZodOptional<z.ZodEnum<{
72
+ skip: "skip";
73
+ partial: "partial";
74
+ }>>;
75
+ maxFileBytes: z.ZodOptional<z.ZodNumber>;
76
+ hardMaxFileBytes: z.ZodOptional<z.ZodNumber>;
77
+ maxBytes: z.ZodOptional<z.ZodObject<{
78
+ text: z.ZodOptional<z.ZodNumber>;
79
+ pdf: z.ZodOptional<z.ZodNumber>;
80
+ officeDoc: z.ZodOptional<z.ZodNumber>;
81
+ sheet: z.ZodOptional<z.ZodNumber>;
82
+ }, z.core.$strip>>;
83
+ partial: z.ZodOptional<z.ZodObject<{
84
+ maxSheets: z.ZodOptional<z.ZodNumber>;
85
+ maxRowsPerSheet: z.ZodOptional<z.ZodNumber>;
86
+ maxPdfPages: z.ZodOptional<z.ZodNumber>;
87
+ maxTextChars: z.ZodOptional<z.ZodNumber>;
88
+ }, z.core.$strip>>;
89
+ parseTimeoutMs: z.ZodOptional<z.ZodNumber>;
90
+ parseTimeoutPerMBMs: z.ZodOptional<z.ZodNumber>;
91
+ maxParseTimeoutMs: z.ZodOptional<z.ZodNumber>;
92
+ }, z.core.$strip>>;
56
93
  }, z.core.$strip>>;
57
94
  load: z.ZodOptional<z.ZodObject<{
58
95
  parseConcurrency: z.ZodOptional<z.ZodNumber>;
@@ -6,6 +6,21 @@
6
6
  import { z } from 'zod';
7
7
  /** Knowledge 全局缺省(agents[].knowledge.recall 覆盖) */
8
8
  export const KnowledgeConfigSchema = z.object({
9
+ /** Knowledge Service 连接(v2:Gateway 不打开 knowledge.db) */
10
+ service: z
11
+ .object({
12
+ baseUrl: z.string().optional(),
13
+ token: z.string().optional(),
14
+ /** 缺省 true:serve 时拉起本地 Knowledge;false 则只连 baseUrl */
15
+ manageLocal: z.boolean().optional(),
16
+ /** manageLocal 本地监听端口(缺省 18280) */
17
+ port: z.number().int().positive().max(65535).optional(),
18
+ timeoutMs: z.number().int().positive().optional(),
19
+ connectTimeoutMs: z.number().int().positive().optional(),
20
+ })
21
+ .optional(),
22
+ /** true = Knowledge 不可用则 run 失败(默认 fail-open) */
23
+ required: z.boolean().optional(),
9
24
  recall: z.enum(['off', 'hint', 'hybrid', 'inject']).optional(),
10
25
  autoInject: z
11
26
  .object({
@@ -42,6 +57,11 @@ export const KnowledgeConfigSchema = z.object({
42
57
  .object({
43
58
  embedding: z.boolean().optional(),
44
59
  hybridKeyword: z.boolean().optional(),
60
+ /**
61
+ * embedding 外发前敏感形态策略(默认 redact)
62
+ * allow=原文;redact=脱敏后 embed;skip=命中不写向量
63
+ */
64
+ embedSecretPolicy: z.enum(['allow', 'redact', 'skip']).optional(),
45
65
  phaseA: z
46
66
  .object({
47
67
  concurrency: z.number().int().positive().optional(),
@@ -56,6 +76,33 @@ export const KnowledgeConfigSchema = z.object({
56
76
  })
57
77
  .optional(),
58
78
  queue: z.object({ maxDepth: z.number().int().positive().optional() }).optional(),
79
+ /** 索引文件限额(按格式分级;缺省见 DEFAULT_KNOWLEDGE_FILE_LIMITS) */
80
+ files: z
81
+ .object({
82
+ oversize: z.enum(['partial', 'skip']).optional(),
83
+ maxFileBytes: z.number().int().positive().optional(),
84
+ hardMaxFileBytes: z.number().int().positive().optional(),
85
+ maxBytes: z
86
+ .object({
87
+ text: z.number().int().positive().optional(),
88
+ pdf: z.number().int().positive().optional(),
89
+ officeDoc: z.number().int().positive().optional(),
90
+ sheet: z.number().int().positive().optional(),
91
+ })
92
+ .optional(),
93
+ partial: z
94
+ .object({
95
+ maxSheets: z.number().int().positive().optional(),
96
+ maxRowsPerSheet: z.number().int().positive().optional(),
97
+ maxPdfPages: z.number().int().positive().optional(),
98
+ maxTextChars: z.number().int().positive().optional(),
99
+ })
100
+ .optional(),
101
+ parseTimeoutMs: z.number().int().positive().optional(),
102
+ parseTimeoutPerMBMs: z.number().int().nonnegative().optional(),
103
+ maxParseTimeoutMs: z.number().int().positive().optional(),
104
+ })
105
+ .optional(),
59
106
  })
60
107
  .optional(),
61
108
  load: z
package/dist/config.d.ts CHANGED
@@ -92,6 +92,8 @@ export interface KnowledgeRuntimeConfig {
92
92
  index?: {
93
93
  embedding?: boolean;
94
94
  hybridKeyword?: boolean;
95
+ /** embedding 外发前敏感形态策略(默认 redact) */
96
+ embedSecretPolicy?: 'allow' | 'redact' | 'skip';
95
97
  phaseA?: {
96
98
  concurrency?: number;
97
99
  debounceMs?: number;
@@ -104,6 +106,33 @@ export interface KnowledgeRuntimeConfig {
104
106
  queue?: {
105
107
  maxDepth?: number;
106
108
  };
109
+ /**
110
+ * 索引文件限额(按格式分级;缺省见 DEFAULT_KNOWLEDGE_FILE_LIMITS)
111
+ * 机器资源不足时下调 maxBytes / hardMaxFileBytes
112
+ */
113
+ files?: {
114
+ /** 超格式上限:partial=截断入索引(默认)| skip=整文件跳过 */
115
+ oversize?: 'partial' | 'skip';
116
+ /** 兜底/未归类格式上限 */
117
+ maxFileBytes?: number;
118
+ /** 绝对内存闸门(partial 也拒绝) */
119
+ hardMaxFileBytes?: number;
120
+ maxBytes?: {
121
+ text?: number;
122
+ pdf?: number;
123
+ officeDoc?: number;
124
+ sheet?: number;
125
+ };
126
+ partial?: {
127
+ maxSheets?: number;
128
+ maxRowsPerSheet?: number;
129
+ maxPdfPages?: number;
130
+ maxTextChars?: number;
131
+ };
132
+ parseTimeoutMs?: number;
133
+ parseTimeoutPerMBMs?: number;
134
+ maxParseTimeoutMs?: number;
135
+ };
107
136
  };
108
137
  load?: {
109
138
  parseConcurrency?: number;
@@ -458,7 +487,7 @@ export interface DocumentsCapabilityConfig {
458
487
  cacheDir?: string | null;
459
488
  cacheMaxBytes?: number;
460
489
  timeoutMs?: number;
461
- allowTextScrape?: boolean;
490
+ maxInputBytes?: number;
462
491
  };
463
492
  markitdown?: {
464
493
  enabled?: boolean;
@@ -149,6 +149,8 @@ export declare class AgentBuilder {
149
149
  private _knowledgeIndexStore?;
150
150
  private _knowledgeSourceStore?;
151
151
  private _knowledgeHitLog?;
152
+ /** 独立 Service 路径:仅 grounding(工具走 client tools) */
153
+ private _knowledgeGroundingPort?;
152
154
  private _knowledgeGrounding?;
153
155
  /** 智慧(注入 system prompt WisdomLayer) */
154
156
  private _wisdomStore?;
@@ -287,6 +289,18 @@ export declare class AgentBuilder {
287
289
  includePriorUserTurns?: number;
288
290
  };
289
291
  }): this;
292
+ /**
293
+ * 仅注入 turn 级 grounding(Knowledge Service client 路径)。
294
+ * 工具面请另用 createKnowledgeClientTools;本地 store 路径请用 knowledgeRetriever。
295
+ */
296
+ knowledgeGrounding(port: import('../knowledge/retriever.js').AutoGroundPort, opts?: {
297
+ budgetTokens?: number;
298
+ budgetRatio?: number;
299
+ maxBudgetTokens?: number;
300
+ maxChunks?: number;
301
+ skipIfUserTokensBelow?: number;
302
+ includePriorUserTurns?: number;
303
+ }): this;
290
304
  /** 注入 WisdomStore(半静态思维范式,进 system prompt WisdomLayer) */
291
305
  wisdomStore(store: import('../memory/types.js').WisdomStore): this;
292
306
  /** 注入 ConceptGraphStore(按 query 召回概念边,进 system prompt CognitionLayer) */
@@ -317,6 +317,8 @@ export class AgentBuilder {
317
317
  _knowledgeIndexStore;
318
318
  _knowledgeSourceStore;
319
319
  _knowledgeHitLog;
320
+ /** 独立 Service 路径:仅 grounding(工具走 client tools) */
321
+ _knowledgeGroundingPort;
320
322
  _knowledgeGrounding;
321
323
  /** 智慧(注入 system prompt WisdomLayer) */
322
324
  _wisdomStore;
@@ -522,6 +524,15 @@ export class AgentBuilder {
522
524
  this._knowledgeGrounding = deps.grounding;
523
525
  return this;
524
526
  }
527
+ /**
528
+ * 仅注入 turn 级 grounding(Knowledge Service client 路径)。
529
+ * 工具面请另用 createKnowledgeClientTools;本地 store 路径请用 knowledgeRetriever。
530
+ */
531
+ knowledgeGrounding(port, opts) {
532
+ this._knowledgeGroundingPort = port;
533
+ this._knowledgeGrounding = opts;
534
+ return this;
535
+ }
525
536
  /** 注入 WisdomStore(半静态思维范式,进 system prompt WisdomLayer) */
526
537
  wisdomStore(store) {
527
538
  this._wisdomStore = store;
@@ -873,10 +884,11 @@ export class AgentBuilder {
873
884
  });
874
885
  runner.setSystemPromptAssembler((input) => systemPromptAssembler.assemble(input), (sid) => systemPromptAssembler.clearSession(sid));
875
886
  // turn 级 Knowledge grounding(消息插槽 knowledgeGrounding;不进 system)
876
- if (this._knowledgeRetriever) {
887
+ const groundingPort = this._knowledgeGroundingPort ?? this._knowledgeRetriever;
888
+ if (groundingPort) {
877
889
  const { GroundingAssembler } = await import('../knowledge/grounding.js');
878
890
  const grounding = new GroundingAssembler({
879
- retriever: this._knowledgeRetriever,
891
+ retriever: groundingPort,
880
892
  hitLog: this._knowledgeHitLog,
881
893
  budgetTokens: this._knowledgeGrounding?.budgetTokens,
882
894
  budgetRatio: this._knowledgeGrounding?.budgetRatio,
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * DOCX 后端 — mammoth(可选依赖,T0)→ HTML → Markdown
3
3
  *
4
- * @module harness/context/capabilities/document/backends/docx
4
+ * @module harness/capabilities/document/backends/docx
5
5
  */
6
6
  import type { DocumentExtractBackend } from '../types.js';
7
7
  export declare const docxMammothBackend: DocumentExtractBackend;
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * DOCX 后端 — mammoth(可选依赖,T0)→ HTML → Markdown
3
3
  *
4
- * @module harness/context/capabilities/document/backends/docx
4
+ * @module harness/capabilities/document/backends/docx
5
5
  */
6
6
  import { DocumentExtractError } from '../errors.js';
7
7
  import { htmlFragmentToMarkdown } from '../html-to-md.js';
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * PPTX / 长尾后端 — officeparser(可选依赖,T0 长尾)
3
3
  *
4
- * @module harness/context/capabilities/document/backends/office-parser
4
+ * @module harness/capabilities/document/backends/office-parser
5
5
  */
6
6
  import type { DocumentExtractBackend } from '../types.js';
7
7
  export declare const officeParserBackend: DocumentExtractBackend;
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * PPTX / 长尾后端 — officeparser(可选依赖,T0 长尾)
3
3
  *
4
- * @module harness/context/capabilities/document/backends/office-parser
4
+ * @module harness/capabilities/document/backends/office-parser
5
5
  */
6
6
  import { DocumentExtractError } from '../errors.js';
7
7
  let cached;
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * PDF 后端 — unpdf(可选依赖,T0)
3
3
  *
4
- * @module harness/context/capabilities/document/backends/pdf
4
+ * @module harness/capabilities/document/backends/pdf
5
5
  */
6
6
  import type { DocumentExtractBackend } from '../types.js';
7
7
  export declare const pdfUnpdfBackend: DocumentExtractBackend;
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * PDF 后端 — unpdf(可选依赖,T0)
3
3
  *
4
- * @module harness/context/capabilities/document/backends/pdf
4
+ * @module harness/capabilities/document/backends/pdf
5
5
  */
6
6
  import { DocumentExtractError } from '../errors.js';
7
7
  let cached;
@@ -51,7 +51,8 @@ export const pdfUnpdfBackend = {
51
51
  const pdf = await unpdf.getDocumentProxy(source.data, {
52
52
  ...(source.password ? { password: source.password } : {}),
53
53
  });
54
- const { totalPages, text } = await unpdf.extractText(pdf, { mergePages: true });
54
+ // mergePages:false → 按页数组,便于 maxPages 截断
55
+ const { totalPages, text } = await unpdf.extractText(pdf, { mergePages: false });
55
56
  let title;
56
57
  let author;
57
58
  try {
@@ -62,7 +63,16 @@ export const pdfUnpdfBackend = {
62
63
  catch {
63
64
  // metadata is optional; extraction result remains usable
64
65
  }
65
- const markdown = Array.isArray(text) ? text.join('\n\n') : text;
66
+ const pages = Array.isArray(text) ? text : [text];
67
+ const maxPages = options.maxPages && options.maxPages > 0 ? options.maxPages : pages.length;
68
+ const usedPages = pages.slice(0, Math.min(maxPages, pages.length));
69
+ if (usedPages.length < totalPages) {
70
+ warnings.push({
71
+ code: 'PARTIAL_EXTRACT',
72
+ message: `pages truncated: ${usedPages.length}/${totalPages} (maxPages=${options.maxPages})`,
73
+ });
74
+ }
75
+ const markdown = usedPages.join('\n\n');
66
76
  return {
67
77
  markdown,
68
78
  meta: {
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * 纯文本 / Markdown / CSV 后端(无外部依赖)
3
3
  *
4
- * @module harness/context/capabilities/document/backends/plain
4
+ * @module harness/capabilities/document/backends/plain
5
5
  */
6
6
  import type { DocumentExtractBackend } from '../types.js';
7
7
  export declare const plainTextBackend: DocumentExtractBackend;
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * 纯文本 / Markdown / CSV 后端(无外部依赖)
3
3
  *
4
- * @module harness/context/capabilities/document/backends/plain
4
+ * @module harness/capabilities/document/backends/plain
5
5
  */
6
6
  function decodeUtf8(data) {
7
7
  return new TextDecoder('utf-8', { fatal: false }).decode(data);
@@ -24,18 +24,27 @@ export const plainTextBackend = {
24
24
  accepts({ format }) {
25
25
  return format === 'txt' || format === 'md' || format === 'csv' || format === 'html';
26
26
  },
27
- async extract(source, _options) {
27
+ async extract(source, options) {
28
28
  if (looksLikeBinary(source.data)) {
29
29
  const { DocumentExtractError } = await import('../errors.js');
30
30
  throw new DocumentExtractError('INVALID_SOURCE', 'plain-text backend received binary data');
31
31
  }
32
- const text = decodeUtf8(source.data);
32
+ let text = decodeUtf8(source.data);
33
+ const warnings = [];
34
+ const maxChars = options.maxTextChars && options.maxTextChars > 0 ? options.maxTextChars : 0;
35
+ if (maxChars > 0 && text.length > maxChars) {
36
+ text = `${text.slice(0, maxChars)}\n\n…[truncated: ${text.length - maxChars} chars omitted]`;
37
+ warnings.push({
38
+ code: 'PARTIAL_EXTRACT',
39
+ message: `text truncated to maxTextChars=${maxChars}`,
40
+ });
41
+ }
33
42
  const format = source.formatHint ?? 'txt';
34
43
  // html 原样保留标签交给 knowledge htmlAdapter;此处仅保证可读文本
35
44
  return {
36
45
  markdown: text,
37
46
  meta: { format },
38
- warnings: [],
47
+ warnings,
39
48
  backend: 'plain-text',
40
49
  };
41
50
  },
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * 电子表格后端 — SheetJS `xlsx`(可选依赖,T0;覆盖 xlsx + xls)
3
3
  *
4
- * @module harness/context/capabilities/document/backends/sheet
4
+ * @module harness/capabilities/document/backends/sheet
5
5
  */
6
6
  import type { DocumentExtractBackend } from '../types.js';
7
7
  export declare const sheetXlsxBackend: DocumentExtractBackend;
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * 电子表格后端 — SheetJS `xlsx`(可选依赖,T0;覆盖 xlsx + xls)
3
3
  *
4
- * @module harness/context/capabilities/document/backends/sheet
4
+ * @module harness/capabilities/document/backends/sheet
5
5
  */
6
6
  import { DocumentExtractError } from '../errors.js';
7
7
  let cached;
@@ -57,7 +57,7 @@ export const sheetXlsxBackend = {
57
57
  accepts({ format }) {
58
58
  return format === 'xlsx' || format === 'xls';
59
59
  },
60
- async extract(source, _options) {
60
+ async extract(source, options) {
61
61
  const xlsx = await loadXlsx();
62
62
  if (!xlsx) {
63
63
  throw new DocumentExtractError('BACKEND_UNAVAILABLE', 'xlsx (SheetJS) is not installed', [
@@ -72,18 +72,38 @@ export const sheetXlsxBackend = {
72
72
  const msg = err instanceof Error ? err.message : String(err);
73
73
  throw new DocumentExtractError('INVALID_SOURCE', `Spreadsheet extract failed: ${msg}`);
74
74
  }
75
+ const warnings = [];
76
+ const maxSheets = options.maxSheets && options.maxSheets > 0 ? options.maxSheets : Infinity;
77
+ const maxRows = options.maxRowsPerSheet && options.maxRowsPerSheet > 0
78
+ ? options.maxRowsPerSheet
79
+ : Infinity;
80
+ const names = wb.SheetNames;
81
+ const usedNames = names.slice(0, maxSheets === Infinity ? names.length : maxSheets);
82
+ if (usedNames.length < names.length) {
83
+ warnings.push({
84
+ code: 'PARTIAL_EXTRACT',
85
+ message: `sheets truncated: ${usedNames.length}/${names.length} (maxSheets=${options.maxSheets})`,
86
+ });
87
+ }
75
88
  const parts = [];
76
- for (const name of wb.SheetNames) {
89
+ for (const name of usedNames) {
77
90
  const sheet = wb.Sheets[name];
78
91
  const rows = xlsx.utils.sheet_to_json(sheet, { header: 1, raw: false, defval: '' });
79
- parts.push(`## ${name}\n\n${sheetToMarkdown(rows)}`);
92
+ const usedRows = maxRows === Infinity || rows.length <= maxRows ? rows : rows.slice(0, maxRows);
93
+ if (usedRows.length < rows.length) {
94
+ warnings.push({
95
+ code: 'PARTIAL_EXTRACT',
96
+ message: `sheet "${name}" rows truncated: ${usedRows.length}/${rows.length} (maxRowsPerSheet=${options.maxRowsPerSheet})`,
97
+ });
98
+ }
99
+ parts.push(`## ${name}\n\n${sheetToMarkdown(usedRows)}`);
80
100
  }
81
101
  return {
82
102
  markdown: parts.join('\n\n'),
83
103
  meta: {
84
104
  format: source.formatHint === 'xls' ? 'xls' : 'xlsx',
85
105
  },
86
- warnings: [],
106
+ warnings,
87
107
  backend: 'sheet-xlsx',
88
108
  };
89
109
  },
@@ -4,7 +4,7 @@
4
4
  * XMind 2020+:content.json 树(children.attached)
5
5
  * XMind 8:content.xml topic 树(尽力解析)
6
6
  *
7
- * @module harness/context/capabilities/document/backends/xmind
7
+ * @module harness/capabilities/document/backends/xmind
8
8
  */
9
9
  import type { DocumentExtractBackend } from '../types.js';
10
10
  /** content.json(XMind 2020+)→ Markdown 大纲 */
@@ -4,7 +4,7 @@
4
4
  * XMind 2020+:content.json 树(children.attached)
5
5
  * XMind 8:content.xml topic 树(尽力解析)
6
6
  *
7
- * @module harness/context/capabilities/document/backends/xmind
7
+ * @module harness/capabilities/document/backends/xmind
8
8
  */
9
9
  import { DocumentExtractError } from '../errors.js';
10
10
  let fflateCache;
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * Document 抽取结构化错误
3
3
  *
4
- * @module harness/context/capabilities/document/errors
4
+ * @module harness/capabilities/document/errors
5
5
  */
6
6
  import type { ExtractErrorCode } from './types.js';
7
7
  /**
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * Document 抽取结构化错误
3
3
  *
4
- * @module harness/context/capabilities/document/errors
4
+ * @module harness/capabilities/document/errors
5
5
  */
6
6
  /**
7
7
  * DocumentExtractError — 调用方可按 code 分支,勿匹配 message 文本
@@ -0,0 +1,33 @@
1
+ /**
2
+ * Document 能力统一装配 — Gateway / Knowledge 共用同一配置源
3
+ *
4
+ * 禁止调用方各自 `createDefaultDocumentPort` 再拼一份默认值:
5
+ * 那样 soffice/超时/限额会分叉(Knowledge worker 曾因此整批 no_adapter)。
6
+ *
7
+ * @module harness/capabilities/document/factory
8
+ */
9
+ import type { DocumentPort } from './types.js';
10
+ /** 根配置 `documents.*`(DocumentsConfigSchema) */
11
+ export interface DocumentCapabilityConfig {
12
+ extract?: {
13
+ enabled?: boolean;
14
+ timeoutMs?: number;
15
+ maxFileBytes?: number;
16
+ allowedRoots?: string[];
17
+ };
18
+ legacy?: {
19
+ converter?: 'none' | 'soffice' | 'remote' | null;
20
+ sofficePath?: string | null;
21
+ timeoutMs?: number;
22
+ cacheDir?: string | null;
23
+ cacheMaxBytes?: number;
24
+ maxInputBytes?: number;
25
+ };
26
+ }
27
+ /**
28
+ * 从 `documents.*` 配置创建 DocumentPort(唯一工厂)。
29
+ *
30
+ * @param cfg - 根配置 documents 段;undefined = 默认 T0 后端、无 legacy 转换
31
+ * @returns DocumentPort
32
+ */
33
+ export declare function createDocumentPortFromConfig(cfg?: DocumentCapabilityConfig | null): DocumentPort;
@@ -0,0 +1,37 @@
1
+ /**
2
+ * Document 能力统一装配 — Gateway / Knowledge 共用同一配置源
3
+ *
4
+ * 禁止调用方各自 `createDefaultDocumentPort` 再拼一份默认值:
5
+ * 那样 soffice/超时/限额会分叉(Knowledge worker 曾因此整批 no_adapter)。
6
+ *
7
+ * @module harness/capabilities/document/factory
8
+ */
9
+ import { createLegacyConverterFromConfig } from './legacy/factory.js';
10
+ import { createDefaultDocumentPort } from './port.js';
11
+ /**
12
+ * 从 `documents.*` 配置创建 DocumentPort(唯一工厂)。
13
+ *
14
+ * @param cfg - 根配置 documents 段;undefined = 默认 T0 后端、无 legacy 转换
15
+ * @returns DocumentPort
16
+ */
17
+ export function createDocumentPortFromConfig(cfg) {
18
+ const extract = cfg?.extract;
19
+ const config = {
20
+ enabled: extract?.enabled !== false,
21
+ ...(extract?.timeoutMs != null ? { timeoutMs: extract.timeoutMs } : {}),
22
+ ...(extract?.maxFileBytes != null ? { maxFileBytes: extract.maxFileBytes } : {}),
23
+ ...(extract?.allowedRoots?.length ? { allowedRoots: extract.allowedRoots } : {}),
24
+ };
25
+ const legacyConverter = createLegacyConverterFromConfig({
26
+ converter: cfg?.legacy?.converter ?? 'none',
27
+ sofficePath: cfg?.legacy?.sofficePath,
28
+ timeoutMs: cfg?.legacy?.timeoutMs,
29
+ cacheDir: cfg?.legacy?.cacheDir,
30
+ cacheMaxBytes: cfg?.legacy?.cacheMaxBytes,
31
+ maxInputBytes: cfg?.legacy?.maxInputBytes,
32
+ });
33
+ return createDefaultDocumentPort({
34
+ config,
35
+ ...(legacyConverter ? { legacyConverter } : {}),
36
+ });
37
+ }