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

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

@@ -1,8 +1,9 @@
 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();
 /**
  * 创建 load_mcp 工具。
  * server 枚举由 filteredMcps （完整 McpServerConfig[]）自动推导，
@@ -68,7 +69,7 @@ export function createLoadMcpTool(mcpManager, filteredMcps) {
             }
             // 静默模式：只回吐摘要（清单仍留在管理器内，供 call_mcp_tool 使用）
             if (!includeManifest) {
-                log.info(`[load_mcp] ${serverName}: 已连接（未披露清单：工具 ${manifest.tools.length} 个，资源 ${manifest.resources.length} 个）`);
+                getLogger().info(`[load_mcp] ${serverName}: 已连接（未披露清单：工具 ${manifest.tools.length} 个，资源 ${manifest.resources.length} 个）`);
                 return JSON.stringify({
                     server: serverName,
                     connected: true,
@@ -76,20 +77,177 @@ export function createLoadMcpTool(mcpManager, filteredMcps) {
                     resources: manifest.resources.length,
                 });
             }
-            log.info(`[load_mcp] ${serverName}:\n${JSON.stringify(manifest, null, 2)}`);
+            getLogger().info(`[load_mcp] ${serverName}:\n${JSON.stringify(manifest, null, 2)}`);
             return JSON.stringify({ tools: manifest.tools, resources: manifest.resources });
         },
     });
 }
+/** 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 +275,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 +302,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 +331,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/scope/plugins/skills/discover.js

@@ -1,7 +1,6 @@
 import { promises as fs } from "node:fs";
 import { join } from "node:path";
 import { getLogger } from "../../../shared/logger.js";
-const log = getLogger();
 // ---- 发现（返回完整 SkillInfo，不再丢失 subAgent 等信息）----
 /**
  * 扫描多个目录中发现的所有 Skill（含 SKILL.md 的子目录）。
@@ -78,7 +77,7 @@ async function readSkillFromPath(skillId, skillMdPath, silent) {
         if (!silent) {
             const errors = validateSkill(skillId, fm);
             for (const err of errors) {
-                log.warn(`[skills] ${err.skillId}: ${err.field} — ${err.message}`);
+                getLogger().warn(`[skills] ${err.skillId}: ${err.field} — ${err.message}`);
             }
         }
         return {

package/dist/scope/plugins/skills/skillTools.js

@@ -1,9 +1,7 @@
 import { CallbackTool, Agent, AgentToolLazy, Message } from "@ai-zen/agents-core";
 import { createDisclosureParam } from "../../disclosure.js";
 import { readSkill } from "./discover.js";
-import { getLogger } from "../../../shared/logger.js";
 import { promises as fs } from "node:fs";
-const log = getLogger();
 const EMPTY_HINT = "（当前没有可用的 Skill，请联系用户添加）";
 /**
  * 创建 load_skill 工具。

package/dist/scope/plugins/subagents/subAgentTools.js

@@ -24,7 +24,8 @@ export function createSubAgentTool(def, scope) {
             let model;
             let modelConfig;
             if (def.modelId) {
-                const m = createModel(scope, def.modelId);
+                // SubAgent 可声明自己的模型与参数覆盖（与主 Agent 同一套规则：直接合并）
+                const m = createModel(scope, def.modelId, def.modelParams);
                 client = m.client;
                 model = m.model;
                 modelConfig = m.modelConfig;

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,253 @@
+/**
+ * 本地文件 → 消息内容块的唯一转换入口。
+ *
+ * 背景：这段逻辑原先散落三处，且各自为政 ——
+ *   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) };
+    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,
+    };
+}