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

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,9 @@ 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 { applyReasoningEffort, capabilityOf, isReasoningEffort, modelAllowedEfforts, modelEfforts, readReasoningEffort, resolveModelParams, resolveReasoningEffort, } from "./shared/reasoning.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,10 @@ 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";
+// 思考强度（reasoning effort）— 能力声明、可用档位与参数写入
+export { applyReasoningEffort, capabilityOf, isReasoningEffort, modelAllowedEfforts, modelEfforts, readReasoningEffort, resolveModelParams, resolveReasoningEffort, } from "./shared/reasoning.js";
 // 运行时
 export { createModel } from "./runtime/createModel.js";
 export { SdkAgent } from "./runtime/SdkAgent.js";

package/dist/runtime/HandoffService.d.ts

@@ -37,7 +37,7 @@ export interface HandoffContext {
     /** 当前 prompt token 用量（自动迁移时由插件提供；手动触发可省略） */
     promptTokens?: number;
     /** 上下文阈值（自动迁移时由插件提供；手动触发可省略） */
-    maxTokens?: number;
+    handoffTokens?: number;
     /** 本次是否会在交接后开新会话（`migrate()` 为 true，`handoff()` 为 false）。钩子据此区分两种语义 */
     migrating: boolean;
     /** 交接前消息总数 */
@@ -83,7 +83,7 @@ export interface HandoffParams {
     /** 当前 prompt token 用量（可选，仅透传给钩子） */
     promptTokens?: number;
     /** 上下文阈值（可选，仅透传给钩子） */
-    maxTokens?: number;
+    handoffTokens?: number;
     /** 会话 id（可选，用于交接文件名，便于回溯） */
     conversationId?: string;
 }

package/dist/runtime/HandoffService.js

@@ -194,7 +194,7 @@ export class HandoffService {
         }
     }
     async runHandoff(params, migrating) {
-        const { agent, promptTokens, maxTokens, conversationId } = params;
+        const { agent, promptTokens, handoffTokens, conversationId } = params;
         const requestedMode = params.mode ?? this.defaultMode;
         const handoffPath = join(this.handoffDirPath, HandoffService.createHandoffFileName(new Date(), conversationId));
         const model = this.model ?? agent.model;
@@ -207,7 +207,7 @@ export class HandoffService {
             handoffPath,
             model,
             promptTokens,
-            maxTokens,
+            handoffTokens,
             migrating,
             messageCountBefore,
             historyText: "",
@@ -241,7 +241,7 @@ export class HandoffService {
             handoffDoc,
             model,
             promptTokens,
-            maxTokens,
+            handoffTokens,
             migrating,
             messageCountBefore,
             historyText,

package/dist/runtime/createAgent.js

@@ -18,7 +18,10 @@ export async function createAgent(scope, agentId) {
     const modelId = definition.modelId ?? scope.config.defaultModel;
     if (!modelId)
         throw new Error("未指定模型且无默认模型");
-    const { client, model, modelConfig } = createModel(scope, modelId);
+    const { client, model, modelConfig } = createModel(scope, modelId, {
+        // Agent 级思考档位覆盖（未声明时为 undefined，行为与以前一致）
+        reasoningEffort: definition.reasoningEffort,
+    });
     const tools = scope.buildTools(definition, {
         exclude: {
             subagents: definition.function?.name

package/dist/runtime/createModel.d.ts

@@ -1,5 +1,6 @@
 import OpenAI from "openai";
 import type { Scope } from "../scope/Scope.js";
+import type { AgentDefinition } from "../types/index.js";
 /**
  * Agent 模型装配结果：openai SDK client + 模型名 + 模型参数。
  * Agent 构造时直接消费此结构。
@@ -17,5 +18,9 @@ export interface AgentModel {
  *
  * 端点（baseUrl / apiKey）来自 config.endpoints，发送给 API 的模型名 = modelName || id。
  * 任何 OpenAI 兼容端点（OpenAI / 智谱 BigModel / DeepSeek 等）均可通过 baseURL 接入。
+ *
+ * `overrides.reasoningEffort` 是 **Agent 级覆盖**（`AgentDefinition.reasoningEffort`）：
+ * 同一个模型可以给不同 Agent 配不同思考强度，而模型自身的 `defaultParams` 不变。
+ * 写入方式按模型的 `reasoning` 能力声明决定（见 `shared/reasoning.ts`）。
  */
-export declare function createModel(scope: Scope, modelId: string): AgentModel;
+export declare function createModel(scope: Scope, modelId: string, overrides?: Pick<AgentDefinition, "reasoningEffort">): AgentModel;

package/dist/runtime/createModel.js

@@ -1,11 +1,16 @@
 import OpenAI from "openai";
+import { resolveModelParams } from "../shared/reasoning.js";
 /**
  * 模型工厂 — 根据 modelId 和 Scope 装配 openai SDK client。
  *
  * 端点（baseUrl / apiKey）来自 config.endpoints，发送给 API 的模型名 = modelName || id。
  * 任何 OpenAI 兼容端点（OpenAI / 智谱 BigModel / DeepSeek 等）均可通过 baseURL 接入。
+ *
+ * `overrides.reasoningEffort` 是 **Agent 级覆盖**（`AgentDefinition.reasoningEffort`）：
+ * 同一个模型可以给不同 Agent 配不同思考强度，而模型自身的 `defaultParams` 不变。
+ * 写入方式按模型的 `reasoning` 能力声明决定（见 `shared/reasoning.ts`）。
  */
-export function createModel(scope, modelId) {
+export function createModel(scope, modelId, overrides) {
     const config = scope.config;
     const modelConfig = config.models.find((m) => m.id === modelId);
     if (!modelConfig)
@@ -25,6 +30,7 @@ export function createModel(scope, modelId) {
     return {
         client,
         model: apiModelName,
-        modelConfig: modelConfig.defaultParams,
+        // 档位覆盖在这里生效：未声明 reasoningEffort 时原样返回模型 defaultParams
+        modelConfig: resolveModelParams(modelConfig, overrides),
     };
 }

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.js

@@ -51,7 +51,7 @@ export class McpScopePlugin {
             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

@@ -21,4 +21,4 @@ export declare function createCallMcpTool(mcpManager: McpConnectionManager, env:
 /**
  * 创建 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,4 +1,5 @@
 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";
@@ -82,31 +83,75 @@ export function createLoadMcpTool(mcpManager, filteredMcps) {
         },
     });
 }
-/** base64 二进制转 data URL（image_url / file_data 均接受） */
-function toDataUrl(base64, mimeType) {
-    return `data:${mimeType};base64,${base64}`;
+/** 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）归一为 `image_url` / `file` 块，
- * 原样透传给模型——图片不进字符闸门，也不丢弃。
+ * 媒体类（image / audio / resource.blob）经 `mediaSection()` → `fileToContentSection()`：
+ * 端点支持 Files API 时上传为 `file` 块，否则 base64 内联——图片不进字符闸门，也不丢弃。
  */
-function toMessageSection(block) {
+async function toMessageSection(block, media) {
     switch (block?.type) {
         case "image":
-            return {
-                type: "image_url",
-                image_url: { url: toDataUrl(block.data, block.mimeType ?? "image/png") },
-            };
+            return await mediaSection(block.data, block.mimeType ?? "image/png", media);
         case "audio":
-            // AgentNS 无独立音频块，以 Files API 的 file_data（base64 data URL）内联承载
-            return {
-                type: "file",
-                file_data: toDataUrl(block.data, block.mimeType ?? "audio/wav"),
-            };
+            // AgentNS 无独立音频块，以 `file` 块承载（支持上传的端点 → file_id，否则 file_data 内联）
+            return await mediaSection(block.data, block.mimeType ?? "audio/wav", media);
         case "resource": {
             const r = block.resource ?? {};
             // 内嵌文本资源：本质是纯文本，并入正文（同样受输出保护）
@@ -115,9 +160,7 @@ function toMessageSection(block) {
             // 内嵌二进制资源：按 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 await mediaSection(r.blob, mime, media);
             }
             return { type: "text", text: `[资源] ${r.uri ?? "(未知 URI)"}` };
         }
@@ -205,7 +248,7 @@ 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: {
@@ -241,7 +284,11 @@ export function createCallMcpTool(mcpManager, env) {
                     const json = JSON.stringify(result);
                     return await protectCallOutput({ sections: [{ type: "text", text: json }], fullText: json, chars: json.length, isError }, env);
                 }
-                const sections = contents.map(toMessageSection);
+                // 按当前模型定位端点：决定媒体走 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);
@@ -256,11 +303,11 @@ export function createCallMcpTool(mcpManager, env) {
 /**
  * 创建 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: {
@@ -285,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>;