@huyooo/ai-chat-core 0.2.19 → 0.2.21

package/dist/index.d.ts

@@ -1,4 +1,43 @@
-import * as fs from 'fs';
+import { ChatEvent } from './events.js';
+export { AbortEvent, CHAT_EVENT_TYPES, ChatEventType, DoneEvent, ErrorCategory, ErrorDetails, ErrorEvent, PlanStep, PlanStepStatus, SearchEndEvent, SearchEvent, SearchResult, SearchResultEvent, SearchStartEvent, StatusEvent, StepEndEvent, StepEvent, StepStartEvent, TextDeltaEvent, TextEvent, ThinkingDeltaEvent, ThinkingEndEvent, ThinkingEvent, ThinkingStartEvent, TokenUsage, ToolApprovalRequestEvent, ToolCallInfo, ToolCallOutputEvent, ToolCallRequestEvent, ToolCallResultEvent, ToolCallStartEvent, ToolCallStatus, ToolEvent, createAbort, createApiError, createDone, createError, createParseError, createRateLimitError, createSearchEnd, createSearchResult, createSearchStart, createStepEnd, createStepStart, createTextDelta, createThinkingDelta, createThinkingEnd, createThinkingStart, createTimeoutError, createToolCallOutput, createToolCallRequest, createToolCallResult, createToolCallStart, createToolError, isAbortEvent, isErrorEvent, isRetryableError, isSearchEvent, isStatusEvent, isStepEvent, isTextEvent, isThinkingEvent, isToolEvent } from './events.js';
+
+/**
+ * MCP (Model Context Protocol) 相关类型定义
+ *
+ * 支持两种传输方式：
+ * - stdio: 启动本地子进程，通过 stdin/stdout 通信（操作本地文件、命令、应用）
+ * - sse: 连接远程 HTTP 服务器（调用远程 API/服务）
+ */
+/** MCP Server 配置 */
+interface McpServerConfig {
+    /** 服务器唯一标识（用于日志和工具命名空间） */
+    name: string;
+    /** 传输方式 */
+    transport: 'stdio' | 'sse';
+    /** stdio 模式：启动命令（如 "npx", "python3", "/usr/local/bin/my-server"） */
+    command?: string;
+    /** stdio 模式：命令参数 */
+    args?: string[];
+    /** stdio 模式：环境变量 */
+    env?: Record<string, string>;
+    /** stdio 模式：工作目录 */
+    cwd?: string;
+    /** sse 模式：服务器 URL */
+    url?: string;
+}
+/** MCP 连接状态 */
+type McpConnectionStatus = 'connecting' | 'connected' | 'disconnected' | 'error';
+/** 单个 MCP 连接信息 */
+interface McpConnectionInfo {
+    /** 服务器名称 */
+    name: string;
+    /** 连接状态 */
+    status: McpConnectionStatus;
+    /** 提供的工具数量 */
+    toolCount: number;
+    /** 错误信息（status === 'error' 时） */
+    error?: string;
+}
 
 /**
  * 模型注册表
@@ -18,8 +57,12 @@ 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';
+/**
+ * 搜索实现方式（谁提供搜索、行为是否由我们统一）
+ * - provider_native：厂商原生，协议层各自实现（ARK type:web_search / Gemini googleSearch 等），行为各异
+ * - tavily：我们注入 Tavily web_search 工具，行为一致（GPT/Claude/Qwen/Gemini 有工具时）
+ */
+type SearchStrategy = 'provider_native' | 'tavily';
 /** 工具调用格式 */
 type ToolCallFormat = 'responses' | 'openai' | 'gemini';
 /**
@@ -48,9 +91,9 @@ interface ModelFamilyConfig {
     /** 是否需要特殊处理（如 Gemini 的 thought_signature） */
     requiresSpecialHandling?: string[];
 }
-/** 豆包家族 */
+/** 豆包家族（联网搜索统一走 web_search_ai/Tavily，与其它模型事件与数据格式一致） */
 declare const DOUBAO_FAMILY: ModelFamilyConfig;
