@ai-zen/agents-sdk 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## [0.7.0] - 2026-08-14
+
+### ⚠️ Breaking
+
+- **`@ai-zen/agents-core` upgraded to 4.0.0** — the SDK now runs on the **official OpenAI SDK**: `createModel(provider, modelId)` returns `{ client, model, modelConfig }` (an `openai` client + model name + params spread into the request) instead of a `ChatCompletionModel`; `SdkAgent` / `createAgent` construct with `{ client, model, modelConfig }`; `GenerateImageTool` calls `client.images.generate`
+- **Plugin mechanism promoted to core** — `AgentPlugin` / `SendContext` / `HookResult` now live in `@ai-zen/agents-core` (re-exported by the SDK for compatibility). `SdkAgent` no longer implements its own `use` / `init` / hook iteration, and the `onUnknownTool` property hack is gone — it inherits everything from Core `Agent`
+- **`SdkAgent.defaultUnknownTool` override removed** — the MCP-aware unknown-tool hint moved out of the class into a standalone plugin (see `UnknownToolHintPlugin` below); Core `Agent` now keeps only a simple built-in hint
+- **`SdkAgent.permissions` field removed** — the Agent no longer carries its own `permissions` copy; read `agent.definition.permissions` instead (single source of truth). `AutoRefreshToolsPlugin` and `call_skill_sub_agent` were updated accordingly
+- **`ContextGuardPlugin` default `ratio` changed from 1.2 to 1.5** — the guard now trips at 50% over `maxTokens` (user setting) instead of 20%
+
+### 🚀 New Features
+
+- **`UnknownToolHintPlugin`** — new standalone plugin providing the MCP-aware unknown-tool hint (replaces the removed `SdkAgent.defaultUnknownTool` override). Register explicitly: `agent.use(new UnknownToolHintPlugin({ provider }))`; without it, unknown tools fall back to Core's simple built-in hint
+- **`Model.vision` field + self-declared tool availability** — models can be marked `vision: true`. `SdkCallbackTool` gains `isAvailable(config, definition)`: tools **self-declare** availability by directly inspecting the full app config and agent definition (e.g. `GenerateImageTool` requires `defaultImageModel`, `ViewImageTool` requires a vision model). All **19 built-in tools** live in `BUILTIN_TOOL_CLASSES` (discovery does no filtering); `Provider.filter`/`buildTools` take the `AgentDefinition` and call `isAvailable` at build time (when the model is already known) to filter the final tool set — no hard-coded tool names, and no runtime duplication (vision checks live only in `ViewImageTool.isAvailable`)
+- **`ViewImageTool`** — let the Agent view/analyze an image (vision models only): a network URL returns an `image_url` content block; a local path is auto-uploaded via the Files API (`client.files.create`, `purpose: "user_data"`) and returned as a `file` content block (no base64). Always registered as a built-in candidate; filtered out by `buildTools` for non-vision models (a runtime check remains as a defensive guard)
+- **`GenerateImageTool` returns a plain string** — it always returns JSON text with the image URLs plus `viewImage` / `downloadFile` hints; how the generated image is consumed (view / download / forward) is left to the model and the caller, instead of forcing image content blocks on vision models
+- **`SdkCallbackTool.exec` passes content-section arrays through** — aligned with Core's `Tool.exec` returning `AgentNS.MessageContent`; other values are still JSON-serialized
+
+### 🎯 Optimized
+
+- `createAgent` / `subAgentTools` / `skillTools` adapted to the new Agent constructor (`{ client, model, modelConfig }`)
+- The plugins (`AutoMigratePlugin` / `AutoRefreshToolsPlugin` / `ContextGuardPlugin` / `UnknownToolHintPlugin`) now type their hooks from core's `AgentPlugin` / `HookResult`
+
+### ✅ Tests
+
+- Adapted `createModel` / `SdkAgent` / `Provider` / `createAgent` / `AutoRefreshToolsPlugin` / `ContextGuardPlugin` / `skillTools` / e2e tests to the core 4.0.0 API — all green (incl. real DeepSeek API e2e)
+
 ## [0.6.0] - 2026-08-14
 
 ### ⚠️ Breaking

package/README.md

