@ai-zen/agents-sdk 0.4.0 → 0.5.1

package/dist/capabilities/implements/builtin/{execAsync.js → ExecAsyncTool.js}

@@ -1,39 +1,43 @@
-import { CallbackTool } from "@ai-zen/agents-core";
 import { spawn } from "child_process";
-export const execAsyncTool = new CallbackTool({
-    function: {
-        name: "exec_async",
-        description: "异步执行命令，启动程序后立即返回，不等待执行结果。适用于启动长期运行的进程（如服务器、监听程序、GUI应用等）或不需要等待结果的命令。注意：该工具不会捕获命令的输出，如果需要获取输出请使用 exec。",
-        parameters: {
-            type: "object",
-            properties: {
-                command: {
-                    type: "string",
-                    description: "要执行的命令（含参数）",
-                },
-                cwd: {
-                    type: "string",
-                    description: "工作目录（可选，默认当前目录）",
-                },
-                detached: {
-                    type: "boolean",
-                    description: "是否完全脱离当前进程组（可选，默认 false）。设为 true 时，即使当前 Agent 进程退出，启动的程序仍会继续运行。适用于需要独立运行的守护进程或 GUI 程序。",
+import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+export class ExecAsyncTool extends SdkCallbackTool {
+    constructor(env) {
+        super({
+            function: {
+                name: "exec_async",
+                description: "异步执行命令，启动程序后立即返回，不等待执行结果。适用于启动长期运行的进程（如服务器、监听程序、GUI应用等）或不需要等待结果的命令。注意：该工具不会捕获命令的输出，如果需要获取输出请使用 exec。",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        command: {
+                            type: "string",
+                            description: "要执行的命令（含参数）",
+                        },
+                        cwd: {
+                            type: "string",
+                            description: "工作目录（可选，默认当前工作目录）",
+                        },
+                        detached: {
+                            type: "boolean",
+                            description: "是否完全脱离当前进程组（可选，默认 false）。设为 true 时，即使当前 Agent 进程退出，启动的程序仍会继续运行。适用于需要独立运行的守护进程或 GUI 程序。",
+                        },
+                    },
+                    required: ["command"],
+                    additionalProperties: false,
                 },
             },
-            required: ["command"],
-            additionalProperties: false,
-        },
-    },
-    async callback(input) {
+            env,
+        });
+    }
+    async call(input) {
         const command = input.command;
-        const cwd = input.cwd ?? undefined;
+        const cwd = input.cwd ? this.resolve(input.cwd) : this.env.cwd;
         const detached = input.detached ?? false;
         // Windows 用 shell 模式，其他平台直接 spawn 避免 shell 安全问题
         const useShell = process.platform === "win32";
         return new Promise((resolve) => {
             let child;
             if (useShell) {
-                // Windows: 通过 shell 执行整条命令
                 child = spawn(command, [], {
                     cwd,
                     detached,
@@ -85,7 +89,6 @@ export const execAsyncTool = new CallbackTool({
                     stdio: "ignore",
                 });
             }
-            // 记录是否已 resolve
             let resolved = false;
             child.on("error", (err) => {
                 if (resolved)
@@ -107,7 +110,6 @@ export const execAsyncTool = new CallbackTool({
                     message: `进程已启动 (PID: ${child.pid ?? "unknown"})`,
                 }));
             });
-            // 如果进程很快退出（如命令不存在被 shell 拒绝），捕获退出码
             child.on("exit", (code) => {
                 if (resolved)
                     return;
@@ -121,8 +123,6 @@ export const execAsyncTool = new CallbackTool({
                         : `进程已退出 (PID: ${child.pid ?? "unknown"}, 退出码: ${code})`,
                 }));
             });
-            // 给子进程一点时间来触发 spawn/error/exit 事件
-            // 若 500ms 后仍未触发，认为启动成功
             const timeout = setTimeout(() => {
                 if (resolved)
                     return;
@@ -133,7 +133,6 @@ export const execAsyncTool = new CallbackTool({
                     message: `进程已启动 (PID: ${child.pid ?? "unknown"})`,
                 }));
             }, 500);
-            // 超时后清理
             const cleanup = () => {
                 clearTimeout(timeout);
                 child.removeAllListeners();
@@ -141,8 +140,7 @@ export const execAsyncTool = new CallbackTool({
             child.on("spawn", cleanup);
             child.on("error", cleanup);
             child.on("exit", cleanup);
-            // 允许子进程独立运行（不阻止父进程退出）
             child.unref();
         });
-    },
-});
+    }
+}

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

@@ -0,0 +1,9 @@
+import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import type { ToolEnv } from "../../../types/index.js";
+export declare class ExecTool extends SdkCallbackTool {
+    constructor(env: ToolEnv);
+    call(input: {
+        command: string;
+        timeout?: number;
+    }): Promise<string>;
+}

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

@@ -0,0 +1,46 @@
+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"],
+                    additionalProperties: false,
+                },
+            },
+            env,
+        });
+    }
+    async call(input) {
+        const command = input.command;
+        const timeout = input.timeout;
+        const result = await new Promise((resolve) => {
+            const child = exec(command, {
+                cwd: this.env.cwd,
+                timeout: timeout && timeout > 0 ? timeout : undefined,
+            }, (error, stdout, stderr) => {
+                resolve({
+                    stdout,
+                    stderr,
+                    exitCode: error?.code ?? (error ? 1 : null),
+                    killed: error?.killed ?? false,
+                });
+            });
+        });
+        return JSON.stringify(result);
+    }
+}

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

