@ai-zen/agents-sdk 0.12.0 → 1.0.0-alpha.0

package/dist/index.js

@@ -1,38 +1,45 @@
 // 能力管线
-export { PermissionEvaluator } from "./capabilities/PermissionEvaluator.js";
-export { createDisclosureParam } from "./capabilities/disclosure.js";
+export { PermissionEvaluator } from "./scope/PermissionEvaluator.js";
+export { createDisclosureParam } from "./scope/disclosure.js";
 // 发现
-export { discoverBuiltinTools } from "./capabilities/discovery/builtin.js";
-export { discoverSubAgents } from "./capabilities/discovery/subagents.js";
-export { discoverSkills, readSkill } from "./capabilities/discovery/skills.js";
-export { discoverMcpServers } from "./capabilities/discovery/mcp.js";
-export { discoverUserTools } from "./capabilities/discovery/usertools.js";
+export { discoverBuiltinTools } from "./scope/plugins/builtin/discover.js";
+export { discoverSubAgents } from "./scope/plugins/subagents/discover.js";
+export { discoverSkills, readSkill } from "./scope/plugins/skills/discover.js";
+export { discoverMcpServers } from "./scope/plugins/mcp/discover.js";
+export { discoverUserTools } from "./scope/plugins/usertools/discover.js";
+// Scope — 全局上下文 + 能力装配编排容器
+export { Scope } from "./scope/Scope.js";
+export { BuiltinToolsScopePlugin } from "./scope/plugins/builtin/BuiltinToolsScopePlugin.js";
+export { UserToolsScopePlugin } from "./scope/plugins/usertools/UserToolsScopePlugin.js";
+export { SkillsScopePlugin } from "./scope/plugins/skills/SkillsScopePlugin.js";
+export { McpScopePlugin } from "./scope/plugins/mcp/McpScopePlugin.js";
+export { SubAgentsScopePlugin } from "./scope/plugins/subagents/SubAgentsScopePlugin.js";
+export { allInOne } from "./scope/plugins/allInOne.js";
 // 配置 — ConfigManager
 export { ConfigManager, DEFAULT_AGENT_ID, DEFAULT_AGENT_DEFINITION, DEFAULT_SUBAGENT_ID, DEFAULT_SUBAGENT_DEFINITION, DEFAULT_APP_CONFIG, DEFAULT_MCP_CONFIG, CONFIG_SUB_DIRS, } from "./config/ConfigManager.js";
 // CRUD — 实体仓储（仅 Agent 定义等能力实体）
 export { EntityRepository } from "./shared/EntityRepository.js";
 export { AgentRepository } from "./crud/AgentRepository.js";
 // 运行时
-export { Provider } from "./runtime/Provider.js";
 export { createModel } from "./runtime/createModel.js";
 export { SdkAgent } from "./runtime/SdkAgent.js";
 export { createAgent } from "./runtime/createAgent.js";
-export { McpConnectionManager } from "./runtime/McpConnectionManager.js";
-export { SdkCallbackTool } from "./runtime/SdkCallbackTool.js";
+export { McpConnectionManager } from "./scope/plugins/mcp/McpConnectionManager.js";
+export { SdkCallbackTool } from "./scope/plugins/builtin/SdkCallbackTool.js";
 export { TaskMigrationService } from "./runtime/TaskMigrationService.js";
 // 插件
-export { AutoMigratePlugin } from "./plugin/AutoMigratePlugin.js";
-export { AutoRefreshToolsPlugin } from "./plugin/AutoRefreshToolsPlugin.js";
-export { ContextGuardPlugin } from "./plugin/ContextGuardPlugin.js";
-export { UnknownToolHintPlugin } from "./plugin/UnknownToolHintPlugin.js";
+export { AutoMigratePlugin } from "./agent-plugins/AutoMigratePlugin.js";
+export { AutoRefreshToolsPlugin } from "./agent-plugins/AutoRefreshToolsPlugin.js";
+export { ContextGuardPlugin } from "./agent-plugins/ContextGuardPlugin.js";
+export { UnknownToolHintPlugin } from "./agent-plugins/UnknownToolHintPlugin.js";
 // 工具 — 内置工具类 + 动态工具工厂
