@ai-zen/agents-sdk 0.5.3 → 0.5.4

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## [0.5.4] - 2026-08-05
+
+### 🚀 新功能
+
+- **`ExecAsyncTool`（exec_async）统一走 shell 解析** — 移除 Unix 平台手动分词逻辑，所有平台均经 `spawn(command, [], { shell: true })` 执行。工具描述明确告知 agent：其本身不捕获输出，如需留存/查看输出可在命令中使用 shell 重定向写入文件（`>` / `>>`），并支持管道（`|`）等 shell 语法
+
+### 🎯 优化
+
+- **`ExecTool`（exec）的 `timeout` 改为必填** — schema `required` 由 `["command"]` 扩为 `["command", "timeout"]`，`call()` 类型签名 `timeout: number`（必填），并在运行时双校验（缺失/非正数/非有限数即抛错）。`timeout` 必填后，命令始终受超时保护，避免无超时长跑
+- **超时原因明确告知 agent** — `exec` 超时被终止（`error.killed` 为 true）时返回结构新增 `terminated: "timeout"` 字段。弥补 Node 不会自动在 stderr 写入超时提示的限制，使 agent 能明确判断命令因超时被终止，从而灵活应对
+
 ## [0.5.3] - 2026-08-05
 
 ### 🚀 新功能

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

@@ -5,7 +5,7 @@ export class ExecAsyncTool extends SdkCallbackTool {
         super({
             function: {
                 name: "exec_async",
-                description: "异步执行命令，启动程序后立即返回，不等待执行结果。适用于启动长期运行的进程（如服务器、监听程序、GUI应用等）或不需要等待结果的命令。注意：该工具不会捕获命令的输出，如果需要获取输出请使用 exec。",
+                description: "异步执行命令，启动程序后立即返回，不等待执行结果。适用于启动长期运行的进程（如服务器、监听程序、GUI应用等）或不需要等待结果的命令。注意：该工具本身不捕获命令的输出；若需获取/留存输出，可在命令中使用 shell 重定向写入文件（如 `> /path/file`，支持 `>>` 追加、`|` 管道）。命令经 shell 解析执行。",
                 parameters: {
                     type: "object",
                     properties: {
@@ -33,62 +33,15 @@ export class ExecAsyncTool extends SdkCallbackTool {
         const command = input.command;
         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";
+        // 统一走 shell：允许 shell 语法（重定向 > / >>、管道 | 等）
         return new Promise((resolve) => {
-            let child;
-            if (useShell) {
-                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",
-                });
-            }
+            const child = spawn(command, [], {
+                cwd,
+                detached,
+                stdio: "ignore",
+                shell: true,
+                windowsHide: true,
+            });
             let resolved = false;
             child.on("error", (err) => {
                 if (resolved)

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

@@ -4,6 +4,6 @@ export declare class ExecTool extends SdkCallbackTool {
     constructor(env: ToolEnv);
     call(input: {
         command: string;
-        timeout?: number;
+        timeout: number;
     }): Promise<string>;
 }

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

@@ -15,10 +15,10 @@ export class ExecTool extends SdkCallbackTool {
                         },
                         timeout: {
                             type: "number",
-                            description: "超时时间（毫秒），超时后会终止进程。默认无超时。建议长时间运行的命令使用 exec_async 异步执行。",
+                            description: "超时时间（毫秒），必填。超时后会终止进程；超过该时长仍未完成即视为超时并终止。建议长时间运行的命令使用 exec_async 异步执行。",
                         },
                     },
-                    required: ["command"],
+                    required: ["command", "timeout"],
                     additionalProperties: false,
                 },
             },
@@ -27,17 +27,24 @@ export class ExecTool extends SdkCallbackTool {
     }
     async call(input) {
         const command = input.command;
-        const timeout = input.timeout;
+        const { timeout } = input;
+        // 运行时双校验：timeout 必填且必须为正数
+        if (typeof timeout !== "number" || !Number.isFinite(timeout) || timeout <= 0) {
+            throw new Error(`exec: 参数 timeout 为必填项，且必须是正数（毫秒），当前值: ${JSON.stringify(timeout)}`);
+        }
         const result = await new Promise((resolve) => {
             const child = exec(command, {
                 cwd: this.env.cwd,
-                timeout: timeout && timeout > 0 ? timeout : undefined,
+                timeout,
             }, (error, stdout, stderr) => {
+                const killed = error?.killed ?? false;
                 resolve({
                     stdout,
                     stderr,
                     exitCode: error?.code ?? (error ? 1 : null),
-                    killed: error?.killed ?? false,
+                    killed,
+                    // 明确告知 agent 命令是因超时被终止（Node 不会自动在 stderr 写入该提示）
+                    terminated: killed ? "timeout" : undefined,
                 });
             });
         });

package/package.json

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