@ai-zen/agents-sdk 0.6.0 → 0.7.1

package/dist/capabilities/implements/skillTools.js

@@ -113,17 +113,17 @@ export function createCallSkillSubAgentTool(skillDirs, filteredSkills, provider)
             if (!skill.subAgent) {
                 return `Skill "${skillId}" 不支持子 Agent 模式，请使用 load_skill 加载指导后自行处理`;
             }
+            // 临时 Skill 子 Agent 复用父 Agent 定义（权限 + 模型），排除当前 Skill 防自调用
             const parentAgent = ctx.agent;
-            const parentPermissions = parentAgent instanceof SdkAgent
-                ? parentAgent.permissions
-                : undefined;
-            const skillTools = provider && parentPermissions
-                ? provider.buildTools(parentPermissions, {
+            const skillTools = provider && parentAgent instanceof SdkAgent
+                ? provider.buildTools(parentAgent.definition, {
                     exclude: { skills: [skillId] },
                 })
                 : [];
             const subAgent = new Agent({
+                client: parentAgent.client,
                 model: parentAgent.model,
+                modelConfig: parentAgent.modelConfig,
                 messages: [
                     Message.System(skill.content),
                     Message.User(task),

package/dist/capabilities/implements/subAgentTools.js

@@ -18,28 +18,37 @@ export function createSubAgentTool(def, provider) {
             parameters: def.function.parameters,
         },
         messages: def.messages,
-        buildAgent: (_parsed_args, ctx) => {
+        buildAgent: (_parsedArgs, ctx) => {
             // 模型解析：SubAgent 可指定独立模型，否则复用父 Agent 的模型
-            let subModel;
+            let client;
+            let model;
+            let modelConfig;
             if (def.modelId) {
-                subModel = createModel(provider, def.modelId);
+                const m = createModel(provider, def.modelId);
+                client = m.client;
+                model = m.model;
+                modelConfig = m.modelConfig;
             }
             else {
-                const parentModel = ctx.agent?.model;
-                if (!parentModel) {
+                const parent = ctx.agent;
+                if (!parent) {
                     throw new Error(`SubAgent "${selfName}" 未指定 modelId，且父 Agent 没有可复用的模型`);
                 }
-                subModel = parentModel;
+                client = parent.client;
+                model = parent.model;
+                modelConfig = parent.modelConfig;
             }
             // SubAgent 独立解析自己的工具（排除自身，防止递归）
-            const subFiltered = provider.filter(def.permissions ?? {}, {
+            const subFiltered = provider.filter(def, {
                 exclude: {
                     subagents: def.function?.name ? [def.function.name] : undefined,
                 },
             });
             const tools = provider.instantiate(subFiltered);
             const subAgent = new Agent({
-                model: subModel,
+                client,
+                model,
+                modelConfig,
                 tools,
             });
             return subAgent;

package/dist/config/constants.js

@@ -119,7 +119,8 @@ export const DEFAULT_APP_CONFIG = {
             modelName: "glm-5v-turbo",
             maxContextTokens: 250_000,
             defaultParams: {},
-            description: "智谱AI 多模态Coding基座",
+            vision: true,
+            description: "智谱AI 多模态Coding基座（支持图片输入）",
         },
         {
             id: "glm-4.7-flash",
@@ -148,6 +149,16 @@ export const DEFAULT_APP_CONFIG = {
             defaultParams: { thinking: { type: "enabled" } },
             description: "DeepSeek 经济高效模型",
         },
+        {
+            id: "deepseek-v4-flash-vision-exp",
+            name: "DeepSeek-V4-Flash-Vision-Exp",
+            endpointId: "deepseek",
+            modelName: "deepseek-v4-flash-vision-exp",
+            maxContextTokens: 250_000,
+            defaultParams: { thinking: { type: "enabled" } },
+            vision: true,
+            description: "DeepSeek 视觉实验模型（支持图片/文件输入）",
+        },
     ],
     imageModels: [
         {

package/dist/index.d.ts

@@ -29,9 +29,11 @@ export type { AutoMigrateOptions } from "./plugin/AutoMigratePlugin.js";
 export { AutoRefreshToolsPlugin } from "./plugin/AutoRefreshToolsPlugin.js";
 export { ContextGuardPlugin } from "./plugin/ContextGuardPlugin.js";
 export type { ContextGuardOptions } from "./plugin/ContextGuardPlugin.js";
+export { UnknownToolHintPlugin } from "./plugin/UnknownToolHintPlugin.js";
 export { BUILTIN_TOOL_CLASSES } from "./capabilities/implements/builtin/index.js";
 export { CwdTool, ReadFileTool, 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";

package/dist/index.js

@@ -24,10 +24,12 @@ 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 { BUILTIN_TOOL_CLASSES } from "./capabilities/implements/builtin/index.js";
 export { CwdTool, ReadFileTool, 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";

package/dist/plugin/AutoMigratePlugin.d.ts

@@ -1,4 +1,4 @@
-import type { AgentPlugin, SendContext } from "../runtime/SdkAgent.js";
+import type { AgentPlugin, SendContext } from "@ai-zen/agents-core";
 import { SdkAgent } from "../runtime/SdkAgent.js";
 export interface AutoMigrateOptions {
     maxTokens: number;

package/dist/plugin/AutoMigratePlugin.js

@@ -22,7 +22,7 @@ export class AutoMigratePlugin {
         this.options = options;
     }
     async onAfterSend(ctx) {
-        const { agent } = ctx;
+        const agent = ctx.agent;
         const { maxTokens, migrationAgent, onBeforeMigrate, onMigrated } = this.options;
         const promptTokens = agent.lastUsage?.prompt_tokens;
         if (promptTokens == null)

package/dist/plugin/AutoRefreshToolsPlugin.d.ts

@@ -1,4 +1,4 @@
-import type { AgentPlugin, SendContext } from "../runtime/SdkAgent.js";
+import type { AgentPlugin, SendContext } from "@ai-zen/agents-core";
 /**
  * 自动刷新能力插件。
  *

package/dist/plugin/AutoRefreshToolsPlugin.js

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

package/dist/plugin/ContextGuardPlugin.d.ts

@@ -1,10 +1,10 @@
-import type { AgentPlugin, SendContext } from "../runtime/SdkAgent.js";
+import type { AgentPlugin, SendContext } from "@ai-zen/agents-core";
 export interface ContextGuardOptions {
     /** 上下文告警阈值（token）。用量超过 maxTokens × ratio 即中断。 */
     maxTokens: number;
     /**
      * 超出比例。用量 > maxTokens × ratio 时判定为「严重超限」（如读入超大文件），
-     * 在请求前抛出 ContextOverflowError 中断对话。默认 1.2（即 +20%）。
+     * 在请求前抛出 ContextOverflowError 中断对话。默认 1.5（即 +50%）。
      */
     ratio?: number;
 }

package/dist/plugin/ContextGuardPlugin.js

@@ -25,7 +25,7 @@ export class ContextGuardPlugin {
     }
     async onInnerLoopStart(ctx) {
         const { agent } = ctx;
-        const { maxTokens, ratio = 1.2 } = this.options;
+        const { maxTokens, ratio = 1.5 } = this.options;
         // 首轮请求前尚无用量数据，跳过（只能在发出首轮请求、拿到 usage 后才有据可查）
         const promptTokens = agent.lastUsage?.prompt_tokens;
         if (promptTokens == null)

package/dist/plugin/UnknownToolHintPlugin.d.ts

@@ -0,0 +1,21 @@
+import type { AgentPlugin, UnknownToolContext } from "@ai-zen/agents-core";
+import type { Provider } from "../runtime/Provider.js";
+/**
+ * 未知工具智能提示插件 — MCP 场景引导。
+ *
+ * 当 LLM 调用不存在的工具时，根据当前环境给出更智能的提示：
+ *   - 有 MCP 配置但 `call_mcp_tool` 不在工具列表中（权限禁用）→ 提示权限问题
+ *   - 有 MCP 配置且 `call_mcp_tool` 可用 → 提示使用 `call_mcp_tool`
+ *   - 否则 → 仅提示工具不存在
+ *
+ * 由调用方显式注册（`agent.use(new UnknownToolHintPlugin({ provider }))`）。
+ * 未注册时，Agent 回落到底层的简单文本默认提示（core 内建）。
+ */
+export declare class UnknownToolHintPlugin implements AgentPlugin {
+    /** 全局 Provider 实例 */
+    private readonly provider;
+    constructor(options: {
+        provider: Provider;
+    });
+    onUnknownTool(ctx: UnknownToolContext): string | undefined;
+}

package/dist/plugin/UnknownToolHintPlugin.js

@@ -0,0 +1,30 @@
+/**
+ * 未知工具智能提示插件 — MCP 场景引导。
+ *
+ * 当 LLM 调用不存在的工具时，根据当前环境给出更智能的提示：
+ *   - 有 MCP 配置但 `call_mcp_tool` 不在工具列表中（权限禁用）→ 提示权限问题
+ *   - 有 MCP 配置且 `call_mcp_tool` 可用 → 提示使用 `call_mcp_tool`
+ *   - 否则 → 仅提示工具不存在
+ *
+ * 由调用方显式注册（`agent.use(new UnknownToolHintPlugin({ provider }))`）。
+ * 未注册时，Agent 回落到底层的简单文本默认提示（core 内建）。
+ */
+export class UnknownToolHintPlugin {
+    /** 全局 Provider 实例 */
+    provider;
+    constructor(options) {
+        this.provider = options.provider;
+    }
+    onUnknownTool(ctx) {
+        const toolName = ctx.toolCall.function?.name ?? "未知";
+        const hasMcpConfig = this.provider.mcpPaths.length > 0;
+        const hasCallMcpTool = ctx.availableTools.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}" 不存在。`;
+    }
+}

package/dist/runtime/Provider.d.ts

@@ -1,5 +1,5 @@
 import type { Tool } from "@ai-zen/agents-core";
-import type { AppConfig, AgentDefinition, AgentPermissions, McpServerConfig, ToolEnv } from "../types/index.js";
+import type { AppConfig, AgentDefinition, McpServerConfig, ToolEnv } from "../types/index.js";
 import type { SkillInfo } from "../capabilities/discovery/skills.js";
 import { McpConnectionManager } from "./McpConnectionManager.js";
 /**
@@ -22,6 +22,11 @@ export interface ExcludeOptions {
     mcps?: string[];
     subagents?: string[];
 }
+/** filter / buildTools 的过滤选项 */
+export interface FilterOptions {
+    /** 排除项黑名单（优先级高于 permissions） */
+    exclude?: ExcludeOptions;
+}
 /**
  * Provider — 全局上下文实例 + 能力注册表。
  *
@@ -96,15 +101,11 @@ export declare class Provider {
      * 按权限过滤候选集，返回过滤后的名称列表。
      * 纯名称操作（安全预过滤 + 权限过滤），不涉及 Tool 实例化。
      */
-    filter(permissions: AgentPermissions, options?: {
-        exclude?: ExcludeOptions;
-    }): FilterOutput;
+    filter(definition: AgentDefinition, options?: FilterOptions): FilterOutput;
     /**
      * 快捷方法：filter + instantiate 一步完成。
      */
-    buildTools(permissions: AgentPermissions, options?: {
-        exclude?: ExcludeOptions;
-    }): Tool[];
+    buildTools(definition: AgentDefinition, options?: FilterOptions): Tool[];
     /**
      * 将过滤后的名称列表实例化为 Tool 数组。
      */

package/dist/runtime/Provider.js

@@ -91,7 +91,7 @@ export class Provider {
      * 按权限过滤候选集，返回过滤后的名称列表。
      * 纯名称操作（安全预过滤 + 权限过滤），不涉及 Tool 实例化。
      */
-    filter(permissions, options) {
+    filter(definition, options) {
         const exclude = options?.exclude ?? {};
         const excludeTools = new Set(exclude.tools ?? []);
         const excludeSkills = new Set(exclude.skills ?? []);
@@ -112,7 +112,17 @@ export class Provider {
             ...this.userTools.map((t) => t.function.name),
             ...DYNAMIC_TOOL_NAMES,
         ].filter((name) => !excludeTools.has(name));
-        const evaluator = new PermissionEvaluator(permissions);
+        // 工具可用性过滤：调用候选工具的 isAvailable（直接透传完整 app config + agent definition）。
+        // 工具自行声明可用条件（如依赖图片模型配置、仅视觉模型可用），返回 false 则剔除。
+        const candidates = [...this.builtinTools, ...this.userTools];
+        for (let i = toolNames.length - 1; i >= 0; i--) {
+            const tool = candidates.find((t) => t.function.name === toolNames[i]);
+            const isAvailable = tool?.isAvailable;
+            if (isAvailable && !isAvailable(this.config, definition)) {
+                toolNames.splice(i, 1);
+            }
+        }
+        const evaluator = new PermissionEvaluator(definition.permissions);
         const filtered = evaluator.filter({
             tools: toolNames,
             skills: this.skills
@@ -133,8 +143,8 @@ export class Provider {
     /**
      * 快捷方法：filter + instantiate 一步完成。
      */
-    buildTools(permissions, options) {
-        return this.instantiate(this.filter(permissions, options));
+    buildTools(definition, options) {
+        return this.instantiate(this.filter(definition, options));
     }
     /**
      * 将过滤后的名称列表实例化为 Tool 数组。

package/dist/runtime/SdkAgent.d.ts

@@ -1,127 +1,34 @@
-import { Agent, type ChatCompletionModel } from "@ai-zen/agents-core";
-import type { AgentNS, Tool, ToolCallContext, UnknownToolContext } from "@ai-zen/agents-core";
-import type { AgentDefinition, AgentPermissions } from "../types/index.js";
+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";
-/**
- * Agent 插件上下文：当前 SdkAgent + 发送内容 + 消息列表。
- *
- * 注意：
- * - messages 是当前 agent 消息数组的**快照**（浅拷贝），插件不应直接修改它。
- *   所有消息变更应通过 agent 上的方法进行。
- * - 如果 onAfterSend 替换了 ctx.agent，send() 方法会使用新 agent 的消息作为返回值。
- */
-export interface SendContext {
-    agent: SdkAgent;
-    content: string;
-    /** 当前 agent 消息数组的浅拷贝快照，仅供读取，不应直接修改 */
-    messages: AgentNS.Message[];
-}
-/**
- * Agent 插件接口。
- * 每个插件单一职责，通过钩子介入 Agent 生命周期。
- *
- * onInit:            Agent.init() 时调用，用于异步初始化
- * onBeforeSend:      Agent.send() 调用前触发。可用于刷新工具列表等。
- * onAfterSend:       Agent.send() 返回后调用。可通过 ctx.agent 替换当前 Agent。
- * onInnerLoopStart:  Agent 内循环开始前触发。由 Core Agent 在内循环中调用。
- * onInnerLoopEnd:    Agent 内循环结束后触发。由 Core Agent 在内循环中调用。
- * onInnerLoopsStart: Agent 整组内循环开始前触发（一次 send 仅一次）。由 Core Agent 在 run() 的 while 循环前调用。
- * onInnerLoopsEnd:   Agent 整组内循环结束后触发（一次 send 仅一次）。由 Core Agent 在 run() 的 while 循环后调用。
- * onToolCall:        单个工具调用执行前触发（对应 Core onToolCall 钩子）。
- *                    返回字符串 = 拒绝该工具（原因作为工具结果回给 LLM，工具不执行）；
- *                    返回 undefined = 放行。多个插件按注册顺序调用，任一返回字符串即拒绝。
- */
-export interface AgentPlugin {
-    /** Agent.init() 时调用，用于异步初始化 */
-    onInit?(): Promise<void>;
-    /** Agent.send() 调用前触发 */
-    onBeforeSend?(ctx: SendContext): Promise<void>;
-    /** Agent.send() 返回后调用，可通过 ctx.agent 替换当前 Agent */
-    onAfterSend?(ctx: SendContext): Promise<void>;
-    /** Agent 内循环开始前触发 */
-    onInnerLoopStart?(ctx: SendContext): Promise<void>;
-    /** Agent 内循环结束后触发 */
-    onInnerLoopEnd?(ctx: SendContext): Promise<void>;
-    /** Agent 整组内循环开始前触发（一次 send 仅一次） */
-    onInnerLoopsStart?(ctx: SendContext): Promise<void>;
-    /** Agent 整组内循环结束后触发（一次 send 仅一次） */
-    onInnerLoopsEnd?(ctx: SendContext): Promise<void>;
-    /**
-     * 单个工具调用执行前触发（对应 Core onToolCall 钩子，收同一个 ToolCallContext 实例）。
-     * 返回字符串 = 拒绝该工具（不执行，原因作为工具结果回给 LLM，继续下一轮）；
-     * 返回 undefined = 放行。多个插件按注册顺序调用，任一返回字符串即拒绝。
-     */
-    onToolCall?(ctx: ToolCallContext): string | undefined | Promise<string | undefined>;
-}
+export type { AgentPlugin, SendContext } from "@ai-zen/agents-core";
 /**
  * SDK Agent — 继承 Core Agent，携带 SDK 层额外信息。
  *
- * Core Agent 不做复杂逻辑（不感知权限、不感知文件系统），
- * SdkAgent 在 Core Agent 基础上增加了 SDK 层需要的元数据，
- * 并通过 provider 字段访问全局上下文。
- *
- * 携带：
+ * Core Agent 不感知权限、文件系统等业务逻辑；
+ * SdkAgent 在 Core Agent 基础上增加了 SDK 层需要的元数据：
  *   - provider：全局 Provider 实例
- *   - definition：Agent 原始定义
- *   - permissions：Agent 权限，供 call_skill_sub_agent 等回调读取
+ *   - definition：Agent 原始定义（含权限 permissions）
  *
- * 插件能力：
- *   - use(plugin)：注册插件
- *   - init()：初始化所有已注册插件
- *   - send()：重写，在前后执行插件钩子
+ * 插件能力（use / init / send 钩子分发）继承自 Core Agent，此处不再重复实现。
+ * 未知工具的 MCP 智能提示由独立插件 `UnknownToolHintPlugin` 提供（调用方显式 use）。
+ * 权限统一从 `definition.permissions` 读取，不再单独持有。
  */
 export declare class SdkAgent extends Agent {
     /** 全局 Provider 实例 */
     readonly provider: Provider;
     /** Agent 原始定义 */
     readonly definition: AgentDefinition;
-    /** Agent 权限 */
-    readonly permissions?: AgentPermissions;
-    /**
-     * 当 LLM 调用不存在的工具时，给出智能提示。
-     * 如果有 MCP 配置但 call_mcp_tool 不在工具列表中（权限禁用），提示权限问题；
-     * 如果有 MCP 配置且 call_mcp_tool 可用，提示使用 call_mcp_tool；
-     * 否则仅提示工具不存在。
-     */
-    onUnknownTool: (ctx: UnknownToolContext) => string;
-    /** 已注册的插件列表 */
-    private _plugins;
     constructor(params: {
         provider: Provider;
         definition: AgentDefinition;
-        model: ChatCompletionModel;
-        model_config?: Record<string, unknown>;
+        client: OpenAI;
+        model: string;
+        modelConfig?: Record<string, unknown>;
         messages?: AgentNS.Message[];
         tools?: Tool[];
-        permissions?: AgentPermissions;
-        rag?: any;
         allowJsonParseError?: boolean;
     });
-    /**
-     * 注册一个插件。
-     * 可以在 init() 之前或之后调用，但 beforeSend/afterSend 钩子仅在
-     * init() 之后发送消息时生效。
-     */
-    use(plugin: AgentPlugin): void;
-    /**
-     * 初始化所有已注册插件。
-     * SdkAgent 本身没有异步初始化需求——模型、工具、消息在构造时已就绪。
-     * init() 的存在完全是为了给插件一个执行异步初始化的机会。
-     *
-     * 如果不使用任何插件，可以不调 init()。
-     */
-    init(): Promise<void>;
-    /**
-     * 发送消息，在前后执行插件钩子。
-     *
-     * 流程：
-     *   1. onBeforeSend — send 外部准备（刷新工具等）
-     *   2. super.send()  — 委托 Core Agent，内含内循环及其钩子
-     *   3. onAfterSend  — send 外部后处理（保存草稿、迁移等）
-     *
-     * 注意：
-     * - ctx.messages 是当前 agent 消息的**浅拷贝快照**，仅供读取，不应直接修改。
-     *   所有消息变更应通过 agent 上的方法进行（如 agent.messages.push 等）。
-     */
-    send(content: string): Promise<AgentNS.Message[]>;
 }

package/dist/runtime/SdkAgent.js

@@ -1,143 +1,31 @@
 import { Agent } from "@ai-zen/agents-core";
-// ---------------------------------------------------------------------------
-// SdkAgent
-// ---------------------------------------------------------------------------
 /**
  * SDK Agent — 继承 Core Agent，携带 SDK 层额外信息。
  *
- * Core Agent 不做复杂逻辑（不感知权限、不感知文件系统），
- * SdkAgent 在 Core Agent 基础上增加了 SDK 层需要的元数据，
- * 并通过 provider 字段访问全局上下文。
- *
- * 携带：
+ * Core Agent 不感知权限、文件系统等业务逻辑；
+ * SdkAgent 在 Core Agent 基础上增加了 SDK 层需要的元数据：
  *   - provider：全局 Provider 实例
- *   - definition：Agent 原始定义
- *   - permissions：Agent 权限，供 call_skill_sub_agent 等回调读取
+ *   - definition：Agent 原始定义（含权限 permissions）
  *
- * 插件能力：
- *   - use(plugin)：注册插件
- *   - init()：初始化所有已注册插件
- *   - send()：重写，在前后执行插件钩子
+ * 插件能力（use / init / send 钩子分发）继承自 Core Agent，此处不再重复实现。
+ * 未知工具的 MCP 智能提示由独立插件 `UnknownToolHintPlugin` 提供（调用方显式 use）。
+ * 权限统一从 `definition.permissions` 读取，不再单独持有。
  */
 export class SdkAgent extends Agent {
     /** 全局 Provider 实例 */
     provider;
     /** Agent 原始定义 */
     definition;
-    /** Agent 权限 */
-    permissions;
-    /**
-     * 当 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) {
         super({
+            client: params.client,
             model: params.model,
-            model_config: params.model_config,
+            modelConfig: params.modelConfig,
             messages: params.messages,
             tools: params.tools,
-            rag: params.rag,
             allowJsonParseError: params.allowJsonParseError,
         });
         this.provider = params.provider;
         this.definition = params.definition;
-        this.permissions = params.permissions;
-    }
-    /**
-     * 注册一个插件。
-     * 可以在 init() 之前或之后调用，但 beforeSend/afterSend 钩子仅在
-     * init() 之后发送消息时生效。
-     */
-    use(plugin) {
-        this._plugins.push(plugin);
-    }
-    /**
-     * 初始化所有已注册插件。
-     * SdkAgent 本身没有异步初始化需求——模型、工具、消息在构造时已就绪。
-     * init() 的存在完全是为了给插件一个执行异步初始化的机会。
-     *
-     * 如果不使用任何插件，可以不调 init()。
-     */
-    async init() {
-        for (const plugin of this._plugins) {
-            await plugin.onInit?.();
-        }
-    }
-    /**
-     * 发送消息，在前后执行插件钩子。
-     *
-     * 流程：
-     *   1. onBeforeSend — send 外部准备（刷新工具等）
-     *   2. super.send()  — 委托 Core Agent，内含内循环及其钩子
-     *   3. onAfterSend  — send 外部后处理（保存草稿、迁移等）
-     *
-     * 注意：
-     * - ctx.messages 是当前 agent 消息的**浅拷贝快照**，仅供读取，不应直接修改。
-     *   所有消息变更应通过 agent 上的方法进行（如 agent.messages.push 等）。
-     */
-    async send(content) {
-        const ctx = {
-            agent: this,
-            content,
-            messages: [...this.messages],
-        };
-        for (const plugin of this._plugins) {
-            await plugin.onBeforeSend?.(ctx);
-        }
-        this.onInnerLoopStart = async () => {
-            for (const plugin of this._plugins) {
-                await plugin.onInnerLoopStart?.(ctx);
-            }
-        };
-        this.onInnerLoopEnd = async () => {
-            for (const plugin of this._plugins) {
-                await plugin.onInnerLoopEnd?.(ctx);
-            }
-        };
-        this.onInnerLoopsStart = async () => {
-            for (const plugin of this._plugins) {
-                await plugin.onInnerLoopsStart?.(ctx);
-            }
-        };
-        this.onInnerLoopsEnd = async () => {
-            for (const plugin of this._plugins) {
-                await plugin.onInnerLoopsEnd?.(ctx);
-            }
-        };
-        // 工具调用拦截：任一插件返回字符串即拒绝该工具（短路），全部放行则返回 undefined
-        this.onToolCall = async (ctx) => {
-            for (const plugin of this._plugins) {
-                const denied = await plugin.onToolCall?.(ctx);
-                if (denied !== undefined)
-                    return denied;
-            }
-            return undefined;
-        };
-        await super.send(content);
-        this.onInnerLoopStart = undefined;
-        this.onInnerLoopEnd = undefined;
-        this.onInnerLoopsStart = undefined;
-        this.onInnerLoopsEnd = undefined;
-        this.onToolCall = undefined;
-        for (const plugin of this._plugins) {
-            await plugin.onAfterSend?.(ctx);
-        }
-        return this.messages;
     }
 }

package/dist/runtime/SdkCallbackTool.d.ts

@@ -1,6 +1,6 @@
 import { Tool, ToolCallContext } from "@ai-zen/agents-core";
 import type { AgentNS } from "@ai-zen/agents-core";
-import type { ToolEnv } from "../types/index.js";
+import type { AgentDefinition, AppConfig, ToolEnv } from "../types/index.js";
 /** SdkCallbackTool 构造选项。env 为核心字段，未来可在此扩展可选项。 */
 export interface SdkCallbackToolOptions {
     /** 注入的工具环境 */
@@ -23,14 +23,22 @@ export declare abstract class SdkCallbackTool extends Tool {
     readonly env: ToolEnv;
     /** 工具定义。由子类以类体字段 function = {...} 提供。 */
     function: AgentNS.FunctionDefine;
+    /**
+     * 工具对当前 Agent 的可用性判断。由工具自行声明，直接透传完整
+     * app config 与 agent definition（含 modelId / permissions 等），工具自取所需
+     * （如是否配置了图片模型、当前模型是否为视觉模型）。
+     * 在 buildTools/filter 阶段调用；返回 false 的工具不会注册给该 Agent。
+     * 不实现则默认可用。
+     */
+    isAvailable?(config: AppConfig, definition: AgentDefinition): boolean;
     constructor(options: SdkCallbackToolOptions);
     /**
-     * 工具核心逻辑（由子类实现，参数为 parsed_args）。
+     * 工具核心逻辑（由子类实现，参数为 parsedArgs）。
      * 可选第二参 ctx：透传完整 ToolCallContext，需中止能力（signal）的工具自行读取。
      */
     abstract call(input: unknown, ctx?: ToolCallContext): unknown | Promise<unknown>;
-    /** 桥接 core 的 Tool.exec：解析参数 → call → 序列化 */
-    exec(ctx: ToolCallContext): Promise<string>;
+    /** 桥接 core 的 Tool.exec：解析参数 → call → 序列化/透传内容块 */
+    exec(ctx: ToolCallContext): Promise<AgentNS.MessageContent>;
     /** 将相对路径解析到 env.cwd，绝对路径原样返回 */
     resolve(p: string): string;
 }