minimal-agent 0.8.2 → 0.10.0

package/src/llm/providers/anthropicFormat.js

@@ -0,0 +1,241 @@
+/**
+ * ============================================================
+ *  src/llm/providers/anthropicFormat.ts —— Anthropic Messages API 协议
+ * ------------------------------------------------------------
+ *  ⚠️ 未经真实端点验证：本机没有任何 Anthropic 兼容的 key/代理，这里的请求体形状
+ *  和 SSE 事件字段完全照 Anthropic 官方文档（Messages API，2023-06-01）实现，配了
+ *  手写的 SSE 录像单测，但没有做过一次真实 round-trip。拿到真实 key 后务必先跑一次
+ *  真实对话冒烟测试，见 test/llm.anthropicFormat.test.ts 头注。
+ *
+ *  与 openaiFormat.ts 的分工一致：这里只做「内部 Message[]/Tool[] ⇄ Anthropic 协议
+ *  形状」的翻译 + SSE 逐行解析；重试/退避/空闲看门狗等协议无关骨架留在 client.ts。
+ *
+ *  v1 明确不支持（写清楚，不装作支持）：
+ *   - output_schema 结构化输出（Anthropic 的强制工具输出模式跟 OpenAI 的
+ *     response_format.json_schema 形状不同）——client.ts 在请求前直接抛错。
+ *   - OpenAI 特有的「400 文本嗅探退化」（不支持 response_format/max_tokens 时自动
+ *     摘字段重发）无 Anthropic 对应逻辑；Anthropic 的 400 直接暴露。
+ *   - 视频输入（ChatContentPart 的 video_url）：Anthropic 无对应协议，退化成文本占位。
+ * ============================================================
+ */
+const ANTHROPIC_VERSION = '2023-06-01';
+function toAnthropicUserContent(content) {
+    if (typeof content === 'string')
+        return [{ type: 'text', text: content }];
+    return content.map((part) => {
+        if (part.type === 'text')
+            return { type: 'text', text: part.text };
+        if (part.type === 'image_url') {
+            const url = part.image_url.url;
+            if (url.startsWith('data:')) {
+                const match = /^data:([^;]+);base64,([\s\S]+)$/.exec(url);
+                if (match)
+                    return { type: 'image', source: { type: 'base64', media_type: match[1], data: match[2] } };
+            }
+            return { type: 'image', source: { type: 'url', url } };
+        }
+        // video_url：Anthropic 无对应协议，退化成文本占位（v1 范围限制）。
+        return { type: 'text', text: '[视频内容未发送：Anthropic 格式的 provider 暂不支持视频输入]' };
+    });
+}
+/**
+ * 内部 Message[]（OpenAI 形状：role 含 tool、assistant.tool_calls、tool.tool_call_id）
+ * → Anthropic 形状：{system, messages}。
+ *
+ * 关键翻译规则：
+ *  - 所有 system 角色内容拼成顶层 system 字符串，从 messages 数组里摘除。
+ *  - tool 角色 → {role:'user', content:[{type:'tool_result', tool_use_id, content}]}。
+ *  - assistant 的 tool_calls[i] → {type:'tool_use', id, name, input}（arguments 是内部的
+ *    JSON 字符串，Anthropic 的 input 要解析后的对象；parse 失败兜底空对象）。
+ *  - **必须合并连续同角色消息**：Anthropic 强制 user/assistant 严格交替，1:1 硬映射会因
+ *    「assistant 调工具 → tool 结果(→user) → 下一条也是 user 的正常对话」之类的连续同角色
+ *    序列而 400。
+ */
+export function toAnthropicMessages(messages) {
+    const systemParts = [];
+    const pieces = [];
+    for (const m of messages) {
+        if (m.role === 'system') {
+            systemParts.push(m.content);
+            continue;
+        }
+        if (m.role === 'user') {
+            pieces.push({ role: 'user', content: toAnthropicUserContent(m.content) });
+            continue;
+        }
+        if (m.role === 'assistant') {
+            const content = [];
+            if (m.content)
+                content.push({ type: 'text', text: m.content });
+            for (const call of m.tool_calls ?? []) {
+                let input = {};
+                try {
+                    input = JSON.parse(call.function.arguments || '{}');
+                }
+                catch {
+                    input = {};
+                }
+                content.push({ type: 'tool_use', id: call.id, name: call.function.name, input });
+            }
+            // 退化 assistant 消息（content 为 null/空字符串且没有 tool_calls——如模型只吐了
+            // reasoning 就被中断）整条跳过，而不是塞一个空文本块：Anthropic 拒绝空 text block
+            // （"text content blocks must be non-empty"），塞了会让下一轮请求直接 400。
+            if (content.length > 0)
+                pieces.push({ role: 'assistant', content });
+            continue;
+        }
+        // role === 'tool'
+        pieces.push({ role: 'user', content: [{ type: 'tool_result', tool_use_id: m.tool_call_id, content: m.content }] });
+    }
+    const merged = [];
+    for (const piece of pieces) {
+        const last = merged[merged.length - 1];
+        if (last && last.role === piece.role)
+            last.content.push(...piece.content);
+        else
+            merged.push({ role: piece.role, content: [...piece.content] });
+    }
+    return { system: systemParts.join('\n\n'), messages: merged };
+}
+function toAnthropicTools(tools) {
+    return tools.map((t) => ({
+        name: t.name,
+        description: typeof t.description === 'function' ? t.description() : t.description,
+        input_schema: t.parameters,
+    }));
+}
+function looksLikeVersionedBase(url) {
+    try {
+        const u = new URL(url);
+        const path = u.pathname.replace(/\/+$/, '');
+        if (path === '' || path === '/')
+            return true;
+        const segments = path.split('/');
+        const last = segments[segments.length - 1];
+        return /^v\d+/.test(last);
+    }
+    catch {
+        return false;
+    }
+}
+export function buildAnthropicUrl(provider) {
+    // baseURL 是完整端点 URL（以 /v1/messages 结尾）。
+    // 向后兼容：旧格式 baseURL（根域名或版本化基础路径）自动补全 /v1/messages 后缀。
+    const url = provider.baseURL.trim().replace(/\/+$/, '');
+    if (url.endsWith('/chat/completions') || url.endsWith('/v1/messages'))
+        return url;
+    if (url.length === 0)
+        return url;
+    if (looksLikeVersionedBase(url)) {
+        console.warn(`[minimal-agent] 旧格式 baseURL 检测："${provider.baseURL}" 未包含端点后缀，` +
+            `已自动补全为 "${url}/v1/messages"。请在设置页更新为完整端点地址。`);
+        return `${url}/v1/messages`;
+    }
+    return url;
+}
+export function buildAnthropicRequest(args) {
+    const { provider, cleanedMessages, tools } = args;
+    const { system, messages } = toAnthropicMessages(cleanedMessages);
+    const anthropicTools = toAnthropicTools(tools);
+    const body = {
+        model: provider.model,
+        ...(system ? { system } : {}),
+        messages,
+        // Anthropic 的 max_tokens 是必填字段；解析层（configService.ts::resolveProvider）已保证
+        // provider.maxTokens 一定有值（defaultMaxTokens() 兜底），这里直接透传不做协商退化——
+        // OpenAI 那套「不支持就摘掉重发」的 400 文本嗅探对 Anthropic 无对应逻辑，见文件头注。
+        max_tokens: provider.maxTokens,
+        stream: true,
+    };
+    // tools: [] 会被部分 provider 拒绝或产生意外行为——空数组直接不发这个字段。
+    if (anthropicTools.length > 0)
+        body.tools = anthropicTools;
+    return {
+        url: buildAnthropicUrl(provider),
+        headers: {
+            'content-type': 'application/json',
+            'x-api-key': provider.apiKey,
+            'anthropic-version': ANTHROPIC_VERSION,
+        },
+        body: JSON.stringify(body),
+    };
+}
+/**
+ * 每个请求一个新实例；把逐条 SSE `data:` 行的内容转换成 LlmStreamEvent（0..N 个）。
+ *
+ * Anthropic 的 SSE 每帧是 `event: <type>` + `data: <json>` 两行，但 data 的 JSON payload
+ * 自身也带 `type` 字段（与 event 行的值相同）——client.ts 的共享读取骨架只识别 `data:`
+ * 开头的行（继承自 OpenAI 分支的既有约定），所以这里直接从 JSON payload 的 `.type` 分支，
+ * 不需要读 `event:` 行，共享骨架的行拆分逻辑不用为 Anthropic 特殊改动。
+ */
+export function createAnthropicSSEParser() {
+    let stopReason = 'unknown';
+    let usagePromptTokens;
+    return {
+        buildFallbackDone() {
+            return { type: 'done', stopReason, promptTokens: usagePromptTokens };
+        },
+        handleData(dataStr) {
+            let data;
+            try {
+                data = JSON.parse(dataStr);
+            }
+            catch {
+                return [];
+            }
+            switch (data.type) {
+                case 'message_start': {
+                    const inputTokens = data.message?.usage?.input_tokens;
+                    if (typeof inputTokens === 'number')
+                        usagePromptTokens = inputTokens;
+                    return [];
+                }
+                case 'content_block_start': {
+                    // tool_use 块的 id/name 在 start 事件里一次性给出（不像 OpenAI 分片在 delta 里），
+                    // 这里补发一条只带 id/name、不带 argumentsDelta 的 tool_call_delta 把它们「种」进
+                    // loop.ts::mergeToolCallDelta 的累积槽；后续同 index 的 input_json_delta 只带参数增量。
+                    const block = data.content_block;
+                    if (block?.type === 'tool_use') {
+                        return [{ type: 'tool_call_delta', index: data.index, id: block.id, name: block.name }];
+                    }
+                    return [];
+                }
+                case 'content_block_delta': {
+                    const delta = data.delta;
+                    if (delta?.type === 'text_delta')
+                        return [{ type: 'text_delta', delta: delta.text }];
+                    if (delta?.type === 'input_json_delta') {
+                        return [{ type: 'tool_call_delta', index: data.index, argumentsDelta: delta.partial_json }];
+                    }
+                    if (delta?.type === 'thinking_delta') {
+                        return [{ type: 'reasoning_delta', field: 'reasoning', delta: delta.thinking }];
+                    }
+                    // signature_delta（扩展思维签名）等其它 delta 类型：v1 不处理，安全忽略。
+                    return [];
+                }
+                case 'message_delta': {
+                    // ⚠️ stop_reason 嵌套在 delta.stop_reason 下，不是 message_delta 顶层。
+                    const sr = data.delta?.stop_reason;
+                    if (sr === 'end_turn' || sr === 'stop_sequence')
+                        stopReason = 'stop';
+                    else if (sr === 'tool_use')
+                        stopReason = 'tool_calls';
+                    else if (sr === 'max_tokens')
+                        stopReason = 'length';
+                    else if (sr)
+                        stopReason = 'unknown';
+                    return [];
+                }
+                case 'message_stop':
+                    return [{ type: 'done', stopReason, promptTokens: usagePromptTokens }];
+                case 'error':
+                    // 中途错误事件（如 overloaded_error/529）：不能静默结束流，必须让调用方看到失败——
+                    // 抛出后由 client.ts 共享读取循环的 try/finally 传播给上层（与其它流中断失败同一路径）。
+                    throw new Error(`Anthropic 流式响应报错：${JSON.stringify(data.error ?? data)}`);
+                default:
+                    // 含 ping、content_block_stop 及未来可能新增的事件类型——已知安全的 no-op，不抛错。
+                    return [];
+            }
+        },
+    };
+}