@@ -23,7 +23,7 @@ config       ← read/write config.json + migration + in-memory cache + atomic w
 crud         ← capability-entity CRUD (Agent definitions, etc.; conversations/drafts are persisted by each consumer)
 capabilities ← capability discovery & assembly (built-in + user + MCP + Skill + SubAgent)
 runtime      ← Provider + model factory + Agent assembly + MCP connection management + task migration + SdkCallbackTool base
-plugin       ← Agent plugins (autoMigrate, autoRefreshTools)
+plugin       ← Agent plugins (autoMigrate, autoRefreshTools, contextGuard, unknownToolHint)
 shared       ← logging, errors
 ```
 
@@ -78,9 +78,9 @@ await agent.send("Hello");
 | `crud` | ✅ Implemented — capability-entity CRUD for Agents, etc. (conversations/drafts persisted by each consumer) |
 | `capabilities` | ✅ Implemented — discovery + permission filtering + safe pre-filtering + enumeration disclosure |
 | `runtime` | ✅ Implemented — Provider, Capabilities, createAgent, MCP connection management, task migration |
-| `plugin` | ✅ Implemented — AutoMigratePlugin / AutoRefreshToolsPlugin |
+| `plugin` | ✅ Implemented — AutoMigratePlugin / AutoRefreshToolsPlugin / ContextGuardPlugin / UnknownToolHintPlugin |
 | `shared` | ✅ Implemented — SdkError + injectable Logger |
-| Tests | ✅ 409 tests, 47 files, all passing (incl. real-API chat e2e) |
+| Tests | ✅ 445 passing, 51 files, all green (incl. real-API chat & viewImage e2e) |
 
 ## Built-in Tools
 
@@ -106,11 +106,12 @@ All built-in tools are classes (extending `SdkCallbackTool`), instantiated by th
 | `edit` | Edit text in a file |
 | `sleep` | Wait for a specified number of milliseconds |
 
-Conditionally injected (registered only when `defaultImageModel` is configured):
+Conditionally injected based on the active model / config:
 
-| Tool | Description |
-|------|-------------|
-| `generateImage` | Generate an image from a text description |
+| Tool | Injection Condition | Description |
+|------|---------------------|-------------|
+| `generateImage` | Only when `defaultImageModel` is configured | Generate an image from a text description |
+| `viewImage` | Only for vision models (the agent's `modelId` resolves to a model with `vision: true`) | View / analyze an image: local images are auto-uploaded via the Files API, network URLs are referenced directly |
 
 ## Built-in Plugins
 
@@ -118,6 +119,8 @@ Conditionally injected (registered only when `defaultImageModel` is configured):
 |--------|-------------|
 | `AutoMigratePlugin` | Automatically triggers task migration when the context overflows, generates a handoff document, and transparently replaces the Agent |
 | `AutoRefreshToolsPlugin` | Re-scans the file system before each `send()` to refresh the tool list |
+| `ContextGuardPlugin` | Context safety guard — before each request, throws `ContextOverflowError` (interrupting the conversation) when the previous round's `usage.prompt_tokens` exceeds `maxTokens × ratio` (default 1.5), preventing context runaway from reading oversized files |
+| `UnknownToolHintPlugin` | Smarter unknown-tool hints — when the LLM calls a nonexistent tool, guides it to `call_mcp_tool` / points out permission issues based on MCP config (opt-in via `agent.use`) |
 
 ## Design Principles
 

package/README.zh.md

@@ -22,7 +22,7 @@ config       ← 读写 config.json + 迁移 + 内存缓存 + 原子写入
 crud         ← 能力实体 CRUD（Agent 定义等；会话/草稿已下放给各端自行持久化）
 capabilities ← 能力发现与装配（内置 + 用户 + MCP + Skill + SubAgent）
 runtime      ← Provider + 模型工厂 + Agent 组装 + MCP 连接管理 + 任务迁移 + SdkCallbackTool 工具基类
-plugin       ← Agent 插件（autoMigrate、autoRefreshTools）
+plugin       ← Agent 插件（autoMigrate、autoRefreshTools、contextGuard、unknownToolHint）
 shared       ← 日志、错误
 ```
 
@@ -77,9 +77,9 @@ await agent.send("你好");
 | `crud` | ✅ 已实现 — Agent 等能力实体 CRUD（会话/草稿由各端自行持久化） |
 | `capabilities` | ✅ 已实现 — 发现 + 权限过滤 + 安全预过滤 + 枚举披露 |
 | `runtime` | ✅ 已实现 — Provider、Capabilities、createAgent、MCP 连接管理、任务迁移 |
