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

package/CHANGELOG.md

@@ -1,5 +1,70 @@
 # Changelog
 
+## [1.0.0-alpha.12] - 2026-10-22
+
+### 💥 Breaking Changes
+
+- **`createReadMcpResourceTool(mcpManager)` → `createReadMcpResourceTool(mcpManager, env: ToolEnv)`** —— 与 alpha.11 的 `createCallMcpTool` 对齐：`env` 用于读取 `maxToolOutput` 并解析当前模型绑定的端点。直接调用该工厂的下游需补第二参。
+- **`view_image` 不再依赖 `deepseek` 端点** —— 此前本地图片固定上传到 `id === "deepseek"` 的端点，未配置时直接报「未配置 deepseek 端点，无法上传本地图片」。现在按能力位决定：声明 `capabilities.filesApi` 的端点走上传，其余走 base64 内联，没有 deepseek 也能查看本地图片。返回文案随之变化（含传输方式与降级说明）。
+- **`Endpoint` 新增可选字段 `capabilities`** —— 类型层面非破坏性（可选），但语义重要：缺省视为「无特殊能力」，即不做上传。
+
+### ✨ 新增
+
+- **「本地文件 → 内容块」统一入口 `shared/content-blocks.ts`**。这段逻辑此前散落三处各自为政（`ViewImageTool` 硬编码端点 id、MCP 媒体块归一、CLI 侧再实现一遍），现在收敛为一处：
+  - `fileToContentSection({ source, endpoint, model, signal, maxInlineBytes, deps })` → `{ section, transport, bytes, warning? }`；`source` 支持 `path` / `url` / `data`（`Uint8Array`）/ `base64` 四种来源。
+  - 决策链：http(s) URL → `image_url`；端点有 Files API → 上传得 `file_id`（失败**自动降级**为内联）；其余端点 + 图片 → `image_url` + base64 data URL；其余端点 + 非图片 → `file` 块 + `file_data`；非视觉模型 + 图片 → 文本提示；内联超限且无法上传 → 抛错（不静默塞进请求体）。
+  - 配套：`resolveModelAndEndpoint()`（按发给 API 的模型名反查模型与端点）、`supportsFilesApi()`、`mimeOf()` / `toDataUrl()` / `base64ByteLength()` / `contentHash()`、`clearUploadCache()`、`DEFAULT_MAX_INLINE_BYTES`（8 MiB）。
+  - **已从包入口 `src/index.ts` 导出为公共 API**（`fileToContentSection` / `resolveModelAndEndpoint` / `supportsFilesApi` / `mimeOf` / `toDataUrl` / `base64ByteLength` / `contentHash` / `clearUploadCache` / `MIME_BY_EXT` / `DEFAULT_MAX_INLINE_BYTES`，以及 `FileSource` / `FileToSectionInput` / `FileToSectionResult` / `ContentTransport` / `UploadFn` / `EndpointCapabilities` 类型）。上层应用构造媒体消息时直接复用，不要各自再实现一遍「上传 or 内联」。
+  - 上传缓存：路径来源用「端点 id + 绝对路径 + mtime + size」，内存来源用内容 sha256（同一张图不重复上传），上限 200 条。
+  - `deps.upload` 可注入，便于测试与替换上传实现。
+- **`Endpoint.capabilities.filesApi` 能力位** —— 出厂仅 `deepseek` 标记为 `true`（description 同步说明）。判据从「端点 id 是不是 deepseek」改为能力位，用户自建端点只要声明即可享受上传。
+
+### 🔧 修复
+
+- **MCP 媒体不再一律 base64 内联**：`call_mcp_tool` 的 `image` / `audio` / `resource.blob` 改走统一入口，端点有 Files API 能力时上传后以 `file_id` 发送，请求体不再随历史反复膨胀；转换失败**不丢块**，退化为一条文本说明，避免整个工具调用因媒体问题失败。
+- **`read_mcp_resource` 的二进制资源被静默丢弃**：此前只拼 `contents[].text`，图片 / PDF 等 `blob` 内容直接消失。新增 `resourceToMessageSection()`——注意 `readResource` 的 contents 形如 `{ uri, mimeType?, text|blob }`，**没有 `type` 判别字段**，不能复用 `toMessageSection`（否则文本资源会被 JSON 化）；`blob` 交给统一入口。
+- **`read_mcp_resource` 接入输出保护**：与 `call_mcp_tool` 共用同一套口径——文本超限落盘 `result.txt` 并返回头尾预览，媒体块原位保留；返回形态同样是「仅文本 → 字符串 / 含媒体 → 内容块数组」。
+- **非视觉模型退化**：`Model.vision !== true` 时图片退化为一行文本提示（本地路径来源与 MCP 内存 base64 来源均生效），避免 `image_url` 被服务端 4xx 拒掉。
+- **`edit` 并发护栏**：`edit` / `batch_edit` 工具描述明确「同一文件禁止并行 `edit`，多处修改改用 `batch_edit`，只有不同文件才能并行」——描述层劝阻（不引入运行时锁）。
+
+### ✅ 测试
+
+- 新增 `shared/content-blocks.test.ts` 16 例；`mcpTools.test.ts` 扩展覆盖媒体统一入口、非视觉退化、`read` 超限落盘与混排保序；`ViewImageTool` / `EditTool` / `BatchEditTool` 断言同步到新语义。
+- 全量 **55 文件 / 569 用例**通过（6 skipped），`tsc --noEmit` 与 `build` 零错误。
+
+### 📄 Docs
+
+- `docs/{zh,en}/sdk.md` 新增「本地文件 → 内容块（统一入口）」小节、`Endpoint` 能力位与 MCP 媒体 / 退化 / 输出保护说明。
+- `docs/{zh,en}/mcp.md` 同步 `call_mcp_tool` / `read_mcp_resource` 的媒体传输方式与输出保护口径。
+
+
+## [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/config/constants.js

