@ai-zen/agents-sdk 0.4.0 → 0.5.1

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## [0.5.1] - 2026-08-03
+
+### 🛠 优化
+
+- **依赖 `@ai-zen/agents-core` 升级并改为范围版本** — 从 `workspace:*`（发布时替换为精确版本 `3.0.1`）改为 `workspace:^`（发布为 `^3.1.0`）。core 3.1.0 起 `Message` 构造自动生成 `id`，SDK 透传的消息随之携带稳定 id；范围版本使 core 后续 minor/patch 升级不再需要 SDK 单独发版跟进
+
+## [0.5.0] - 2026-07-29
+
+### 💥 破坏性变更
+
+- **内置工具全部类化** — 17 个内置工具从单例 `CallbackTool` 实例改为类（`CwdTool`、`ReadFileTool`、`WriteFileTool`、`ExecTool` 等，PascalCase 命名），继承新抽象基类 `SdkCallbackTool`。`BUILTIN_TOOLS` 单例注册表替换为 `BUILTIN_TOOL_CLASSES` 类注册表（`Array<new (env: ToolEnv) => SdkCallbackTool>`）
+- **`generateImage` 类化为 `GenerateImageTool`** — 删除工厂函数 `createGenerateImageTool(config)`，构造签名与其它内置工具统一为 `(env: ToolEnv)`。仍按 `config.defaultImageModel` 条件注册，不进入 `BUILTIN_TOOL_CLASSES` 静态注册表
+- **`discoverBuiltinTools` 签名变更** — 从 `discoverBuiltinTools(config: AppConfig)` 改为 `discoverBuiltinTools(env: ToolEnv)`，用 `env` 实例化工具类
+- **`Provider` 新增 `cwd` 与 `env`** — `cwd` 默认 `process.cwd()`，是相对路径解析的基准；`env: ToolEnv`（`{ cwd, config }`）在构造时建立，`refresh()` 用它实例化内置工具。**工具不再依赖全局 `process.cwd()`**，每个 Provider 可绑定不同工作目录
+- **删除会话/草稿产品层** — `Conversation` / `Draft` 类型、`ConversationRepository`、`DraftRepository`、`AutoDraftPlugin` 及其测试全部移除。会话、草稿持久化下放给各端（CLI/Desktop）自行实现（可复用 `EntityRepository`）
+- **`index.ts` 导出变更** — 移除 `Conversation`/`Draft`/`ConversationRepository`/`DraftRepository`/`AutoDraftPlugin`/`BUILTIN_TOOLS`/`execAsyncTool`/`sleepTool`/`createGenerateImageTool`；新增 `ToolEnv`、`SdkCallbackTool`、`BUILTIN_TOOL_CLASSES`、`GenerateImageTool` 及 17 个工具类
+
+### 🚀 新功能
+
+- **`ToolEnv` 接口** — 工具环境 `{ cwd, config }`，在工具构造时注入，作为相对路径解析与配置读取的基准
+- **`SdkCallbackTool` 抽象基类** — `env` 构造注入 + 子类实现 `call()` + `exec()` 桥接 + `resolve()` 相对路径解析（public，便于测试直调）
+
+### 🎯 优化
+
+- **多会话并行支持** — `cwd` 下沉到 Provider（`ToolEnv.cwd`），多个 Provider 可并行服务不同工作目录的会话，互不干扰
+- **工具实例 per-Provider** — 每个 Provider 通过 `discoverBuiltinTools(env)` 实例化自己的一套工具，消除全局单例状态
+
 ## [0.4.0] - 2026-07-29
 
 ### 💥 破坏性变更

package/README.md

@@ -17,12 +17,12 @@ Desktop ──┘                    │
 ## 模块分层
 
 ```
-types        ← 纯类型，零业务依赖
+types        ← 纯类型，零业务依赖（含 ToolEnv 工具环境）
 config       ← 读写 config.json + 迁移 + 内存缓存 + 原子写入
-crud         ← 实体 CRUD（Endpoints / Models / Agents / Conversations / Draft）
+crud         ← 能力实体 CRUD（Agent 定义等；会话/草稿已下放给各端自行持久化）
 capabilities ← 能力发现与装配（内置 + 用户 + MCP + Skill + SubAgent）
-runtime      ← Provider + 模型工厂 + Agent 组装 + MCP 连接管理 + 任务迁移
-plugin       ← Agent 插件（autoMigrate、autoDraft、autoRefreshTools）
+runtime      ← Provider + 模型工厂 + Agent 组装 + MCP 连接管理 + 任务迁移 + SdkCallbackTool 工具基类
+plugin       ← Agent 插件（autoMigrate、autoRefreshTools）
 shared       ← 日志、错误
 ```
 
