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

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/Capabilities.d.ts

@@ -67,5 +67,7 @@ export declare class Capabilities {
     /**
      * 重新执行全局发现（重新扫描文件系统）。
      */
-    refresh(): void;
+    refresh(options?: {
+        silent?: boolean;
+    }): void;
 }

package/dist/capabilities/Capabilities.js

@@ -138,12 +138,13 @@ export class Capabilities {
     /**
      * 重新执行全局发现（重新扫描文件系统）。
      */
-    refresh() {
+    refresh(options) {
+        const silent = options?.silent ?? false;
         const provider = this.provider;
         this.builtinInstances = discoverBuiltinTools(provider.config);
-        this.userInstances = discoverUserTools(provider.toolsPaths);
+        this.userInstances = discoverUserTools(provider.toolsPaths, { silent });
         this.subagentDefs = discoverSubAgents(provider.subAgentsPaths);
-        this.skills = discoverSkills(provider.skillsPaths);
+        this.skills = discoverSkills(provider.skillsPaths, { silent });
         this.mcps = discoverMcpServers(provider.mcpPaths);
     }
 }

package/dist/capabilities/discovery/skills.d.ts

@@ -30,13 +30,17 @@ export interface SkillInfo {
  * 按优先级从高到低传入路径列表，同名 skill 靠前的路径优先（先到先得）。
  * 解析 YAML frontmatter 中的 name 和 description，同时校验合规。
  */
-export declare function discoverSkills(paths: string[]): SkillInfo[];
+export declare function discoverSkills(paths: string[], options?: {
+    silent?: boolean;
+}): SkillInfo[];
 /**
  * 读取单个 Skill 的完整内容与元数据。
  * 按优先级从高到低传入路径列表，靠前的路径优先（先到先得）。
  * 返回 null 如果 skill 在所有目录中都不存在或 SKILL.md 不可读。
  */
-export declare function readSkill(skillDirs: string[], skillId: string): SkillInfo | null;
+export declare function readSkill(skillDirs: string[], skillId: string, options?: {
+    silent?: boolean;
+}): SkillInfo | null;
 /** @internal */
 export declare function parseFrontmatter(content: string): Frontmatter;
 /** @internal */

package/dist/capabilities/discovery/skills.js

@@ -8,7 +8,8 @@ const log = createLogger();
  * 按优先级从高到低传入路径列表，同名 skill 靠前的路径优先（先到先得）。
  * 解析 YAML frontmatter 中的 name 和 description，同时校验合规。
  */
-export function discoverSkills(paths) {
+export function discoverSkills(paths, options) {
+    const silent = options?.silent ?? false;
     const seen = new Set();
     const items = [];
     for (const dir of paths) {
@@ -29,7 +30,7 @@ export function discoverSkills(paths) {
             const skillMdPath = join(dir, entry.name, "SKILL.md");
             if (!existsSync(skillMdPath))
                 continue;
-            const skill = readSkillFromPath(entry.name, skillMdPath);
+            const skill = readSkillFromPath(entry.name, skillMdPath, silent);
             if (skill) {
                 seen.add(entry.name);
                 items.push(skill);
@@ -44,26 +45,29 @@ export function discoverSkills(paths) {
  * 按优先级从高到低传入路径列表，靠前的路径优先（先到先得）。
  * 返回 null 如果 skill 在所有目录中都不存在或 SKILL.md 不可读。
  */
-export function readSkill(skillDirs, skillId) {
+export function readSkill(skillDirs, skillId, options) {
+    const silent = options?.silent ?? false;
     for (const dir of skillDirs) {
         const candidate = join(dir, skillId, "SKILL.md");
         if (existsSync(candidate)) {
-            return readSkillFromPath(skillId, candidate);
+            return readSkillFromPath(skillId, candidate, silent);
         }
     }
     return null;
 }
 // ---- 内部 ----
-function readSkillFromPath(skillId, skillMdPath) {
+function readSkillFromPath(skillId, skillMdPath, silent) {
     try {
         const content = readFileSync(skillMdPath, "utf-8");
         const fm = parseFrontmatter(content);
         if (!fm.name)
             return null;
         // 规范合规校验
-        const errors = validateSkill(skillId, fm);
-        for (const err of errors) {
-            log.warn(`[skills] ${err.skillId}: ${err.field} — ${err.message}`);
+        if (!silent) {
+            const errors = validateSkill(skillId, fm);
+            for (const err of errors) {
+                log.warn(`[skills] ${err.skillId}: ${err.field} — ${err.message}`);
+            }
         }
         return {
             id: skillId,

package/dist/capabilities/discovery/usertools.d.ts

@@ -10,4 +10,6 @@ import { Tool } from "@ai-zen/agents-core";
  * 3. 支持直接导出 { function, exec } 格式的对象（自动适配为 Tool）
  * 4. 支持导出 CallbackTool 兼容的 { function, callback } 格式
  */
-export declare function discoverUserTools(paths: string[]): Tool[];
+export declare function discoverUserTools(paths: string[], options?: {
+    silent?: boolean;
+}): Tool[];

package/dist/capabilities/discovery/usertools.js

@@ -13,7 +13,8 @@ import { Tool, CallbackTool } from "@ai-zen/agents-core";
  * 3. 支持直接导出 { function, exec } 格式的对象（自动适配为 Tool）
  * 4. 支持导出 CallbackTool 兼容的 { function, callback } 格式
  */
-export function discoverUserTools(paths) {
+export function discoverUserTools(paths, options) {
+    const silent = options?.silent ?? false;
     const seen = new Set();
     const tools = [];
     for (const dir of paths) {
@@ -28,7 +29,7 @@ export function discoverUserTools(paths) {
                 if (!seen.has(name)) {
                     seen.add(name);
                     try {
-                        const tool = loadToolFile(join(dir, name + ".js"));
+                        const tool = loadToolFile(join(dir, name + ".js"), silent);
                         if (tool) {
                             tools.push(tool);
                         }
@@ -51,7 +52,7 @@ export function discoverUserTools(paths) {
  * 使用 vm.compileFunction 创建沙箱执行环境，避免污染全局作用域。
  * 注入有限的全局 API（console, setTimeout 等），不暴露 process/require。
  */
-function loadToolFile(filepath) {
+function loadToolFile(filepath, silent) {
     const code = readFileSync(filepath, "utf-8");
     // 构造沙箱上下文
     const sandbox = {
@@ -83,17 +84,19 @@ function loadToolFile(filepath) {
             return null;
         }
         // 适配不同导出格式
-        return normalizeToolExport(exported, filepath);
+        return normalizeToolExport(exported, filepath, silent);
     }
     catch (err) {
-        console.error(`[usertools] 加载工具文件失败: ${filepath} — ${err?.message ?? err}`);
+        if (!silent) {
+            console.error(`[usertools] 加载工具文件失败: ${filepath} — ${err?.message ?? err}`);
+        }
         return null;
     }
 }
 /**
  * 统一各种导出格式为 Tool 实例。
  */
-function normalizeToolExport(exported, filepath) {
+function normalizeToolExport(exported, filepath, silent) {
     // 情况 1：直接是 Tool 实例
     if (exported instanceof Tool) {
         return exported;
@@ -114,7 +117,9 @@ function normalizeToolExport(exported, filepath) {
             callback: target.callback,
         });
     }
-    console.error(`[usertools] 无法识别的工具格式: ${filepath}`);
+    if (!silent) {
+        console.error(`[usertools] 无法识别的工具格式: ${filepath}`);
+    }
     return null;
 }
 /**

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,
+                    message: `启动失败: ${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/capabilities/implements/skillTools.js

@@ -12,6 +12,11 @@ const EMPTY_HINT = "（当前没有可用的 Skill，请联系用户添加）";
 export function createLoadSkillTool(skillDirs, filteredSkills) {
     const ids = filteredSkills.map((s) => s.id);
     const param = createDisclosureParam(ids, "选择一个 Skill", EMPTY_HINT);
+    // 拼接各 skill 的描述供 LLM 参考
+    const skillDescriptions = filteredSkills
+        .map((s) => `  - ${s.id}: ${s.description || "无描述"}`)
+        .join("\n");
+    const skillIdDescription = `${param.description}\n\n各 Skill 说明：\n${skillDescriptions || "  无可用 Skill"}`;
     return new CallbackTool({
         function: {
             name: "load_skill",
@@ -21,7 +26,7 @@ export function createLoadSkillTool(skillDirs, filteredSkills) {
                 properties: {
                     skill_id: {
                         type: "string",
-                        description: param.description,
+                        description: skillIdDescription,
                         ...(param.enum ? { enum: param.enum } : {}),
                     },
                 },
@@ -57,6 +62,11 @@ export function createCallSkillSubAgentTool(skillDirs, filteredSkills, caps) {
     const subAgentSkills = filteredSkills.filter((s) => s.subAgent);
     const ids = subAgentSkills.map((s) => s.id);
     const param = createDisclosureParam(ids, "选择一个 Skill（支持子 Agent）", EMPTY_HINT);
+    // 拼接各 skill 的描述供 LLM 参考
+    const skillDescriptions = subAgentSkills
+        .map((s) => `  - ${s.id}: ${s.description || "无描述"}`)
+        .join("\n");
+    const skillIdDescription = `${param.description}\n\n各 Skill 说明：\n${skillDescriptions || "  无可用 Skill"}`;
     return new CallbackTool({
         function: {
             name: "call_skill_sub_agent",
@@ -66,7 +76,7 @@ export function createCallSkillSubAgentTool(skillDirs, filteredSkills, caps) {
                 properties: {
                     skill_id: {
                         type: "string",
-                        description: param.description,
+                        description: skillIdDescription,
                         ...(param.enum ? { enum: param.enum } : {}),
                     },
                     task: {

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/dist/plugin/AutoRefreshToolsPlugin.js

@@ -11,7 +11,7 @@ export class AutoRefreshToolsPlugin {
         const { agent } = ctx;
         if (!agent.caps)
             return;
-        agent.caps.refresh();
+        agent.caps.refresh({ silent: true });
         agent.tools = agent.caps.buildTools(agent.permissions ?? {}, {
             exclude: {
                 subagents: agent.definition.function?.name

package/package.json

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