@huyooo/ai-chat-core 0.2.19 → 0.2.21

package/src/agent.ts

@@ -0,0 +1,399 @@
+/**
+ * HybridAgent - 混合 AI Agent
+ * 
+ * 新架构（Protocol + Family 分离）：
+ * - UnifiedAdapter: 统一适配器，组合 Protocol + FamilyConfig
+ * - ChatOrchestrator: 统一处理工具调用循环、消息历史、事件发射
+ * - HybridAgent: 协调者，负责初始化和路由
+ * 
+ * 设计优势：
+ * 1. Protocol 只负责 HTTP/SSE 通信
+ * 2. FamilyConfig 统一管理行为差异
+ * 3. 新增模型只需在 Registry 配置，无需修改代码
+ */
+
+import { GoogleGenAI } from '@google/genai';
+import type {
+  AgentConfig,
+  ToolExecutor,
+  ChatOptions,
+  ThinkingMode,
+  Tool,
+  ToolContext,
+  ToolResult,
+  ToolConfigItem,
+} from './types';
+import { resolveTools, MODELS } from './types';
+import type { ChatEvent } from './events';
+import { createApiError } from './events';
+import { createDefaultToolExecutor } from './tools';
+import { DEFAULT_ARK_URL, DEFAULT_QWEN_URL, DEFAULT_OPENROUTER_URL, DEFAULT_MODEL, AGENT_MODE_PROMPT } from './constants';
+import { routeModelToProvider, routeModelWithDetails, type ProviderType, type RouteResult } from './router';
+import { getModelFamily, modelSupportsNativeSearch, type ModelFamilyConfig } from './providers/model-registry';
+import { McpClientManager } from './mcp/client-manager';
+import type { McpServerConfig } from './mcp/types';
+
+// 新架构导入
+import type { OrchestratorContext, SimpleToolDefinition, ToolExecutionHooks } from './providers/types';
+import { ChatOrchestrator } from './providers/orchestrator';
+import { UnifiedAdapter } from './providers/unified-adapter';
+import { createWebSearchTool, WEB_SEARCH_TOOL_NAME } from './internal/web-search';
+
+/** 运行时配置（API Keys 和 URLs） */
+export interface RuntimeConfig {
+  arkApiKey: string;
+  arkApiUrl: string;
+  qwenApiKey: string;
+  qwenApiUrl: string;
+  openrouterApiKey: string;
+  openrouterApiUrl: string;
+  vercelApiKey: string;
+  tavilyApiKey: string;
+  geminiApiKey: string;
+  cwd: string;
+}
+
+/**
+ * 混合 Agent 类
+ * 
+ * 职责：
+ * 1. 管理 UnifiedAdapter（统一适配器）
+ * 2. 使用 ChatOrchestrator 统一处理工具调用
+ * 3. 管理工具注册
+ */
+export class HybridAgent {
+  private config: RuntimeConfig;
+  private adapter: UnifiedAdapter;
+  private orchestrator: ChatOrchestrator;
+  private geminiClient: GoogleGenAI;
+  private toolExecutor: ToolExecutor;
+  private abortController: AbortController | null = null;
+
+  /** 已注册的工具 */
+  private tools: Map<string, Tool> = new Map();
+
+  /** 工具配置（用于异步初始化） */
+  private toolConfig: ToolConfigItem[] | undefined;
+
+  /** MCP 客户端管理器 */
+  private mcpManager: McpClientManager | null = null;
+  /** MCP 服务器配置 */
+  private mcpConfigs: McpServerConfig[] | undefined;
+
+  constructor(config: AgentConfig, toolExecutor?: ToolExecutor) {
+    this.config = {
+      arkApiKey: config.arkApiKey,
+      arkApiUrl: config.arkApiUrl || DEFAULT_ARK_URL,
+      qwenApiKey: config.qwenApiKey || '',
+      qwenApiUrl: config.qwenApiUrl || DEFAULT_QWEN_URL,
+      openrouterApiKey: config.openrouterApiKey || '',
+      openrouterApiUrl: config.openrouterApiUrl || DEFAULT_OPENROUTER_URL,
+      vercelApiKey: config.vercelApiKey || '',
+      tavilyApiKey: config.tavilyApiKey || '',
+      geminiApiKey: config.geminiApiKey,
+      cwd: config.cwd || process.cwd(),
+    };
+
+    this.geminiClient = new GoogleGenAI({ apiKey: this.config.geminiApiKey });
+    this.toolExecutor = toolExecutor || createDefaultToolExecutor(this.config.cwd);
+
+    // 保存工具配置（用于异步初始化）
+    this.toolConfig = config.tools;
+    this.mcpConfigs = config.mcpServers;
+    this.tools = new Map();
+
+    // 初始化 UnifiedAdapter（统一适配器）
+    this.adapter = new UnifiedAdapter({
+      arkApiKey: this.config.arkApiKey,
+      arkApiUrl: this.config.arkApiUrl,
+      qwenApiKey: this.config.qwenApiKey,
+      qwenApiUrl: this.config.qwenApiUrl,
+      geminiApiKey: this.config.geminiApiKey,
+      openrouterApiKey: this.config.openrouterApiKey,
+      openrouterApiUrl: this.config.openrouterApiUrl,
+      vercelApiKey: this.config.vercelApiKey,
+    });
+
+    // 初始化 Orchestrator（不传 maxIterations，使用 Orchestrator 默认值 25）
+    this.orchestrator = new ChatOrchestrator({
+      executeTool: this.executeTool.bind(this),
+      tools: this.tools,
+      onToolApprovalRequest: config.onToolApprovalRequest,
+      getAutoRunConfig: config.getAutoRunConfig,
+    });
+  }
+
+  /** 异步初始化工具（在第一次 chat 前调用） */
+  private async asyncInit(): Promise<void> {
+    if (this.toolConfig && this.tools.size === 0) {
+      const resolvedTools = await resolveTools(this.toolConfig);
+      for (const tool of resolvedTools) {
+        this.tools.set(tool.name, tool);
+      }
+    }
+
+    // 内置 Web Search（Tavily）：仅在配置了 tavilyApiKey 且未被用户覆盖时注册
+    if (this.config.tavilyApiKey && !this.tools.has(WEB_SEARCH_TOOL_NAME)) {
+      this.tools.set(WEB_SEARCH_TOOL_NAME, createWebSearchTool(this.config.tavilyApiKey));
+    }
+
+    // MCP 工具：连接所有配置的 MCP Server，发现并注册工具
+    if (this.mcpConfigs?.length && !this.mcpManager) {
+      this.mcpManager = new McpClientManager();
+      await this.mcpManager.connectAll(this.mcpConfigs);
+
+      // 注册 MCP 发现的工具（不覆盖已有同名工具）
+      for (const tool of this.mcpManager.getAllTools()) {
+        if (!this.tools.has(tool.name)) {
+          this.tools.set(tool.name, tool);
+        }
+      }
+    }
+  }
+
+  /** 获取模型的家族配置 */
+  getModelFamilyConfig(model: string): ModelFamilyConfig | undefined {
+    return getModelFamily(model);
+  }
+
+  /** 
+   * 判断模型提供商（兼容旧接口）
+   */
+  private getModelProvider(model: string): ProviderType {
+    return routeModelToProvider(model);
+  }
+
+  /**
+   * 调试：获取模型路由信息
+   */
+  getModelRouteInfo(model: string): RouteResult & { available: boolean; familyConfig?: ModelFamilyConfig } {
+    const result = routeModelWithDetails(model);
+    return {
+      ...result,
+      available: this.adapter.supportsModel(model),
+      familyConfig: getModelFamily(model),
+    };
+  }
+
+  /** 构建系统提示词 */
+  private buildSystemPrompt(options: ChatOptions): string {
+    const model = options.model || DEFAULT_MODEL;
+    const familyConfig = getModelFamily(model);
+
+    // Agent 和 Ask 模式使用默认提示词
+    let prompt = AGENT_MODE_PROMPT;
+
+    // Skills 注入：用户启用的 Skills 内容拼接到 system prompt
+    if (options.skillContents?.length) {
+      prompt += '\n\n【用户指令】\n' + options.skillContents.join('\n\n');
+    }
+
+    // Web Search（工具方式）：仅对"不支持原生搜索"的模型提示使用 web_search_ai
+    if (options.enableWebSearch && familyConfig && !modelSupportsNativeSearch(model)) {
+      prompt += `\n\n【联网搜索】当用户问题需要实时信息/最新事实/可引用来源时，请先调用 ${WEB_SEARCH_TOOL_NAME} 工具获取结果，然后基于返回的 title/url/snippet 作答，并在回答中给出来源链接。`;
+    }
+
+    return prompt;
+  }
+
+  /** 获取默认深度思考模式 */
+  private getDefaultThinkingMode(): ThinkingMode {
+    return 'disabled';
+  }
+
+  /** 创建工具执行上下文 */
+  private createToolContext(signal?: AbortSignal, hooks?: ToolExecutionHooks): ToolContext {
+    return {
+      cwd: this.config.cwd,
+      geminiClient: this.geminiClient,
+      executeCommand: (command: string, cwd?: string) =>
+        this.toolExecutor.executeCommand(command, cwd || this.config.cwd, signal, {
+          onStdout: hooks?.onStdout,
+          onStderr: hooks?.onStderr,
+        }),
+      signal,
+    };
+  }
+
+  /** 执行工具 */
+  private async executeTool(
+    name: string,
+    args: Record<string, unknown>,
+    signal?: AbortSignal,
+    hooks?: ToolExecutionHooks
+  ): Promise<string | ToolResult> {
+    const tool = this.tools.get(name);
+    if (!tool) {
+      return `未知工具: ${name}`;
+    }
+    return await tool.execute(args, this.createToolContext(signal, hooks));
+  }
+
+  /** 获取工具定义列表 */
+  private getToolDefinitions(enabledTools?: string[], forceInclude?: string[]): SimpleToolDefinition[] {
+    const allTools = Array.from(this.tools.values());
+    let selected = enabledTools !== undefined
+      ? allTools.filter(t => enabledTools.includes(t.name))
+      : allTools;
+
+    // 强制包含指定工具（用于 enableWebSearch 这类"功能开关"）
+    if (forceInclude?.length) {
+      for (const name of forceInclude) {
+        if (!selected.some(t => t.name === name)) {
+          const t = this.tools.get(name);
+          if (t) selected = [...selected, t];
+        }
+      }
+    }
+
+    return selected.map(tool => ({
+      name: tool.name,
+      description: tool.description,
+      parameters: tool.parameters
+    }));
+  }
+
+  /** 获取所有工具列表（用于设置面板） */
+  public getAllTools(): Array<{ name: string; description: string }> {
+    return Array.from(this.tools.values()).map(tool => ({
+      name: tool.name,
+      description: tool.description
+    }));
+  }
+
+  /**
+   * 聊天入口
+   * 
+   * 使用 ChatOrchestrator 统一处理所有 Provider 的工具调用循环
+   */
+  async *chat(
+    message: string,
+    options: ChatOptions = {},
+    images?: string[]
+  ): AsyncGenerator<ChatEvent> {
+    // 异步初始化工具（如果还没初始化）
+    await this.asyncInit();
+
+    this.abortController = new AbortController();
+    const signal = this.abortController.signal;
+
+    const model = options.model || DEFAULT_MODEL;
+
+    // 检查模型是否支持
+    if (!this.adapter.supportsModel(model)) {
+      const familyConfig = getModelFamily(model);
+      if (!familyConfig) {
+        yield createApiError(`未知模型: ${model}`, { code: 'MODEL_NOT_SUPPORTED' });
+      } else {
+        yield createApiError(`模型 ${model} 缺少 API Key 配置`, { code: 'MISSING_API_KEY' });
+      }
+      return;
+    }
+
+    // 获取模型家族配置
+    const familyConfig = getModelFamily(model);
+
+    // 统一 thinkingMode
+    const rawThinkingMode = options.thinkingMode ?? this.getDefaultThinkingMode();
+    const thinkingMode: ThinkingMode = rawThinkingMode === 'enabled' ? 'enabled' : 'disabled';
+    const systemPrompt = this.buildSystemPrompt(options);
+
+    // ask 模式：强制"纯文本回答"
+    const isAskMode = options.mode === 'ask';
+    const enableSearch = !isAskMode && !!options.enableWebSearch;
+
+    // 对于不支持原生搜索的模型，需要强制包含联网搜索工具
+    const forceInclude = enableSearch && familyConfig && !modelSupportsNativeSearch(model)
+      ? [WEB_SEARCH_TOOL_NAME]
+      : undefined;
+
+    // 云端工具定义
+    const cloudTools = isAskMode ? [] : this.getToolDefinitions(options.enabledTools, forceInclude);
+
+    // 用户自定义工具（透传模式）
+    const userTools = options.userTools || [];
+    const userToolDefinitions = userTools.map(t => ({
+      name: t.name,
+      description: t.description,
+      parameters: {
+        ...t.parameters,
+        required: t.parameters.required || [],
+      },
+    }));
+
+    // 合并所有工具
+    const tools = [...cloudTools, ...userToolDefinitions];
+
+    // 客户端工具名称集合
+    const clientToolNames = userTools.length > 0
+      ? new Set(userTools.map(t => t.name))
+      : undefined;
+
+    // 只有家族支持 thinking 且用户启用时才真正启用
+    const enableThinking = !isAskMode && thinkingMode === 'enabled' && (familyConfig?.supportsThinking ?? false);
+
+    // 使用传入的历史
+    const history = options.history || [];
+
+    // 构建 Orchestrator 上下文
+    const context: OrchestratorContext = {
+      systemPrompt,
+      history,
+      tools,
+      signal,
+      images,
+      clientToolNames,
+    };
+
+    try {
+      // 使用 Orchestrator + UnifiedAdapter
+      yield* this.orchestrator.chat(this.adapter, message, context, {
+        model,
+        enableThinking,
+        enableSearch,
+        autoRunConfig: options.autoRunConfig,
+      });
+    } finally {
+      this.abortController = null;
+    }
+  }
+
+  /** 中断当前请求 */
+  abort(): void {
+    if (this.abortController) {
+      this.abortController.abort();
+    }
+  }
+
+  /** 设置当前工作目录 */
+  setCwd(dir: string): void {
+    this.config.cwd = dir;
+  }
+
+  /** 获取当前配置 */
+  getConfig(): RuntimeConfig {
+    return { ...this.config };
+  }
+
+  /** 获取所有支持的模型 */
+  getSupportedModels() {
+    return MODELS;
+  }
+
+  /** 获取 MCP 连接状态 */
+  getMcpConnections() {
+    return this.mcpManager?.getConnectionInfos() ?? [];
+  }
+
+  /**
+   * 销毁 Agent（优雅关闭所有 MCP 连接）
+   * 
+   * 桌面客户端退出时应调用此方法。
+   */
+  async destroy(): Promise<void> {
+    if (this.mcpManager) {
+      await this.mcpManager.disconnectAll();
+      this.mcpManager = null;
+    }
+  }
+}