@@ -0,0 +1,8 @@
+import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import type { ToolEnv } from "../../../types/index.js";
+export declare class ExistTool extends SdkCallbackTool {
+    constructor(env: ToolEnv);
+    call(input: {
+        path: string;
+    }): Promise<string>;
+}

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

@@ -0,0 +1,30 @@
+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,
+                },
+            },
+            env,
+        });
+    }
+    async call(input) {
+        return await fsp
+            .access(this.resolve(input.path))
+            .then(() => "true")
+            .catch(() => "false");
+    }
+}

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

@@ -0,0 +1,12 @@
+import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import type { ToolEnv } from "../../../types/index.js";
+export declare class FindTextTool extends SdkCallbackTool {
+    constructor(env: ToolEnv);
+    call(input: {
+        path?: string;
+        pattern: string;
+        text?: string;
+        regex?: string;
+        exclude?: string[];
+    }): Promise<string>;
+}

package/dist/capabilities/implements/builtin/{findText.js → FindTextTool.js}

@@ -1,42 +1,48 @@
-import { CallbackTool } from "@ai-zen/agents-core";
 import * as fsp from "fs/promises";
 import * as path from "path";
-export const findTextTool = new CallbackTool({
-    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",
+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",
+                            },
+                        },
                     },
+                    required: ["path", "pattern"],
                 },
             },
