@ai-zen/agents-sdk 0.2.0-alpha.2 → 0.2.0-alpha.3

package/README.md

@@ -77,7 +77,35 @@ await agent.send("你好");
 | `runtime` | ✅ 已实现 — Provider、Capabilities、createAgent、MCP 连接管理、任务迁移 |
 | `plugin` | ✅ 已实现 — AutoMigratePlugin / AutoDraftPlugin / AutoRefreshToolsPlugin |
 | `shared` | ✅ 已实现 — SdkError + 可注入 Logger |
-| 测试 | ✅ 378 个测试，46 个文件，全通过（含真实 API 聊天 e2e） |
+| 测试 | ✅ 359 个测试，45 个文件，全通过（含真实 API 聊天 e2e） |
+
+## 内置工具
+
+| 工具 | 说明 |
+|------|------|
+| `cwd` | 获取当前工作目录 |
+| `readFile` | 读取文件 |
+| `writeFile` | 写入文件 |
+| `exec` | 执行命令（支持 `timeout` 超时参数） |
+| `exec_async` | 异步执行命令，启动后立即返回，不等待结果 |
+| `mkdir` | 创建目录 |
+| `rm` | 删除文件或目录 |
+| `glob` | 使用 glob 模式扫描查找文件 |
+| `ls` | 列出目录内容 |
+| `exist` | 检查文件或目录是否存在 |
+| `findText` | 在文件中搜索文本或正则 |
+| `downloadFile` | 从 URL 下载文件并保存到本地 |
+| `rename` | 重命名或移动文件/目录 |
+| `copy` | 复制文件或目录 |
+| `batchEdit` | 批量编辑文件文本 |
+| `edit` | 编辑文件中的文本 |
+| `sleep` | 等待指定毫秒数后继续 |
+
+条件注入（需配置 `imageModels`）：
+
+| 工具 | 说明 |
+|------|------|
+| `generateImage` | 根据文字描述生成图片 |
 
 ## 内置插件
 

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

