@ai-zen/agents-sdk 1.0.0-alpha.10 → 1.0.0-alpha.11

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## [1.0.0-alpha.11] - 2026-10-20
+
+### 💥 Breaking Changes
+
+- **`createCallMcpTool(mcpManager)` → `createCallMcpTool(mcpManager, env: ToolEnv)`** —— 新增的 `env` 只用于读取 `maxToolOutput`，由 `McpScopePlugin.instantiate` 传入 `scope.env`。直接调用该工厂的下游需补第二参。
+
+### ✨ 新增
+
+- **`call_mcp_tool` 输出保护**：MCP 工具是最容易一次吐出上百 KB 甚至上 MB JSON 的通道，此前完全裸返回。现在文本部分超过 `maxToolOutput`（默认 32768 字符）时，完整文本落盘为 `result.txt`，只返回警告 + 头尾预览（`outputTooLarge` / `chars` / `head` / `tail` / `files`）。复用内置工具同一套 `outputGuard` 骨架与同一配置口径，不另立阈值。
+- **媒体内容块原样透传**：`image` → `image_url`（`data:<mimeType>;base64,...`）、`audio` → `file`（`file_data` 内联 data URL）、`resource.blob` 按 mimeType 分流到 `image_url` / `file`。媒体**不参与字符计数、不落盘、不丢弃**——只对文本做保护。
+- **返回形态**：仅文本 → 纯字符串（与历史一致）；含媒体 → 内容块数组。
+
+### 🔧 修复
+
+- **非文本内容块被静默丢弃**：旧实现只取 `type === "text"`，`image` / `audio` / `resource` / `resource_link` 全部被扔掉，模型只知道「有个块没给我」。现在媒体透传、`resource.text` 并入正文、`resource_link` 转为 `[资源链接] name · uri · mimeType` 线索、未知类型（如 `tool_use`）退化为 JSON 文本。
+- **内容块顺序**：严格按 MCP `content[]` 原始顺序逐块映射，文本夹在图片中间也保持原位。超限时只保留一个警告块占据原**首个**文本块的位置，其余文本落盘、媒体原位不动——即使文本夹在两图之间，图注与图片的对应关系也不会被打乱。
+- **判定口径**：用全部文本的字符**总数**判超限，不逐块判（否则 N 段各 3 万字符都不超限、合起来却能灌爆）。
+
+### ✅ 测试
+
+- `mcpTools.test.ts` 38 例（新增内容块映射 8 例、输出保护 4 例、保序 4 例）。全量 **54 文件 / 542 用例**通过，`tsc --noEmit` 与 `build` 零错误。
+
+### 📄 Docs
+
+- `docs/sdk-design-v1.md` §9 `call_mcp_tool` 补充内容块映射表、输出保护口径与超限保序折叠规则；`../docs/{zh,en}/mcp.md` 及网站镜像同步。
+
+
 ## [1.0.0-alpha.10] - 2026-10-20
 
 ### 💥 Breaking Changes

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,7 +47,8 @@ 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));

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,8 +10,14 @@ 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 工具。
  */

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

@@ -1,5 +1,6 @@
 import { CallbackTool } from "@ai-zen/agents-core";
 import { createDisclosureParam } from "../../disclosure.js";
+import { DEFAULT_MAX_TOOL_OUTPUT, guardOutput, headTailPreview } from "../builtin/outputGuard.js";
 import { getLogger } from "../../../shared/logger.js";
 const EMPTY_HINT = "（当前没有可用的 MCP 服务器，请联系用户添加）";
 const log = getLogger();
@@ -81,15 +82,130 @@ export function createLoadMcpTool(mcpManager, filteredMcps) {
         },
     });
 }
