@h-ai/tools 0.0.0-stage → 1.0.0-beta.31
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.
- package/LICENSE +202 -0
- package/README.en.md +37 -0
- package/README.ja.md +37 -0
- package/README.md +36 -2
- package/dist/chunk-UA7MOYTT.js +413 -0
- package/dist/chunk-UA7MOYTT.js.map +1 -0
- package/dist/index.d.ts +16 -0
- package/dist/index.js +3 -0
- package/dist/index.js.map +1 -0
- package/dist/server/index.d.ts +306 -0
- package/dist/server/index.js +1051 -0
- package/dist/server/index.js.map +1 -0
- package/dist/tools-types-CM0lGuJr.d.ts +199 -0
- package/jobs/.dockerignore +4 -0
- package/jobs/README.md +223 -0
- package/jobs/archives.py +56 -0
- package/jobs/browser/Dockerfile +20 -0
- package/jobs/browser/operation.py +17 -0
- package/jobs/browser/render.mjs +90 -0
- package/jobs/browser_policy.py +36 -0
- package/jobs/documents/Dockerfile +23 -0
- package/jobs/documents/generate.py +165 -0
- package/jobs/documents/operation.py +84 -0
- package/jobs/documents/requirements.txt +3 -0
- package/jobs/hyperframes-runtime.mjs +73 -0
- package/jobs/media_files.py +78 -0
- package/jobs/ocr/Dockerfile +19 -0
- package/jobs/ocr/operation.py +18 -0
- package/jobs/office/Dockerfile +21 -0
- package/jobs/office/office_job.py +65 -0
- package/jobs/office/operation.py +43 -0
- package/jobs/preview_build/Dockerfile +19 -0
- package/jobs/preview_build/build.mjs +552 -0
- package/jobs/preview_build/operation.py +62 -0
- package/jobs/preview_build/package.json +11 -0
- package/jobs/tests/image-smoke.mjs +83 -0
- package/jobs/tests/requirements.txt +4 -0
- package/jobs/tests/test_documents_generate.py +107 -0
- package/jobs/tests/test_hai_tool.py +82 -0
- package/jobs/tests/test_media_jobs.py +449 -0
- package/jobs/tests/test_preview_build.py +213 -0
- package/jobs/tool.py +145 -0
- package/jobs/video_render/Dockerfile +20 -0
- package/jobs/video_render/operation.py +109 -0
- package/jobs/video_render/render.mjs +36 -0
- package/jobs/web_capture/Dockerfile +20 -0
- package/jobs/web_capture/capture.mjs +122 -0
- package/jobs/web_capture/operation.py +65 -0
- package/package.json +62 -3
|
@@ -0,0 +1,306 @@
|
|
|
1
|
+
import { ToolDefinition, Tool, ToolsFunctions, DefineToolOptions, ToolRegistryOptions, ToolRegistryOperations } from '../index.js';
|
|
2
|
+
import { HaiResult } from '@h-ai/core';
|
|
3
|
+
import { RunnerFunctions, RunnerScope, RunnerContext, RunnerExecution, RunnerJson, RunnerEvent } from '@h-ai/runner';
|
|
4
|
+
import 'zod';
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* 已登记作业环境;缺失的环境不会出现在工具目录。
|
|
8
|
+
* @example
|
|
9
|
+
* ```ts
|
|
10
|
+
* import type { JobToolOptions } from '@h-ai/tools/server'
|
|
11
|
+
* function environments(options: JobToolOptions) { return options.environments }
|
|
12
|
+
* ```
|
|
13
|
+
*/
|
|
14
|
+
interface JobToolOptions {
|
|
15
|
+
context: ToolServiceContext;
|
|
16
|
+
files: ToolArtifactAccess;
|
|
17
|
+
runner: RunnerFunctions;
|
|
18
|
+
environments: Partial<Record<'documents' | 'office' | 'ocr' | 'browser' | 'web' | 'preview' | 'video', string>>;
|
|
19
|
+
/** 部署控制的 HTTP 出网代理;仅支持非本机、非链路本地的 IPv4 和显式端口。 */
|
|
20
|
+
browserProxy?: string;
|
|
21
|
+
}
|
|
22
|
+
/**
|
|
23
|
+
* 构造固定命令的容器工具,复用 Runner 已登记的隔离环境。
|
|
24
|
+
* @example 模块内部上下文
|
|
25
|
+
* ```ts
|
|
26
|
+
* function build(options: JobToolOptions) { return createJobTools(options) }
|
|
27
|
+
* ```
|
|
28
|
+
*/
|
|
29
|
+
declare function createJobTools({ context, files, runner, environments, browserProxy }: JobToolOptions): ToolSet;
|
|
30
|
+
|
|
31
|
+
/**
|
|
32
|
+
* 由可信宿主绑定的工具服务身份。执行节点补入真实 RunnerContext。
|
|
33
|
+
* @example
|
|
34
|
+
* ```ts
|
|
35
|
+
* import type { ToolServiceContext } from '@h-ai/tools/server'
|
|
36
|
+
* const context: ToolServiceContext = { scope: { tenantId: 'team', userId: 'alice' }, sessionId: 'task-1' }
|
|
37
|
+
* ```
|
|
38
|
+
*/
|
|
39
|
+
interface ToolServiceContext {
|
|
40
|
+
scope: RunnerScope;
|
|
41
|
+
sessionId?: string;
|
|
42
|
+
signal?: AbortSignal;
|
|
43
|
+
execution?: RunnerContext;
|
|
44
|
+
}
|
|
45
|
+
/**
|
|
46
|
+
* 工具组只保存元数据,不创建额外执行器。
|
|
47
|
+
* @example
|
|
48
|
+
* ```ts
|
|
49
|
+
* import type { ToolGroup } from '@h-ai/tools/server'
|
|
50
|
+
* const group: ToolGroup = { id: 'image', title: 'Images', tools: ['image_generate'] }
|
|
51
|
+
* ```
|
|
52
|
+
*/
|
|
53
|
+
interface ToolGroup {
|
|
54
|
+
id: string;
|
|
55
|
+
title: string;
|
|
56
|
+
tools: readonly string[];
|
|
57
|
+
}
|
|
58
|
+
/**
|
|
59
|
+
* 工具构造函数返回同一内核的定义与可选分组。
|
|
60
|
+
* @example
|
|
61
|
+
* ```ts
|
|
62
|
+
* import type { ToolSet } from '@h-ai/tools/server'
|
|
63
|
+
* const set: ToolSet = { tools: [], groups: [] }
|
|
64
|
+
* ```
|
|
65
|
+
*/
|
|
66
|
+
interface ToolSet {
|
|
67
|
+
tools: Tool[];
|
|
68
|
+
groups?: readonly ToolGroup[];
|
|
69
|
+
environments?: Readonly<Record<string, string>>;
|
|
70
|
+
}
|
|
71
|
+
/**
|
|
72
|
+
* 工具组和独立工具取并集,再排除显式停用的名称;省略表示全部停用。
|
|
73
|
+
* @example
|
|
74
|
+
* ```ts
|
|
75
|
+
* import type { ToolSelection } from '@h-ai/tools/server'
|
|
76
|
+
* const selection: ToolSelection = { groups: ['image'], exclude: ['image_remove_background'] }
|
|
77
|
+
* ```
|
|
78
|
+
*/
|
|
79
|
+
interface ToolSelection {
|
|
80
|
+
groups?: readonly string[];
|
|
81
|
+
tools?: readonly string[];
|
|
82
|
+
exclude?: readonly string[];
|
|
83
|
+
}
|
|
84
|
+
/**
|
|
85
|
+
* 持久幂等键与真实执行编号共同校验工具服务归属。
|
|
86
|
+
* @example
|
|
87
|
+
* ```ts
|
|
88
|
+
* import type { ToolReceipt } from '@h-ai/tools/server'
|
|
89
|
+
* function executionId(receipt: ToolReceipt) { return receipt.id }
|
|
90
|
+
* ```
|
|
91
|
+
*/
|
|
92
|
+
interface ToolReceipt {
|
|
93
|
+
id: string;
|
|
94
|
+
key: string;
|
|
95
|
+
}
|
|
96
|
+
/**
|
|
97
|
+
* Runner 状态与工具结果,不复制任务或租约。
|
|
98
|
+
* @example
|
|
99
|
+
* ```ts
|
|
100
|
+
* import type { ToolRun } from '@h-ai/tools/server'
|
|
101
|
+
* function waiting(run: ToolRun) { return ['queued', 'running', 'cancelling'].includes(run.status) }
|
|
102
|
+
* ```
|
|
103
|
+
*/
|
|
104
|
+
interface ToolRun {
|
|
105
|
+
receipt: ToolReceipt;
|
|
106
|
+
status: RunnerExecution['status'];
|
|
107
|
+
output?: RunnerJson;
|
|
108
|
+
failure?: RunnerExecution['failure'];
|
|
109
|
+
events: RunnerEvent[];
|
|
110
|
+
next: number;
|
|
111
|
+
}
|
|
112
|
+
/**
|
|
113
|
+
* 提交工具名称与 JSON 业务输入;主体不放入请求参数。
|
|
114
|
+
* @example
|
|
115
|
+
* ```ts
|
|
116
|
+
* import type { ToolSubmitRequest } from '@h-ai/tools/server'
|
|
117
|
+
* const request: ToolSubmitRequest = { name: 'image_generate', input: { prompt: 'A mountain' }, idempotencyKey: 'action-1' }
|
|
118
|
+
* ```
|
|
119
|
+
*/
|
|
120
|
+
interface ToolSubmitRequest {
|
|
121
|
+
name: string;
|
|
122
|
+
input: unknown;
|
|
123
|
+
idempotencyKey?: string;
|
|
124
|
+
}
|
|
125
|
+
/**
|
|
126
|
+
* 提交和执行阶段均检查当前业务授权。
|
|
127
|
+
* @example
|
|
128
|
+
* ```ts
|
|
129
|
+
* import type { ToolServiceAuthorization } from '@h-ai/tools/server'
|
|
130
|
+
* function principal(request: ToolServiceAuthorization) { return request.context.scope.userId }
|
|
131
|
+
* ```
|
|
132
|
+
*/
|
|
133
|
+
interface ToolServiceAuthorization {
|
|
134
|
+
context: ToolServiceContext;
|
|
135
|
+
name: string;
|
|
136
|
+
input: unknown;
|
|
137
|
+
phase: 'submit' | 'execute';
|
|
138
|
+
}
|
|
139
|
+
/**
|
|
140
|
+
* 注入 Runner 和工具构造函数,不启动或关闭借入模块。
|
|
141
|
+
* @example
|
|
142
|
+
* ```ts
|
|
143
|
+
* import type { ToolServiceOptions } from '@h-ai/tools/server'
|
|
144
|
+
* function serviceName(options: ToolServiceOptions) { return options.id }
|
|
145
|
+
* ```
|
|
146
|
+
*/
|
|
147
|
+
interface ToolServiceOptions {
|
|
148
|
+
id: string;
|
|
149
|
+
runner: RunnerFunctions;
|
|
150
|
+
createTools: (context: ToolServiceContext) => ToolSet | Promise<ToolSet>;
|
|
151
|
+
enabled: ToolSelection | ((context: ToolServiceContext) => ToolSelection | Promise<ToolSelection>);
|
|
152
|
+
authorize: (request: ToolServiceAuthorization) => boolean | Promise<boolean>;
|
|
153
|
+
runTimeoutMs?: number;
|
|
154
|
+
queueTimeoutMs?: number;
|
|
155
|
+
}
|
|
156
|
+
/**
|
|
157
|
+
* 只交付已启用的工具描述,模型和界面共享该结果。
|
|
158
|
+
* @example
|
|
159
|
+
* ```ts
|
|
160
|
+
* import type { ToolCatalog } from '@h-ai/tools/server'
|
|
161
|
+
* function names(catalog: ToolCatalog) { return catalog.tools.map(tool => tool.name) }
|
|
162
|
+
* ```
|
|
163
|
+
*/
|
|
164
|
+
interface ToolCatalog {
|
|
165
|
+
tools: ToolDefinition[];
|
|
166
|
+
groups: ToolGroup[];
|
|
167
|
+
}
|
|
168
|
+
/**
|
|
169
|
+
* 工具服务实例。关闭仅移除本服务处理器,活跃任务仍由 Runner 管理。
|
|
170
|
+
* @example
|
|
171
|
+
* ```ts
|
|
172
|
+
* import type { ToolService } from '@h-ai/tools/server'
|
|
173
|
+
* function stop(service: ToolService) { service.close() }
|
|
174
|
+
* ```
|
|
175
|
+
*/
|
|
176
|
+
interface ToolService {
|
|
177
|
+
/** 按当前主体和服务的幂等键找回已提交任务;未知键不创建新任务。 */
|
|
178
|
+
find: (idempotencyKey: string, context: ToolServiceContext) => Promise<HaiResult<ToolRun | undefined>>;
|
|
179
|
+
catalog: (context: ToolServiceContext) => Promise<HaiResult<ToolCatalog>>;
|
|
180
|
+
submit: (request: ToolSubmitRequest, context: ToolServiceContext) => Promise<HaiResult<ToolRun>>;
|
|
181
|
+
inspect: (receipt: ToolReceipt, context: ToolServiceContext, options?: {
|
|
182
|
+
after?: number;
|
|
183
|
+
}) => Promise<HaiResult<ToolRun>>;
|
|
184
|
+
cancel: (receipt: ToolReceipt, context: ToolServiceContext) => Promise<HaiResult<ToolRun>>;
|
|
185
|
+
invoke: (request: ToolSubmitRequest, context: ToolServiceContext) => Promise<HaiResult<RunnerJson>>;
|
|
186
|
+
close: () => void;
|
|
187
|
+
}
|
|
188
|
+
/**
|
|
189
|
+
* 服务端工具入口,保留所有轻量工具能力。
|
|
190
|
+
* @example
|
|
191
|
+
* ```ts
|
|
192
|
+
* import { tools } from '@h-ai/tools/server'
|
|
193
|
+
* const registry = tools.createRegistry()
|
|
194
|
+
* ```
|
|
195
|
+
*/
|
|
196
|
+
interface ToolsServerFunctions extends ToolsFunctions {
|
|
197
|
+
createService: (options: ToolServiceOptions) => HaiResult<ToolService>;
|
|
198
|
+
createArtifactTools: typeof createArtifactTools;
|
|
199
|
+
createJobTools: typeof createJobTools;
|
|
200
|
+
}
|
|
201
|
+
|
|
202
|
+
/**
|
|
203
|
+
* 宿主验证所有权之后返回的文件或产物。
|
|
204
|
+
* @example
|
|
205
|
+
* ```ts
|
|
206
|
+
* import type { ToolArtifact } from '@h-ai/tools/server'
|
|
207
|
+
* function size(file: ToolArtifact) { return file.data.byteLength }
|
|
208
|
+
* ```
|
|
209
|
+
*/
|
|
210
|
+
interface ToolArtifact {
|
|
211
|
+
id: string;
|
|
212
|
+
name: string;
|
|
213
|
+
mediaType: string;
|
|
214
|
+
data: Uint8Array;
|
|
215
|
+
kind?: string;
|
|
216
|
+
version?: number;
|
|
217
|
+
}
|
|
218
|
+
/**
|
|
219
|
+
* 业务资源引用,大文件字节不进入任务结果。
|
|
220
|
+
* @example
|
|
221
|
+
* ```ts
|
|
222
|
+
* import type { ToolArtifactReference } from '@h-ai/tools/server'
|
|
223
|
+
* function id(reference: ToolArtifactReference) { return reference.id }
|
|
224
|
+
* ```
|
|
225
|
+
*/
|
|
226
|
+
interface ToolArtifactReference {
|
|
227
|
+
id: string;
|
|
228
|
+
title: string;
|
|
229
|
+
kind: string;
|
|
230
|
+
version: number;
|
|
231
|
+
mediaType: string;
|
|
232
|
+
}
|
|
233
|
+
/**
|
|
234
|
+
* 授权文件读写由宿主复核主体、任务、版本和最终提交条件。
|
|
235
|
+
* @example
|
|
236
|
+
* ```ts
|
|
237
|
+
* import type { ToolArtifactAccess } from '@h-ai/tools/server'
|
|
238
|
+
* function reader(access: ToolArtifactAccess) { return access.read }
|
|
239
|
+
* ```
|
|
240
|
+
*/
|
|
241
|
+
interface ToolArtifactAccess {
|
|
242
|
+
read: (context: ToolServiceContext, input: {
|
|
243
|
+
id: string;
|
|
244
|
+
}) => Promise<HaiResult<ToolArtifact>>;
|
|
245
|
+
publish: (context: ToolServiceContext, input: {
|
|
246
|
+
name: string;
|
|
247
|
+
kind: string;
|
|
248
|
+
mediaType: string;
|
|
249
|
+
data: Uint8Array;
|
|
250
|
+
id?: string;
|
|
251
|
+
}) => Promise<HaiResult<ToolArtifactReference>>;
|
|
252
|
+
save?: (context: ToolServiceContext, input: {
|
|
253
|
+
id: string;
|
|
254
|
+
baseVersion: number;
|
|
255
|
+
content: string;
|
|
256
|
+
}) => Promise<HaiResult<ToolArtifactReference>>;
|
|
257
|
+
}
|
|
258
|
+
|
|
259
|
+
/**
|
|
260
|
+
* 可编辑产物工具所需的宿主权限接口。
|
|
261
|
+
* @example
|
|
262
|
+
* ```ts
|
|
263
|
+
* import type { ArtifactToolOptions } from '@h-ai/tools/server'
|
|
264
|
+
* function owner(options: ArtifactToolOptions) { return options.context.scope.userId }
|
|
265
|
+
* ```
|
|
266
|
+
*/
|
|
267
|
+
interface ArtifactToolOptions {
|
|
268
|
+
context: ToolServiceContext;
|
|
269
|
+
files: ToolArtifactAccess;
|
|
270
|
+
}
|
|
271
|
+
/**
|
|
272
|
+
* 构造可编辑产物及数据分析工具,持久化由宿主负责。
|
|
273
|
+
* @example 模块内部上下文
|
|
274
|
+
* ```ts
|
|
275
|
+
* function build(options: ArtifactToolOptions) { return createArtifactTools(options) }
|
|
276
|
+
* ```
|
|
277
|
+
*/
|
|
278
|
+
declare function createArtifactTools({ context, files }: ArtifactToolOptions): ToolSet;
|
|
279
|
+
|
|
280
|
+
/**
|
|
281
|
+
* 创建共享 Runner 上的工具服务。工厂只登记本服务的处理器,不管理 Runner 生命周期。
|
|
282
|
+
* @example 模块内部上下文
|
|
283
|
+
* ```ts
|
|
284
|
+
* function configure(options: ToolServiceOptions) { return createToolService(options) }
|
|
285
|
+
* ```
|
|
286
|
+
*/
|
|
287
|
+
declare function createToolService(options: ToolServiceOptions): HaiResult<ToolService>;
|
|
288
|
+
|
|
289
|
+
/**
|
|
290
|
+
* 服务端工具入口:借用 Runner 执行,资源存取由宿主授权。
|
|
291
|
+
* @example
|
|
292
|
+
* ```ts
|
|
293
|
+
* import { tools } from '@h-ai/tools/server'
|
|
294
|
+
* const registry = tools.createRegistry()
|
|
295
|
+
* ```
|
|
296
|
+
*/
|
|
297
|
+
declare const tools: {
|
|
298
|
+
createService: typeof createToolService;
|
|
299
|
+
createArtifactTools: typeof createArtifactTools;
|
|
300
|
+
createJobTools: typeof createJobTools;
|
|
301
|
+
define: <TInput, TOutput>(options: DefineToolOptions<TInput, TOutput>) => Tool<TInput, TOutput>;
|
|
302
|
+
createRegistry: (options?: ToolRegistryOptions) => ToolRegistryOperations;
|
|
303
|
+
};
|
|
304
|
+
|
|
305
|
+
export { tools };
|
|
306
|
+
export type { ArtifactToolOptions, JobToolOptions, ToolArtifact, ToolArtifactAccess, ToolArtifactReference, ToolCatalog, ToolGroup, ToolReceipt, ToolRun, ToolSelection, ToolService, ToolServiceAuthorization, ToolServiceContext, ToolServiceOptions, ToolSet, ToolSubmitRequest, ToolsServerFunctions };
|