-export { BUILTIN_TOOL_CLASSES } from "./capabilities/implements/builtin/index.js";
-export { CwdTool, ReadFileTool, InspectFileTool, WriteFileTool, ExecTool, MkdirTool, RmTool, GlobTool, LsTool, ExistTool, FindTextTool, DownloadFileTool, RenameTool, CopyTool, BatchEditTool, EditTool, ExecAsyncTool, SleepTool, } from "./capabilities/implements/builtin/index.js";
-export { GenerateImageTool } from "./capabilities/implements/builtin/GenerateImageTool.js";
-export { ViewImageTool } from "./capabilities/implements/builtin/ViewImageTool.js";
-export { createLoadSkillTool, createCallSkillSubAgentTool } from "./capabilities/implements/skillTools.js";
-export { createLoadMcpTool, createCallMcpTool, createReadMcpResourceTool } from "./capabilities/implements/mcpTools.js";
-export { createSubAgentTool } from "./capabilities/implements/subAgentTools.js";
+export { BUILTIN_TOOL_CLASSES } from "./scope/plugins/builtin/index.js";
+export { CwdTool, ReadFileTool, InspectFileTool, WriteFileTool, ExecTool, MkdirTool, RmTool, GlobTool, LsTool, ExistTool, FindTextTool, DownloadFileTool, RenameTool, CopyTool, BatchEditTool, EditTool, ExecAsyncTool, SleepTool, } from "./scope/plugins/builtin/index.js";
+export { GenerateImageTool } from "./scope/plugins/builtin/GenerateImageTool.js";
+export { ViewImageTool } from "./scope/plugins/builtin/ViewImageTool.js";
+export { createLoadSkillTool, createCallSkillSubAgentTool } from "./scope/plugins/skills/skillTools.js";
+export { createLoadMcpTool, createCallMcpTool, createReadMcpResourceTool } from "./scope/plugins/mcp/mcpTools.js";
+export { createSubAgentTool } from "./scope/plugins/subagents/subAgentTools.js";
 // 共享
 export { getLogger, setLogger } from "./shared/logger.js";
 export { SdkError, ContextOverflowError } from "./shared/errors.js";

package/dist/runtime/SdkAgent.d.ts

@@ -2,14 +2,14 @@ import type OpenAI from "openai";
 import { Agent } from "@ai-zen/agents-core";
 import type { AgentNS, Tool } from "@ai-zen/agents-core";
 import type { AgentDefinition } from "../types/index.js";