package/src/llm/providers/openaiFormat.js

@@ -0,0 +1,190 @@
+/**
+ * ============================================================
+ *  src/llm/providers/openaiFormat.ts —— OpenAI Chat Completions 协议
+ * ------------------------------------------------------------
+ *  从 client.ts 拆出来的格式相关部分：请求体构造 + SSE chunk → LlmStreamEvent。
+ *  重试/退避/空闲看门狗等协议无关的骨架留在 client.ts，两个格式模块共用。
+ * ============================================================
+ */
+/**
+ * 判断一个 400 是否在抱怨 response_format（json_schema）不被支持。
+ * 各 provider 文案不一（火山 GLM：`json_schema is not supported by this model`），
+ * 故宽松匹配："提到 response_format" 且 "出现 not support / unsupported / not valid / invalid"。
+ */
+export function isResponseFormatUnsupported(status, errText) {
+    if (status !== 400)
+        return false;
+    const t = errText.toLowerCase();
+    if (!t.includes('response_format'))
+        return false;
+    return (t.includes('not support') ||
+        t.includes('unsupported') ||
+        t.includes('not valid') ||
+        t.includes('invalid'));
+}
+/**
+ * 判断一个 400 是否在抱怨 max_tokens（不支持 / 超模型上限 / 取值非法）。
+ * 文案各家不一，故宽松匹配："提到 max_tokens" 且 "出现 not support / invalid /
+ * exceed / too large / out of range / maximum"。命中后去掉 max_tokens 重发即可。
+ */
+export function isMaxTokensRejected(status, errText) {
+    if (status !== 400)
+        return false;
+    const t = errText.toLowerCase();
+    if (!t.includes('max_tokens') && !t.includes('max tokens'))
+        return false;
+    return (t.includes('not support') ||
+        t.includes('unsupported') ||
+        t.includes('not valid') ||
+        t.includes('invalid') ||
+        t.includes('exceed') ||
+        t.includes('too large') ||
+        t.includes('out of range') ||
+        t.includes('maximum'));
+}
+/**
+ * 判断一个 4xx 是否在抱怨图片/image_url/多模态输入不被支持。
+ * 匹配关键词：image_url、image、vision、multimodal + not support/unsupported/invalid 等。
+ */
+export function isImageInputRejected(status, errText) {
+    if (status !== 400 && status !== 404)
+        return false;
+    const t = errText.toLowerCase();
+    const hasImageKw = t.includes('image_url') || t.includes('image') || t.includes('vision') || t.includes('multimodal') || t.includes('不支持图片') || t.includes('图片输入');
+    if (!hasImageKw)
+        return false;
+    return (t.includes('not support') ||
+        t.includes('unsupported') ||
+        t.includes('not valid') ||
+        t.includes('invalid') ||
+        t.includes('not allowed') ||
+        t.includes('does not support') ||
+        t.includes('不支持'));
+}
+function looksLikeVersionedBase(url) {
+    try {
+        const u = new URL(url);
+        const path = u.pathname.replace(/\/+$/, '');
+        if (path === '' || path === '/')
+            return true;
+        const segments = path.split('/');
+        const last = segments[segments.length - 1];
+        return /^v\d+/.test(last);
+    }
+    catch {
+        return false;
+    }
+}
+export function buildOpenAIUrl(provider) {
+    // baseURL 是完整端点 URL（以 /chat/completions 结尾）。
+    // 向后兼容：旧格式 baseURL（版本化基础路径，如 /v1）自动补全后缀，并打 warning。
+    const url = provider.baseURL.trim().replace(/\/+$/, '');
+    if (url.endsWith('/chat/completions') || url.endsWith('/v1/messages'))
+        return url;
+    if (url.length === 0)
+        return url;
+    if (looksLikeVersionedBase(url)) {
+        console.warn(`[minimal-agent] 旧格式 baseURL 检测："${provider.baseURL}" 未包含端点后缀，` +
+            `已自动补全为 "${url}/chat/completions"。请在设置页更新为完整端点地址。`);
+        return `${url}/chat/completions`;
+    }
+    return url;
+}
+export function buildOpenAIRequest(args) {
+    const { provider, cleanedMessages, tools, withResponseFormat, withMaxTokens, includeUsage, responseFormat } = args;
+    const openaiTools = tools.map((t) => ({
+        type: 'function',
+        function: {
+            name: t.name,
+            description: typeof t.description === 'function' ? t.description() : t.description,
+            parameters: t.parameters,
+        },
+    }));
+    return {
+        url: buildOpenAIUrl(provider),
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${provider.apiKey}`,
+        },
+        body: JSON.stringify({
+            model: provider.model,
+            messages: cleanedMessages,
+            tools: openaiTools.length > 0 ? openaiTools : undefined,
+            stream: true,
+            // 显式输出上限：兜住默认上限偏小的 provider（豆包默认 4096）。缺省 undefined 不出现在 body。
+            max_tokens: withMaxTokens ? provider.maxTokens : undefined,
+            // stream_options.include_usage：让 provider 在流末附带真实 prompt_tokens，
+            // 供上层自动压缩判断用；provider 不支持时 usagePromptTokens 保持 undefined，上层 fallback 本地估算。
+            ...(includeUsage ? { stream_options: { include_usage: true } } : {}),
+            // tool_choice: 'auto' 是默认值，可不写；某些 provider 必须显式
+            tool_choice: openaiTools.length > 0 ? 'auto' : undefined,
+            // ADR-05: structured output；缺省 undefined 不出现在 body（JSON.stringify 自动剥离）
+            response_format: withResponseFormat ? responseFormat : undefined,
+        }),
+    };
+}
+/** 每个请求一个新实例；把逐条 SSE `data:` 行的内容转换成 LlmStreamEvent（0..N 个）。 */
+export function createOpenAISSEParser() {
+    let stopReason = 'unknown';
+    let usagePromptTokens;
+    return {
+        buildFallbackDone() {
+            return { type: 'done', stopReason, promptTokens: usagePromptTokens };
+        },
+        handleData(dataStr) {
+            if (dataStr === '[DONE]')
+                return [{ type: 'done', stopReason, promptTokens: usagePromptTokens }];
+            let chunk;
+            try {
+                chunk = JSON.parse(dataStr);
+            }
+            catch {
+                // 罕见：某些 provider 会发空行或心跳，忽略
+                return [];
+            }
+            const events = [];
+            // usage chunk：include_usage 开启时，provider 通常在流末单独发一帧，
+            // 此帧 choices 为空（没有 delta），必须在 `if (!delta) return` 之前读取，
+            // 否则会被跳过，永远拿不到真实 prompt_tokens。
+            if (chunk.usage && typeof chunk.usage.prompt_tokens === 'number') {
+                usagePromptTokens = chunk.usage.prompt_tokens;
+            }
+            const delta = chunk.choices?.[0]?.delta;
+            const finish = chunk.choices?.[0]?.finish_reason;
+            if (finish) {
+                stopReason = finish === 'stop' || finish === 'tool_calls' || finish === 'length' ? finish : 'unknown';
+            }
+            if (!delta)
+                return events;
+            // 文本增量。注意：MiniMax 等模型默认会把 <think>...</think> 标签直接放在
+            // content 字段里——我们原样累积，不剥离，确保下一轮工具调用时思维链完整回传。
+            if (typeof delta.content === 'string' && delta.content.length > 0) {
+                events.push({ type: 'text_delta', delta: delta.content });
+            }
+            // tool_calls 增量（OpenAI 协议下 tool_calls 也是分片返回的）
+            if (Array.isArray(delta.tool_calls)) {
+                for (const tc of delta.tool_calls) {
+                    events.push({
+                        type: 'tool_call_delta',
+                        index: tc.index ?? 0,
+                        id: tc.id,
+                        name: tc.function?.name,
+                        argumentsDelta: tc.function?.arguments,
+                    });
+                }
+            }
+            // 思维链增量（DeepSeek-R1 / MiniMax reasoning_split / OpenRouter）
+            // 三种字段名都见过：reasoning_content / reasoning / reasoning_details
+            if (typeof delta.reasoning_content === 'string' && delta.reasoning_content.length > 0) {
+                events.push({ type: 'reasoning_delta', field: 'reasoning_content', delta: delta.reasoning_content });
+            }
+            if (typeof delta.reasoning === 'string' && delta.reasoning.length > 0) {
+                events.push({ type: 'reasoning_delta', field: 'reasoning', delta: delta.reasoning });
+            }
+            if (Array.isArray(delta.reasoning_details) && delta.reasoning_details.length > 0) {
+                events.push({ type: 'reasoning_delta', field: 'reasoning_details', items: delta.reasoning_details });
+            }
+            return events;
+        },
+    };
+}