-| `plugin` | ✅ 已实现 — AutoMigratePlugin / AutoRefreshToolsPlugin |
+| `plugin` | ✅ 已实现 — AutoMigratePlugin / AutoRefreshToolsPlugin / ContextGuardPlugin / UnknownToolHintPlugin |
 | `shared` | ✅ 已实现 — SdkError + 可注入 Logger |
-| 测试 | ✅ 409 个测试，47 个文件，全通过（含真实 API 聊天 e2e） |
+| 测试 | ✅ 445 通过，51 个文件，全绿（含真实 API 聊天与 viewImage e2e） |
 
 ## 内置工具
 
@@ -105,11 +105,12 @@ await agent.send("你好");
 | `edit` | 编辑文件中的文本 |
 | `sleep` | 等待指定毫秒数后继续 |
 
-条件注入（`GenerateImageTool` 需配置 `defaultImageModel` 才注册）：
+条件注入（按当前模型 / 配置决定是否注册）：
 
-| 工具 | 说明 |
-|------|------|
-| `generateImage` | 根据文字描述生成图片 |
+| 工具 | 注入条件 | 说明 |
+|------|----------|------|
+| `generateImage` | 配置了 `defaultImageModel` 才注册 | 根据文字描述生成图片 |
+| `viewImage` | 仅视觉模型可用（Agent 的 `modelId` 解析为 `vision: true` 的模型） | 查看/分析图片：本地图片自动经 Files API 上传，网络 URL 直接引用 |
 
 ## 内置插件
 
@@ -117,6 +118,8 @@ await agent.send("你好");
 |------|------|
 | `AutoMigratePlugin` | 上下文超限时自动触发任务迁移，生成交接文档，透明替换 Agent |
 | `AutoRefreshToolsPlugin` | 每次 `send()` 前重新扫描文件系统，刷新工具列表 |
+| `ContextGuardPlugin` | 上下文安全护栏 — 每轮发请求前检测上一轮 `usage.prompt_tokens`，超过 `maxTokens × ratio`（默认 1.5，即 +50%）时抛 `ContextOverflowError` 中断对话，防止读入超大文件导致上下文失控 |
+| `UnknownToolHintPlugin` | 未知工具智能提示 — LLM 调用不存在的工具时，根据 MCP 配置引导使用 `call_mcp_tool` / 提示权限问题（调用方显式 `agent.use` 注册） |
 
 ## 设计原则
 

package/dist/capabilities/discovery/builtin.d.ts

@@ -1,9 +1,9 @@
 import type { Tool } from "@ai-zen/agents-core";
 import type { ToolEnv } from "../../types/index.js";
 /**
- * 发现内置工具：用 ToolEnv 实例化全部内置工具类。
+ * 发现内置工具：按静态注册表实例化全部内置工具（无任何过滤）。
  *
- * generateImage 依赖图片模型配置（defaultImageModel），未配置时不注册，
- * 因此不进入 BUILTIN_TOOL_CLASSES 静态注册表，在此按条件实例化。
+ * 工具的可用性由各工具自行声明（SdkCallbackTool.isAvailable，入参含完整 config
+ * + 模型信息），在 buildTools/filter 阶段（模型已知）按声明过滤。
  */
 export declare function discoverBuiltinTools(env: ToolEnv): Tool[];

package/dist/capabilities/discovery/builtin.js

@@ -1,18 +1,10 @@
 import { BUILTIN_TOOL_CLASSES } from "../implements/builtin/index.js";
-import { GenerateImageTool } from "../implements/builtin/GenerateImageTool.js";
 /**
- * 发现内置工具：用 ToolEnv 实例化全部内置工具类。
+ * 发现内置工具：按静态注册表实例化全部内置工具（无任何过滤）。
  *
- * generateImage 依赖图片模型配置（defaultImageModel），未配置时不注册，
- * 因此不进入 BUILTIN_TOOL_CLASSES 静态注册表，在此按条件实例化。
+ * 工具的可用性由各工具自行声明（SdkCallbackTool.isAvailable，入参含完整 config
+ * + 模型信息），在 buildTools/filter 阶段（模型已知）按声明过滤。
  */
 export function discoverBuiltinTools(env) {
-    const tools = BUILTIN_TOOL_CLASSES.map((Cls) => new Cls(env));
-    if (env.config.defaultImageModel) {
-        const existingNames = new Set(tools.map((t) => t.function.name));
-        if (!existingNames.has("generateImage")) {
-            tools.push(new GenerateImageTool(env));
-        }
-    }
-    return tools;
+    return BUILTIN_TOOL_CLASSES.map((Cls) => new Cls(env));
 }

