@huyooo/ai-chat-core 0.2.19 → 0.2.21

package/src/index.ts

@@ -0,0 +1,309 @@
+/**
+ * @huyooo/ai-chat-core
+ * 
+ * AI Chat 核心包 - 纯 Agent 逻辑，无框架依赖
+ * 
+ * 新架构（Protocol + Family 分离）：
+ * - Model Registry: 模型注册表，管理所有模型配置
+ * - Protocol Layer: 只负责 HTTP/SSE 通信
+ * - Family Config: 统一管理模型行为差异
+ * - UnifiedAdapter: 组合 Protocol + Family
+ * - ChatOrchestrator: 统一处理工具调用循环
+ * 
+ * 设计优势：
+ * 1. Protocol 只负责 HTTP/SSE 通信
+ * 2. FamilyConfig 统一管理行为差异
+ * 3. 新增模型只需在 Registry 配置，无需修改代码
+ * 
+ * 支持模型：
+ * - ARK (豆包/DeepSeek) - 火山引擎
+ * - Qwen (通义千问) - DashScope
+ * - Gemini - Google AI
+ * - OpenRouter - Claude/GPT 等
+ */
+
+// ==================== Agent ====================
+
+export { HybridAgent, type RuntimeConfig } from './agent';
+
+// ==================== 模型注册表 ====================
+
+export {
+  // 家族配置
+  MODEL_FAMILIES,
+  DOUBAO_FAMILY,
+  DEEPSEEK_FAMILY,
+  QWEN_FAMILY,
+  GEMINI_FAMILY,
+  GPT_FAMILY,
+  CLAUDE_FAMILY,
+  
+  // 模型注册表
+  MODEL_REGISTRY,
+  
+  // 查询函数
+  getModelEntry,
+  getModelFamily,
+  getModelProtocol,
+  getVisibleModels,
+  getModelsByFamily,
+  getModelsByProtocol,
+  modelSupportsThinking,
+  modelSupportsNativeSearch,
+  getModelSearchStrategy,
+} from './providers/model-registry';
+
+export type {
+  ModelFamilyId,
+  ProtocolId,
+  ThinkingFormat,
+  SearchStrategy,
+  ToolCallFormat,
+  ModelFamilyConfig,
+  ModelRegistryEntry,
+} from './providers/model-registry';
+
+// ==================== 新架构：UnifiedAdapter + Protocol ====================
+
+// UnifiedAdapter - 统一适配器
+export { UnifiedAdapter, createUnifiedAdapter } from './providers/unified-adapter';
+export type { UnifiedAdapterConfig, StreamOptions } from './providers/unified-adapter';
+
+// Protocol Layer
+export {
+  ArkProtocol,
+  createArkProtocol,
+  DeepSeekProtocol,
+  createDeepSeekProtocol,
+  QwenProtocol,
+  createQwenProtocol,
+  GeminiProtocol,
+  createGeminiProtocol,
+  OpenAIProtocol,
+  createOpenAIProtocol,
+  AnthropicProtocol,
+  createAnthropicProtocol,
+} from './providers/protocols';
+
+export type {
+  Protocol,
+  ProtocolConfig,
+  ProtocolMessage,
+  ProtocolToolDefinition,
+  ProtocolToolCall,
+  RawEvent,
+  RawEventType,
+  RawToolCall,
+  RawSearchResult,
+} from './providers/protocols';
+
+// Orchestrator - 统一的工具调用处理
+export { ChatOrchestrator, createOrchestrator } from './providers/orchestrator';
+
+// 新架构类型
+export type {
+  StreamChunk,
+  StreamChunkType,
+  ToolCallRequest,
+  SearchResultItem,
+  StandardMessage,
+  ProviderAdapter,
+  AdapterConfig,
+  StreamOnceOptions,
+  OrchestratorConfig,
+  OrchestratorContext,
+  OrchestratorOptions,
+  SimpleToolDefinition,
+  ToolExecutor as OrchestratorToolExecutor,
+} from './providers/types';
+
+// Legacy Adapters 已删除，使用 UnifiedAdapter + Protocol 新架构
+
+// ==================== 配置与类型 ====================
+
+export type {
+  AgentConfig,
+  ChatOptions,
+  ChatMode,
+  ThinkingMode,
+  AutoRunMode,
+  AutoRunConfig,
+  ToolExecutor,
+  ToolDefinition,
+  ChatMessage,
+  ResponsesApiTool,
+  // 模型类型
+  ModelOption,
+  ProviderType,
+  // 工具接口
+  Tool,
+  ToolContext,
+  ToolResult,
+  // 副作用类型
+  SideEffect,
+  // 工具插件（Vite 风格）
+  ToolPlugin,
+  ToolConfigItem,
+  // 用户工具（透传模式）
+  UserToolDefinition,
+} from './types';
+
+export { 
+  // 模型列表
+  MODELS,
+  getModelByModelId,
+  // 工具解析和辅助函数
+  resolveTools,
+  tool,
+  tools,
+} from './types';
+
+// 常量
+export { DEFAULT_MODEL } from './constants';
+
+// ==================== 事件系统 ====================
+
+// 基础类型
+export type {
+  SearchResult,
+  ToolCallStatus,
+  ToolCallInfo,
+  TokenUsage,
+  ErrorCategory,
+  ErrorDetails
+} from './events';
+
+// 思考事件
+export type {
+  ThinkingStartEvent,
+  ThinkingDeltaEvent,
+  ThinkingEndEvent,
+  ThinkingEvent
+} from './events';
+
+// 搜索事件
+export type {
+  SearchStartEvent,
+  SearchResultEvent,
+  SearchEndEvent,
+  SearchEvent
+} from './events';
+
+// 工具事件
+export type {
+  ToolCallStartEvent,
+  ToolCallResultEvent,
+  ToolCallOutputEvent,
+  ToolApprovalRequestEvent,
+  ToolCallRequestEvent,
+  ToolEvent
+} from './events';
+
+// 文本事件
+export type {
+  TextDeltaEvent,
+  TextEvent
+} from './events';
+
+// 计划类型（update_plan 工具通过 resultType:'plan' 渲染，无专用事件）
+export type {
+  PlanStep,
+  PlanStepStatus,
+} from './events';
+
+// 状态事件
+export type {
+  DoneEvent,
+  ErrorEvent,
+  AbortEvent,
+  StatusEvent
+} from './events';
+
+// 步骤事件
+export type {
+  StepStartEvent,
+  StepEndEvent,
+  StepEvent
+} from './events';
+
+// 聚合类型
+export type {
+  ChatEvent,
+  ChatEventType
+} from './events';
+
+// 事件创建函数
+export {
+  createThinkingStart,
+  createThinkingDelta,
+  createThinkingEnd,
+  createSearchStart,
+  createSearchResult,
+  createSearchEnd,
+  createToolCallStart,
+  createToolCallResult,
+  createToolCallOutput,
+  createToolCallRequest,
+  createTextDelta,
+  createDone,
+  // 错误创建函数
+  createError,
+  createApiError,
+  createRateLimitError,
+  createToolError,
+  createTimeoutError,
+  createParseError,
+  createAbort,
+  // 步骤事件
+  createStepStart,
+  createStepEnd,
+  // 类型守卫
+  isThinkingEvent,
+  isSearchEvent,
+  isToolEvent,
+  isTextEvent,
+  isStatusEvent,
+  isErrorEvent,
+  isAbortEvent,
+  isStepEvent,
+  isRetryableError,
+  CHAT_EVENT_TYPES
+} from './events';
+
+// ==================== 工具执行器 ====================
+
+export { createDefaultToolExecutor } from './tools';
+
+// ==================== 工具已迁移 ====================
+//
+// 计划工具（update_plan）请使用:
+//   import { createUpdatePlanTool } from '@huyooo/ai-chat-tools-local';
+//
+// 云端工具（weather, web-search）请使用:
+//   import { getWeatherTool, createWebSearchTool } from '@huyooo/ai-chat-tools-cloud';
+// 
+// 本地工具（execute-command, ui-actions 等）请使用:
+//   import { getCwdTool, executeCommandTool, ... } from '@huyooo/ai-chat-tools-local';
+//
+
+// ==================== 路由 ====================
+
+export type { RouteResult } from './router';
+
+export {
+  routeModelToProvider,
+  routeModelWithDetails,
+  getDefaultProvider,
+  isModelForProvider
+} from './router';
+
+// ==================== MCP ====================
+// McpClientManager 只在内部使用（agent.ts 直接 import），不从主入口导出
+// 避免在 renderer 中因 barrel file 加载整个模块图而引入 Node.js-only 的 MCP SDK
+// 如需外部使用，请通过 @huyooo/ai-chat-core/mcp 子路径导入
+
+export type { McpServerConfig, McpConnectionStatus, McpConnectionInfo } from './mcp';
+
+// ==================== 调试工具 ====================
+
+export { DebugLogger } from './utils';

