@octopi-agent/engine 0.55.0 → 0.56.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 (56) hide show
  1. package/dist/config-schema/context.d.ts +38 -0
  2. package/dist/config-schema/context.js +39 -0
  3. package/dist/config-schema/engine.d.ts +37 -0
  4. package/dist/config-schema/engine.js +3 -1
  5. package/dist/config.d.ts +35 -0
  6. package/dist/harness/context/capabilities/document/backends/docx.d.ts +7 -0
  7. package/dist/harness/context/capabilities/document/backends/docx.js +67 -0
  8. package/dist/harness/context/capabilities/document/backends/office-parser.d.ts +7 -0
  9. package/dist/harness/context/capabilities/document/backends/office-parser.js +76 -0
  10. package/dist/harness/context/capabilities/document/backends/pdf.d.ts +7 -0
  11. package/dist/harness/context/capabilities/document/backends/pdf.js +86 -0
  12. package/dist/harness/context/capabilities/document/backends/plain.d.ts +7 -0
  13. package/dist/harness/context/capabilities/document/backends/plain.js +42 -0
  14. package/dist/harness/context/capabilities/document/backends/sheet.d.ts +7 -0
  15. package/dist/harness/context/capabilities/document/backends/sheet.js +90 -0
  16. package/dist/harness/context/capabilities/document/backends/xmind.d.ts +20 -0
  17. package/dist/harness/context/capabilities/document/backends/xmind.js +198 -0
  18. package/dist/harness/context/capabilities/document/errors.d.ts +27 -0
  19. package/dist/harness/context/capabilities/document/errors.js +33 -0
  20. package/dist/harness/context/capabilities/document/format.d.ts +38 -0
  21. package/dist/harness/context/capabilities/document/format.js +113 -0
  22. package/dist/harness/context/capabilities/document/html-to-md.d.ts +14 -0
  23. package/dist/harness/context/capabilities/document/html-to-md.js +97 -0
  24. package/dist/harness/context/capabilities/document/index.d.ts +21 -0
  25. package/dist/harness/context/capabilities/document/index.js +20 -0
  26. package/dist/harness/context/capabilities/document/legacy/factory.d.ts +13 -0
  27. package/dist/harness/context/capabilities/document/legacy/factory.js +23 -0
  28. package/dist/harness/context/capabilities/document/legacy/soffice.d.ts +32 -0
  29. package/dist/harness/context/capabilities/document/legacy/soffice.js +186 -0
  30. package/dist/harness/context/capabilities/document/port.d.ts +19 -0
  31. package/dist/harness/context/capabilities/document/port.js +400 -0
  32. package/dist/harness/context/capabilities/document/types.d.ts +149 -0
  33. package/dist/harness/context/capabilities/document/types.js +8 -0
  34. package/dist/harness/context/capabilities/index.d.ts +1 -0
  35. package/dist/harness/context/capabilities/index.js +1 -0
  36. package/dist/harness/extension/plugin-ecosystem/tools/builtin.d.ts +1 -0
  37. package/dist/harness/extension/plugin-ecosystem/tools/builtin.js +10 -0
  38. package/dist/harness/extension/plugin-ecosystem/tools/document-tools.d.ts +64 -0
  39. package/dist/harness/extension/plugin-ecosystem/tools/document-tools.js +155 -0
  40. package/dist/harness/extension/plugin-ecosystem/tools/index.d.ts +1 -0
  41. package/dist/harness/extension/plugin-ecosystem/tools/index.js +1 -0
  42. package/dist/harness/extension/plugin-ecosystem/tools/tool-set.d.ts +2 -0
  43. package/dist/harness/extension/plugin-ecosystem/tools/tool-set.js +4 -1
  44. package/dist/harness/index.d.ts +2 -2
  45. package/dist/harness/index.js +1 -1
  46. package/dist/harness/knowledge/index-store.d.ts +7 -1
  47. package/dist/harness/knowledge/index-store.js +6 -0
  48. package/dist/harness/knowledge/ingest.d.ts +23 -0
  49. package/dist/harness/knowledge/ingest.js +81 -3
  50. package/dist/harness/session/attachments/extract.d.ts +3 -2
  51. package/dist/harness/session/attachments/extract.js +19 -6
  52. package/dist/harness/session/attachments/service.d.ts +5 -1
  53. package/dist/harness/session/attachments/service.js +44 -2
  54. package/dist/index.d.ts +2 -2
  55. package/dist/index.js +1 -1
  56. package/package.json +8 -3
