@huyooo/ai-chat-core 0.2.13 → 0.2.14

package/dist/index.d.ts

@@ -1,107 +1,197 @@
+import * as fs from 'fs';
+
 /**
- * 模型路由模块
+ * 模型注册表
  *
- * 根据模型名称将请求路由到对应的 Provider
+ * 核心设计：Protocol + Family 分离
+ * - Protocol：负责 API 通信协议（HTTP/SSE/认证）
+ * - Family：负责模型行为差异（thinking格式、搜索方式、工具格式）
  *
- * 设计原则：
- * 1. 配置驱动：路由规则集中管理，易于扩展
- * 2. 优先级机制：高优先级规则先匹配
- * 3. 多种匹配模式：支持精确、前缀、包含、正则匹配
- */
-/** Provider 类型（API 供应商） */
-type ProviderType = 'ark' | 'qwen' | 'gemini' | 'openrouter' | 'vercel';
-/** 路由规则匹配类型 */
-type RouteMatchType = 'exact' | 'prefix' | 'contains' | 'regex';
-/** 单条路由规则 */
-interface RouteRule {
-    /** 规则类型 */
-    type: RouteMatchType;
-    /** 匹配模式（大小写不敏感） */
-    pattern: string;
-    /** 目标 Provider */
-    provider: ProviderType;
-    /** 规则优先级（数字越大越优先，默认 0） */
-    priority: number;
-    /** 规则描述（调试用） */
-    description?: string;
+ * 这样设计的好处：
+ * 1. 同协议不同行为的模型可以复用协议层（如 ARK 上的豆包和 DeepSeek）
+ * 2. 新增模型只需配置 family，无需修改 adapter 代码
+ * 3. 行为差异集中管理，易于维护
+ */
+/** 模型家族 ID */
+type ModelFamilyId = 'doubao' | 'deepseek' | 'qwen' | 'gemini' | 'gpt' | 'claude';
+/** 协议类型 */
+type ProtocolId = 'ark' | 'deepseek' | 'qwen' | 'gemini' | 'openai' | 'anthropic';
+/** Thinking 输出格式 */
+type ThinkingFormat = 'reasoning' | 'thinking_enabled' | 'thought_signature' | 'none';
+/** 搜索实现方式 */
+type SearchStrategy = 'native_web_search' | 'native_enable' | 'google_search' | 'tool_based';
+/** 工具调用格式 */
+type ToolCallFormat = 'responses' | 'openai' | 'gemini';
+/**
+ * 模型家族配置
+ * 定义同一家族模型的共同行为特征
+ */
+interface ModelFamilyConfig {
+    /** 家族 ID */
+    id: ModelFamilyId;
+    /** 显示名称 */
+    displayName: string;
+    /** 是否支持图片理解 */
+    supportsVision: boolean;
+    /** 是否支持 thinking */
+    supportsThinking: boolean;
+    /** Thinking 输出格式 */
+    thinkingFormat: ThinkingFormat;
+    /** 是否支持原生搜索 */
+    supportsNativeSearch: boolean;
+    /** 搜索实现方式 */
+    searchStrategy: SearchStrategy;
+    /** 工具调用格式 */
+    toolCallFormat: ToolCallFormat;
+    /** 默认最大输出 token */
+    defaultMaxTokens?: number;
+    /** 是否需要特殊处理（如 Gemini 的 thought_signature） */
+    requiresSpecialHandling?: string[];
+}
+/** 豆包家族 */
+declare const DOUBAO_FAMILY: ModelFamilyConfig;
+/** DeepSeek 家族 */
+declare const DEEPSEEK_FAMILY: ModelFamilyConfig;
+/** 通义千问家族 */
+/** Qwen 家族（使用 Tavily 统一搜索） */
+declare const QWEN_FAMILY: ModelFamilyConfig;
+/** Gemini 家族（注意：googleSearch 不能与其他工具同时使用，有工具时走 Tavily） */
+declare const GEMINI_FAMILY: ModelFamilyConfig;
+/** GPT 家族 */
+declare const GPT_FAMILY: ModelFamilyConfig;
+/** Claude 家族（使用 Vercel AI SDK / @ai-sdk/anthropic） */
+declare const CLAUDE_FAMILY: ModelFamilyConfig;
+/** 家族配置映射 */
+declare const MODEL_FAMILIES: Record<ModelFamilyId, ModelFamilyConfig>;
+/**
+ * 模型注册项
+ */
+interface ModelRegistryEntry {
+    /** 模型 ID（API 调用用） */
+    id: string;
+    /** 显示名称 */
+    displayName: string;
+    /** 所属家族 */
+    family: ModelFamilyId;
+    /** 使用的协议 */
+    protocol: ProtocolId;
+    /** 是否在前端显示 */
+    visible?: boolean;
+    /** 是否支持图片理解（优先级高于 family.supportsVision） */
+    supportsVision?: boolean;
+    /** 上下文窗口大小（如 "256K"） */
+    contextWindow?: string;
+    /** 价格信息（数组，分行显示） */
+    pricing?: string[];
 }
+/**
+ * 全局模型注册表
+ *
+ * 每个模型只有一家供应商，无需分组
+ */
+declare const MODEL_REGISTRY: ModelRegistryEntry[];
+/**
+ * 根据模型 ID 获取注册信息
+ */
+declare function getModelEntry(modelId: string): ModelRegistryEntry | undefined;
+/**
+ * 根据模型 ID 获取家族配置
+ */
+declare function getModelFamily(modelId: string): ModelFamilyConfig | undefined;
+/**
+ * 根据模型 ID 获取协议类型
+ */
+declare function getModelProtocol(modelId: string): ProtocolId | undefined;
+/**
+ * 获取所有可见模型（用于前端显示）
+ */
+declare function getVisibleModels(): ModelRegistryEntry[];
+/**
+ * 根据家族 ID 获取所有模型
+ */
+declare function getModelsByFamily(familyId: ModelFamilyId): ModelRegistryEntry[];
+/**
+ * 根据协议获取所有模型
+ */
+declare function getModelsByProtocol(protocol: ProtocolId): ModelRegistryEntry[];
+/**
+ * 检查模型是否支持 thinking
+ */
+declare function modelSupportsThinking(modelId: string): boolean;
+/**
+ * 检查模型是否支持原生搜索
+ */
+declare function modelSupportsNativeSearch(modelId: string): boolean;
+/**
+ * 获取模型的搜索策略
+ */
+declare function getModelSearchStrategy(modelId: string): SearchStrategy;
+
+/**
+ * 模型路由模块
+ *
+ * 根据模型 ID 查询对应的 Protocol 和 Family 配置
+ */
+
+/** Provider 类型 = Protocol 类型 */
+type ProviderType = ProtocolId;
 /** 路由结果 */
 interface RouteResult {
-    /** 匹配的 Provider */
+    /** Protocol 类型 */
     provider: ProviderType;
-    /** 匹配的规则（如果有） */
-    matchedRule?: RouteRule;
-    /** 是否使用了默认路由 */
+    /** 是否未注册（使用默认 Provider） */
     isDefault: boolean;
+    /** 模型注册信息 */
+    registryEntry?: ModelRegistryEntry;
+    /** 模型家族配置 */
+    familyConfig?: ModelFamilyConfig;
 }
 /**
- * 将模型路由到对应的 Provider
- *
- * @param model - 模型名称
- * @returns Provider 类型
+ * 获取模型的 Provider
  */
 declare function routeModelToProvider(model: string): ProviderType;
 /**
- * 将模型路由到对应的 Provider（带详细信息）
- *
- * @param model - 模型名称
- * @returns 路由结果（包含匹配规则信息）
+ * 获取模型的完整路由信息
  */
 declare function routeModelWithDetails(model: string): RouteResult;
-/**
- * 获取所有路由规则（调试用）
- */
-declare function getRouteRules(): readonly RouteRule[];
 /**
  * 获取默认 Provider
  */
 declare function getDefaultProvider(): ProviderType;
 /**
- * 检查模型是否匹配某个 Provider
- *
- * @param model - 模型名称
- * @param provider - Provider 类型
- * @returns 是否匹配
+ * 检查模型是否属于指定 Provider
  */
 declare function isModelForProvider(model: string, provider: ProviderType): boolean;
 
 /**
  * AI Chat Core 类型定义
- *
- * 注意：事件类型已迁移到 events.ts
  */
+
 /** 对话模式 */
-type ChatMode = 'agent' | 'plan' | 'ask';
+type ChatMode = 'agent' | 'ask';
 
-/**
- * 简化的模型配置
- *
- * - modelId: 发送给 API 的模型 ID
- * - displayName: 前端显示名称
- * - group: 分组名称（由后端决定，前端只负责渲染）
- */
+/** 模型选项（前端显示用） */
 interface ModelOption {
     /** 模型 ID（发送给 API） */
     modelId: string;
     /** 显示名称 */
     displayName: string;
-    /** 分组名称（由后端决定，前端只负责渲染，必填） */
-    group: string;
-    /** 是否来自 OpenRouter（保留用于兼容，后续可能移除） */
-    isOpenRouter?: boolean;
-    /** 提供商名称（保留用于兼容，后续可能移除） */
-    provider?: string;
+    /** 是否支持深度思考 */
+    supportsThinking: boolean;
+    /** 是否支持图片理解 */
+    supportsVision: boolean;
+    /** 用于模型项 hover 的特性描述（由后端定义，前端只渲染） */
+    tooltip?: {
+        features?: string[];
+        /** 开销信息（数组，分行显示） */
+        cost?: string[];
+        description?: string;
+    };
 }
 /**
- * 预定义模型列表（从 constants.ts 映射）
- *
- * 分组信息由后端决定，前端只负责渲染
+ * 预定义模型列表
  */
 declare const MODELS: ModelOption[];
-/** 获取原生模型 */
-declare function getNativeModels(): ModelOption[];
-/** 获取 OpenRouter 模型 */
-declare function getOpenRouterModels(): ModelOption[];
 /** 根据 modelId 获取模型 */
 declare function getModelByModelId(modelId: string): ModelOption | undefined;
 /** 工具批准回调函数 */
@@ -124,6 +214,10 @@ interface AgentConfig {
     openrouterApiKey?: string;
     /** OpenRouter API URL */
     openrouterApiUrl?: string;
+    /** Vercel API Key（用于 Vercel AI Gateway 访问 Claude） */
+    vercelApiKey?: string;
+    /** Tavily API Key（用于统一 Web Search） */
+    tavilyApiKey?: string;
     /** Gemini API Key (用于图片/视频，注意：中国大陆无法直接访问) */
     geminiApiKey: string;
     /** 当前工作目录（Current Working Directory） */
@@ -146,11 +240,6 @@ interface AgentConfig {
      * ```
      */
     tools?: ToolConfigItem[];
-    /**
-     * plan 模式的系统提示词（可选，有默认值）
-     * 用于指导 AI 如何制定执行计划
-     */
-    planPrompt?: string;
     /**
      * 工具批准回调（manual 模式使用）
      * 返回 true 表示批准执行，false 表示跳过
@@ -196,6 +285,8 @@ interface ChatOptions {
      * - 'disabled': 强制关闭深度思考
      */
     thinkingMode?: ThinkingMode;
+    /** 启用的工具名称列表（agent 模式有效，ask 模式强制禁用） */
+    enabledTools?: string[];
     /** 自动运行配置 */
     autoRunConfig?: AutoRunConfig$1;
     /** 对话历史（从数据库加载，无状态架构） */
@@ -260,6 +351,7 @@ interface ToolContext {
  *   description: '我的自定义工具',
  *   parameters: { type: 'object', properties: {}, required: [] },
  *   sideEffects: ['filesystem'], // 声明副作用
+ *   resultType: 'my_result',     // 结果类型（用于前端渲染）
  *   execute: async (args, ctx) => '执行结果'
  * };
  * ```
@@ -293,6 +385,15 @@ interface Tool {
      * 注意：如果 execute 返回 ToolResult 带有 sideEffects，会覆盖此静态声明
      */
     sideEffects?: SideEffect$1[];
+    /**
+     * 结果类型（用于前端渲染）
+     *
+     * 当工具执行成功时，前端会根据此类型生成对应的 ContentPart
+     * 例如：resultType: 'weather' 会生成 { type: 'weather', ...result }
+     *
+     * 如果不指定，工具结果仅显示在 ToolCallPart 的折叠面板中
+     */
+    resultType?: string;
     /**
      * 执行函数
      *
@@ -305,7 +406,10 @@ interface Tool {
 /** 工具执行器接口（可由使用方实现，用于自定义命令执行环境） */
 interface ToolExecutor$1 {
     /** 执行 Shell 命令 */
-    executeCommand(command: string, cwd?: string, signal?: AbortSignal): Promise<{
+    executeCommand(command: string, cwd?: string, signal?: AbortSignal, hooks?: {
+        onStdout?: (chunk: string) => void;
+        onStderr?: (chunk: string) => void;
+    }): Promise<{
         success: boolean;
         output?: string;
         error?: string;
@@ -406,6 +510,8 @@ interface ChatMessage {
             name: string;
             arguments: string;
         };
+        /** Gemini 模型需要的 thought_signature（用于工具调用循环） */
+        thought_signature?: string;
     }>;
 }
 /** 火山引擎 Responses API 工具定义 */
@@ -592,6 +698,29 @@ interface ToolCallResultEvent {
          * 前端可根据此字段处理通知、刷新文件列表等
          */
         sideEffects?: SideEffect[];
+        /**
+         * 结果类型（用于前端渲染）
+         *
+         * 当工具定义了 resultType 且执行成功时，前端会根据此类型生成对应的 ContentPart
+         * 例如：resultType: 'weather' 会生成 { type: 'weather', ...result }
+         */
+        resultType?: string;
+    };
+}
+/** 工具输出增量事件（用于 stdout/stderr 流式展示） */
+interface ToolCallOutputEvent {
+    type: 'tool_call_output';
+    data: {
+        /** 工具调用 ID */
+        id: string;
+        /** 工具名称 */
+        name: string;
+        /** 输出流类型 */
+        stream: 'stdout' | 'stderr';
+        /** 输出增量内容 */
+        chunk: string;
+        /** 时间戳 */
+        at: number;
     };
 }
 /** 工具执行批准请求事件（manual 模式） */
@@ -609,7 +738,7 @@ interface ToolApprovalRequestEvent {
     };
 }
 /** 工具相关事件联合类型 */
-type ToolEvent = ToolCallStartEvent | ToolCallResultEvent | ToolApprovalRequestEvent;
+type ToolEvent = ToolCallStartEvent | ToolCallResultEvent | ToolApprovalRequestEvent | ToolCallOutputEvent;
 /** 文本增量事件 */
 interface TextDeltaEvent {
     type: 'text_delta';
@@ -744,7 +873,7 @@ declare function createToolCallStart(id: string, name: string, args: Record<stri
 /**
  * 创建工具调用结果事件
  */
-declare function createToolCallResult(id: string, name: string, result: string, success: boolean, startedAt: number, error?: string, sideEffects?: SideEffect[]): ToolCallResultEvent;
+declare function createToolCallResult(id: string, name: string, result: string, success: boolean, startedAt: number, error?: string, sideEffects?: SideEffect[], resultType?: string): ToolCallResultEvent;
 /**
  * 创建文本增量事件
  */
@@ -842,22 +971,22 @@ interface RuntimeConfig {
     qwenApiUrl: string;
     openrouterApiKey: string;
     openrouterApiUrl: string;
+    vercelApiKey: string;
+    tavilyApiKey: string;
     geminiApiKey: string;
     cwd: string;
-    planPrompt: string;
 }
 /**
  * 混合 Agent 类
  *
  * 职责：
- * 1. 管理多个 ProviderAdapter
- * 2. 路由请求到正确的 Adapter
- * 3. 使用 ChatOrchestrator 统一处理工具调用
- * 4. 管理对话历史和工具注册
+ * 1. 管理 UnifiedAdapter（统一适配器）
+ * 2. 使用 ChatOrchestrator 统一处理工具调用
+ * 3. 管理工具注册
  */
 declare class HybridAgent {
     private config;
-    private adapters;
+    private adapter;
     private orchestrator;
     private geminiClient;
     private toolExecutor;
@@ -869,19 +998,18 @@ declare class HybridAgent {
     constructor(config: AgentConfig, toolExecutor?: ToolExecutor$1);
     /** 异步初始化工具（在第一次 chat 前调用） */
     private asyncInit;
-    /** 初始化所有 Adapter */
-    private initializeAdapters;
+    /** 获取模型的家族配置 */
+    getModelFamilyConfig(model: string): ModelFamilyConfig | undefined;
     /**
-     * 判断模型提供商
+     * 判断模型提供商（兼容旧接口）
      */
     private getModelProvider;
-    /** 获取 Adapter */
-    private getAdapter;
     /**
      * 调试：获取模型路由信息
      */
     getModelRouteInfo(model: string): RouteResult & {
         available: boolean;
+        familyConfig?: ModelFamilyConfig;
     };
     /** 构建系统提示词 */
     private buildSystemPrompt;
@@ -893,6 +1021,11 @@ declare class HybridAgent {
     private executeTool;
     /** 获取工具定义列表 */
     private getToolDefinitions;
+    /** 获取所有工具列表（用于设置面板） */
+    getAllTools(): Array<{
+        name: string;
+        description: string;
+    }>;
     /**
      * 聊天入口
      *
@@ -942,6 +1075,8 @@ interface ToolCallRequest {
     id: string;
     name: string;
     arguments: string;
+    /** Gemini 模型需要的 thought_signature（用于工具调用循环） */
+    thought_signature?: string;
 }
 /** 搜索结果项 */
 interface SearchResultItem {
@@ -972,6 +1107,8 @@ interface StandardMessage {
 interface AdapterConfig {
     apiKey: string;
     apiUrl?: string;
+    /** Tavily API Key（用于统一 Web Search） */
+    tavilyApiKey?: string;
 }
 /** 单次调用选项 */
 interface StreamOnceOptions {
@@ -1018,7 +1155,17 @@ interface ProviderAdapter {
  * - string: 简单结果，使用工具的静态 sideEffects
  * - ToolResult: 带动态副作用的结果
  */
-type ToolExecutor = (name: string, args: Record<string, unknown>, signal?: AbortSignal) => Promise<string | ToolResult>;
+interface ToolExecutionHooks {
+    /** 工具调用 ID（用于把输出归属到具体 tool_call 卡片） */
+    toolCallId: string;
+    /** 工具名称 */
+    toolName: string;
+    /** stdout 增量 */
+    onStdout?: (chunk: string) => void;
+    /** stderr 增量 */
+    onStderr?: (chunk: string) => void;
+}
+type ToolExecutor = (name: string, args: Record<string, unknown>, signal?: AbortSignal, hooks?: ToolExecutionHooks) => Promise<string | ToolResult>;
 /** 自动运行配置 */
 interface AutoRunConfig {
     /**
@@ -1086,209 +1233,482 @@ interface OrchestratorOptions {
 }
 
 /**
- * Chat Orchestrator
+ * UnifiedAdapter - 统一适配器
  *
- * 统一处理：
- * 1. 工具调用循环 (while iterations < MAX)
- * 2. 消息历史维护 (assistant + tool 消息)
- * 3. 事件发射 (ChatEvent)
- * 4. 错误处理
+ * 组合 Protocol + FamilyConfig，产出标准 StreamChunk
  *
- * 所有 Provider 通过此类执行，确保行为一致
+ * 设计原则：
+ * 1. Protocol 只负责 HTTP/SSE 通信，产出 RawEvent
+ * 2. UnifiedAdapter 根据 FamilyConfig 将 RawEvent 转换为 StreamChunk
+ * 3. 所有模型都使用同一个 UnifiedAdapter，行为差异由 FamilyConfig 决定
+ * 4. 实现 ProviderAdapter 接口，可与现有 Orchestrator 无缝集成
  */
 
 /**
- * Chat Orchestrator
- *
- * 核心职责：统一处理工具调用循环，所有 Provider 共享相同的逻辑
+ * UnifiedAdapter 配置
  */
-declare class ChatOrchestrator {
-    private config;
-    constructor(config: OrchestratorConfig);
+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;
+}
+/**
+ * 流式调用选项
+ */
+interface StreamOptions {
+    /** 模型 ID */
+    model: string;
+    /** 是否启用 thinking */
+    enableThinking?: boolean;
+    /** 是否启用搜索 */
+    enableSearch?: boolean;
+    /** 中断信号 */
+    signal: AbortSignal;
+}
+/**
+ * 统一适配器
+ *
+ * 实现 ProviderAdapter 接口，根据模型自动选择 Protocol，并根据 FamilyConfig 转换事件
+ */
+declare class UnifiedAdapter implements ProviderAdapter {
+    readonly name = "unified";
+    /** 支持的模型列表（从 Registry 获取） */
+    get supportedModels(): string[];
+    private protocols;
+    constructor(config: UnifiedAdapterConfig);
     /**
-     * 执行聊天
+     * 检查是否支持指定模型
+     */
+    supportsModel(model: string): boolean;
+    /**
+     * 获取模型的家族配置
+     */
+    getModelFamilyConfig(model: string): ModelFamilyConfig | undefined;
+    /**
+     * 实现 ProviderAdapter.streamOnce 接口
      *
-     * @param adapter Provider 适配器
-     * @param message 用户消息
-     * @param context Orchestrator 上下文
-     * @param options 选项
+     * @param messages 标准消息列表
+     * @param tools 工具定义
+     * @param options 调用选项
+     * @returns 标准 StreamChunk 流
      */
-    chat(adapter: ProviderAdapter, message: string, context: OrchestratorContext, options: OrchestratorOptions): AsyncGenerator<ChatEvent>;
+    streamOnce(messages: StandardMessage[], tools: SimpleToolDefinition[], options: StreamOnceOptions): AsyncGenerator<StreamChunk>;
     /**
-     * 构建标准化消息列表
+     * 流式调用（内部方法）
      */
-    private buildMessages;
+    private stream;
+    /**
+     * 将 RawEvent 转换为 StreamChunk
+     *
+     * 根据 FamilyConfig 处理行为差异
+     */
+    private transformEvents;
 }
 /**
- * 创建 Orchestrator 实例
+ * 创建 UnifiedAdapter
  */
-declare function createOrchestrator(config: OrchestratorConfig): ChatOrchestrator;
+declare function createUnifiedAdapter(config: UnifiedAdapterConfig): UnifiedAdapter;
 
 /**
- * ARK (火山引擎) Adapter
+ * Protocol Layer 类型定义
  *
- * 职责：
- * - 将标准消息转换为 ARK Responses API 格式
- * - 调用 API 并解析响应为标准 StreamChunk
- * - 不处理工具执行和消息历史
+ * Protocol 只负责：
+ * 1. HTTP 请求发送
+ * 2. SSE 流解析
+ * 3. 认证处理
+ *
+ * 不负责：
+ * - thinking 格式转换（由 Family 处理）
+ * - 搜索行为差异（由 Family 处理）
+ * - 工具调用格式差异（由 Family 处理）
  */
 
-/** ARK 支持的模型 */
-declare const ARK_MODELS: string[];
 /**
- * ARK Adapter
+ * Protocol 原始事件类型
  *
- * 使用 Responses API 格式
+ * 这是 Protocol 层产出的"原始"事件，
+ * 后续由 FamilyBehavior 转换为标准 StreamChunk
+ */
+type RawEventType = 'text_delta' | 'thinking_delta' | 'thinking_done' | 'tool_call_start' | 'tool_call_delta' | 'tool_call_done' | 'search_query' | 'search_result' | 'done' | 'error';
+/**
+ * 原始工具调用
  */
-declare class ArkAdapter implements ProviderAdapter {
+interface RawToolCall {
+    id: string;
+    name: string;
+    arguments: string;
+    /** Gemini 需要的 thoughtSignature（用于工具调用循环） */
+    thoughtSignature?: string;
+}
+/**
+ * Protocol 消息中的工具调用
+ */
+interface ProtocolToolCall {
+    id: string;
+    name: string;
+    arguments: string;
+    /** Gemini 需要的 thoughtSignature */
+    thoughtSignature?: string;
+}
+/**
+ * 原始搜索结果
+ */
+interface RawSearchResult {
+    title: string;
+    url: string;
+    snippet: string;
+}
+/**
+ * Protocol 原始事件
+ */
+interface RawEvent {
+    type: RawEventType;
+    delta?: string;
+    toolCall?: Partial<RawToolCall>;
+    searchQuery?: string;
+    searchResults?: RawSearchResult[];
+    finishReason?: 'stop' | 'tool_calls' | 'length' | 'error';
+    error?: string;
+}
+/**
+ * Protocol 请求消息（标准化格式）
+ */
+interface ProtocolMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: string;
+    /** 图片列表（base64 或 URL） */
+    images?: string[];
+    /** 工具调用（assistant 消息） */
+    toolCalls?: ProtocolToolCall[];
+    /** 工具调用 ID（tool 消息） */
+    toolCallId?: string;
+    /** 工具名称（tool 消息，Gemini 需要） */
+    toolName?: string;
+}
+/**
+ * Protocol 工具定义（简化格式）
+ */
+interface ProtocolToolDefinition {
+    name: string;
+    description: string;
+    parameters: {
+        type: 'object';
+        properties: Record<string, {
+            type: string;
+            description: string;
+            enum?: string[];
+            items?: {
+                type: string;
+            };
+        }>;
+        required: string[];
+    };
+}
+/**
+ * Protocol 请求选项
+ */
+interface ProtocolRequestOptions {
+    /** 模型 ID */
+    model: string;
+    /** 模型家族配置 */
+    familyConfig: ModelFamilyConfig;
+    /** 是否启用 thinking */
+    enableThinking: boolean;
+    /** 是否启用搜索 */
+    enableSearch: boolean;
+    /** 中断信号 */
+    signal: AbortSignal;
+}
+/**
+ * Protocol 配置
+ */
+interface ProtocolConfig {
+    apiKey: string;
+    apiUrl?: string;
+}
+/**
+ * Protocol 接口
+ *
+ * 只负责 HTTP/SSE 通信，不处理任何业务逻辑
+ */
+interface Protocol {
+    /** 协议名称 */
+    readonly name: string;
+    /**
+     * 发送请求并返回原始事件流
+     *
+     * @param messages 消息列表
+     * @param tools 工具定义
+     * @param options 请求选项
+     * @returns 原始事件流
+     */
+    stream(messages: ProtocolMessage[], tools: ProtocolToolDefinition[], options: ProtocolRequestOptions): AsyncGenerator<RawEvent>;
+}
+
+/**
+ * ARK Protocol（火山引擎 Responses API）
+ *
+ * 只负责：
+ * - HTTP 请求发送
+ * - SSE 流解析
+ * - 原始事件产出
+ */
+
+/**
+ * ARK Protocol 实现
+ */
+declare class ArkProtocol implements Protocol {
     readonly name = "ark";
-    readonly supportedModels: string[];
     private apiKey;
     private apiUrl;
-    constructor(config: AdapterConfig);
-    supportsModel(model: string): boolean;
+    constructor(config: ProtocolConfig);
     /**
-     * 单次流式调用
+     * 发送请求并返回原始事件流
      */
-    streamOnce(messages: StandardMessage[], tools: SimpleToolDefinition[], options: StreamOnceOptions): AsyncGenerator<StreamChunk>;
+    stream(messages: ProtocolMessage[], tools: ProtocolToolDefinition[], options: ProtocolRequestOptions): AsyncGenerator<RawEvent>;
     /**
-     * 转换标准消息为 ARK Responses API 格式
+     * 构建请求体
+     */
+    private buildRequestBody;
+    /**
+     * 转换消息格式
      */
     private convertMessages;
     /**
-     * 解析 ARK 流式响应
+     * 解析 SSE 流
      */
-    private parseStream;
+    private parseSSE;
 }
 /**
- * 创建 ARK Adapter
+ * 创建 ARK Protocol
  */
-declare function createArkAdapter(config: AdapterConfig): ArkAdapter;
+declare function createArkProtocol(config: ProtocolConfig): ArkProtocol;
 
 /**
- * OpenRouter Adapter
+ * DeepSeek Protocol（通过火山引擎 ARK API 访问）
  *
- * 职责：
- * - 将标准消息转换为 OpenAI 兼容格式
- * - 调用 API 并解析响应为标准 StreamChunk
- * - 不处理工具执行和消息历史
+ * 特点：
+ * - 支持 reasoning（深度思考）
+ * - 支持 web_search 原生搜索
+ * - 与豆包共用 ARK API，但行为可能有差异
  */
 
-/** OpenRouter 支持的模型 */
-declare const OPENROUTER_MODELS: string[];
 /**
- * OpenRouter Adapter
+ * DeepSeek Protocol 实现
+ */
+declare class DeepSeekProtocol implements Protocol {
+    readonly name = "deepseek";
+    private apiKey;
+    private apiUrl;
+    constructor(config: ProtocolConfig);
+    stream(messages: ProtocolMessage[], tools: ProtocolToolDefinition[], options: ProtocolRequestOptions): AsyncGenerator<RawEvent>;
+    /**
+     * 构建请求体（DeepSeek 专用）
+     */
+    private buildRequestBody;
+    private convertMessages;
+    /**
+     * 解析 SSE 流（DeepSeek 专用）
+     */
+    private parseSSE;
+}
+declare function createDeepSeekProtocol(config: ProtocolConfig): DeepSeekProtocol;
+
+/**
+ * Qwen Protocol（通义千问 OpenAI 兼容模式 API）
  *
- * 使用 OpenAI 兼容 API 格式
+ * 使用 OpenAI 兼容端点以支持工具调用：
+ * https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions
  */
-declare class OpenRouterAdapter implements ProviderAdapter {
-    readonly name = "openrouter";
-    readonly supportedModels: string[];
+
+/**
+ * Qwen Protocol 实现（OpenAI 兼容模式）
+ */
+declare class QwenProtocol implements Protocol {
+    readonly name = "qwen";
     private apiKey;
     private apiUrl;
-    constructor(config: AdapterConfig);
-    supportsModel(model: string): boolean;
+    constructor(config: ProtocolConfig);
     /**
-     * 单次流式调用
+     * 发送请求并返回原始事件流
      */
-    streamOnce(messages: StandardMessage[], tools: SimpleToolDefinition[], options: StreamOnceOptions): AsyncGenerator<StreamChunk>;
+    stream(messages: ProtocolMessage[], tools: ProtocolToolDefinition[], options: ProtocolRequestOptions): AsyncGenerator<RawEvent>;
+    /**
+     * 构建请求体（OpenAI 格式）
+     */
+    private buildRequestBody;
     /**
-     * 转换标准消息为 OpenAI 格式
+     * 转换消息格式（OpenAI 标准格式）
      */
     private convertMessages;
     /**
-     * 解析 OpenAI 兼容流式响应
+     * 解析 SSE 流（OpenAI 格式）
      */
-    private parseStream;
+    private parseSSE;
 }
 /**
- * 创建 OpenRouter Adapter
+ * 创建 Qwen Protocol
  */
-declare function createOpenRouterAdapter(config: AdapterConfig): OpenRouterAdapter;
+declare function createQwenProtocol(config: ProtocolConfig): QwenProtocol;
 
 /**
- * Qwen (通义千问) Adapter
+ * Gemini Protocol（Google Gemini API）
  *
- * 职责：
- * - 将标准消息转换为 DashScope 原生 API 格式
- * - 调用 API 并解析响应为标准 StreamChunk
- * - 不处理工具执行和消息历史
+ * 只负责：
+ * - HTTP 请求发送
+ * - SSE 流解析
+ * - 原始事件产出
  */
 
-/** Qwen 支持的模型 */
-declare const QWEN_MODELS: string[];
 /**
- * Qwen Adapter
- *
- * 使用 DashScope 原生协议
+ * Gemini Protocol 实现
  */
-declare class QwenAdapter implements ProviderAdapter {
-    readonly name = "qwen";
-    readonly supportedModels: string[];
+declare class GeminiProtocol implements Protocol {
+    readonly name = "gemini";
     private apiKey;
     private apiUrl;
-    constructor(config: AdapterConfig);
-    supportsModel(model: string): boolean;
+    constructor(config: ProtocolConfig);
     /**
-     * 单次流式调用
+     * 发送请求并返回原始事件流
      */
-    streamOnce(messages: StandardMessage[], tools: SimpleToolDefinition[], options: StreamOnceOptions): AsyncGenerator<StreamChunk>;
+    stream(messages: ProtocolMessage[], tools: ProtocolToolDefinition[], options: ProtocolRequestOptions): AsyncGenerator<RawEvent>;
     /**
-     * 转换标准消息为 Qwen 格式
+     * 构建请求体
+     */
+    private buildRequestBody;
+    /**
+     * 转换消息格式
      */
     private convertMessages;
     /**
-     * 解析 Qwen 流式响应
+     * 解析 SSE 流
      */
-    private parseStream;
+    private parseSSE;
 }
 /**
- * 创建 Qwen Adapter
+ * 创建 Gemini Protocol
  */
-declare function createQwenAdapter(config: AdapterConfig): QwenAdapter;
+declare function createGeminiProtocol(config: ProtocolConfig): GeminiProtocol;
 
 /**
- * Gemini Adapter
+ * OpenAI Protocol（通过 OpenRouter 访问 OpenAI/GPT 模型）
  *
- * 职责：
- * - 将标准消息转换为 Gemini SDK 格式
- * - 调用 SDK 并解析响应为标准 StreamChunk
- * - 不处理工具执行和消息历史
+ * 特点：
+ * - GPT-5.x 支持 reasoning（思考模式）
+ * - 支持工具调用
  */
 
-/** Gemini 支持的模型 */
-declare const GEMINI_MODELS: string[];
-/** Gemini Adapter 配置 */
-interface GeminiAdapterConfig {
-    apiKey: string;
-}
 /**
- * Gemini Adapter
- *
- * 使用 @google/genai SDK
+ * OpenAI Protocol 实现（通过 OpenRouter）
  */
-declare class GeminiAdapter implements ProviderAdapter {
-    readonly name = "gemini";
-    readonly supportedModels: string[];
-    private client;
+declare class OpenAIProtocol implements Protocol {
+    readonly name = "openai";
     private apiKey;
-    constructor(config: GeminiAdapterConfig);
-    /** 懒加载客户端 */
-    private getClient;
-    supportsModel(model: string): boolean;
+    private apiUrl;
+    constructor(config: ProtocolConfig);
+    stream(messages: ProtocolMessage[], tools: ProtocolToolDefinition[], options: ProtocolRequestOptions): AsyncGenerator<RawEvent>;
     /**
-     * 单次流式调用
+     * 构建请求体（OpenAI/GPT 专用）
      */
-    streamOnce(messages: StandardMessage[], tools: SimpleToolDefinition[], options: StreamOnceOptions): AsyncGenerator<StreamChunk>;
+    private buildRequestBody;
+    private convertMessages;
     /**
-     * 转换标准消息为 Gemini 格式
+     * 解析 SSE 流（OpenAI/GPT 专用）
+     */
+    private parseSSE;
+}
+declare function createOpenAIProtocol(config: ProtocolConfig): OpenAIProtocol;
+
+/**
+ * Anthropic Protocol（通过 Vercel AI Gateway）
+ *
+ * 特点：
+ * - 使用 Vercel AI SDK 的 createGateway
+ * - 支持 extended thinking
+ * - 支持工具调用
+ * - 自动处理流式输出
+ *
+ * 参考: https://vercel.com/docs/ai-gateway
+ */
+
+/**
+ * Anthropic Protocol 实现（通过 Vercel AI Gateway）
+ */
+declare class AnthropicProtocol implements Protocol {
+    readonly name = "anthropic";
+    private gateway;
+    constructor(config: ProtocolConfig);
+    stream(messages: ProtocolMessage[], tools: ProtocolToolDefinition[], options: ProtocolRequestOptions): AsyncGenerator<RawEvent>;
+    /**
+     * 转换消息格式（ProtocolMessage → AI SDK CoreMessage）
+     * 简化版：主要处理文本消息，工具调用通过历史上下文传递
      */
     private convertMessages;
+    /**
+     * 转换工具格式（ProtocolToolDefinition → AI SDK tools）
+     * 注意：Vercel Gateway 对工具格式有特殊要求，这里使用标准格式
+     */
+    private convertTools;
+    /**
+     * 将 JSON Schema 转换为 Zod Schema
+     */
+    private jsonSchemaToZod;
+    /**
+     * 解析 AI SDK 流式响应
+     */
+    private parseStream;
+}
+declare function createAnthropicProtocol(config: ProtocolConfig): AnthropicProtocol;
+
+/**
+ * Chat Orchestrator
+ *
+ * 统一处理：
+ * 1. 工具调用循环 (while iterations < MAX)
+ * 2. 消息历史维护 (assistant + tool 消息)
+ * 3. 事件发射 (ChatEvent)
+ * 4. 错误处理
+ *
+ * 所有 Provider 通过此类执行，确保行为一致
+ */
+
+/**
+ * Chat Orchestrator
+ *
+ * 核心职责：统一处理工具调用循环，所有 Provider 共享相同的逻辑
+ */
+declare class ChatOrchestrator {
+    private config;
+    constructor(config: OrchestratorConfig);
+    /**
+     * 执行聊天
+     *
+     * @param adapter Provider 适配器
+     * @param message 用户消息
+     * @param context Orchestrator 上下文
+     * @param options 选项
+     */
+    chat(adapter: ProviderAdapter, message: string, context: OrchestratorContext, options: OrchestratorOptions): AsyncGenerator<ChatEvent>;
+    /**
+     * 构建标准化消息列表
+     */
+    private buildMessages;
 }
 /**
- * 创建 Gemini Adapter
+ * 创建 Orchestrator 实例
  */
-declare function createGeminiAdapter(config: GeminiAdapterConfig): GeminiAdapter;
+declare function createOrchestrator(config: OrchestratorConfig): ChatOrchestrator;
 
 declare const DEFAULT_MODEL: string;
 
@@ -1427,4 +1847,56 @@ declare function getDocumentSearchInstance(dataDir?: string, workspace?: string)
     [key: string]: unknown;
 } | null>;
 
-export { ARK_MODELS, type AbortEvent, type AdapterConfig, type AgentConfig, ArkAdapter, type AutoRunConfig$1 as AutoRunConfig, type AutoRunMode, type ChatEvent, type ChatEventType, type ChatMessage, type ChatMode, type ChatOptions, ChatOrchestrator, DEFAULT_MODEL, type DoneEvent, type ErrorCategory, type ErrorDetails, type ErrorEvent, GEMINI_MODELS, GeminiAdapter, HybridAgent, type ImageEvent, MODELS, type MediaEvent, type ModelOption, OPENROUTER_MODELS, OpenRouterAdapter, type OrchestratorConfig, type OrchestratorContext, type OrchestratorOptions, type ToolExecutor as OrchestratorToolExecutor, type ProviderAdapter, type ProviderType, QWEN_MODELS, QwenAdapter, type ResponsesApiTool, type RouteMatchType, type RouteResult, type RouteRule, type RuntimeConfig, type SearchEndEvent, type SearchEvent, type SearchResult, type SearchResultEvent, type SearchResultItem, type SearchStartEvent, type SearchToolsOptions, type SideEffect$1 as SideEffect, type SimpleToolDefinition, type StandardMessage, type StatusEvent, type StepEndEvent, type StepEvent, type StepStartEvent, type StreamChunk, type StreamChunkType, type StreamOnceOptions, type StreamStartEvent, type TextDeltaEvent, type TextEvent, type ThinkingDeltaEvent, type ThinkingEndEvent, type ThinkingEvent, type ThinkingMode, type ThinkingStartEvent, type TokenUsage, type Tool, type ToolCallInfo, type ToolCallRequest, type ToolCallResultEvent, type ToolCallStartEvent, type ToolCallStatus, type ToolConfigItem, type ToolContext, type ToolDefinition, type ToolEvent, type ToolExecutor$1 as ToolExecutor, type ToolPlugin, type ToolResult, type VideoEvent, analyzeImageTool, analyzeVideoTool, createAbort, createApiError, createArkAdapter, createDefaultToolExecutor, createDocumentSearchTools, createDone, createError, createGeminiAdapter, createImage, createOpenRouterAdapter, createOrchestrator, createParseError, createQwenAdapter, createRateLimitError, createSearchEnd, createSearchResult, createSearchStart, createStepEnd, createStepStart, createStreamStart, createTextDelta, createThinkingDelta, createThinkingEnd, createThinkingStart, createTimeoutError, createToolCallResult, createToolCallStart, createToolError, createVideo, executeCommandTool, generateImageTool, getCwdTool, getDefaultProvider, getDocumentSearchInstance, getModelByModelId, getNativeModels, getOpenRouterModels, getPlatformTool, getRouteRules, getWeatherTool, isAbortEvent, isErrorEvent, isMediaEvent, isModelForProvider, isRetryableError, isSearchEvent, isStatusEvent, isStepEvent, isTextEvent, isThinkingEvent, isToolEvent, navigateToDirectoryTool, openConfirmDialogTool, openFilePreviewTool, resolveTools, routeModelToProvider, routeModelWithDetails, showToastTool, tool, tools, uiActionTools };
+/**
+ * 调试日志工具
+ *
+ * 用法：
+ * - 设置环境变量 AI_CHAT_DEBUG=true 启用调试日志
+ * - 设置环境变量 AI_CHAT_DEBUG_FILE=/path/to/log.jsonl 启用文件输出
+ * - 或者调用 DebugLogger.enable() / DebugLogger.setLogFile()
+ */
+/**
+ * 调试日志工具
+ */
+declare const DebugLogger: {
+    /**
+     * 启用/禁用调试日志
+     */
+    enable(enabled?: boolean): void;
+    /**
+     * 检查是否启用
+     */
+    isEnabled(): boolean;
+    /**
+     * 直接设置 fs 模块（用于 Electron 主进程等打包环境）
+     */
+    setFsModule(fs: typeof fs): void;
+    /**
+     * 设置日志文件路径（仅 Node.js 环境有效）
+     * @param path 日志文件路径，null 表示禁用文件输出
+     */
+    setLogFile(path: string | null): void;
+    /**
+     * 获取日志文件路径
+     */
+    getLogFile(): string | null;
+    /**
+     * 立即刷新日志到文件
+     */
+    flush(): void;
+    /**
+     * 创建模块专用的 logger
+     */
+    module(moduleName: string): {
+        debug: (message: string, data?: unknown) => void;
+        info: (message: string, data?: unknown) => void;
+        warn: (message: string, data?: unknown) => void;
+        error: (message: string, data?: unknown) => void;
+    };
+    debug: (module: string, message: string, data?: unknown) => void;
+    info: (module: string, message: string, data?: unknown) => void;
+    warn: (module: string, message: string, data?: unknown) => void;
+    error: (module: string, message: string, data?: unknown) => void;
+};
+
+export { type AbortEvent, type AdapterConfig, type AgentConfig, AnthropicProtocol, ArkProtocol, type AutoRunConfig$1 as AutoRunConfig, type AutoRunMode, CLAUDE_FAMILY, type ChatEvent, type ChatEventType, type ChatMessage, type ChatMode, type ChatOptions, ChatOrchestrator, DEEPSEEK_FAMILY, DEFAULT_MODEL, DOUBAO_FAMILY, DebugLogger, DeepSeekProtocol, type DoneEvent, type ErrorCategory, type ErrorDetails, type ErrorEvent, GEMINI_FAMILY, GPT_FAMILY, GeminiProtocol, HybridAgent, type ImageEvent, MODELS, MODEL_FAMILIES, MODEL_REGISTRY, type MediaEvent, type ModelFamilyConfig, type ModelFamilyId, type ModelOption, type ModelRegistryEntry, OpenAIProtocol, type OrchestratorConfig, type OrchestratorContext, type OrchestratorOptions, type ToolExecutor as OrchestratorToolExecutor, type Protocol, type ProtocolConfig, type ProtocolId, type ProtocolMessage, type ProtocolToolCall, type ProtocolToolDefinition, type ProviderAdapter, type ProviderType, QWEN_FAMILY, QwenProtocol, type RawEvent, type RawEventType, type RawSearchResult, type RawToolCall, type ResponsesApiTool, type RouteResult, type RuntimeConfig, type SearchEndEvent, type SearchEvent, type SearchResult, type SearchResultEvent, type SearchResultItem, type SearchStartEvent, type SearchStrategy, type SearchToolsOptions, type SideEffect$1 as SideEffect, type SimpleToolDefinition, type StandardMessage, type StatusEvent, type StepEndEvent, type StepEvent, type StepStartEvent, type StreamChunk, type StreamChunkType, type StreamOnceOptions, type StreamOptions, type StreamStartEvent, type TextDeltaEvent, type TextEvent, type ThinkingDeltaEvent, type ThinkingEndEvent, type ThinkingEvent, type ThinkingFormat, type ThinkingMode, type ThinkingStartEvent, type TokenUsage, type Tool, type ToolCallFormat, type ToolCallInfo, type ToolCallRequest, type ToolCallResultEvent, type ToolCallStartEvent, type ToolCallStatus, type ToolConfigItem, type ToolContext, type ToolDefinition, type ToolEvent, type ToolExecutor$1 as ToolExecutor, type ToolPlugin, type ToolResult, UnifiedAdapter, type UnifiedAdapterConfig, type VideoEvent, analyzeImageTool, analyzeVideoTool, createAbort, createAnthropicProtocol, createApiError, createArkProtocol, createDeepSeekProtocol, createDefaultToolExecutor, createDocumentSearchTools, createDone, createError, createGeminiProtocol, createImage, createOpenAIProtocol, createOrchestrator, createParseError, createQwenProtocol, createRateLimitError, createSearchEnd, createSearchResult, createSearchStart, createStepEnd, createStepStart, createStreamStart, createTextDelta, createThinkingDelta, createThinkingEnd, createThinkingStart, createTimeoutError, createToolCallResult, createToolCallStart, createToolError, createUnifiedAdapter, createVideo, executeCommandTool, generateImageTool, getCwdTool, getDefaultProvider, getDocumentSearchInstance, getModelByModelId, getModelEntry, getModelFamily, getModelProtocol, getModelSearchStrategy, getModelsByFamily, getModelsByProtocol, getPlatformTool, getVisibleModels, getWeatherTool, isAbortEvent, isErrorEvent, isMediaEvent, isModelForProvider, isRetryableError, isSearchEvent, isStatusEvent, isStepEvent, isTextEvent, isThinkingEvent, isToolEvent, modelSupportsNativeSearch, modelSupportsThinking, navigateToDirectoryTool, openConfirmDialogTool, openFilePreviewTool, resolveTools, routeModelToProvider, routeModelWithDetails, showToastTool, tool, tools, uiActionTools };