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

/**
 * DeepSeek Provider Adapter
 *
 * 基于 OpenAI 兼容 API。支持 Tool Calling、Thinking 模式、流式输出。
 * 模型: deepseek-v4-flash / deepseek-v4-pro（1M 上下文，384K 最大输出）
 *
 * 独立继承 BaseAdapter，通过 shared/openai-format 和 shared/sse-stream 复用
 * OpenAI 兼容格式构建和 SSE 流式解析逻辑。不与其他 Provider Adapter 耦合。
 *
 * @see apis/deepseek-api-docs-20260518.html
 */

import log from 'electron-log';
import { BaseAdapter } from './base-adapter';
import type { MetonaRequest, MetonaResponse, MetonaStreamEvent } from '../types';
import { MetonaFinishReason } from '../types';
import type { MetonaModelInfo } from '../types/metona-adapter';
import { buildOpenAICompatibleMessages, buildOpenAICompatibleTools } from './shared/openai-format';
import { parseSSEStream, parseOpenAICompatibleResponse } from './shared/sse-stream';

export class DeepSeekAdapter extends BaseAdapter {
  // H-2 修复: provider → providerId（规范要求）
  override readonly providerId: string = 'deepseek';
  readonly supportedModels = [
    'deepseek-v4-pro',
    'deepseek-v4-flash',
    'deepseek-v4-flash-vision-exp',
  ];
  readonly supportsToolCalling = true;
  readonly supportsThinking = true;

  // H-2 修复: DeepSeek 模型元信息（1M 上下文，384K 最大输出）
  private static readonly MODEL_INFO: Record<string, MetonaModelInfo> = {
    'deepseek-v4-pro': {
      id: 'deepseek-v4-pro',
      name: 'DeepSeek V4 Pro',
      contextWindow: 1_000_000,
      maxOutputTokens: 384_000,
      supportsToolCalling: true,
      supportsThinking: true,
      description: 'DeepSeek 旗舰模型，1M 上下文，支持深度推理与工具调用',
    },
    'deepseek-v4-flash': {
      id: 'deepseek-v4-flash',
      name: 'DeepSeek V4 Flash',
      contextWindow: 1_000_000,
      maxOutputTokens: 384_000,
      supportsToolCalling: true,
      supportsThinking: true,
      description: 'DeepSeek 快速版，1M 上下文，低延迟推理',
    },
    // v0.5.4: DeepSeek 多模态实验模型（OpenAI image_url content parts 格式）
    'deepseek-v4-flash-vision-exp': {
      id: 'deepseek-v4-flash-vision-exp',
      name: 'DeepSeek V4 Flash Vision (Exp)',
      contextWindow: 128_000,
      maxOutputTokens: 8_192,
      supportsToolCalling: true,
      supportsThinking: false,
      description: 'DeepSeek 多模态实验模型，支持图片输入（image_url content parts）',
    },
  };

  /**
   * v0.5.4: 当前模型是否支持多模态图片输入
   *
   * DeepSeek 仅 vision 系列模型支持图片（命名含 'vision'）；
   * 非 vision 模型收到 images 时静默丢弃（避免 API 400）。
   * 前端上传入口由 llm.multimodalEnabled 配置总开关控制，此处是 adapter 侧的模型级防线。
   */
  private isVisionModel(): boolean {
    return this.config.defaultModel.includes('vision');
  }

  // ===== POST /chat/completions (非流式) =====

  // H-2 修复: chat → send（规范要求）
  async send(request: MetonaRequest): Promise<MetonaResponse> {
    const body = this.toNativeRequest(request, false);

    // #24 修复: 使用 fetchWithTimeout 替代 getFetchSignal + fetch，确保 timer 清理
    const response = await this.fetchWithTimeout(
      `${this.config.baseURL}/chat/completions`,
      {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          Authorization: `Bearer ${this.config.apiKey}`,
          ...this.config.headers,
        },
        body: JSON.stringify(body),
      },
      this.config.timeoutMs ?? 120_000,
    );