@@ -0,0 +1,149 @@
1
+ /**
2
+ * Document 公用能力 — 类型契约
3
+ *
4
+ * 读路径统一抽取为 Markdown;写路径不进本 Port。
5
+ *
6
+ * @module harness/context/capabilities/document/types
7
+ */
8
+ /** 品牌 ID:后端名 / 转换器名 */
9
+ export type DocumentBackendId = string;
10
+ export type DocumentFormatHint = 'pdf' | 'docx' | 'xlsx' | 'pptx' | 'doc' | 'xls' | 'ppt' | 'rtf' | 'odt' | 'ods' | 'odp' | 'odg' | 'html' | 'md' | 'csv' | 'txt' | 'epub' | 'tex' | 'xmind' | 'unknown';
11
+ export interface ExtractSource {
12
+ /** 本地路径(首选;调用方负责 toolIsolation / attachments root 约束) */
13
+ path?: string;
14
+ /** 或字节流(上传附件等) */
15
+ data?: Uint8Array;
16
+ /** 逻辑名(用于格式嗅探与 meta) */
17
+ name?: string;
18
+ /** 强制格式;缺省按扩展名 + magic */
19
+ formatHint?: DocumentFormatHint;
20
+ /** 加密文档密码(不落盘、不进日志) */
21
+ password?: string;
22
+ }
23
+ export type ExtractTier = 'auto' | 't0' | 't1' | 't2';
24
+ export interface ExtractOptions {
25
+ /** 页/表范围等;后端可忽略并 warn */
26
+ pageRange?: string;
27
+ /** 是否请求 OCR(无 OCR 后端时 warn 并继续文本层) */
28
+ ocr?: boolean;
29
+ /** 硬超时 ms */
30
+ timeoutMs?: number;
31
+ /** 仅用某档;默认 auto = t0 → t1 → t2 */
32
+ tier?: ExtractTier;
33
+ /** 取消 / 会话级 abort */
34
+ signal?: AbortSignal;
35
+ }
36
+ export interface DocumentMeta {
37
+ format: DocumentFormatHint;
38
+ pages?: number;
39
+ title?: string;
40
+ author?: string;
41
+ language?: string;
42
+ /** 云/增强后端结构化字段 */
43
+ fields?: Record<string, string>;
44
+ /** 老格式转换记录 */
45
+ legacyConversion?: {
46
+ from: DocumentFormatHint;
47
+ converter: string;
48
+ cached: boolean;
49
+ };
50
+ }
51
+ export type ExtractWarningCode = 'OCR_UNAVAILABLE' | 'OCR_FAILED' | 'PARTIAL_EXTRACT' | 'LEGACY_CONVERTER_MISSING' | 'LEGACY_CONVERT_FAILED' | 'PASSWORD_REQUIRED' | 'PASSWORD_INCORRECT' | 'DEGRADED_BACKEND' | 'TIMEOUT' | 'RESOURCE_LIMIT';
52
+ export interface ExtractWarning {
53
+ code: ExtractWarningCode;
54
+ message: string;
55
+ }
56
+ export type ExtractErrorCode = 'UNSUPPORTED_FORMAT' | 'UNSUPPORTED_LEGACY' | 'PASSWORD_REQUIRED' | 'PASSWORD_INCORRECT' | 'FILE_TOO_LARGE' | 'TIMEOUT' | 'BACKEND_UNAVAILABLE' | 'INVALID_SOURCE' | 'PATH_FORBIDDEN';
57
+ export interface ExtractResult {
58
+ /** 统一契约:Markdown */
59
+ markdown: string;
60
+ meta: DocumentMeta;
61
+ warnings: ExtractWarning[];
62
+ /** 实际使用的后端,便于诊断 */
63
+ backend: DocumentBackendId;
64
+ /** true = 降级完成(如 T1 不可用退回 T0) */
65
+ degraded?: boolean;
66
+ }
67
+ export type FormatSupportLevel = 'native' | 'via-converter' | 'via-enhanced' | 'via-cloud' | 'none';
68
+ export interface DocumentCapabilities {
69
+ formats: Record<DocumentFormatHint, {
70
+ level: FormatSupportLevel;
71
+ backend?: DocumentBackendId;
72
+ notes?: string;
73
+ }>;
74
+ ocr: boolean;
75
+ legacyConverter?: 'soffice' | 'remote' | 'none';
76
+ tiers: {
77
+ t0: true;
78
+ t1: boolean;
79
+ t2: boolean;
80
+ };
81
+ }
82
+ export interface ProbeResult {
83
+ format: DocumentFormatHint;
84
+ level: FormatSupportLevel;
85
+ }
86
+ export interface DocumentPort {
87
+ /**
88
+ * 抽取为 Markdown。
89
+ *
90
+ * @param source - 路径或字节流
91
+ * @param options - 页范围 / OCR / 超时 / 档位
92
+ * @throws DocumentExtractError 不可用/不支持/密码错误等结构化失败
93
+ */
94
+ extract(source: ExtractSource, options?: ExtractOptions): Promise<ExtractResult>;
95
+ /** 探测本部署能力(可缓存;后端变更时失效) */
96
+ capabilities(): Promise<DocumentCapabilities>;
97
+ /**
98
+ * 是否接受该输入(轻量,不完整解析)。
99
+ *
100
+ * @param source - 路径或字节流
101
+ * @returns 格式与建议层级;不接受则 level: 'none'
102
+ */
103
+ probe(source: ExtractSource): Promise<ProbeResult>;
104
+ }
105
+ /** 老格式 → 中间态转换器(P1 接入;接口先定) */
106
+ export interface LegacyConverter {
107
+ id: 'soffice' | 'remote' | string;
108
+ isAvailable(): Promise<boolean>;
109
+ convert(source: ExtractSource, target: 'docx' | 'xlsx' | 'pptx' | 'pdf'): Promise<{
110
+ data: Uint8Array;
111
+ meta: DocumentMeta;
112
+ }>;
113
+ }
114
+ export type DocumentExtractBackendTier = 't0' | 't1' | 't2';
115
+ export interface BackendAcceptInput {
116
+ format: DocumentFormatHint;
117
+ name?: string;
118
+ head?: Uint8Array;
119
+ }
120
+ export interface DocumentExtractBackend {
121
+ id: DocumentBackendId;
122
+ tier: DocumentExtractBackendTier;
123
+ formats: DocumentFormatHint[];
124
+ /** 运行时是否可用(依赖、二进制、凭据) */
125
+ isAvailable(): Promise<boolean>;
126
+ accepts(input: BackendAcceptInput): boolean;
127
+ extract(source: ResolvedExtractSource, options: ExtractOptions): Promise<ExtractResult>;
128
+ }
129
+ /** 路由后交给后端的输入:保证有 bytes */
130
+ export interface ResolvedExtractSource {
131
+ name?: string;
132
+ data: Uint8Array;
133
+ formatHint?: DocumentFormatHint;
134
+ password?: string;
135
+ }
136
+ export interface DocumentPortConfig {
137
+ enabled?: boolean;
138
+ timeoutMs?: number;
139
+ maxFileBytes?: number;
140
+ /** 路径允许根;未设置则不限制(由调用方约束) */
141
+ allowedRoots?: string[];
142
+ }
143
+ export interface CreateDocumentPortOptions {
144
+ config?: DocumentPortConfig;
145
+ backends?: DocumentExtractBackend[];
146
+ legacyConverter?: LegacyConverter | null;
147
+ /** 能力缓存 TTL ms(默认 5min) */
148
+ capabilitiesTtlMs?: number;
149
+ }
@@ -0,0 +1,8 @@
1
+ /**
2
+ * Document 公用能力 — 类型契约
3
+ *
4
+ * 读路径统一抽取为 Markdown;写路径不进本 Port。
5
+ *
6
+ * @module harness/context/capabilities/document/types
7
+ */
8
+ export {};
@@ -7,4 +7,5 @@
7
7
  */
