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

package/dist/capabilities/discovery/skills.js

@@ -0,0 +1,175 @@
+import { readdirSync, existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { createLogger } from "../../shared/logger.js";
+const log = createLogger();
+// ---- 发现（返回完整 SkillInfo，不再丢失 subAgent 等信息）----
+/**
+ * 扫描多个目录中发现的所有 Skill（含 SKILL.md 的子目录）。
+ * 按优先级从高到低传入路径列表，同名 skill 靠前的路径优先（先到先得）。
+ * 解析 YAML frontmatter 中的 name 和 description，同时校验合规。
+ */
+export function discoverSkills(paths) {
+    const seen = new Set();
+    const items = [];
+    for (const dir of paths) {
+        if (!existsSync(dir))
+            continue;
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            if (seen.has(entry.name))
+                continue;
+            const skillMdPath = join(dir, entry.name, "SKILL.md");
+            if (!existsSync(skillMdPath))
+                continue;
+            const skill = readSkillFromPath(entry.name, skillMdPath);
+            if (skill) {
+                seen.add(entry.name);
+                items.push(skill);
+            }
+        }
+    }
+    return items;
+}
+// ---- 完整读取（用于加载 Skill 正文和子 Agent 判断）----
+/**
+ * 读取单个 Skill 的完整内容与元数据。
+ * 按优先级从高到低传入路径列表，靠前的路径优先（先到先得）。
+ * 返回 null 如果 skill 在所有目录中都不存在或 SKILL.md 不可读。
+ */
+export function readSkill(skillDirs, skillId) {
+    for (const dir of skillDirs) {
+        const candidate = join(dir, skillId, "SKILL.md");
+        if (existsSync(candidate)) {
+            return readSkillFromPath(skillId, candidate);
+        }
+    }
+    return null;
+}
+// ---- 内部 ----
+function readSkillFromPath(skillId, skillMdPath) {
+    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}`);
+        }
+        return {
+            id: skillId,
+            name: fm.name,
+            description: fm.description ?? "",
+            subAgent: fm.subAgent ?? false,
+            content,
+            license: fm.license,
+            compatibility: fm.compatibility,
+            metadata: fm.metadata,
+            allowedTools: fm.allowedTools,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+// ---- 解析 ----
+/** @internal */
+export function parseFrontmatter(content) {
+    const match = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!match)
+        return {};
+    const result = {};
+    const lines = match[1].split("\n");
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        const metaHeader = line.match(/^metadata:\s*$/);
+        if (metaHeader) {
+            const metadata = {};
+            i++;
+            while (i < lines.length) {
+                const subMatch = lines[i].match(/^  (\S+):\s*(.*)/);
+                if (!subMatch)
+                    break;
+                metadata[subMatch[1]] = stripQuotes(subMatch[2].trim());
+                i++;
+            }
+            if (Object.keys(metadata).length > 0) {
+                result.metadata = metadata;
+            }
+            continue;
+        }
+        const kv = line.match(/^(\S+):\s*(.*)/);
+        if (kv) {
+            const key = kv[1];
+            const val = kv[2].trim();
+            switch (key) {
+                case "name":
+                    result.name = val;
+                    break;
+                case "description":
+                    result.description = val;
+                    break;
+                case "sub-agent":
+                    result.subAgent = val === "true";
+                    break;
+                case "license":
+                    result.license = val;
+                    break;
+                case "compatibility":
+                    result.compatibility = val;
+                    break;
+                case "allowed-tools":
+                    result.allowedTools = val ? val.split(/\s+/).filter(Boolean) : [];
+                    break;
+            }
+        }
+        i++;
+    }
+    return result;
+}
+function stripQuotes(s) {
+    if ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'"))) {
+        return s.slice(1, -1);
+    }
+    return s;
+}
+// ---- 校验 ----
+const VALID_NAME_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+/** @internal */
+export function validateSkill(skillId, fm) {
+    const errors = [];
+    if (!fm.name || fm.name.length === 0) {
+        errors.push({ skillId, field: "name", message: "必须存在且非空" });
+    }
+    else {
+        if (fm.name.length > 64) {
+            errors.push({ skillId, field: "name", message: `超过 64 字符（当前 ${fm.name.length}）` });
+        }
+        if (!VALID_NAME_RE.test(fm.name)) {
+            errors.push({ skillId, field: "name", message: `"${fm.name}" 不符合规范：仅允许小写字母、数字、连字符，且不能首尾或连续连字符` });
+        }
+        if (fm.name !== skillId) {
+            errors.push({ skillId, field: "name", message: `"${fm.name}" 与目录名 "${skillId}" 不一致` });
+        }
+    }
+    if (!fm.description || fm.description.length === 0) {
+        errors.push({ skillId, field: "description", message: "必须存在且非空" });
+    }
+    else if (fm.description.length > 1024) {
+        errors.push({ skillId, field: "description", message: `超过 1024 字符（当前 ${fm.description.length}）` });
+    }
+    if (fm.compatibility && fm.compatibility.length > 500) {
+        errors.push({ skillId, field: "compatibility", message: `超过 500 字符（当前 ${fm.compatibility.length}）` });
+    }
+    return errors;
+}

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

@@ -0,0 +1,7 @@
+import type { AgentDefinition } from "../../types/index.js";
+/**
+ * 扫描多个目录中发现的所有 SubAgent 完整定义。
+ * 按优先级从高到低传入路径列表，同名 function.name 靠前的路径优先（先到先得）。
+ * 跳过无 function 的普通 Agent 和解析失败的文件。
+ */
+export declare function discoverSubAgents(paths: string[]): AgentDefinition[];

package/dist/capabilities/discovery/subagents.js

@@ -0,0 +1,39 @@
+import { readdirSync, existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * 扫描多个目录中发现的所有 SubAgent 完整定义。
+ * 按优先级从高到低传入路径列表，同名 function.name 靠前的路径优先（先到先得）。
+ * 跳过无 function 的普通 Agent 和解析失败的文件。
+ */
+export function discoverSubAgents(paths) {
+    const seen = new Set();
+    const agents = [];
+    for (const dir of paths) {
+        if (!existsSync(dir))
+            continue;
+        let files;
+        try {
+            files = readdirSync(dir).filter((f) => f.endsWith(".json"));
+        }
+        catch {
+            continue;
+        }
+        for (const file of files) {
+            try {
+                const raw = readFileSync(join(dir, file), "utf-8");
+                const def = JSON.parse(raw);
+                if (def.function) {
+                    const funcName = def.function.name;
+                    if (!seen.has(funcName)) {
+                        seen.add(funcName);
+                        agents.push(def);
+                    }
+                }
+            }
+            catch {
+                // 跳过解析失败的文件
+            }
+        }
+    }
+    return agents;
+}

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

@@ -0,0 +1,13 @@
+import { Tool } from "@ai-zen/agents-core";
+/**
+ * 扫描多个 tools/ 目录，发现所有 .js 文件，动态加载为 Tool 实例。
+ * 按优先级从高到低传入路径列表，同名工具靠前的路径优先（先到先得）。
+ * 按文件名排序以保证确定性。
+ *
+ * 加载方式：
+ * 1. 使用 vm.compileFunction 创建安全的执行上下文
+ * 2. 工具文件应通过 module.exports 或 exports.default 导出 Tool 实例
+ * 3. 支持直接导出 { function, exec } 格式的对象（自动适配为 Tool）
+ * 4. 支持导出 CallbackTool 兼容的 { function, callback } 格式
+ */
+export declare function discoverUserTools(paths: string[]): Tool[];

package/dist/capabilities/discovery/usertools.js

@@ -0,0 +1,136 @@
+import { readdirSync, existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import vm from "node:vm";
+import { Tool, CallbackTool } from "@ai-zen/agents-core";
+/**
+ * 扫描多个 tools/ 目录，发现所有 .js 文件，动态加载为 Tool 实例。
+ * 按优先级从高到低传入路径列表，同名工具靠前的路径优先（先到先得）。
+ * 按文件名排序以保证确定性。
+ *
+ * 加载方式：
+ * 1. 使用 vm.compileFunction 创建安全的执行上下文
+ * 2. 工具文件应通过 module.exports 或 exports.default 导出 Tool 实例
+ * 3. 支持直接导出 { function, exec } 格式的对象（自动适配为 Tool）
+ * 4. 支持导出 CallbackTool 兼容的 { function, callback } 格式
+ */
+export function discoverUserTools(paths) {
+    const seen = new Set();
+    const tools = [];
+    for (const dir of paths) {
+        if (!existsSync(dir))
+            continue;
+        try {
+            const files = readdirSync(dir)
+                .filter((f) => f.endsWith(".js"))
+                .map((f) => f.slice(0, -3))
+                .sort();
+            for (const name of files) {
+                if (!seen.has(name)) {
+                    seen.add(name);
+                    try {
+                        const tool = loadToolFile(join(dir, name + ".js"));
+                        if (tool) {
+                            tools.push(tool);
+                        }
+                    }
+                    catch {
+                        // 跳过加载失败的文件
+                    }
+                }
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    return tools;
+}
+/**
+ * 从 .js 文件加载 Tool 实例。
+ *
+ * 使用 vm.compileFunction 创建沙箱执行环境，避免污染全局作用域。
+ * 注入有限的全局 API（console, setTimeout 等），不暴露 process/require。
+ */
+function loadToolFile(filepath) {
+    const code = readFileSync(filepath, "utf-8");
+    // 构造沙箱上下文
+    const sandbox = {
+        // 有限全局 API
+        console: console,
+        setTimeout: setTimeout,
+        clearTimeout: clearTimeout,
+        setInterval: setInterval,
+        clearInterval: clearInterval,
+        Buffer: Buffer,
+        URL: URL,
+        URLSearchParams: URLSearchParams,
+        TextEncoder: TextEncoder,
+        TextDecoder: TextDecoder,
+        // 导出的结果存放处
+        module: { exports: {} },
+        exports: {},
+    };
+    sandbox.global = sandbox;
+    sandbox.globalThis = sandbox;
+    const context = vm.createContext(sandbox);
+    const script = new vm.Script(code, { filename: filepath });
+    try {
+        script.runInContext(context, { timeout: 5000 });
+        // 获取导出结果
+        const exported = sandbox.module.exports ?? sandbox.exports;
+        // 空导出
+        if (!exported || (typeof exported === "object" && Object.keys(exported).length === 0)) {
+            return null;
+        }
+        // 适配不同导出格式
+        return normalizeToolExport(exported, filepath);
+    }
+    catch (err) {
+        console.error(`[usertools] 加载工具文件失败: ${filepath} — ${err?.message ?? err}`);
+        return null;
+    }
+}
+/**
+ * 统一各种导出格式为 Tool 实例。
+ */
+function normalizeToolExport(exported, filepath) {
+    // 情况 1：直接是 Tool 实例
+    if (exported instanceof Tool) {
+        return exported;
+    }
+    // 情况 2：默认导出（exported.default）
+    const target = exported.default ?? exported;
+    if (target instanceof Tool) {
+        return target;
+    }
+    // 情况 3：{ function, exec } 格式 → 适配为 Tool 子类
+    if (target && typeof target === "object" && target.function && typeof target.exec === "function") {
+        return createToolFromObject(target, filepath);
+    }
+    // 情况 4：{ function, callback } 格式 → 适配为 CallbackTool
+    if (target && typeof target === "object" && target.function && typeof target.callback === "function") {
+        return new CallbackTool({
+            function: target.function,
+            callback: target.callback,
+        });
+    }
+    console.error(`[usertools] 无法识别的工具格式: ${filepath}`);
+    return null;
+}
+/**
+ * 将 { function, exec } 对象适配为 Tool 子类实例。
+ */
+function createToolFromObject(obj, filepath) {
+    return new (class extends Tool {
+        constructor() {
+            super({ function: obj.function });
+        }
+        async exec(ctx) {
+            const result = await obj.exec.call(ctx, ctx.parsed_args);
+            if (typeof result !== "string") {
+                return JSON.stringify(result) ?? "";
+            }
+            return result;
+        }
+    })();
+}

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

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

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

@@ -0,0 +1,76 @@
+import { CallbackTool } from "@ai-zen/agents-core";
+import * as fsp from "fs/promises";
+export const batchEditTool = new CallbackTool({
+    function: {
+        name: "batchEdit",
+        description: "批量编辑文件文本，可以优先使用这个工具对文件进行编辑",
+        parameters: {
+            type: "object",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "文件路径",
+                },
+                replacements: {
+                    type: "array",
+                    description: "要替换的文本数组",
+                    items: {
+                        type: "object",
+                        properties: {
+                            oldText: {
+                                type: "string",
+                                description: "要替换的文本",
+                            },
+                            newText: {
+                                type: "string",
+                                description: "替换后的文本",
+                            },
+                            isReplaceAll: {
+                                type: "boolean",
+                                description: "是否替换所有匹配的文本（默认仅替换首次匹配）。使用此功能前应确保你提供的 oldText 足够精确，避免误替换",
+                                default: false,
+                            },
+                        },
+                        required: ["oldText", "newText"],
+                        additionalProperties: false,
+                    },
+                },
+            },
+            required: ["path", "replacements"],
+            additionalProperties: false,
+        },
+    },
+    async callback(input) {
+        try {
+            const content = await fsp.readFile(input.path, "utf-8");
+            let newContent = content;
+            const results = [];
+            for (const replacement of input.replacements) {
+                if (!newContent.includes(replacement.oldText)) {
+                    results.push({
+                        oldText: replacement.oldText,
+                        newText: replacement.newText,
+                        result: "文件中未精确匹配到要替换的文本",
+                    });
+                    continue;
+                }
+                if (replacement.isReplaceAll) {
+                    newContent = newContent.replaceAll(replacement.oldText, replacement.newText);
+                }
+                else {
+                    newContent = newContent.replace(replacement.oldText, replacement.newText);
+                }
+                results.push({
+                    oldText: replacement.oldText,
+                    newText: replacement.newText,
+                    result: "success",
+                });
+            }
+            await fsp.writeFile(input.path, newContent);
+            return JSON.stringify(results);
+        }
+        catch (error) {
+            return error?.message;
+        }
+    },
+});

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

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

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

@@ -0,0 +1,38 @@
+import { CallbackTool } from "@ai-zen/agents-core";
+import * as fsp from "fs/promises";
+export const copyTool = new CallbackTool({
+    function: {
+        name: "copy",
+        description: "复制文件或目录（相当于 cp 命令）",
+        parameters: {
+            type: "object",
+            properties: {
+                src: {
+                    type: "string",
+                    description: "源路径",
+                },
+                dest: {
+                    type: "string",
+                    description: "目标路径",
+                },
+                recursive: {
+                    type: "boolean",
+                    description: "是否递归复制目录，复制目录时需设为 true",
+                },
+            },
+            required: ["src", "dest"],
+            additionalProperties: false,
+        },
+    },
+    async callback(input) {
+        try {
+            await fsp.cp(input.src, input.dest, {
+                recursive: input.recursive ?? false,
+            });
+            return "success";
+        }
+        catch (error) {
+            return error?.message;
+        }
+    },
+});

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

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

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

@@ -0,0 +1,15 @@
+import { CallbackTool } from "@ai-zen/agents-core";
+export const cwdTool = new CallbackTool({
+    function: {
+        name: "cwd",
+        description: "获取当前工作目录 cwd",
+        parameters: {
+            type: "object",
+            properties: {},
+            required: [],
+        },
+    },
+    async callback() {
+        return process.cwd();
+    },
+});

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

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

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

@@ -0,0 +1,70 @@
+import { CallbackTool } from "@ai-zen/agents-core";
+import * as fsp from "fs/promises";
+import * as path from "path";
+export const downloadFileTool = new CallbackTool({
+    function: {
+        name: "downloadFile",
+        description: "从 URL 下载文件（图片、PDF 等二进制文件）并保存到本地磁盘。自动从 URL 推断文件名，也可指定保存路径。",
+        parameters: {
+            type: "object",
+            properties: {
+                url: {
+                    type: "string",
+                    description: "文件下载链接",
+                },
+                outputPath: {
+                    type: "string",
+                    description: "保存路径（可选）。可以是目录或完整文件路径。不指定则下载到当前工作目录，自动从 URL 推断文件名。",
+                },
+            },
+            required: ["url"],
+            additionalProperties: false,
+        },
+    },
+    async callback(input) {
+        try {
+            const url = input.url;
+            if (!url)
+                throw new Error("url 不能为空");
+            let savePath;
+            if (input.outputPath) {
+                savePath = input.outputPath;
+                const stat = await fsp.stat(savePath).catch(() => null);
+                if (stat?.isDirectory()) {
+                    const urlPath = new URL(url).pathname;
+                    const fileName = path.basename(urlPath) || `download_${Date.now()}`;
+                    savePath = path.join(savePath, fileName);
+                }
+            }
+            else {
+                const urlPath = new URL(url).pathname;
+                const fileName = path.basename(urlPath) || `download_${Date.now()}`;
+                savePath = path.join(process.cwd(), fileName);
+            }
+            await fsp.mkdir(path.dirname(savePath), { recursive: true });
+            const response = await fetch(url);
+            if (!response.ok) {
+                throw new Error(`下载失败: HTTP ${response.status} ${response.statusText}`);
+            }
+            const contentType = response.headers.get("content-type") || "";
+            const arrayBuffer = await response.arrayBuffer();
+            const buffer = Buffer.from(arrayBuffer);
+            await fsp.writeFile(savePath, buffer);
+            const stats = await fsp.stat(savePath);
+            const fileSizeKB = (stats.size / 1024).toFixed(1);
+            return JSON.stringify({
+                success: true,
+                filePath: path.resolve(savePath),
+                fileSize: `${fileSizeKB} KB`,
+                contentType,
+                note: "文件已保存到本地",
+            });
+        }
+        catch (error) {
+            return JSON.stringify({
+                success: false,
+                error: error?.message || "下载失败",
+            });
+        }
+    },
+});

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

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

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

@@ -0,0 +1,79 @@
+import { CallbackTool } from "@ai-zen/agents-core";
+import * as fsp from "fs/promises";
+function countOccurrences(content, text) {
+    let count = 0;
+    let pos = 0;
+    while (true) {
+        pos = content.indexOf(text, pos);
+        if (pos === -1)
+            break;
+        count++;
+        pos += text.length;
+    }
+    return count;
+}
+export const editTool = new CallbackTool({
+    function: {
+        name: "edit",
+        description: "编辑文件中的文本，支持精确替换或替换所有匹配项",
+        parameters: {
+            type: "object",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "文件路径",
+                },
+                oldText: {
+                    type: "string",
+                    description: "要替换的文本",
+                },
+                newText: {
+                    type: "string",
+                    description: "替换后的文本",
+                },
+                isReplaceAll: {
+                    type: "boolean",
+                    description: "是否替换所有匹配的文本（默认 false，仅替换首次匹配）。使用此功能前应确保你提供的 oldText 足够精确，避免误替换",
+                    default: false,
+                },
+            },
+            required: ["path", "oldText", "newText"],
+            additionalProperties: false,
+        },
+    },
+    async callback(input) {
+        try {
+            const path = input.path;
+            const oldText = input.oldText;
+            const newText = input.newText;
+            const isReplaceAll = input.isReplaceAll;
+            const content = await fsp.readFile(path, "utf-8");
+            const count = countOccurrences(content, oldText);
+            if (count === 0) {
+                return JSON.stringify({
+                    result: "文件中未精确匹配到要替换的文本",
+                    matchCount: 0,
+                });
+            }
+            const newContent = isReplaceAll
+                ? content.replaceAll(oldText, newText)
+                : content.replace(oldText, newText);
+            await fsp.writeFile(path, newContent);
+            if (!isReplaceAll && count > 1) {
+                return JSON.stringify({
+                    result: `警告：未开启替换所有（isReplaceAll=false），但文本 "${oldText}" 在文件中出现了 ${count} 次，仅替换了首次匹配。如果希望替换所有匹配，请将 isReplaceAll 设为 true`,
+                    matchCount: count,
+                    replacedCount: 1,
+                });
+            }
+            return JSON.stringify({
+                result: "success",
+                matchCount: count,
+                replacedCount: isReplaceAll ? count : 1,
+            });
+        }
+        catch (error) {
+            return error?.message;
+        }
+    },
+});

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

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