@huyooo/ai-chat-core 0.2.19 → 0.2.21

package/src/providers/types.ts

@@ -0,0 +1,272 @@
+/**
+ * Provider 统一类型定义
+ * 
+ * 核心设计原则：
+ * 1. Adapter 只负责 API 格式转换，不处理业务逻辑
+ * 2. Orchestrator 统一处理工具调用循环、消息历史、事件发射
+ * 3. 所有 Adapter 返回标准化的 StreamChunk
+ */
+
+import type { ChatMessage, Tool, ToolResult } from '../types';
+
+
+/** 简化的工具定义（供 Adapter 使用） */
+import type { JsonSchemaObject } from '../types';
+
+export interface SimpleToolDefinition {
+  name: string;
+  description: string;
+  parameters: JsonSchemaObject;
+}
+
+// ==================== 标准化流式响应 ====================
+
+/** 流式响应块类型 */
+export type StreamChunkType = 
+  | 'text'           // 文本内容
+  | 'thinking'       // 思考内容
+  | 'thinking_done'  // 思考完成
+  | 'tool_call'      // 工具调用请求
+  | 'search_result'  // 搜索结果
+  | 'done'           // 响应完成
+  | 'error';         // 错误
+
+/** 工具调用请求 */
+export interface ToolCallRequest {
+  id: string;
+  name: string;
+  arguments: string;
+  /** Gemini 模型需要的 thought_signature（用于工具调用循环） */
+  thought_signature?: string;
+}
+
+/** 搜索结果项 */
+export interface SearchResultItem {
+  title: string;
+  url: string;
+  snippet: string;
+}
+
+/** 流式响应块 - 所有 Adapter 必须返回此格式 */
+/** Token 使用统计 */
+export interface StreamTokenUsage {
+  promptTokens?: number;
+  completionTokens?: number;
+  totalTokens?: number;
+  reasoningTokens?: number;
+  cachedTokens?: number;
+}
+
+export interface StreamChunk {
+  type: StreamChunkType;
+  
+  // 文本内容 (type: 'text')
+  text?: string;
+  
+  // 思考内容 (type: 'thinking')
+  thinking?: string;
+  
+  // 工具调用 (type: 'tool_call')
+  toolCall?: ToolCallRequest;
+  
+  // 搜索结果 (type: 'search_result')
+  searchResults?: SearchResultItem[];
+  
+  // 完成信号 (type: 'done')
+  finishReason?: 'stop' | 'tool_calls' | 'length' | 'error';
+  /** Token 使用统计（done 事件携带） */
+  usage?: StreamTokenUsage;
+  
+  // 错误信息 (type: 'error')
+  error?: string;
+}
+
+// ==================== 标准化消息格式 ====================
+
+/** 标准化消息 - Orchestrator 内部使用 */
+export interface StandardMessage {
+  role: 'system' | 'user' | 'assistant' | 'tool';
+  content: string;
+  
+  // 图片（用户消息）
+  images?: string[];
+  
+  // 工具调用（assistant 消息）
+  toolCalls?: ToolCallRequest[];
+  
+  // 工具调用 ID（tool 消息）
+  toolCallId?: string;
+  
+  // 工具名称（tool 消息，Gemini 需要）
+  toolName?: string;
+}
+
+// ==================== Adapter 接口 ====================
+
+/** Adapter 配置 */
+export interface AdapterConfig {
+  apiKey: string;
+  apiUrl?: string;
+  /** Tavily API Key（用于统一 Web Search） */
+  tavilyApiKey?: string;
+}
+
+/** 单次调用选项 */
+export interface StreamOnceOptions {
+  /** 模型 ID */
+  model: string;
+  /** 是否启用思考 */
+  enableThinking?: boolean;
+  /** 是否启用搜索 */
+  enableSearch?: boolean;
+  /** 中断信号 */
+  signal: AbortSignal;
+}
+
+/**
+ * Provider Adapter 接口
+ * 
+ * 职责：
+ * - 将标准消息转换为 API 特定格式
+ * - 调用 API 并返回标准化的 StreamChunk
+ * - 不处理工具执行、消息历史维护
+ */
+export interface ProviderAdapter {
+  /** 适配器名称 */
+  readonly name: string;
+  
+  /** 支持的模型列表 */
+  readonly supportedModels: string[];
+  
+  /**
+   * 单次流式调用
+   * 
+   * @param messages 标准化消息列表
+   * @param tools 工具定义列表
+   * @param options 调用选项
+   * @returns 标准化的流式响应
+   */
+  streamOnce(
+    messages: StandardMessage[],
+    tools: SimpleToolDefinition[],
+    options: StreamOnceOptions
+  ): AsyncGenerator<StreamChunk>;
+  
+  /**
+   * 检查是否支持指定模型
+   */
+  supportsModel(model: string): boolean;
+}
+
+// ==================== Orchestrator 类型 ====================
+
+/** 
+ * 工具执行器
+ * 
+ * 返回值：
+ * - string: 简单结果，使用工具的静态 sideEffects
+ * - ToolResult: 带动态副作用的结果
+ */
+export interface ToolExecutionHooks {
+  /** 工具调用 ID（用于把输出归属到具体 tool_call 卡片） */
+  toolCallId: string;
+  /** 工具名称 */
+  toolName: string;
+  /** stdout 增量 */
+  onStdout?: (chunk: string) => void;
+  /** stderr 增量 */
+  onStderr?: (chunk: string) => void;
+}
+
+export type ToolExecutor = (
+  name: string,
+  args: Record<string, unknown>,
+  signal?: AbortSignal,
+  hooks?: ToolExecutionHooks
+) => Promise<string | ToolResult>;
+
+/** 自动运行配置 */
+export interface AutoRunConfig {
+  /** 
+   * 自动运行模式
+   * - 'run-everything': 运行所有内容（自动执行）
+   * - 'manual': 手动批准（每次执行前询问）
+   */
+  mode?: 'run-everything' | 'manual';
+}
+
+/** 工具批准回调函数 */
+export type ToolApprovalCallback = (toolCall: {
+  id: string;
+  name: string;
+  args: Record<string, unknown>;
+}) => Promise<boolean>;
+
+/** 获取自动运行配置回调 */
+export type GetAutoRunConfigCallback = () => Promise<AutoRunConfig | undefined>;
+
+/** Orchestrator 配置 */
+export interface OrchestratorConfig {
+  /** 最大迭代次数 */
+  maxIterations?: number;
+  /** 工具执行器 */
+  executeTool: ToolExecutor;
+  /** 
+   * 完整的工具列表（用于获取 sideEffects）
+   * key: 工具名称, value: 工具定义
+   */
+  tools?: Map<string, Tool>;
+  /** 自动运行配置（静态配置，优先使用 getAutoRunConfig） */
+  autoRunConfig?: AutoRunConfig;
+  /** 
+   * 动态获取自动运行配置回调
+   * 每次检查工具批准时调用，获取最新配置
+   */
+  getAutoRunConfig?: GetAutoRunConfigCallback;
+  /** 
+   * 工具批准回调（manual 模式使用）
+   * 返回 true 表示批准执行，false 表示跳过
+   */
+  onToolApprovalRequest?: ToolApprovalCallback;
+  /**
+   * 客户端工具名称集合（透传模式）
+   * 
+   * 这些工具不在服务端执行，而是：
+   * 1. 发送 tool_call_request 事件给客户端
+   * 2. 结束本轮对话
+   * 3. 客户端执行后，发新请求继续对话
+   */
+  clientToolNames?: Set<string>;
+}
+
+/** Orchestrator 上下文 */
+export interface OrchestratorContext {
+  /** 系统提示 */
+  systemPrompt: string;
+  /** 对话历史（会被修改） */
+  history: ChatMessage[];
+  /** 工具定义 */
+  tools: SimpleToolDefinition[];
+  /** 中断信号 */
+  signal: AbortSignal;
+  /** 图片列表 */
+  images?: string[];
+  /**
+   * 客户端工具名称集合（透传模式）
+   * 
+   * 这些工具不在服务端执行，而是发送 tool_call_request 事件给客户端
+   */
+  clientToolNames?: Set<string>;
+}
+
+/** Orchestrator 选项 */
+export interface OrchestratorOptions {
+  /** 模型 ID */
+  model: string;
+  /** 是否启用思考 */
+  enableThinking?: boolean;
+  /** 是否启用搜索 */
+  enableSearch?: boolean;
+  /** 自动运行配置 */
+  autoRunConfig?: AutoRunConfig;
+}

