@ai-zen/agents-sdk 0.3.1 → 0.3.2

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # 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
 
 ### 💥 破坏性变更

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，请联系用户添加）";
 /**
@@ -44,7 +44,7 @@ export function createLoadSkillTool(skillDirs, filteredSkills) {
             // 扫描 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}`;

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";

package/dist/config/ConfigManager.js

@@ -1,4 +1,4 @@
-import { readFileSync, writeFileSync, existsSync, renameSync, mkdirSync, readdirSync } from "node:fs";
+import { promises as fs } from "node:fs";
 import { dirname, join } from "node:path";
 import { DEFAULT_AGENT_ID, DEFAULT_AGENT_DEFINITION, DEFAULT_SUBAGENT_ID, DEFAULT_SUBAGENT_DEFINITION, DEFAULT_APP_CONFIG, CONFIG_SUB_DIRS, } from "./constants.js";
 /**
@@ -17,21 +17,27 @@ export class ConfigManager {
     /**
      * 读取配置。文件不存在时返回出厂默认配置。
      */
-    read() {
-        if (!existsSync(this.configPath)) {
+    async read() {
+        try {
+            await fs.access(this.configPath);
+        }
+        catch {
             return { ...DEFAULT_APP_CONFIG };
         }
-        const raw = readFileSync(this.configPath, "utf-8");
+        const raw = await fs.readFile(this.configPath, "utf-8");
         return JSON.parse(raw);
     }
-    write(config) {
+    async write(config) {
         const dir = dirname(this.configPath);
-        if (!existsSync(dir)) {
-            mkdirSync(dir, { recursive: true });
+        try {
+            await fs.access(dir);
+        }
+        catch {
+            await fs.mkdir(dir, { recursive: true });
         }
         const tmpPath = this.configPath + ".tmp";
-        writeFileSync(tmpPath, JSON.stringify(config, null, 2), "utf-8");
-        renameSync(tmpPath, this.configPath);
+        await fs.writeFile(tmpPath, JSON.stringify(config, null, 2), "utf-8");
+        await fs.rename(tmpPath, this.configPath);
     }
     // -----------------------------------------------------------------------
     // 目录 & 默认实体
@@ -40,22 +46,25 @@ export class ConfigManager {
      * 确保基础目录结构存在。
      * 创建 basePath 及所有标准共享子目录（agents/、sub-agents/、skills/ 等）。
      */
-    ensureDirs() {
-        mkdirSync(this.basePath, { recursive: true });
+    async ensureDirs() {
+        await fs.mkdir(this.basePath, { recursive: true });
         for (const dir of CONFIG_SUB_DIRS) {
-            mkdirSync(join(this.basePath, dir), { recursive: true });
+            await fs.mkdir(join(this.basePath, dir), { recursive: true });
         }
     }
     /**
      * 确保 config.json 存在。不存在时写入出厂默认配置 DSL。
      */
-    ensureDefaultConfig() {
-        if (existsSync(this.configPath)) {
-            return this.read();
+    async ensureDefaultConfig() {
+        try {
+            await fs.access(this.configPath);
+            return await this.read();
+        }
+        catch {
+            await this.ensureDirs();
+            await this.write(DEFAULT_APP_CONFIG);
+            return { ...DEFAULT_APP_CONFIG };
         }
-        this.ensureDirs();
-        this.write(DEFAULT_APP_CONFIG);
-        return { ...DEFAULT_APP_CONFIG };
     }
     /**
      * 确保 basePath/agents/default.json 存在。
@@ -64,14 +73,25 @@ export class ConfigManager {
      * - agents/ 为空 → 写入默认 Agent
      * - 已有其他 Agent → 返回 null
      */
-    ensureDefaultAgent() {
+    async ensureDefaultAgent() {
         const agentsDir = join(this.basePath, "agents");
         const defaultPath = join(agentsDir, `${DEFAULT_AGENT_ID}.json`);
-        if (existsSync(defaultPath)) {
-            return JSON.parse(readFileSync(defaultPath, "utf-8"));
+        try {
+            await fs.access(defaultPath);
+            return JSON.parse(await fs.readFile(defaultPath, "utf-8"));
+        }
+        catch {
+            // default.json 不存在，继续
+        }
+        await fs.mkdir(agentsDir, { recursive: true });
+        let existing;
+        try {
+            const allFiles = await fs.readdir(agentsDir);
+            existing = allFiles.filter((f) => f.endsWith(".json"));
+        }
+        catch {
+            existing = [];
         }
-        mkdirSync(agentsDir, { recursive: true });
-        const existing = readdirSync(agentsDir).filter((f) => f.endsWith(".json"));
         if (existing.length > 0) {
             return null;
         }
@@ -81,7 +101,7 @@ export class ConfigManager {
             createdAt: now,
             updatedAt: now,
         };
-        writeFileSync(defaultPath, JSON.stringify(definition, null, 2), "utf-8");
+        await fs.writeFile(defaultPath, JSON.stringify(definition, null, 2), "utf-8");
         return definition;
     }
     /**
@@ -91,14 +111,25 @@ export class ConfigManager {
      * - sub-agents/ 为空 → 写入默认通用助手 SubAgent
      * - 已有其他 SubAgent → 返回 null
      */
-    ensureDefaultSubAgent() {
+    async ensureDefaultSubAgent() {
         const subDir = join(this.basePath, "sub-agents");
         const defaultPath = join(subDir, `${DEFAULT_SUBAGENT_ID}.json`);
-        if (existsSync(defaultPath)) {
-            return JSON.parse(readFileSync(defaultPath, "utf-8"));
+        try {
+            await fs.access(defaultPath);
+            return JSON.parse(await fs.readFile(defaultPath, "utf-8"));
+        }
+        catch {
+            // 文件不存在，继续
+        }
+        await fs.mkdir(subDir, { recursive: true });
+        let existing;
+        try {
+            const allFiles = await fs.readdir(subDir);
+            existing = allFiles.filter((f) => f.endsWith(".json"));
+        }
+        catch {
+            existing = [];
         }
-        mkdirSync(subDir, { recursive: true });
-        const existing = readdirSync(subDir).filter((f) => f.endsWith(".json"));
         if (existing.length > 0) {
             return null;
         }
@@ -108,18 +139,18 @@ export class ConfigManager {
             createdAt: now,
             updatedAt: now,
         };
-        writeFileSync(defaultPath, JSON.stringify(definition, null, 2), "utf-8");
+        await fs.writeFile(defaultPath, JSON.stringify(definition, null, 2), "utf-8");
         return definition;
     }
     /**
      * 一键初始化：目录 + config.json + 默认 Agent + 默认 SubAgent。
      * 已有文件不会被覆盖。
      */
-    bootstrap() {
-        this.ensureDirs();
-        const config = this.ensureDefaultConfig();
-        const agent = this.ensureDefaultAgent();
-        const subAgent = this.ensureDefaultSubAgent();
+    async bootstrap() {
+        await this.ensureDirs();
+        const config = await this.ensureDefaultConfig();
+        const agent = await this.ensureDefaultAgent();
+        const subAgent = await this.ensureDefaultSubAgent();
         return { config, agent, subAgent };
     }
 }

package/dist/crud/DraftRepository.d.ts

@@ -9,7 +9,7 @@ export declare class DraftRepository {
     private dir;
     constructor(dir: string);
     private path;
-    read(conversationId?: string): Draft | null;
-    write(draft: Draft): void;
-    delete(conversationId?: string): void;
+    read(conversationId?: string): Promise<Draft | null>;
+    write(draft: Draft): Promise<void>;
+    delete(conversationId?: string): Promise<void>;
 }

package/dist/crud/DraftRepository.js

@@ -1,4 +1,4 @@
-import { readFileSync, writeFileSync, existsSync, unlinkSync, mkdirSync } from "node:fs";
+import { promises as fs } from "node:fs";
 import { join } from "node:path";
 const CURRENT_DRAFT = "_current.json";
 /**
@@ -15,27 +15,38 @@ export class DraftRepository {
     path(conversationId) {
         return join(this.dir, conversationId ? `${conversationId}.json` : CURRENT_DRAFT);
     }
-    read(conversationId) {
+    async read(conversationId) {
         const p = this.path(conversationId);
-        if (!existsSync(p))
+        try {
+            await fs.access(p);
+        }
+        catch {
             return null;
+        }
         try {
-            return JSON.parse(readFileSync(p, "utf-8"));
+            return JSON.parse(await fs.readFile(p, "utf-8"));
         }
         catch {
             return null;
         }
     }
-    write(draft) {
-        if (!existsSync(this.dir)) {
-            mkdirSync(this.dir, { recursive: true });
+    async write(draft) {
+        try {
+            await fs.access(this.dir);
         }
-        writeFileSync(this.path(draft.conversationId), JSON.stringify(draft, null, 2), "utf-8");
+        catch {
+            await fs.mkdir(this.dir, { recursive: true });
+        }
+        await fs.writeFile(this.path(draft.conversationId), JSON.stringify(draft, null, 2), "utf-8");
     }
-    delete(conversationId) {
+    async delete(conversationId) {
         const p = this.path(conversationId);
-        if (existsSync(p)) {
-            unlinkSync(p);
+        try {
+            await fs.access(p);
+            await fs.unlink(p);
+        }
+        catch {
+            // 文件不存在，忽略
         }
     }
 }

package/dist/plugin/AutoDraftPlugin.d.ts

@@ -22,5 +22,5 @@ export declare class AutoDraftPlugin implements AgentPlugin {
     private options;
     constructor(options: AutoDraftOptions);
     onInnerLoopEnd(ctx: SendContext): Promise<void>;
-    static checkDraftForRestore(draftsDir: string): Draft | null;
+    static checkDraftForRestore(draftsDir: string): Promise<Draft | null>;
 }

package/dist/plugin/AutoDraftPlugin.js

@@ -1,6 +1,6 @@
 import { DraftRepository } from "../crud/DraftRepository.js";
 import { createLogger } from "../shared/logger.js";
-import { existsSync } from "node:fs";
+import { promises as fs } from "node:fs";
 import { join } from "node:path";
 import dayjs from "dayjs";
 const log = createLogger();
@@ -34,23 +34,27 @@ export class AutoDraftPlugin {
                 updatedAt: new Date().toISOString(),
             };
             const repo = new DraftRepository(draftsDir);
-            repo.write(draft);
+            await repo.write(draft);
         }
         catch (err) {
             log.error(`[autoDraft] 保存失败: ${err?.message ?? err}`);
         }
     }
-    static checkDraftForRestore(draftsDir) {
+    static async checkDraftForRestore(draftsDir) {
         const path = join(draftsDir, CURRENT_DRAFT);
-        if (!existsSync(path))
+        try {
+            await fs.access(path);
+        }
+        catch {
             return null;
+        }
         const repo = new DraftRepository(draftsDir);
-        const draft = repo.read();
+        const draft = await repo.read();
         if (!draft)
             return null;
         const age = dayjs().diff(dayjs(draft.updatedAt), "day");
         if (age > EXPIRE_DAYS) {
-            repo.delete();
+            await repo.delete();
             return null;
         }
         return draft;

package/dist/runtime/createAgent.d.ts

@@ -1,7 +1,7 @@
 import { SdkAgent } from "./SdkAgent.js";
 import type { Provider } from "./Provider.js";
 /**
- * 从磁盘创建 Agent（异步）。
+ * 从磁盘创建 Agent。
  *
  * 通过 Provider 获取已发现的能力，读取 Agent 定义，过滤并实例化工具，产出 SdkAgent。
  *

package/dist/runtime/createAgent.js

@@ -2,7 +2,7 @@ import { AgentRepository } from "../crud/AgentRepository.js";
 import { SdkAgent } from "./SdkAgent.js";
 import { createModel } from "./createModel.js";
 /**
- * 从磁盘创建 Agent（异步）。
+ * 从磁盘创建 Agent。
  *
  * 通过 Provider 获取已发现的能力，读取 Agent 定义，过滤并实例化工具，产出 SdkAgent。
  *
@@ -12,7 +12,7 @@ import { createModel } from "./createModel.js";
  * ```
  */
 export async function createAgent(provider, agentId) {
-    const definition = new AgentRepository(provider.agentsDir).read(agentId);
+    const definition = await new AgentRepository(provider.agentsDir).read(agentId);
     if (!definition)
         throw new Error(`Agent "${agentId}" 不存在`);
     const modelId = definition.modelId ?? provider.config.defaultModel;

package/dist/shared/EntityRepository.d.ts

@@ -14,11 +14,11 @@ export declare class EntityRepository<T extends {
     /** 获取实体的文件路径 */
     protected path(id: string): string;
     /** 列出目录下所有实体（跳过解析失败的文件） */
-    list(): T[];
+    list(): Promise<T[]>;
     /** 读取单个实体，不存在返回 null */
-    read(id: string): T | null;
+    read(id: string): Promise<T | null>;
     /** 写入实体（创建或更新） */
-    write(entity: T): void;
+    write(entity: T): Promise<void>;
     /** 删除实体，不存在时不抛异常 */
-    delete(id: string): void;
+    delete(id: string): Promise<void>;
 }

package/dist/shared/EntityRepository.js

@@ -1,4 +1,4 @@
-import { readFileSync, writeFileSync, existsSync, unlinkSync, readdirSync, mkdirSync } from "node:fs";
+import { promises as fs } from "node:fs";
 import { join } from "node:path";
 /**
  * 通用实体仓储 — 对磁盘 JSON 文件的 CRUD 操作。
@@ -18,27 +18,36 @@ export class EntityRepository {
         return join(this.dir, `${id}.json`);
     }
     /** 列出目录下所有实体（跳过解析失败的文件） */
-    list() {
-        if (!existsSync(this.dir))
+    async list() {
+        try {
+            await fs.access(this.dir);
+        }
+        catch {
             return [];
-        const ids = readdirSync(this.dir)
+        }
+        const entries = await fs.readdir(this.dir);
+        const ids = entries
             .filter((f) => f.endsWith(".json"))
             .map((f) => f.replace(/\.json$/, ""));
         const entities = [];
         for (const id of ids) {
-            const entity = this.read(id);
+            const entity = await this.read(id);
             if (entity)
                 entities.push(entity);
         }
         return entities;
     }
     /** 读取单个实体，不存在返回 null */
-    read(id) {
+    async read(id) {
         const p = this.path(id);
-        if (!existsSync(p))
+        try {
+            await fs.access(p);
+        }
+        catch {
             return null;
+        }
         try {
-            const raw = readFileSync(p, "utf-8");
+            const raw = await fs.readFile(p, "utf-8");
             return JSON.parse(raw);
         }
         catch {
@@ -46,17 +55,24 @@ export class EntityRepository {
         }
     }
     /** 写入实体（创建或更新） */
-    write(entity) {
-        if (!existsSync(this.dir)) {
-            mkdirSync(this.dir, { recursive: true });
+    async write(entity) {
+        try {
+            await fs.access(this.dir);
+        }
+        catch {
+            await fs.mkdir(this.dir, { recursive: true });
         }
-        writeFileSync(this.path(entity.id), JSON.stringify(entity, null, 2), "utf-8");
+        await fs.writeFile(this.path(entity.id), JSON.stringify(entity, null, 2), "utf-8");
     }
     /** 删除实体，不存在时不抛异常 */
-    delete(id) {
+    async delete(id) {
         const p = this.path(id);
-        if (existsSync(p)) {
-            unlinkSync(p);
+        try {
+            await fs.access(p);
+            await fs.unlink(p);
+        }
+        catch {
+            // 文件不存在，忽略
         }
     }
 }

package/package.json

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