@@ -32,14 +32,14 @@ shared       ← 日志、错误
 
 | 实体 | 说明 |
 |------|------|
-| **Provider** | 全局上下文 + 能力注册表，持有配置、路径、模型工厂、MCP 管理器，整合发现 → 过滤 → 实例化 |
+| **Provider** | 全局上下文 + 能力注册表，持有配置、路径（含 `cwd`）、模型工厂、MCP 管理器，整合发现 → 过滤 → 实例化 |
+| **ToolEnv** | 工具环境 `{ cwd, config }`，Provider 实例化内置工具时注入，作为相对路径解析与配置读取的基准 |
+| **SdkCallbackTool** | 内置工具抽象基类：`env` 构造注入 + 子类实现 `call()` + `resolve()` 相对路径解析 |
 | **SdkAgent** | 继承 Core Agent，携带 SDK 元数据，支持 `use()` 插件注册 |
 | **AgentPlugin** | 插件接口（`onInit`, `onBeforeSend`, `onAfterSend`, `onInnerLoopStart`, `onInnerLoopEnd`） |
 | **Endpoint** | API 端点（baseUrl + apiKey） |
 | **Model** | 模型配置，绑定 Endpoint |
 | **SubAgent** | 有 `function` 字段的 Agent，可被其他 Agent 作为工具调用 |
-| **Conversation** | 对话记录 |
-| **Draft** | 当前会话自动保存 |
 
 ## 权限模型
 
