metona-ai-desktop/electron/harness/adapters/openai.adapter.ts

/**
 * OpenAI Provider Adapter（P3）
 *
 * OpenAI Chat Completions API（/v1/chat/completions），支持 Tool Calling、
 * 流式输出、多模态图片、o 系列推理模型的 reasoning_effort 参数。
 *
 * v0.6.4 P3-1: 继承 OpenAICompatibleAdapter —— 传输/组装/回退链收敛到共享基类，
 * 本文件只保留 OpenAI 差异点：o 系列/gpt-5 的字段名路由与 reasoning_effort、
 * 推理模型拒图的前置拦截（升级为 ModelCapabilityError）、动态 /models 列表、
 * 非推理模型 temperature 控制。
 *
 * @see https://platform.openai.com/docs/api-reference/chat
 */

import log from 'electron-log';
import type { MetonaRequest } from '../types';
import type { MetonaModelInfo } from '../types/metona-adapter';
import { buildOpenAICompatibleMessages, buildOpenAICompatibleTools } from './shared/openai-format';
import { ModelCapabilityError, OpenAICompatibleAdapter } from './shared/openai-compatible-base';

export class OpenAIAdapter extends OpenAICompatibleAdapter {
  override readonly providerId: string = 'openai';
  readonly supportedModels = ['gpt-4o', 'gpt-4o-mini', 'gpt-4.1', 'o3-mini'];
  readonly supportsToolCalling = true;
  readonly supportsThinking = true;

  private static readonly MODEL_INFO: Record<string, MetonaModelInfo> = {
    'gpt-4o': {
      id: 'gpt-4o',
      name: 'GPT-4o',
      contextWindow: 128_000,
      maxOutputTokens: 16_384,
      supportsToolCalling: true,
      supportsThinking: false,
      description: 'OpenAI 旗舰多模态模型，128K 上下文',
    },
    'gpt-4o-mini': {
      id: 'gpt-4o-mini',
      name: 'GPT-4o mini',
      contextWindow: 128_000,
      maxOutputTokens: 16_384,
      supportsToolCalling: true,
      supportsThinking: false,
      description: 'OpenAI 高性价比模型，128K 上下文',
    },
    'gpt-4.1': {
      id: 'gpt-4.1',
      name: 'GPT-4.1',
      contextWindow: 1_000_000,
      maxOutputTokens: 32_768,
      supportsToolCalling: true,
      supportsThinking: false,
      description: 'OpenAI 长上下文模型，1M 上下文',
    },
    'o3-mini': {
      id: 'o3-mini',
      name: 'o3-mini',
      contextWindow: 200_000,
      maxOutputTokens: 100_000,
      supportsToolCalling: true,
      supportsThinking: true,
      description: 'OpenAI 推理模型，支持 reasoning_effort',
    },
  };

  // ===== 共享基类差异声明 =====

  protected override chatCompletionsUrl(): string {
    return `${this.config.baseURL}/chat/completions`;
  }

  protected override sendTimeoutMs(): number {
    return 120_000;
  }

  protected override modelInfoTable(): Record<string, MetonaModelInfo> {
    return OpenAIAdapter.MODEL_INFO;
  }

  protected override providerLabel(): string {
    return 'OpenAI';
  }

  // v0.6.4: OpenAI 家族兜底窗口为 128K（其余 OpenAI 兼容 Provider 为 1M）
  protected override defaultContextWindowFallback(): number {
    return 128_000;
  }

  // ===== GET /v1/models =====

  override async listModels(): Promise<MetonaModelInfo[]> {
    try {
      const response = await fetch(`${this.config.baseURL}/models`, {
        headers: { Authorization: `Bearer ${this.config.apiKey}` },
        signal: AbortSignal.timeout(10_000),
      });
      if (response.ok) {
        const data = (await response.json()) as { data?: Array<{ id: string }> };
        if (data.data?.length) {
          return data.data.map((m) => OpenAIAdapter.MODEL_INFO[m.id] ?? { id: m.id });
        }
      }
    } catch {
      // API 不可用时降级
    }
    return this.supportedModels.map((id) => OpenAIAdapter.MODEL_INFO[id] ?? { id });
  }

  // ========== 协议参数映射（OpenAI 差异点） ==========

  protected override toNativeRequest(
    request: MetonaRequest,
    stream: boolean,
  ): Record<string, unknown> {
    // 推理模型检测（o 系列使用新参数名）
    const model = this.config.defaultModel;
    const isReasoningModel = /^(o\d|gpt-5)/.test(model);

    // 推理模型不支持图片输入 — 前置校验
    // v0.6.4 升级: 原实现抛裸 Error 落入 UNKNOWN 错误码；现在抛 ModelCapabilityError
    // （携带 status=400），引擎按"不可重试请求级错误"处理，UI 可区分能力限制与一般故障。
    if (isReasoningModel) {
      const hasImages = request.messages.some((m) => m.images?.length);
      if (hasImages) {
        throw new ModelCapabilityError(model, 'image inputs');
      }
    }

    // v0.6.2: images 处理收敛至共享层（原索引对齐循环在孤立 tool 过滤后会错位）
    const messages = buildOpenAICompatibleMessages(request, true);
    const tools = buildOpenAICompatibleTools(request.tools);

    const body: Record<string, unknown> = {
      model,
      messages,
      stream,
    };

    // Token 上限参数：o 系列/gpt-5 使用 max_completion_tokens
    // v0.5.3: 按模型上限钳制（gpt-4o 16384 / gpt-4.1 32768 / o3-mini 100000）—
    // 引擎默认 63488 超过 gpt-4o/gpt-4.1 上限时 API 直接 400
    const oaMaxOutput = OpenAIAdapter.MODEL_INFO[model]?.maxOutputTokens ?? 128_000;
    const oaMaxTokens = Math.min(
      request.params.maxTokens ?? (isReasoningModel ? 32_768 : oaMaxOutput),
      oaMaxOutput,
    );
    if (oaMaxTokens) {
      if (isReasoningModel) {
        body.max_completion_tokens = oaMaxTokens;
      } else {
        body.max_tokens = oaMaxTokens;
      }
    }

    if (stream) {
      body.stream_options = { include_usage: true };
    }

    if (tools) {
      body.tools = tools;
    }

    // Thinking 模式：推理模型映射 reasoning_effort；非推理模型忽略
    if (request.params.thinkingEnabled && isReasoningModel) {
      const effortMap: Record<string, string> = {
        low: 'low',
        medium: 'medium',
        high: 'high',
        max: 'high',
      };
      body.reasoning_effort = effortMap[request.params.thinkingEffort ?? 'high'] ?? 'high';
      // v0.8.0 P0-3: 推理 token 计入 max_completion_tokens —— 钳制后预算过小时告警
      if (oaMaxTokens < 8192) {
        log.warn(
          `[OpenAI] reasoning enabled with small output budget (${oaMaxTokens} tokens after model clamp) — reasoning may consume the entire budget and truncate the answer`,
        );
      }
    } else if (!isReasoningModel) {
      // 非推理模型使用温度控制
      body.temperature = request.params.temperature;
    }

    // 停止序列
    // 已知边界（协议限制，待上游放开后移除此注释）：o 系列不支持 stop 参数，
    // 当前仍透传 —— 若推理模型 + stop 组合触发 400 属上游约束而非本层缺陷。
    if (request.params.stopSequences?.length) {
      body.stop = request.params.stopSequences;
    }

    return body;
  }
}