@ai-zen/agents-sdk 0.6.0 → 0.7.1

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## [0.7.1] - 2026-08-25
+
+### 🚀 New Features
+
+- **`FindTextTool` (findText) gains three-layer output protection** — prevents search results from blowing up the context window:
+  - **`maxMatches`** (default 200) — caps the total number of matches; once reached, scanning stops and the result is marked `truncated`
+  - **`maxFileSize`** (default 300KB, aligned with `ReadFileTool`) — files larger than this are **skipped** rather than rejected, so an oversized file doesn't block the whole search
+  - **`maxLineLength`** (default 200) — each matched line's `content` and the regex `match` substring are truncated (with a trailing `…`)
+  - All three are optional parameters that can be overridden by the caller; when truncated the result returns `{ truncated: true, totalMatches, results }`, while non-truncated results keep the original JSON array shape (backward compatible)
+
+## [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/FindTextTool.d.ts

@@ -10,5 +10,8 @@ export declare class FindTextTool extends SdkCallbackTool {
         text?: string;
         regex?: string;
         exclude?: string[];
+        maxMatches?: number;
+        maxFileSize?: number;
+        maxLineLength?: number;
     }, ctx?: ToolCallContext): Promise<string>;
 }

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

@@ -1,10 +1,16 @@
 import * as fsp from "fs/promises";
 import * as path from "path";
 import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
+/** 默认总匹配数上限 */
+const DEFAULT_MAX_MATCHES = 200;
+/** 默认文件大小上限（字节，与 ReadFileTool 的 300KB 口径一致） */
+const DEFAULT_MAX_FILE_SIZE = 300 * 1024;
+/** 默认行内容/匹配子串截断长度 */
+const DEFAULT_MAX_LINE_LENGTH = 200;
 export class FindTextTool extends SdkCallbackTool {
     function = {
         name: "findText",
-        description: "查找文本出现的位置，支持普通文本或正则匹配，返回文件名及具体行号、行内容",
+        description: "查找文本出现的位置，支持普通文本或正则匹配，返回文件名及具体行号、行内容。为避免结果撑爆上下文，默认限制总匹配数、单文件大小与行内容长度，超限会截断并标记 truncated。",
         parameters: {
             type: "object",
             properties: {
@@ -31,6 +37,18 @@ export class FindTextTool extends SdkCallbackTool {
                         type: "string",
                     },
                 },
+                maxMatches: {
+                    type: "number",
+                    description: "总匹配数上限，默认 200",
+                },
+                maxFileSize: {
+                    type: "number",
+                    description: "单文件大小上限（字节），超过则跳过该文件，默认 307200（300KB）",
+                },
+                maxLineLength: {
+                    type: "number",
+                    description: "行内容与匹配子串的截断长度，默认 200",
+                },
             },
             required: ["path", "pattern"],
         },
@@ -49,48 +67,70 @@ export class FindTextTool extends SdkCallbackTool {
                 return "请提供 text 或 regex 参数";
             }
             const regex = regexStr ? new RegExp(regexStr) : null;
+            const maxMatches = input.maxMatches ?? DEFAULT_MAX_MATCHES;
+            const maxFileSize = input.maxFileSize ?? DEFAULT_MAX_FILE_SIZE;
+            const maxLineLength = input.maxLineLength ?? DEFAULT_MAX_LINE_LENGTH;
+            let totalMatches = 0;
+            let truncated = false;
             for await (const file of fsp.glob(input.pattern, {
                 cwd,
                 exclude: input.exclude || ["**/node_modules/**"],
             })) {
                 if (signal?.aborted)
                     break; // 中断：停止继续遍历/消费
+                if (totalMatches >= maxMatches) {
+                    truncated = true;
+                    break;
+                }
                 const fullPath = path.join(cwd, file);
                 const stats = await fsp.stat(fullPath);
                 if (signal?.aborted)
                     break; // 中断：stat 后再次检查
-                if (stats.isFile()) {
-                    const content = await fsp.readFile(fullPath, "utf-8");
-                    if (signal?.aborted)
-                        break; // 中断：readFile 后再次检查
-                    const lines = content.split("\n");
-                    const matches = [];
-                    lines.forEach((lineContent, index) => {
-                        if (regex) {
-                            const matchResult = lineContent.match(regex);
-                            if (matchResult) {
-                                matches.push({
-                                    line: index + 1,
-                                    content: lineContent,
-                                    match: matchResult[0],
-                                });
-                            }
-                        }
-                        else if (lineContent.includes(text)) {
+                if (!stats.isFile())
+                    continue;
+                // 文件过大则跳过（避免撑爆上下文；与 ReadFileTool 300KB 口径一致，但此处为跳过而非报错）
+                if (stats.size > maxFileSize)
+                    continue;
+                const content = await fsp.readFile(fullPath, "utf-8");
+                if (signal?.aborted)
+                    break; // 中断：readFile 后再次检查
+                const lines = content.split("\n");
+                const matches = [];
+                for (let index = 0; index < lines.length; index++) {
+                    if (totalMatches >= maxMatches) {
+                        truncated = true;
+                        break;
+                    }
+                    const lineContent = lines[index];
+                    if (regex) {
+                        const matchResult = lineContent.match(regex);
+                        if (matchResult) {
                             matches.push({
                                 line: index + 1,
-                                content: lineContent,
+                                content: truncate(lineContent, maxLineLength),
+                                match: truncate(matchResult[0], maxLineLength),
                             });
+                            totalMatches++;
                         }
-                    });
-                    if (matches.length > 0) {
-                        result.push({ file, matches });
                     }
+                    else if (lineContent.includes(text)) {
+                        matches.push({
+                            line: index + 1,
+                            content: truncate(lineContent, maxLineLength),
+                        });
+                        totalMatches++;
+                    }
+                }
+                if (matches.length > 0) {
+                    result.push({ file, matches });
                 }
             }
             if (signal?.aborted) {
                 return JSON.stringify({ aborted: true, results: result });
             }
+            if (truncated) {
+                return JSON.stringify({ truncated: true, totalMatches, results: result });
+            }
             return JSON.stringify(result);
         }
         catch (error) {
@@ -98,3 +138,9 @@ export class FindTextTool extends SdkCallbackTool {
         }
     }
 }
+/** 截断字符串到指定长度，超出部分以 "…" 结尾标记 */
+function truncate(s, max) {
+    if (s.length <= max)
+        return s;
+    return s.slice(0, max) + "…";
+}

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