@@ -11,18 +11,25 @@ export const execTool = new CallbackTool({
                     type: "string",
                     description: "要执行的命令",
                 },
+                timeout: {
+                    type: "number",
+                    description: "超时时间（毫秒），超时后会终止进程。默认无超时。建议长时间运行的命令使用 exec_async 异步执行。",
+                },
             },
             required: ["command"],
             additionalProperties: false,
         },
     },
     async callback(input) {
+        const command = input.command;
+        const timeout = input.timeout;
         const result = await new Promise((resolve) => {
-            exec(input.command, (error, stdout, stderr) => {
+            const child = exec(command, { timeout: timeout && timeout > 0 ? timeout : undefined }, (error, stdout, stderr) => {
                 resolve({
                     stdout,
                     stderr,
                     exitCode: error?.code ?? (error ? 1 : null),
+                    killed: error?.killed ?? false,
                 });
             });
         });

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

@@ -0,0 +1,2 @@
+import { CallbackTool } from "@ai-zen/agents-core";
+export declare const execAsyncTool: CallbackTool;

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

@@ -0,0 +1,148 @@
+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 程序。",
+                },
+            },
+            required: ["command"],
+            additionalProperties: false,
+        },
+    },
+    async callback(input) {
+        const command = input.command;
+        const cwd = input.cwd ?? undefined;
+        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,
+                    stdio: "ignore",
+                    shell: true,
+                    windowsHide: true,
+                });
+            }
+            else {
+                // Unix: 解析命令和参数，直接 spawn
+                const args = [];
+                let current = "";
+                let inQuote = null;
+                for (const ch of command) {
+                    if (inQuote) {
+                        if (ch === "\\") {
+                            current += command[command.indexOf(ch) + 1] ?? "";
+                            continue;
+                        }
+                        if (ch === inQuote) {
+                            inQuote = null;
+                            if (current)
+                                args.push(current);
+                            current = "";
+                            continue;
+                        }
+                        current += ch;
+                    }
+                    else {
+                        if (ch === '"' || ch === "'") {
+                            inQuote = ch;
+                        }
+                        else if (ch === " ") {
+                            if (current) {
+                                args.push(current);
+                                current = "";
+                            }
+                        }
+                        else {
+                            current += ch;
+                        }
+                    }
+                }
+                if (current)
+                    args.push(current);
+                child = spawn(args[0], args.slice(1), {
+                    cwd,
+                    detached,
+                    stdio: "ignore",
+                });
+            }
+            // 记录是否已 resolve
+            let resolved = false;
+            child.on("error", (err) => {
+                if (resolved)
+                    return;
+                resolved = true;
+                resolve(JSON.stringify({
+                    success: false,
+                    pid: null,
+                    error: `启动失败: ${err.message}`,
+                }));
+            });
+            child.on("spawn", () => {
+                if (resolved)
+                    return;
+                resolved = true;
+                resolve(JSON.stringify({
+                    success: true,
+                    pid: child.pid ?? null,
+                    message: `进程已启动 (PID: ${child.pid ?? "unknown"})`,
+                }));
+            });
+            // 如果进程很快退出（如命令不存在被 shell 拒绝），捕获退出码
+            child.on("exit", (code) => {
+                if (resolved)
+                    return;
+                resolved = true;
+                resolve(JSON.stringify({
+                    success: code === 0,
+                    pid: child.pid ?? null,
+                    exitCode: code,
+                    message: code === null
+                        ? `进程已退出 (PID: ${child.pid ?? "unknown"})`
+                        : `进程已退出 (PID: ${child.pid ?? "unknown"}, 退出码: ${code})`,
+                }));
+            });
+            // 给子进程一点时间来触发 spawn/error/exit 事件
+            // 若 500ms 后仍未触发，认为启动成功
+            const timeout = setTimeout(() => {
+                if (resolved)
+                    return;
+                resolved = true;
+                resolve(JSON.stringify({
+                    success: true,
+                    pid: child.pid ?? null,
+                    message: `进程已启动 (PID: ${child.pid ?? "unknown"})`,
+                }));
+            }, 500);
+            // 超时后清理
+            const cleanup = () => {
+                clearTimeout(timeout);
+                child.removeAllListeners();
+            };
+            child.on("spawn", cleanup);
+            child.on("error", cleanup);
+            child.on("exit", cleanup);
+            // 允许子进程独立运行（不阻止父进程退出）
+            child.unref();
+        });
+    },
+});

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

@@ -14,6 +14,8 @@ import { renameTool } from "./rename.js";
 import { copyTool } from "./copy.js";
 import { batchEditTool } from "./batchEdit.js";
 import { editTool } from "./edit.js";
-/** 15 个内置工具实例，注册与实现一体。 */
+import { execAsyncTool } from "./execAsync.js";
+import { sleepTool } from "./sleep.js";
+/** 17 个内置工具实例，注册与实现一体。 */
 export declare const BUILTIN_TOOLS: Tool[];
-export { cwdTool, readFileTool, writeFileTool, execTool, mkdirTool, rmTool, globTool, lsTool, existTool, findTextTool, downloadFileTool, renameTool, copyTool, batchEditTool, editTool };
+export { cwdTool, readFileTool, writeFileTool, execTool, mkdirTool, rmTool, globTool, lsTool, existTool, findTextTool, downloadFileTool, renameTool, copyTool, batchEditTool, editTool, execAsyncTool, sleepTool };

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

@@ -13,7 +13,9 @@ import { renameTool } from "./rename.js";
 import { copyTool } from "./copy.js";
 import { batchEditTool } from "./batchEdit.js";
 import { editTool } from "./edit.js";