    if (!response.ok) {
      await this.throwHttpError(response, 'DeepSeek API error');
    }

    const data = (await response.json()) as Record<string, unknown>;
    const parsed = parseOpenAICompatibleResponse(data);

    return {
      meta: {
        requestId: request.meta.requestId,
        provider: this.providerId,
        model: (data.model as string) ?? this.config.defaultModel,
        latencyMs: 0,
        timestamp: Date.now(),
      },
      content: parsed.content,
      reasoningContent: parsed.reasoningContent,
      toolCalls: parsed.toolCalls,
      usage: parsed.usage,
      finishReason: parsed.finishReason as MetonaFinishReason,
    };
  }

  // ===== POST /chat/completions (流式) =====

  // H-2 修复: chatStream → sendStream（规范要求）
  async *sendStream(request: MetonaRequest): AsyncIterable<MetonaStreamEvent> {
    const body = this.toNativeRequest(request, true);

    // #24 修复: 使用 fetchWithTimeout 替代 getFetchSignal + fetch，确保 timer 清理
    const response = await this.fetchWithTimeout(
      `${this.config.baseURL}/chat/completions`,
      {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          Authorization: `Bearer ${this.config.apiKey}`,
          ...this.config.headers,
        },
        body: JSON.stringify(body),
      },
      this.config.timeoutMs ?? 300_000,
    );

    if (!response.ok || !response.body) {
      await this.throwHttpError(response, 'DeepSeek stream error');
    }

    yield* parseSSEStream(
      // 非空断言：上方 if 已确保 response.body 不为 null
      // TypeScript 无法通过 await Promise<never> 正确收窄，需显式断言
      response.body!,
      request.meta.requestId,
      request.meta.sessionId,
      request.meta.iteration,
    );
  }

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

  /**
   * H-2 修复: 返回 MetonaModelInfo[]（规范要求）
   *
   * 优先尝试从 API 获取实时模型列表，并合并本地 MODEL_INFO 元数据。
   * API 不可用时回退到 supportedModels。
   */
  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) {
          // 合并 API 返回的模型 ID 与本地元数据
          return data.data.map((m) => DeepSeekAdapter.MODEL_INFO[m.id] ?? { id: m.id });
        }
      }
    } catch {
      // API 不可用时降级
    }
    // 回退到 supportedModels（带本地元数据）
    return this.supportedModels.map((id) => DeepSeekAdapter.MODEL_INFO[id] ?? { id });
  }

  /**
   * H-2 修复: 获取上下文窗口大小（规范要求）
   *
   * v0.3.1: 优先使用配置注入的 contextWindow，回退到 MODEL_INFO 默认值。
   * DeepSeek OpenAI 兼容 API 不支持 context_window 参数，此值仅用于
   * Engine 压缩判断和前端 UI 显示。
   */
  override getContextWindow(): number {
    // v0.3.1: 优先使用配置注入的 contextWindow
    if (typeof this.config.contextWindow === 'number' && this.config.contextWindow > 0) {
      return this.config.contextWindow;
    }
    // 回退到 MODEL_INFO
    const modelInfo = DeepSeekAdapter.MODEL_INFO[this.config.defaultModel];
    return modelInfo?.contextWindow ?? 1_000_000;
  }

  // ===== GET /user/balance =====

  /**
   * 查询账户余额
   *
   * v0.5.2 修复: DeepSeek 官方 API 实际返回 `balance_infos` 数组格式：
   *   { "is_available": true, "balance_infos": [{ "currency": "CNY",
   *     "total_balance": "110.00", "granted_balance": "10.00", "topped_up_balance": "100.00" }] }
   * 此前按扁平字段解析（data.total_balance）→ 永远取到 undefined → 恒显示 0。
   * 现优先取 balance_infos[0]，回退扁平格式（兼容网关/代理的简化响应）。
   *
   * URL 规范化: 余额端点为 {root}/user/balance（无 /v1 前缀）。用户配置的
   * baseURL 可能带 /v1 或尾斜杠（chat 端点两种写法都合法），此处剥离后拼接。
   */
  async getBalance(): Promise<{
    currency: string;
    totalBalance: string;
    grantedBalance: string;
    toppedUpBalance: string;
  } | null> {
    try {
      // 规范化 baseURL：去尾斜杠、去尾 /v1（余额端点在根路径下）
      const root = this.config.baseURL.replace(/\/+$/, '').replace(/\/v1$/, '');
      const response = await fetch(`${root}/user/balance`, {
        headers: { Authorization: `Bearer ${this.config.apiKey}` },
        signal: AbortSignal.timeout(10_000),
      });
      if (!response.ok) return null;
      const data = (await response.json()) as {
        is_available?: boolean;
        balance_infos?: Array<{
          currency?: string;
          total_balance?: string;
          granted_balance?: string;
          topped_up_balance?: string;
        }>;
        // 扁平格式字段（网关/代理兼容）
        currency?: string;
        total_balance?: string;
        granted_balance?: string;
        topped_up_balance?: string;
      };
      // 优先官方 balance_infos 数组，回退扁平格式
      const info = data.balance_infos?.[0] ?? data;
      return {
        currency: info.currency ?? 'CNY',
        totalBalance: info.total_balance ?? '0',
        grantedBalance: info.granted_balance ?? '0',
        toppedUpBalance: info.topped_up_balance ?? '0',
      };
    } catch {
      return null;
    }
  }

  // ========== 私有方法 ==========

  /**
   * 构建 DeepSeek 原生请求体
   *
   * DeepSeek 特有参数：
   * - thinking: { type: "enabled" } — 启用思考模式
   * - reasoning_effort — 思考强度映射
   * - stream_options: { include_usage: true } — 流式返回 usage
   */
  private toNativeRequest(request: MetonaRequest, stream: boolean): Record<string, unknown> {
    // v0.6.2: images 处理收敛至共享层（includeImages = vision 模型才转换，
    // 非 vision 静默丢弃——正确行为，见 openai-format.ts #27 记录）
    const messages = buildOpenAICompatibleMessages(request, this.isVisionModel());
    const tools = buildOpenAICompatibleTools(request.tools);

    // v0.5.3: max_tokens 按模型上限钳制 — 引擎默认 63488 超过部分模型上限时 API 直接 400
    const modelInfo = DeepSeekAdapter.MODEL_INFO[this.config.defaultModel];
    const maxOutput = modelInfo?.maxOutputTokens ?? 384_000;
    const maxTokens = Math.min(request.params.maxTokens ?? maxOutput, maxOutput);

    const body: Record<string, unknown> = {
      model: this.config.defaultModel,
      messages,
      temperature: request.params.temperature,
      max_tokens: maxTokens,
      stream,
    };

    // v0.5.4: vision 模型图片数审计（转换在共享层完成）
    if (this.isVisionModel()) {
      const imageCount = request.messages.reduce((n, m) => n + (m.images?.length ?? 0), 0);
      if (imageCount > 0) {
        log.info(`[DeepSeek] Vision model processing ${imageCount} image(s)`);
      }
    }

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

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

    // Thinking 模式
    // API 默认 thinking.type = "enabled"，必须显式发送 disabled 才能关闭
    if (request.params.thinkingEnabled === false) {
      body.thinking = { type: 'disabled' };
    } else if (request.params.thinkingEnabled) {
      body.thinking = { type: 'enabled' };
      const effortMap: Record<string, string> = {
        low: 'high',
        medium: 'high',
        high: 'high',
        max: 'max',
      };
      // DeepSeek API 仅支持 high / max 两档，low/medium 映射为 high
      body.reasoning_effort = effortMap[request.params.thinkingEffort ?? 'high'] ?? 'high';
    }

    // 停止序列
    if (request.params.stopSequences?.length) {
      body.stop = request.params.stopSequences;
    }

    return body;
  }
}