@ai-zen/agents-sdk 0.2.8 → 0.3.2

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

@@ -12,7 +12,13 @@ export const DEFAULT_AGENT_DEFINITION = {
     messages: [
         {
             role: AgentNS.Role.System,
-            content: "你是一个AI助手，专门帮助用户回答问题和执行任务。请用中文回复。",
+            content: `你是一个严谨可靠的智能助手。请用中文回复，说话风格参照官方文件。
+
+- 开动脑筋 — 主动思考、灵活运用工具，而不是机械执行
+- 实事求是 — 知之为知之，不知为不知，而不是凭空编造
+- 一切行动听指挥 — 严格遵循用户指令，而不是自作主张
+- 安全第一 — 风险操作先告知确认，而不是盲目执行
+- 能打胜仗 — 写优秀的代码，而不是只限于能用的代码`,
         },
     ],
     permissions: {
@@ -47,11 +53,11 @@ export const DEFAULT_SUBAGENT_DEFINITION = {
     },
     function: {
         name: "sub_agent_default",
-        description: "通用子 Agent，可独立完成各类任务。将任务委派给它后，它会自主调用自身工具（文件读写、代码执行、搜索等）来完成任务并返回结果。适合处理需要多步骤执行、工具调用的复杂任务。",
+        description: "通用子 Agent，可独立完成各类任务。委派任务时必须提供完整的任务上下文，包括所有必要的背景信息、文件路径、具体要求和约束条件，确保子 Agent 无需追问即可独立执行。",
         parameters: {
             type: "object",
             properties: {
-                task: { type: "string", description: "任务描述" },
+                task: { type: "string", description: "完整的任务描述，必须包含所有必要的背景、目标、约束条件和上下文信息" },
             },
             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/index.d.ts

@@ -1,10 +1,8 @@
 export type { PermissionPolicy, AgentPermissions, Endpoint, Model, ImageModel, AgentDefinition, Conversation, Draft, AppConfig, McpIcon, McpAnnotations, McpToolDef, McpResourceDef, McpPromptDef, McpServerManifest, McpServerConfig, McpConnectionState, } from "./types/index.js";
-export { Capabilities } from "./capabilities/Capabilities.js";
 export { PermissionEvaluator } from "./capabilities/PermissionEvaluator.js";
 export type { CandidateSets } from "./capabilities/PermissionEvaluator.js";
 export { createDisclosureParam } from "./capabilities/disclosure.js";
 export type { DisclosureParam } from "./capabilities/disclosure.js";
-export type { FilterOutput, ExcludeOptions } from "./capabilities/Capabilities.js";
 export { discoverBuiltinTools } from "./capabilities/discovery/builtin.js";
 export { discoverSubAgents } from "./capabilities/discovery/subagents.js";
 export { discoverSkills, readSkill } from "./capabilities/discovery/skills.js";
@@ -17,6 +15,7 @@ export { AgentRepository } from "./crud/AgentRepository.js";
 export { ConversationRepository } from "./crud/ConversationRepository.js";
 export { DraftRepository } from "./crud/DraftRepository.js";
 export { Provider } from "./runtime/Provider.js";
+export type { FilterOutput, ExcludeOptions } from "./runtime/Provider.js";
 export { createModel } from "./runtime/createModel.js";
 export { SdkAgent } from "./runtime/SdkAgent.js";
 export type { AgentPlugin, SendContext } from "./runtime/SdkAgent.js";

package/dist/index.js

@@ -1,5 +1,4 @@
 // 能力管线
-export { Capabilities } from "./capabilities/Capabilities.js";
 export { PermissionEvaluator } from "./capabilities/PermissionEvaluator.js";
 export { createDisclosureParam } from "./capabilities/disclosure.js";
 // 发现

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/plugin/AutoRefreshToolsPlugin.js

@@ -9,10 +9,8 @@
 export class AutoRefreshToolsPlugin {
     async onBeforeSend(ctx) {
         const { agent } = ctx;
-        if (!agent.caps)
-            return;
-        agent.caps.refresh({ silent: true });
-        agent.tools = agent.caps.buildTools(agent.permissions ?? {}, {
+        await agent.provider.refresh({ silent: true });
+        agent.tools = agent.provider.buildTools(agent.permissions ?? {}, {
             exclude: {
                 subagents: agent.definition.function?.name
                     ? [agent.definition.function.name]

package/dist/runtime/Provider.d.ts

@@ -1,15 +1,49 @@
-import type { AppConfig } from "../types/index.js";
+import type { Tool } from "@ai-zen/agents-core";
+import type { AppConfig, AgentDefinition, AgentPermissions, McpServerConfig } from "../types/index.js";
+import type { SkillInfo } from "../capabilities/discovery/skills.js";
 import { McpConnectionManager } from "./McpConnectionManager.js";
 /**
- * Provider — 全局上下文实例。
+ * 能力过滤系统的公共类型。
+ * FilterOutput 由 filter() 产出，由 instantiate() 消费。
+ */
+export interface FilterOutput {
+    tools: string[];
+    subagents: string[];
+    skills: string[];
+    mcps: string[];
+}
+/**
+ * 排除项黑名单（优先级高于 permissions）。
+ * 与 permissions 四维对称，用于安全预过滤。
+ */
+export interface ExcludeOptions {
+    tools?: string[];
+    skills?: string[];
+    mcps?: string[];
+    subagents?: string[];
+}
+/**
+ * Provider — 全局上下文实例 + 能力注册表。
  *
- * SDK 不是一个模块工具箱（到处 import 散装函数），而是一个实例，
- * 持有所有全局状态（配置、路径、MCP 管理器等），各层通过它获取所需。
+ * Provider 是 SDK 的全局单例（按需创建），持有：
+ *   - 应用配置（端点、模型等）
+ *   - 文件系统路径（Agent 目录、Skill 目录等）
+ *   - 全局能力注册表（内置工具、用户工具、SubAgent、Skill、MCP）
+ *   - MCP 连接管理器
+ *
+ * 创建方式：
+ * ```ts
+ * // 推荐：一步完成构造 + 能力发现
+ * const provider = await Provider.create({ ... });
+ *
+ * // 仅构造（能力需后续加载）
+ * const provider = new Provider({ ... });
+ * await provider.init();
+ * ```
  *
  * 设计原则：
- *   - Provider 实例一旦创建不可变（路径、配置等不变），refresh 时创建新实例
+ *   - Provider 实例一旦创建不可变（路径、配置等不变），refresh 时重新发现能力
  *   - 各层不直接 import 散装函数，而是通过 Provider 实例获取
- *   - Provider 不关心能力的发现/过滤/实例化，那是 Capabilities 的事
  */
 export declare class Provider {
     /** 应用配置（端点、模型等） */
@@ -19,7 +53,14 @@ export declare class Provider {
     readonly skillsPaths: string[];
     readonly toolsPaths: string[];
     readonly mcpPaths: string[];
-    private _mcpManager?;
+    builtinTools: Tool[];
+    userTools: Tool[];
+    subagents: AgentDefinition[];
+    /** 完整 SkillInfo，含 subAgent 标记，可据此区分枚举 */
+    skills: SkillInfo[];
+    /** 完整 MCP 服务器配置 */
+    mcps: McpServerConfig[];
+    readonly mcpManager: McpConnectionManager | undefined;
     constructor(options: {
         config: AppConfig;
         agentsDir: string;
@@ -29,8 +70,41 @@ export declare class Provider {
         mcpPaths?: string[];
     });
     /**
-     * 获取 McpConnectionManager，有 mcpPaths 时延迟创建。
-     * 首次访问时创建，后续复用同一实例。
+     * 异步创建 Provider，一步完成构造 + 全局能力发现。
+     */
+    static create(options: {
+        config: AppConfig;
+        agentsDir: string;
+        subAgentsPaths?: string[];
+        skillsPaths?: string[];
+        toolsPaths?: string[];
+        mcpPaths?: string[];
+    }): Promise<Provider>;
+    /**
+     * 初始化：执行全局能力发现。
+     */
+    init(): Promise<void>;
+    /**
+     * 按权限过滤候选集，返回过滤后的名称列表。
+     * 纯名称操作（安全预过滤 + 权限过滤），不涉及 Tool 实例化。
+     */
+    filter(permissions: AgentPermissions, options?: {
+        exclude?: ExcludeOptions;
+    }): FilterOutput;
+    /**
+     * 快捷方法：filter + instantiate 一步完成。
+     */
+    buildTools(permissions: AgentPermissions, options?: {
+        exclude?: ExcludeOptions;
+    }): Tool[];
+    /**
+     * 将过滤后的名称列表实例化为 Tool 数组。
+     */
+    instantiate(filtered: FilterOutput): Tool[];
+    /**
+     * 重新执行全局发现（重新扫描文件系统）。
      */
-    getMcpManager(): McpConnectionManager | undefined;
+    refresh(options?: {
+        silent?: boolean;
+    }): Promise<void>;
 }