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

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/shared/errors.d.ts

@@ -8,17 +8,13 @@ export declare class SdkError extends Error {
 }
 /**
  * 上下文超限错误。由 ContextGuardPlugin 在请求前抛出，用于中断对话。
- * 触发条件通常是上下文 token 用量远超阈值（如读入超大文件），
+ * 触发条件通常是上下文 token 用量超过硬线（如读入超大文件），
  * 继续对话已无意义且会持续放大费用/延迟，故由上层捕获后向用户显式报错。
  */
 export declare class ContextOverflowError extends Error {
     /** 触发中断时的刚用量（usage.prompt_tokens） */
     readonly promptTokens: number;
-    /** 配置的告警阈值（maxTokens） */
-    readonly maxTokens: number;
-    /** 实际生效的硬上限（maxTokens × ratio，越界即中断） */
-    readonly threshold: number;
-    /** 超出比例（如 1.2 表示 20%） */
-    readonly ratio: number;
-    constructor(promptTokens: number, maxTokens: number, ratio: number);
+    /** 被越过的强行阻断阈值（`tokenThresholds.guard`，绝对值） */
+    readonly guardTokens: number;
+    constructor(promptTokens: number, guardTokens: number);
 }

package/dist/shared/errors.js

@@ -15,26 +15,20 @@ export class SdkError extends Error {
 }
 /**
  * 上下文超限错误。由 ContextGuardPlugin 在请求前抛出，用于中断对话。
- * 触发条件通常是上下文 token 用量远超阈值（如读入超大文件），
+ * 触发条件通常是上下文 token 用量超过硬线（如读入超大文件），
  * 继续对话已无意义且会持续放大费用/延迟，故由上层捕获后向用户显式报错。
  */
 export class ContextOverflowError extends Error {
     /** 触发中断时的刚用量（usage.prompt_tokens） */
     promptTokens;
-    /** 配置的告警阈值（maxTokens） */
-    maxTokens;
-    /** 实际生效的硬上限（maxTokens × ratio，越界即中断） */
-    threshold;
-    /** 超出比例（如 1.2 表示 20%） */
-    ratio;
-    constructor(promptTokens, maxTokens, ratio) {
-        const threshold = maxTokens * ratio;
-        super(`🛑 上下文严重超限：已用 ${promptTokens} token，超过硬上限 ${threshold}（${Math.round((ratio - 1) * 100)}%，配置上限 ${maxTokens}）。` +
-            `当前对话可能因读入超大文件而失控，已中断，请检查并重新开始。`);
+    /** 被越过的强行阻断阈值（`tokenThresholds.guard`，绝对值） */
+    guardTokens;
+    constructor(promptTokens, guardTokens) {
+        super(`🛑 上下文严重超限：已用 ${promptTokens} token，超过阻断阈值 ${guardTokens}。` +
+            `当前对话可能因读入超大文件而失控，已中断，请检查并重新开始。` +
+            `（如确需更长上下文，请调高 config.json 中该模型的 tokenThresholds.guard。）`);
         this.name = "ContextOverflowError";
         this.promptTokens = promptTokens;
-        this.maxTokens = maxTokens;
-        this.threshold = threshold;
-        this.ratio = ratio;
+        this.guardTokens = guardTokens;
     }
 }

package/dist/shared/reasoning.d.ts

@@ -0,0 +1,64 @@
+/**
+ * 思考强度（reasoning effort）—— 能力声明、可用档位与参数写入的唯一实现
+ *
+ * 为什么要有这一层：档位不是全局统一枚举，各端点接受的值域**互不相同**，而且
+ * 同一家不同型号也不同（智谱文档原文）：
+ *
+ * | 端点 | 官方依据 | 可调档位 | 能否关闭 |
+ * |------|---------|---------|---------|
+ * | DeepSeek | `/guides/thinking_mode` | `low / high / max` | 能，`thinking.type = "disabled"` |
+ * | 智谱 GLM-5.3 系 | `/cn/guide/capabilities/thinking` | `low / high / max`（**其余报错**） | **不能**，传 disabled 直接报错 |
+ * | 智谱 GLM-5.2 | 同上 | `none / minimal / low / medium / high / xhigh / max` | 能（`none` 或 `disabled`） |
+ * | OpenAI | `openai-node` 的 `Shared.ReasoningEffort` | `minimal / low / medium / high`（枚举含 none/xhigh/max） | 能，`reasoning_effort = "none"` |
+ *
+ * 所以「能力声明在模型上，Agent 只能收窄」，写入时按声明选择表达方式，
+ * 绝不把端点不认的值发出去。
+ */
+import type { AgentDefinition, Model, ReasoningCapability, ReasoningEffort } from "../types/index.js";
+/** 是否为合法档位值 */
+export declare function isReasoningEffort(value: unknown): value is ReasoningEffort;
+/** 模型的能力声明（缺省 = 不可调档） */
+export declare function capabilityOf(model?: Model | null): ReasoningCapability | undefined;
+/**
+ * 模型可调的档位（不含 `off`）。
+ *
+ * 未声明能力的模型返回空数组 —— 不猜、不给默认值，避免把非法参数发给服务端。
+ */
+export declare function modelEfforts(model?: Model | null): ReasoningEffort[];
+/**
+ * 模型允许的全部取值（含 `off`）。
+ *
+ * `off` 只在声明了 `disable` 方式时出现：没有合法表达式时，「关闭思考」这个选项
+ * 本身就不该出现在菜单里。
+ */
+export declare function modelAllowedEfforts(model?: Model | null): ReasoningEffort[];
+/**
+ * 从 `defaultParams` 读当前档位。
+ *
+ * 返回 `undefined` 表示「没有显式档位」：可能是模型默认开思考但没写 effort
+ * （DeepSeek 出厂配置就是 `{thinking:{type:"enabled"}}`），也可能压根没有思考参数。
+ * 展示层要区分这两种情况，请配合 `capabilityOf()` 判断。
+ */
+export declare function readReasoningEffort(params?: Record<string, unknown> | null): ReasoningEffort | undefined;
+/**
+ * 按档位生成新的 `defaultParams`（不改入参）。
+ *
+ * 三种写入形态，取决于模型声明：
+ * - `disable: "thinking"` → 同时维护 `thinking.type` 与 `reasoning_effort`
+ * - `disable: "effort-none"` → 只写 `reasoning_effort`（OpenAI 不认 `thinking` 键，
+ *   对它写 `thinking` 会被当作未知参数拒绝）
+ * - 未声明 `disable`（如 GLM-5.3 系）→ 只写 `reasoning_effort`，传 `off` 直接抛错
+ *
+ * @throws 当档位为 `off` 而模型不支持关闭思考，或档位不在模型能力范围内
+ */
+export declare function applyReasoningEffort(params: Record<string, unknown> | undefined | null, model: Model | null | undefined, effort: ReasoningEffort): Record<string, unknown>;
+/**
+ * 解析某 Agent 的实际档位：Agent 声明优先，否则看模型默认参数。
+ */
+export declare function resolveReasoningEffort(model?: Model | null, definition?: Pick<AgentDefinition, "reasoningEffort"> | null): ReasoningEffort | undefined;
+/**
+ * 把 Agent 的档位覆盖应用到模型参数上（`createModel` 用）。
+ *
+ * 未声明 `reasoningEffort` 时原样返回模型参数，保证既有行为不变。
+ */
+export declare function resolveModelParams(model?: Model | null, definition?: Pick<AgentDefinition, "reasoningEffort"> | null): Record<string, unknown> | undefined;

package/dist/shared/reasoning.js

@@ -0,0 +1,151 @@
+/**
+ * 思考强度（reasoning effort）—— 能力声明、可用档位与参数写入的唯一实现
+ *
+ * 为什么要有这一层：档位不是全局统一枚举，各端点接受的值域**互不相同**，而且
+ * 同一家不同型号也不同（智谱文档原文）：
+ *
+ * | 端点 | 官方依据 | 可调档位 | 能否关闭 |
+ * |------|---------|---------|---------|
+ * | DeepSeek | `/guides/thinking_mode` | `low / high / max` | 能，`thinking.type = "disabled"` |
+ * | 智谱 GLM-5.3 系 | `/cn/guide/capabilities/thinking` | `low / high / max`（**其余报错**） | **不能**，传 disabled 直接报错 |
+ * | 智谱 GLM-5.2 | 同上 | `none / minimal / low / medium / high / xhigh / max` | 能（`none` 或 `disabled`） |
+ * | OpenAI | `openai-node` 的 `Shared.ReasoningEffort` | `minimal / low / medium / high`（枚举含 none/xhigh/max） | 能，`reasoning_effort = "none"` |
+ *
+ * 所以「能力声明在模型上，Agent 只能收窄」，写入时按声明选择表达方式，
+ * 绝不把端点不认的值发出去。
+ */
+/** `defaultParams` 里承载开关的键 */
+const THINKING_KEY = "thinking";
+/** `defaultParams` 里承载档位的键 */
+const EFFORT_KEY = "reasoning_effort";
+const KNOWN_EFFORTS = [
+    "off",
+    "none",
+    "minimal",
+    "low",
+    "medium",
+    "high",
+    "xhigh",
+    "max",
+];
+/** 是否为合法档位值 */
+export function isReasoningEffort(value) {
+    return typeof value === "string" && KNOWN_EFFORTS.includes(value);
+}
+/** 模型的能力声明（缺省 = 不可调档） */
+export function capabilityOf(model) {
+    return model?.reasoning;
+}
+/**
+ * 模型可调的档位（不含 `off`）。
+ *
+ * 未声明能力的模型返回空数组 —— 不猜、不给默认值，避免把非法参数发给服务端。
+ */
+export function modelEfforts(model) {
+    return [...(capabilityOf(model)?.efforts ?? [])];
+}
+/**
+ * 模型允许的全部取值（含 `off`）。
+ *
+ * `off` 只在声明了 `disable` 方式时出现：没有合法表达式时，「关闭思考」这个选项
+ * 本身就不该出现在菜单里。
+ */
+export function modelAllowedEfforts(model) {
+    const capability = capabilityOf(model);
+    if (!capability)
+        return [];
+    return capability.disable ? ["off", ...capability.efforts] : [...capability.efforts];
+}
+function thinkingType(params) {
+    const thinking = params?.[THINKING_KEY];
+    if (typeof thinking !== "object" || thinking === null)
+        return undefined;
+    const type = thinking.type;
+    return typeof type === "string" ? type : undefined;
+}
+/**
+ * 从 `defaultParams` 读当前档位。
+ *
+ * 返回 `undefined` 表示「没有显式档位」：可能是模型默认开思考但没写 effort
+ * （DeepSeek 出厂配置就是 `{thinking:{type:"enabled"}}`），也可能压根没有思考参数。
+ * 展示层要区分这两种情况，请配合 `capabilityOf()` 判断。
+ */
+export function readReasoningEffort(params) {
+    if (thinkingType(params) === "disabled")
+        return "off";
+    const raw = params?.[EFFORT_KEY];
+    if (typeof raw !== "string")
+        return undefined;
+    // `none` 与 `off` 语义一致（都表示不思考），统一归一为 off，避免菜单里出现两个「关」
+    if (raw === "none")
+        return "off";
+    return isReasoningEffort(raw) ? raw : undefined;
+}
+/**
+ * 按档位生成新的 `defaultParams`（不改入参）。
+ *
+ * 三种写入形态，取决于模型声明：
+ * - `disable: "thinking"` → 同时维护 `thinking.type` 与 `reasoning_effort`
+ * - `disable: "effort-none"` → 只写 `reasoning_effort`（OpenAI 不认 `thinking` 键，
+ *   对它写 `thinking` 会被当作未知参数拒绝）
+ * - 未声明 `disable`（如 GLM-5.3 系）→ 只写 `reasoning_effort`，传 `off` 直接抛错
+ *
+ * @throws 当档位为 `off` 而模型不支持关闭思考，或档位不在模型能力范围内
+ */
+export function applyReasoningEffort(params, model, effort) {
+    const capability = capabilityOf(model);
+    const next = { ...(params ?? {}) };
+    if (effort === "off") {
+        if (capability?.disable === "thinking") {
+            next[THINKING_KEY] = { type: "disabled" };
+            delete next[EFFORT_KEY];
+            return next;
+        }
+        if (capability?.disable === "effort-none") {
+            next[EFFORT_KEY] = "none";
+            // 不在 OpenAI 的请求里塞 thinking：那是未知参数
+            delete next[THINKING_KEY];
+            return next;
+        }
+        throw new Error(`模型 "${model?.id ?? "(未知)"}" 不支持关闭思考`);
+    }
+    if (!capability) {
+        throw new Error(`模型 "${model?.id ?? "(未知)"}" 未声明思考能力，无法设置档位`);
+    }
+    if (!capability.efforts.includes(effort)) {
+        throw new Error(`模型 "${model?.id ?? "(未知)"}" 不支持档位 "${effort}"（可选：${capability.efforts.join(" / ")}）`);
+    }
+    if (capability.disable === "thinking") {
+        next[THINKING_KEY] = { type: "enabled" };
+    }
+    next[EFFORT_KEY] = effort;
+    return next;
+}
+/**
+ * 解析某 Agent 的实际档位：Agent 声明优先，否则看模型默认参数。
+ */
+export function resolveReasoningEffort(model, definition) {
+    const declared = definition?.reasoningEffort;
+    if (declared) {
+        // 声明了但模型不支持 → 退化为模型默认，避免把非法值发给服务端
+        const allowed = modelAllowedEfforts(model);
+        if (allowed.length === 0 || allowed.includes(declared))
+            return declared;
+    }
+    return readReasoningEffort(model?.defaultParams);
+}
+/**
+ * 把 Agent 的档位覆盖应用到模型参数上（`createModel` 用）。
+ *
+ * 未声明 `reasoningEffort` 时原样返回模型参数，保证既有行为不变。
+ */
+export function resolveModelParams(model, definition) {
+    const declared = definition?.reasoningEffort;
+    if (!declared)
+        return model?.defaultParams;
+    const allowed = modelAllowedEfforts(model);
+    // 模型不支持声明值：宁可保持模型默认，也不发非法参数
+    if (allowed.length === 0 || !allowed.includes(declared))
+        return model?.defaultParams;
+    return applyReasoningEffort(model?.defaultParams, model, declared);
+}

package/dist/types/index.d.ts

@@ -12,6 +12,48 @@ 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;
+}
+/**
+ * 思考强度档位 —— 各端点官方枚举的**并集**，不含各家不认的值。
+ *
+ * OpenAI（`openai-node` 的 `Shared.ReasoningEffort`）：`none | minimal | low | medium | high | xhigh | max`
+ * DeepSeek（`/guides/thinking_mode`）：`low | high | max`（另接受 minimal/medium/xhigh/ultra 并做映射）
+ * 智谱 GLM-5.3 系（`/cn/guide/capabilities/thinking`）：`low | high | max`，**其余值直接报错**
+ * 智谱 GLM-5.2：`none | minimal | low | medium | high | xhigh | max`
+ *
+ * `off` 是本 SDK 的语义值（「关闭思考」），对接时按 `ReasoningCapability.disable` 选择表达方式。
+ * 它与 `none` 不重复：`none` 是端点自己认的档位值，`off` 是「没有档位、彻底不思考」。
+ */
+export type ReasoningEffort = "off" | "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+/**
+ * 模型/端点的思考能力声明（**物理上限**，来自厂商官方文档）。
+ *
+ * 刻意不推断、不猜：未声明的模型视为「不可调档」，`/think` 不会列任何选项——
+ * 发一个端点不认的值会被直接报错（智谱 5.3 系原文「其余输入将报错」）。
+ */
+export interface ReasoningCapability {
+    /** 型号真实接受的档位（不含 `off`）；空数组 = 支持思考但不可调档 */
+    efforts: ReasoningEffort[];
+    /**
+     * 关闭思考的表达方式：
+     * - `thinking` → `thinking: { type: "disabled" }`（DeepSeek / GLM-5.2）
+     * - `effort-none` → `reasoning_effort: "none"`（OpenAI / GLM-5.2）
+     * - 缺省 → 不支持关闭（如 GLM-5.3 系，传 disabled 会报错）
+     */
+    disable?: "thinking" | "effort-none";
+}
 /** API 端点 */
 export interface Endpoint {
     id: string;
@@ -19,6 +61,25 @@ export interface Endpoint {
     baseUrl: string;
     apiKey: string;
     description?: string;
+    capabilities?: EndpointCapabilities;
+}
+/**
+ * 上下文用量阈值 —— 与模型的真实窗口无关，只描述「用量到了这条线该怎么办」。
+ *
+ * 两个阈值语义不同，消费方也不同：
+ *   - `handoff`：软线。`AutoMigratePlugin` 在响应返回后拿 `usage.prompt_tokens` 比它，
+ *     超过即触发任务交接（交接本身还要再发 1~2 次请求，所以这条线必须留足余量）。
+ *   - `guard`：硬线。`ContextGuardPlugin` 在**每次请求前**比它，超过即抛
+ *     `ContextOverflowError` 中断本轮——这是最后一道保护，宁可报错也不要发出必然失败的请求。
+ *
+ * 建议 `guard ≈ handoff × 1.5`，给交接留出缓冲；两者都是绝对值，配置里写多少就是多少，
+ * 不做任何倍数换算（阈值就该是能直接读懂的数字）。
+ */
+export interface TokenThresholds {
+    /** 交接阈值（软线）：prompt_tokens 超过它 → 触发任务交接 */
+    handoff: number;
+    /** 强行阻断阈值（硬线）：请求前用量超过它 → 中断本轮并报错 */
+    guard: number;
 }
 /** 模型配置，绑定一个 Endpoint */
 export interface Model {
@@ -27,15 +88,20 @@ export interface Model {
     endpointId: string;
     modelName?: string;
     /**
-     * 任务迁移（交接）触发阈值 —— **不是**模型的真实上下文窗口。
+     * 上下文用量阈值（交接软线 + 阻断硬线）。**不是**模型的真实上下文窗口。
      *
-     * AutoMigratePlugin 不估算、不学习：只在 API 响应返回后，用 `usage.prompt_tokens`
-     * 与该值比较，超过即触发交接迁移。建议取模型真实窗口的约 25%，为 response 留出空间。
+     * 历史字段 `maxContextTokens` / `maxContextChars` 已由 `config/migrate.ts`
+     * 迁移成这个结构体并删除。
      */
-    maxContextTokens: number;
-    /** 旧版字符数阈值（兼容迁移） */
-    maxContextChars?: number;
+    tokenThresholds: TokenThresholds;
     defaultParams?: Record<string, unknown>;
+    /**
+     * 思考强度能力（按厂商官方文档声明）。缺省视为不可调档。
+     *
+     * Agent 用 `AgentDefinition.reasoningEffort` 在这个范围内选一档；
+     * 超出范围的值不会发给服务端（`resolveModelParams()` 会退回模型默认）。
+     */
+    reasoning?: ReasoningCapability;
     /** 是否支持图片输入（视觉模型）。看图工具（view_image）仅对视觉模型启用；generate_image 是否返回图片内容块也据此判断 */
     vision?: boolean;
     description?: string;
@@ -55,6 +121,13 @@ export interface AgentDefinition {
     description?: string;
     messages: AgentNS.Message[];
     modelId?: string;
+    /**
+     * 该 Agent 的思考档位（可选），覆盖模型 `defaultParams` 里的对应参数。
+     *
+     * 有了它，同一个模型可以给不同 Agent 配不同强度（编程 Agent `max`、闲聊 Agent `low`），
+     * 而模型本身的默认参数保持不变。未声明时沿用模型默认。
+     */
+    reasoningEffort?: ReasoningEffort;
     permissions?: AgentPermissions;
     function?: AgentNS.FunctionDefine;
     createdAt: string;

package/package.json

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