@@ -82,7 +82,10 @@ export const DEFAULT_APP_CONFIG = {
             name: "DeepSeek",
             apiKey: "",
             baseUrl: "https://api.deepseek.com/v1",
-            description: "DeepSeek API 端点",
+            description: "DeepSeek API 端点（支持 Files API：本地文件上传后以 file_id 引用）",
+            // 唯一声明了 Files API 能力的出厂端点；其余端点本地文件走 base64 内联。
+            // 判断依据是能力位而非端点 id，用户自建端点只要声明即可享受上传。
+            capabilities: { filesApi: true },
         },
     ],
     // 模型清单（2026-10-03 依据各厂商官方来源核对）：

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export type { PermissionPolicy, AgentPermissions, Endpoint, Model, ImageModel, AgentDefinition, AppConfig, ToolEnv, McpIcon, McpAnnotations, McpToolDef, McpResourceDef, McpPromptDef, McpServerManifest, McpServerConfig, McpConnectionState, } from "./types/index.js";
+export type { PermissionPolicy, AgentPermissions, Endpoint, EndpointCapabilities, Model, ImageModel, AgentDefinition, AppConfig, ToolEnv, McpIcon, McpAnnotations, McpToolDef, McpResourceDef, McpPromptDef, McpServerManifest, McpServerConfig, McpConnectionState, } from "./types/index.js";
 export { PermissionEvaluator } from "./scope/PermissionEvaluator.js";
 export type { CandidateSets } from "./scope/PermissionEvaluator.js";
 export { createDisclosureParam } from "./scope/disclosure.js";