-/** 15 个内置工具实例，注册与实现一体。 */
+import { execAsyncTool } from "./execAsync.js";
+import { sleepTool } from "./sleep.js";
+/** 17 个内置工具实例，注册与实现一体。 */
 export const BUILTIN_TOOLS = [
     cwdTool,
     readFileTool,
@@ -30,5 +32,7 @@ export const BUILTIN_TOOLS = [
     copyTool,
     batchEditTool,
     editTool,
+    execAsyncTool,
+    sleepTool,
 ];
-export { cwdTool, readFileTool, writeFileTool, execTool, mkdirTool, rmTool, globTool, lsTool, existTool, findTextTool, downloadFileTool, renameTool, copyTool, batchEditTool, editTool };
+export { cwdTool, readFileTool, writeFileTool, execTool, mkdirTool, rmTool, globTool, lsTool, existTool, findTextTool, downloadFileTool, renameTool, copyTool, batchEditTool, editTool, execAsyncTool, sleepTool };

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

@@ -0,0 +1,2 @@
+import { CallbackTool } from "@ai-zen/agents-core";
+export declare const sleepTool: CallbackTool;

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

@@ -0,0 +1,41 @@
+import { CallbackTool } from "@ai-zen/agents-core";
+export const sleepTool = new CallbackTool({
+    function: {
+        name: "sleep",
+        description: "等待指定的时间（毫秒）。用于需要延迟执行的场景，例如等待其他操作完成、操作间隔控制等。注意：过长的等待时间会影响响应速度，建议不超过 30000 毫秒（30 秒）。",
+        parameters: {
+            type: "object",
+            properties: {
+                ms: {
+                    type: "number",
+                    description: "等待的毫秒数（1 秒 = 1000 毫秒）。建议不超过 30000（30 秒）。",
+                },
+            },
+            required: ["ms"],
+            additionalProperties: false,
+        },
+    },
+    async callback(input) {
+        const ms = input.ms;
+        if (typeof ms !== "number" || !Number.isFinite(ms) || ms < 0) {
+            return JSON.stringify({
+                success: false,
+                error: "ms 必须是正整数",
+            });
+        }
+        if (ms > 300_000) {
+            // 超过 5 分钟给出警告
+            return JSON.stringify({
+                success: false,
+                error: `等待时间 ${ms}ms 过长，建议不超过 300000ms（5 分钟）。如需长时间等待请分段执行。`,
+            });
+        }
+        await new Promise((resolve) => setTimeout(resolve, ms));
+        return JSON.stringify({
+            success: true,
+            waitedMs: ms,
+            waitedSeconds: (ms / 1000).toFixed(1),
+            message: `已等待 ${ms}ms（${(ms / 1000).toFixed(1)} 秒）`,
+        });
+    },
+});

package/dist/index.d.ts

@@ -32,6 +32,8 @@ export type { AutoDraftOptions } from "./plugin/AutoDraftPlugin.js";
 export { AutoRefreshToolsPlugin } from "./plugin/AutoRefreshToolsPlugin.js";
 export { BUILTIN_TOOLS } from "./capabilities/implements/builtin/index.js";
 export { createGenerateImageTool } from "./capabilities/implements/builtin/generateImage.js";
+export { execAsyncTool } from "./capabilities/implements/builtin/execAsync.js";
+export { sleepTool } from "./capabilities/implements/builtin/sleep.js";
 export { createLoadSkillTool, createCallSkillSubAgentTool } from "./capabilities/implements/skillTools.js";
 export { createLoadMcpTool, createCallMcpTool, createReadMcpResourceTool } from "./capabilities/implements/mcpTools.js";
 export { createSubAgentTool } from "./capabilities/implements/subAgentTools.js";

package/dist/index.js

@@ -29,6 +29,8 @@ export { AutoRefreshToolsPlugin } from "./plugin/AutoRefreshToolsPlugin.js";
 // 工具
 export { BUILTIN_TOOLS } from "./capabilities/implements/builtin/index.js";
 export { createGenerateImageTool } from "./capabilities/implements/builtin/generateImage.js";
+export { execAsyncTool } from "./capabilities/implements/builtin/execAsync.js";
+export { sleepTool } from "./capabilities/implements/builtin/sleep.js";
 export { createLoadSkillTool, createCallSkillSubAgentTool } from "./capabilities/implements/skillTools.js";
 export { createLoadMcpTool, createCallMcpTool, createReadMcpResourceTool } from "./capabilities/implements/mcpTools.js";
 export { createSubAgentTool } from "./capabilities/implements/subAgentTools.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-zen/agents-sdk",
-  "version": "0.2.0-alpha.2",
+  "version": "0.2.0-alpha.3",
   "description": "AI-Zen Agents SDK — shared business logic for CLI and Desktop",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",