@ai-zen/agents-sdk 1.0.0-alpha.2 → 1.0.0-alpha.21

package/dist/scope/plugins/builtin/ExecTool.js

@@ -14,7 +14,7 @@ export class ExecTool extends SdkCallbackTool {
                 },
                 timeout: {
                     type: "number",
-                    description: "超时时间（毫秒），必填。超时后会终止进程；超过该时长仍未完成即视为超时并终止。建议长时间运行的命令使用 exec_async 异步执行。",
+                    description: "超时时间（毫秒），必填。超时后会终止进程；超过该时长仍未完成即视为超时并终止。建议长时间运行的命令使用 spawn 异步执行。",
                 },
             },
             required: ["command", "timeout"],
@@ -98,7 +98,7 @@ export class ExecTool extends SdkCallbackTool {
                 return JSON.stringify({
                     outputTooLarge: true,
                     warning: `输出过大：stdout + stderr 合计 ${result.stdout.length + result.stderr.length} 字符，` +
-                        `超过上限 ${limit} 字符。完整内容已分文件落盘（stdout.log / stderr.log），可用 readFile 分批读取。`,
+                        `超过上限 ${limit} 字符。完整内容已分文件落盘（stdout.log / stderr.log），可用 read 分批读取。`,
                     files: ctx.files,
                     stdout: { chars: result.stdout.length, lines: countLines(result.stdout), ...stdout },
                     stderr: { chars: result.stderr.length, lines: countLines(result.stderr), ...stderr },

package/dist/scope/plugins/builtin/FindTextTool.js

@@ -4,13 +4,13 @@ import { SdkCallbackTool } from "./SdkCallbackTool.js";
 import { DEFAULT_MAX_TOOL_OUTPUT, guardOutput, headPreview } from "./outputGuard.js";
 /** 默认总匹配数上限 */
 const DEFAULT_MAX_MATCHES = 200;
-/** 默认文件大小上限（字节，与 ReadFileTool 的 300KB 口径一致） */
+/** 默认文件大小上限（字节，与 ReadTool 的 300KB 口径一致） */
 const DEFAULT_MAX_FILE_SIZE = 300 * 1024;
 /** 默认行内容/匹配子串截断长度 */
 const DEFAULT_MAX_LINE_LENGTH = 200;
 export class FindTextTool extends SdkCallbackTool {
     function = {
-        name: "findText",
+        name: "find_text",
         description: "查找文本出现的位置，支持普通文本或正则匹配，返回文件名及具体行号、行内容。为避免结果撑爆上下文，默认限制总匹配数、单文件大小与行内容长度，超限会截断并标记 truncated。",
         parameters: {
             type: "object",
@@ -89,12 +89,12 @@ export class FindTextTool extends SdkCallbackTool {
                     break; // 中断：stat 后再次检查
                 if (!stats.isFile())
                     continue;
-                // 文件过大则跳过（避免撑爆上下文；与 ReadFileTool 300KB 口径一致，但此处为跳过而非报错）
+                // 文件过大则跳过（避免撑爆上下文；与 ReadTool 300KB 口径一致，但此处为跳过而非报错）
                 if (stats.size > maxFileSize)
                     continue;
                 const content = await fsp.readFile(fullPath, "utf-8");
                 if (signal?.aborted)
-                    break; // 中断：readFile 后再次检查
+                    break; // 中断：read 后再次检查
                 const lines = content.split("\n");
                 const matches = [];
                 for (let index = 0; index < lines.length; index++) {
@@ -145,7 +145,7 @@ export class FindTextTool extends SdkCallbackTool {
     async protect(json) {
         const limit = this.env.config.maxToolOutput ?? DEFAULT_MAX_TOOL_OUTPUT;
         return await guardOutput({
-            tool: "findText",
+            tool: "find_text",
             content: json,
             isOverLimit: (text) => text.length > limit,
             dump: (_dir, text) => [{ name: "result.json", content: text }],
@@ -154,7 +154,7 @@ export class FindTextTool extends SdkCallbackTool {
                 return JSON.stringify({
                     outputTooLarge: true,
                     warning: `输出过大：结果共 ${json.length} 字符，超过上限 ${limit} 字符。` +
-                        `完整结果已落盘（result.json），可用 readFile 分批读取。`,
+                        `完整结果已落盘（result.json），可用 read 分批读取。`,
                     files: ctx.files,
                     chars: json.length,
                     ...preview,

package/dist/scope/plugins/builtin/GenerateImageTool.d.ts

@@ -4,7 +4,7 @@ import type { AgentDefinition, AppConfig, ToolEnv } from "../../../types/index.j
 /**
  * 根据文字描述生成图片。**统一返回字符串**（JSON，含图片 URL 列表）：
  * 生成结果如何处理（查看/下载/转发）由模型与上层自由决定——
- * 需要让模型看图时，模型可主动调用 viewImage(URL)；需要保存时用 downloadFile。
+ * 需要让模型看图时，模型可主动调用 view_image(URL)；需要保存时用 download_file。
  *
  * 依赖 AppConfig 中的 imageModels 和 defaultImageModel 配置（isAvailable 声明），
  * 未配置时由 buildTools 过滤，不暴露给 Agent。

package/dist/scope/plugins/builtin/GenerateImageTool.js

@@ -3,7 +3,7 @@ import { SdkCallbackTool } from "./SdkCallbackTool.js";
 /**
  * 根据文字描述生成图片。**统一返回字符串**（JSON，含图片 URL 列表）：
  * 生成结果如何处理（查看/下载/转发）由模型与上层自由决定——
- * 需要让模型看图时，模型可主动调用 viewImage(URL)；需要保存时用 downloadFile。
+ * 需要让模型看图时，模型可主动调用 view_image(URL)；需要保存时用 download_file。
  *
  * 依赖 AppConfig 中的 imageModels 和 defaultImageModel 配置（isAvailable 声明），
  * 未配置时由 buildTools 过滤，不暴露给 Agent。
@@ -14,8 +14,8 @@ export class GenerateImageTool extends SdkCallbackTool {
         return !!config.defaultImageModel;
     }
     function = {
-        name: "generateImage",
-        description: "根据文字描述生成图片，返回图片 URL 列表（JSON）。如需查看图片内容，请用 viewImage 工具（传入图片 URL）；如需保存到本地，用 downloadFile 下载。",
+        name: "generate_image",
+        description: "根据文字描述生成图片，返回图片 URL 列表（JSON）。如需查看图片内容，请用 view_image 工具（传入图片 URL）；如需保存到本地，用 download_file 下载。",
         parameters: {
             type: "object",
             properties: {
@@ -25,7 +25,7 @@ export class GenerateImageTool extends SdkCallbackTool {
                 },
                 model: {
                     type: "string",
-                    description: "图片模型 ID，不指定则使用配置中的默认图片模型。配置中的图片模型可通过 'aiz config show' 查看。",
+                    description: "图片模型 ID，不指定则使用配置中的默认图片模型；若指定的模型不存在，本工具会返回当前可用的模型列表。",
                 },
                 size: {
                     type: "string",
@@ -99,15 +99,15 @@ export class GenerateImageTool extends SdkCallbackTool {
                 .map((img) => img.url)
                 .filter((url) => !!url);
             // 统一返回字符串（JSON）：生成结果如何处理（查看/下载/转发）由模型与上层自由决定，
-            // 不替模型做「看或不看」的假设。需要让模型看图 → 模型可主动调用 viewImage(URL)；
-            // 需要保存 → downloadFile 下载。
+            // 不替模型做「看或不看」的假设。需要让模型看图 → 模型可主动调用 view_image(URL)；
+            // 需要保存 → download_file 下载。
             return JSON.stringify({
                 success: true,
                 model: imageModel.name,
                 modelId: imageModel.id,
                 created: result.created,
                 images: urls.map((url, i) => ({ index: i, url })),
-                note: "图片临时链接有效期为30天。如需查看图片内容，可用 viewImage 工具（传入图片 URL）；如需保存，可用 downloadFile 下载。",
+                note: "图片临时链接有效期为30天。如需查看图片内容，可用 view_image 工具（传入图片 URL）；如需保存，可用 download_file 下载。",
             }, null, 2);
         }
         catch (error) {

package/dist/scope/plugins/builtin/GlobTool.js

@@ -69,7 +69,7 @@ export class GlobTool extends SdkCallbackTool {
                 return JSON.stringify({
                     outputTooLarge: true,
                     warning: `输出过大：匹配结果共 ${json.length} 字符，超过上限 ${limit} 字符。` +
-                        `完整结果已落盘（result.json），可用 readFile 分批读取；` +
+                        `完整结果已落盘（result.json），可用 read 分批读取；` +
                         `也可用更精确的 pattern 或 exclude 缩小范围后重新查找。`,
                     files: ctx.files,
                     chars: json.length,

package/dist/scope/plugins/builtin/InspectFileTool.d.ts

@@ -4,8 +4,8 @@ import type { AgentNS } from "@ai-zen/agents-core";
 /**
  * 勘察文件结构概况（行数、每行列数等），不做内容读取。
  *
- * 定位与 readFile 的 range 配套：大文件先看结构（有多少行、每行多长），
- * 再决定 readFile 的读取范围。流式扫描，故不受 readFile 的 300KB 读取阈值限制。
+ * 定位与 read 的 range 配套：大文件先看结构（有多少行、每行多长），
+ * 再决定 read 的读取范围。流式扫描，故不受 read 的 300KB 读取阈值限制。
  */
 export declare class InspectFileTool extends SdkCallbackTool {
     function: AgentNS.FunctionDefine;

package/dist/scope/plugins/builtin/InspectFileTool.js

@@ -6,13 +6,13 @@ import { DEFAULT_MAX_TOOL_OUTPUT } from "./outputGuard.js";
 /**
  * 勘察文件结构概况（行数、每行列数等），不做内容读取。
  *
- * 定位与 readFile 的 range 配套：大文件先看结构（有多少行、每行多长），
- * 再决定 readFile 的读取范围。流式扫描，故不受 readFile 的 300KB 读取阈值限制。
+ * 定位与 read 的 range 配套：大文件先看结构（有多少行、每行多长），
+ * 再决定 read 的读取范围。流式扫描，故不受 read 的 300KB 读取阈值限制。
  */
 export class InspectFileTool extends SdkCallbackTool {
     function = {
-        name: "inspectFile",
-        description: "勘察文件的结构概况：总行数、总字符数、最长行的列数及其行索引、平均列数、行尾类型（LF/CRLF）。可选返回每行的列数映射。适用于在 readFile 之前先了解文件规模，再决定用 range 读取哪一段。仅做流式扫描，不受 readFile 的 300KB 读取阈值限制。",
+        name: "inspect_file",
+        description: "勘察文件的结构概况：总行数、总字符数、最长行的列数及其行索引、平均列数、行尾类型（LF/CRLF）。可选返回每行的列数映射。适用于在 read 之前先了解文件规模，再决定用 range 读取哪一段。仅做流式扫描，不受 read 的 300KB 读取阈值限制。",
         parameters: {
             type: "object",
             properties: {
@@ -63,7 +63,7 @@ export class InspectFileTool extends SdkCallbackTool {
                     colCountMapOmitted: true,
                     warning: `行长度明细过大：概况与 colCountMap 合计 ${payload.length} 字符，` +
                         `超过上限 ${limit} 字符，未落盘返回。文件规模超出可处理范围，` +
-                        `建议改用 findText 定位后再按 range 分段读取。`,
+                        `建议改用 find_text 定位后再按 range 分段读取。`,
                 });
             }
             return payload;

package/dist/scope/plugins/builtin/LsTool.js

@@ -36,7 +36,7 @@ export class LsTool extends SdkCallbackTool {
                     return JSON.stringify({
                         outputTooLarge: true,
                         warning: `输出过大：目录条目共 ${entries.length} 项、${json.length} 字符，超过上限 ${limit} 字符。` +
-                            `完整列表已落盘（result.json），可用 readFile 分批读取；` +
+                            `完整列表已落盘（result.json），可用 read 分批读取；` +
                             `也可改用 glob 按模式筛选。`,
                         files: ctx.files,
                         chars: json.length,

package/dist/scope/plugins/builtin/{ReadFileTool.d.ts → ReadTool.d.ts}

@@ -1,7 +1,7 @@
 import { SdkCallbackTool } from "./SdkCallbackTool.js";
 import type { ToolEnv } from "../../../types/index.js";
 import type { AgentNS } from "@ai-zen/agents-core";
-export declare class ReadFileTool extends SdkCallbackTool {
+export declare class ReadTool extends SdkCallbackTool {
     function: AgentNS.FunctionDefine;
     constructor(env: ToolEnv);
     call(input: {

package/dist/scope/plugins/builtin/{ReadFileTool.js → ReadTool.js}

@@ -1,9 +1,9 @@
 import * as fsp from "fs/promises";
 import { SdkCallbackTool } from "./SdkCallbackTool.js";
 import { DEFAULT_MAX_TOOL_OUTPUT, guardOutput } from "./outputGuard.js";
-export class ReadFileTool extends SdkCallbackTool {
+export class ReadTool extends SdkCallbackTool {
     function = {
-        name: "readFile",
+        name: "read",
         description: "读取文件",
         parameters: {
             type: "object",
@@ -41,7 +41,7 @@ export class ReadFileTool extends SdkCallbackTool {
             // 输出保护：本次返回内容超过上限时只警告、不落盘，并提示用 range 分批读取
             const limit = this.env.config.maxToolOutput ?? DEFAULT_MAX_TOOL_OUTPUT;
             return await guardOutput({
-                tool: "readFile",
+                tool: "read",
                 content: output,
                 isOverLimit: (text) => text.length > limit,
                 buildWarning: () => `读取内容过大：本次输出 ${output.length} 字符，超过上限 ${limit} 字符，未落盘。` +

package/dist/scope/plugins/builtin/{ExecAsyncTool.d.ts → SpawnTool.d.ts}

@@ -1,7 +1,7 @@
 import { SdkCallbackTool } from "./SdkCallbackTool.js";
 import type { ToolEnv } from "../../../types/index.js";
 import type { AgentNS } from "@ai-zen/agents-core";
-export declare class ExecAsyncTool extends SdkCallbackTool {
+export declare class SpawnTool extends SdkCallbackTool {
     function: AgentNS.FunctionDefine;
     constructor(env: ToolEnv);
     call(input: {

package/dist/scope/plugins/builtin/{ExecAsyncTool.js → SpawnTool.js}

@@ -1,8 +1,8 @@
 import { spawn } from "child_process";
 import { SdkCallbackTool } from "./SdkCallbackTool.js";
-export class ExecAsyncTool extends SdkCallbackTool {
+export class SpawnTool extends SdkCallbackTool {
     function = {
-        name: "exec_async",
+        name: "spawn",
         description: "异步执行命令，启动程序后立即返回，不等待执行结果。适用于启动长期运行的进程（如服务器、监听程序、GUI应用等）或不需要等待结果的命令。注意：该工具本身不捕获命令的输出；若需获取/留存输出，可在命令中使用 shell 重定向写入文件（如 `> /path/file`，支持 `>>` 追加、`|` 管道）。命令经 shell 解析执行。",
         parameters: {
             type: "object",

package/dist/scope/plugins/builtin/ViewImageTool.d.ts

@@ -7,11 +7,13 @@ import type { AgentDefinition, AppConfig, ToolEnv } from "../../../types/index.j
  * buildTools 阶段按声明过滤——非视觉模型不会拿到该工具，故无需运行时重复校验。
  *
  * 输入 `path_or_url`：
- *   - http(s) URL → 直接以 `image_url` 内容块返回，模型直接查看；
- *   - 本地路径 → 自动通过 Files API（DeepSeek）上传，以 `file` 内容块（file_id）返回。
+ *   - http(s) URL → 直接以 `image_url` 内容块返回；
+ *   - 本地路径 → 交给 `fileToContentSection()` 统一处理：
+ *       端点声明 `capabilities.filesApi`（出厂仅 deepseek）→ Files API 上传，`file` 块（file_id）；
+ *       其余端点 → base64 data URL 内联（`image_url`），不再要求必须配置 deepseek。
  *
- * 不使用 base64 内联（本地图片走 Files API，符合 DeepSeek 推荐与 48 MiB 请求体限制）。
- * 依赖配置中的 deepseek 端点（Files API 能力）；URL 场景不依赖上传。
+ * 端点按**当前模型**反查（`ctx.agent.model`），不硬编码端点 id——`file_id` 是端点维度
+ * 资源，传错端点会返回 not found。
  */
 export declare class ViewImageTool extends SdkCallbackTool {
     /** 仅视觉模型可用：从 definition.modelId 解析当前模型，非视觉模型由 buildTools 过滤 */

package/dist/scope/plugins/builtin/ViewImageTool.js

@@ -1,8 +1,7 @@
-import OpenAI, { toFile } from "openai";
-import { promises as fs } from "node:fs";
 import path from "node:path";
+import { promises as fs } from "node:fs";
 import { SdkCallbackTool } from "./SdkCallbackTool.js";
-const SUPPORTED_EXT = [".jpg", ".jpeg", ".png", ".gif", ".webp"];
+import { fileToContentSection, mimeOf, resolveModelAndEndpoint } from "../../../shared/content-blocks.js";
 /**
  * 是否为"本地 URL"——指向本地/回环地址，API 服务商无法下载访问。
  * 覆盖 file:// 等本地协议，以及指向本机的 http(s) 地址（localhost、127.0.0.1、[::1]、0.0.0.0）。
@@ -19,22 +18,24 @@ function isLocalUrl(value) {
  * buildTools 阶段按声明过滤——非视觉模型不会拿到该工具，故无需运行时重复校验。
  *
  * 输入 `path_or_url`：
- *   - http(s) URL → 直接以 `image_url` 内容块返回，模型直接查看；
- *   - 本地路径 → 自动通过 Files API（DeepSeek）上传，以 `file` 内容块（file_id）返回。
+ *   - http(s) URL → 直接以 `image_url` 内容块返回；
+ *   - 本地路径 → 交给 `fileToContentSection()` 统一处理：
+ *       端点声明 `capabilities.filesApi`（出厂仅 deepseek）→ Files API 上传，`file` 块（file_id）；
+ *       其余端点 → base64 data URL 内联（`image_url`），不再要求必须配置 deepseek。
  *
- * 不使用 base64 内联（本地图片走 Files API，符合 DeepSeek 推荐与 48 MiB 请求体限制）。
- * 依赖配置中的 deepseek 端点（Files API 能力）；URL 场景不依赖上传。
+ * 端点按**当前模型**反查（`ctx.agent.model`），不硬编码端点 id——`file_id` 是端点维度
+ * 资源，传错端点会返回 not found。
  */
 export class ViewImageTool extends SdkCallbackTool {
     /** 仅视觉模型可用：从 definition.modelId 解析当前模型，非视觉模型由 buildTools 过滤 */
     isAvailable(config, definition) {
-        const modelId = definition.modelId ?? config.defaultModel;
+        const modelId = definition.modelId;
         const model = (config.models ?? []).find((m) => m.id === modelId);
         return model?.vision === true;
     }
     function = {
-        name: "viewImage",
-        description: "查看一张图片并分析其内容。传入本地图片路径或 http(s) 图片 URL。本地图片会自动上传（Files API）后引用，网络图片直接引用。不支持本地 URL（如 file:// 协议、指向本机 localhost/127.0.0.1 的 http(s) 地址），本地图片请使用文件路径。适合识别图片文字、描述图片内容、分析图表等。",
+        name: "view_image",
+        description: "查看一张图片并分析其内容。传入本地图片路径或 http(s) 图片 URL。本地图片优先上传（端点支持 Files API 时）否则以 base64 内联引用，网络图片直接引用。不支持本地 URL（如 file:// 协议、指向本机 localhost/127.0.0.1 的 http(s) 地址），本地图片请使用文件路径。适合识别图片文字、描述图片内容、分析图表等。",
         parameters: {
             type: "object",
             properties: {
@@ -54,63 +55,46 @@ export class ViewImageTool extends SdkCallbackTool {
         const signal = ctx?.signal;
         const target = input?.path_or_url;
         if (!target || !target.trim()) {
-            return "viewImage 需要提供 path_or_url 参数（本地图片路径或 http(s) URL）。";
+            return "view_image 需要提供 path_or_url 参数（本地图片路径或 http(s) URL）。";
         }
         const value = target.trim();
-        // 拒绝服务商无法访问的"本地 URL"：file:// 等本地协议，或指向本机回环地址（localhost/127.0.0.1/[::1]/0.0.0.0）的 http(s) 地址
+        // 拒绝服务商无法访问的"本地 URL"：file:// 等本地协议，或指向本机回环地址的 http(s) 地址
         if (isLocalUrl(value)) {
             return "不支持本地 URL（API 服务商无法下载访问）。本地图片请使用文件路径，而不是本地链接。";
         }
+        // 按当前模型定位端点：决定走 Files API 上传还是 base64 内联
+        const { model, endpoint } = resolveModelAndEndpoint(this.env.config, ctx?.agent?.model);
         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 isUrl = /^https?:\/\//i.test(value);
+            // 本工具只处理图片：先按扩展名把关，给出比通用入口更贴切的提示
+            if (!isUrl) {
+                const abs = this.resolve(value);
+                // 先 stat 一次，把 ENOENT 变成对人友好的提示（通用入口的报错面向任意文件）
+                try {
+                    await fs.stat(abs);
+                }
+                catch {
+                    return `本地图片不存在: ${abs}`;
+                }
+                const mime = mimeOf(abs);
+                if (!mime || !mime.startsWith("image/")) {
+                    return `不支持的图片格式 "${path.extname(abs) || "(无扩展名)"}"。支持的格式：JPEG、PNG、GIF、WebP。`;
+                }
             }
-            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 result = await fileToContentSection({
+                source: isUrl ? { url: value } : { path: this.resolve(value) },
+                endpoint,
+                model,
+                signal,
             });
-            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 },
-            ];
+            const label = isUrl ? `已获取网络图片：${value}` : `已获取本地图片（${path.basename(value)}）`;
+            const how = result.transport === "files-api"
+                ? `，已上传至 Files API（file_id: ${result.section.file_id ?? "?"}）`
+                : result.transport === "inline"
+                    ? `，已按 base64 内联（${(result.bytes / 1024).toFixed(0)} KB）`
+                    : "";
+            const extra = result.warning ? `（降级说明：${result.warning}）` : "";
+            return [{ type: "text", text: `${label}${how}${extra}` }, result.section];
         }
         catch (error) {
             // 中断（abort）时返回明确的中断结果

package/dist/scope/plugins/builtin/{WriteFileTool.d.ts → WriteTool.d.ts}

@@ -1,7 +1,7 @@
 import { SdkCallbackTool } from "./SdkCallbackTool.js";
 import type { ToolEnv } from "../../../types/index.js";
 import type { AgentNS } from "@ai-zen/agents-core";
-export declare class WriteFileTool extends SdkCallbackTool {
+export declare class WriteTool extends SdkCallbackTool {
     function: AgentNS.FunctionDefine;
     constructor(env: ToolEnv);
     call(input: {

package/dist/scope/plugins/builtin/{WriteFileTool.js → WriteTool.js}

@@ -1,9 +1,9 @@
 import * as fsp from "fs/promises";
 import * as path from "path";
 import { SdkCallbackTool } from "./SdkCallbackTool.js";
-export class WriteFileTool extends SdkCallbackTool {
+export class WriteTool extends SdkCallbackTool {
     function = {
-        name: "writeFile",
+        name: "write",
         description: "写入文件",
         parameters: {
             type: "object",

package/dist/scope/plugins/builtin/index.d.ts

@@ -1,9 +1,9 @@
 import type { SdkCallbackTool } from "./SdkCallbackTool.js";
 import type { ToolEnv } from "../../../types/index.js";
 import { CwdTool } from "./CwdTool.js";
-import { ReadFileTool } from "./ReadFileTool.js";
+import { ReadTool } from "./ReadTool.js";
 import { InspectFileTool } from "./InspectFileTool.js";
-import { WriteFileTool } from "./WriteFileTool.js";
+import { WriteTool } from "./WriteTool.js";
 import { ExecTool } from "./ExecTool.js";
 import { MkdirTool } from "./MkdirTool.js";
 import { RmTool } from "./RmTool.js";
@@ -16,7 +16,7 @@ import { RenameTool } from "./RenameTool.js";
 import { CopyTool } from "./CopyTool.js";
 import { BatchEditTool } from "./BatchEditTool.js";
 import { EditTool } from "./EditTool.js";
-import { ExecAsyncTool } from "./ExecAsyncTool.js";
+import { SpawnTool } from "./SpawnTool.js";
 import { SleepTool } from "./SleepTool.js";
 import { ViewImageTool } from "./ViewImageTool.js";
 import { GenerateImageTool } from "./GenerateImageTool.js";
@@ -29,4 +29,4 @@ import { GenerateImageTool } from "./GenerateImageTool.js";
  * 如 GenerateImageTool 依赖 defaultImageModel、ViewImageTool 仅视觉模型可用。
  */
 export declare const BUILTIN_TOOL_CLASSES: Array<new (env: ToolEnv) => SdkCallbackTool>;
-export { CwdTool, ReadFileTool, InspectFileTool, WriteFileTool, ExecTool, MkdirTool, RmTool, GlobTool, LsTool, ExistTool, FindTextTool, DownloadFileTool, RenameTool, CopyTool, BatchEditTool, EditTool, ExecAsyncTool, SleepTool, ViewImageTool, GenerateImageTool, };
+export { CwdTool, ReadTool, InspectFileTool, WriteTool, ExecTool, MkdirTool, RmTool, GlobTool, LsTool, ExistTool, FindTextTool, DownloadFileTool, RenameTool, CopyTool, BatchEditTool, EditTool, SpawnTool, SleepTool, ViewImageTool, GenerateImageTool, };

package/dist/scope/plugins/builtin/index.js

@@ -1,7 +1,7 @@
 import { CwdTool } from "./CwdTool.js";
-import { ReadFileTool } from "./ReadFileTool.js";
+import { ReadTool } from "./ReadTool.js";
 import { InspectFileTool } from "./InspectFileTool.js";
-import { WriteFileTool } from "./WriteFileTool.js";
+import { WriteTool } from "./WriteTool.js";
 import { ExecTool } from "./ExecTool.js";
 import { MkdirTool } from "./MkdirTool.js";
 import { RmTool } from "./RmTool.js";
@@ -14,7 +14,7 @@ import { RenameTool } from "./RenameTool.js";
 import { CopyTool } from "./CopyTool.js";
 import { BatchEditTool } from "./BatchEditTool.js";
 import { EditTool } from "./EditTool.js";
-import { ExecAsyncTool } from "./ExecAsyncTool.js";
+import { SpawnTool } from "./SpawnTool.js";
 import { SleepTool } from "./SleepTool.js";
 import { ViewImageTool } from "./ViewImageTool.js";
 import { GenerateImageTool } from "./GenerateImageTool.js";
@@ -28,9 +28,9 @@ import { GenerateImageTool } from "./GenerateImageTool.js";
  */
 export const BUILTIN_TOOL_CLASSES = [
     CwdTool,
-    ReadFileTool,
+    ReadTool,
     InspectFileTool,
-    WriteFileTool,
+    WriteTool,
     ExecTool,
     MkdirTool,
     RmTool,
@@ -43,9 +43,9 @@ export const BUILTIN_TOOL_CLASSES = [
     CopyTool,
     BatchEditTool,
     EditTool,
-    ExecAsyncTool,
+    SpawnTool,
     SleepTool,
     ViewImageTool,
     GenerateImageTool,
 ];
-export { CwdTool, ReadFileTool, InspectFileTool, WriteFileTool, ExecTool, MkdirTool, RmTool, GlobTool, LsTool, ExistTool, FindTextTool, DownloadFileTool, RenameTool, CopyTool, BatchEditTool, EditTool, ExecAsyncTool, SleepTool, ViewImageTool, GenerateImageTool, };
+export { CwdTool, ReadTool, InspectFileTool, WriteTool, ExecTool, MkdirTool, RmTool, GlobTool, LsTool, ExistTool, FindTextTool, DownloadFileTool, RenameTool, CopyTool, BatchEditTool, EditTool, SpawnTool, SleepTool, ViewImageTool, GenerateImageTool, };

package/dist/scope/plugins/builtin/outputGuard.d.ts

@@ -28,7 +28,7 @@ export interface OutputGuardOptions<T> {
     /** 超限判定：上限由工具自行从 config 读取，骨架不传参 */
     isOverLimit: (content: T) => boolean;
     /**
-     * 落盘内容组织（可选）。缺省表示"只警告、不落盘"（如 readFile）。
+     * 落盘内容组织（可选）。缺省表示"只警告、不落盘"（如 read）。
      * 返回的文件按顺序写入本次调用专属的目录。
      */
     dump?: (dir: string, content: T) => GuardDumpFile[] | Promise<GuardDumpFile[]>;
@@ -61,7 +61,7 @@ export interface HeadPreview {
 /**
  * 生成头部预览：最多 size 字符。
  *
- * 适用于结果按出现顺序排列、尾部参考价值低的工具（如 findText）。
+ * 适用于结果按出现顺序排列、尾部参考价值低的工具（如 find_text）。
  */
 export declare function headPreview(text: string, size?: number): HeadPreview;
 /** 头尾预览 */

package/dist/scope/plugins/builtin/outputGuard.js

@@ -42,7 +42,7 @@ export async function guardOutput(options) {
 /**
  * 生成头部预览：最多 size 字符。
  *
- * 适用于结果按出现顺序排列、尾部参考价值低的工具（如 findText）。
+ * 适用于结果按出现顺序排列、尾部参考价值低的工具（如 find_text）。
  */
 export function headPreview(text, size = 1000) {
     if (text.length <= size)

package/dist/scope/plugins/mcp/McpScopePlugin.d.ts

@@ -24,6 +24,6 @@ export declare class McpScopePlugin implements ScopePlugin {
     /** 是否配置了 MCP（供外部代码判定，如 UnknownToolHintPlugin） */
     hasConfig(): boolean;
     candidates(): ScopeCandidates;
-    instantiate(_scope: Scope, filtered: FilterOutput): Tool[];
+    instantiate(scope: Scope, filtered: FilterOutput): Tool[];
     dispose(): Promise<void>;
 }

package/dist/scope/plugins/mcp/McpScopePlugin.js

@@ -37,7 +37,7 @@ export class McpScopePlugin {
             tools: ["load_mcp", "call_mcp_tool", "read_mcp_resource"],
         };
     }
-    instantiate(_scope, filtered) {
+    instantiate(scope, filtered) {
         const allow = new Set(filtered.tools);
         const allowedMcps = new Set(filtered.mcps);
         const filteredMcps = this.servers.filter((s) => allowedMcps.has(s.id));
@@ -47,10 +47,11 @@ export class McpScopePlugin {
             result.push(createLoadMcpTool(m, filteredMcps));
         }
         if (allow.has("call_mcp_tool") && m) {
-            result.push(createCallMcpTool(m));
+            // env 供 call_mcp_tool 读取 maxToolOutput，与内置工具共用同一上限口径
+            result.push(createCallMcpTool(m, scope.env));
         }
         if (allow.has("read_mcp_resource") && m) {
-            result.push(createReadMcpResourceTool(m));
+            result.push(createReadMcpResourceTool(m, scope.env));
         }
         return result;
     }

package/dist/scope/plugins/mcp/mcpTools.d.ts

@@ -1,6 +1,6 @@
 import { CallbackTool } from "@ai-zen/agents-core";
 import type { McpConnectionManager } from "./McpConnectionManager.js";
-import type { McpServerConfig } from "../../../types/index.js";
+import type { McpServerConfig, ToolEnv } from "../../../types/index.js";
 /**
  * 创建 load_mcp 工具。
  * server 枚举由 filteredMcps （完整 McpServerConfig[]）自动推导，
@@ -10,9 +10,15 @@ export declare function createLoadMcpTool(mcpManager: McpConnectionManager, filt
 /**
  * 创建 call_mcp_tool 工具。
  * 通过官方 Client.callTool() API 调用 MCP 服务器上的工具。
+ *
+ * 返回形态：
+ *   - 仅文本 → 纯字符串（与历史行为一致）；
+ *   - 含媒体 → 内容块数组：首块为受保护的文本，其后原样透传 image / file 块。
+ *
+ * env 仅用于读取 maxToolOutput（文本输出保护上限），与内置工具口径一致。
  */
-export declare function createCallMcpTool(mcpManager: McpConnectionManager): CallbackTool;
+export declare function createCallMcpTool(mcpManager: McpConnectionManager, env: ToolEnv): CallbackTool;
 /**
  * 创建 read_mcp_resource 工具。
  */
-export declare function createReadMcpResourceTool(mcpManager: McpConnectionManager): CallbackTool;
+export declare function createReadMcpResourceTool(mcpManager: McpConnectionManager, env: ToolEnv): CallbackTool;