@ai-zen/agents-sdk 0.3.4 → 0.5.0

package/dist/runtime/SdkCallbackTool.d.ts

@@ -0,0 +1,28 @@
+import { Tool, FunctionCallContext } from "@ai-zen/agents-core";
+import type { AgentNS } from "@ai-zen/agents-core";
+import type { ToolEnv } from "../types/index.js";
+/**
+ * SdkCallbackTool — SDK 内置工具基类。
+ *
+ * 环境（ToolEnv）在构造时注入，工具逻辑在子类的 call() 中实现，
+ * 不再依赖全局 process.cwd()，也不需要在运行时反查 Agent 上下文。
+ *
+ * 设计原则：
+ *   - 一个工具一个类，文件名 = 类名（PascalCase）
+ *   - 依赖环境（cwd、config）通过构造参数显式注入
+ *   - 相对路径统一用 resolve() 解析到 env.cwd
+ */
+export declare abstract class SdkCallbackTool extends Tool {
+    /** 注入的工具环境 */
+    readonly env: ToolEnv;
+    constructor(options: {
+        function: AgentNS.FunctionDefine;
+        env: ToolEnv;
+    });
+    /** 工具核心逻辑（由子类实现，参数为 parsed_args） */
+    abstract call(input: unknown): unknown | Promise<unknown>;
+    /** 桥接 core 的 Tool.exec：解析参数 → call → 序列化 */
+    exec(ctx: FunctionCallContext): Promise<string>;
+    /** 将相对路径解析到 env.cwd，绝对路径原样返回 */
+    resolve(p: string): string;
+}

package/dist/runtime/SdkCallbackTool.js

@@ -0,0 +1,33 @@
+import path from "node:path";
+import { Tool } from "@ai-zen/agents-core";
+/**
+ * SdkCallbackTool — SDK 内置工具基类。
+ *
+ * 环境（ToolEnv）在构造时注入，工具逻辑在子类的 call() 中实现，
+ * 不再依赖全局 process.cwd()，也不需要在运行时反查 Agent 上下文。
+ *
+ * 设计原则：
+ *   - 一个工具一个类，文件名 = 类名（PascalCase）
+ *   - 依赖环境（cwd、config）通过构造参数显式注入
+ *   - 相对路径统一用 resolve() 解析到 env.cwd
+ */
+export class SdkCallbackTool extends Tool {
+    /** 注入的工具环境 */
+    env;
+    constructor(options) {
+        super({ function: options.function });
+        this.env = options.env;
+    }
+    /** 桥接 core 的 Tool.exec：解析参数 → call → 序列化 */
+    async exec(ctx) {
+        const result = await this.call(ctx.parsed_args);
+        if (typeof result === "string")
+            return result;
+        // JSON.stringify(undefined) 返回 undefined（非字符串），会破坏 Promise<string> 契约
+        return JSON.stringify(result) ?? "";
+    }
+    /** 将相对路径解析到 env.cwd，绝对路径原样返回 */
+    resolve(p) {
+        return path.isAbsolute(p) ? p : path.join(this.env.cwd, p);
+    }
+}

package/dist/shared/logger.d.ts

@@ -5,6 +5,10 @@ export interface LogFunctions {
 }
 export type Logger = LogFunctions;
 /**
- * 创建可注入的 Logger，默认使用 console。
+ * 获取全局 Logger 实例。
  */
-export declare function createLogger(log?: Partial<LogFunctions>): Logger;
+export declare function getLogger(): Logger;
+/**
+ * 设置全局 Logger 实例，替换默认的 console 输出。
+ */
+export declare function setLogger(log: Logger): void;

package/dist/shared/logger.js

@@ -1,10 +1,17 @@
+let currentLogger = {
+    info: console.log,
+    warn: console.warn,
+    error: console.error,
+};
 /**
- * 创建可注入的 Logger，默认使用 console。
+ * 获取全局 Logger 实例。
  */
