@ai-zen/agents-sdk 0.5.7 → 0.7.0

package/dist/capabilities/implements/builtin/ExecAsyncTool.js

@@ -1,33 +1,31 @@
 import { spawn } from "child_process";
 import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
 export class ExecAsyncTool extends SdkCallbackTool {
-    constructor(env) {
-        super({
-            function: {
-                name: "exec_async",
-                description: "异步执行命令，启动程序后立即返回，不等待执行结果。适用于启动长期运行的进程（如服务器、监听程序、GUI应用等）或不需要等待结果的命令。注意：该工具本身不捕获命令的输出；若需获取/留存输出，可在命令中使用 shell 重定向写入文件（如 `> /path/file`，支持 `>>` 追加、`|` 管道）。命令经 shell 解析执行。",
-                parameters: {
-                    type: "object",
-                    properties: {
-                        command: {
-                            type: "string",
-                            description: "要执行的命令（含参数）",
-                        },
-                        cwd: {
-                            type: "string",
-                            description: "工作目录（可选，默认当前工作目录）",
-                        },
-                        detached: {
-                            type: "boolean",
-                            description: "是否完全脱离当前进程组（可选，默认 false）。设为 true 时，即使当前 Agent 进程退出，启动的程序仍会继续运行。适用于需要独立运行的守护进程或 GUI 程序。",
-                        },
-                    },
-                    required: ["command"],
-                    additionalProperties: false,
+    function = {
+        name: "exec_async",
+        description: "异步执行命令，启动程序后立即返回，不等待执行结果。适用于启动长期运行的进程（如服务器、监听程序、GUI应用等）或不需要等待结果的命令。注意：该工具本身不捕获命令的输出；若需获取/留存输出，可在命令中使用 shell 重定向写入文件（如 `> /path/file`，支持 `>>` 追加、`|` 管道）。命令经 shell 解析执行。",
+        parameters: {
+            type: "object",
+            properties: {
+                command: {
+                    type: "string",
+                    description: "要执行的命令（含参数）",
+                },
+                cwd: {
+                    type: "string",
+                    description: "工作目录（可选，默认当前工作目录）",
+                },
+                detached: {
+                    type: "boolean",
+                    description: "是否完全脱离当前进程组（可选，默认 false）。设为 true 时，即使当前 Agent 进程退出，启动的程序仍会继续运行。适用于需要独立运行的守护进程或 GUI 程序。",
                 },
             },
-            env,
-        });
+            required: ["command"],
+            additionalProperties: false,
+        },
+    };
+    constructor(env) {
+        super({ env });
     }
     async call(input) {
         const command = input.command;

package/dist/capabilities/implements/builtin/ExecTool.d.ts

@@ -1,9 +1,11 @@
 import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
 import type { ToolEnv } from "../../../types/index.js";
+import type { AgentNS, ToolCallContext } from "@ai-zen/agents-core";
 export declare class ExecTool extends SdkCallbackTool {
+    function: AgentNS.FunctionDefine;
     constructor(env: ToolEnv);
     call(input: {
         command: string;
         timeout: number;
-    }): Promise<string>;
+    }, ctx?: ToolCallContext): Promise<string>;
 }

package/dist/capabilities/implements/builtin/ExecTool.js

@@ -1,52 +1,85 @@
 import { exec } from "child_process";
 import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
 export class ExecTool extends SdkCallbackTool {
-    constructor(env) {
-        super({
-            function: {
-                name: "exec",
-                description: "执行命令",
-                parameters: {
-                    type: "object",
-                    properties: {
-                        command: {
-                            type: "string",
-                            description: "要执行的命令",
-                        },
-                        timeout: {
-                            type: "number",
-                            description: "超时时间（毫秒），必填。超时后会终止进程；超过该时长仍未完成即视为超时并终止。建议长时间运行的命令使用 exec_async 异步执行。",
-                        },
-                    },
-                    required: ["command", "timeout"],
-                    additionalProperties: false,
+    function = {
+        name: "exec",
+        description: "执行命令",
+        parameters: {
+            type: "object",
+            properties: {
+                command: {
+                    type: "string",
+                    description: "要执行的命令",
+                },
+                timeout: {
+                    type: "number",
+                    description: "超时时间（毫秒），必填。超时后会终止进程；超过该时长仍未完成即视为超时并终止。建议长时间运行的命令使用 exec_async 异步执行。",
                 },
             },
-            env,
-        });
+            required: ["command", "timeout"],
+            additionalProperties: false,
+        },
+    };
+    constructor(env) {
+        super({ env });
     }
-    async call(input) {
+    async call(input, ctx) {
         const command = input.command;
         const { timeout } = input;
         // 运行时双校验：timeout 必填且必须为正数
         if (typeof timeout !== "number" || !Number.isFinite(timeout) || timeout <= 0) {
             throw new Error(`exec: 参数 timeout 为必填项，且必须是正数（毫秒），当前值: ${JSON.stringify(timeout)}`);
         }
+        const signal = ctx?.signal;
         const result = await new Promise((resolve) => {
-            const child = exec(command, {
-                cwd: this.env.cwd,
-                timeout,
-            }, (error, stdout, stderr) => {
-                const killed = error?.killed ?? false;
+            // 若 signal 已处于 aborted，直接标记中断结果
+            if (signal?.aborted) {
                 resolve({
+                    stdout: "",
+                    stderr: "进程已中断（aborted）",
+                    exitCode: null,
+                    killed: true,
+                    terminated: "aborted",
+                });
+                return;
+            }
+            let child;
+            let settled = false;
+            const settle = (value) => {
+                if (settled)
+                    return;
+                settled = true;
+                signal?.removeEventListener("abort", onAbort);
+                resolve(value);
+            };
+            child = exec(command, { cwd: this.env.cwd, timeout }, (error, stdout, stderr) => {
+                const killed = error?.killed ?? false;
+                const terminated = killed
+                    ? (signal?.aborted ? "aborted" : "timeout")
+                    : undefined;
+                settle({
                     stdout,
                     stderr,
                     exitCode: error?.code ?? (error ? 1 : null),
                     killed,
-                    // 明确告知 agent 命令是因超时被终止（Node 不会自动在 stderr 写入该提示）
-                    terminated: killed ? "timeout" : undefined,
+                    terminated,
                 });
             });
+            // 中断：kill 子进程，令其尽快结束
+            const onAbort = () => {
+                child?.kill("SIGKILL");
+                // 即便 exec 回调因信号处理而未能及时触发，也立即返回中断结果，避免挂起
+                settle({
+                    stdout: "",
+                    stderr: "进程已中断（aborted）",
+                    exitCode: null,
+                    killed: true,
+                    terminated: "aborted",
+                });
+            };
+            if (signal) {
+                signal.addEventListener("abort", onAbort, { once: true });
+            }
         });
         return JSON.stringify(result);
     }

package/dist/capabilities/implements/builtin/ExistTool.d.ts

@@ -1,6 +1,8 @@
 import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
 import type { ToolEnv } from "../../../types/index.js";
+import type { AgentNS } from "@ai-zen/agents-core";
 export declare class ExistTool extends SdkCallbackTool {
+    function: AgentNS.FunctionDefine;
     constructor(env: ToolEnv);
     call(input: {
         path: string;

package/dist/capabilities/implements/builtin/ExistTool.js

@@ -1,25 +1,23 @@
 import * as fsp from "fs/promises";
 import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
 export class ExistTool extends SdkCallbackTool {
-    constructor(env) {
-        super({
-            function: {
-                name: "exist",
-                description: "检查文件或目录是否存在",
-                parameters: {
-                    type: "object",
-                    properties: {
-                        path: {
-                            type: "string",
-                            description: "文件或目录路径",
-                        },
-                    },
-                    required: ["path"],
-                    additionalProperties: false,
+    function = {
+        name: "exist",
+        description: "检查文件或目录是否存在",
+        parameters: {
+            type: "object",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "文件或目录路径",
                 },
             },
-            env,
-        });
+            required: ["path"],
+            additionalProperties: false,
+        },
+    };
+    constructor(env) {
+        super({ env });
     }
     async call(input) {
         return await fsp

package/dist/capabilities/implements/builtin/FindTextTool.d.ts

@@ -1,6 +1,8 @@
 import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
 import type { ToolEnv } from "../../../types/index.js";
+import type { AgentNS, ToolCallContext } from "@ai-zen/agents-core";
 export declare class FindTextTool extends SdkCallbackTool {
+    function: AgentNS.FunctionDefine;
     constructor(env: ToolEnv);
     call(input: {
         path?: string;
@@ -8,5 +10,5 @@ export declare class FindTextTool extends SdkCallbackTool {
         text?: string;
         regex?: string;
         exclude?: string[];
-    }): Promise<string>;
+    }, ctx?: ToolCallContext): Promise<string>;
 }

package/dist/capabilities/implements/builtin/FindTextTool.js

@@ -2,45 +2,44 @@ import * as fsp from "fs/promises";
 import * as path from "path";
 import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
 export class FindTextTool extends SdkCallbackTool {
-    constructor(env) {
-        super({
-            function: {
-                name: "findText",
-                description: "查找文本出现的位置，支持普通文本或正则匹配，返回文件名及具体行号、行内容",
-                parameters: {
-                    type: "object",
-                    properties: {
-                        path: {
-                            type: "string",
-                            description: "glob cwd",
-                        },
-                        pattern: {
-                            type: "string",
-                            description: "glob pattern",
-                        },
-                        text: {
-                            type: "string",
-                            description: "要查找的文本（与 regex 二选一）",
-                        },
-                        regex: {
-                            type: "string",
-                            description: "正则表达式（与 text 二选一，例如 \\bconst\\s+\\w+）",
-                        },
-                        exclude: {
-                            type: "array",
-                            description: "要排除的 glob 模式数组",
-                            items: {
-                                type: "string",
-                            },
-                        },
+    function = {
+        name: "findText",
+        description: "查找文本出现的位置，支持普通文本或正则匹配，返回文件名及具体行号、行内容",
+        parameters: {
+            type: "object",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "glob cwd",
+                },
+                pattern: {
+                    type: "string",
+                    description: "glob pattern",
+                },
+                text: {
+                    type: "string",
+                    description: "要查找的文本（与 regex 二选一）",
+                },
+                regex: {
+                    type: "string",
+                    description: "正则表达式（与 text 二选一，例如 \\bconst\\s+\\w+）",
+                },
+                exclude: {
+                    type: "array",
+                    description: "要排除的 glob 模式数组",
+                    items: {
+                        type: "string",
                     },
-                    required: ["path", "pattern"],
                 },
             },
-            env,
-        });
+            required: ["path", "pattern"],
+        },
+    };
+    constructor(env) {
+        super({ env });
     }
-    async call(input) {
+    async call(input, ctx) {
+        const signal = ctx?.signal;
         try {
             const cwd = input.path ? this.resolve(input.path) : this.env.cwd;
             const result = [];
@@ -54,10 +53,16 @@ export class FindTextTool extends SdkCallbackTool {
                 cwd,
                 exclude: input.exclude || ["**/node_modules/**"],
             })) {
+                if (signal?.aborted)
+                    break; // 中断：停止继续遍历/消费
                 const fullPath = path.join(cwd, file);
                 const stats = await fsp.stat(fullPath);
+                if (signal?.aborted)
+                    break; // 中断：stat 后再次检查
                 if (stats.isFile()) {
                     const content = await fsp.readFile(fullPath, "utf-8");
+                    if (signal?.aborted)
+                        break; // 中断：readFile 后再次检查
                     const lines = content.split("\n");
                     const matches = [];
                     lines.forEach((lineContent, index) => {
@@ -83,6 +88,9 @@ export class FindTextTool extends SdkCallbackTool {
                     }
                 }
             }
+            if (signal?.aborted) {
+                return JSON.stringify({ aborted: true, results: result });
+            }
             return JSON.stringify(result);
         }
         catch (error) {

package/dist/capabilities/implements/builtin/GenerateImageTool.d.ts

@@ -1,21 +1,23 @@
+import type { AgentNS, ToolCallContext } from "@ai-zen/agents-core";
 import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
-import type { ToolEnv } from "../../../types/index.js";
+import type { AgentDefinition, AppConfig, ToolEnv } from "../../../types/index.js";
 /**
- * 根据文字描述生成图片。返回图片 URL，可通过 downloadFile 工具保存到本地。
+ * 根据文字描述生成图片。**统一返回字符串**（JSON，含图片 URL 列表）：
+ * 生成结果如何处理（查看/下载/转发）由模型与上层自由决定——
+ * 需要让模型看图时，模型可主动调用 viewImage(URL)；需要保存时用 downloadFile。
  *
- * 依赖 AppConfig 中的 imageModels 和 defaultImageModel 配置。
- * 如果未配置图片模型，工具会返回错误提示。
- *
- * 注意：与其它内置工具不同，generateImage 依赖图片模型配置，
- * 因此由 discoverBuiltinTools 按 env.config.defaultImageModel 条件实例化，
- * 不加入 BUILTIN_TOOL_CLASSES 静态注册表。
+ * 依赖 AppConfig 中的 imageModels 和 defaultImageModel 配置（isAvailable 声明），
+ * 未配置时由 buildTools 过滤，不暴露给 Agent。
  */
 export declare class GenerateImageTool extends SdkCallbackTool {
+    /** 依赖图片模型配置（defaultImageModel），未配置时由 buildTools 按 isAvailable 过滤 */
+    isAvailable(config: AppConfig, _definition: AgentDefinition): boolean;
+    function: AgentNS.FunctionDefine;
     constructor(env: ToolEnv);
     call(input: {
         prompt: string;
         model?: string;
         size?: string;
         quality?: string;
-    }): Promise<string>;
+    }, ctx?: ToolCallContext): Promise<string>;
 }

package/dist/capabilities/implements/builtin/GenerateImageTool.js

@@ -1,50 +1,51 @@
-import { OpenAI, ZhipuImage } from "@ai-zen/agents-core";
+import OpenAI from "openai";
 import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
 /**
- * 根据文字描述生成图片。返回图片 URL，可通过 downloadFile 工具保存到本地。
+ * 根据文字描述生成图片。**统一返回字符串**（JSON，含图片 URL 列表）：
+ * 生成结果如何处理（查看/下载/转发）由模型与上层自由决定——
+ * 需要让模型看图时，模型可主动调用 viewImage(URL)；需要保存时用 downloadFile。
  *
- * 依赖 AppConfig 中的 imageModels 和 defaultImageModel 配置。
- * 如果未配置图片模型，工具会返回错误提示。
- *
- * 注意：与其它内置工具不同，generateImage 依赖图片模型配置，
- * 因此由 discoverBuiltinTools 按 env.config.defaultImageModel 条件实例化，
- * 不加入 BUILTIN_TOOL_CLASSES 静态注册表。
+ * 依赖 AppConfig 中的 imageModels 和 defaultImageModel 配置（isAvailable 声明），
+ * 未配置时由 buildTools 过滤，不暴露给 Agent。
  */
 export class GenerateImageTool extends SdkCallbackTool {
-    constructor(env) {
-        super({
-            function: {
-                name: "generateImage",
-                description: "根据文字描述生成图片。返回图片 URL，可通过 downloadFile 工具保存到本地。",
-                parameters: {
-                    type: "object",
-                    properties: {
-                        prompt: {
-                            type: "string",
-                            description: "所需图像的文本描述，应详细描述画面内容、风格、构图等",
-                        },
-                        model: {
-                            type: "string",
-                            description: "图片模型 ID，不指定则使用配置中的默认图片模型。配置中的图片模型可通过 'aiz config show' 查看。",
-                        },
-                        size: {
-                            type: "string",
-                            description: '图片尺寸。不指定则使用模型的默认尺寸。cogview系列: 1024x1024, 768x1344, 864x1152, 1344x768, 1152x864, 1440x720, 720x1440。glm-image: 1280x1280, 1568x1056, 1056x1568, 1472x1088, 1088x1472, 1728x960, 960x1728。',
-                        },
-                        quality: {
-                            type: "string",
-                            description: "图像质量。hd: 精细(约20秒), standard: 快速(约5-10秒)",
-                            enum: ["hd", "standard"],
-                        },
-                    },
-                    required: ["prompt"],
-                    additionalProperties: false,
+    /** 依赖图片模型配置（defaultImageModel），未配置时由 buildTools 按 isAvailable 过滤 */
+    isAvailable(config, _definition) {
+        return !!config.defaultImageModel;
+    }
+    function = {
+        name: "generateImage",
+        description: "根据文字描述生成图片，返回图片 URL 列表（JSON）。如需查看图片内容，请用 viewImage 工具（传入图片 URL）；如需保存到本地，用 downloadFile 下载。",
+        parameters: {
+            type: "object",
+            properties: {
+                prompt: {
+                    type: "string",
+                    description: "所需图像的文本描述，应详细描述画面内容、风格、构图等",
+                },
+                model: {
+                    type: "string",
+                    description: "图片模型 ID，不指定则使用配置中的默认图片模型。配置中的图片模型可通过 'aiz config show' 查看。",
+                },
+                size: {
+                    type: "string",
+                    description: '图片尺寸。不指定则使用模型的默认尺寸。cogview系列: 1024x1024, 768x1344, 864x1152, 1344x768, 1152x864, 1440x720, 720x1440。glm-image: 1280x1280, 1568x1056, 1056x1568, 1472x1088, 1088x1472, 1728x960, 960x1728。',
+                },
+                quality: {
+                    type: "string",
+                    description: "图像质量。hd: 精细(约20秒), standard: 快速(约5-10秒)",
+                    enum: ["hd", "standard"],
                 },
             },
-            env,
-        });
+            required: ["prompt"],
+            additionalProperties: false,
+        },
+    };
+    constructor(env) {
+        super({ env });
     }
-    async call(input) {
+    async call(input, ctx) {
+        const signal = ctx?.signal;
         try {
             const prompt = input.prompt;
             if (!prompt || !prompt.trim()) {
@@ -82,36 +83,42 @@ export class GenerateImageTool extends SdkCallbackTool {
                     error: `端点 "${endpoint.name}" 的 API Key 未设置`,
                 });
             }
-            const ep = new OpenAI({
-                openai_endpoint: endpoint.baseUrl,
-                api_key: endpoint.apiKey,
+            const client = new OpenAI({
+                apiKey: endpoint.apiKey,
+                baseURL: endpoint.baseUrl,
             });
             const modelName = input.model || imageModel.modelName;
-            const model = new ZhipuImage({
-                request_config: await ep.imageGeneration(modelName),
-            });
-            const result = await model.generate({
-                prompt: prompt.trim(),
+            // 通过官方 SDK 生成图片（厂商特有字段如 size/quality 用 any 透传）
+            const result = await client.images.generate({
                 model: modelName,
+                prompt: prompt.trim(),
                 size: input.size || imageModel.defaultSize || undefined,
                 quality: input.quality || imageModel.defaultQuality || undefined,
-            });
-            const images = result.data.map((img, i) => ({
-                index: i,
-                url: img.url,
-                description: `图片 ${i + 1}`,
-            }));
+            }, { signal });
+            const urls = (result.data ?? [])
+                .map((img) => img.url)
+                .filter((url) => !!url);
+            // 统一返回字符串（JSON）：生成结果如何处理（查看/下载/转发）由模型与上层自由决定，
+            // 不替模型做「看或不看」的假设。需要让模型看图 → 模型可主动调用 viewImage(URL)；
+            // 需要保存 → downloadFile 下载。
             return JSON.stringify({
                 success: true,
                 model: imageModel.name,
                 modelId: imageModel.id,
                 created: result.created,
-                images,
-                content_filter: result.content_filter || [],
-                note: "图片临时链接有效期为30天，请及时转存图片。",
+                images: urls.map((url, i) => ({ index: i, url })),
+                note: "图片临时链接有效期为30天。如需查看图片内容，可用 viewImage 工具（传入图片 URL）；如需保存，可用 downloadFile 下载。",
             }, null, 2);
         }
         catch (error) {
+            // 中断（abort）时返回明确的中断结果
+            if (signal?.aborted) {
+                return JSON.stringify({
+                    success: false,
+                    aborted: true,
+                    error: "图片生成被中断（aborted）",
+                });
+            }
             return JSON.stringify({
                 success: false,
                 error: error instanceof Error ? error.message : "图片生成失败",

package/dist/capabilities/implements/builtin/GlobTool.d.ts

@@ -1,10 +1,12 @@
 import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
 import type { ToolEnv } from "../../../types/index.js";
+import type { AgentNS, ToolCallContext } from "@ai-zen/agents-core";
 export declare class GlobTool extends SdkCallbackTool {
+    function: AgentNS.FunctionDefine;
     constructor(env: ToolEnv);
     call(input: {
         path?: string;
         pattern: string;
         exclude?: string[];
-    }): Promise<string>;
+    }, ctx?: ToolCallContext): Promise<string>;
 }

package/dist/capabilities/implements/builtin/GlobTool.js

@@ -1,38 +1,37 @@
 import * as fsp from "fs/promises";
 import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
 export class GlobTool extends SdkCallbackTool {
-    constructor(env) {
-        super({
-            function: {
-                name: "glob",
-                description: "使用 glob 模式递归扫描和查找文件。这是进行文件系统搜索的首选工具，功能远优于简单的 'ls' 列表命令。当你需要查找特定类型的文件、遍历目录树或需要排除特定文件时，请优先使用此函数。",
-                parameters: {
-                    type: "object",
-                    properties: {
-                        path: {
-                            type: "string",
-                            description: "glob cwd",
-                        },
-                        pattern: {
-                            type: "string",
-                            description: "glob pattern",
-                        },
-                        exclude: {
-                            type: "array",
-                            description: "glob pattern to exclude",
-                            items: {
-                                type: "string",
-                            },
-                        },
+    function = {
+        name: "glob",
+        description: "使用 glob 模式递归扫描和查找文件。这是进行文件系统搜索的首选工具，功能远优于简单的 'ls' 列表命令。当你需要查找特定类型的文件、遍历目录树或需要排除特定文件时，请优先使用此函数。",
+        parameters: {
+            type: "object",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "glob cwd",
+                },
+                pattern: {
+                    type: "string",
+                    description: "glob pattern",
+                },
+                exclude: {
+                    type: "array",
+                    description: "glob pattern to exclude",
+                    items: {
+                        type: "string",
                     },
-                    required: ["pattern"],
-                    additionalProperties: false,
                 },
             },
-            env,
-        });
+            required: ["pattern"],
+            additionalProperties: false,
+        },
+    };
+    constructor(env) {
+        super({ env });
     }
-    async call(input) {
+    async call(input, ctx) {
+        const signal = ctx?.signal;
         try {
             const cwd = input.path ? this.resolve(input.path) : this.env.cwd;
             const result = [];
@@ -40,8 +39,13 @@ export class GlobTool extends SdkCallbackTool {
                 exclude: input.exclude || ["**/node_modules/**"],
                 cwd,
             })) {
+                if (signal?.aborted)
+                    break; // 中断：停止继续遍历/消费
                 result.push(file);
             }
+            if (signal?.aborted) {
+                return JSON.stringify({ aborted: true, files: result });
+            }
             return JSON.stringify(result);
         }
         catch (error) {