package/dist/capabilities/implements/builtin/GenerateImageTool.d.ts

@@ -1,17 +1,17 @@
 import type { AgentNS, ToolCallContext } from "@ai-zen/agents-core";
 import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
-import type { ToolEnv } from "../../../types/index.js";
+import type { AgentDefinition, AppConfig, ToolEnv } from "../../../types/index.js";
 /**
- * 根据文字描述生成图片。返回图片 URL，可通过 downloadFile 工具保存到本地。
+ * 根据文字描述生成图片。**统一返回字符串**（JSON，含图片 URL 列表）：
+ * 生成结果如何处理（查看/下载/转发）由模型与上层自由决定——
+ * 需要让模型看图时，模型可主动调用 viewImage(URL)；需要保存时用 downloadFile。
  *
- * 依赖 AppConfig 中的 imageModels 和 defaultImageModel 配置。
- * 如果未配置图片模型，工具会返回错误提示。
- *
- * 注意：与其它内置工具不同，generateImage 依赖图片模型配置，
- * 因此由 discoverBuiltinTools 按 env.config.defaultImageModel 条件实例化，
- * 不加入 BUILTIN_TOOL_CLASSES 静态注册表。
+ * 依赖 AppConfig 中的 imageModels 和 defaultImageModel 配置（isAvailable 声明），
+ * 未配置时由 buildTools 过滤，不暴露给 Agent。
  */
 export declare class GenerateImageTool extends SdkCallbackTool {
+    /** 依赖图片模型配置（defaultImageModel），未配置时由 buildTools 按 isAvailable 过滤 */
+    isAvailable(config: AppConfig, _definition: AgentDefinition): boolean;
     function: AgentNS.FunctionDefine;
     constructor(env: ToolEnv);
     call(input: {

package/dist/capabilities/implements/builtin/GenerateImageTool.js

@@ -1,19 +1,21 @@
-import { OpenAI, ZhipuImage } from "@ai-zen/agents-core";
+import OpenAI from "openai";
 import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
 /**
- * 根据文字描述生成图片。返回图片 URL，可通过 downloadFile 工具保存到本地。
+ * 根据文字描述生成图片。**统一返回字符串**（JSON，含图片 URL 列表）：
+ * 生成结果如何处理（查看/下载/转发）由模型与上层自由决定——
+ * 需要让模型看图时，模型可主动调用 viewImage(URL)；需要保存时用 downloadFile。
  *
- * 依赖 AppConfig 中的 imageModels 和 defaultImageModel 配置。
- * 如果未配置图片模型，工具会返回错误提示。
- *
- * 注意：与其它内置工具不同，generateImage 依赖图片模型配置，
- * 因此由 discoverBuiltinTools 按 env.config.defaultImageModel 条件实例化，
- * 不加入 BUILTIN_TOOL_CLASSES 静态注册表。
+ * 依赖 AppConfig 中的 imageModels 和 defaultImageModel 配置（isAvailable 声明），
+ * 未配置时由 buildTools 过滤，不暴露给 Agent。
  */
 export class GenerateImageTool extends SdkCallbackTool {
+    /** 依赖图片模型配置（defaultImageModel），未配置时由 buildTools 按 isAvailable 过滤 */
+    isAvailable(config, _definition) {
+        return !!config.defaultImageModel;
+    }
     function = {
         name: "generateImage",
-        description: "根据文字描述生成图片。返回图片 URL，可通过 downloadFile 工具保存到本地。",
+        description: "根据文字描述生成图片，返回图片 URL 列表（JSON）。如需查看图片内容，请用 viewImage 工具（传入图片 URL）；如需保存到本地，用 downloadFile 下载。",
         parameters: {
             type: "object",
             properties: {
@@ -81,34 +83,31 @@ export class GenerateImageTool extends SdkCallbackTool {
                     error: `端点 "${endpoint.name}" 的 API Key 未设置`,
                 });
             }
-            const ep = new OpenAI({
-                openai_endpoint: endpoint.baseUrl,
-                api_key: endpoint.apiKey,
+            const client = new OpenAI({
+                apiKey: endpoint.apiKey,
+                baseURL: endpoint.baseUrl,
             });
             const modelName = input.model || imageModel.modelName;
-            const model = new ZhipuImage({
-                request_config: await ep.imageGeneration(modelName),
-            });
-            const result = await model.generate({
-                prompt: prompt.trim(),
+            // 通过官方 SDK 生成图片（厂商特有字段如 size/quality 用 any 透传）
+            const result = await client.images.generate({
                 model: modelName,
+                prompt: prompt.trim(),
                 size: input.size || imageModel.defaultSize || undefined,
                 quality: input.quality || imageModel.defaultQuality || undefined,
-                signal,
-            });
-            const images = result.data.map((img, i) => ({
-                index: i,
-                url: img.url,
-                description: `图片 ${i + 1}`,
-            }));
+            }, { signal });
+            const urls = (result.data ?? [])
+                .map((img) => img.url)
+                .filter((url) => !!url);
+            // 统一返回字符串（JSON）：生成结果如何处理（查看/下载/转发）由模型与上层自由决定，
+            // 不替模型做「看或不看」的假设。需要让模型看图 → 模型可主动调用 viewImage(URL)；
+            // 需要保存 → downloadFile 下载。
             return JSON.stringify({
                 success: true,
                 model: imageModel.name,
                 modelId: imageModel.id,
                 created: result.created,
-                images,
-                content_filter: result.content_filter || [],
-                note: "图片临时链接有效期为30天，请及时转存图片。",
+                images: urls.map((url, i) => ({ index: i, url })),
+                note: "图片临时链接有效期为30天。如需查看图片内容，可用 viewImage 工具（传入图片 URL）；如需保存，可用 downloadFile 下载。",
             }, null, 2);
         }
         catch (error) {

package/dist/capabilities/implements/builtin/ViewImageTool.d.ts

@@ -0,0 +1,24 @@
+import type { AgentNS, ToolCallContext } from "@ai-zen/agents-core";
+import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+import type { AgentDefinition, AppConfig, ToolEnv } from "../../../types/index.js";
+/**
+ * 查看图片工具 — 让 Agent 主动查看/分析一张图片。**仅对视觉模型可用**：
+ * 由 `isAvailable(config, definition)` 声明（从 definition.modelId 解析模型，检查 Model.vision），
+ * buildTools 阶段按声明过滤——非视觉模型不会拿到该工具，故无需运行时重复校验。
+ *
+ * 输入 `path_or_url`：
+ *   - http(s) URL → 直接以 `image_url` 内容块返回，模型直接查看；
+ *   - 本地路径 → 自动通过 Files API（DeepSeek）上传，以 `file` 内容块（file_id）返回。
+ *
+ * 不使用 base64 内联（本地图片走 Files API，符合 DeepSeek 推荐与 48 MiB 请求体限制）。
+ * 依赖配置中的 deepseek 端点（Files API 能力）；URL 场景不依赖上传。
+ */
+export declare class ViewImageTool extends SdkCallbackTool {
+    /** 仅视觉模型可用：从 definition.modelId 解析当前模型，非视觉模型由 buildTools 过滤 */
+    isAvailable(config: AppConfig, definition: AgentDefinition): boolean;
+    function: AgentNS.FunctionDefine;
+    constructor(env: ToolEnv);
+    call(input: {
+        path_or_url?: string;
+    }, ctx?: ToolCallContext): Promise<AgentNS.MessageContent>;
+}

package/dist/capabilities/implements/builtin/ViewImageTool.js

@@ -0,0 +1,109 @@
+import OpenAI, { toFile } from "openai";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+const SUPPORTED_EXT = [".jpg", ".jpeg", ".png", ".gif", ".webp"];
+/**
+ * 查看图片工具 — 让 Agent 主动查看/分析一张图片。**仅对视觉模型可用**：
+ * 由 `isAvailable(config, definition)` 声明（从 definition.modelId 解析模型，检查 Model.vision），
+ * buildTools 阶段按声明过滤——非视觉模型不会拿到该工具，故无需运行时重复校验。
+ *
+ * 输入 `path_or_url`：
+ *   - http(s) URL → 直接以 `image_url` 内容块返回，模型直接查看；
+ *   - 本地路径 → 自动通过 Files API（DeepSeek）上传，以 `file` 内容块（file_id）返回。
+ *
+ * 不使用 base64 内联（本地图片走 Files API，符合 DeepSeek 推荐与 48 MiB 请求体限制）。
+ * 依赖配置中的 deepseek 端点（Files API 能力）；URL 场景不依赖上传。
+ */
+export class ViewImageTool extends SdkCallbackTool {
+    /** 仅视觉模型可用：从 definition.modelId 解析当前模型，非视觉模型由 buildTools 过滤 */
+    isAvailable(config, definition) {
+        const modelId = definition.modelId ?? config.defaultModel;
+        const model = (config.models ?? []).find((m) => m.id === modelId);
+        return model?.vision === true;
+    }
+    function = {
+        name: "viewImage",
+        description: "查看一张图片并分析其内容。传入本地图片路径或 http(s) 图片 URL。本地图片会自动上传（Files API）后引用，网络图片直接引用。适合识别图片文字、描述图片内容、分析图表等。",
+        parameters: {
+            type: "object",
+            properties: {
+                path_or_url: {
+                    type: "string",
+                    description: "本地图片路径（相对/绝对）或 http(s) 图片 URL。支持的格式：JPEG、PNG、GIF、WebP。",
+                },
+            },
+            required: ["path_or_url"],
+            additionalProperties: false,
+        },
+    };
+    constructor(env) {
+        super({ env });
+    }
+    async call(input, ctx) {
+        const signal = ctx?.signal;
+        const target = input?.path_or_url;
+        if (!target || !target.trim()) {
+            return "viewImage 需要提供 path_or_url 参数（本地图片路径或 http(s) URL）。";
+        }
+        const value = target.trim();
+        try {
+            // 网络图片：直接返回 image_url 内容块（无需上传）
+            if (/^https?:\/\//i.test(value)) {
+                return [
+                    {
+                        type: "text",
+                        text: `已获取网络图片：${value}`,
+                    },
+                    { type: "image_url", image_url: { url: value } },
+                ];
+            }
+            // 本地图片：解析路径 + 校验 + Files API 上传
+            const absPath = path.isAbsolute(value)
+                ? value
+                : path.join(this.env.cwd, value);
+            let stat;
+            try {
+                stat = await fs.stat(absPath);
+            }
+            catch {
+                return `本地图片不存在: ${absPath}`;
+            }
+            if (!stat.isFile()) {
+                return `"${absPath}" 不是文件。`;
+            }
+            const ext = path.extname(absPath).toLowerCase();
+            if (!SUPPORTED_EXT.includes(ext)) {
+                return `不支持的图片格式 "${ext || "(无扩展名)"}"。支持的格式：JPEG、PNG、GIF、WebP。`;
+            }
+            // 上传端点：deepseek（Files API 能力）
+            const endpoint = (this.env.config.endpoints ?? []).find((e) => e.id === "deepseek");
+            if (!endpoint) {
+                return "未配置 deepseek 端点，无法上传本地图片（Files API）。如需查看本地图片，请先配置 deepseek 端点；网络图片 URL 可直接使用。";
+            }
+            if (!endpoint.apiKey) {
+                return `端点 "${endpoint.name}" 的 API Key 未设置，无法上传本地图片。`;
+            }
+            const client = new OpenAI({
+                apiKey: endpoint.apiKey,
+                baseURL: endpoint.baseUrl,
+            });
+            const file = await toFile(await fs.readFile(absPath), path.basename(absPath));
+            const uploaded = await client.files.create({ file, purpose: "user_data" }, { signal });
+            return [
+                {
+                    type: "text",
+                    text: `图片已上传（${path.basename(absPath)}），file_id: ${uploaded.id}`,
+                },
+                { type: "file", file_id: uploaded.id },
+            ];
+        }
+        catch (error) {
+            // 中断（abort）时返回明确的中断结果
+            if (signal?.aborted) {
+                return "图片查看被中断（aborted）";
+            }
+            return `查看图片失败: ${error instanceof Error ? error.message : String(error)}`;
+        }
+    }
+}

package/dist/capabilities/implements/builtin/index.d.ts

@@ -17,13 +17,15 @@ import { BatchEditTool } from "./BatchEditTool.js";
 import { EditTool } from "./EditTool.js";
 import { ExecAsyncTool } from "./ExecAsyncTool.js";
 import { SleepTool } from "./SleepTool.js";
+import { ViewImageTool } from "./ViewImageTool.js";
 import { GenerateImageTool } from "./GenerateImageTool.js";
 /**
- * 17 个无条件注册的内置工具类。
+ * 全部内置工具类（19 个）。
  * 工具类由 Provider 用 ToolEnv 实例化（每个 Provider 一套实例，注入其 cwd）。
  *
- * 注意：GenerateImageTool 依赖图片模型配置（defaultImageModel），
- * 由 discoverBuiltinTools 按条件实例化，不在此静态注册表中。
+ * 发现层不做任何过滤——工具的可用性由各工具自行声明（SdkCallbackTool.isAvailable，
+ * 入参含完整 config + 模型信息），在 buildTools/filter 阶段按声明过滤。
+ * 如 GenerateImageTool 依赖 defaultImageModel、ViewImageTool 仅视觉模型可用。
  */
 export declare const BUILTIN_TOOL_CLASSES: Array<new (env: ToolEnv) => SdkCallbackTool>;
-export { CwdTool, ReadFileTool, WriteFileTool, ExecTool, MkdirTool, RmTool, GlobTool, LsTool, ExistTool, FindTextTool, DownloadFileTool, RenameTool, CopyTool, BatchEditTool, EditTool, ExecAsyncTool, SleepTool, GenerateImageTool, };
+export { CwdTool, ReadFileTool, WriteFileTool, ExecTool, MkdirTool, RmTool, GlobTool, LsTool, ExistTool, FindTextTool, DownloadFileTool, RenameTool, CopyTool, BatchEditTool, EditTool, ExecAsyncTool, SleepTool, ViewImageTool, GenerateImageTool, };

package/dist/capabilities/implements/builtin/index.js

@@ -15,13 +15,15 @@ import { BatchEditTool } from "./BatchEditTool.js";
 import { EditTool } from "./EditTool.js";
 import { ExecAsyncTool } from "./ExecAsyncTool.js";
 import { SleepTool } from "./SleepTool.js";
+import { ViewImageTool } from "./ViewImageTool.js";
 import { GenerateImageTool } from "./GenerateImageTool.js";
 /**
- * 17 个无条件注册的内置工具类。
+ * 全部内置工具类（19 个）。
  * 工具类由 Provider 用 ToolEnv 实例化（每个 Provider 一套实例，注入其 cwd）。
  *
- * 注意：GenerateImageTool 依赖图片模型配置（defaultImageModel），
- * 由 discoverBuiltinTools 按条件实例化，不在此静态注册表中。
+ * 发现层不做任何过滤——工具的可用性由各工具自行声明（SdkCallbackTool.isAvailable，
+ * 入参含完整 config + 模型信息），在 buildTools/filter 阶段按声明过滤。
+ * 如 GenerateImageTool 依赖 defaultImageModel、ViewImageTool 仅视觉模型可用。
  */
 export const BUILTIN_TOOL_CLASSES = [
     CwdTool,
@@ -41,5 +43,7 @@ export const BUILTIN_TOOL_CLASSES = [
     EditTool,
     ExecAsyncTool,
     SleepTool,
+    ViewImageTool,
+    GenerateImageTool,
 ];
-export { CwdTool, ReadFileTool, WriteFileTool, ExecTool, MkdirTool, RmTool, GlobTool, LsTool, ExistTool, FindTextTool, DownloadFileTool, RenameTool, CopyTool, BatchEditTool, EditTool, ExecAsyncTool, SleepTool, GenerateImageTool, };
+export { CwdTool, ReadFileTool, WriteFileTool, ExecTool, MkdirTool, RmTool, GlobTool, LsTool, ExistTool, FindTextTool, DownloadFileTool, RenameTool, CopyTool, BatchEditTool, EditTool, ExecAsyncTool, SleepTool, ViewImageTool, GenerateImageTool, };

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]