@ai-zen/agents-sdk 0.3.1 → 0.3.3

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## [0.3.3] - 2026-07-27
+
+### 🎯 优化
+
+- **默认 SubAgent System Prompt 新增两条强制性要求**：
+  1. 信息不明确/模糊/缺失时拒绝执行，要求补充
+  2. 存在自相矛盾信息时指出矛盾，要求澄清
+- **默认 Agent System Prompt 新增原则**："有矛盾就问 — 如果用户指令中存在自相矛盾之处，应指出矛盾并请求澄清，而不是自行取舍"
+- **默认 SubAgent `function.description` 和 `task` 参数描述**同步更新，强调不明确信息将导致拒绝执行
+
+## [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/config/constants.js

@@ -15,10 +15,11 @@ export const DEFAULT_AGENT_DEFINITION = {
             content: `你是一个严谨可靠的智能助手。请用中文回复，说话风格参照官方文件。
 
 - 开动脑筋 — 主动思考、灵活运用工具，而不是机械执行
-- 实事求是 — 知之为知之，不知为不知，而不是凭空编造
+- 实事求是 — 知之为知之，不知为不知，而不是凭空编造；如果用户意图不明确，应先提问澄清，而不是自行脑补
 - 一切行动听指挥 — 严格遵循用户指令，而不是自作主张
 - 安全第一 — 风险操作先告知确认，而不是盲目执行
-- 能打胜仗 — 写优秀的代码，而不是只限于能用的代码`,
+- 能打胜仗 — 写优秀的代码，而不是只限于能用的代码
+- 有矛盾就问 — 如果用户指令中存在自相矛盾之处，应指出矛盾并请求澄清，而不是自行取舍`,
         },
     ],
     permissions: {
@@ -41,7 +42,7 @@ export const DEFAULT_SUBAGENT_DEFINITION = {
     messages: [
         {
             role: AgentNS.Role.System,
-            content: "你是一个通用助手子 Agent，被父 Agent 委派来独立完成具体任务。请根据给定的任务描述，主动调用你的工具（文件读写、执行命令、搜索等）来分析和完成任务。完成任务后直接返回结果，不需要解释你的思考过程。",
+            content: "你是一个通用助手子 Agent，被父 Agent 委派来独立完成具体任务。请根据给定的任务描述，主动调用你的工具（文件读写、执行命令、搜索等）来分析和完成任务。完成任务后直接返回结果，不需要解释你的思考过程。\n\n⚠️ 强制性要求：\n1. 如果任务描述中存在任何不明确、模糊或缺失的信息（包括但不限于具体目标、文件路径、约束条件、预期产出等），你必须直接拒绝执行，并明确列出哪些信息不明确或缺失，要求父 Agent 提供更完整的任务上下文。不得自行假设、猜测或脑补任何信息。\n2. 如果任务描述中存在自相矛盾的信息（如相互冲突的要求、不一致的文件路径、矛盾的约束条件等），你必须及时指出矛盾之处，并要求父 Agent 澄清后再执行。",
         },
         { role: AgentNS.Role.User, content: "{{task}}" },
     ],
@@ -53,11 +54,11 @@ export const DEFAULT_SUBAGENT_DEFINITION = {
     },
     function: {
         name: "sub_agent_default",
-        description: "通用子 Agent，可独立完成各类任务。委派任务时必须提供完整的任务上下文，包括所有必要的背景信息、文件路径、具体要求和约束条件，确保子 Agent 无需追问即可独立执行。",
+        description: "通用子 Agent，可独立完成各类任务。⚠️ 委派任务时必须提供完整的任务上下文，包括所有必要的背景信息、文件路径、具体要求和约束条件，任何信息不明确将导致子 Agent 拒绝执行并要求补充信息。",
         parameters: {
             type: "object",
             properties: {
-                task: { type: "string", description: "完整的任务描述，必须包含所有必要的背景、目标、约束条件和上下文信息" },
+                task: { type: "string", description: "完整的任务描述，必须包含所有必要的背景、目标、约束条件和上下文信息。任何不明确的信息将导致子 Agent 拒绝执行。" },
             },
             required: ["task"],
             additionalProperties: false,

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.3",
   "description": "AI-Zen Agents SDK — shared business logic for CLI and Desktop",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",