-/** DeepSeek 家族 */
+/** DeepSeek 家族（联网搜索统一走 web_search_ai/Tavily，与其它模型事件与数据格式一致） */
 declare const DEEPSEEK_FAMILY: ModelFamilyConfig;
 /** 通义千问家族 */
 /** Qwen 家族（使用 Tavily 统一搜索） */
@@ -250,6 +293,21 @@ interface AgentConfig {
      * 每次检查工具批准时调用，获取最新配置
      */
     getAutoRunConfig?: () => Promise<AutoRunConfig$1 | undefined>;
+    /**
+     * MCP Server 配置列表
+     *
+     * 初始化时自动连接所有 MCP Server，发现工具并注册到 Agent。
+     *
+     * @example
+     * ```typescript
+     * mcpServers: [
+     *   { name: 'filesystem', transport: 'stdio', command: 'npx', args: ['-y', '@modelcontextprotocol/server-filesystem', '/Users/me'] },
+     *   { name: 'github', transport: 'stdio', command: 'npx', args: ['-y', '@modelcontextprotocol/server-github'], env: { GITHUB_TOKEN: '...' } },
+     *   { name: 'remote-db', transport: 'sse', url: 'http://localhost:3001/mcp' },
+     * ]
+     * ```
+     */
+    mcpServers?: McpServerConfig[];
 }
 /** 深度思考模式 */
 type ThinkingMode = 'enabled' | 'disabled';
@@ -269,6 +327,20 @@ interface ChatHistoryMessage {
     role: 'user' | 'assistant' | 'system' | 'tool';
     content: string;
 }
