@ai-zen/agents-sdk 0.2.8 → 0.3.2

package/dist/runtime/Provider.js

@@ -1,14 +1,35 @@
 import { McpConnectionManager } from "./McpConnectionManager.js";
+import { PermissionEvaluator } from "../capabilities/PermissionEvaluator.js";
+import { createLoadSkillTool, createCallSkillSubAgentTool } from "../capabilities/implements/skillTools.js";
+import { createLoadMcpTool, createCallMcpTool, createReadMcpResourceTool } from "../capabilities/implements/mcpTools.js";
+import { createSubAgentTool } from "../capabilities/implements/subAgentTools.js";
+import { discoverBuiltinTools } from "../capabilities/discovery/builtin.js";
+import { discoverSubAgents } from "../capabilities/discovery/subagents.js";
+import { discoverSkills } from "../capabilities/discovery/skills.js";
+import { discoverMcpServers } from "../capabilities/discovery/mcp.js";
+import { discoverUserTools } from "../capabilities/discovery/usertools.js";
 /**
- * Provider — 全局上下文实例。
+ * 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 class Provider {
     /** 应用配置（端点、模型等） */
@@ -19,8 +40,16 @@ export class Provider {
     skillsPaths;
     toolsPaths;
     mcpPaths;
+    // ---- 全局候选集（发现一次，全局复用）----
+    builtinTools;
+    userTools;
+    subagents;
+    /** 完整 SkillInfo，含 subAgent 标记，可据此区分枚举 */
+    skills;
+    /** 完整 MCP 服务器配置 */
+    mcps;
     // ---- MCP ----
-    _mcpManager;
+    mcpManager;
     constructor(options) {
         this.config = options.config;
         this.agentsDir = options.agentsDir;
@@ -28,15 +57,146 @@ export class Provider {
         this.skillsPaths = options.skillsPaths ?? [];
         this.toolsPaths = options.toolsPaths ?? [];
         this.mcpPaths = options.mcpPaths ?? [];
+        this.builtinTools = [];
+        this.userTools = [];
+        this.subagents = [];
+        this.skills = [];
+        this.mcps = [];
+        this.mcpManager = this.mcpPaths.length > 0 ? new McpConnectionManager() : undefined;
+    }
+    /**
+     * 异步创建 Provider，一步完成构造 + 全局能力发现。
+     */
+    static async create(options) {
+        const provider = new Provider(options);
+        await provider.init();
+        return provider;
+    }
+    /**
+     * 初始化：执行全局能力发现。
+     */
+    async init() {
+        await this.refresh();
+    }
+    // ==================================================================
+    // 能力过滤与实例化
+    // ==================================================================
+    /**
+     * 按权限过滤候选集，返回过滤后的名称列表。
+     * 纯名称操作（安全预过滤 + 权限过滤），不涉及 Tool 实例化。
+     */
+    filter(permissions, options) {
+        const exclude = options?.exclude ?? {};
+        const excludeTools = new Set(exclude.tools ?? []);
+        const excludeSkills = new Set(exclude.skills ?? []);
+        const excludeMcps = new Set(exclude.mcps ?? []);
+        const excludeSubAgents = new Set(exclude.subagents ?? []);
+        const safeSubagents = excludeSubAgents.size === 0
+            ? this.subagents
+            : this.subagents.filter((def) => !excludeSubAgents.has(def.function?.name ?? ""));
+        const DYNAMIC_TOOL_NAMES = [
+            "load_skill",
+            "call_skill_sub_agent",
+            "load_mcp",
+            "call_mcp_tool",
+            "read_mcp_resource",
+        ];
+        const toolNames = [
+            ...this.builtinTools.map((t) => t.function.name),
+            ...this.userTools.map((t) => t.function.name),
+            ...DYNAMIC_TOOL_NAMES,
+        ].filter((name) => !excludeTools.has(name));
+        const evaluator = new PermissionEvaluator(permissions);
+        const filtered = evaluator.filter({
+            tools: toolNames,
+            skills: this.skills
+                .filter((s) => !excludeSkills.has(s.id))
+                .map((s) => s.id),
+            mcps: this.mcps
+                .filter((m) => !excludeMcps.has(m.id))
+                .map((m) => m.id),
+            subagents: safeSubagents.map((d) => d.function.name),
+        });
+        return {
+            tools: filtered.tools,
+            subagents: filtered.subagents,
+            skills: filtered.skills,
+            mcps: filtered.mcps,
+        };
+    }
+    /**
+     * 快捷方法：filter + instantiate 一步完成。
+     */
+    buildTools(permissions, options) {
+        return this.instantiate(this.filter(permissions, options));
     }
     /**
-     * 获取 McpConnectionManager，有 mcpPaths 时延迟创建。
-     * 首次访问时创建，后续复用同一实例。
+     * 将过滤后的名称列表实例化为 Tool 数组。
      */
-    getMcpManager() {
-        if (!this._mcpManager && this.mcpPaths.length > 0) {
-            this._mcpManager = new McpConnectionManager();
+    instantiate(filtered) {
+        const result = [];
+        const allowedToolNames = new Set(filtered.tools);
+        // 1. 内置 + 用户工具
+        for (const t of [...this.builtinTools, ...this.userTools]) {
+            if (allowedToolNames.has(t.function.name)) {
+                result.push(t);
+            }
+        }
+        // 2. 筛选候选项（保留完整信息，传给工具函数自行决定如何构建枚举）
+        const allowedSkillSet = new Set(filtered.skills);
+        const allowedMcpSet = new Set(filtered.mcps);
+        const filteredSkills = this.skills.filter((s) => allowedSkillSet.has(s.id));
+        const filteredMcps = this.mcps.filter((m) => allowedMcpSet.has(m.id));
+        // 3. 动态工具
+        if (allowedToolNames.has("load_skill") && filteredSkills.length > 0) {
+            result.push(createLoadSkillTool(this.skillsPaths, filteredSkills));
+        }
+        // call_skill_sub_agent：只要有支持子 Agent 的 skill 就注册
+        const hasSubAgentSkills = filteredSkills.some((s) => s.subAgent);
+        if (allowedToolNames.has("call_skill_sub_agent") && hasSubAgentSkills) {
+            result.push(createCallSkillSubAgentTool(this.skillsPaths, filteredSkills, this));
+        }
+        const mcpManager = this.mcpManager;
+        if (allowedToolNames.has("load_mcp") && mcpManager && filteredMcps.length > 0) {
+            result.push(createLoadMcpTool(mcpManager, filteredMcps));
+        }
+        if (allowedToolNames.has("call_mcp_tool") && mcpManager) {
+            result.push(createCallMcpTool(mcpManager));
+        }
+        if (allowedToolNames.has("read_mcp_resource") && mcpManager) {
+            result.push(createReadMcpResourceTool(mcpManager));
+        }
+        // 4. SubAgent
+        const allowedSubagentSet = new Set(filtered.subagents);
+        for (const def of this.subagents) {
+            if (!def.function || !allowedSubagentSet.has(def.function.name))
+                continue;
+            result.push(createSubAgentTool(def, this));
+        }
+        // 5. 去重
+        return dedupTools(result);
+    }
+    /**
+     * 重新执行全局发现（重新扫描文件系统）。
+     */
+    async refresh(options) {
+        const silent = options?.silent ?? false;
+        this.builtinTools = discoverBuiltinTools(this.config);
+        this.userTools = await discoverUserTools(this.toolsPaths, { silent });
+        this.subagents = await discoverSubAgents(this.subAgentsPaths);
+        this.skills = await discoverSkills(this.skillsPaths, { silent });
+        this.mcps = await discoverMcpServers(this.mcpPaths);
+    }
+}
+function dedupTools(tools) {
+    const seen = new Set();
+    const result = [];
+    for (let i = tools.length - 1; i >= 0; i--) {
+        const name = tools[i].function.name;
+        if (!seen.has(name)) {
+            seen.add(name);
+            result.unshift(tools[i]);
         }
-        return this._mcpManager;
     }
+    return result;
 }

package/dist/runtime/SdkAgent.d.ts

@@ -1,7 +1,6 @@
 import { Agent, type ChatCompletionModel } from "@ai-zen/agents-core";
-import type { AgentNS, Tool } from "@ai-zen/agents-core";
+import type { AgentNS, Tool, UnknownToolContext } from "@ai-zen/agents-core";
 import type { AgentDefinition, AgentPermissions } from "../types/index.js";
-import type { Capabilities } from "../capabilities/Capabilities.js";
 import type { Provider } from "./Provider.js";
 /**
  * Agent 插件上下文：当前 SdkAgent + 发送内容 + 消息列表。
@@ -50,7 +49,6 @@ export interface AgentPlugin {
  *   - provider：全局 Provider 实例
  *   - definition：Agent 原始定义
  *   - permissions：Agent 权限，供 call_skill_sub_agent 等回调读取
- *   - caps：Capabilities 全局注册表，供 refreshTools 刷新工具列表
  *
  * 插件能力：
  *   - use(plugin)：注册插件
@@ -64,8 +62,13 @@ export declare class SdkAgent extends Agent {
     readonly definition: AgentDefinition;
     /** Agent 权限 */
     readonly permissions?: AgentPermissions;
-    /** Capabilities 全局注册表，用于运行时刷新工具列表 */
-    readonly caps?: Capabilities;
+    /**
+     * 当 LLM 调用不存在的工具时，给出智能提示。
+     * 如果有 MCP 配置但 call_mcp_tool 不在工具列表中（权限禁用），提示权限问题；
+     * 如果有 MCP 配置且 call_mcp_tool 可用，提示使用 call_mcp_tool；
+     * 否则仅提示工具不存在。
+     */
+    onUnknownTool: (ctx: UnknownToolContext) => string;
     /** 已注册的插件列表 */
     private _plugins;
     constructor(params: {
@@ -76,7 +79,6 @@ export declare class SdkAgent extends Agent {
         messages?: AgentNS.Message[];
         tools?: Tool[];
         permissions?: AgentPermissions;
-        caps?: Capabilities;
         rag?: any;
         allowJsonParseError?: boolean;
     });

package/dist/runtime/SdkAgent.js

@@ -13,7 +13,6 @@ import { Agent } from "@ai-zen/agents-core";
  *   - provider：全局 Provider 实例
  *   - definition：Agent 原始定义
  *   - permissions：Agent 权限，供 call_skill_sub_agent 等回调读取
- *   - caps：Capabilities 全局注册表，供 refreshTools 刷新工具列表
  *
  * 插件能力：
  *   - use(plugin)：注册插件
@@ -27,8 +26,24 @@ export class SdkAgent extends Agent {
     definition;
     /** Agent 权限 */
     permissions;
-    /** Capabilities 全局注册表，用于运行时刷新工具列表 */
-    caps;
+    /**
+     * 当 LLM 调用不存在的工具时，给出智能提示。
+     * 如果有 MCP 配置但 call_mcp_tool 不在工具列表中（权限禁用），提示权限问题；
+     * 如果有 MCP 配置且 call_mcp_tool 可用，提示使用 call_mcp_tool；
+     * 否则仅提示工具不存在。
+     */
+    onUnknownTool = (ctx) => {
+        const toolName = ctx.toolCall.function?.name ?? "未知";
+        const hasMcpConfig = this.provider.mcpPaths.length > 0;
+        const hasCallMcpTool = (this.tools ?? []).some((t) => t.function.name === "call_mcp_tool");
+        if (hasMcpConfig && !hasCallMcpTool) {
+            return `工具 "${toolName}" 不存在。当前有 MCP 服务器配置，但 call_mcp_tool 权限已被禁用，如需使用 MCP 工具请调整权限。`;
+        }
+        if (hasMcpConfig && hasCallMcpTool) {
+            return `工具 "${toolName}" 不存在。如果要调用 MCP 工具，请使用 call_mcp_tool。`;
+        }
+        return `工具 "${toolName}" 不存在。`;
+    };
     /** 已注册的插件列表 */
     _plugins = [];
     constructor(params) {
@@ -43,7 +58,6 @@ export class SdkAgent extends Agent {
         this.provider = params.provider;
         this.definition = params.definition;
         this.permissions = params.permissions;
-        this.caps = params.caps;
     }
     /**
      * 注册一个插件。

package/dist/runtime/createAgent.d.ts

@@ -1,14 +1,13 @@
 import { SdkAgent } from "./SdkAgent.js";
 import type { Provider } from "./Provider.js";
 /**
- * 从磁盘创建 Agent（同步）。
+ * 从磁盘创建 Agent。
  *
- * 内部创建 Capabilities 实例执行全局发现，读取 Agent 定义，
- * 过滤并实例化工具，产出 SdkAgent。
+ * 通过 Provider 获取已发现的能力，读取 Agent 定义，过滤并实例化工具，产出 SdkAgent。
  *
  * ```ts
- * const agent = createAgent(runtime, "my-agent");
+ * const agent = await createAgent(provider, "my-agent");
  * // agent 是 SdkAgent，可直接注册插件、发送消息
  * ```
  */
-export declare function createAgent(provider: Provider, agentId: string): SdkAgent;
+export declare function createAgent(provider: Provider, agentId: string): Promise<SdkAgent>;

package/dist/runtime/createAgent.js

@@ -1,28 +1,25 @@
 import { AgentRepository } from "../crud/AgentRepository.js";
-import { Capabilities } from "../capabilities/Capabilities.js";
 import { SdkAgent } from "./SdkAgent.js";
 import { createModel } from "./createModel.js";
 /**
- * 从磁盘创建 Agent（同步）。
+ * 从磁盘创建 Agent。
  *
- * 内部创建 Capabilities 实例执行全局发现，读取 Agent 定义，
- * 过滤并实例化工具，产出 SdkAgent。
+ * 通过 Provider 获取已发现的能力，读取 Agent 定义，过滤并实例化工具，产出 SdkAgent。
  *
  * ```ts
- * const agent = createAgent(runtime, "my-agent");
+ * const agent = await createAgent(provider, "my-agent");
  * // agent 是 SdkAgent，可直接注册插件、发送消息
  * ```
  */
-export function createAgent(provider, agentId) {
-    const caps = new Capabilities(provider);
-    const definition = new AgentRepository(provider.agentsDir).read(agentId);
+export async function createAgent(provider, agentId) {
+    const definition = await new AgentRepository(provider.agentsDir).read(agentId);
     if (!definition)
         throw new Error(`Agent "${agentId}" 不存在`);
     const modelId = definition.modelId ?? provider.config.defaultModel;
     if (!modelId)
         throw new Error("未指定模型且无默认模型");
-    const model = createModel(provider.config, modelId);
-    const tools = caps.buildTools(definition.permissions ?? {}, {
+    const model = createModel(provider, modelId);
+    const tools = provider.buildTools(definition.permissions ?? {}, {
         exclude: {
             subagents: definition.function?.name
                 ? [definition.function.name]
@@ -36,20 +33,6 @@ export function createAgent(provider, agentId) {
         messages: definition.messages,
         tools,
         permissions: definition.permissions,
-        caps,
     });
-    // 设置 onUnknownTool 钩子：当 LLM 调用不存在的工具时，给出智能提示
-    agent.onUnknownTool = (ctx) => {
-        const toolName = ctx.toolCall.function?.name ?? "未知";
-        const hasMcpConfig = provider.mcpPaths.length > 0;
-        const hasCallMcpTool = tools.some((t) => t.function.name === "call_mcp_tool");
-        if (hasMcpConfig && !hasCallMcpTool) {
-            return `工具 "${toolName}" 不存在。当前有 MCP 服务器配置，但 call_mcp_tool 权限已被禁用，如需使用 MCP 工具请调整权限。`;
-        }
-        if (hasMcpConfig && hasCallMcpTool) {
-            return `工具 "${toolName}" 不存在。如果要调用 MCP 工具，请使用 call_mcp_tool。`;
-        }
-        return `工具 "${toolName}" 不存在。`;
-    };
     return agent;
 }

package/dist/runtime/createModel.d.ts

@@ -1,11 +1,8 @@
 import type { ChatCompletionModel } from "@ai-zen/agents-core";
-import type { AppConfig } from "../types/index.js";
+import type { Provider } from "./Provider.js";
 /**
- * 模型工厂 — 根据 modelId 和 config 构建 Core ChatCompletionModel。
+ * 模型工厂 — 根据 modelId 和 Provider 构建 Core ChatCompletionModel。
  *
- * 属于独立的 runtime 子层，不依赖 capabilities/ 或其他模块。
- * 通过 Provider 实例获取 AppConfig 后调用。
- *
- * 改为同步版本，使用 endp​oint.chatCompletionSync() 避免不必要的 async。
+ * 同步版本，使用 endp​oint.chatCompletionSync() 避免不必要的 async。
  */
-export declare function createModel(config: AppConfig, modelId: string): ChatCompletionModel;
+export declare function createModel(provider: Provider, modelId: string): ChatCompletionModel;

package/dist/runtime/createModel.js

@@ -1,13 +1,11 @@
 import { OpenAI, ChatGPT } from "@ai-zen/agents-core";
 /**
- * 模型工厂 — 根据 modelId 和 config 构建 Core ChatCompletionModel。
+ * 模型工厂 — 根据 modelId 和 Provider 构建 Core ChatCompletionModel。
  *
- * 属于独立的 runtime 子层，不依赖 capabilities/ 或其他模块。
- * 通过 Provider 实例获取 AppConfig 后调用。
- *
- * 改为同步版本，使用 endp​oint.chatCompletionSync() 避免不必要的 async。
+ * 同步版本，使用 endp​oint.chatCompletionSync() 避免不必要的 async。
  */
-export function createModel(config, modelId) {
+export function createModel(provider, modelId) {
+    const config = provider.config;
     const modelConfig = config.models.find((m) => m.id === modelId);
     if (!modelConfig)
         throw new Error(`模型 "${modelId}" 不存在`);

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.2.8",
+  "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",
@@ -18,7 +18,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dayjs": "^1.11.21",
-    "@ai-zen/agents-core": "3.0.0-alpha.4"
+    "@ai-zen/agents-core": "3.0.1"
   },
   "devDependencies": {
     "@types/node": "^24.12.2",

package/dist/capabilities/Capabilities.d.ts

@@ -1,73 +0,0 @@
-import type { Tool } from "@ai-zen/agents-core";
-import type { AgentDefinition, AgentPermissions, McpServerConfig } from "../types/index.js";
-import type { SkillInfo } from "./discovery/skills.js";
-import type { Provider } from "../runtime/Provider.js";
-/**
- * 能力过滤系统的公共类型。
- * FilterOutput 由 Capabilities.filter() 产出，由 Capabilities.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[];
-}
-/**
- * Capabilities — 全局能力注册表。
- *
- * 职责：
- *   1. 全局发现一次（扫描文件系统，收集所有完整候选）
- *   2. 提供 filter(permissions) 按权限过滤
- *   3. 提供 instantiate(filterOutput) 将过滤后的名称实例化为 Tool[]
- *
- * 设计原则：
- *   - 发现结果全局共享，SubAgent 复用同一份候选集
- *   - filter 是纯函数（名称匹配），可被任意 Agent 独立调用
- *   - instantiate 是纯映射（名称→实例），不含业务逻辑
- *   - 通过持有的 Provider 实例获取配置、路径、模型工厂等全局服务
- */
-export declare class Capabilities {
-    /** Provider 全局上下文 */
-    readonly provider: Provider;
-    builtinInstances: Tool[];
-    userInstances: Tool[];
-    subagentDefs: AgentDefinition[];
-    /** 完整 SkillInfo，含 subAgent 标记，可据此区分枚举 */
-    skills: SkillInfo[];
-    /** 完整 MCP 服务器配置 */
-    mcps: McpServerConfig[];
-    constructor(provider: Provider);
-    /**
-     * 按权限过滤候选集，返回过滤后的名称列表。
-     * 纯名称操作（安全预过滤 + 权限过滤），不涉及 Tool 实例化。
-     */
-    filter(permissions: AgentPermissions, options?: {
-        exclude?: ExcludeOptions;
-    }): FilterOutput;
-    /**
-     * 快捷方法：filter + instantiate 一步完成。
-     */
-    buildTools(permissions: AgentPermissions, options?: {
-        exclude?: ExcludeOptions;
-    }): Tool[];
-    /**
-     * 将过滤后的名称列表实例化为 Tool 数组。
-     */
-    instantiate(filtered: FilterOutput): Tool[];
-    /**
-     * 重新执行全局发现（重新扫描文件系统）。
-     */
-    refresh(options?: {
-        silent?: boolean;
-    }): void;
-}