@ai-zen/agents-sdk 0.2.8 → 0.3.2

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # Changelog
 
+## [0.3.2] - 2026-07-26
+
+### 💥 破坏性变更
+
+- **`EntityRepository` 所有方法改为异步** — `list()`、`read()`、`write()`、`delete()` 现在返回 `Promise`，需 `await`
+- **`DraftRepository` 所有方法改为异步** — `read()`、`write()`、`delete()` 需 `await`
+- **`ConfigManager` 所有方法改为异步** — `read()`、`write()`、`ensureDirs()`、`ensureDefaultAgent()`、`ensureDefaultSubAgent()`、`ensureDefaultConfig()`、`bootstrap()` 均需 `await`
+- **`createAgent()` 恢复为 `async`** — 因底层仓储改为异步，`createAgent(provider, agentId)` 需 `await`
+- **`AutoDraftPlugin.checkDraftForRestore()` 改为异步** — 需 `await`
+
+### 🎯 优化
+
+- **全面消除同步文件 IO** — 所有生产代码中的 `existsSync`、`readFileSync`、`writeFileSync`、`readdirSync`、`mkdirSync`、`unlinkSync`、`renameSync` 全部替换为 `fs.promises` 异步 API，避免事件循环阻塞
+- **`skillTools.ts` — 工具回调中的 `readdirSync` 替换为 `fs.promises.readdir`**
+
+### ✅ 测试
+
+- 7 个测试文件同步更新为 `async`/`await`，测试辅助函数也使用 `fs.promises`
+
+## [0.3.1] - 2026-07-26
+
+### 💥 破坏性变更
+
+- **`Provider` 移至 `runtime`，合并 `Capabilities`** — 删除 `capabilities/Capabilities.ts` 和原 `runtime/Provider.ts`，Provider 直接暴露 `filter()`、`buildTools()`、`instantiate()`、`refresh()`
+- **去除 `getMcpManager()` 方法** — `mcpManager` 从 lazy getter 改为构造时直接 `new McpConnectionManager()`（有 mcpPaths 时），`readonly` 属性
+- **字段重命名** — `builtinInstances` → `builtinTools`，`userInstances` → `userTools`，`subagentDefs` → `subagents`
+- **`createModel` 签名变更** — 从 `createModel(config, modelId)` 改为 `createModel(provider, modelId)`，调用方不再需要 `.config` 解构
+- **`SdkAgent` 去掉 `caps` 字段** — 只保留 `provider`
+
+### 🚀 新功能
+
+- **用户工具 ESM 支持** — 移除 `node:vm` 沙箱，统一使用 `import()` 加载 `.js` / `.mjs` 文件，每次 `refresh()` 加时间戳 querystring 防止缓存
+- **`CallbackTool` 替代 `createToolFromObject`** — `{ function, exec }` 格式直接映射为 `CallbackTool`
+
+### 🎯 优化
+
+- **默认 Agent 系统提示词更新** — 精简为五条原则：开动脑筋、实事求是、一切行动听指挥、安全第一、能打胜仗
+- **默认 SubAgent `function.description` 优化** — 强调主 Agent 必须提供完整任务上下文
+
+### 🗑 移除
+
+- 删除 `capabilities/Provider.ts`（已移回 `runtime/Provider.ts`）
+- 删除 `createToolFromObject` 工具函数
+- 删除 `TODO.md`、`TODO2.md`
+- 测试 fixture 从 `.js` 迁移为 `.mjs`
+
 ## [0.2.6] - 2026-07-20
 
 ### 🔧 修复

package/README.md

@@ -9,9 +9,9 @@ AI-Zen SDK — 共享业务逻辑层，为 CLI 和 Desktop 提供统一的 Agent
 
 ```
 CLI ──┐
-      ├── @ai-zen/sdk ──┐
-Desktop ──┘              │
-                    LLM API
+      ├── @ai-zen/agents-sdk ──┐
+Desktop ──┘                    │
+                          LLM API
 ```
 
 ## 模块分层
@@ -32,8 +32,7 @@ shared       ← 日志、错误
 
 | 实体 | 说明 |
 |------|------|