8
8
  export * from './summary/index.js';
9
9
  export * from './compact/index.js';
10
+ export * from './document/index.js';
10
11
  export { createMemorySummaryCache } from './summary/memory-cache.js';
@@ -7,4 +7,5 @@
7
7
  */
8
8
  export * from './summary/index.js';
9
9
  export * from './compact/index.js';
10
+ export * from './document/index.js';
10
11
  export { createMemorySummaryCache } from './summary/memory-cache.js';
@@ -98,4 +98,5 @@ export declare function createFileListTool(options?: {
98
98
  /** 获取内置工具(零依赖,所有环境可用)。shell 靠后注册,提示模型优先专用工具 */
99
99
  export declare function getBuiltinTools(options?: {
100
100
  summary?: import('../../../context/capabilities/summary/index.js').ToolSummarySupport;
101
+ documentPort?: import('./document-tools.js').DocumentToolOptions['documentPort'];
101
102
  }): RegisteredTool[];
@@ -21,6 +21,7 @@ import { createFileEditTool } from './file-edit.js';
21
21
  import { createFileSearchTool } from './file-search.js';
22
22
  import { createHttpRequestTool } from './http.js';
23
23
  import { createEnvInfoTool } from './env-info.js';
24
+ import { createDocumentProbeTool, createDocumentReadTool } from './document-tools.js';
24
25
  import { defaultPathEnv, isUnderAttachmentRoot, resolvePlatformShell, resolveReadableToolPath, resolveToolPath, } from './platform.js';
25
26
  /**
26
27
  * Shell 工具 — 执行 shell 命令
@@ -563,6 +564,15 @@ export function getBuiltinTools(options) {
563
564
  createFileWriteTool(),
564
565
  createFileEditTool(),
565
566
  createFileSearchTool(),
567
+ ...(options?.documentPort
568
+ ? [
569
+ createDocumentReadTool({
570
+ summary: options.summary,
571
+ documentPort: options.documentPort,
572
+ }),
573
+ createDocumentProbeTool({ documentPort: options.documentPort }),
574
+ ]
575
+ : []),
566
576
  createHttpRequestTool({ summary: options?.summary }),
567
577
  createEnvInfoTool(),
568
578
  createShellTool({ summary: options?.summary }),
@@ -0,0 +1,64 @@
1
+ /**
2
+ * document_read / document_probe 工具 — DocumentPort 薄封装
3
+ *
4
+ * 只消费 DocumentPort;业务/设计知识留在 skill。
5
+ */
6
+ import type { RegisteredTool } from '@octopi-agent/core/types.js';
7
+ type DocumentPortLike = {
8
+ extract(source: {
9
+ path?: string;
10
+ name?: string;
11
+ }, options?: {
12
+ timeoutMs?: number;
13
+ ocr?: boolean;
14
+ }): Promise<{
15
+ markdown: string;
16
+ meta: {
17
+ format: string;
18
+ pages?: number;
19
+ title?: string;
20
+ };
21
+ warnings: Array<{
22
+ code: string;
23
+ message: string;
24
+ }>;
25
+ backend: string;
26
+ degraded?: boolean;
27
+ }>;
28
+ capabilities(): Promise<{
29
+ formats: Record<string, {
30
+ level: string;
31
+ backend?: string;
32
+ }>;
33
+ ocr: boolean;
34
+ legacyConverter?: string;
35
+ }>;
36
+ probe(source: {
37
+ path?: string;
38
+ name?: string;
39
+ }): Promise<{
40
+ format: string;
41
+ level: string;
42
+ }>;
43
+ };
44
+ export interface DocumentToolOptions {
45
+ documentPort?: DocumentPortLike | null;
46
+ summary?: import('../../../context/capabilities/summary/index.js').ToolSummarySupport;
47
+ /** document_read 默认截断(字符) */
48
+ maxReturnChars?: number;
49
+ }
50
+ /**
51
+ * document_read — 抽取 PDF/Office 为 Markdown
52
+ *
53
+ * @param options - documentPort / summary / maxReturnChars
54
+ * @returns RegisteredTool
55
+ */
56
+ export declare function createDocumentReadTool(options?: DocumentToolOptions): RegisteredTool;
57
+ /**
58
+ * document_probe — 轻量探测格式与可读性
59
+ *
60
+ * @param options - documentPort
61
+ * @returns RegisteredTool
62
+ */
63
+ export declare function createDocumentProbeTool(options?: DocumentToolOptions): RegisteredTool;
64
+ export {};
@@ -0,0 +1,155 @@
1
+ /**
2
+ * document_read / document_probe 工具 — DocumentPort 薄封装
3
+ *
4
+ * 只消费 DocumentPort;业务/设计知识留在 skill。
5
+ */
6
+ import { resolveReadableToolPath } from './platform.js';
7
+ /**
8
+ * document_read — 抽取 PDF/Office 为 Markdown
9
+ *
10
+ * @param options - documentPort / summary / maxReturnChars
11
+ * @returns RegisteredTool
12
+ */
13
+ export function createDocumentReadTool(options) {
14
+ return {
15
+ definition: {
16
+ name: 'document_read',
17
+ description: 'Extract PDF/Office (docx/xlsx/pptx/legacy) to Markdown for reading. Prefer this over shell converters.',
18
+ parameters: {
19
+ path: {
20
+ type: 'string',
21
+ description: 'Path to the document',
22
+ required: true,
23
+ },
24
+ ocr: {
25
+ type: 'boolean',
26
+ description: 'Request OCR for scanned pages (if backend supports it)',
27
+ },
28
+ max_chars: {
29
+ type: 'number',
30
+ description: 'Soft cap on returned markdown (default 20000)',
31
+ },
32
+ summarize: {
33
+ type: 'string',
34
+ description: 'Summary mode after extract: auto | force | off',
35
+ enum: ['auto', 'force', 'off'],
36
+ },
37
+ },
38
+ },
39
+ handler: async (args, context) => {
40
+ const port = options?.documentPort;
41
+ if (!port) {
42
+ throw new Error('document_read unavailable: DocumentPort is not configured (documents.extract.enabled)');
43
+ }
44
+ const rawPath = String(args.path ?? '');
45
+ const cwd = context?.cwd ?? process.cwd();
46
+ const path = resolveReadableToolPath(rawPath, cwd, context?.attachmentRoots);
47
+ try {
48
+ const result = await port.extract({
49
+ path,
50
+ name: path,
51
+ }, {
52
+ ocr: args.ocr === true,
53
+ });
54
+ const maxChars = args.max_chars ?? options?.maxReturnChars ?? 20_000;
55
+ let body = result.markdown;
56
+ let truncated = false;
57
+ if (body.length > maxChars) {
58
+ body = body.slice(0, maxChars);
59
+ truncated = true;
60
+ }
61
+ const { applyToolOutputGate, resolveSupportBinding } = await import('../../../context/capabilities/summary/index.js');
62
+ const support = options?.summary;
63
+ const binding = resolveSupportBinding('document_read', support, maxChars);
64
+ const applied = await applyToolOutputGate({
65
+ tool: 'document_read',
66
+ rawBody: body,
67
+ support: { ...support, binding },
68
+ locator: path,
69
+ kind: 'document',
70
+ summarizeArg: args.summarize,
71
+ truncateHint: 'Extract is truncated; raise max_chars or use summarize=force for an overview.',
72
+ });
73
+ return {
74
+ content: applied.body,
75
+ format: result.meta.format,
76
+ pages: result.meta.pages,
77
+ title: result.meta.title,
78
+ backend: result.backend,
79
+ degraded: result.degraded ?? false,
80
+ warnings: result.warnings,
81
+ truncated: truncated || applied.bodyTruncated,
82
+ rawLength: applied.rawLength,
83
+ summary: applied.summary,
84
+ };
85
+ }
86
+ catch (error) {
87
+ const msg = error instanceof Error ? error.message : String(error);
88
+ const code = typeof error === 'object' && error && 'code' in error
89
+ ? String(error.code)
90
+ : undefined;
91
+ const requires = typeof error === 'object' && error && 'requires' in error
92
+ ? error.requires
93
+ : undefined;
94
+ return {
95
+ error: true,
96
+ code,
97
+ requires,
98
+ message: `document_read failed for "${path}": ${msg}`,
99
+ };
100
+ }
101
+ },
102
+ };
103
+ }
104
+ /**
105
+ * document_probe — 轻量探测格式与可读性
106
+ *
107
+ * @param options - documentPort
108
+ * @returns RegisteredTool
109
+ */
110
+ export function createDocumentProbeTool(options) {
111
+ return {
112
+ definition: {
113
+ name: 'document_probe',
114
+ description: 'Detect document format and whether this deployment can extract it (without full parse).',
115
+ parameters: {
116
+ path: {
117
+ type: 'string',
118
+ description: 'Path to the document',
119
+ required: true,
120
+ },
121
+ },
122
+ },
123
+ handler: async (args, context) => {
124
+ const port = options?.documentPort;
125
+ if (!port) {
126
+ return {
127
+ available: false,
128
+ reason: 'DocumentPort is not configured',
129
+ };
130
+ }
131
+ const rawPath = String(args.path ?? '');
132
+ const cwd = context?.cwd ?? process.cwd();
133
+ const path = resolveReadableToolPath(rawPath, cwd, context?.attachmentRoots);
134
+ try {
135
+ const probe = await port.probe({ path, name: path });
136
+ const caps = await port.capabilities();
137
+ return {
138
+ path,
139
+ format: probe.format,
140
+ level: probe.level,
141
+ extractable: probe.level !== 'none',
142
+ backend: caps.formats[probe.format]?.backend,
143
+ ocr: caps.ocr,
144
+ legacyConverter: caps.legacyConverter,
145
+ };
146
+ }
147
+ catch (error) {
148
+ return {
149
+ error: true,
150
+ message: error instanceof Error ? error.message : String(error),
151
+ };
152
+ }
153
+ },
154
+ };
155
+ }
@@ -1,4 +1,5 @@
1
1
  export { getBuiltinTools } from './builtin.js';
2
+ export { createDocumentReadTool, createDocumentProbeTool } from './document-tools.js';
2
3
  export { createFileEditTool } from './file-edit.js';
3
4
  export { createFileSearchTool } from './file-search.js';
4
5
  export { createHttpRequestTool } from './http.js';
@@ -1,4 +1,5 @@
1
1
  export { getBuiltinTools } from './builtin.js';
2
+ export { createDocumentReadTool, createDocumentProbeTool } from './document-tools.js';
2
3
  export { createFileEditTool } from './file-edit.js';
3
4
  export { createFileSearchTool } from './file-search.js';
4
5
  export { createHttpRequestTool } from './http.js';
@@ -23,6 +23,8 @@ export interface ToolSetConfig {
23
23
  };
24
24
  /** Summary 公用能力(http_request / file_read L1/L2) */
25
25
  summary?: import('../../../context/capabilities/summary/index.js').ToolSummarySupport;
26
+ /** DocumentPort(document_read / document_probe) */
27
+ documentPort?: import('./document-tools.js').DocumentToolOptions['documentPort'];
26
28
  /** Information 历史检索(session_search / session_read) */
27
29
  sessionHistory?: SessionHistoryPort;
28
30
  }
@@ -6,7 +6,10 @@ import { createWebSearchTool } from './web-search.js';
6
6
  import { createSessionHistoryTools } from './session-history.js';
7
7
  export function createToolSet(config) {
8
8
  const taskService = config?.sessionTaskService ?? config?.taskTracker;
9
- const builtin = getBuiltinTools({ summary: config?.summary });
9
+ const builtin = getBuiltinTools({
10
+ summary: config?.summary,
11
+ documentPort: config?.documentPort,
12
+ });
10
13
  const extensions = [
11
14
  ...(config?.memoryStore ? createMemoryTools(config.memoryStore, config?.memory) : []),
12
15
  ...(taskService ? createSessionTaskTools(taskService) : []),
@@ -12,8 +12,8 @@ export type { WebSearchToolOptions } from './extension/plugin-ecosystem/tools/we
12
12
  export { createSessionHistoryPort, resolveHistoryAccess, } from './session/history/index.js';
13
13
  export { createSessionHistoryTools, createSessionSearchTool, createSessionReadTool, } from './extension/plugin-ecosystem/tools/session-history.js';
14
14
  export type { SessionHistoryPort, SessionHistoryQuery, SessionHistorySearchResult, SessionHistoryOptions, } from './session/history/index.js';
15
- export { createSummaryPort, applyToolOutputGate, createDefaultSummaryPolicies, resolveSummaryModel, getToolSummaryBinding, createCompactEngine, createMemorySummaryCache, } from './context/capabilities/index.js';
16
- export type { ContentUnit, ContentKind, ContentChannel, SummaryPort, SummaryPolicy, SummaryResult, ToolSummaryBinding, ToolSummarySupport, CreateSummaryPortOptions, CompactEngine, CompactOptions, CompactOutcome, } from './context/capabilities/index.js';
15
+ export { createSummaryPort, applyToolOutputGate, createDefaultSummaryPolicies, resolveSummaryModel, getToolSummaryBinding, createCompactEngine, createMemorySummaryCache, createDefaultDocumentPort, createDefaultBackends, DocumentExtractError, isDocumentExtractError, } from './context/capabilities/index.js';
16
+ export type { ContentUnit, ContentKind, ContentChannel, SummaryPort, SummaryPolicy, SummaryResult, ToolSummaryBinding, ToolSummarySupport, CreateSummaryPortOptions, CompactEngine, CompactOptions, CompactOutcome, DocumentPort, DocumentCapabilities, DocumentMeta, ExtractResult, ExtractSource, ExtractOptions, ExtractWarning, DocumentExtractBackend, LegacyConverter, CreateDocumentPortOptions, } from './context/capabilities/index.js';
17
17
  export { AgentBuilder, createAgent, isSubsystemAllowed, discoverSubsystemSpecs } from './agent/builder.js';
18
18
  export type { AgentBuildOptions, AgentBuildResult, AgentBuildCoreResult, AgentTraceOptions } from './agent/builder.js';
19
19
  export type { ChannelAdapter, ChannelMessage, ChannelReply } from './extension/plugin-ecosystem/channel-types.js';
@@ -11,7 +11,7 @@ export { createWebSearchTool } from './extension/plugin-ecosystem/tools/web-sear
11
11
  export { createSessionHistoryPort, resolveHistoryAccess, } from './session/history/index.js';
12
12
  export { createSessionHistoryTools, createSessionSearchTool, createSessionReadTool, } from './extension/plugin-ecosystem/tools/session-history.js';
13
13
  // ── Capabilities(公用能力;横切,不计入业务领域口径) ──
14
- export { createSummaryPort, applyToolOutputGate, createDefaultSummaryPolicies, resolveSummaryModel, getToolSummaryBinding, createCompactEngine, createMemorySummaryCache, } from './context/capabilities/index.js';
14
+ export { createSummaryPort, applyToolOutputGate, createDefaultSummaryPolicies, resolveSummaryModel, getToolSummaryBinding, createCompactEngine, createMemorySummaryCache, createDefaultDocumentPort, createDefaultBackends, DocumentExtractError, isDocumentExtractError, } from './context/capabilities/index.js';
15
15
  // ── Agent Building ──
16
16
  export { AgentBuilder, createAgent, isSubsystemAllowed, discoverSubsystemSpecs } from './agent/builder.js';
17
17
  export { setRunTelemetryFactory, getRunTelemetryFactory } from './observability/run-telemetry.js';
@@ -147,4 +147,10 @@ export declare class KnowledgeIndexStore {
147
147
  limit?: number;
148
148
  }): ChunkHit[];
149
149
  }
150
- export declare function hashContent(content: string): string;
150
+ /**
151
+ * 内容指纹(新鲜度判断)
152
+ *
153
+ * @param content - UTF-8 文本或原始字节(二进制文档用 bytes)
154
+ * @returns sha256 hex
155
+ */
156
+ export declare function hashContent(content: string | Uint8Array): string;
@@ -371,6 +371,12 @@ export class KnowledgeIndexStore {
371
371
  return hits.slice(0, limit);
372
372
  }
373
373
  }
