@ai-zen/agents-sdk 0.6.0 → 0.7.0

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;
 }

package/dist/runtime/SdkCallbackTool.js

@@ -19,11 +19,14 @@ export class SdkCallbackTool extends Tool {
         super();
         this.env = options.env;
     }
-    /** 桥接 core 的 Tool.exec：解析参数 → call → 序列化 */
+    /** 桥接 core 的 Tool.exec：解析参数 → call → 序列化/透传内容块 */
     async exec(ctx) {
-        const result = await this.call(ctx.parsed_args, ctx);
+        const result = await this.call(ctx.parsedArgs, ctx);
         if (typeof result === "string")
             return result;
+        // 内容块数组（图片/文件等）直接透传，让模型能收到结构化内容
+        if (Array.isArray(result))
+            return result;
         // JSON.stringify(undefined) 返回 undefined（非字符串），会破坏 Promise<string> 契约
         return JSON.stringify(result) ?? "";
     }

package/dist/runtime/createAgent.js

@@ -18,8 +18,8 @@ export async function createAgent(provider, agentId) {
     const modelId = definition.modelId ?? provider.config.defaultModel;
     if (!modelId)
         throw new Error("未指定模型且无默认模型");
-    const model = createModel(provider, modelId);
-    const tools = provider.buildTools(definition.permissions ?? {}, {
+    const { client, model, modelConfig } = createModel(provider, modelId);
+    const tools = provider.buildTools(definition, {
         exclude: {
             subagents: definition.function?.name
                 ? [definition.function.name]
@@ -29,10 +29,11 @@ export async function createAgent(provider, agentId) {
     const agent = new SdkAgent({
         provider,
         definition,
+        client,
         model,
+        modelConfig,
         messages: definition.messages,
         tools,
-        permissions: definition.permissions,
     });
     return agent;
 }

package/dist/runtime/createModel.d.ts

@@ -1,8 +1,21 @@
-import type { ChatCompletionModel } from "@ai-zen/agents-core";
+import OpenAI from "openai";
 import type { Provider } from "./Provider.js";
 /**
- * 模型工厂 — 根据 modelId 和 Provider 构建 Core ChatCompletionModel。
+ * Agent 模型装配结果：openai SDK client + 模型名 + 模型参数。
+ * Agent 构造时直接消费此结构。
+ */
+export interface AgentModel {
+    /** openai 官方 SDK 客户端 */
+    client: OpenAI;
+    /** 发送给 API 的模型名 */
+    model: string;
+    /** 模型参数（defaultParams），透传给 API（可含厂商特有字段，如 DeepSeek thinking） */
+    modelConfig?: Record<string, unknown>;
+}
+/**
+ * 模型工厂 — 根据 modelId 和 Provider 装配 openai SDK client。
  *
- * 同步版本，使用 endp​oint.chatCompletionSync() 避免不必要的 async。
+ * 端点（baseUrl / apiKey）来自 config.endpoints，发送给 API 的模型名 = modelName || id。
+ * 任何 OpenAI 兼容端点（OpenAI / 智谱 BigModel / DeepSeek 等）均可通过 baseURL 接入。
  */
-export declare function createModel(provider: Provider, modelId: string): ChatCompletionModel;
+export declare function createModel(provider: Provider, modelId: string): AgentModel;

package/dist/runtime/createModel.js

@@ -1,8 +1,9 @@
-import { OpenAI, ChatGPT } from "@ai-zen/agents-core";
+import OpenAI from "openai";
 /**
- * 模型工厂 — 根据 modelId 和 Provider 构建 Core ChatCompletionModel。
+ * 模型工厂 — 根据 modelId 和 Provider 装配 openai SDK client。
  *
- * 同步版本，使用 endp​oint.chatCompletionSync() 避免不必要的 async。
+ * 端点（baseUrl / apiKey）来自 config.endpoints，发送给 API 的模型名 = modelName || id。
+ * 任何 OpenAI 兼容端点（OpenAI / 智谱 BigModel / DeepSeek 等）均可通过 baseURL 接入。
  */
 export function createModel(provider, modelId) {
     const config = provider.config;
@@ -12,15 +13,18 @@ export function createModel(provider, modelId) {
     const endpointConfig = config.endpoints.find((e) => e.id === modelConfig.endpointId);
     if (!endpointConfig)
         throw new Error(`端点 "${modelConfig.endpointId}" 未配置`);
-    const endpoint = new OpenAI({
-        openai_endpoint: endpointConfig.baseUrl,
-        api_key: endpointConfig.apiKey,
+    if (!endpointConfig.apiKey) {
+        throw new Error(`端点 "${endpointConfig.name}" 的 API Key 未设置`);
+    }
+    const client = new OpenAI({
+        apiKey: endpointConfig.apiKey,
+        baseURL: endpointConfig.baseUrl,
     });
     // 发送给 API 的模型名：modelName > id
     const apiModelName = modelConfig.modelName || modelConfig.id;
-    const model = new ChatGPT({
-        model_config: modelConfig.defaultParams,
-        request_config: endpoint.chatCompletionSync(apiModelName),
-    });
-    return model;
+    return {
+        client,
+        model: apiModelName,
+        modelConfig: modelConfig.defaultParams,
+    };
 }

package/dist/types/index.d.ts

@@ -29,6 +29,8 @@ export interface Model {
     maxContextTokens: number;
     maxContextChars?: number;
     defaultParams?: Record<string, unknown>;
+    /** 是否支持图片输入（视觉模型）。看图工具（viewImage）仅对视觉模型启用；generateImage 是否返回图片内容块也据此判断 */
+    vision?: boolean;
     description?: string;
     version?: number;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-zen/agents-sdk",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "AI-Zen Agents SDK — shared business logic for CLI and Desktop",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -18,7 +18,8 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dayjs": "^1.11.21",
-    "@ai-zen/agents-core": "^3.4.0"
+    "openai": "^7.5.0",
+    "@ai-zen/agents-core": "^4.0.0"
   },
   "devDependencies": {
     "@types/node": "^24.12.2",