package/src/internal/update-plan.ts

@@ -0,0 +1,2 @@
+// 已迁移到 @huyooo/ai-chat-tools-local
+// import { createUpdatePlanTool } from '@huyooo/ai-chat-tools-local';

package/src/internal/web-search.ts

@@ -0,0 +1,78 @@
+/**
+ * Web Search 工具（内部使用，Tavily 实现）
+ *
+ * 对外统一使用工具名 web_search_ai，各协议一致使用，与厂商内置 web_search 不冲突。
+ */
+
+import type { Tool } from '../types';
+
+/** 联网搜索工具名（Tavily 实现，对外统一） */
+export const WEB_SEARCH_TOOL_NAME = 'web_search_ai';
+
+export function createWebSearchTool(tavilyApiKey: string): Tool {
+  return {
+    name: WEB_SEARCH_TOOL_NAME,
+    description:
+      '联网搜索工具。输入 query（搜索关键词/问题），返回搜索结果列表（title/url/snippet）。用于获取实时信息与可引用来源。',
+    parameters: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: '搜索关键词或问题（必填）' },
+        max_results: { type: 'number', description: '最大返回结果数（可选，默认 5）' },
+      },
+      required: ['query'],
+    },
+    resultType: 'search_results',
+    execute: async (args, ctx) => {
+      const query = typeof args.query === 'string' ? args.query : '';
+      const maxResults = typeof args.max_results === 'number' && Number.isFinite(args.max_results)
+        ? Math.max(1, Math.min(10, Math.floor(args.max_results)))
+        : 5;
+
+      if (!query.trim()) {
+        return JSON.stringify({ query: '', results: [], error: '缺少 query' });
+      }
+      if (!tavilyApiKey) {
+        return JSON.stringify({ query, results: [], error: '缺少 Tavily API Key' });
+      }
+
+      const resp = await fetch('https://api.tavily.com/search', {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${tavilyApiKey}`,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+          query,
+          max_results: maxResults,
+          search_depth: 'basic',
+          include_answer: false,
+          include_raw_content: false,
+        }),
+        signal: ctx.signal,
+      });
+
+      if (!resp.ok) {
+        const t = await resp.text().catch(() => '');
+        return JSON.stringify({ query, results: [], error: `Tavily /search 错误: ${resp.status} ${t}`.trim() });
+      }
+
+      const data: unknown = await resp.json().catch(() => null);
+
+      const results: Array<{ title: string; url: string; snippet: string }> = [];
+      const arr = (data && typeof data === 'object' && Array.isArray((data as Record<string, unknown>).results))
+        ? (data as Record<string, unknown>).results as Array<Record<string, unknown>>
+        : [];
+      for (const r of arr) {
+        const url = typeof r?.url === 'string' ? r.url : '';
+        if (!url) continue;
+        const title = typeof r?.title === 'string' ? r.title : '';
+        const snippet = typeof r?.content === 'string' ? r.content : '';
+        results.push({ title, url, snippet });
+      }
+
+      return JSON.stringify({ query, results });
+    },
+  };
+}
+

package/src/mcp/client-manager.ts

@@ -0,0 +1,301 @@
+/**
+ * MCP Client Manager
+ * 
+ * 管理多个 MCP Server 连接，自动发现工具并转换为 Tool 接口。
+ * 
+ * 职责：
+ * 1. 连接管理：根据配置连接/断开 MCP Server
+ * 2. 工具发现：通过 MCP 协议自动发现 Server 提供的工具
+ * 3. 工具适配：将 MCP 工具转换为我们的 Tool 接口
+ * 4. 生命周期：优雅关闭所有连接
+ */
+
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
+import type { Tool, JsonSchemaObject, JsonSchemaProperty } from '../types';
+import type { McpServerConfig, McpConnectionInfo, McpConnectionStatus } from './types';
+import { DebugLogger } from '../utils';
+
+const logger = DebugLogger.module('MCP');
+
+/** 单个 MCP Server 连接 */
+interface McpConnection {
+  config: McpServerConfig;
+  client: Client;
+  transport: StdioClientTransport | SSEClientTransport;
+  status: McpConnectionStatus;
+  tools: Tool[];
+  error?: string;
+}
+
+/**
+ * MCP Client Manager
+ * 
+ * 使用方式：
+ * ```typescript
+ * const manager = new McpClientManager();
+ * await manager.connectAll(configs);
+ * const tools = manager.getAllTools(); // 返回 Tool[] 直接注册到 Agent
+ * // ... 使用完毕
+ * await manager.disconnectAll();
+ * ```
+ */
+export class McpClientManager {
+  private connections = new Map<string, McpConnection>();
+
+  /**
+   * 连接到所有配置的 MCP Server
+   * 
+   * 并行连接，单个失败不影响其他。
+   */
+  async connectAll(configs: McpServerConfig[]): Promise<void> {
+    const results = await Promise.allSettled(
+      configs.map(config => this.connect(config))
+    );
+
+    // 记录连接结果
+    for (let i = 0; i < results.length; i++) {
+      const result = results[i];
+      const name = configs[i].name;
+      if (result.status === 'rejected') {
+        logger.error(`[${name}] 连接失败:`, result.reason);
+      }
+    }
+  }
+
+  /**
+   * 连接单个 MCP Server
+   */
+  async connect(config: McpServerConfig): Promise<void> {
+    const { name } = config;
+
+    // 如果已连接，先断开
+    if (this.connections.has(name)) {
+      await this.disconnect(name);
+    }
+
+    logger.info(`[${name}] 正在连接...`);
+
+    const client = new Client(
+      { name: 'ai-chat-mcp-client', version: '1.0.0' },
+    );
+
+    let transport: StdioClientTransport | SSEClientTransport;
+
+    if (config.transport === 'stdio') {
+      if (!config.command) {
+        throw new Error(`[${name}] stdio 模式必须指定 command`);
+      }
+      transport = new StdioClientTransport({
+        command: config.command,
+        args: config.args,
+        env: config.env,
+        cwd: config.cwd,
+      });
+    } else if (config.transport === 'sse') {
+      if (!config.url) {
+        throw new Error(`[${name}] sse 模式必须指定 url`);
+      }
+      transport = new SSEClientTransport(new URL(config.url));
+    } else {
+      throw new Error(`[${name}] 不支持的传输方式: ${config.transport}`);
+    }
+
+    const connection: McpConnection = {
+      config,
+      client,
+      transport,
+      status: 'connecting',
+      tools: [],
+    };
+
+    this.connections.set(name, connection);
+
+    try {
+      await client.connect(transport);
+      connection.status = 'connected';
+      logger.info(`[${name}] 已连接`);
+
+      // 发现工具
+      const tools = await this.discoverTools(connection);
+      connection.tools = tools;
+      logger.info(`[${name}] 发现 ${tools.length} 个工具:`, tools.map(t => t.name));
+    } catch (error) {
+      connection.status = 'error';
+      connection.error = error instanceof Error ? error.message : String(error);
+      logger.error(`[${name}] 连接失败:`, connection.error);
+      throw error;
+    }
+  }
+
+  /**
+   * 从 MCP Server 发现工具并转换为 Tool 接口
+   */
+  private async discoverTools(connection: McpConnection): Promise<Tool[]> {
+    const { client, config } = connection;
+    const { tools: mcpTools } = await client.listTools();
+
+    return mcpTools.map(mcpTool => this.adaptTool(mcpTool, config.name, client));
+  }
+
+  /**
+   * 将 MCP 工具转换为我们的 Tool 接口
+   * 
+   * 关键转换：
+   * - MCP inputSchema → 我们的 parameters (JsonSchemaObject)
+   * - MCP callTool() → 我们的 execute()
+   */
+  private adaptTool(
+    mcpTool: { name: string; description?: string; inputSchema: Record<string, unknown> },
+    serverName: string,
+    client: Client
+  ): Tool {
+    // 转换 inputSchema 为我们的 JsonSchemaObject
+    const parameters = this.convertSchema(mcpTool.inputSchema);
+
+    return {
+      name: mcpTool.name,
+      description: mcpTool.description || `MCP tool from ${serverName}`,
+      parameters,
+      execute: async (args: Record<string, unknown>) => {
+        const result = await client.callTool({
+          name: mcpTool.name,
+          arguments: args,
+        });
+
+        // MCP 返回 content 数组，拼接为字符串
+        const texts: string[] = [];
+        if (Array.isArray(result.content)) {
+          for (const item of result.content) {
+            if (typeof item === 'object' && item !== null) {
+              const content = item as Record<string, unknown>;
+              if (content.type === 'text' && typeof content.text === 'string') {
+                texts.push(content.text);
+              } else if (content.type === 'image') {
+                texts.push(`[image: ${content.mimeType || 'unknown'}]`);
+              } else if (content.type === 'resource') {
+                texts.push(JSON.stringify(content));
+              }
+            }
+          }
+        }
+
+        return texts.join('\n') || JSON.stringify(result.content);
+      },
+    };
+  }
+
+  /**
+   * 将 MCP inputSchema 转换为 JsonSchemaObject
+   */
+  private convertSchema(inputSchema: Record<string, unknown>): JsonSchemaObject {
+    const properties: Record<string, JsonSchemaProperty> = {};
+    const required: string[] = [];
+
+    const schemaProperties = inputSchema.properties as Record<string, Record<string, unknown>> | undefined;
+    if (schemaProperties) {
+      for (const [key, value] of Object.entries(schemaProperties)) {
+        properties[key] = this.convertProperty(value);
+      }
+    }
+
+    if (Array.isArray(inputSchema.required)) {
+      required.push(...inputSchema.required.filter((r): r is string => typeof r === 'string'));
+    }
+
+    return {
+      type: 'object',
+      properties,
+      required: required.length > 0 ? required : undefined,
+    };
+  }
+
+  /**
+   * 递归转换 JSON Schema 属性
+   */
+  private convertProperty(prop: Record<string, unknown>): JsonSchemaProperty {
+    const result: JsonSchemaProperty = {
+      type: typeof prop.type === 'string' ? prop.type : 'string',
+    };
+
+    if (typeof prop.description === 'string') {
+      result.description = prop.description;
+    }
+
+    if (Array.isArray(prop.enum)) {
+      result.enum = prop.enum;
+    }
+
+    // 递归处理 items（数组类型）
+    if (prop.items && typeof prop.items === 'object') {
+      result.items = this.convertProperty(prop.items as Record<string, unknown>);
+    }
+
+    // 递归处理 properties（对象类型）
+    if (prop.properties && typeof prop.properties === 'object') {
+      result.properties = {};
+      for (const [key, value] of Object.entries(prop.properties as Record<string, Record<string, unknown>>)) {
+        result.properties[key] = this.convertProperty(value);
+      }
+    }
+
+    if (Array.isArray(prop.required)) {
+      result.required = prop.required.filter((r): r is string => typeof r === 'string');
+    }
+
+    return result;
+  }
+
+  /**
+   * 获取所有已连接 Server 的工具
+   */
+  getAllTools(): Tool[] {
+    const tools: Tool[] = [];
+    for (const connection of this.connections.values()) {
+      if (connection.status === 'connected') {
+        tools.push(...connection.tools);
+      }
+    }
+    return tools;
+  }
+
+  /**
+   * 获取所有连接状态
+   */
+  getConnectionInfos(): McpConnectionInfo[] {
+    return Array.from(this.connections.values()).map(conn => ({
+      name: conn.config.name,
+      status: conn.status,
+      toolCount: conn.tools.length,
+      error: conn.error,
+    }));
+  }
+
+  /**
+   * 断开单个 Server
+   */
+  async disconnect(name: string): Promise<void> {
+    const connection = this.connections.get(name);
+    if (!connection) return;
+
+    try {
+      await connection.client.close();
+      logger.info(`[${name}] 已断开`);
+    } catch (error) {
+      logger.error(`[${name}] 断开失败:`, error);
+    } finally {
+      connection.status = 'disconnected';
+      connection.tools = [];
+      this.connections.delete(name);
+    }
+  }
+
+  /**
+   * 断开所有连接
+   */
+  async disconnectAll(): Promise<void> {
+    const names = Array.from(this.connections.keys());
+    await Promise.allSettled(names.map(name => this.disconnect(name)));
+  }
+}

package/src/mcp/index.ts

@@ -0,0 +1,2 @@
+export { McpClientManager } from './client-manager';
+export type { McpServerConfig, McpConnectionStatus, McpConnectionInfo } from './types';