374
+ /**
375
+ * 内容指纹(新鲜度判断)
376
+ *
377
+ * @param content - UTF-8 文本或原始字节(二进制文档用 bytes)
378
+ * @returns sha256 hex
379
+ */
374
380
  export function hashContent(content) {
375
381
  return createHash('sha256').update(content).digest('hex');
376
382
  }
@@ -11,6 +11,7 @@ import { type SourceFetcher, type VirtualDocument } from './fetchers.js';
11
11
  import { ConnectorRegistry } from './connectors.js';
12
12
  import type { CredentialStore } from '../governance/credentials/store.js';
13
13
  import type { EmbeddingProvider } from '../memory/sqlite/embedding.js';
14
+ import type { DocumentPort } from '../context/capabilities/document/types.js';
14
15
  export type IngestJobKind = 'parse_file' | 'walk_source' | 'drop_file' | 'embed_source' | 'fetch_doc';
15
16
  export interface IngestProgressEvent {
16
17
  type: 'job' | 'source' | 'error' | 'embed';
@@ -53,6 +54,11 @@ export interface KnowledgeIngestOptions {
53
54
  pollMinIntervalMs?: number;
54
55
  /** 每轮 poll 最多处理源数(成本上限,默认 8) */
55
56
  maxPollPerTick?: number;
57
+ /**
58
+ * DocumentPort:启用后 PDF/Office 等走抽取 → Markdown 切块
59
+ * (缺省 null = 维持 BINARY skip 语义)
60
+ */
61
+ documentPort?: DocumentPort | null;
56
62
  }
57
63
  export declare class KnowledgeIngest extends EventEmitter {
58
64
  private readonly sources;
@@ -74,6 +80,7 @@ export declare class KnowledgeIngest extends EventEmitter {
74
80
  private readonly pollTickMs;
75
81
  private readonly pollMinIntervalMs;
76
82
  private readonly maxPollPerTick;
83
+ private readonly documentPort;
77
84
  private lastEmbedAt;
78
85
  private pollTimer;
79
86
  private running;
@@ -88,6 +95,13 @@ export declare class KnowledgeIngest extends EventEmitter {
88
95
  private disposed;
89
96
  constructor(options: KnowledgeIngestOptions);
90
97
  get indexStore(): KnowledgeIndexStore;
98
+ /**
99
+ * 路径过滤:有 DocumentPort 时文档扩展名不再被 BINARY 短路。
100
+ *
101
+ * @param p - 文件路径
102
+ * @returns 是否跳过
103
+ */
104
+ private shouldSkipFile;
91
105
  /**
92
106
  * 全量/增量索引某源(Phase A)
93
107
  */
@@ -151,6 +165,15 @@ export declare class KnowledgeIngest extends EventEmitter {
151
165
  */
152
166
  private fetchDocJob;
153
167
  private parseOne;
168
+ /**
169
+ * PDF/Office:DocumentPort 抽取为 Markdown 后走 markdownAdapter 切块。
170
+ * 新鲜度以原件字节 hash 为准。
171
+ *
172
+ * @param sourceId - 知识源 id
173
+ * @param filePath - 本地文件路径
174
+ * @returns 是否成功入索引
175
+ */
176
+ private parseDocumentFile;
154
177
  /**
155
178
  * Phase B:嵌入待处理 chunk(批 + 限速;失败不丢,下次再补)
156
179
  */