package/src/providers/unified-adapter.ts

@@ -0,0 +1,367 @@
+/**
+ * UnifiedAdapter - 统一适配器
+ * 
+ * 组合 Protocol + FamilyConfig，产出标准 StreamChunk
+ * 
+ * 设计原则：
+ * 1. Protocol 只负责 HTTP/SSE 通信，产出 RawEvent
+ * 2. UnifiedAdapter 根据 FamilyConfig 将 RawEvent 转换为 StreamChunk
+ * 3. 所有模型都使用同一个 UnifiedAdapter，行为差异由 FamilyConfig 决定
+ * 4. 实现 ProviderAdapter 接口，可与现有 Orchestrator 无缝集成
+ */
+
+import type {
+  Protocol,
+  ProtocolMessage,
+  ProtocolToolDefinition,
+  RawEvent,
+} from './protocols';
+import {
+  createArkProtocol,
+  createDeepSeekProtocol,
+  createQwenProtocol,
+  createGeminiProtocol,
+  createOpenAIProtocol,
+  createAnthropicProtocol,
+} from './protocols';
+import {
+  getModelFamily,
+  getModelProtocol,
+  getVisibleModels,
+  type ModelFamilyConfig,
+  type ProtocolId,
+} from './model-registry';
+import type { 
+  ProviderAdapter,
+  StreamChunk, 
+  ToolCallRequest, 
+  SearchResultItem,
+  StandardMessage,
+  SimpleToolDefinition,
+  StreamOnceOptions,
+} from './types';
+import { DebugLogger } from '../utils';
+
+const logger = DebugLogger.module('UnifiedAdapter');
+
+// ==================== 配置类型 ====================
+
+/**
+ * UnifiedAdapter 配置
+ */
+export interface UnifiedAdapterConfig {
+  /** ARK API Key（豆包/DeepSeek） */
+  arkApiKey?: string;
+  arkApiUrl?: string;
+  
+  /** Qwen API Key（通义千问） */
+  qwenApiKey?: string;
+  qwenApiUrl?: string;
+  
+  /** Gemini API Key */
+  geminiApiKey?: string;
+  geminiApiUrl?: string;
+  
+  /** OpenRouter API Key */
+  openrouterApiKey?: string;
+  openrouterApiUrl?: string;
+  
+  /** Vercel API Key（用于 Vercel AI Gateway 访问 Claude） */
+  vercelApiKey?: string;
+}
+
+/**
+ * 流式调用选项
+ */
+export interface StreamOptions {
+  /** 模型 ID */
+  model: string;
+  /** 是否启用 thinking */
+  enableThinking?: boolean;
+  /** 是否启用搜索 */
+  enableSearch?: boolean;
+  /** 中断信号 */
+  signal: AbortSignal;
+}
+
+// ==================== UnifiedAdapter ====================
+
+/**
+ * 统一适配器
+ * 
+ * 实现 ProviderAdapter 接口，根据模型自动选择 Protocol，并根据 FamilyConfig 转换事件
+ */
+export class UnifiedAdapter implements ProviderAdapter {
+  readonly name = 'unified';
+  
+  /** 支持的模型列表（从 Registry 获取） */
+  get supportedModels(): string[] {
+    return getVisibleModels().map(m => m.id);
+  }
+  
+  private protocols: Map<ProtocolId, Protocol> = new Map();
+  
+  constructor(config: UnifiedAdapterConfig) {
+    // 初始化各 Protocol
+    if (config.arkApiKey) {
+      // 豆包（ARK 原生）
+      this.protocols.set('ark', createArkProtocol({
+        apiKey: config.arkApiKey,
+        apiUrl: config.arkApiUrl,
+      }));
+      // DeepSeek（通过 ARK，但独立 Protocol）
+      this.protocols.set('deepseek', createDeepSeekProtocol({
+        apiKey: config.arkApiKey,
+        apiUrl: config.arkApiUrl,
+      }));
+    }
+    
+    if (config.qwenApiKey) {
+      this.protocols.set('qwen', createQwenProtocol({
+        apiKey: config.qwenApiKey,
+        apiUrl: config.qwenApiUrl,
+      }));
+    }
+    
+    if (config.geminiApiKey) {
+      this.protocols.set('gemini', createGeminiProtocol({
+        apiKey: config.geminiApiKey,
+        apiUrl: config.geminiApiUrl,
+      }));
+    }
+    
+    // OpenAI 通过 OpenRouter 访问
+    if (config.openrouterApiKey) {
+      this.protocols.set('openai', createOpenAIProtocol({
+        apiKey: config.openrouterApiKey,
+        apiUrl: config.openrouterApiUrl,
+      }));
+    }
+    
+    // Anthropic 使用 Vercel AI SDK
+    if (config.vercelApiKey) {
+      this.protocols.set('anthropic', createAnthropicProtocol({
+        apiKey: config.vercelApiKey,
+      }));
+    }
+  }
+  
+  /**
+   * 检查是否支持指定模型
+   */
+  supportsModel(model: string): boolean {
+    const protocol = getModelProtocol(model);
+    return protocol ? this.protocols.has(protocol) : false;
+  }
+  
+  /**
+   * 获取模型的家族配置
+   */
+  getModelFamilyConfig(model: string): ModelFamilyConfig | undefined {
+    return getModelFamily(model);
+  }
+  
+  /**
+   * 实现 ProviderAdapter.streamOnce 接口
+   * 
+   * @param messages 标准消息列表
+   * @param tools 工具定义
+   * @param options 调用选项
+   * @returns 标准 StreamChunk 流
+   */
+  async *streamOnce(
+    messages: StandardMessage[],
+    tools: SimpleToolDefinition[],
+    options: StreamOnceOptions
+  ): AsyncGenerator<StreamChunk> {
+    const { model, enableThinking = false, enableSearch = false, signal } = options;
+    
+    // 转换消息格式（StandardMessage → ProtocolMessage）
+    const protocolMessages: ProtocolMessage[] = messages.map(m => ({
+      role: m.role,
+      content: m.content,
+      images: m.images,
+      toolCalls: m.toolCalls?.map(tc => ({
+        id: tc.id,
+        name: tc.name,
+        arguments: tc.arguments,
+        thoughtSignature: tc.thought_signature,
+      })),
+      toolCallId: m.toolCallId,
+      toolName: m.toolName,
+    }));
+    
+    // 转换工具格式（SimpleToolDefinition → ProtocolToolDefinition）
+    const protocolTools: ProtocolToolDefinition[] = tools;
+    
+    yield* this.stream(protocolMessages, protocolTools, {
+      model,
+      enableThinking,
+      enableSearch,
+      signal,
+    });
+  }
+  
+  /**
+   * 流式调用（内部方法）
+   */
+  private async *stream(
+    messages: ProtocolMessage[],
+    tools: ProtocolToolDefinition[],
+    options: StreamOptions
+  ): AsyncGenerator<StreamChunk> {
+    const { model, enableThinking = false, enableSearch = false, signal } = options;
+    
+    // 获取模型配置
+    const protocolId = getModelProtocol(model);
+    const familyConfig = getModelFamily(model);
+    
+    if (!protocolId) {
+      yield { type: 'error', error: `未知模型: ${model}` };
+      return;
+    }
+    
+    if (!familyConfig) {
+      yield { type: 'error', error: `模型 ${model} 缺少家族配置` };
+      return;
+    }
+    
+    const protocol = this.protocols.get(protocolId);
+    if (!protocol) {
+      yield { type: 'error', error: `Protocol ${protocolId} 未配置` };
+      return;
+    }
+    
+    logger.debug('开始流式调用', {
+      model,
+      protocol: protocolId,
+      family: familyConfig.id,
+      enableThinking,
+      enableSearch,
+    });
+    
+    // 调用 Protocol 获取原始事件流
+    const rawStream = protocol.stream(messages, tools, {
+      model,
+      familyConfig,
+      enableThinking,
+      enableSearch,
+      signal,
+    });
+    
+    // 转换为标准 StreamChunk
+    yield* this.transformEvents(rawStream, familyConfig, enableThinking, enableSearch);
+  }
+  
+  /**
+   * 将 RawEvent 转换为 StreamChunk
+   * 
+   * 根据 FamilyConfig 处理行为差异
+   */
+  private async *transformEvents(
+    rawStream: AsyncGenerator<RawEvent>,
+    familyConfig: ModelFamilyConfig,
+    enableThinking: boolean,
+    enableSearch: boolean
+  ): AsyncGenerator<StreamChunk> {
+    // 状态跟踪
+    let thinkingBuffer = '';
+    let thinkingStarted = false;
+    
+    for await (const event of rawStream) {
+      switch (event.type) {
+        // ========== Thinking 处理 ==========
+        case 'thinking_delta':
+          // 只有启用 thinking 且家族支持时才输出
+          if (enableThinking && familyConfig.supportsThinking && event.delta) {
+            // 去除开头的换行
+            let delta = event.delta;
+            if (!thinkingStarted) {
+              delta = delta.replace(/^\n+/, '');
+              if (delta) thinkingStarted = true;
+            }
+            if (delta) {
+              thinkingBuffer += delta;
+              yield { type: 'thinking', thinking: delta };
+            }
+          }
+          break;
+          
+        case 'thinking_done':
+          if (enableThinking && familyConfig.supportsThinking) {
+            yield { type: 'thinking_done' };
+          }
+          break;
+          
+        // ========== 文本处理 ==========
+        case 'text_delta':
+          if (event.delta) {
+            yield { type: 'text', text: event.delta };
+          }
+          break;
+          
+        // ========== 工具调用处理 ==========
+        case 'tool_call_done':
+          if (event.toolCall) {
+            const toolCall: ToolCallRequest = {
+              id: event.toolCall.id || '',
+              name: event.toolCall.name || '',
+              arguments: event.toolCall.arguments || '{}',
+            };
+            // 保留 Gemini 的 thoughtSignature
+            if (event.toolCall.thoughtSignature) {
+              toolCall.thought_signature = event.toolCall.thoughtSignature;
+            }
+            yield { type: 'tool_call', toolCall };
+          }
+          break;
+          
+        // ========== 搜索结果处理 ==========
+        case 'search_result':
+          if (enableSearch && event.searchResults) {
+            const searchResults: SearchResultItem[] = event.searchResults.map(r => ({
+              title: r.title,
+              url: r.url,
+              snippet: r.snippet,
+            }));
+            yield { type: 'search_result', searchResults };
+          }
+          break;
+          
+        // ========== 完成处理 ==========
+        case 'done':
+          // usage 数据由 protocol 层透传
+          yield {
+            type: 'done',
+            finishReason: event.finishReason || 'stop',
+            // 透传 Token 使用统计
+            usage: event.usage ? {
+              promptTokens: event.usage.promptTokens,
+              completionTokens: event.usage.completionTokens,
+              totalTokens: event.usage.totalTokens,
+              reasoningTokens: event.usage.reasoningTokens,
+              cachedTokens: event.usage.cachedTokens,
+            } : undefined,
+          };
+          break;
+          
+        // ========== 错误处理 ==========
+        case 'error':
+          yield { type: 'error', error: event.error || '未知错误' };
+          break;
+          
+        // 忽略其他事件（如 tool_call_start, tool_call_delta）
+        default:
+          break;
+      }
+    }
+  }
+}
+
+/**
+ * 创建 UnifiedAdapter
+ */
+export function createUnifiedAdapter(config: UnifiedAdapterConfig): UnifiedAdapter {
+  return new UnifiedAdapter(config);
+}
+