-export function createLogger(log) {
-    return {
-        info: log?.info ?? console.log,
-        warn: log?.warn ?? console.warn,
-        error: log?.error ?? console.error,
-    };
+export function getLogger() {
+    return currentLogger;
+}
+/**
+ * 设置全局 Logger 实例，替换默认的 console 输出。
+ */
+export function setLogger(log) {
+    currentLogger = log;
 }

package/dist/types/index.d.ts

@@ -45,26 +45,6 @@ export interface AgentDefinition {
     updatedAt: string;
     version?: number;
 }
-/** 对话记录 */
-export interface Conversation {
-    id: string;
-    agentId: string;
-    modelId: string;
-    messages: AgentNS.Message[];
-    lastPromptTokens?: number;
-    cwd?: string;
-    createdAt: string;
-    updatedAt: string;
-}
-/** 当前会话草稿 */
-export interface Draft {
-    conversationId?: string;
-    agentId: string;
-    modelId: string;
-    messages: AgentNS.Message[];
-    cwd?: string;
-    updatedAt: string;
-}
 /** 图片生成模型配置 */
 export interface ImageModel {
     id: string;
@@ -90,6 +70,18 @@ export interface AppConfig {
     /** 默认迁移模型 ID */
     defaultMigrationModel?: string;
 }
+/**
+ * 工具环境 — Provider 在实例化内置工具时注入的环境信息。
+ *
+ * cwd 是相对路径解析的基准（每个 Provider 对应一个工作目录）；
+ * config 供需要模型/端点配置的工具（如 generateImage）使用。
+ */
+export interface ToolEnv {
+    /** 当前工作目录 */
+    cwd: string;
+    /** 应用配置 */
+    config: AppConfig;
+}
 /** MCP 连接状态 */
 export type McpConnectionState = "disconnected" | "connecting" | "connected" | "error";
 /** MCP 服务器配置 */

package/package.json

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

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

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

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

@@ -1,76 +0,0 @@
-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

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

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

@@ -1,38 +0,0 @@
-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

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

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

@@ -1,15 +0,0 @@
-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

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

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

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

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

@@ -1,79 +0,0 @@
-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

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

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

@@ -1,38 +0,0 @@
-import { CallbackTool } from "@ai-zen/agents-core";
-import { exec } from "child_process";
-export const execTool = new CallbackTool({
-    function: {
-        name: "exec",
-        description: "执行命令",
-        parameters: {
-            type: "object",
-            properties: {
-                command: {
-                    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) => {
-            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,
-                });
-            });
-        });
-        return JSON.stringify(result);
-    },
-});

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

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

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

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

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

@@ -1,25 +0,0 @@
-import { CallbackTool } from "@ai-zen/agents-core";
-import * as fsp from "fs/promises";
-export const existTool = new CallbackTool({
-    function: {
-        name: "exist",
-        description: "检查文件或目录是否存在",
-        parameters: {
-            type: "object",
-            properties: {
-                path: {
-                    type: "string",
-                    description: "文件或目录路径",
-                },
-            },
-            required: ["path"],
-            additionalProperties: false,
-        },
-    },
-    async callback(input) {
-        return await fsp
-            .access(input.path)
-            .then(() => "true")
-            .catch(() => "false");
-    },
-});

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

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

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

@@ -1,9 +0,0 @@
-import { CallbackTool } from "@ai-zen/agents-core";
-import type { AppConfig } from "../../../types/index.js";
-/**
- * 根据文字描述生成图片。返回图片 URL，可通过 downloadFile 工具保存到本地。
- *
- * 依赖 AppConfig 中的 imageModels 和 defaultImageModel 配置。
- * 如果未配置图片模型，工具会返回错误提示。
- */
-export declare function createGenerateImageTool(config: AppConfig): CallbackTool;

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

@@ -1,112 +0,0 @@
-import { CallbackTool, OpenAI, ZhipuImage } from "@ai-zen/agents-core";
-/**
- * 根据文字描述生成图片。返回图片 URL，可通过 downloadFile 工具保存到本地。
- *
- * 依赖 AppConfig 中的 imageModels 和 defaultImageModel 配置。
- * 如果未配置图片模型，工具会返回错误提示。
- */
-export function createGenerateImageTool(config) {
-    return new CallbackTool({
-        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,
-            },
-        },
-        async callback(input) {
-            try {
-                const prompt = input.prompt;
-                if (!prompt || !prompt.trim()) {
-                    return JSON.stringify({ success: false, error: "prompt 不能为空" });
-                }
-                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/glob.d.ts

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

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

@@ -1,45 +0,0 @@
-import { CallbackTool } from "@ai-zen/agents-core";
-import * as fsp from "fs/promises";
-export const globTool = new CallbackTool({
-    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,
-        },
-    },
-    async callback(input) {
-        try {
-            const result = [];
-            for await (const file of fsp.glob(input.pattern, {
-                exclude: input.exclude || ["**/node_modules/**"],
-                cwd: input.path,
-            })) {
-                result.push(file);
-            }
-            return JSON.stringify(result);
-        }
-        catch (error) {
-            return error?.message;
-        }
-    },
-});

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

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