+/**
+ * 用户工具定义（透传模式）
+ *
+ * 只包含 schema，不包含 execute 函数
+ * 由客户端执行，服务端透传 tool_call_request 事件
+ */
+interface UserToolDefinition {
+    /** 工具名称 */
+    name: string;
+    /** 工具描述（供 AI 理解） */
+    description: string;
+    /** 参数定义（JSON Schema，支持嵌套） */
+    parameters: JsonSchemaObject;
+}
 /** 聊天配置（每次聊天可变的选项） */
 interface ChatOptions {
     /** 对话模式 */
@@ -291,6 +363,31 @@ interface ChatOptions {
     autoRunConfig?: AutoRunConfig$1;
     /** 对话历史（从数据库加载，无状态架构） */
     history?: ChatHistoryMessage[];
+    /**
+     * 用户自定义工具（透传模式）
+     *
+     * 这些工具不在服务端执行，而是：
+     * 1. 传递给 AI 模型
+     * 2. AI 返回 tool_call 时，发送 tool_call_request 事件给客户端
+     * 3. 客户端执行后，发新请求继续对话
+     */
+    userTools?: UserToolDefinition[];
+    /**
+     * 上次请求的计划快照（可选，仅用于断点续传）
+     *
+     * 正常流程不需要传：AI 会在单次请求内自主创建和管理计划。
+     *
+     * 仅在请求被中断后需要恢复时使用：
+     * - 客户端工具透传模式（请求中断，等客户端执行后重新发请求）
+     * - 用户 abort 后想继续
+     */
+    /**
+     * Skills 内容（启用的 Skills 的 content 数组，由前端/服务端拼好传入）
+     *
+     * 自动注入到 system prompt 的【用户指令】段落。
+     * 前端合并「默认启用的 skills + @ 手动选的 skills」后传入。
+     */
+    skillContents?: string[];
 }
 /**
  * 副作用定义（参考 REST API 规范）
@@ -305,7 +402,7 @@ interface ChatOptions {
  * // 失败
  * { type: 'notification', success: false, message: 'API 超时' }
  */
-interface SideEffect$1 {
+interface SideEffect {
     /** 副作用类型 */
     type: string;
     /** 是否成功 */
@@ -324,7 +421,7 @@ interface ToolResult {
     /** 执行结果（字符串） */
     result: string;
     /** 动态副作用（覆盖静态声明） */
-    sideEffects?: SideEffect$1[];
+    sideEffects?: SideEffect[];
 }
 /** 工具执行上下文 */
 interface ToolContext {
@@ -341,6 +438,23 @@ interface ToolContext {
     /** 中断信号（用于取消长时间操作） */
     signal?: AbortSignal;
 }
+/** JSON Schema 属性定义（支持嵌套，符合 JSON Schema 规范） */
+interface JsonSchemaProperty {
+    type?: string;
+    description?: string;
+    enum?: unknown[];
+    items?: JsonSchemaProperty;
+    properties?: Record<string, JsonSchemaProperty>;
+    required?: string[];
+    default?: unknown;
+}
+/** JSON Schema 对象类型（工具参数的根类型） */
+interface JsonSchemaObject {
+    type: 'object';
+    properties: Record<string, JsonSchemaProperty>;
+    required?: string[];
+    description?: string;
+}
 /**
  * 工具接口（用户可实现此接口创建自定义工具）
  *
@@ -361,19 +475,8 @@ interface Tool {
     name: string;
     /** 工具描述（供 AI 理解） */
     description: string;
-    /** 参数定义（JSON Schema） */
-    parameters: {
-        type: 'object';
-        properties: Record<string, {
-            type: string;
-            description: string;
-            enum?: string[];
-            items?: {
-                type: string;
-            };
-        }>;
-        required: string[];
-    };
+    /** 参数定义（JSON Schema，支持嵌套对象和数组） */
+    parameters: JsonSchemaObject;
     /**
      * 静态副作用声明（可选）
      *
@@ -384,7 +487,7 @@ interface Tool {
      *
      * 注意：如果 execute 返回 ToolResult 带有 sideEffects，会覆盖此静态声明
      */
-    sideEffects?: SideEffect$1[];
+    sideEffects?: SideEffect[];
     /**
      * 结果类型（用于前端渲染）
      *
@@ -467,11 +570,14 @@ declare function tools(ts: Tool[]): ToolPlugin;
  * ]
  * ```
  */
-type ToolConfigItem = ToolPlugin | Promise<ToolPlugin>;
+type ToolConfigItem = Tool | ToolPlugin | Promise<Tool | ToolPlugin>;
 /**
  * 解析工具配置，统一转换为 Tool[]
  *
- * 所有工具都必须是 ToolPlugin 形式（Vite 插件风格）
+ * 支持三种形式：
+ * - Tool: 单个工具（直接使用）
+ * - ToolPlugin: 工具插件（展开 .tools 数组）
+ * - Promise<Tool | ToolPlugin>: 异步工具/插件
  */
 declare function resolveTools(items: ToolConfigItem[]): Promise<Tool[]>;
 /** 工具定义（OpenAI 格式，内部使用） */
@@ -480,18 +586,7 @@ interface ToolDefinition {
     function: {
         name: string;
         description: string;
-        parameters: {
-            type: 'object';
-            properties: Record<string, {
-                type: string;
-                description: string;
-                enum?: string[];
-                items?: {
-                    type: string;
-                };
-            }>;
-            required: string[];
-        };
+        parameters: JsonSchemaObject;
     };
 }
 /** 聊天消息（内部格式） */
@@ -525,444 +620,6 @@ interface ResponsesApiTool {
     sources?: string[];
 }
 
-/**
- * AI Chat 事件系统
- *
- * 模块化的事件类型定义，用于 Agent 与前端之间的通信。
- *
- * 设计原则：
- * 1. 每种事件类型有明确的数据结构
- * 2. 事件分组便于管理和扩展
- * 3. 类型安全，避免 unknown
- * 4. 统一的时间追踪（开始/结束/耗时）
- */
-/** 搜索结果项 */
-interface SearchResult {
-    title: string;
-    url: string;
-    snippet: string;
-}
-/** 工具调用状态 */
-type ToolCallStatus = 'pending' | 'running' | 'success' | 'error';
-/** 工具调用信息（用于前端状态管理） */
-interface ToolCallInfo {
-    id: string;
-    name: string;
-    args: Record<string, unknown>;
-    status: ToolCallStatus;
-    result?: string;
-    error?: string;
-    startedAt?: number;
-    duration?: number;
-}
-/** Token 使用统计 */
-interface TokenUsage {
-    promptTokens: number;
-    completionTokens: number;
-    totalTokens: number;
-    /** 思考 token 数（如果有） */
-    reasoningTokens?: number;
-    /** 缓存命中 token 数（如果有） */
-    cachedTokens?: number;
-}
-/** 错误类别 - 参考 AI SDK 设计 */
-type ErrorCategory = 'api' | 'rate_limit' | 'validation' | 'tool' | 'timeout' | 'abort' | 'parse' | 'unknown';
-/** 错误详情 - 结构化错误信息 */
-interface ErrorDetails {
-    /** 错误分类 */
-    category: ErrorCategory;
-    /** 人类可读的错误信息 */
-    message: string;
-    /** 错误代码（如 'RATE_LIMIT', 'NETWORK_ERROR'） */
-    code?: string;
-    /** HTTP 状态码（如果适用） */
-    statusCode?: number;
-    /** HTTP 状态文本 */
-    statusText?: string;
-    /** 是否可重试 */
-    retryable?: boolean;
-    /** 重试等待时间（秒） */
-    retryAfter?: number;
-    /** 原始错误信息（用于调试） */
-    cause?: string;
-    /** 错误发生的上下文（如模型名、工具名） */
-    context?: string;
-}
-/** 思考开始事件 */
-interface ThinkingStartEvent {
-    type: 'thinking_start';
-    data: {
-        /** 开始时间戳（毫秒） */
-        startedAt: number;
-    };
-}
-/** 思考内容增量事件 */
-interface ThinkingDeltaEvent {
-    type: 'thinking_delta';
-    data: {
-        /** 增量内容 */
-        content: string;
-    };
-}
-/** 思考结束事件 */
-interface ThinkingEndEvent {
-    type: 'thinking_end';
-    data: {
-        /** 结束时间戳（毫秒） */
-        endedAt: number;
-        /** 思考耗时（毫秒） */
-        duration: number;
-    };
-}
-/** 思考相关事件联合类型 */
-type ThinkingEvent = ThinkingStartEvent | ThinkingDeltaEvent | ThinkingEndEvent;
-/** 搜索开始事件 */
-interface SearchStartEvent {
-    type: 'search_start';
-    data: {
-        /** 搜索查询词 */
-        query: string;
-        /** 开始时间戳（毫秒） */
-        startedAt: number;
-    };
-}
-/** 搜索结果事件（成功完成） */
-interface SearchResultEvent {
-    type: 'search_result';
-    data: {
-        /** 搜索结果列表 */
-        results: SearchResult[];
-        /** 结束时间戳（毫秒） */
-        endedAt: number;
-        /** 搜索耗时（毫秒） */
-        duration: number;
-    };
-}
-/** 搜索结束事件（失败或取消） */
-interface SearchEndEvent {
-    type: 'search_end';
-    data: {
-        /** 是否成功 */
-        success: boolean;
-        /** 错误信息（失败时） */
-        error?: string;
-        /** 结束时间戳（毫秒） */
-        endedAt: number;
-        /** 搜索耗时（毫秒） */
-        duration: number;
-    };
-}
-/** 搜索相关事件联合类型 */
-type SearchEvent = SearchStartEvent | SearchResultEvent | SearchEndEvent;
-/** 工具调用开始事件 */
-interface ToolCallStartEvent {
-    type: 'tool_call_start';
-    data: {
-        /** 工具调用 ID */
-        id: string;
-        /** 工具名称 */
-        name: string;
-        /** 工具参数 */
-        args: Record<string, unknown>;
-        /** 开始时间戳（毫秒） */
-        startedAt: number;
-    };
-}
-/** 副作用定义（从 types.ts 复制，避免循环依赖） */
-interface SideEffect {
-    type: string;
-    success: boolean;
-    data?: unknown;
-    message?: string;
-}
-/** 工具调用结果事件 */
-interface ToolCallResultEvent {
-    type: 'tool_call_result';
-    data: {
-        /** 工具调用 ID */
-        id: string;
-        /** 工具名称 */
-        name: string;
-        /** 执行结果 */
-        result: string;
-        /** 是否成功 */
-        success: boolean;
-        /** 错误信息（失败时） */
-        error?: string;
-        /** 结束时间戳（毫秒） */
-        endedAt: number;
-        /** 执行耗时（毫秒） */
-        duration: number;
-        /**
-         * 工具副作用
-         * 前端可根据此字段处理通知、刷新文件列表等
-         */
-        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 模式） */
-interface ToolApprovalRequestEvent {
-    type: 'tool_approval_request';
-    data: {
-        /** 工具调用 ID */
-        id: string;
-        /** 工具名称 */
-        name: string;
-        /** 工具参数 */
-        args: Record<string, unknown>;
-        /** 请求时间戳 */
-        requestedAt: number;
-    };
-}
-/** 工具相关事件联合类型 */
-type ToolEvent = ToolCallStartEvent | ToolCallResultEvent | ToolApprovalRequestEvent | ToolCallOutputEvent;
-/** 文本增量事件 */
-interface TextDeltaEvent {
-    type: 'text_delta';
-    data: {
-        /** 增量文本 */
-        content: string;
-    };
-}
-/** 文本相关事件联合类型 */
-type TextEvent = TextDeltaEvent;
-/** 图片事件 */
-interface ImageEvent {
-    type: 'image';
-    data: {
-        /** 图片路径 */
-        path?: string;
-        /** Base64 编码 */
-        base64?: string;
-        /** MIME 类型 */
-        mimeType?: string;
-    };
-}
-/** 视频事件 */
-interface VideoEvent {
-    type: 'video';
-    data: {
-        /** 视频路径 */
-        path: string;
-    };
-}
-/** 媒体相关事件联合类型 */
-type MediaEvent = ImageEvent | VideoEvent;
-/** 流开始事件 */
-interface StreamStartEvent {
-    type: 'stream_start';
-    data: {
-        /** 请求 ID */
-        requestId?: string;
-        /** 使用的模型 */
-        model: string;
-        /** 开始时间戳 */
-        startedAt: number;
-    };
-}
-/** 完成事件 */
-interface DoneEvent {
-    type: 'done';
-    data: {
-        /** 完整的最终文本 */
-        text: string;
-        /** Token 使用统计 */
-        usage?: TokenUsage;
-        /** 总耗时（毫秒） */
-        duration?: number;
-    };
-}
-/** 错误事件 - 结构化错误信息 */
-interface ErrorEvent {
-    type: 'error';
-    data: ErrorDetails;
-}
-/** 中止事件 - 用户主动取消 */
-interface AbortEvent {
-    type: 'abort';
-    data: {
-        /** 中止原因 */
-        reason?: string;
-        /** 中止时间戳 */
-        abortedAt: number;
-    };
-}
-/** 状态相关事件联合类型 */
-type StatusEvent = StreamStartEvent | DoneEvent | ErrorEvent | AbortEvent;
-/** 步骤开始事件 */
-interface StepStartEvent {
-    type: 'step_start';
-    data: {
-        /** 步骤编号（从 1 开始） */
-        stepNumber: number;
-        /** 步骤描述（可选） */
-        description?: string;
-        /** 开始时间戳 */
-        startedAt: number;
-    };
-}
-/** 步骤结束事件 */
-interface StepEndEvent {
-    type: 'step_end';
-    data: {
-        /** 步骤编号 */
-        stepNumber: number;
-        /** 结束时间戳 */
-        endedAt: number;
-        /** 耗时（毫秒） */
-        duration: number;
-    };
-}
-/** 步骤相关事件联合类型 */
-type StepEvent = StepStartEvent | StepEndEvent;
-/** 所有事件类型 */
-type ChatEvent = ThinkingEvent | SearchEvent | ToolEvent | TextEvent | MediaEvent | StatusEvent | StepEvent;
-/** 事件类型字符串 */
-type ChatEventType = ChatEvent['type'];
-/**
- * 创建思考开始事件
- */
-declare function createThinkingStart(): ThinkingStartEvent;
-/**
- * 创建思考增量事件
- */
-declare function createThinkingDelta(content: string): ThinkingDeltaEvent;
-/**
- * 创建思考结束事件
- */
-declare function createThinkingEnd(startedAt: number): ThinkingEndEvent;
-/**
- * 创建搜索开始事件
- */
-declare function createSearchStart(query: string): SearchStartEvent;
-/**
- * 创建搜索结果事件（成功）
- */
-declare function createSearchResult(results: SearchResult[], startedAt: number): SearchResultEvent;
-/**
- * 创建搜索结束事件（失败或取消）
- */
-declare function createSearchEnd(success: boolean, startedAt: number, error?: string): SearchEndEvent;
-/**
- * 创建工具调用开始事件
- */
-declare function createToolCallStart(id: string, name: string, args: Record<string, unknown>): ToolCallStartEvent;
-/**
- * 创建工具调用结果事件
- */
-declare function createToolCallResult(id: string, name: string, result: string, success: boolean, startedAt: number, error?: string, sideEffects?: SideEffect[], resultType?: string): ToolCallResultEvent;
-/**
- * 创建文本增量事件
- */
-declare function createTextDelta(content: string): TextDeltaEvent;
-/**
- * 创建流开始事件
- */
-declare function createStreamStart(model: string, requestId?: string): StreamStartEvent;
-/**
- * 创建完成事件
- */
-declare function createDone(text: string, usage?: TokenUsage, duration?: number): DoneEvent;
-/**
- * 创建错误事件（完整版）
- */
-declare function createError(details: ErrorDetails): ErrorEvent;
-/**
- * 创建 API 错误事件
- */
-declare function createApiError(message: string, options?: {
-    code?: string;
-    statusCode?: number;
-    statusText?: string;
-    retryable?: boolean;
-    retryAfter?: number;
-    cause?: string;
-    context?: string;
-}): ErrorEvent;
-/**
- * 创建速率限制错误事件
- */
-declare function createRateLimitError(message: string, retryAfter?: number, context?: string): ErrorEvent;
-/**
- * 创建工具错误事件
- */
-declare function createToolError(message: string, toolName: string, cause?: string): ErrorEvent;
-/**
- * 创建超时错误事件
- */
-declare function createTimeoutError(message: string, context?: string): ErrorEvent;
-/**
- * 创建解析错误事件
- */
-declare function createParseError(message: string, cause?: string): ErrorEvent;
-/**
- * 创建中止事件
- */
-declare function createAbort(reason?: string): AbortEvent;
-/**
- * 创建步骤开始事件
- */
-declare function createStepStart(stepNumber: number, description?: string): StepStartEvent;
-/**
- * 创建步骤结束事件
- */
-declare function createStepEnd(stepNumber: number, startedAt: number): StepEndEvent;
-/**
- * 创建图片事件
- */
-declare function createImage(options: {
-    path?: string;
-    base64?: string;
-    mimeType?: string;
-}): ImageEvent;
-/**
- * 创建视频事件
- */
-declare function createVideo(path: string): VideoEvent;
-/** 检查是否为思考事件 */
-declare function isThinkingEvent(event: ChatEvent): event is ThinkingEvent;
-/** 检查是否为搜索事件 */
-declare function isSearchEvent(event: ChatEvent): event is SearchEvent;
-/** 检查是否为工具事件 */
-declare function isToolEvent(event: ChatEvent): event is ToolEvent;
-/** 检查是否为文本事件 */
-declare function isTextEvent(event: ChatEvent): event is TextEvent;
-/** 检查是否为媒体事件 */
-declare function isMediaEvent(event: ChatEvent): event is MediaEvent;
-/** 检查是否为状态事件 */
-declare function isStatusEvent(event: ChatEvent): event is StatusEvent;
-/** 检查是否为错误事件 */
-declare function isErrorEvent(event: ChatEvent): event is ErrorEvent;
-/** 检查是否为中止事件 */
-declare function isAbortEvent(event: ChatEvent): event is AbortEvent;
-/** 检查是否为步骤事件 */
-declare function isStepEvent(event: ChatEvent): event is StepEvent;
-/** 检查错误是否可重试 */
-declare function isRetryableError(event: ChatEvent): boolean;
-
 /** 运行时配置（API Keys 和 URLs） */
 interface RuntimeConfig {
     arkApiKey: string;
@@ -995,6 +652,10 @@ declare class HybridAgent {
     private tools;
     /** 工具配置（用于异步初始化） */
     private toolConfig;
+    /** MCP 客户端管理器 */
+    private mcpManager;
+    /** MCP 服务器配置 */
+    private mcpConfigs;
     constructor(config: AgentConfig, toolExecutor?: ToolExecutor$1);
     /** 异步初始化工具（在第一次 chat 前调用） */
     private asyncInit;
@@ -1040,6 +701,14 @@ declare class HybridAgent {
     getConfig(): RuntimeConfig;
     /** 获取所有支持的模型 */
     getSupportedModels(): ModelOption[];
+    /** 获取 MCP 连接状态 */
+    getMcpConnections(): McpConnectionInfo[];
+    /**
+     * 销毁 Agent（优雅关闭所有 MCP 连接）
+     *
+     * 桌面客户端退出时应调用此方法。
+     */
+    destroy(): Promise<void>;
 }
 
 /**
@@ -1051,22 +720,10 @@ declare class HybridAgent {
  * 3. 所有 Adapter 返回标准化的 StreamChunk
  */
 
-/** 简化的工具定义（供 Adapter 使用） */
 interface SimpleToolDefinition {
     name: string;
     description: string;
-    parameters: {
-        type: 'object';
-        properties: Record<string, {
-            type: string;
-            description: string;
-            enum?: string[];
-            items?: {
-                type: string;
-            };
-        }>;
-        required: string[];
-    };
+    parameters: JsonSchemaObject;
 }
 /** 流式响应块类型 */
 type StreamChunkType = 'text' | 'thinking' | 'thinking_done' | 'tool_call' | 'search_result' | 'done' | 'error';
@@ -1085,6 +742,14 @@ interface SearchResultItem {
     snippet: string;
 }
 /** 流式响应块 - 所有 Adapter 必须返回此格式 */
+/** Token 使用统计 */
+interface StreamTokenUsage {
+    promptTokens?: number;
+    completionTokens?: number;
+    totalTokens?: number;
+    reasoningTokens?: number;
+    cachedTokens?: number;
+}
 interface StreamChunk {
     type: StreamChunkType;
     text?: string;
@@ -1092,6 +757,8 @@ interface StreamChunk {
     toolCall?: ToolCallRequest;
     searchResults?: SearchResultItem[];
     finishReason?: 'stop' | 'tool_calls' | 'length' | 'error';
+    /** Token 使用统计（done 事件携带） */
+    usage?: StreamTokenUsage;
     error?: string;
 }
 /** 标准化消息 - Orchestrator 内部使用 */
@@ -1206,6 +873,15 @@ interface OrchestratorConfig {
      * 返回 true 表示批准执行，false 表示跳过
      */
     onToolApprovalRequest?: ToolApprovalCallback;
+    /**
+     * 客户端工具名称集合（透传模式）
+     *
+     * 这些工具不在服务端执行，而是：
+     * 1. 发送 tool_call_request 事件给客户端
+     * 2. 结束本轮对话
+     * 3. 客户端执行后，发新请求继续对话
+     */
+    clientToolNames?: Set<string>;
 }
 /** Orchestrator 上下文 */
 interface OrchestratorContext {
@@ -1219,6 +895,12 @@ interface OrchestratorContext {
     signal: AbortSignal;
     /** 图片列表 */
     images?: string[];
+    /**
+     * 客户端工具名称集合（透传模式）
+     *
+     * 这些工具不在服务端执行，而是发送 tool_call_request 事件给客户端
+     */
+    clientToolNames?: Set<string>;
 }
 /** Orchestrator 选项 */
 interface OrchestratorOptions {
@@ -1372,6 +1054,14 @@ interface RawSearchResult {
 /**
  * Protocol 原始事件
  */
+/** Token 使用统计（Protocol 层） */
+interface RawTokenUsage {
+    promptTokens?: number;
+    completionTokens?: number;
+    totalTokens?: number;
+    reasoningTokens?: number;
+    cachedTokens?: number;
+}
 interface RawEvent {
     type: RawEventType;
     delta?: string;
@@ -1379,6 +1069,8 @@ interface RawEvent {
     searchQuery?: string;
     searchResults?: RawSearchResult[];
     finishReason?: 'stop' | 'tool_calls' | 'length' | 'error';
+    /** Token 使用统计（done 事件携带） */
+    usage?: RawTokenUsage;
     error?: string;
 }
 /**
@@ -1396,24 +1088,11 @@ interface ProtocolMessage {
     /** 工具名称（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[];
-    };
+    parameters: JsonSchemaObject;
 }
 /**
  * Protocol 请求选项
@@ -1727,53 +1406,26 @@ declare function createDefaultToolExecutor(defaultCwd?: string): ToolExecutor$1;
 /**
  * 调试日志工具
  *
- * 用法：
- * - 设置环境变量 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;
-};
+ * 通过 DebugLogger.enable(true) 全局开启，
+ * 通过 DebugLogger.setLogFile(path) 同时写入 JSONL 文件，
+ * 各模块通过 DebugLogger.module('Name') 创建带前缀的 logger。
+ */
+declare class DebugLogger {
+    private prefix;
+    private constructor();
+    /** 全局启停调试日志 */
+    static enable(value: boolean): void;
+    /** 查询是否已启用 */
+    static isEnabled(): boolean;
+    /** 设置日志文件路径（JSONL 格式，追加写入） */
+    static setLogFile(filePath: string): void;
+    /** 创建模块专用 logger */
+    static module(name: string): DebugLogger;
+    debug(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+    private writeToFile;
+}
 
-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 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, createAbort, createAnthropicProtocol, createApiError, createArkProtocol, createDeepSeekProtocol, createDefaultToolExecutor, 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, getDefaultProvider, getModelByModelId, getModelEntry, getModelFamily, getModelProtocol, getModelSearchStrategy, getModelsByFamily, getModelsByProtocol, getVisibleModels, isAbortEvent, isErrorEvent, isMediaEvent, isModelForProvider, isRetryableError, isSearchEvent, isStatusEvent, isStepEvent, isTextEvent, isThinkingEvent, isToolEvent, modelSupportsNativeSearch, modelSupportsThinking, resolveTools, routeModelToProvider, routeModelWithDetails, tool, tools };
+export { type AdapterConfig, type AgentConfig, AnthropicProtocol, ArkProtocol, type AutoRunConfig$1 as AutoRunConfig, type AutoRunMode, CLAUDE_FAMILY, ChatEvent, type ChatMessage, type ChatMode, type ChatOptions, ChatOrchestrator, DEEPSEEK_FAMILY, DEFAULT_MODEL, DOUBAO_FAMILY, DebugLogger, DeepSeekProtocol, GEMINI_FAMILY, GPT_FAMILY, GeminiProtocol, HybridAgent, MODELS, MODEL_FAMILIES, MODEL_REGISTRY, type McpConnectionInfo, type McpConnectionStatus, type McpServerConfig, 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 SearchResultItem, type SearchStrategy, type SideEffect, type SimpleToolDefinition, type StandardMessage, type StreamChunk, type StreamChunkType, type StreamOnceOptions, type StreamOptions, type ThinkingFormat, type ThinkingMode, type Tool, type ToolCallFormat, type ToolCallRequest, type ToolConfigItem, type ToolContext, type ToolDefinition, type ToolExecutor$1 as ToolExecutor, type ToolPlugin, type ToolResult, UnifiedAdapter, type UnifiedAdapterConfig, type UserToolDefinition, createAnthropicProtocol, createArkProtocol, createDeepSeekProtocol, createDefaultToolExecutor, createGeminiProtocol, createOpenAIProtocol, createOrchestrator, createQwenProtocol, createUnifiedAdapter, getDefaultProvider, getModelByModelId, getModelEntry, getModelFamily, getModelProtocol, getModelSearchStrategy, getModelsByFamily, getModelsByProtocol, getVisibleModels, isModelForProvider, modelSupportsNativeSearch, modelSupportsThinking, resolveTools, routeModelToProvider, routeModelWithDetails, tool, tools };