package/src/constants.ts

@@ -0,0 +1,125 @@
+/**
+ * 常量定义
+ * 
+ * 所有模型配置统一在此管理
+ */
+
+// ==================== API URL ====================
+export const DEFAULT_ARK_URL = 'https://ark.cn-beijing.volces.com/api/v3';
+// Qwen 使用 OpenAI 兼容模式以支持工具调用
+export const DEFAULT_QWEN_URL = 'https://dashscope.aliyuncs.com/compatible-mode/v1';
+export const DEFAULT_OPENROUTER_URL = 'https://openrouter.ai/api/v1';
+
+// ==================== 模型配置类型 ====================
+interface ModelConfig {
+  id: string;
+  displayName: string;
+  isOpenRouter?: boolean;
+  /** 提供商名称（用于分组） */
+  provider?: string;
+  /** 模型描述 */
+  description?: string;
+}
+
+// ==================== 豆包模型 (ARK) ====================
+export const DOUBAO_SEED_1_8: ModelConfig = { 
+  id: 'doubao-seed-1-8-251215', 
+  displayName: '豆包 Seed 1.8',
+  provider: '豆包',
+};
+export const DOUBAO_SEED_1_6: ModelConfig = { 
+  id: 'doubao-seed-1-6-250615', 
+  displayName: '豆包 Seed 1.6',
+  provider: '豆包',
+};
+export const DOUBAO_SEED_1_6_LATEST: ModelConfig = { 
+  id: 'doubao-seed-1-6-251015', 
+  displayName: '豆包 Seed 1.6 Latest',
+  provider: '豆包',
+};
+export const DOUBAO_SEED_1_6_FLASH: ModelConfig = { 
+  id: 'doubao-seed-1-6-flash-250617', 
+  displayName: '豆包 Seed 1.6 Flash',
+  provider: '豆包',
+};
+
+// ==================== DeepSeek 模型 (ARK) ====================
+export const DEEPSEEK_V3: ModelConfig = { 
+  id: 'deepseek-v3-2-251201', 
+  displayName: 'DeepSeek V3.2',
+  // 展示层显式标注：该模型通过 ARK（火山/豆包平台）托管接入
+  provider: 'DeepSeek（ARK）',
+};
+
+// ==================== 通义千问模型 ====================
+export const QWEN_MAX: ModelConfig = { id: 'qwen-max', displayName: '通义千问 Max', provider: '通义千问' };
+export const QWEN_MAX_LATEST: ModelConfig = { id: 'qwen-max-latest', displayName: '通义千问 Max Latest', provider: '通义千问' };
+export const QWEN_PLUS: ModelConfig = { id: 'qwen-plus', displayName: '通义千问 Plus', provider: '通义千问' };
+export const QWEN_PLUS_LATEST: ModelConfig = { id: 'qwen-plus-latest', displayName: '通义千问 Plus Latest', provider: '通义千问' };
+export const QWEN_TURBO: ModelConfig = { id: 'qwen-turbo', displayName: '通义千问 Turbo', provider: '通义千问' };
+export const QWEN_TURBO_LATEST: ModelConfig = { id: 'qwen-turbo-latest', displayName: '通义千问 Turbo Latest', provider: '通义千问' };
+export const QWEN3_235B: ModelConfig = { id: 'qwen3-235b-a22b', displayName: 'Qwen3 235B', provider: '通义千问' };
+export const QWEN3_MAX_PREVIEW: ModelConfig = { 
+  id: 'qwen3-max-preview', 
+  displayName: '通义千问 3 Max',
+  provider: '通义千问',
+};
+
+// ==================== Gemini 模型 ====================
+export const GEMINI_2_5_FLASH: ModelConfig = { id: 'gemini-2.5-flash-preview-05-20', displayName: 'Gemini 2.5 Flash', provider: 'Gemini' };
+export const GEMINI_2_5_PRO: ModelConfig = { id: 'gemini-2.5-pro-preview-05-06', displayName: 'Gemini 2.5 Pro', provider: 'Gemini' };
+export const GEMINI_2_0_FLASH: ModelConfig = { id: 'gemini-2.0-flash', displayName: 'Gemini 2.0 Flash', provider: 'Gemini' };
+export const GEMINI_2_0_FLASH_LITE: ModelConfig = { id: 'gemini-2.0-flash-lite', displayName: 'Gemini 2.0 Flash Lite', provider: 'Gemini' };
+export const GEMINI_3_PRO: ModelConfig = { 
+  id: 'gemini-3-pro-preview', 
+  displayName: 'Gemini 3 Pro',
+  provider: 'Gemini',
+};
+// 图片模型（仅 id）
+export const GEMINI_IMAGE_MODEL = 'gemini-2.0-flash';
+export const GEMINI_IMAGE_GEN_MODEL = 'gemini-3-pro-image-preview';
+
+// ==================== OpenRouter 模型 ====================
+export const OR_GPT_5_1: ModelConfig = { 
+  id: 'openai/gpt-5.1-codex', 
+  displayName: 'GPT-5.1 Codex', 
+  isOpenRouter: true,
+  provider: 'OpenAI',
+};
+export const CLAUDE_OPUS_4_5: ModelConfig = { 
+  id: 'anthropic/claude-opus-4.5', 
+  displayName: 'Claude Opus 4.5', 
+  provider: 'Anthropic',
+};
+
+// ==================== 前端显示的模型列表 ====================
+export const DISPLAY_MODELS: ModelConfig[] = [
+  // 原生模型
+  DOUBAO_SEED_1_6,
+  DEEPSEEK_V3,
+  QWEN3_MAX_PREVIEW,
+  GEMINI_3_PRO,
+  // OpenRouter 模型
+  OR_GPT_5_1,
+  // Vercel AI SDK 模型
+  CLAUDE_OPUS_4_5,
+];
+
+// ==================== 默认配置 ====================
+export const DEFAULT_MODEL = DOUBAO_SEED_1_6.id;
+
+/** agent 模式提示词 */
+export const AGENT_MODE_PROMPT = `你是一个专业的 AI 助手，具备自主执行复杂任务的能力。
+
+## 工作方式
+1. **分析任务**：理解用户需求，拆解为可执行的步骤
+2. **逐步执行**：按步骤依次调用工具，检查每步结果
+3. **自我验证**：工具执行后检查结果是否符合预期
+4. **自动纠正**：发现问题时尝试替代方案，不要停下来问用户
+5. **总结汇报**：所有步骤完成后，给出简洁的结果总结
+
+## 输出规范
+- 不使用表情符号（emoji），除非用户要求
+- 使用 Markdown 格式组织内容
+- 代码块使用正确的语言标识`;
+