+/** base64 二进制转 data URL（image_url / file_data 均接受） */
+function toDataUrl(base64, mimeType) {
+    return `data:${mimeType};base64,${base64}`;
+}
+/**
+ * MCP content 块 → SDK 内容块。
+ *
+ * 文本类（text / resource.text / resource_link / 未知类型）归一为 `text` 块，
+ * 由调用方拼接成正文后进入输出保护；
+ * 媒体类（image / audio / resource.blob）归一为 `image_url` / `file` 块，
+ * 原样透传给模型——图片不进字符闸门，也不丢弃。
+ */
+function toMessageSection(block) {
+    switch (block?.type) {
+        case "image":
+            return {
+                type: "image_url",
+                image_url: { url: toDataUrl(block.data, block.mimeType ?? "image/png") },
+            };
+        case "audio":
+            // AgentNS 无独立音频块，以 Files API 的 file_data（base64 data URL）内联承载
+            return {
+                type: "file",
+                file_data: toDataUrl(block.data, block.mimeType ?? "audio/wav"),
+            };
+        case "resource": {
+            const r = block.resource ?? {};
+            // 内嵌文本资源：本质是纯文本，并入正文（同样受输出保护）
+            if (typeof r.text === "string")
+                return { type: "text", text: r.text };
+            // 内嵌二进制资源：按 mimeType 选块类型，不丢弃
+            if (typeof r.blob === "string") {
+                const mime = r.mimeType ?? "application/octet-stream";
+                return mime.startsWith("image/")
+                    ? { type: "image_url", image_url: { url: toDataUrl(r.blob, mime) } }
+                    : { type: "file", file_data: toDataUrl(r.blob, mime) };
+            }
+            return { type: "text", text: `[资源] ${r.uri ?? "(未知 URI)"}` };
+        }
+        case "resource_link": {
+            const parts = [block.name, block.uri, block.mimeType].filter(Boolean);
+            return { type: "text", text: `[资源链接] ${parts.join(" · ")}` };
+        }
+        case "text":
+            return { type: "text", text: block.text ?? "" };
+        default:
+            // 未知类型（如 tool_use）退化为 JSON 文本，仍受输出保护
+            return { type: "text", text: JSON.stringify(block) };
+    }
+}
+/**
+ * 文本输出保护（保序）：
+ *
+ * - **未超限**：原样返回映射后的块数组，不重排、不合并、不丢块；
+ *   纯文本时退化为单个字符串（历史行为）。
+ * - **超限**：全部文本落盘为 result.txt，只保留**一个**警告文本块占据
+ *   原首个文本块的位置，其余文本块丢弃（内容已落盘），媒体块原位不动。
+ *   这样即使文本夹在中间，媒体与位置的对应关系也不会被打乱。
+ *
+ * 判定用全部文本的字符总数——不能逐块判，否则 N 段各 3 万字符都不超限、合起来却能灌爆。
+ * 落盘只写文本正文，不写原始结果——后者可能含 image 的 base64，
+ * 落盘等于把几 MB 二进制再抄一遍磁盘。
+ */
+async function protectCallOutput(output, env) {
+    const limit = env.config.maxToolOutput ?? DEFAULT_MAX_TOOL_OUTPUT;
+    const { sections, fullText, chars, isError } = output;
+    const guarded = await guardOutput({
+        tool: "call_mcp_tool",
+        content: output,
+        isOverLimit: (o) => o.chars > limit,
+        dump: (_dir, o) => [{ name: "result.txt", content: o.fullText }],
+        buildWarning: (ctx) => {
+            const preview = headTailPreview(fullText);
+            return JSON.stringify({
+                outputTooLarge: true,
+                isError: isError || undefined,
+                warning: `文本输出过大：共 ${chars} 字符，超过上限 ${limit} 字符。` +
+                    `完整文本已落盘（result.txt），可用 read 分批读取。`,
+                files: ctx.files,
+                chars,
+                ...preview,
+            });
+        },
+    });
+    // 超限：警告占据首个文本块的位置，其余文本块合并到它身上（内容已落盘），媒体原位
+    if (typeof guarded === "string") {
+        const collapsed = [];
+        let placed = false;
+        for (const section of sections) {
+            if (section.type === "text") {
+                if (!placed) {
+                    collapsed.push({ type: "text", text: guarded });
+                    placed = true;
+                }
+                continue;
+            }
+            collapsed.push(section);
+        }
+        // 仅一个文本块（无媒体）：退化为字符串，与历史行为一致
+        return collapsed.length === 1 ? collapsed[0].text : collapsed;
+    }
+    // 未超限：无媒体 → 纯字符串；有媒体 → 原序块数组
+    const hasMedia = sections.some((s) => s.type !== "text");
+    if (!hasMedia)
+        return isError ? `❌ 工具执行出错:\n${fullText}` : fullText;
+    return isError
+        ? [{ type: "text", text: "❌ 工具执行出错:" }, ...sections]
+        : sections;
+}
 /**
  * 创建 call_mcp_tool 工具。
  * 通过官方 Client.callTool() API 调用 MCP 服务器上的工具。
+ *
+ * 返回形态：
+ *   - 仅文本 → 纯字符串（与历史行为一致）；
+ *   - 含媒体 → 内容块数组：首块为受保护的文本，其后原样透传 image / file 块。
+ *
+ * env 仅用于读取 maxToolOutput（文本输出保护上限），与内置工具口径一致。
  */
-export function createCallMcpTool(mcpManager) {
+export function createCallMcpTool(mcpManager, env) {
     return new CallbackTool({
         function: {
             name: "call_mcp_tool",
-            description: "调用已连接 MCP 服务器上的指定工具。需先通过 load_mcp 连接服务器。",
+            description: "调用已连接 MCP 服务器上的指定工具。需先通过 load_mcp 连接服务器。文本输出过大时会落盘并只返回头尾预览；图片、音频等媒体原样返回。",
             parameters: {
                 type: "object",
                 properties: {
@@ -117,15 +233,19 @@ export function createCallMcpTool(mcpManager) {
                     name: input.tool,
                     arguments: input.arguments,
                 }, undefined, { signal: ctx?.signal });
+                // 按 MCP content 原始顺序映射，文本与媒体的相对位置完整保留
                 const contents = result.content ?? [];
-                const textParts = contents
-                    .filter((c) => c.type === "text")
-                    .map((c) => c.text);
-                const text = textParts.join("\n");
-                if (result.isError) {
-                    return `❌ 工具执行出错:\n${text || JSON.stringify(result)}`;
+                const isError = Boolean(result.isError);
+                // 没有 content 时退回原始 JSON（既有兜底）
+                if (contents.length === 0) {
+                    const json = JSON.stringify(result);
+                    return await protectCallOutput({ sections: [{ type: "text", text: json }], fullText: json, chars: json.length, isError }, env);
                 }
-                return text || JSON.stringify(result);
+                const sections = contents.map(toMessageSection);
+                const textSections = sections.filter((s) => s.type === "text");
+                const fullText = textSections.map((s) => s.text).join("\n");
+                const chars = textSections.reduce((n, s) => n + s.text.length, 0);
+                return await protectCallOutput({ sections, fullText, chars, isError }, env);
             }
             catch (error) {
                 return `❌ 调用 "${input.tool}" 失败: ${error?.message ?? error}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-zen/agents-sdk",
-  "version": "1.0.0-alpha.10",
+  "version": "1.0.0-alpha.11",
   "description": "AI-Zen Agents SDK — shared business logic for CLI and Desktop",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",