-import type { Provider } from "./Provider.js";
+import type { Scope } from "../scope/Scope.js";
 export type { AgentPlugin, SendContext } from "@ai-zen/agents-core";
 /**
  * SDK Agent — 继承 Core Agent，携带 SDK 层额外信息。
  *
  * Core Agent 不感知权限、文件系统等业务逻辑；
  * SdkAgent 在 Core Agent 基础上增加了 SDK 层需要的元数据：
- *   - provider：全局 Provider 实例
+ *   - scope：全局 Scope 实例
  *   - definition：Agent 原始定义（含权限 permissions）
  *
  * 插件能力（use / init / send 钩子分发）继承自 Core Agent，此处不再重复实现。
@@ -17,12 +17,12 @@ export type { AgentPlugin, SendContext } from "@ai-zen/agents-core";
  * 权限统一从 `definition.permissions` 读取，不再单独持有。
  */
 export declare class SdkAgent extends Agent {
-    /** 全局 Provider 实例 */
-    readonly provider: Provider;
+    /** 全局 Scope 实例 */
+    readonly scope: Scope;
     /** Agent 原始定义 */
     readonly definition: AgentDefinition;
     constructor(params: {
-        provider: Provider;
+        scope: Scope;
         definition: AgentDefinition;
         client: OpenAI;
         model: string;

package/dist/runtime/SdkAgent.js

@@ -4,7 +4,7 @@ import { Agent } from "@ai-zen/agents-core";
  *
  * Core Agent 不感知权限、文件系统等业务逻辑；
  * SdkAgent 在 Core Agent 基础上增加了 SDK 层需要的元数据：
- *   - provider：全局 Provider 实例
+ *   - scope：全局 Scope 实例
  *   - definition：Agent 原始定义（含权限 permissions）
  *
  * 插件能力（use / init / send 钩子分发）继承自 Core Agent，此处不再重复实现。
@@ -12,8 +12,8 @@ import { Agent } from "@ai-zen/agents-core";
  * 权限统一从 `definition.permissions` 读取，不再单独持有。
  */
 export class SdkAgent extends Agent {
-    /** 全局 Provider 实例 */
-    provider;
+    /** 全局 Scope 实例 */
+    scope;
     /** Agent 原始定义 */
     definition;
     constructor(params) {
@@ -25,7 +25,7 @@ export class SdkAgent extends Agent {
             tools: params.tools,
             allowJsonParseError: params.allowJsonParseError,
         });
-        this.provider = params.provider;
+        this.scope = params.scope;
         this.definition = params.definition;
     }
 }

package/dist/runtime/TaskMigrationService.d.ts

@@ -55,7 +55,7 @@ export interface TaskMigrationServiceOptions {
  *
  * 一个服务实例对应一次迁移上下文。它**不持有**任何模型调用——生成交接文档时
  * 默认复用传入 `agent`（`SdkAgent`）自身的 `client` / `model` / `modelConfig`，
- * 因此无需 Provider、无需独立「迁移 Agent」对象，也无需自建 OpenAI 客户端。
+ * 因此无需 Scope、无需独立「迁移 Agent」对象，也无需自建 OpenAI 客户端。
  * 如需用不同模型生成交接文档，可在构造时显式传入 `client` / `model` / `modelConfig`，
  * 未传则 migrate 时回退到 agent 自带的配置。
  *

package/dist/runtime/TaskMigrationService.js

@@ -5,7 +5,7 @@ import { getLogger } from "../shared/logger.js";
  *
  * 一个服务实例对应一次迁移上下文。它**不持有**任何模型调用——生成交接文档时
  * 默认复用传入 `agent`（`SdkAgent`）自身的 `client` / `model` / `modelConfig`，
- * 因此无需 Provider、无需独立「迁移 Agent」对象，也无需自建 OpenAI 客户端。
+ * 因此无需 Scope、无需独立「迁移 Agent」对象，也无需自建 OpenAI 客户端。
  * 如需用不同模型生成交接文档，可在构造时显式传入 `client` / `model` / `modelConfig`，
  * 未传则 migrate 时回退到 agent 自带的配置。
  *
@@ -143,7 +143,7 @@ export class TaskMigrationService {
         const historyText = TaskMigrationService.serializeMessages(agent.messages.filter((m) => !m.omit));
         const messageCountBefore = agent.messages.length;
         // 生成交接文档所用模型调用：优先使用构造时传入的 client/model/modelConfig，
-        // 未传则回退到 agent 自带的（无需 Provider / 独立迁移 Agent）。
+        // 未传则回退到 agent 自带的（无需 Scope / 独立迁移 Agent）。
         const client = this.client ?? agent.client;
         const model = this.model ?? agent.model;
         const modelConfig = this.modelConfig ?? agent.modelConfig;

package/dist/runtime/createAgent.d.ts

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

package/dist/runtime/createAgent.js

@@ -4,22 +4,22 @@ import { createModel } from "./createModel.js";
 /**
  * 从磁盘创建 Agent。
  *
- * 通过 Provider 获取已发现的能力，读取 Agent 定义，过滤并实例化工具，产出 SdkAgent。
+ * 通过 Scope 获取已发现的能力，读取 Agent 定义，过滤并实例化工具，产出 SdkAgent。
  *
  * ```ts
- * const agent = await createAgent(provider, "my-agent");
+ * const agent = await createAgent(scope, "my-agent");
  * // agent 是 SdkAgent，可直接注册插件、发送消息
  * ```
  */
-export async function createAgent(provider, agentId) {
-    const definition = await new AgentRepository(provider.agentsDir).read(agentId);
+export async function createAgent(scope, agentId) {
+    const definition = await new AgentRepository(scope.agentsDir).read(agentId);
     if (!definition)
         throw new Error(`Agent "${agentId}" 不存在`);
-    const modelId = definition.modelId ?? provider.config.defaultModel;
+    const modelId = definition.modelId ?? scope.config.defaultModel;
     if (!modelId)
         throw new Error("未指定模型且无默认模型");
-    const { client, model, modelConfig } = createModel(provider, modelId);
-    const tools = provider.buildTools(definition, {
+    const { client, model, modelConfig } = createModel(scope, modelId);
+    const tools = scope.buildTools(definition, {
         exclude: {
             subagents: definition.function?.name
                 ? [definition.function.name]
@@ -27,7 +27,7 @@ export async function createAgent(provider, agentId) {
         },
     });
     const agent = new SdkAgent({
-        provider,
+        scope,
         definition,
         client,
         model,

package/dist/runtime/createModel.d.ts

@@ -1,5 +1,5 @@
 import OpenAI from "openai";
-import type { Provider } from "./Provider.js";
+import type { Scope } from "../scope/Scope.js";
 /**
  * Agent 模型装配结果：openai SDK client + 模型名 + 模型参数。
  * Agent 构造时直接消费此结构。
@@ -13,9 +13,9 @@ export interface AgentModel {
     modelConfig?: Record<string, unknown>;
 }
 /**
- * 模型工厂 — 根据 modelId 和 Provider 装配 openai SDK client。
+ * 模型工厂 — 根据 modelId 和 Scope 装配 openai SDK client。
  *
  * 端点（baseUrl / apiKey）来自 config.endpoints，发送给 API 的模型名 = modelName || id。
  * 任何 OpenAI 兼容端点（OpenAI / 智谱 BigModel / DeepSeek 等）均可通过 baseURL 接入。
  */
-export declare function createModel(provider: Provider, modelId: string): AgentModel;
+export declare function createModel(scope: Scope, modelId: string): AgentModel;

package/dist/runtime/createModel.js

@@ -1,12 +1,12 @@
 import OpenAI from "openai";
 /**
- * 模型工厂 — 根据 modelId 和 Provider 装配 openai SDK client。
+ * 模型工厂 — 根据 modelId 和 Scope 装配 openai SDK client。
  *
  * 端点（baseUrl / apiKey）来自 config.endpoints，发送给 API 的模型名 = modelName || id。
  * 任何 OpenAI 兼容端点（OpenAI / 智谱 BigModel / DeepSeek 等）均可通过 baseURL 接入。
  */
-export function createModel(provider, modelId) {
-    const config = provider.config;
+export function createModel(scope, modelId) {
+    const config = scope.config;
     const modelConfig = config.models.find((m) => m.id === modelId);
     if (!modelConfig)
         throw new Error(`模型 "${modelId}" 不存在`);

package/dist/scope/Scope.d.ts

@@ -0,0 +1,111 @@
+import type { Tool } from "@ai-zen/agents-core";
+import type { AppConfig, AgentDefinition, ToolEnv } from "../types/index.js";
+import type { ScopePlugin } from "./ScopePlugin.js";
+/**
+ * 能力过滤系统的公共类型。
+ * 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[];
+}
+/** filter / buildTools 的过滤选项 */
+export interface FilterOptions {
+    /** 排除项黑名单（优先级高于 permissions） */
+    exclude?: ExcludeOptions;
+}
+/**
+ * Scope — 全局上下文 + 能力装配编排容器（v1）。
+ *
+ * Scope 是 SDK 的唯一入口对象，持有：
+ *   - 应用配置（端点、模型等）
+ *   - 当前工作目录 cwd（相对路径解析基准，ToolEnv.cwd 的来源）
+ *   - Agent 定义目录 agentsDir（createAgent 用）
+ *   - 一组 ScopePlugin（能力插件）
+ *
+ * 装配方式（插件必须显式注入，Scope 不装任何默认插件）：
+ * ```ts
+ * const scope = new Scope({ config, cwd, agentsDir })
+ *   .use(...allInOne({ skillsPaths, toolsPaths, subAgentsPaths, mcpPaths }));
+ * await scope.init();
+ * ```
+ *
+ * 设计原则：
+ *   - Scope 只做编排：三阶段管线骨架（发现 → 过滤 → 实例化）+ 生命周期
+ *   - 能力来源（内置/用户工具、Skill、MCP、SubAgent）全部疏散到 ScopePlugin，各自自持
+ *   - Scope 实例一旦创建，config/cwd/agentsDir/env 不变；refresh() 只让插件重新发现
+ */
+export declare class Scope {
+    /** 应用配置（端点、模型等） */
+    readonly config: AppConfig;
+    /** 当前工作目录 — 相对路径解析基准，也是 ToolEnv.cwd 的来源 */
+    readonly cwd: string;
+    /** 工具环境 — 插件实例化内置工具时注入 */
+    readonly env: ToolEnv;
+    /** Agent 定义目录（createAgent 用） */
+    readonly agentsDir: string;
+    /** 已注册的插件 */
+    private _plugins;
+    /** 是否已 init（init 之后禁止再 use） */
+    private _initialized;
+    constructor(options: {
+        config: AppConfig;
+        agentsDir: string;
+        cwd?: string;
+    });
+    /** 已注册插件（只读视图） */
+    get plugins(): readonly ScopePlugin[];
+    /**
+     * 注册能力插件（链式，可变参数）。
+     *
+     * 支持两种用法：
+     *   scope.use(plugin)
+     *   scope.use(...allInOne({ ... }))   // 展开批量注册
+     *
+     * 必须在 init() 之前调用；init() 之后再 use() 会抛错。
+     */
+    use(...plugins: ScopePlugin[]): this;
+    /** 按 id 查找插件（供外部代码/其它插件查询插件状态） */
+    getPluginById<T extends ScopePlugin>(id: string): T | undefined;
+    /**
+     * 初始化：执行首次全局能力发现（遍历插件 discover()），随后锁定插件注册。
+     */
+    init(): Promise<void>;
+    /**
+     * 重新执行全局发现（遍历插件 discover()）。
+     */
+    refresh(options?: {
+        silent?: boolean;
+    }): Promise<void>;
+    /**
+     * 释放：逆序调用各插件 dispose()（如 MCP 断开所有连接）。与 init() 对称。
+     */
+    dispose(): Promise<void>;
+    /**
+     * 按权限过滤候选集，返回过滤后的名称列表。
+     * 汇总各插件 candidates() → 应用 exclude 安全预过滤 → 四维权限过滤。
+     * 纯名称操作，不涉及 Tool 实例化。
+     */
+    filter(definition: AgentDefinition, options?: FilterOptions): FilterOutput;
+    /**
+     * 快捷方法：filter + instantiate 一步完成。
+     */
+    buildTools(definition: AgentDefinition, options?: FilterOptions): Tool[];
+    /**
+     * 将过滤后的名称列表实例化为 Tool 数组。
+     * 遍历各插件 instantiate()，收集后去重（后注册覆盖先注册）。
+     */
+    instantiate(filtered: FilterOutput): Tool[];
+}

package/dist/scope/Scope.js

@@ -0,0 +1,165 @@
+import { PermissionEvaluator } from "./PermissionEvaluator.js";
+/**
+ * Scope — 全局上下文 + 能力装配编排容器（v1）。
+ *
+ * Scope 是 SDK 的唯一入口对象，持有：
+ *   - 应用配置（端点、模型等）
+ *   - 当前工作目录 cwd（相对路径解析基准，ToolEnv.cwd 的来源）
+ *   - Agent 定义目录 agentsDir（createAgent 用）
+ *   - 一组 ScopePlugin（能力插件）
+ *
+ * 装配方式（插件必须显式注入，Scope 不装任何默认插件）：
+ * ```ts
+ * const scope = new Scope({ config, cwd, agentsDir })
+ *   .use(...allInOne({ skillsPaths, toolsPaths, subAgentsPaths, mcpPaths }));
+ * await scope.init();
+ * ```
+ *
+ * 设计原则：
+ *   - Scope 只做编排：三阶段管线骨架（发现 → 过滤 → 实例化）+ 生命周期
+ *   - 能力来源（内置/用户工具、Skill、MCP、SubAgent）全部疏散到 ScopePlugin，各自自持
+ *   - Scope 实例一旦创建，config/cwd/agentsDir/env 不变；refresh() 只让插件重新发现
+ */
+export class Scope {
+    /** 应用配置（端点、模型等） */
+    config;
+    /** 当前工作目录 — 相对路径解析基准，也是 ToolEnv.cwd 的来源 */
+    cwd;
+    /** 工具环境 — 插件实例化内置工具时注入 */
+    env;
+    /** Agent 定义目录（createAgent 用） */
+    agentsDir;
+    /** 已注册的插件 */
+    _plugins = [];
+    /** 是否已 init（init 之后禁止再 use） */
+    _initialized = false;
+    constructor(options) {
+        this.config = options.config;
+        this.cwd = options.cwd ?? process.cwd();
+        this.env = { cwd: this.cwd, config: this.config };
+        this.agentsDir = options.agentsDir;
+    }
+    // ==================================================================
+    // 插件注册与生命周期
+    // ==================================================================
+    /** 已注册插件（只读视图） */
+    get plugins() {
+        return this._plugins;
+    }
+    /**
+     * 注册能力插件（链式，可变参数）。
+     *
+     * 支持两种用法：
+     *   scope.use(plugin)
+     *   scope.use(...allInOne({ ... }))   // 展开批量注册
+     *
+     * 必须在 init() 之前调用；init() 之后再 use() 会抛错。
+     */
+    use(...plugins) {
+        if (this._initialized) {
+            throw new Error("Scope.use() 必须在 init() 之前调用");
+        }
+        for (const plugin of plugins) {
+            this._plugins.push(plugin);
+        }
+        return this;
+    }
+    /** 按 id 查找插件（供外部代码/其它插件查询插件状态） */
+    getPluginById(id) {
+        return this._plugins.find((p) => p.id === id);
+    }
+    /**
+     * 初始化：执行首次全局能力发现（遍历插件 discover()），随后锁定插件注册。
+     */
+    async init() {
+        await this.refresh();
+        this._initialized = true;
+    }
+    /**
+     * 重新执行全局发现（遍历插件 discover()）。
+     */
+    async refresh(options) {
+        const opts = { silent: options?.silent ?? false };
+        for (const plugin of this._plugins) {
+            await plugin.discover?.(this, opts);
+        }
+    }
+    /**
+     * 释放：逆序调用各插件 dispose()（如 MCP 断开所有连接）。与 init() 对称。
+     */
+    async dispose() {
+        for (let i = this._plugins.length - 1; i >= 0; i--) {
+            await this._plugins[i].dispose?.();
+        }
+    }
+    // ==================================================================
+    // 能力过滤与实例化
+    // ==================================================================
+    /**
+     * 按权限过滤候选集，返回过滤后的名称列表。
+     * 汇总各插件 candidates() → 应用 exclude 安全预过滤 → 四维权限过滤。
+     * 纯名称操作，不涉及 Tool 实例化。
+     */
+    filter(definition, 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 ?? []);
+        // 1. 汇总各插件候选（插件已在 candidates 内完成自身可用性判断）
+        const tools = new Set();
+        const skills = new Set();
+        const mcps = new Set();
+        const subagents = new Set();
+        for (const plugin of this._plugins) {
+            const c = plugin.candidates(this, definition);
+            c.tools?.forEach((n) => tools.add(n));
+            c.skills?.forEach((n) => skills.add(n));
+            c.mcps?.forEach((n) => mcps.add(n));
+            c.subagents?.forEach((n) => subagents.add(n));
+        }
+        // 2 + 3. exclude 预过滤 + 四维权限过滤
+        const evaluator = new PermissionEvaluator(definition.permissions);
+        const filtered = evaluator.filter({
+            tools: [...tools].filter((n) => !excludeTools.has(n)),
+            skills: [...skills].filter((n) => !excludeSkills.has(n)),
+            mcps: [...mcps].filter((n) => !excludeMcps.has(n)),
+            subagents: [...subagents].filter((n) => !excludeSubAgents.has(n)),
+        });
+        return {
+            tools: filtered.tools,
+            subagents: filtered.subagents,
+            skills: filtered.skills,
+            mcps: filtered.mcps,
+        };
+    }
+    /**
+     * 快捷方法：filter + instantiate 一步完成。
+     */
+    buildTools(definition, options) {
+        return this.instantiate(this.filter(definition, options));
+    }
+    /**
+     * 将过滤后的名称列表实例化为 Tool 数组。
+     * 遍历各插件 instantiate()，收集后去重（后注册覆盖先注册）。
+     */
+    instantiate(filtered) {
+        const result = [];
+        for (const plugin of this._plugins) {
+            result.push(...plugin.instantiate(this, filtered));
+        }
+        return dedupTools(result);
+    }
+}
+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 result;
+}

package/dist/scope/ScopePlugin.d.ts

@@ -0,0 +1,51 @@
+import type { Tool } from "@ai-zen/agents-core";
+import type { AgentDefinition } from "../types/index.js";
+import type { Scope, FilterOutput } from "./Scope.js";
+/**
+ * 插件向四维权限体系贡献的候选名称（任意子集）。
+ */
+export interface ScopeCandidates {
+    tools?: string[];
+    skills?: string[];
+    mcps?: string[];
+    subagents?: string[];
+}
+/**
+ * ScopePlugin — 能力插件契约（v1 核心扩展点）。
+ *
+ * 一个插件**自持一类能力**的完整生命周期：自己发现、自己持有发现结果、
+ * 自己声明候选名、自己按过滤结果实例化工具、自己负责释放。
+ * `Scope` 只做编排，不感知任何具体能力的发现状态。
+ *
+ * 与 `AgentPlugin`（core，挂在 Agent 运行时 send/loop/toolcall）不同，
+ * `ScopePlugin` 挂在**能力装配管线**（discover/filter/instantiate）。二者互不相关。
+ *
+ * 生命周期与三阶段管线的对应：
+ *   discover     —— 阶段 1 · 发现
+ *   candidates   —— 阶段 2 · 候选（供权限过滤）
+ *   instantiate  —— 阶段 3 · 实例化
+ *   dispose      —— 释放
+ */
+export interface ScopePlugin {
+    /** 唯一标识，如 "builtin" / "user-tools" / "skills" / "mcp" / "subagents" */
+    readonly id: string;
+    /**
+     * 阶段 1 · 发现：扫描来源、刷新自身状态（每次内部重新扫描，不跨 refresh 累积）。
+     * 相对路径应在此基于 `scope.cwd` 解析。
+     */
+    discover?(scope: Scope, options: {
+        silent?: boolean;
+    }): Promise<void> | void;
+    /**
+     * 阶段 2 · 候选：返回本插件向四维贡献的候选名。
+     * 可结合 `definition` 做可用性判断（如内置工具的 isAvailable）。同步返回。
+     */
+    candidates(scope: Scope, definition: AgentDefinition): ScopeCandidates;
+    /**
+     * 阶段 3 · 实例化：按过滤后的允许名产出 Tool 实例。
+     * `filtered` 为 `Scope.filter()` 的产物（四维允许名）。
+     */
+    instantiate(scope: Scope, filtered: FilterOutput): Tool[];
+    /** 可选 · 释放：逆序于注册顺序调用。如 MCP 断开所有连接。 */
+    dispose?(): Promise<void> | void;
+}

package/dist/scope/ScopePlugin.js

@@ -0,0 +1 @@
+export {};

package/dist/scope/plugins/allInOne.d.ts

@@ -0,0 +1,18 @@
+import type { ScopePlugin } from "../ScopePlugin.js";
+/** allInOne 的装配选项：各类能力来源的路径（绝对或相对 scope.cwd） */
+export interface AllInOneOptions {
+    skillsPaths?: string[];
+    toolsPaths?: string[];
+    subAgentsPaths?: string[];
+    mcpPaths?: string[];
+}
+/**
+ * 标准能力插件工厂 —— 恒返回 5 个标准插件（"全家桶"）。
+ *
+ * 顺序即优先级（去重时后注册覆盖先注册）：
+ *   builtin → user-tools → skills → mcp → subagents
+ * 因此用户工具可覆盖同名内置工具（与 v0 一致）。
+ *
+ * 想裁剪/替换某一类，改用手工逐个 `new XxxScopePlugin(...)` 后 `.use()`。
+ */
+export declare function allInOne(options?: AllInOneOptions): ScopePlugin[];

package/dist/scope/plugins/allInOne.js

@@ -0,0 +1,23 @@
+import { BuiltinToolsScopePlugin } from "./builtin/BuiltinToolsScopePlugin.js";
+import { UserToolsScopePlugin } from "./usertools/UserToolsScopePlugin.js";
+import { SkillsScopePlugin } from "./skills/SkillsScopePlugin.js";
+import { McpScopePlugin } from "./mcp/McpScopePlugin.js";
+import { SubAgentsScopePlugin } from "./subagents/SubAgentsScopePlugin.js";
+/**
+ * 标准能力插件工厂 —— 恒返回 5 个标准插件（"全家桶"）。
+ *
+ * 顺序即优先级（去重时后注册覆盖先注册）：
+ *   builtin → user-tools → skills → mcp → subagents
+ * 因此用户工具可覆盖同名内置工具（与 v0 一致）。
+ *
+ * 想裁剪/替换某一类，改用手工逐个 `new XxxScopePlugin(...)` 后 `.use()`。
+ */
+export function allInOne(options) {
+    return [
+        new BuiltinToolsScopePlugin(),
+        new UserToolsScopePlugin({ paths: options?.toolsPaths }),
+        new SkillsScopePlugin({ paths: options?.skillsPaths }),
+        new McpScopePlugin({ paths: options?.mcpPaths }),
+        new SubAgentsScopePlugin({ paths: options?.subAgentsPaths }),
+    ];
+}

package/dist/{capabilities/implements → scope/plugins}/builtin/BatchEditTool.d.ts

@@ -1,4 +1,4 @@
-import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import { SdkCallbackTool } from "./SdkCallbackTool.js";
 import type { ToolEnv } from "../../../types/index.js";
 import type { AgentNS } from "@ai-zen/agents-core";
 interface Replacement {

package/dist/{capabilities/implements → scope/plugins}/builtin/BatchEditTool.js

@@ -1,5 +1,5 @@
 import * as fsp from "fs/promises";
-import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import { SdkCallbackTool } from "./SdkCallbackTool.js";
 export class BatchEditTool extends SdkCallbackTool {
     function = {
         name: "batchEdit",