-            required: ["path", "pattern"],
-        },
-    },
-    async callback(input) {
+            env,
+        });
+    }
+    async call(input) {
         try {
+            const cwd = input.path ? this.resolve(input.path) : this.env.cwd;
             const result = [];
             const text = input.text;
             const regexStr = input.regex;
@@ -45,10 +51,10 @@ export const findTextTool = new CallbackTool({
             }
             const regex = regexStr ? new RegExp(regexStr) : null;
             for await (const file of fsp.glob(input.pattern, {
-                cwd: input.path,
+                cwd,
                 exclude: input.exclude || ["**/node_modules/**"],
             })) {
-                const fullPath = path.join(input.path, file);
+                const fullPath = path.join(cwd, file);
                 const stats = await fsp.stat(fullPath);
                 if (stats.isFile()) {
                     const content = await fsp.readFile(fullPath, "utf-8");
@@ -82,5 +88,5 @@ export const findTextTool = new CallbackTool({
         catch (error) {
             return error?.message;
         }
-    },
-});
+    }
+}

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

@@ -0,0 +1,21 @@
+import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import type { ToolEnv } from "../../../types/index.js";
+/**
+ * 根据文字描述生成图片。返回图片 URL，可通过 downloadFile 工具保存到本地。
+ *
+ * 依赖 AppConfig 中的 imageModels 和 defaultImageModel 配置。
+ * 如果未配置图片模型，工具会返回错误提示。
+ *
+ * 注意：与其它内置工具不同，generateImage 依赖图片模型配置，
+ * 因此由 discoverBuiltinTools 按 env.config.defaultImageModel 条件实例化，
+ * 不加入 BUILTIN_TOOL_CLASSES 静态注册表。
+ */
+export declare class GenerateImageTool extends SdkCallbackTool {
+    constructor(env: ToolEnv);
+    call(input: {
+        prompt: string;
+        model?: string;
+        size?: string;
+        quality?: string;
+    }): Promise<string>;
+}

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

@@ -0,0 +1,121 @@
+import { OpenAI, ZhipuImage } from "@ai-zen/agents-core";
+import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+/**
+ * 根据文字描述生成图片。返回图片 URL，可通过 downloadFile 工具保存到本地。
+ *
+ * 依赖 AppConfig 中的 imageModels 和 defaultImageModel 配置。
+ * 如果未配置图片模型，工具会返回错误提示。
+ *
+ * 注意：与其它内置工具不同，generateImage 依赖图片模型配置，
+ * 因此由 discoverBuiltinTools 按 env.config.defaultImageModel 条件实例化，
+ * 不加入 BUILTIN_TOOL_CLASSES 静态注册表。
+ */
+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,
+                },
+            },
+            env,
+        });
+    }
+    async call(input) {
+        try {
+            const prompt = input.prompt;
+            if (!prompt || !prompt.trim()) {
+                return JSON.stringify({ success: false, error: "prompt 不能为空" });
+            }
+            const config = this.env.config;
+            const imageModels = config.imageModels;
+            const defaultImageModel = config.defaultImageModel;
+            if (!imageModels || imageModels.length === 0) {
+                return JSON.stringify({
+                    success: false,
+                    error: "未配置图片生成模型。请在配置中添加 imageModels。",
+                });
+            }
+            const modelId = input.model || defaultImageModel;
+            const imageModel = modelId
+                ? imageModels.find((m) => m.id === modelId)
+                : imageModels[0];
+            if (!imageModel) {
+                return JSON.stringify({
+                    success: false,
+                    error: `图片模型 "${modelId}" 不存在。可用的图片模型: ${imageModels.map((m) => m.id).join(", ")}`,
+                });
+            }
+            const endpoint = config.endpoints.find((e) => e.id === imageModel.endpointId);
+            if (!endpoint) {
+                return JSON.stringify({
+                    success: false,
+                    error: `图片模型 "${imageModel.name}" 对应的端点 "${imageModel.endpointId}" 未配置`,
+                });
+            }
+            if (!endpoint.apiKey) {
+                return JSON.stringify({
+                    success: false,
+                    error: `端点 "${endpoint.name}" 的 API Key 未设置`,
+                });
+            }
+            const ep = new OpenAI({
+                openai_endpoint: endpoint.baseUrl,
+                api_key: endpoint.apiKey,
+            });
+            const modelName = input.model || imageModel.modelName;
+            const model = new ZhipuImage({
+                request_config: await ep.imageGeneration(modelName),
+            });
+            const result = await model.generate({
+                prompt: prompt.trim(),
+                model: modelName,
+                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}`,
+            }));
+            return JSON.stringify({
+                success: true,
+                model: imageModel.name,
+                modelId: imageModel.id,
+                created: result.created,
+                images,
+                content_filter: result.content_filter || [],
+                note: "图片临时链接有效期为30天，请及时转存图片。",
+            }, null, 2);
+        }
+        catch (error) {
+            return JSON.stringify({
+                success: false,
+                error: error instanceof Error ? error.message : "图片生成失败",
+            });
+        }
+    }
+}

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

@@ -0,0 +1,10 @@
+import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import type { ToolEnv } from "../../../types/index.js";
+export declare class GlobTool extends SdkCallbackTool {
+    constructor(env: ToolEnv);
+    call(input: {
+        path?: string;
+        pattern: string;
+        exclude?: string[];
+    }): Promise<string>;
+}

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

@@ -0,0 +1,51 @@
+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",
+                            },
+                        },
+                    },
+                    required: ["pattern"],
+                    additionalProperties: false,
+                },
+            },
+            env,
+        });
+    }
+    async call(input) {
+        try {
+            const cwd = input.path ? this.resolve(input.path) : this.env.cwd;
+            const result = [];
+            for await (const file of fsp.glob(input.pattern, {
+                exclude: input.exclude || ["**/node_modules/**"],
+                cwd,
+            })) {
+                result.push(file);
+            }
+            return JSON.stringify(result);
+        }
+        catch (error) {
+            return error?.message;
+        }
+    }
+}

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

@@ -0,0 +1,8 @@
+import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import type { ToolEnv } from "../../../types/index.js";
+export declare class LsTool extends SdkCallbackTool {
+    constructor(env: ToolEnv);
+    call(input: {
+        path: string;
+    }): Promise<string>;
+}

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

@@ -0,0 +1,33 @@
+import * as fsp from "fs/promises";
+import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+export class LsTool extends SdkCallbackTool {
+    constructor(env) {
+        super({
+            function: {
+                name: "ls",
+                description: "列出目录",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        path: {
+                            type: "string",
+                            description: "目录路径",
+                        },
+                    },
+                    required: ["path"],
+                    additionalProperties: false,
+                },
+            },
+            env,
+        });
+    }
+    async call(input) {
+        try {
+            const result = await fsp.readdir(this.resolve(input.path));
+            return JSON.stringify(result);
+        }
+        catch (error) {
+            return error?.message;
+        }
+    }
+}

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

@@ -0,0 +1,9 @@
+import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import type { ToolEnv } from "../../../types/index.js";
+export declare class MkdirTool extends SdkCallbackTool {
+    constructor(env: ToolEnv);
+    call(input: {
+        path: string;
+        recursive?: boolean;
+    }): Promise<string>;
+}

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

@@ -0,0 +1,39 @@
+import * as fsp from "fs/promises";
+import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+export class MkdirTool extends SdkCallbackTool {
+    constructor(env) {
+        super({
+            function: {
+                name: "mkdir",
+                description: "创建目录",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        path: {
+                            type: "string",
+                            description: "目录路径",
+                        },
+                        recursive: {
+                            type: "boolean",
+                            description: "是否递归创建子目录",
+                        },
+                    },
+                    required: ["path"],
+                    additionalProperties: false,
+                },
+            },
+            env,
+        });
+    }
+    async call(input) {
+        try {
+            await fsp.mkdir(this.resolve(input.path), {
+                recursive: input.recursive ?? false,
+            });
+            return "success";
+        }
+        catch (error) {
+            return error?.message;
+        }
+    }
+}

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

@@ -0,0 +1,8 @@
+import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import type { ToolEnv } from "../../../types/index.js";
+export declare class ReadFileTool extends SdkCallbackTool {
+    constructor(env: ToolEnv);
+    call(input: {
+        path: string;
+    }): Promise<string>;
+}