package/src/router.ts

@@ -0,0 +1,72 @@
+/**
+ * 模型路由模块
+ * 
+ * 根据模型 ID 查询对应的 Protocol 和 Family 配置
+ */
+
+import { 
+  getModelEntry, 
+  getModelFamily,
+  type ProtocolId, 
+  type ModelFamilyConfig,
+  type ModelRegistryEntry,
+} from './providers/model-registry';
+
+/** Provider 类型 = Protocol 类型 */
+export type ProviderType = ProtocolId;
+
+/** 路由结果 */
+export interface RouteResult {
+  /** Protocol 类型 */
+  provider: ProviderType;
+  /** 是否未注册（使用默认 Provider） */
+  isDefault: boolean;
+  /** 模型注册信息 */
+  registryEntry?: ModelRegistryEntry;
+  /** 模型家族配置 */
+  familyConfig?: ModelFamilyConfig;
+}
+
+/** 默认 Provider（未注册模型的兜底） */
+const DEFAULT_PROVIDER: ProviderType = 'ark';
+
+/**
+ * 获取模型的 Provider
+ */
+export function routeModelToProvider(model: string): ProviderType {
+  return routeModelWithDetails(model).provider;
+}
+
+/**
+ * 获取模型的完整路由信息
+ */
+export function routeModelWithDetails(model: string): RouteResult {
+  const registryEntry = getModelEntry(model);
+  if (registryEntry) {
+    return {
+      provider: registryEntry.protocol,
+      registryEntry,
+      familyConfig: getModelFamily(model),
+      isDefault: false,
+    };
+  }
+  
+  return {
+    provider: DEFAULT_PROVIDER,
+    isDefault: true
+  };
+}
+
+/**
+ * 获取默认 Provider
+ */
+export function getDefaultProvider(): ProviderType {
+  return DEFAULT_PROVIDER;
+}
+
+/**
+ * 检查模型是否属于指定 Provider
+ */
+export function isModelForProvider(model: string, provider: ProviderType): boolean {
+  return routeModelToProvider(model) === provider;
+}