@@ -56,10 +56,13 @@ Agent.permissions
 ## 消费模式
 
 ```typescript
-const provider = await Provider.create({ config, ...paths });
+const provider = await Provider.create({
+  config,
+  cwd: "/path/to/workspace", // 每个 Provider 一个工作目录，多会话并行互不干扰
+  ...paths,
+});
 const agent = createAgent(provider, "my-agent");
-agent.use(new AutoMigratePlugin({ maxTokens, migrationAgent, onHandoff }));
-agent.use(new AutoDraftPlugin({ draftsDir, agentId, modelId }));
+agent.use(new AutoMigratePlugin({ maxTokens, migrationAgent, onMigrated }));
 agent.use(new AutoRefreshToolsPlugin());
 await agent.init();
 await agent.send("你好");
@@ -71,15 +74,17 @@ await agent.send("你好");
 |------|------|
 | `types` | ✅ 已实现 — 核心实体、权限模型、MCP 类型完整 |
 | `config` | ✅ 已实现 — ConfigManager + 出厂默认配置 + 一键 bootstrap |
-| `crud` | ✅ 已实现 — Agent / Conversation / Draft 完整 CRUD |
+| `crud` | ✅ 已实现 — Agent 等能力实体 CRUD（会话/草稿由各端自行持久化） |
 | `capabilities` | ✅ 已实现 — 发现 + 权限过滤 + 安全预过滤 + 枚举披露 |
 | `runtime` | ✅ 已实现 — Provider、Capabilities、createAgent、MCP 连接管理、任务迁移 |
-| `plugin` | ✅ 已实现 — AutoMigratePlugin / AutoDraftPlugin / AutoRefreshToolsPlugin |
+| `plugin` | ✅ 已实现 — AutoMigratePlugin / AutoRefreshToolsPlugin |
 | `shared` | ✅ 已实现 — SdkError + 可注入 Logger |
-| 测试 | ✅ 593 个测试，68 个文件，全通过（含真实 API 聊天 e2e） |
+| 测试 | ✅ 409 个测试，47 个文件，全通过（含真实 API 聊天 e2e） |
 
 ## 内置工具
 
+内置工具全部类化（继承 `SdkCallbackTool`），由 Provider 用 `ToolEnv` 实例化——每个 Provider 一套实例，`cwd` 注入，相对路径以 `Provider.cwd` 为基准，不依赖全局 `process.cwd()`。
+
 | 工具 | 说明 |
 |------|------|
 | `cwd` | 获取当前工作目录 |
@@ -100,7 +105,7 @@ await agent.send("你好");
 | `edit` | 编辑文件中的文本 |
 | `sleep` | 等待指定毫秒数后继续 |
 
-条件注入（需配置 `imageModels`）：
+条件注入（`GenerateImageTool` 需配置 `defaultImageModel` 才注册）：
 
 | 工具 | 说明 |
 |------|------|
@@ -111,7 +116,6 @@ await agent.send("你好");
 | 插件 | 说明 |
 |------|------|
 | `AutoMigratePlugin` | 上下文超限时自动触发任务迁移，生成交接文档，透明替换 Agent |
-| `AutoDraftPlugin` | 每次 `send()` 后自动保存当前消息历史到 draft 文件 |
 | `AutoRefreshToolsPlugin` | 每次 `send()` 前重新扫描文件系统，刷新工具列表 |
 
 ## 设计原则

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

@@ -1,8 +1,9 @@
-import { Tool } from "@ai-zen/agents-core";
-import type { AppConfig } from "../../types/index.js";
+import type { Tool } from "@ai-zen/agents-core";
+import type { ToolEnv } from "../../types/index.js";
 /**
- * 发现内置工具。直接返回 BUILTIN_TOOLS 实例。
- * 如果配置了 defaultImageModel，额外包含 generateImage 工具。
- * 与 discoverUserTools 保持对称：都返回 Tool[]。
+ * 发现内置工具：用 ToolEnv 实例化全部内置工具类。
+ *
+ * generateImage 依赖图片模型配置（defaultImageModel），未配置时不注册，
+ * 因此不进入 BUILTIN_TOOL_CLASSES 静态注册表，在此按条件实例化。
  */
-export declare function discoverBuiltinTools(config: AppConfig): Tool[];
+export declare function discoverBuiltinTools(env: ToolEnv): Tool[];

package/dist/capabilities/discovery/builtin.js

@@ -1,16 +1,17 @@
-import { BUILTIN_TOOLS } from "../implements/builtin/index.js";
-import { createGenerateImageTool } from "../implements/builtin/generateImage.js";
+import { BUILTIN_TOOL_CLASSES } from "../implements/builtin/index.js";
+import { GenerateImageTool } from "../implements/builtin/GenerateImageTool.js";
 /**
- * 发现内置工具。直接返回 BUILTIN_TOOLS 实例。
- * 如果配置了 defaultImageModel，额外包含 generateImage 工具。
- * 与 discoverUserTools 保持对称：都返回 Tool[]。
+ * 发现内置工具：用 ToolEnv 实例化全部内置工具类。
+ *
+ * generateImage 依赖图片模型配置（defaultImageModel），未配置时不注册，
+ * 因此不进入 BUILTIN_TOOL_CLASSES 静态注册表，在此按条件实例化。
  */
-export function discoverBuiltinTools(config) {
-    const tools = [...BUILTIN_TOOLS];
-    if (config.defaultImageModel) {
+export function discoverBuiltinTools(env) {
+    const tools = BUILTIN_TOOL_CLASSES.map((Cls) => new Cls(env));
+    if (env.config.defaultImageModel) {
         const existingNames = new Set(tools.map((t) => t.function.name));
         if (!existingNames.has("generateImage")) {
-            tools.push(createGenerateImageTool(config));
+            tools.push(new GenerateImageTool(env));
         }
     }
     return tools;

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

@@ -0,0 +1,15 @@
+import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import type { ToolEnv } from "../../../types/index.js";
+interface Replacement {
+    oldText: string;
+    newText: string;
+    isReplaceAll?: boolean;
+}
+export declare class BatchEditTool extends SdkCallbackTool {
+    constructor(env: ToolEnv);
+    call(input: {
+        path: string;
+        replacements: Replacement[];
+    }): Promise<string>;
+}
+export {};

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

@@ -0,0 +1,82 @@
+import * as fsp from "fs/promises";
+import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+export class BatchEditTool extends SdkCallbackTool {
+    constructor(env) {
+        super({
+            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,
+                },
+            },
+            env,
+        });
+    }
+    async call(input) {
+        try {
+            const filePath = this.resolve(input.path);
+            const content = await fsp.readFile(filePath, "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(filePath, newContent);
+            return JSON.stringify(results);
+        }
+        catch (error) {
+            return error?.message;
+        }
+    }
+}

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

@@ -0,0 +1,10 @@
+import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import type { ToolEnv } from "../../../types/index.js";
+export declare class CopyTool extends SdkCallbackTool {
+    constructor(env: ToolEnv);
+    call(input: {
+        src: string;
+        dest: string;
+        recursive?: boolean;
+    }): Promise<string>;
+}

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

@@ -0,0 +1,43 @@
+import * as fsp from "fs/promises";
+import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+export class CopyTool extends SdkCallbackTool {
+    constructor(env) {
+        super({
+            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,
+                },
+            },
+            env,
+        });
+    }
+    async call(input) {
+        try {
+            await fsp.cp(this.resolve(input.src), this.resolve(input.dest), {
+                recursive: input.recursive ?? false,
+            });
+            return "success";
+        }
+        catch (error) {
+            return error?.message;
+        }
+    }
+}

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

@@ -0,0 +1,6 @@
+import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import type { ToolEnv } from "../../../types/index.js";
+export declare class CwdTool extends SdkCallbackTool {
+    constructor(env: ToolEnv);
+    call(): string;
+}

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

@@ -0,0 +1,20 @@
+import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+export class CwdTool extends SdkCallbackTool {
+    constructor(env) {
+        super({
+            function: {
+                name: "cwd",
+                description: "获取当前工作目录 cwd",
+                parameters: {
+                    type: "object",
+                    properties: {},
+                    required: [],
+                },
+            },
+            env,
+        });
+    }
+    call() {
+        return this.env.cwd;
+    }
+}

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

@@ -0,0 +1,9 @@
+import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import type { ToolEnv } from "../../../types/index.js";
+export declare class DownloadFileTool extends SdkCallbackTool {
+    constructor(env: ToolEnv);
+    call(input: {
+        url: string;
+        outputPath?: string;
+    }): Promise<string>;
+}

package/dist/capabilities/implements/builtin/{downloadFile.js → DownloadFileTool.js}

@@ -1,34 +1,39 @@
-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 推断文件名。",
+import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+export class DownloadFileTool extends SdkCallbackTool {
+    constructor(env) {
+        super({
+            function: {
+                name: "downloadFile",
+                description: "从 URL 下载文件（图片、PDF 等二进制文件）并保存到本地磁盘。自动从 URL 推断文件名，也可指定保存路径。",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        url: {
+                            type: "string",
+                            description: "文件下载链接",
+                        },
+                        outputPath: {
+                            type: "string",
+                            description: "保存路径（可选）。可以是目录或完整文件路径。不指定则下载到当前工作目录，自动从 URL 推断文件名。",
+                        },
+                    },
+                    required: ["url"],
+                    additionalProperties: false,
                 },
             },
-            required: ["url"],
-            additionalProperties: false,
-        },
-    },
-    async callback(input) {
+            env,
+        });
+    }
+    async call(input) {
         try {
             const url = input.url;
             if (!url)
                 throw new Error("url 不能为空");
             let savePath;
             if (input.outputPath) {
-                savePath = input.outputPath;
+                savePath = this.resolve(input.outputPath);
                 const stat = await fsp.stat(savePath).catch(() => null);
                 if (stat?.isDirectory()) {
                     const urlPath = new URL(url).pathname;
@@ -39,7 +44,7 @@ export const downloadFileTool = new CallbackTool({
             else {
                 const urlPath = new URL(url).pathname;
                 const fileName = path.basename(urlPath) || `download_${Date.now()}`;
-                savePath = path.join(process.cwd(), fileName);
+                savePath = path.join(this.env.cwd, fileName);
             }
             await fsp.mkdir(path.dirname(savePath), { recursive: true });
             const response = await fetch(url);
@@ -66,5 +71,5 @@ export const downloadFileTool = new CallbackTool({
                 error: error?.message || "下载失败",
             });
         }
-    },
-});
+    }
+}

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

@@ -0,0 +1,11 @@
+import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import type { ToolEnv } from "../../../types/index.js";
+export declare class EditTool extends SdkCallbackTool {
+    constructor(env: ToolEnv);
+    call(input: {
+        path: string;
+        oldText: string;
+        newText: string;
+        isReplaceAll?: boolean;
+    }): Promise<string>;
+}

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

@@ -0,0 +1,84 @@
+import * as fsp from "fs/promises";
+import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+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 class EditTool extends SdkCallbackTool {
+    constructor(env) {
+        super({
+            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,
+                },
+            },
+            env,
+        });
+    }
+    async call(input) {
+        try {
+            const filePath = this.resolve(input.path);
+            const oldText = input.oldText;
+            const newText = input.newText;
+            const isReplaceAll = input.isReplaceAll ?? false;
+            const content = await fsp.readFile(filePath, "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(filePath, 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/ExecAsyncTool.d.ts

@@ -0,0 +1,10 @@
+import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import type { ToolEnv } from "../../../types/index.js";
+export declare class ExecAsyncTool extends SdkCallbackTool {
+    constructor(env: ToolEnv);
+    call(input: {
+        command: string;
+        cwd?: string;
+        detached?: boolean;
+    }): Promise<string>;
+}