@@ -23,6 +23,8 @@ export { ConfigManager, DEFAULT_AGENT_ID, DEFAULT_AGENT_DEFINITION, DEFAULT_SUBA
 export { FACTORY_SKILLS, HANDOFF_SKILL_ID, FALLBACK_HANDOFF_TEMPLATE, isCustomSkill, } from "./config/factory-skills.js";
 export { EntityRepository } from "./shared/EntityRepository.js";
 export { AgentRepository } from "./crud/AgentRepository.js";
+export { fileToContentSection, resolveModelAndEndpoint, supportsFilesApi, mimeOf, toDataUrl, base64ByteLength, contentHash, clearUploadCache, MIME_BY_EXT, DEFAULT_MAX_INLINE_BYTES, } from "./shared/content-blocks.js";
+export type { FileSource, FileToSectionInput, FileToSectionResult, ContentTransport, UploadFn, } from "./shared/content-blocks.js";
 export { createModel } from "./runtime/createModel.js";
 export { SdkAgent } from "./runtime/SdkAgent.js";
 export type { AgentPlugin, SendContext } from "./runtime/SdkAgent.js";

package/dist/index.js

@@ -22,6 +22,8 @@ export { FACTORY_SKILLS, HANDOFF_SKILL_ID, FALLBACK_HANDOFF_TEMPLATE, isCustomSk
 // CRUD — 实体仓储（仅 Agent 定义等能力实体）
 export { EntityRepository } from "./shared/EntityRepository.js";
 export { AgentRepository } from "./crud/AgentRepository.js";
+// 文件 → 内容块（统一入口）— 上层应用构造媒体消息时请走这里，不要自己判断上传还是内联
+export { fileToContentSection, resolveModelAndEndpoint, supportsFilesApi, mimeOf, toDataUrl, base64ByteLength, contentHash, clearUploadCache, MIME_BY_EXT, DEFAULT_MAX_INLINE_BYTES, } from "./shared/content-blocks.js";
 // 运行时
 export { createModel } from "./runtime/createModel.js";
 export { SdkAgent } from "./runtime/SdkAgent.js";

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

@@ -3,7 +3,10 @@ import { SdkCallbackTool } from "./SdkCallbackTool.js";
 export class BatchEditTool extends SdkCallbackTool {
     function = {
         name: "batch_edit",
-        description: "批量编辑文件文本，可以优先使用这个工具对文件进行编辑",
+        description: [
+            "批量编辑文件文本，可以优先使用这个工具对文件进行编辑。",
+            "对同一个文件的多处修改应在一次调用中全部提交（replacements 数组），而不是并行多次调用 edit——并行编辑同一文件会互相覆盖。",
+        ].join("\n"),
         parameters: {
             type: "object",
             properties: {

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

@@ -15,7 +15,12 @@ function countOccurrences(content, text) {
 export class EditTool extends SdkCallbackTool {
     function = {
         name: "edit",
-        description: "编辑文件中的文本，支持精确替换或替换所有匹配项",
+        description: [
+            "编辑文件中的文本，支持精确替换或替换所有匹配项。",
+            "",
+            "并发限制（重要）：同一个文件禁止并行编辑。不要在同一轮回复中对同一路径发起多个 edit 调用——这些调用会各自读取旧内容再写回，后写者覆盖先写者，导致修改丢失或文件被写坏。",
+            "如需对同一个文件施加多处修改，请改用 batch_edit，在一次调用里提交全部替换。只有编辑不同文件时才可以并行调用 edit。",
+        ].join("\n"),
         parameters: {
             type: "object",
             properties: {

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,11 +18,13 @@ 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 过滤 */
@@ -34,7 +35,7 @@ export class ViewImageTool extends SdkCallbackTool {
     }
     function = {
         name: "view_image",
-        description: "查看一张图片并分析其内容。传入本地图片路径或 http(s) 图片 URL。本地图片会自动上传（Files API）后引用，网络图片直接引用。不支持本地 URL（如 file:// 协议、指向本机 localhost/127.0.0.1 的 http(s) 地址），本地图片请使用文件路径。适合识别图片文字、描述图片内容、分析图表等。",
+        description: "查看一张图片并分析其内容。传入本地图片路径或 http(s) 图片 URL。本地图片优先上传（端点支持 Files API 时）否则以 base64 内联引用，网络图片直接引用。不支持本地 URL（如 file:// 协议、指向本机 localhost/127.0.0.1 的 http(s) 地址），本地图片请使用文件路径。适合识别图片文字、描述图片内容、分析图表等。",
         parameters: {
             type: "object",
             properties: {
@@ -57,60 +58,43 @@ export class ViewImageTool extends SdkCallbackTool {
             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/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;

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

@@ -1,5 +1,7 @@
 import { CallbackTool } from "@ai-zen/agents-core";
+import { fileToContentSection, resolveModelAndEndpoint } from "../../../shared/content-blocks.js";
 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 +83,172 @@ export function createLoadMcpTool(mcpManager, filteredMcps) {
         },
     });
 }
+/** MIME → 文件名后缀（仅用于上传时给文件一个好名字） */
+const EXT_BY_MIME = {
+    "image/png": "png",
+    "image/jpeg": "jpg",
+    "image/gif": "gif",
+    "image/webp": "webp",
+    "audio/wav": "wav",
+    "audio/mpeg": "mp3",
+    "application/pdf": "pdf",
+};
+/**
+ * MCP 媒体（base64 字符串）→ SDK 内容块。
+ *
+ * 统一交给 `fileToContentSection()` 决定传输方式：端点声明 Files API 能力就上传
+ * （`file` 块 + `file_id`，请求体小、不随历史反复膨胀），否则保持 base64 内联。
+ * 转换失败**不丢块**——退化为一条文本说明，避免整个工具调用因媒体问题失败。
+ */
+async function mediaSection(data, mime, media) {
+    const ext = EXT_BY_MIME[mime] ?? "bin";
+    try {
+        const { section } = await fileToContentSection({
+            source: {
+                base64: data,
+                mime,
+                filename: `mcp-media-${Date.now()}.${ext}`,
+            },
+            endpoint: media.endpoint,
+            model: media.model,
+            signal: media.signal,
+        });
+        return section;
+    }
+    catch (error) {
+        return {
+            type: "text",
+            text: `[媒体] 无法转换（${mime}）：${error?.message ?? error}`,
+        };
+    }
+}
+/**
+ * `read_mcp_resource` 的 resource contents → SDK 内容块。
+ *
+ * 注意形状差异：`callTool` 的 content 块带 `type` 判别字段，而 `readResource` 的
+ * contents 是 `{ uri, mimeType?, text }` 或 `{ uri, mimeType?, blob }`——**没有 type**。
+ * 若直接复用 `toMessageSection`，文本资源会掉进 default 分支被 JSON 化（实测踩过）。
+ */
+async function resourceToMessageSection(item, media) {
+    if (typeof item?.text === "string")
+        return { type: "text", text: item.text };
+    if (typeof item?.blob === "string") {
+        return mediaSection(item.blob, item.mimeType ?? "application/octet-stream", media);
+    }
+    return { type: "text", text: JSON.stringify(item) };
+}
+/**
+ * MCP content 块 → SDK 内容块。
+ *
+ * 文本类（text / resource.text / resource_link / 未知类型）归一为 `text` 块，
+ * 由调用方拼接成正文后进入输出保护；
+ * 媒体类（image / audio / resource.blob）经 `mediaSection()` → `fileToContentSection()`：
+ * 端点支持 Files API 时上传为 `file` 块，否则 base64 内联——图片不进字符闸门，也不丢弃。
+ */
+async function toMessageSection(block, media) {
+    switch (block?.type) {
+        case "image":
+            return await mediaSection(block.data, block.mimeType ?? "image/png", media);
+        case "audio":
+            // AgentNS 无独立音频块，以 `file` 块承载（支持上传的端点 → file_id，否则 file_data 内联）
+            return await mediaSection(block.data, block.mimeType ?? "audio/wav", media);
+        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 await mediaSection(r.blob, mime, media);
+            }
+            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 连接服务器。文本输出过大时会落盘并只返回头尾预览；图片、音频等媒体会保留：端点支持 Files API 时上传后以 file_id 引用，否则 base64 内联。",
             parameters: {
                 type: "object",
                 properties: {
@@ -117,15 +276,23 @@ 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);
+                // 按当前模型定位端点：决定媒体走 Files API 上传还是 base64 内联
+                const { model, endpoint } = resolveModelAndEndpoint(env.config, ctx?.agent?.model);
+                const mediaContext = { endpoint, model, signal: ctx?.signal };
+                // Promise.all 保序：文本与媒体的相对位置不变
+                const sections = await Promise.all(contents.map((block) => toMessageSection(block, mediaContext)));
+                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}`;
@@ -136,11 +303,11 @@ export function createCallMcpTool(mcpManager) {
 /**
  * 创建 read_mcp_resource 工具。
  */
-export function createReadMcpResourceTool(mcpManager) {
+export function createReadMcpResourceTool(mcpManager, env) {
     return new CallbackTool({
         function: {
             name: "read_mcp_resource",
-            description: "读取已连接 MCP 服务器上的指定资源（文档、数据等）。",
+            description: "读取已连接 MCP 服务器上的指定资源（文档、数据、图片等）。文本原样返回；图片等媒体按端点能力上传（file_id）或 base64 内联，不会被丢弃。",
             parameters: {
                 type: "object",
                 properties: {
@@ -165,10 +332,22 @@ export function createReadMcpResourceTool(mcpManager) {
                 mcpManager.touch(serverName);
                 const result = await client.readResource({ uri: input.uri }, { signal: ctx?.signal });
                 const contents = result?.contents ?? [];
-                const textParts = contents
-                    .filter((c) => c.text)
-                    .map((c) => c.text);
-                return textParts.join("\n") || JSON.stringify(result);
+                const { model, endpoint } = resolveModelAndEndpoint(env.config, ctx?.agent?.model);
+                const mediaContext = { endpoint, model, signal: ctx?.signal };
+                // 与 call_mcp_tool 同一套映射：文本归一为 text 块，媒体按端点能力上传或内联，
+                // 不再把二进制资源（图片 / PDF）静默丢掉。
+                const sections = await Promise.all(contents.map((content) => resourceToMessageSection(content, mediaContext)));
+                // 没有 contents 时退回原始 JSON（与 call_mcp_tool 同一兜底）
+                if (sections.length === 0) {
+                    const json = JSON.stringify(result);
+                    return await protectCallOutput({ sections: [{ type: "text", text: json }], fullText: json, chars: json.length, isError: false }, env);
+                }
+                // 与 call_mcp_tool 共用同一套输出保护：文本超限落盘 result.txt，
+                // 媒体块原位保留；未超限时纯文本退化为字符串、含媒体返回块数组。
+                const textSections = sections.filter((section) => section.type === "text");
+                const fullText = textSections.map((section) => section.text).join("\n");
+                const chars = textSections.reduce((n, section) => n + section.text.length, 0);
+                return await protectCallOutput({ sections, fullText, chars, isError: false }, env);
             }
             catch (error) {
                 return `❌ 读取资源 "${input.uri}" 失败: ${error?.message ?? error}`;

package/dist/shared/content-blocks.d.ts

@@ -0,0 +1,108 @@
+/**
+ * 本地文件 → 消息内容块的唯一转换入口。
+ *
+ * 背景：这段逻辑原先散落三处，且各自为政 ——
+ *   1. `ViewImageTool` 自己判断 `endpoint.id === "deepseek"` 再上传（端点 id 一变就失效）；
+ *   2. `mcp/mcpTools.ts` 自己把 MCP 的 base64 归一成 `image_url` / `file` 块；
+ *   3. CLI 侧又实现了一遍「上传 or base64」。
+ *
+ * 现在统一到这里，调用方只提供「文件 + 当前端点/模型」，传输方式由本模块决定：
+ *
+ * | 条件 | 结果 |
+ * |------|------|
+ * | http(s) URL | 直接 `image_url`（不上传、不内联） |
+ * | 端点声明 `capabilities.filesApi` | 上传 Files API → `file` 块（`file_id`），失败降级为内联 |
+ * | 其余端点 + 图片 | `image_url` + base64 data URL |
+ * | 其余端点 + 非图片 | `file` 块 + `file_data`（base64 data URL） |
+ * | 模型明确不支持视觉（`vision === false`）且是图片 | 退化为 `text`，只给路径提示 |
+ * | 内联体积超过上限且无法上传 | 抛错（不静默塞进请求体） |
+ */
+import type { AgentNS } from "@ai-zen/agents-core";
+import type { AppConfig, Endpoint, Model } from "../types/index.js";
+/** 扩展名 → MIME。图片走视觉通道，其余走 `file` 块 */
+export declare const MIME_BY_EXT: Record<string, string>;
+/** 按扩展名推断 MIME；未知扩展名返回 undefined */
+export declare function mimeOf(filePath: string): string | undefined;
+/** base64 二进制转 data URL（`image_url` 与 `file.file_data` 均接受） */
+export declare function toDataUrl(base64: string, mime: string): string;
+/**
+ * base64 字符串对应的字节数（不含空白）。
+ *
+ * 用于「只看体积、不想解码」的场景：内联上限检查与日志统计。
+ */
+export declare function base64ByteLength(base64: string): number;
+/** 内联（base64）体积上限，默认 8 MiB；超过且端点不支持上传时直接报错 */
+export declare const DEFAULT_MAX_INLINE_BYTES: number;
+/** 实际采用的传输方式（供调用方组织提示文案 / 日志） */
+export type ContentTransport = "url" | "files-api" | "inline" | "text";
+/** 文件来源：本地路径 / 网络 URL / 已在内存里的字节 */
+export type FileSource = {
+    path: string;
+} | {
+    url: string;
+} | {
+    data: Uint8Array;
+    mime: string;
+    filename?: string;
+}
+/** 已经是 base64 的字节（MCP 等协议给的就是 base64）：内联时原样透传，不做解码再编码 */
+ | {
+    base64: string;
+    mime: string;
+    filename?: string;
+};
+/** Files API 上传函数签名（可注入，便于测试与替换实现） */
+export type UploadFn = (input: {
+    endpoint: Endpoint;
+    data: Uint8Array;
+    filename: string;
+    signal?: AbortSignal;
+}) => Promise<string>;
+export interface FileToSectionInput {
+    source: FileSource;
+    /** 当前模型所用端点：决定能否走 Files API */
+    endpoint?: Endpoint | null;
+    /** 当前模型：`vision === false` 时图片退化为文本提示 */
+    model?: Model | null;
+    signal?: AbortSignal;
+    /** 覆盖内联体积上限 */
+    maxInlineBytes?: number;
+    /** 依赖注入（测试用），默认走 OpenAI SDK 的 Files API */
+    deps?: {
+        upload?: UploadFn;
+    };
+}
+export interface FileToSectionResult {
+    section: AgentNS.MessageContentSection;
+    transport: ContentTransport;
+    /** 实际处理的字节数（URL 来源为 0） */
+    bytes: number;
+    /** 降级 / 退化时的人类可读说明，供上层拼提示 */
+    warning?: string;
+}
+/**
+ * 由「发给 API 的模型名」反查它绑定的模型定义与端点。
+ *
+ * 工具在 `call()` 阶段拿不到 Agent 定义，但 `ctx.agent.model` 就是发给 API 的
+ * 模型名（`Model.modelName ?? Model.id`）。必须按**当前实际使用的模型**定位端点：
+ * `file_id` 是端点维度资源，传错端点会得到 not found。
+ */
+export declare function resolveModelAndEndpoint(config: AppConfig, apiModelName?: string): {
+    model?: Model;
+    endpoint?: Endpoint | null;
+};
+/** 端点是否声明了 Files API 能力 */
+export declare function supportsFilesApi(endpoint?: Endpoint | null): boolean;
+/** 清空上传缓存（测试用；进程内长期运行无需清理，条目有上限） */
+export declare function clearUploadCache(): void;
+/** 内容哈希（sha256），用于给「内存里的字节」做上传缓存键 */
+export declare function contentHash(bytes: Uint8Array): string;
+/**
+ * 把文件转成内容块。
+ *
+ * 抛错场景（均由调用方决定如何呈现给模型）：
+ * - `source.url` 不是 http(s)（本地 URL 服务商访问不到）
+ * - 本地文件不存在 / 不是文件 / 扩展名不支持
+ * - 需要内联但体积超过上限，且端点不支持上传
+ */
+export declare function fileToContentSection(input: FileToSectionInput): Promise<FileToSectionResult>;

package/dist/shared/content-blocks.js

@@ -0,0 +1,256 @@
+/**
+ * 本地文件 → 消息内容块的唯一转换入口。
+ *
+ * 背景：这段逻辑原先散落三处，且各自为政 ——
+ *   1. `ViewImageTool` 自己判断 `endpoint.id === "deepseek"` 再上传（端点 id 一变就失效）；
+ *   2. `mcp/mcpTools.ts` 自己把 MCP 的 base64 归一成 `image_url` / `file` 块；
+ *   3. CLI 侧又实现了一遍「上传 or base64」。
+ *
+ * 现在统一到这里，调用方只提供「文件 + 当前端点/模型」，传输方式由本模块决定：
+ *
+ * | 条件 | 结果 |
+ * |------|------|
+ * | http(s) URL | 直接 `image_url`（不上传、不内联） |
+ * | 端点声明 `capabilities.filesApi` | 上传 Files API → `file` 块（`file_id`），失败降级为内联 |
+ * | 其余端点 + 图片 | `image_url` + base64 data URL |
+ * | 其余端点 + 非图片 | `file` 块 + `file_data`（base64 data URL） |
+ * | 模型明确不支持视觉（`vision === false`）且是图片 | 退化为 `text`，只给路径提示 |
+ * | 内联体积超过上限且无法上传 | 抛错（不静默塞进请求体） |
+ */
+import OpenAI, { toFile } from "openai";
+import { createHash } from "node:crypto";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+/** 扩展名 → MIME。图片走视觉通道，其余走 `file` 块 */
+export const MIME_BY_EXT = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".pdf": "application/pdf",
+    ".txt": "text/plain",
+    ".md": "text/markdown",
+    ".json": "application/json",
+};
+/** 按扩展名推断 MIME；未知扩展名返回 undefined */
+export function mimeOf(filePath) {
+    const dot = filePath.lastIndexOf(".");
+    if (dot < 0)
+        return undefined;
+    return MIME_BY_EXT[filePath.slice(dot).toLowerCase()];
+}
+/** base64 二进制转 data URL（`image_url` 与 `file.file_data` 均接受） */
+export function toDataUrl(base64, mime) {
+    return `data:${mime};base64,${base64}`;
+}
+/**
+ * base64 字符串对应的字节数（不含空白）。
+ *
+ * 用于「只看体积、不想解码」的场景：内联上限检查与日志统计。
+ */
+export function base64ByteLength(base64) {
+    const len = base64.replace(/\s/g, "").length;
+    if (len === 0)
+        return 0;
+    const pad = base64.endsWith("==") ? 2 : base64.endsWith("=") ? 1 : 0;
+    return Math.max(0, Math.floor((len * 3) / 4) - pad);
+}
+/** 内联（base64）体积上限，默认 8 MiB；超过且端点不支持上传时直接报错 */
+export const DEFAULT_MAX_INLINE_BYTES = 8 * 1024 * 1024;
+/**
+ * 由「发给 API 的模型名」反查它绑定的模型定义与端点。
+ *
+ * 工具在 `call()` 阶段拿不到 Agent 定义，但 `ctx.agent.model` 就是发给 API 的
+ * 模型名（`Model.modelName ?? Model.id`）。必须按**当前实际使用的模型**定位端点：
+ * `file_id` 是端点维度资源，传错端点会得到 not found。
+ */
+export function resolveModelAndEndpoint(config, apiModelName) {
+    const models = config.models ?? [];
+    const endpoints = config.endpoints ?? [];
+    const findEndpoint = (id) => (id ? endpoints.find((e) => e.id === id) ?? null : null);
+    const byApiName = apiModelName
+        ? models.find((m) => (m.modelName ?? m.id) === apiModelName)
+        : undefined;
+    if (byApiName)
+        return { model: byApiName, endpoint: findEndpoint(byApiName.endpointId) };
+    const fallback = models.find((m) => m.id === config.defaultModel);
+    if (fallback)
+        return { model: fallback, endpoint: findEndpoint(fallback.endpointId) };
+    return { endpoint: null };
+}
+/** 端点是否声明了 Files API 能力 */
+export function supportsFilesApi(endpoint) {
+    return endpoint?.capabilities?.filesApi === true;
+}
+/**
+ * 上传缓存：`端点id + 绝对路径 + mtime + size` → `file_id`。
+ *
+ * file_id 是**端点维度**的资源，所以 key 必须带端点 id —— 同一张图传到两个端点
+ * 会得到两个不同的 id，混用会让另一端返回 not found。
+ */
+const uploadCache = new Map();
+/** 清空上传缓存（测试用；进程内长期运行无需清理，条目有上限） */
+export function clearUploadCache() {
+    uploadCache.clear();
+}
+const UPLOAD_CACHE_LIMIT = 200;
+/** 内容哈希（sha256），用于给「内存里的字节」做上传缓存键 */
+export function contentHash(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+function cacheKey(endpoint, absPath, stat) {
+    return `${endpoint.id}\u0000${absPath}\u0000${stat.mtimeMs}\u0000${stat.size}`;
+}
+/** 内存来源的缓存键：没有路径与 mtime，改用内容哈希（同一张图不会重复上传） */
+function contentCacheKey(endpoint, hash) {
+    return `${endpoint.id}\u0000sha256:${hash}`;
+}
+function rememberUpload(key, fileId) {
+    uploadCache.set(key, fileId);
+    while (uploadCache.size > UPLOAD_CACHE_LIMIT) {
+        const oldest = uploadCache.keys().next();
+        if (oldest.done)
+            break;
+        uploadCache.delete(oldest.value);
+    }
+}
+/** 默认上传实现：OpenAI 兼容的 `POST {baseUrl}/files`（`purpose=user_data`） */
+const defaultUpload = async ({ endpoint, data, filename, signal }) => {
+    const client = new OpenAI({ apiKey: endpoint.apiKey, baseURL: endpoint.baseUrl });
+    const file = await toFile(Buffer.from(data), filename);
+    const uploaded = await client.files.create({ file, purpose: "user_data" }, { signal });
+    return uploaded.id;
+};
+function isRemoteUrl(value) {
+    return /^https?:\/\//i.test(value);
+}
+function textSection(text) {
+    return { type: "text", text };
+}
+/**
+ * 把文件转成内容块。
+ *
+ * 抛错场景（均由调用方决定如何呈现给模型）：
+ * - `source.url` 不是 http(s)（本地 URL 服务商访问不到）
+ * - 本地文件不存在 / 不是文件 / 扩展名不支持
+ * - 需要内联但体积超过上限，且端点不支持上传
+ */
+export async function fileToContentSection(input) {
+    const { source, endpoint, model, signal } = input;
+    const maxInline = input.maxInlineBytes ?? DEFAULT_MAX_INLINE_BYTES;
+    // ---- 1. 网络 URL：直接引用，不经上传/内联 ----
+    if ("url" in source) {
+        if (!isRemoteUrl(source.url)) {
+            throw new Error(`不支持本地 URL（${source.url}）：API 服务商无法访问。本地文件请传文件路径，而不是本地链接。`);
+        }
+        return {
+            section: { type: "image_url", image_url: { url: source.url } },
+            transport: "url",
+            bytes: 0,
+        };
+    }
+    // ---- 2. 取得字节与 MIME ----
+    // 已经是 base64 的来源（MCP）：先不解码，内联时原样透传，只有真要上传/算哈希时才解码
+    let base64 = null;
+    let bytes = null;
+    let byteLength;
+    let mime;
+    let filename;
+    let absPath = null;
+    let stat = null;
+    if ("path" in source) {
+        absPath = path.isAbsolute(source.path) ? source.path : path.resolve(source.path);
+        const st = await fs.stat(absPath);
+        if (!st.isFile())
+            throw new Error(`"${absPath}" 不是文件。`);
+        const inferred = mimeOf(absPath);
+        if (!inferred) {
+            throw new Error(`不支持的文件类型："${absPath}"（已知类型：${Object.keys(MIME_BY_EXT).join(" ")}）`);
+        }
+        mime = inferred;
+        stat = { mtimeMs: st.mtimeMs, size: st.size };
+        bytes = new Uint8Array(await fs.readFile(absPath));
+        byteLength = bytes.byteLength;
+        filename = path.basename(absPath);
+    }
+    else if ("base64" in source) {
+        mime = source.mime;
+        base64 = source.base64;
+        byteLength = base64ByteLength(base64);
+        filename = source.filename ?? "file";
+    }
+    else {
+        mime = source.mime;
+        bytes = source.data;
+        byteLength = bytes.byteLength;
+        filename = source.filename ?? "file";
+    }
+    /** 需要真实字节时才解码（上传、算内容哈希） */
+    const ensureBytes = () => {
+        if (!bytes)
+            bytes = new Uint8Array(Buffer.from(base64 ?? "", "base64"));
+        return bytes;
+    };
+    const isImage = mime.startsWith("image/");
+    // ---- 3. 模型看不见图：退化为文本提示 ----
+    // 判定口径与 `ViewImageTool.isAvailable` 一致：只有 `vision === true` 才算视觉模型，
+    // 缺省视为不支持（模型未提供 model 时不做判断，交给调用方）。
+    // 对任何来源都生效（本地路径给路径，内存来源给文件名）：非视觉模型收到 image_url
+    // 可能直接 4xx，宁可退化成一行提示。
+    if (isImage && model && model.vision !== true) {
+        const label = absPath ?? filename;
+        return {
+            section: textSection(`[图片] ${label}（当前模型不支持图片输入，如需查看请改用视觉模型）`),
+            transport: "text",
+            bytes: byteLength,
+            warning: "当前模型不支持图片输入，已退化为文本提示",
+        };
+    }
+    // ---- 4. 端点支持 Files API：上传（带缓存），失败降级内联 ----
+    let warning;
+    if (supportsFilesApi(endpoint) && endpoint?.apiKey) {
+        const key = absPath && stat
+            ? cacheKey(endpoint, absPath, stat)
+            : contentCacheKey(endpoint, contentHash(ensureBytes()));
+        const cached = uploadCache.get(key);
+        if (cached) {
+            return {
+                section: { type: "file", file_id: cached },
+                transport: "files-api",
+                bytes: byteLength,
+            };
+        }
+        try {
+            const upload = input.deps?.upload ?? defaultUpload;
+            const fileId = await upload({ endpoint, data: ensureBytes(), filename, signal });
+            rememberUpload(key, fileId);
+            return {
+                section: { type: "file", file_id: fileId },
+                transport: "files-api",
+                bytes: byteLength,
+            };
+        }
+        catch (error) {
+            if (signal?.aborted)
+                throw error;
+            warning = `上传 Files API 失败，已改为 base64 内联：${error?.message ?? error}`;
+        }
+    }
+    // ---- 5. 内联（base64 data URL）----
+    if (byteLength > maxInline) {
+        throw new Error(`文件体积 ${(byteLength / 1024 / 1024).toFixed(1)} MiB 超过内联上限 ` +
+            `${(maxInline / 1024 / 1024).toFixed(1)} MiB，且端点未声明 Files API 能力` +
+            `（capabilities.filesApi），无法发送。`);
+    }
+    // base64 来源直接透传，不重新编码（保证字节级一致，也省一次编解码）
+    const dataUrl = toDataUrl(base64 ?? Buffer.from(ensureBytes()).toString("base64"), mime);
+    return {
+        section: isImage
+            ? { type: "image_url", image_url: { url: dataUrl } }
+            : { type: "file", file_data: dataUrl, filename },
+        transport: "inline",
+        bytes: byteLength,
+        warning,
+    };
+}

package/dist/types/index.d.ts

@@ -12,6 +12,19 @@ export interface AgentPermissions {
     mcps?: PermissionPolicy;
     subagents?: PermissionPolicy;
 }
+/**
+ * 端点能力声明 —— 决定「本地文件 → 内容块」时走哪条传输路径。
+ *
+ * 之前这段判断硬编码在 ViewImageTool 里（`endpoint.id === "deepseek"`），
+ * 用户改一下端点 id 就失效；改为显式能力位后，新端点只要声明能力即可享受上传。
+ */
+export interface EndpointCapabilities {
+    /**
+     * 是否支持 OpenAI 兼容的 Files API（`POST {baseUrl}/files`，`purpose=user_data`）。
+     * 为 true 时本地文件优先上传并以 `file` 块（file_id）发送；否则走 base64 内联。
+     */
+    filesApi?: boolean;
+}
 /** API 端点 */
 export interface Endpoint {
     id: string;
@@ -19,6 +32,7 @@ export interface Endpoint {
     baseUrl: string;
     apiKey: string;
     description?: string;
+    capabilities?: EndpointCapabilities;
 }
 /** 模型配置，绑定一个 Endpoint */
 export interface Model {

package/package.json

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