@jsonstudio/llms 0.6.230 → 0.6.375

package/README.md

@@ -21,6 +21,8 @@
 
 👉 **Hub Pipeline 是当前唯一入口。** 如果 Host 需要直接编排 Virtual Router，请参见 `docs/HUB_PIPELINE_USAGE.md`，了解如何通过 `bootstrapVirtualRouterConfig` + `HubPipeline` 完成初始化与热更新。
 
+👉 **ServerTool 是所有 server-side 工具的唯一统一框架。** web_search / vision followup 等服务端工具均在 llmswitch-core 内部通过 ServerTool 执行，Host 只需提供 providerInvoker/reenterPipeline 即可。设计与接入方式详见 `docs/SERVERTOOL_DESIGN.md`。
+
 ## 总览
 
 ```

package/dist/conversion/codecs/gemini-openai-codec.js

@@ -185,6 +185,8 @@ export function buildOpenAIChatFromGeminiResponse(payload) {
     const toolCalls = [];
     const toolResultTexts = [];
     const toolOutputs = [];
+    // 为当前响应内生成稳定的工具调用 ID，避免下游 ServerTool 因缺少 id 而跳过。
+    let toolCallCounter = 0;
     for (const part of parts) {
         if (!part || typeof part !== 'object')
             continue;
@@ -227,7 +229,7 @@ export function buildOpenAIChatFromGeminiResponse(payload) {
             const name = typeof fc.name === 'string' ? String(fc.name) : undefined;
             if (!name)
                 continue;
-            const id = typeof fc.id === 'string' ? String(fc.id) : undefined;
+            let id = typeof fc.id === 'string' && fc.id.trim().length ? String(fc.id).trim() : undefined;
             const argsRaw = (fc.args ?? fc.arguments);
             let argsStr;
             if (typeof argsRaw === 'string') {
@@ -237,6 +239,12 @@ export function buildOpenAIChatFromGeminiResponse(payload) {
                 argsStr = safeJson(argsRaw);
             }
             const thoughtSignature = coerceThoughtSignature(pObj.thoughtSignature);
+            // Gemini 某些响应中的 functionCall 不带 id，但下游 servertool 需要稳定的
+            // tool_call.id 才会识别为有效工具调用；此处在缺失时生成本响应内唯一的占位 ID。
+            if (!id) {
+                const suffix = toolCallCounter++;
+                id = `gemini_tool_${suffix}`;
+            }
             const toolCall = {
                 id,
                 type: 'function',

package/dist/conversion/compat/actions/gemini-web-search.d.ts

@@ -0,0 +1,17 @@
+import type { JsonObject } from '../../hub/types/json.js';
+import type { AdapterContext } from '../../hub/types/chat-envelope.js';
+/**
+ * Gemini web_search 请求适配（作用于 Gemini 请求 payload，而不是 ChatEnvelope）：
+ *
+ * - 仅在 routeId 以 `web_search` 开头时生效（来自 AdapterContext.routeId）；
+ * - 针对 Gemini 请求中的 `tools` 字段进行清洗：
+ *   - 保留 name === 'web_search' 的 functionDeclarations（如果存在）；
+ *   - 丢弃其它 Codex 自身工具（exec_command / MCP 等），避免 Cloud Code 报
+ *     “Multiple tools are supported only when they are all search tools.”；
+ *   - 如果清洗后没有任何工具，则删除 `tools` 字段。
+ *
+ * 注意：
+ * - 这里处理的是 llmswitch-core 为 gemini-chat 构造的中间 payload（buildGeminiRequestFromChat 输出）；
+ * - 对于 Gemini CLI 后续在传输层添加的 googleSearch 工具，本适配不负责构造或修改。
+ */
+export declare function applyGeminiWebSearchCompat(payload: JsonObject, adapterContext?: AdapterContext): JsonObject;

package/dist/conversion/compat/actions/gemini-web-search.js

@@ -0,0 +1,68 @@
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/**
+ * Gemini web_search 请求适配（作用于 Gemini 请求 payload，而不是 ChatEnvelope）：
+ *
+ * - 仅在 routeId 以 `web_search` 开头时生效（来自 AdapterContext.routeId）；
+ * - 针对 Gemini 请求中的 `tools` 字段进行清洗：
+ *   - 保留 name === 'web_search' 的 functionDeclarations（如果存在）；
+ *   - 丢弃其它 Codex 自身工具（exec_command / MCP 等），避免 Cloud Code 报
+ *     “Multiple tools are supported only when they are all search tools.”；
+ *   - 如果清洗后没有任何工具，则删除 `tools` 字段。
+ *
+ * 注意：
+ * - 这里处理的是 llmswitch-core 为 gemini-chat 构造的中间 payload（buildGeminiRequestFromChat 输出）；
+ * - 对于 Gemini CLI 后续在传输层添加的 googleSearch 工具，本适配不负责构造或修改。
+ */
+export function applyGeminiWebSearchCompat(payload, adapterContext) {
+    const routeId = typeof adapterContext?.routeId === 'string' ? adapterContext.routeId : '';
+    if (!routeId || !routeId.toLowerCase().startsWith('web_search')) {
+        return payload;
+    }
+    const cloned = { ...payload };
+    // 对于 Gemini Chat 后端，请求根节点不支持自定义 `web_search` 字段，
+    // 统一在 compat 层移除，避免触发
+    // "Unknown name \"web_search\" at 'request': Cannot find field." 错误。
+    if (cloned.web_search !== undefined) {
+        delete cloned.web_search;
+    }
+    const toolsRaw = cloned.tools;
+    // 当 web_search 路由下完全没有 tools 时，为 Gemini 搜索模型注入最小 googleSearch 工具，
+    // 保持与 gcli2api 类似的“搜索模型自动启用 Search 工具”行为。
+    if (!Array.isArray(toolsRaw)) {
+        cloned.tools = [{ googleSearch: {} }];
+        return cloned;
+    }
+    const nextTools = [];
+    for (const entry of toolsRaw) {
+        if (!isRecord(entry))
+            continue;
+        // 1) 保留 name === 'web_search' 的 functionDeclarations（单函数声明）。
+        const decls = Array.isArray(entry.functionDeclarations)
+            ? entry.functionDeclarations
+            : [];
+        const webSearchDecls = decls.filter((fn) => {
+            if (!isRecord(fn))
+                return false;
+            const name = typeof fn.name === 'string' ? fn.name.trim().toLowerCase() : '';
+            return name === 'web_search';
+        });
+        if (webSearchDecls.length) {
+            nextTools.push({
+                functionDeclarations: webSearchDecls
+            });
+            continue;
+        }
+        // 2) 若上游已经构造了 googleSearch 工具，则保留。
+        if (isRecord(entry.googleSearch)) {
+            nextTools.push({ googleSearch: entry.googleSearch });
+        }
+    }
+    if (nextTools.length > 0) {
+        cloned.tools = nextTools;
+    }
+    else {
+        // 3) 清洗后没有任何工具时，再次注入一个最小 googleSearch 工具，确保搜索模型仍然启用 Search。
+        cloned.tools = [{ googleSearch: {} }];
+    }
+    return cloned;
+}

package/dist/conversion/compat/actions/glm-image-content.d.ts

@@ -0,0 +1,2 @@
+import type { JsonObject } from '../../hub/types/json.js';
+export declare function applyGlmImageContentTransform(payload: JsonObject): JsonObject;

package/dist/conversion/compat/actions/glm-image-content.js

@@ -0,0 +1,83 @@
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+function normalizeImagePart(part) {
+    const rawType = typeof part.type === 'string' ? part.type.toLowerCase() : '';
+    if (rawType !== 'image' && rawType !== 'image_url') {
+        return null;
+    }
+    // Try multiple locations for the URL, since different inbound
+    // protocols may populate different keys.
+    const imageUrlBlock = isRecord(part.image_url)
+        ? part.image_url
+        : undefined;
+    let url;
+    if (imageUrlBlock && typeof imageUrlBlock.url === 'string') {
+        url = imageUrlBlock.url;
+    }
+    else if (typeof part.image_url === 'string') {
+        url = part.image_url;
+    }
+    else if (typeof part.url === 'string') {
+        url = part.url;
+    }
+    else if (typeof part.uri === 'string') {
+        url = part.uri;
+    }
+    else if (typeof part.data === 'string') {
+        // If caller passed a raw base64/data URI string, forward as-is.
+        url = part.data;
+    }
+    if (!url || !url.trim().length) {
+        return null;
+    }
+    const normalized = {
+        type: 'image_url',
+        image_url: {
+            url: url.trim()
+        }
+    };
+    // Preserve a best-effort "detail" field when present.
+    const detailValue = (imageUrlBlock && imageUrlBlock.detail) ?? part.detail;
+    if (typeof detailValue === 'string' && detailValue.trim().length) {
+        normalized.image_url.detail = detailValue.trim();
+    }
+    return normalized;
+}
+export function applyGlmImageContentTransform(payload) {
+    const root = structuredClone(payload);
+    const messagesValue = root.messages;
+    if (!Array.isArray(messagesValue)) {
+        return root;
+    }
+    const messages = [];
+    for (const msg of messagesValue) {
+        if (!isRecord(msg)) {
+            messages.push(msg);
+            continue;
+        }
+        const contentValue = msg.content;
+        if (!Array.isArray(contentValue)) {
+            messages.push(msg);
+            continue;
+        }
+        const newContent = [];
+        for (const part of contentValue) {
+            if (!isRecord(part)) {
+                newContent.push(part);
+                continue;
+            }
+            const normalizedImage = normalizeImagePart(part);
+            if (normalizedImage) {
+                newContent.push(normalizedImage);
+            }
+            else {
+                newContent.push(part);
+            }
+        }
+        messages.push({
+            ...msg,
+            content: newContent
+        });
+    }
+    root.messages = messages;
+    return root;
+}

package/dist/conversion/compat/actions/glm-vision-prompt.d.ts

@@ -0,0 +1,11 @@
+import type { JsonObject } from '../../hub/types/json.js';
+/**
+ * GLM 4.6V 专用视觉提示裁剪：
+ * - 仅在 model 为 glm-4.6v 且存在携带图片的 user 消息时生效；
+ * - 丢弃原有 system 与历史对话，只保留一条新的 system + 一条 user；
+ * - system：要求模型以结构化 JSON 描述截图内容、标记（圈/箭头等）及其大致 bbox；
+ * - user：保留原始用户文字（如果有）+ 单一 image_url 块。
+ *
+ * 其他模型（包括 glm-4.7、Gemini 等）不受影响。
+ */
+export declare function applyGlmVisionPromptTransform(payload: JsonObject): JsonObject;

package/dist/conversion/compat/actions/glm-vision-prompt.js

@@ -0,0 +1,177 @@
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+function extractImageUrlFromPart(part) {
+    const imageUrlBlock = isRecord(part.image_url)
+        ? part.image_url
+        : undefined;
+    let url;
+    if (imageUrlBlock && typeof imageUrlBlock.url === 'string') {
+        url = imageUrlBlock.url;
+    }
+    else if (typeof part.image_url === 'string') {
+        url = part.image_url;
+    }
+    else if (typeof part.url === 'string') {
+        url = part.url;
+    }
+    else if (typeof part.uri === 'string') {
+        url = part.uri;
+    }
+    else if (typeof part.data === 'string') {
+        url = part.data;
+    }
+    const trimmed = (url ?? '').trim();
+    return trimmed.length ? trimmed : null;
+}
+function collectUserTextFromMessage(msg) {
+    const content = msg.content;
+    if (!Array.isArray(content)) {
+        if (typeof content === 'string') {
+            return content;
+        }
+        return '';
+    }
+    const parts = [];
+    for (const entry of content) {
+        if (!isRecord(entry))
+            continue;
+        const text = entry.text;
+        if (typeof text === 'string' && text.trim().length) {
+            parts.push(text.trim());
+        }
+    }
+    return parts.join('\n');
+}
+/**
+ * GLM 4.6V 专用视觉提示裁剪：
+ * - 仅在 model 为 glm-4.6v 且存在携带图片的 user 消息时生效；
+ * - 丢弃原有 system 与历史对话，只保留一条新的 system + 一条 user；
+ * - system：要求模型以结构化 JSON 描述截图内容、标记（圈/箭头等）及其大致 bbox；
+ * - user：保留原始用户文字（如果有）+ 单一 image_url 块。
+ *
+ * 其他模型（包括 glm-4.7、Gemini 等）不受影响。
+ */
+export function applyGlmVisionPromptTransform(payload) {
+    const root = structuredClone(payload);
+    const modelRaw = root.model;
+    const model = typeof modelRaw === 'string' ? modelRaw.trim() : '';
+    if (!model.startsWith('glm-4.6v')) {
+        return root;
+    }
+    const messagesValue = root.messages;
+    if (!Array.isArray(messagesValue)) {
+        return root;
+    }
+    const messages = messagesValue.filter((msg) => isRecord(msg));
+    if (!messages.length) {
+        return root;
+    }
+    // 从末尾开始查找最近一条带图片的 user 消息。
+    let latestUserWithImage = null;
+    let imageUrl = null;
+    for (let i = messages.length - 1; i >= 0; i -= 1) {
+        const msg = messages[i];
+        const role = typeof msg.role === 'string' ? msg.role.toLowerCase() : '';
+        if (role !== 'user') {
+            continue;
+        }
+        const content = msg.content;
+        if (!Array.isArray(content)) {
+            continue;
+        }
+        for (const part of content) {
+            if (!isRecord(part))
+                continue;
+            const typeValue = typeof part.type === 'string' ? part.type.toLowerCase() : '';
+            if (typeValue === 'image' || typeValue === 'image_url' || typeValue === 'input_image') {
+                const candidateUrl = extractImageUrlFromPart(part);
+                if (candidateUrl) {
+                    latestUserWithImage = msg;
+                    imageUrl = candidateUrl;
+                    break;
+                }
+            }
+        }
+        if (latestUserWithImage && imageUrl) {
+            break;
+        }
+    }
+    if (!latestUserWithImage || !imageUrl) {
+        return root;
+    }
+    const systemContent = '你是 Codex 的截图理解子系统，专门用于分析 UI 截图和网页图片。请仅根据用户提供的图片，输出一个结构化的 JSON，用于后续自动化处理，不要输出额外解释性文字或自然语言说明。\n' +
+        '\n' +
+        '输出必须是**单个合法 JSON 对象**，不要包含 Markdown、代码块标记或多余文本。请严格遵循下面的结构（字段可以为空数组，但必须存在）：\n' +
+        '{\n' +
+        '  "summary": "用 1-3 句整体描述这张图片（例如页面类型、主要区域、核心信息）",\n' +
+        '  "marks": [\n' +
+        '    {\n' +
+        '      "type": "circle | arrow | underline | box | other",\n' +
+        '      "color": "red | green | blue | yellow | other",\n' +
+        '      "bbox": [x, y, width, height],\n' +
+        '      "description": "该标记所圈出/指向/强调的内容，包含相关文字或 UI 元素描述"\n' +
+        '    }\n' +
+        '  ],\n' +
+        '  "regions": [\n' +
+        '    {\n' +
+        '      "bbox": [x, y, width, height],\n' +
+        '      "description": "该区域的可见内容（控件/图标/布局，以及其中出现的所有清晰可辨的文字）",\n' +
+        '      "is_marked": true | false\n' +
+        '    }\n' +
+        '  ],\n' +
+        '  "metadata": {\n' +
+        '    "image_size_hint": "如果能推断出大致分辨率，请给出类似 1920x1080 的字符串；无法判断时用 null",\n' +
+        '    "screenshot": true\n' +
+        '  }\n' +
+        '}\n' +
+        '\n' +
+        '细则：\n' +
+        '1. 文字提取要求：\n' +
+        '   - 如果图片中存在清晰可辨的文字（包括标题、菜单、按钮、标签、提示信息、弹窗、错误信息等），必须在对应的 regions.description 中**完整抄写**这些文字，按自然阅读顺序组织，避免遗漏。\n' +
+        '   - 如果有多行文字，可以用换行符分隔，但仍放在同一个 description 字段中。\n' +
+        '   - 对确实无法看清的文字，用类似 "（模糊，无法辨认）" 标注即可；没有任何文字也视为正常情况，此时只需描述界面结构。\n' +
+        '2. 标记识别（marks）：\n' +
+        '   - 对所有明显的圈选、箭头、下划线、高亮框等标记，必须在 marks 中列出，每一项提供大致 bbox、颜色和简短说明，说明其强调或指向的内容。\n' +
+        '3. 区域划分（regions）：\n' +
+        '   - 将截图拆分为若干有意义的区域：如导航栏、侧边栏、主内容区、弹窗、对话框、表格、代码块、表单等。\n' +
+        '   - 每个区域的 description 中，既要描述布局/控件类型，也要包含该区域内的全部清晰文字内容。\n' +
+        '   - is_marked 为 true 表示该区域与某个标记（marks）相关或被标记强调。\n' +
+        '4. 坐标规范：所有 bbox 使用相对于当前图片的像素坐标，左上角为 (0,0)，width/height 为正数近似值。\n' +
+        '5. 无论图片内容如何，最终回答必须是合法 JSON，不能在 JSON 前后添加任何额外文本。';
+    const systemMessage = {
+        role: 'system',
+        content: systemContent
+    };
+    const originalUserText = collectUserTextFromMessage(latestUserWithImage);
+    const userBlocks = [];
+    if (originalUserText && originalUserText.trim().length) {
+        userBlocks.push({
+            type: 'text',
+            text: originalUserText.trim()
+        });
+    }
+    else {
+        userBlocks.push({
+            type: 'text',
+            text: '请按照上面的 JSON 结构，详细描述这张图片的内容和标记。'
+        });
+    }
+    userBlocks.push({
+        type: 'image_url',
+        image_url: {
+            url: imageUrl
+        }
+    });
+    const userMessage = {
+        role: 'user',
+        content: userBlocks
+    };
+    // 丢弃原有 messages，仅保留新的 system + user。
+    root.messages = [systemMessage, userMessage];
+    // 对于专用视觉模型，限制 max_tokens，避免过大的 completion 预算进一步触发上下文相关错误。
+    const maxTokensValue = root.max_tokens;
+    if (typeof maxTokensValue === 'number' && Number.isFinite(maxTokensValue)) {
+        // 将超大值收敛到一个相对安全的上限；真实上限由上游再校验。
+        root.max_tokens = Math.min(maxTokensValue, 4096);
+    }
+    return root;
+}

package/dist/conversion/compat/actions/glm-web-search.js

@@ -1,4 +1,5 @@
 const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const DEBUG_GLM_WEB_SEARCH = (process.env.ROUTECODEX_DEBUG_GLM_WEB_SEARCH || '').trim() === '1';
 export function applyGlmWebSearchRequestTransform(payload) {
     const root = structuredClone(payload);
     const webSearchRaw = root.web_search;
@@ -23,19 +24,13 @@ export function applyGlmWebSearchRequestTransform(payload) {
         delete root.web_search;
         return root;
     }
-    const toolsValue = root.tools;
-    const tools = Array.isArray(toolsValue) ? [...toolsValue] : [];
-    let existingIndex = -1;
-    for (let i = 0; i < tools.length; i += 1) {
-        const tool = tools[i];
-        if (isRecord(tool) && typeof tool.type === 'string' && tool.type === 'web_search') {
-            existingIndex = i;
-            break;
-        }
-    }
     const webSearchConfig = {
+        // 按 GLM 文档要求：search_engine 为必填，默认使用 search_std。
+        search_engine: 'search_std',
         enable: true,
-        search_query: query
+        search_query: query,
+        // 返回搜索结果详情，便于我们在响应中提取摘要或调试。
+        search_result: true
     };
     if (recency) {
         webSearchConfig.search_recency_filter = recency;
@@ -43,24 +38,26 @@ export function applyGlmWebSearchRequestTransform(payload) {
     if (typeof count === 'number') {
         webSearchConfig.count = count;
     }
-    const baseTool = existingIndex >= 0 && isRecord(tools[existingIndex])
-        ? { ...tools[existingIndex] }
-        : {};
-    baseTool.type = 'web_search';
-    const existingWebSearch = isRecord(baseTool.web_search)
-        ? baseTool.web_search
-        : {};
-    baseTool.web_search = {
-        ...existingWebSearch,
-        ...webSearchConfig
+    // 根据 OpenAPI：tools.anyOf[*] = WebSearchToolSchema[]，即一次只能选择一种工具类型。
+    // 在 web_search 路由下，我们只保留 WebSearchToolSchema，丢弃其它 function/retrieval/MCP 工具，
+    // 避免混用导致后端忽略 web_search 配置。
+    const baseTool = {
+        type: 'web_search',
+        web_search: webSearchConfig
     };
-    if (existingIndex >= 0) {
-        tools[existingIndex] = baseTool;
-    }
-    else {
-        tools.push(baseTool);
-    }
-    root.tools = tools;
+    root.tools = [baseTool];
     delete root.web_search;
+    if (DEBUG_GLM_WEB_SEARCH) {
+        try {
+            // eslint-disable-next-line no-console
+            console.log('\x1b[38;5;27m[compat][glm_web_search_request] applied web_search transform ' +
+                `search_engine=${String(baseTool?.web_search?.search_engine ?? 'search_std')} ` +
+                `query=${JSON.stringify(query).slice(0, 200)} ` +
+                `count=${String(count ?? '')}\x1b[0m`);
+        }
+        catch {
+            // logging best-effort
+        }
+    }
     return root;
 }

package/dist/conversion/compat/actions/universal-shape-filter.js

@@ -127,6 +127,17 @@ export class UniversalShapeFilter {
                 normalized.tool_call_id = msg.tool_call_id;
             }
         }
+        else if (Array.isArray(msg.content)) {
+            normalized.content = msg.content.map((part) => {
+                if (typeof part === 'string') {
+                    return part;
+                }
+                if (isRecord(part)) {
+                    return { ...part };
+                }
+                return part;
+            });
+        }
         else {
             normalized.content = (msg.content !== null && msg.content !== undefined) ? String(msg.content) : '';
         }

package/dist/conversion/compat/profiles/chat-gemini.json

@@ -0,0 +1,17 @@
+{
+  "id": "chat:gemini",
+  "protocol": "gemini-chat",
+  "request": {
+    "mappings": [
+      { "action": "snapshot", "phase": "compat-pre" },
+      {
+        "action": "gemini_web_search_request"
+      },
+      { "action": "snapshot", "phase": "compat-post" }
+    ]
+  },
+  "response": {
+    "mappings": []
+  }
+}
+