-| **Provider** | 全局上下文，持有配置、路径、模型工厂、MCP 管理器 |
-| **Capabilities** | 全局能力注册表（发现 → 过滤 → 实例化） |
+| **Provider** | 全局上下文 + 能力注册表，持有配置、路径、模型工厂、MCP 管理器，整合发现 → 过滤 → 实例化 |
 | **SdkAgent** | 继承 Core Agent，携带 SDK 元数据，支持 `use()` 插件注册 |
 | **AgentPlugin** | 插件接口（`onInit`, `onBeforeSend`, `onAfterSend`, `onInnerLoopStart`, `onInnerLoopEnd`） |
 | **Endpoint** | API 端点（baseUrl + apiKey） |
@@ -57,7 +56,7 @@ Agent.permissions
 ## 消费模式
 
 ```typescript
-const provider = new Provider({ config, ...paths });
+const provider = await Provider.create({ config, ...paths });
 const agent = createAgent(provider, "my-agent");
 agent.use(new AutoMigratePlugin({ maxTokens, migrationAgent, onHandoff }));
 agent.use(new AutoDraftPlugin({ draftsDir, agentId, modelId }));
@@ -77,7 +76,7 @@ await agent.send("你好");
 | `runtime` | ✅ 已实现 — Provider、Capabilities、createAgent、MCP 连接管理、任务迁移 |
 | `plugin` | ✅ 已实现 — AutoMigratePlugin / AutoDraftPlugin / AutoRefreshToolsPlugin |
 | `shared` | ✅ 已实现 — SdkError + 可注入 Logger |
-| 测试 | ✅ 359 个测试，45 个文件，全通过（含真实 API 聊天 e2e） |
+| 测试 | ✅ 593 个测试，68 个文件，全通过（含真实 API 聊天 e2e） |
 
 ## 内置工具
 

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

@@ -9,4 +9,4 @@ import type { McpServerConfig } from "../../types/index.js";
  *
  * 按优先级从高到低传入路径列表，同名 server 靠前的文件优先（先到先得）。
  */
-export declare function discoverMcpServers(paths: string[]): McpServerConfig[];
+export declare function discoverMcpServers(paths: string[]): Promise<McpServerConfig[]>;

package/dist/capabilities/discovery/mcp.js

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync } from "node:fs";
+import { promises as fs } from "node:fs";
 /**
  * 归一化原始 MCP server 配置为内部 McpServerConfig。
  * 处理业界标准中的字段别名差异。
@@ -51,14 +51,18 @@ function normalizeTransport(type, raw) {
  *
  * 按优先级从高到低传入路径列表，同名 server 靠前的文件优先（先到先得）。
  */
-export function discoverMcpServers(paths) {
+export async function discoverMcpServers(paths) {
     const seen = new Set();
     const items = [];
     for (const path of paths) {
-        if (!existsSync(path))
+        try {
+            await fs.access(path);
+        }
+        catch {
             continue;
+        }
         try {
-            const raw = readFileSync(path, "utf-8");
+            const raw = await fs.readFile(path, "utf-8");
             const config = JSON.parse(raw);
             // 业界标准使用 mcpServers 顶层字段
             const servers = config.mcpServers ?? {};

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

@@ -34,7 +34,7 @@ export interface SkillInfo {
  */
 export declare function discoverSkills(paths: string[], options?: {
     silent?: boolean;
-}): SkillInfo[];
+}): Promise<SkillInfo[]>;
 /**
  * 读取单个 Skill 的完整内容与元数据。
  * 按优先级从高到低传入路径列表，靠前的路径优先（先到先得）。
@@ -42,7 +42,7 @@ export declare function discoverSkills(paths: string[], options?: {
  */
 export declare function readSkill(skillDirs: string[], skillId: string, options?: {
     silent?: boolean;
-}): SkillInfo | null;
+}): Promise<SkillInfo | null>;
 /** @internal */
 export declare function parseFrontmatter(content: string): Frontmatter;
 /** @internal */

package/dist/capabilities/discovery/skills.js

@@ -1,4 +1,4 @@
-import { readdirSync, existsSync, readFileSync } from "node:fs";
+import { promises as fs } from "node:fs";
 import { join } from "node:path";
 import { createLogger } from "../../shared/logger.js";
 const log = createLogger();
@@ -8,16 +8,20 @@ const log = createLogger();
  * 按优先级从高到低传入路径列表，同名 skill 靠前的路径优先（先到先得）。
  * 解析 YAML frontmatter 中的 name 和 description，同时校验合规。
  */
-export function discoverSkills(paths, options) {
+export async function discoverSkills(paths, options) {
     const silent = options?.silent ?? false;
     const seen = new Set();
     const items = [];
     for (const dir of paths) {
-        if (!existsSync(dir))
+        try {
+            await fs.access(dir);
+        }
+        catch {
             continue;
+        }
         let entries;
         try {
-            entries = readdirSync(dir, { withFileTypes: true });
+            entries = await fs.readdir(dir, { withFileTypes: true });
         }
         catch {
             continue;
@@ -28,9 +32,13 @@ export function discoverSkills(paths, options) {
             if (seen.has(entry.name))
                 continue;
             const skillMdPath = join(dir, entry.name, "SKILL.md");
-            if (!existsSync(skillMdPath))
+            try {
+                await fs.access(skillMdPath);
+            }
+            catch {
                 continue;
-            const skill = readSkillFromPath(entry.name, skillMdPath, silent);
+            }
+            const skill = await readSkillFromPath(entry.name, skillMdPath, silent);
             if (skill) {
                 seen.add(entry.name);
                 items.push(skill);
@@ -45,20 +53,24 @@ export function discoverSkills(paths, options) {
  * 按优先级从高到低传入路径列表，靠前的路径优先（先到先得）。
  * 返回 null 如果 skill 在所有目录中都不存在或 SKILL.md 不可读。
  */
-export function readSkill(skillDirs, skillId, options) {
+export async 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, silent);
+        try {
+            await fs.access(candidate);
+            return await readSkillFromPath(skillId, candidate, silent);
+        }
+        catch {
+            continue;
         }
     }
     return null;
 }
 // ---- 内部 ----
-function readSkillFromPath(skillId, skillMdPath, silent) {
+async function readSkillFromPath(skillId, skillMdPath, silent) {
     try {
-        const content = readFileSync(skillMdPath, "utf-8");
+        const content = await fs.readFile(skillMdPath, "utf-8");
         const fm = parseFrontmatter(content);
         if (!fm.name)
             return null;

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

@@ -4,4 +4,4 @@ import type { AgentDefinition } from "../../types/index.js";
  * 按优先级从高到低传入路径列表，同名 function.name 靠前的路径优先（先到先得）。
  * 跳过无 function 的普通 Agent 和解析失败的文件。
  */
-export declare function discoverSubAgents(paths: string[]): AgentDefinition[];
+export declare function discoverSubAgents(paths: string[]): Promise<AgentDefinition[]>;

package/dist/capabilities/discovery/subagents.js

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

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

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

package/dist/capabilities/discovery/usertools.js

@@ -1,35 +1,40 @@
-import { readdirSync, existsSync, readFileSync } from "node:fs";
+import { promises as fs } from "node:fs";
 import { join } from "node:path";
-import vm from "node:vm";
+import { pathToFileURL } from "node:url";
 import { Tool, CallbackTool } from "@ai-zen/agents-core";
 /**
- * 扫描多个 tools/ 目录，发现所有 .js 文件，动态加载为 Tool 实例。
+ * 扫描多个 tools/ 目录，发现所有 .js / .mjs 文件，动态加载为 Tool 实例。
+ * 使用原生 dynamic import() 加载（在 "type": "module" 下 .js 也是 ESM），
+ * 每次添加时间戳 querystring 防止缓存。
+ *
  * 按优先级从高到低传入路径列表，同名工具靠前的路径优先（先到先得）。
  * 按文件名排序以保证确定性。
- *
- * 加载方式：
- * 1. 使用 vm.compileFunction 创建安全的执行上下文
- * 2. 工具文件应通过 module.exports 或 exports.default 导出 Tool 实例
- * 3. 支持直接导出 { function, exec } 格式的对象（自动适配为 Tool）
- * 4. 支持导出 CallbackTool 兼容的 { function, callback } 格式
  */
-export function discoverUserTools(paths, options) {
+export async function discoverUserTools(paths, options) {
     const silent = options?.silent ?? false;
     const seen = new Set();
     const tools = [];
     for (const dir of paths) {
-        if (!existsSync(dir))
+        try {
+            await fs.access(dir);
+        }
+        catch {
             continue;
+        }
         try {
-            const files = readdirSync(dir)
-                .filter((f) => f.endsWith(".js"))
-                .map((f) => f.slice(0, -3))
-                .sort();
-            for (const name of files) {
+            const allFiles = await fs.readdir(dir);
+            const files = allFiles
+                .filter((f) => f.endsWith(".js") || f.endsWith(".mjs"))
+                .map((f) => {
+                const ext = f.endsWith(".mjs") ? ".mjs" : ".js";
+                return { name: f.slice(0, -ext.length), ext };
+            })
+                .sort((a, b) => a.name.localeCompare(b.name));
+            for (const { name, ext } of files) {
                 if (!seen.has(name)) {
                     seen.add(name);
                     try {
-                        const tool = loadToolFile(join(dir, name + ".js"), silent);
+                        const tool = await loadToolFile(join(dir, name + ext), silent);
                         if (tool) {
                             tools.push(tool);
                         }
@@ -46,45 +51,25 @@ export function discoverUserTools(paths, options) {
     }
     return tools;
 }
+// ==================================================================
+// ESM 加载（import()）
+// ==================================================================
 /**
- * 从 .js 文件加载 Tool 实例。
+ * 从 .js / .mjs 文件加载 Tool 实例。
  *
- * 使用 vm.compileFunction 创建沙箱执行环境，避免污染全局作用域。
- * 注入有限的全局 API（console, setTimeout 等），不暴露 process/require。
+ * 使用原生 dynamic import() 加载 ESM 模块。每次调用添加时间戳 querystring
+ * 防止模块缓存，确保 refresh() 能重新加载。
  */
-function loadToolFile(filepath, silent) {
-    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 });
+async function loadToolFile(filepath, silent) {
     try {
-        script.runInContext(context, { timeout: 5000 });
-        // 获取导出结果
-        const exported = sandbox.module.exports ?? sandbox.exports;
-        // 空导出
+        const url = `${pathToFileURL(filepath).href}?t=${Date.now()}`;
+        const mod = await import(url);
+        // import() 返回模块命名空间对象，取其 default 导出
+        const exported = mod.default ?? mod;
         if (!exported || (typeof exported === "object" && Object.keys(exported).length === 0)) {
             return null;
         }
-        // 适配不同导出格式
-        return normalizeToolExport(exported, filepath, silent);
+        return normalizeToolExport({ default: exported }, filepath, silent);
     }
     catch (err) {
         if (!silent) {
@@ -93,6 +78,9 @@ function loadToolFile(filepath, silent) {
         return null;
     }
 }
+// ==================================================================
+// 导出格式归一化
+// ==================================================================
 /**
  * 统一各种导出格式为 Tool 实例。
  */
@@ -106,9 +94,12 @@ function normalizeToolExport(exported, filepath, silent) {
     if (target instanceof Tool) {
         return target;
     }
-    // 情况 3：{ function, exec } 格式 → 适配为 Tool 子类
+    // 情况 3：{ function, exec } 格式 → 适配为 CallbackTool
     if (target && typeof target === "object" && target.function && typeof target.exec === "function") {
-        return createToolFromObject(target, filepath);
+        return new CallbackTool({
+            function: target.function,
+            callback: target.exec,
+        });
     }
     // 情况 4：{ function, callback } 格式 → 适配为 CallbackTool
     if (target && typeof target === "object" && target.function && typeof target.callback === "function") {
@@ -122,20 +113,3 @@ function normalizeToolExport(exported, filepath, silent) {
     }
     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/skillTools.d.ts

@@ -1,6 +1,6 @@
 import { CallbackTool } from "@ai-zen/agents-core";
 import type { SkillInfo } from "../discovery/skills.js";
-import type { Capabilities } from "../Capabilities.js";
+import type { Provider } from "../../runtime/Provider.js";
 /**
  * 创建 load_skill 工具。
  * 枚举所有允许的 skill（不限是否支持子 Agent），由 filteredSkills 提供完整信息。
@@ -12,4 +12,4 @@ export declare function createLoadSkillTool(skillDirs: string[], filteredSkills:
  *
  * 回调中创建独立的 Skill 子 Agent，通过 caps 按父 Agent 权限独立解析工具集。
  */
-export declare function createCallSkillSubAgentTool(skillDirs: string[], filteredSkills: SkillInfo[], caps?: Capabilities): CallbackTool;
+export declare function createCallSkillSubAgentTool(skillDirs: string[], filteredSkills: SkillInfo[], provider?: Provider): CallbackTool;

package/dist/capabilities/implements/skillTools.js

@@ -3,7 +3,7 @@ import { SdkAgent } from "../../runtime/SdkAgent.js";
 import { createDisclosureParam } from "../disclosure.js";
 import { readSkill } from "../discovery/skills.js";
 import { createLogger } from "../../shared/logger.js";
-import { readdirSync } from "node:fs";
+import { promises as fs } from "node:fs";
 const log = createLogger();
 const EMPTY_HINT = "（当前没有可用的 Skill，请联系用户添加）";
 /**
@@ -37,14 +37,14 @@ export function createLoadSkillTool(skillDirs, filteredSkills) {
         },
         callback: async function (input) {
             const skillId = input.skill_id;
-            const skill = readSkill(skillDirs, skillId);
+            const skill = await readSkill(skillDirs, skillId);
             if (!skill) {
                 return `❌ Skill "${skillId}" 不存在，请确认名称是否正确`;
             }
             // 扫描 skill 目录下的文件列表
             let fileList = "";
             try {
-                const entries = readdirSync(skill.dirPath, { withFileTypes: true });
+                const entries = await fs.readdir(skill.dirPath, { withFileTypes: true });
                 const files = entries.map((e) => {
                     const suffix = e.isDirectory() ? "/" : "";
                     return `  - ${e.name}${suffix}`;
@@ -72,7 +72,7 @@ export function createLoadSkillTool(skillDirs, filteredSkills) {
  *
  * 回调中创建独立的 Skill 子 Agent，通过 caps 按父 Agent 权限独立解析工具集。
  */
-export function createCallSkillSubAgentTool(skillDirs, filteredSkills, caps) {
+export function createCallSkillSubAgentTool(skillDirs, filteredSkills, provider) {
     // 只保留支持子 Agent 模式的 skill
     const subAgentSkills = filteredSkills.filter((s) => s.subAgent);
     const ids = subAgentSkills.map((s) => s.id);
@@ -106,7 +106,7 @@ export function createCallSkillSubAgentTool(skillDirs, filteredSkills, caps) {
         async callback(input) {
             const skillId = input.skill_id;
             const task = input.task;
-            const skill = readSkill(skillDirs, skillId);
+            const skill = await readSkill(skillDirs, skillId);
             if (!skill) {
                 return `❌ Skill "${skillId}" 不存在，请确认名称是否正确`;
             }
@@ -117,8 +117,8 @@ export function createCallSkillSubAgentTool(skillDirs, filteredSkills, caps) {
             const parentPermissions = parentAgent instanceof SdkAgent
                 ? parentAgent.permissions
                 : undefined;
-            const skillTools = caps && parentPermissions
-                ? caps.buildTools(parentPermissions, {
+            const skillTools = provider && parentPermissions
+                ? provider.buildTools(parentPermissions, {
                     exclude: { skills: [skillId] },
                 })
                 : [];

package/dist/capabilities/implements/subAgentTools.d.ts

@@ -1,11 +1,10 @@
 import type { Tool } from "@ai-zen/agents-core";
 import type { AgentDefinition } from "../../types/index.js";
 import type { Provider } from "../../runtime/Provider.js";
-import type { Capabilities } from "../Capabilities.js";
 /**
  * 创建 SubAgent 工具（AgentToolLazy）。
  *
  * SubAgent 是有 `function` 字段的 Agent，可被其他 Agent 作为工具调用。
  * 使用延迟构建（AgentToolLazy）避免工具列表构建阶段的递归创建问题。
  */
-export declare function createSubAgentTool(def: AgentDefinition, provider: Provider, caps?: Capabilities): Tool;
+export declare function createSubAgentTool(def: AgentDefinition, provider: Provider): Tool;

package/dist/capabilities/implements/subAgentTools.js

@@ -6,7 +6,7 @@ import { createModel } from "../../runtime/createModel.js";
  * SubAgent 是有 `function` 字段的 Agent，可被其他 Agent 作为工具调用。
  * 使用延迟构建（AgentToolLazy）避免工具列表构建阶段的递归创建问题。
  */
-export function createSubAgentTool(def, provider, caps) {
+export function createSubAgentTool(def, provider) {
     if (!def.function) {
         throw new Error(`Agent "${def.id}" 没有 function 字段，不能作为 SubAgent 工具`);
     }
@@ -19,14 +19,10 @@ export function createSubAgentTool(def, provider, caps) {
         },
         messages: def.messages,
         buildAgent: function (_parsedArgs) {
-            if (!caps) {
-                throw new Error(`SubAgent "${selfName}" 缺少 Capabilities 引用。` +
-                    `请确保 Capabilities.instantiate() 传入了 caps（this）。`);
-            }
             // 模型解析：SubAgent 可指定独立模型，否则复用父 Agent 的模型
             let subModel;
             if (def.modelId) {
-                subModel = createModel(provider.config, def.modelId);
+                subModel = createModel(provider, def.modelId);
             }
             else {
                 const parentModel = this.agent?.model;
@@ -36,12 +32,12 @@ export function createSubAgentTool(def, provider, caps) {
                 subModel = parentModel;
             }
             // SubAgent 独立解析自己的工具（排除自身，防止递归）
-            const subFiltered = caps.filter(def.permissions ?? {}, {
+            const subFiltered = provider.filter(def.permissions ?? {}, {
                 exclude: {
                     subagents: def.function?.name ? [def.function.name] : undefined,
                 },
             });
-            const tools = caps.instantiate(subFiltered);
+            const tools = provider.instantiate(subFiltered);
             const subAgent = new Agent({
                 model: subModel,
                 tools,

package/dist/config/ConfigManager.d.ts

@@ -9,17 +9,17 @@ export declare class ConfigManager {
     /**
      * 读取配置。文件不存在时返回出厂默认配置。
      */
-    read(): AppConfig;
-    write(config: AppConfig): void;
+    read(): Promise<AppConfig>;
+    write(config: AppConfig): Promise<void>;
     /**
      * 确保基础目录结构存在。
      * 创建 basePath 及所有标准共享子目录（agents/、sub-agents/、skills/ 等）。
      */
-    ensureDirs(): void;
+    ensureDirs(): Promise<void>;
     /**
      * 确保 config.json 存在。不存在时写入出厂默认配置 DSL。
      */
-    ensureDefaultConfig(): AppConfig;
+    ensureDefaultConfig(): Promise<AppConfig>;
     /**
      * 确保 basePath/agents/default.json 存在。
      *
@@ -27,7 +27,7 @@ export declare class ConfigManager {
      * - agents/ 为空 → 写入默认 Agent
      * - 已有其他 Agent → 返回 null
      */
-    ensureDefaultAgent(): AgentDefinition | null;
+    ensureDefaultAgent(): Promise<AgentDefinition | null>;
     /**
      * 确保 basePath/sub-agents/{DEFAULT_SUBAGENT_ID}.json 存在。
      *
@@ -35,15 +35,15 @@ export declare class ConfigManager {
      * - sub-agents/ 为空 → 写入默认通用助手 SubAgent
      * - 已有其他 SubAgent → 返回 null
      */
-    ensureDefaultSubAgent(): AgentDefinition | null;
+    ensureDefaultSubAgent(): Promise<AgentDefinition | null>;
     /**
      * 一键初始化：目录 + config.json + 默认 Agent + 默认 SubAgent。
      * 已有文件不会被覆盖。
      */
-    bootstrap(): {
+    bootstrap(): Promise<{
         config: AppConfig;
         agent: AgentDefinition | null;
         subAgent: AgentDefinition | null;
-    };
+    }>;
 }
 export { DEFAULT_AGENT_ID, DEFAULT_AGENT_DEFINITION, DEFAULT_SUBAGENT_ID, DEFAULT_SUBAGENT_DEFINITION, DEFAULT_APP_CONFIG, CONFIG_SUB_DIRS, } from "./constants.js";