@huyooo/ai-chat-core 0.1.6 → 0.1.8

package/dist/index.d.cts

@@ -1,22 +1,115 @@
+/**
+ * 模型路由模块
+ *
+ * 根据模型名称将请求路由到对应的 Provider
+ *
+ * 设计原则：
+ * 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;
+}
+/** 路由结果 */
+interface RouteResult {
+    /** 匹配的 Provider */
+    provider: ProviderType;
+    /** 匹配的规则（如果有） */
+    matchedRule?: RouteRule;
+    /** 是否使用了默认路由 */
+    isDefault: boolean;
+}
+/**
+ * 将模型路由到对应的 Provider
+ *
+ * @param model - 模型名称
+ * @returns 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 是否匹配
+ */
+declare function isModelForProvider(model: string, provider: ProviderType): boolean;
+
 /**
  * AI Chat Core 类型定义
+ *
+ * 注意：事件类型已迁移到 events.ts
  */
 /** 对话模式 */
 type ChatMode = 'agent' | 'plan' | 'ask';
-/** 可用模型 */
-type ModelProvider = 'doubao' | 'deepseek' | 'qwen' | 'gemini' | 'openrouter';
-/** 模型配置 */
-interface ModelConfig {
-    provider: ModelProvider;
-    model: string;
+
+/**
+ * 简化的模型配置
+ *
+ * - modelId: 发送给 API 的模型 ID
+ * - displayName: 前端显示名称
+ * - group: 分组名称（由后端决定，前端只负责渲染）
+ */
+interface ModelOption {
+    /** 模型 ID（发送给 API） */
+    modelId: string;
+    /** 显示名称 */
     displayName: string;
-    supportsTools: boolean;
-    supportsWebSearch: boolean;
-    /** 支持的深度思考模式 */
-    supportedThinkingModes: ThinkingMode[];
+    /** 分组名称（由后端决定，前端只负责渲染，必填） */
+    group: string;
+    /** 是否来自 OpenRouter（保留用于兼容，后续可能移除） */
+    isOpenRouter?: boolean;
+    /** 提供商名称（保留用于兼容，后续可能移除） */
+    provider?: string;
 }
-/** 预定义模型列表 */
-declare const AVAILABLE_MODELS: ModelConfig[];
+/**
+ * 预定义模型列表（从 constants.ts 映射）
+ *
+ * 分组信息由后端决定，前端只负责渲染
+ */
+declare const MODELS: ModelOption[];
+/** 获取原生模型 */
+declare function getNativeModels(): ModelOption[];
+/** 获取 OpenRouter 模型 */
+declare function getOpenRouterModels(): ModelOption[];
+/** 根据 modelId 获取模型 */
+declare function getModelByModelId(modelId: string): ModelOption | undefined;
+/** 工具批准回调函数 */
+type ToolApprovalCallback$1 = (toolCall: {
+    id: string;
+    name: string;
+    args: Record<string, unknown>;
+}) => Promise<boolean>;
 /** Agent 配置 */
 interface AgentConfig {
     /** 豆包/火山引擎 API Key (用于豆包和 DeepSeek) */
@@ -31,13 +124,62 @@ interface AgentConfig {
     openrouterApiKey?: string;
     /** OpenRouter API URL */
     openrouterApiUrl?: string;
-    /** Gemini API Key (用于图片/视频) */
+    /** Gemini API Key (用于图片/视频，注意：中国大陆无法直接访问) */
     geminiApiKey: string;
-    /** 工作目录 */
-    workingDir?: string;
+    /** 当前工作目录（Current Working Directory） */
+    cwd?: string;
+    /**
+     * 工具列表（Vite 插件风格）
+     *
+     * 支持多种形式：
+     * - 单个工具：getCwdTool
+     * - 工具插件：searchPlugin({ dataDir, workspace })
+     * - Promise：await asyncPlugin()
+     *
+     * @example
+     * ```typescript
+     * tools: [
+     *   getCwdTool,
+     *   executeCommandTool,
+     *   searchPlugin({ dataDir: '/path', workspace: '/project' }),
+     * ]
+     * ```
+     */
+    tools?: ToolConfigItem[];
+    /**
+     * plan 模式的系统提示词（可选，有默认值）
+     * 用于指导 AI 如何制定执行计划
+     */
+    planPrompt?: string;
+    /**
+     * 工具批准回调（manual 模式使用）
+     * 返回 true 表示批准执行，false 表示跳过
+     */
+    onToolApprovalRequest?: ToolApprovalCallback$1;
+    /**
+     * 动态获取自动运行配置回调
+     * 每次检查工具批准时调用，获取最新配置
+     */
+    getAutoRunConfig?: () => Promise<AutoRunConfig$1 | undefined>;
 }
 /** 深度思考模式 */
 type ThinkingMode = 'enabled' | 'disabled';
+/** 自动运行模式 */
+type AutoRunMode = 'run-everything' | 'manual';
+/** 自动运行配置 */
+interface AutoRunConfig$1 {
+    /**
+     * 自动运行模式
+     * - 'run-everything': 运行所有内容（自动执行）
+     * - 'manual': 手动批准（每次执行前询问）
+     */
+    mode?: AutoRunMode;
+}
+/** 聊天消息格式（用于传递历史） */
+interface ChatHistoryMessage {
+    role: 'user' | 'assistant' | 'system' | 'tool';
+    content: string;
+}
 /** 聊天配置（每次聊天可变的选项） */
 interface ChatOptions {
     /** 对话模式 */
@@ -45,7 +187,7 @@ interface ChatOptions {
     /** 使用的模型 */
     model?: string;
     /** 模型提供商 */
-    provider?: ModelProvider;
+    provider?: ProviderType;
     /** 是否启用联网搜索 */
     enableWebSearch?: boolean;
     /**
@@ -54,92 +196,181 @@ interface ChatOptions {
      * - 'disabled': 强制关闭深度思考
      */
     thinkingMode?: ThinkingMode;
-    /** 深度思考预算（token 数，仅 enabled 时有效） */
-    thinkingBudget?: number;
-}
-/** 聊天进度事件类型 */
-type ChatProgressType = 'thinking' | 'search_start' | 'search_result' | 'tool_call' | 'tool_result' | 'text' | 'text_delta' | 'image' | 'video' | 'done' | 'error';
-/** 聊天进度事件 */
-interface ChatProgress {
-    type: ChatProgressType;
-    data: unknown;
-}
-/** 工具调用进度 */
-interface ToolCallProgress {
-    type: 'tool_call';
-    data: {
-        name: string;
-        args: Record<string, unknown>;
-    };
-}
-/** 工具结果进度 */
-interface ToolResultProgress {
-    type: 'tool_result';
-    data: {
-        name: string;
-        result: string;
-    };
-}
-/** 搜索开始进度 */
-interface SearchStartProgress {
-    type: 'search_start';
-    data: {
-        query: string;
-    };
-}
-/** 搜索结果进度 */
-interface SearchResultProgress {
-    type: 'search_result';
-    data: {
-        results: Array<{
-            title: string;
-            url: string;
-            snippet: string;
-        }>;
-    };
+    /** 自动运行配置 */
+    autoRunConfig?: AutoRunConfig$1;
+    /** 对话历史（从数据库加载，无状态架构） */
+    history?: ChatHistoryMessage[];
 }
-/** 文本进度 */
-interface TextProgress {
-    type: 'text';
-    data: string;
+/**
+ * 副作用定义（参考 REST API 规范）
+ *
+ * @example
+ * // 通知
+ * { type: 'notification', success: true, message: '图片生成完成' }
+ *
+ * // 文件系统变更
+ * { type: 'filesystem', success: true, data: { paths: ['/path/to/file'] } }
+ *
+ * // 失败
+ * { type: 'notification', success: false, message: 'API 超时' }
+ */
+interface SideEffect$1 {
+    /** 副作用类型 */
+    type: string;
+    /** 是否成功 */
+    success: boolean;
+    /** 附加数据 */
+    data?: unknown;
+    /** 消息（成功时为提示，失败时为错误信息） */
+    message?: string;
 }
-/** 流式文本增量 */
-interface TextDeltaProgress {
-    type: 'text_delta';
-    data: string;
+/**
+ * 工具执行结果（支持动态副作用）
+ *
+ * 工具可以返回此类型来动态声明副作用
+ */
+interface ToolResult {
+    /** 执行结果（字符串） */
+    result: string;
+    /** 动态副作用（覆盖静态声明） */
+    sideEffects?: SideEffect$1[];
 }
-/** 思考进度 */
-interface ThinkingProgress {
-    type: 'thinking';
-    data: {
-        content: string;
-        isComplete?: boolean;
-    };
+/** 工具执行上下文 */
+interface ToolContext {
+    /** 当前工作目录（Current Working Directory） */
+    cwd: string;
+    /** Gemini 客户端（供多模态工具使用） */
+    geminiClient?: unknown;
+    /** 执行 Shell 命令（内置方法） */
+    executeCommand: (command: string, cwd?: string) => Promise<{
+        success: boolean;
+        output?: string;
+        error?: string;
+    }>;
+    /** 中断信号（用于取消长时间操作） */
+    signal?: AbortSignal;
 }
-/** 图片进度 */
-interface ImageProgress {
-    type: 'image';
-    data: {
-        path?: string;
-        base64?: string;
+/**
+ * 工具接口（用户可实现此接口创建自定义工具）
+ *
+ * 示例：
+ * ```typescript
+ * const myTool: Tool = {
+ *   name: 'my_tool',
+ *   description: '我的自定义工具',
+ *   parameters: { type: 'object', properties: {}, required: [] },
+ *   sideEffects: ['filesystem'], // 声明副作用
+ *   execute: async (args, ctx) => '执行结果'
+ * };
+ * ```
+ */
+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[];
     };
+    /**
+     * 静态副作用声明（可选）
+     *
+     * 用于通知前端该工具执行后可能产生的副作用
+     *
+     * @example
+     * sideEffects: [{ type: 'notification', message: '图片生成完成', level: 'success' }]
+     *
+     * 注意：如果 execute 返回 ToolResult 带有 sideEffects，会覆盖此静态声明
+     */
+    sideEffects?: SideEffect$1[];
+    /**
+     * 执行函数
+     *
+     * 返回值：
+     * - string: 简单返回结果，使用静态 sideEffects
+     * - ToolResult: 带动态副作用的结果，覆盖静态 sideEffects
+     */
+    execute: (args: Record<string, unknown>, context: ToolContext) => Promise<string | ToolResult>;
 }
-/** 工具执行器接口（可由使用方实现） */
+/** 工具执行器接口（可由使用方实现，用于自定义命令执行环境） */
 interface ToolExecutor$1 {
     /** 执行 Shell 命令 */
-    executeCommand(command: string, workingDir?: string): Promise<{
+    executeCommand(command: string, cwd?: string, signal?: AbortSignal): Promise<{
         success: boolean;
         output?: string;
         error?: string;
     }>;
-    /** 读取文件 */
-    readFile?(path: string): Promise<Buffer>;
-    /** 写入文件 */
-    writeFile?(path: string, data: Buffer): Promise<void>;
-    /** 读取目录 */
-    readDirectory?(path: string): Promise<string[]>;
-}
-/** 工具定义（OpenAI 格式） */
+}
+/**
+ * 工具插件实例
+ *
+ * 由 createXxxPlugin() 返回，可直接在 tools 数组中展开使用
+ */
+interface ToolPlugin {
+    /** 插件提供的工具数组 */
+    tools: Tool[];
+    /** 插件控制方法（可选，由各插件自定义） */
+    [key: string]: unknown;
+}
+/**
+ * 创建单个工具插件（辅助函数）
+ *
+ * @example
+ * ```typescript
+ * export function getCwdTool(): ToolPlugin {
+ *   return tool({
+ *     name: 'get_cwd',
+ *     description: '...',
+ *     parameters: { ... },
+ *     execute: async (args, context) => { ... }
+ *   });
+ * }
+ * ```
+ */
+declare function tool(t: Tool): ToolPlugin;
+/**
+ * 创建多个工具插件（辅助函数）
+ *
+ * @example
+ * ```typescript
+ * export function myPlugin(): ToolPlugin {
+ *   return tools([
+ *     { name: 'tool1', ... },
+ *     { name: 'tool2', ... },
+ *   ]);
+ * }
+ * ```
+ */
+declare function tools(ts: Tool[]): ToolPlugin;
+/**
+ * 工具配置项（Vite 插件风格，只支持插件形式）
+ *
+ * @example
+ * ```typescript
+ * tools: [
+ *   getCwdTool(),                          // 工具插件（函数调用）
+ *   searchPlugin({ dataDir, workspace }), // 异步插件（返回 Promise<ToolPlugin>）
+ * ]
+ * ```
+ */
+type ToolConfigItem = ToolPlugin | Promise<ToolPlugin>;
+/**
+ * 解析工具配置，统一转换为 Tool[]
+ *
+ * 所有工具都必须是 ToolPlugin 形式（Vite 插件风格）
+ */
+declare function resolveTools(items: ToolConfigItem[]): Promise<Tool[]>;
+/** 工具定义（OpenAI 格式，内部使用） */
 interface ToolDefinition {
     type: 'function';
     function: {
@@ -161,11 +392,11 @@ interface ToolDefinition {
 }
 /** 聊天消息（内部格式） */
 interface ChatMessage {
-    /** 消息 ID（豆包 Responses API 需要） */
+    /** 消息 ID */
     id?: string;
     role: 'system' | 'user' | 'assistant' | 'tool';
     content: string;
-    /** 深度思考内容（DeepSeek 思考模式下需要回传） */
+    /** 深度思考内容 */
     reasoning_content?: string;
     tool_call_id?: string;
     tool_calls?: Array<{
@@ -177,320 +408,1027 @@ interface ChatMessage {
         };
     }>;
 }
-/** DeepSeek Responses API 消息格式 */
-interface DeepSeekMessage {
-    role: 'user' | 'assistant';
-    content: Array<{
-        type: 'input_text' | 'output_text';
-        text: string;
-    }>;
-}
-/** DeepSeek / 火山引擎 Responses API 工具定义 */
-interface DeepSeekTool {
+/** 火山引擎 Responses API 工具定义 */
+interface ResponsesApiTool {
     type: 'function' | 'web_search';
-    function?: {
-        name: string;
-        description: string;
-        parameters: Record<string, unknown>;
-    };
+    name?: string;
+    description?: string;
+    parameters?: Record<string, unknown>;
     max_keyword?: number;
     limit?: number;
     sources?: string[];
 }
 
 /**
- * Provider 基础接口定义
+ * AI Chat 事件系统
  *
- * 所有 AI 模型提供商都实现这个统一接口
+ * 模块化的事件类型定义，用于 Agent 与前端之间的通信。
+ *
+ * 设计原则：
+ * 1. 每种事件类型有明确的数据结构
+ * 2. 事件分组便于管理和扩展
+ * 3. 类型安全，避免 unknown
+ * 4. 统一的时间追踪（开始/结束/耗时）
  */
-
-/** 工具执行器类型 */
-type ToolExecutor = (name: string, args: Record<string, unknown>) => Promise<string>;
-/** 聊天上下文 */
-interface ChatContext {
-    /** 对话历史 */
-    history: ChatMessage[];
-    /** 系统提示词 */
-    systemPrompt: string;
-    /** 工作目录 */
-    workingDir: string;
-    /** 工具执行器 */
-    executeTool: ToolExecutor;
-    /** 取消信号 */
-    signal: AbortSignal;
+/** 搜索结果项 */
+interface SearchResult {
+    title: string;
+    url: string;
+    snippet: string;
 }
-/** 模型能力定义 */
-interface ModelCapabilities {
-    supportsTools: boolean;
-    supportsWebSearch: boolean;
-    supportsThinking: boolean;
-    supportedThinkingModes: Array<'enabled' | 'disabled'>;
+/** 工具调用状态 */
+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[];
+    };
+}
+/** 工具执行批准请求事件（manual 模式） */
+interface ToolApprovalRequestEvent {
+    type: 'tool_approval_request';
+    data: {
+        /** 工具调用 ID */
+        id: string;
+        /** 工具名称 */
+        name: string;
+        /** 工具参数 */
+        args: Record<string, unknown>;
+        /** 请求时间戳 */
+        requestedAt: number;
+    };
+}
+/** 工具相关事件联合类型 */
+type ToolEvent = ToolCallStartEvent | ToolCallResultEvent | ToolApprovalRequestEvent;
+/** 文本增量事件 */
+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[]): 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;
+    arkApiUrl: string;
+    qwenApiKey: string;
+    qwenApiUrl: string;
+    openrouterApiKey: string;
+    openrouterApiUrl: string;
+    geminiApiKey: string;
+    cwd: string;
+    planPrompt: string;
 }
 /**
- * ChatProvider 接口
+ * 混合 Agent 类
  *
- * 每个 AI 模型提供商都需要实现这个接口
+ * 职责：
+ * 1. 管理多个 ProviderAdapter
+ * 2. 路由请求到正确的 Adapter
+ * 3. 使用 ChatOrchestrator 统一处理工具调用
+ * 4. 管理对话历史和工具注册
  */
-interface ChatProvider {
-    /** 提供商名称 */
-    readonly name: string;
-    /** 支持的模型列表 */
-    readonly supportedModels: string[];
+declare class HybridAgent {
+    private config;
+    private adapters;
+    private orchestrator;
+    private geminiClient;
+    private toolExecutor;
+    private abortController;
+    /** 已注册的工具 */
+    private tools;
+    /** 工具配置（用于异步初始化） */
+    private toolConfig;
+    constructor(config: AgentConfig, toolExecutor?: ToolExecutor$1);
+    /** 异步初始化工具（在第一次 chat 前调用） */
+    private asyncInit;
+    /** 初始化所有 Adapter */
+    private initializeAdapters;
     /**
-     * 检查是否支持指定模型
+     * 判断模型提供商
      */
-    supportsModel(model: string): boolean;
+    private getModelProvider;
+    /** 获取 Adapter */
+    private getAdapter;
     /**
-     * 获取模型能力
+     * 调试：获取模型路由信息
      */
-    getModelCapabilities(model: string): ModelCapabilities;
+    getModelRouteInfo(model: string): RouteResult & {
+        available: boolean;
+    };
+    /** 构建系统提示词 */
+    private buildSystemPrompt;
+    /** 获取默认深度思考模式 */
+    private getDefaultThinkingMode;
+    /** 创建工具执行上下文 */
+    private createToolContext;
+    /** 执行工具 */
+    private executeTool;
+    /** 获取工具定义列表 */
+    private getToolDefinitions;
     /**
-     * 执行聊天
+     * 聊天入口
      *
-     * @param message 用户消息
-     * @param model 模型名称
-     * @param options 聊天选项
-     * @param context 聊天上下文
-     * @returns 异步生成器，产出聊天进度事件
+     * 使用 ChatOrchestrator 统一处理所有 Provider 的工具调用循环
      */
-    chat(message: string, model: string, options: ChatOptions, context: ChatContext): AsyncGenerator<ChatProgress>;
+    chat(message: string, options?: ChatOptions, images?: string[]): AsyncGenerator<ChatEvent>;
+    /** 中断当前请求 */
+    abort(): void;
+    /** 设置当前工作目录 */
+    setCwd(dir: string): void;
+    /** 获取当前配置 */
+    getConfig(): RuntimeConfig;
+    /** 获取所有支持的模型 */
+    getSupportedModels(): ModelOption[];
 }
 
 /**
- * ARK Provider (火山引擎)
- *
- * 统一使用 Responses API，支持：
- * - 函数调用 Function Calling
- * - 联网搜索 Web Search
- * - 深度思考 Thinking
- * - 上下文缓存 Caching
+ * Provider 统一类型定义
  *
- * 支持模型：豆包 (doubao-*), DeepSeek (deepseek-*)
+ * 核心设计原则：
+ * 1. Adapter 只负责 API 格式转换，不处理业务逻辑
+ * 2. Orchestrator 统一处理工具调用循环、消息历史、事件发射
+ * 3. 所有 Adapter 返回标准化的 StreamChunk
  */
 
-/** ARK Provider 配置 */
-interface ArkProviderConfig {
+/** 简化的工具定义（供 Adapter 使用） */
+interface SimpleToolDefinition {
+    name: string;
+    description: string;
+    parameters: {
+        type: 'object';
+        properties: Record<string, {
+            type: string;
+            description: string;
+            enum?: string[];
+            items?: {
+                type: string;
+            };
+        }>;
+        required: string[];
+    };
+}
+/** 流式响应块类型 */
+type StreamChunkType = 'text' | 'thinking' | 'thinking_done' | 'tool_call' | 'search_result' | 'done' | 'error';
+/** 工具调用请求 */
+interface ToolCallRequest {
+    id: string;
+    name: string;
+    arguments: string;
+}
+/** 搜索结果项 */
+interface SearchResultItem {
+    title: string;
+    url: string;
+    snippet: string;
+}
+/** 流式响应块 - 所有 Adapter 必须返回此格式 */
+interface StreamChunk {
+    type: StreamChunkType;
+    text?: string;
+    thinking?: string;
+    toolCall?: ToolCallRequest;
+    searchResults?: SearchResultItem[];
+    finishReason?: 'stop' | 'tool_calls' | 'length' | 'error';
+    error?: string;
+}
+/** 标准化消息 - Orchestrator 内部使用 */
+interface StandardMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: string;
+    images?: string[];
+    toolCalls?: ToolCallRequest[];
+    toolCallId?: string;
+    toolName?: string;
+}
+/** Adapter 配置 */
+interface AdapterConfig {
     apiKey: string;
     apiUrl?: string;
-    /** 是否启用上下文缓存 */
-    enableCaching?: boolean;
+}
+/** 单次调用选项 */
+interface StreamOnceOptions {
+    /** 模型 ID */
+    model: string;
+    /** 是否启用思考 */
+    enableThinking?: boolean;
+    /** 是否启用搜索 */
+    enableSearch?: boolean;
+    /** 中断信号 */
+    signal: AbortSignal;
 }
 /**
- * ARK Provider 实现
+ * Provider Adapter 接口
  *
- * 统一使用 Responses API
+ * 职责：
+ * - 将标准消息转换为 API 特定格式
+ * - 调用 API 并返回标准化的 StreamChunk
+ * - 不处理工具执行、消息历史维护
  */
-declare class ArkProvider implements ChatProvider {
-    readonly name = "ark";
+interface ProviderAdapter {
+    /** 适配器名称 */
+    readonly name: string;
+    /** 支持的模型列表 */
     readonly supportedModels: string[];
-    private apiKey;
-    private apiUrl;
-    private enableCaching;
-    constructor(config: ArkProviderConfig);
+    /**
+     * 单次流式调用
+     *
+     * @param messages 标准化消息列表
+     * @param tools 工具定义列表
+     * @param options 调用选项
+     * @returns 标准化的流式响应
+     */
+    streamOnce(messages: StandardMessage[], tools: SimpleToolDefinition[], options: StreamOnceOptions): AsyncGenerator<StreamChunk>;
+    /**
+     * 检查是否支持指定模型
+     */
     supportsModel(model: string): boolean;
-    getModelCapabilities(model: string): ModelCapabilities;
+}
+/**
+ * 工具执行器
+ *
+ * 返回值：
+ * - string: 简单结果，使用工具的静态 sideEffects
+ * - ToolResult: 带动态副作用的结果
+ */
+type ToolExecutor = (name: string, args: Record<string, unknown>, signal?: AbortSignal) => Promise<string | ToolResult>;
+/** 自动运行配置 */
+interface AutoRunConfig {
     /**
-     * 聊天入口 - 统一使用 Responses API
+     * 自动运行模式
+     * - 'run-everything': 运行所有内容（自动执行）
+     * - 'manual': 手动批准（每次执行前询问）
      */
-    chat(message: string, model: string, options: ChatOptions, context: ChatContext): AsyncGenerator<ChatProgress>;
+    mode?: 'run-everything' | 'manual';
+}
+/** 工具批准回调函数 */
+type ToolApprovalCallback = (toolCall: {
+    id: string;
+    name: string;
+    args: Record<string, unknown>;
+}) => Promise<boolean>;
+/** 获取自动运行配置回调 */
+type GetAutoRunConfigCallback = () => Promise<AutoRunConfig | undefined>;
+/** Orchestrator 配置 */
+interface OrchestratorConfig {
+    /** 最大迭代次数 */
+    maxIterations?: number;
+    /** 工具执行器 */
+    executeTool: ToolExecutor;
+    /**
+     * 完整的工具列表（用于获取 sideEffects）
+     * key: 工具名称, value: 工具定义
+     */
+    tools?: Map<string, Tool>;
+    /** 自动运行配置（静态配置，优先使用 getAutoRunConfig） */
+    autoRunConfig?: AutoRunConfig;
+    /**
+     * 动态获取自动运行配置回调
+     * 每次检查工具批准时调用，获取最新配置
+     */
+    getAutoRunConfig?: GetAutoRunConfigCallback;
+    /**
+     * 工具批准回调（manual 模式使用）
+     * 返回 true 表示批准执行，false 表示跳过
+     */
+    onToolApprovalRequest?: ToolApprovalCallback;
+}
+/** Orchestrator 上下文 */
+interface OrchestratorContext {
+    /** 系统提示 */
+    systemPrompt: string;
+    /** 对话历史（会被修改） */
+    history: ChatMessage[];
+    /** 工具定义 */
+    tools: SimpleToolDefinition[];
+    /** 中断信号 */
+    signal: AbortSignal;
+    /** 图片列表 */
+    images?: string[];
+}
+/** Orchestrator 选项 */
+interface OrchestratorOptions {
+    /** 模型 ID */
+    model: string;
+    /** 是否启用思考 */
+    enableThinking?: boolean;
+    /** 是否启用搜索 */
+    enableSearch?: boolean;
+    /** 自动运行配置 */
+    autoRunConfig?: AutoRunConfig;
 }
 
 /**
- * Qwen Provider (通义千问)
+ * Chat Orchestrator
+ *
+ * 统一处理：
+ * 1. 工具调用循环 (while iterations < MAX)
+ * 2. 消息历史维护 (assistant + tool 消息)
+ * 3. 事件发射 (ChatEvent)
+ * 4. 错误处理
  *
- * 使用 DashScope 原生协议以获得完整功能：
- * - 联网搜索引用 (search_info)
- * - 角标标注 (enable_citation)
- * - 深度思考 (enable_thinking)
+ * 所有 Provider 通过此类执行，确保行为一致
  */
 
-/** Qwen Provider 配置 */
-interface QwenProviderConfig {
-    apiKey: string;
-    apiUrl?: string;
-}
 /**
- * Qwen Provider 实现
+ * Chat Orchestrator
+ *
+ * 核心职责：统一处理工具调用循环，所有 Provider 共享相同的逻辑
  */
-declare class QwenProvider implements ChatProvider {
-    readonly name = "qwen";
-    readonly supportedModels: string[];
-    private apiKey;
-    private apiUrl;
-    constructor(config: QwenProviderConfig);
-    supportsModel(model: string): boolean;
-    getModelCapabilities(model: string): ModelCapabilities;
-    chat(message: string, model: string, options: ChatOptions, context: ChatContext): AsyncGenerator<ChatProgress>;
-    /** 调用 DashScope API (流式) */
-    private callDashScopeStream;
+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;
 }
+/**
+ * 创建 Orchestrator 实例
+ */
+declare function createOrchestrator(config: OrchestratorConfig): ChatOrchestrator;
 
 /**
- * Gemini 3 Provider (Google)
- *
- * 使用 @google/genai SDK
- *
- * Gemini 3 新特性：
- * - thinking_level: 'low' | 'high' (控制推理深度，替代旧的 thinking_budget)
- * - thoughtSignature (维持推理上下文，必须返回给模型)
- * - includeThoughts (返回思考摘要)
+ * ARK (火山引擎) Adapter
  *
- * 限制：
- * - Google Search + 自定义 Function Calling 仍然不兼容
- * - 内置工具可组合：google_search + url_context + code_execution
- *
- * 参考：https://ai.google.dev/docs/gemini-3
+ * 职责：
+ * - 将标准消息转换为 ARK Responses API 格式
+ * - 调用 API 并解析响应为标准 StreamChunk
+ * - 不处理工具执行和消息历史
  */
 
-/** Gemini Provider 配置 */
-interface GeminiProviderConfig {
-    apiKey: string;
-}
+/** ARK 支持的模型 */
+declare const ARK_MODELS: string[];
 /**
- * Gemini Provider 实现
+ * ARK Adapter
+ *
+ * 使用 Responses API 格式
  */
-declare class GeminiProvider implements ChatProvider {
-    readonly name = "gemini";
+declare class ArkAdapter implements ProviderAdapter {
+    readonly name = "ark";
     readonly supportedModels: string[];
-    private geminiClient;
     private apiKey;
-    constructor(config: GeminiProviderConfig);
-    /** 懒加载 Gemini 客户端 */
-    private getClient;
+    private apiUrl;
+    constructor(config: AdapterConfig);
     supportsModel(model: string): boolean;
-    getModelCapabilities(model: string): ModelCapabilities;
-    chat(message: string, model: string, options: ChatOptions, context: ChatContext): AsyncGenerator<ChatProgress>;
-    /** 转换消息格式为 Gemini 格式 */
-    private convertToGeminiMessages;
-    /** 转换工具定义为 Gemini functionDeclarations 格式 */
-    private convertToGeminiFunctions;
+    /**
+     * 单次流式调用
+     */
+    streamOnce(messages: StandardMessage[], tools: SimpleToolDefinition[], options: StreamOnceOptions): AsyncGenerator<StreamChunk>;
+    /**
+     * 转换标准消息为 ARK Responses API 格式
+     */
+    private convertMessages;
+    /**
+     * 解析 ARK 流式响应
+     */
+    private parseStream;
 }
+/**
+ * 创建 ARK Adapter
+ */
+declare function createArkAdapter(config: AdapterConfig): ArkAdapter;
 
 /**
- * OpenRouter Provider
+ * OpenRouter Adapter
  *
- * 使用 OpenAI 兼容格式，支持多种模型：
- * - Claude (anthropic/claude-*)
- * - GPT (openai/gpt-*)
- * - Gemini (google/gemini-*)
- *
- * 特性：
- * - Web Search 插件支持
- * - URL 引用 annotations
- * - Extended Thinking (reasoning) 支持
+ * 职责：
+ * - 将标准消息转换为 OpenAI 兼容格式
+ * - 调用 API 并解析响应为标准 StreamChunk
+ * - 不处理工具执行和消息历史
  */
 
-/** OpenRouter Provider 配置 */
-interface OpenRouterProviderConfig {
-    apiKey: string;
-    apiUrl?: string;
-}
+/** OpenRouter 支持的模型 */
+declare const OPENROUTER_MODELS: string[];
 /**
- * OpenRouter Provider 实现
+ * OpenRouter Adapter
+ *
+ * 使用 OpenAI 兼容 API 格式
  */
-declare class OpenRouterProvider implements ChatProvider {
+declare class OpenRouterAdapter implements ProviderAdapter {
     readonly name = "openrouter";
     readonly supportedModels: string[];
     private apiKey;
     private apiUrl;
-    constructor(config: OpenRouterProviderConfig);
+    constructor(config: AdapterConfig);
     supportsModel(model: string): boolean;
-    getModelCapabilities(model: string): ModelCapabilities;
-    /** 检查模型是否支持 Extended Thinking */
-    private supportsThinking;
-    chat(message: string, model: string, options: ChatOptions, context: ChatContext): AsyncGenerator<ChatProgress>;
-    /** 调用 OpenRouter API */
-    private callOpenRouter;
-}
-
-/**
- * 混合 Agent 类
- *
- * 职责：
- * 1. 管理多个 Provider
- * 2. 路由请求到正确的 Provider
- * 3. 管理对话历史和上下文
- * 4. 处理工具执行
- */
-declare class HybridAgent {
-    private config;
-    private providers;
-    private geminiClient;
-    private toolExecutor;
-    private conversationHistory;
-    private abortController;
-    constructor(config: AgentConfig, toolExecutor?: ToolExecutor$1);
-    /**
-     * 初始化所有 Provider
-     */
-    private initializeProviders;
-    /**
-     * 判断模型提供商
-     */
-    private getModelProvider;
-    /**
-     * 获取 Provider
-     */
-    private getProvider;
-    /**
-     * 构建系统提示词
-     */
-    private buildSystemPrompt;
-    /**
-     * 获取默认深度思考模式（统一为 disabled）
-     */
-    private getDefaultThinkingMode;
     /**
-     * 执行工具
+     * 单次流式调用
      */
-    private executeTool;
-    /**
-     * 聊天入口
-     *
-     * 使用 Provider 模式路由请求到对应的模型提供商
-     */
-    chat(message: string, options?: ChatOptions, images?: string[]): AsyncGenerator<ChatProgress>;
+    streamOnce(messages: StandardMessage[], tools: SimpleToolDefinition[], options: StreamOnceOptions): AsyncGenerator<StreamChunk>;
     /**
-     * 中断当前请求
+     * 转换标准消息为 OpenAI 格式
      */
-    abort(): void;
+    private convertMessages;
     /**
-     * 清空对话历史
+     * 解析 OpenAI 兼容流式响应
      */
-    clearHistory(): void;
+    private parseStream;
+}
+/**
+ * 创建 OpenRouter Adapter
+ */
+declare function createOpenRouterAdapter(config: AdapterConfig): OpenRouterAdapter;
+
+/**
+ * Qwen (通义千问) Adapter
+ *
+ * 职责：
+ * - 将标准消息转换为 DashScope 原生 API 格式
+ * - 调用 API 并解析响应为标准 StreamChunk
+ * - 不处理工具执行和消息历史
+ */
+
+/** Qwen 支持的模型 */
+declare const QWEN_MODELS: string[];
+/**
+ * Qwen Adapter
+ *
+ * 使用 DashScope 原生协议
+ */
+declare class QwenAdapter implements ProviderAdapter {
+    readonly name = "qwen";
+    readonly supportedModels: string[];
+    private apiKey;
+    private apiUrl;
+    constructor(config: AdapterConfig);
+    supportsModel(model: string): boolean;
     /**
-     * 获取对话历史
+     * 单次流式调用
      */
-    getHistory(): ChatMessage[];
+    streamOnce(messages: StandardMessage[], tools: SimpleToolDefinition[], options: StreamOnceOptions): AsyncGenerator<StreamChunk>;
     /**
-     * 设置工作目录
+     * 转换标准消息为 Qwen 格式
      */
-    setWorkingDir(dir: string): void;
+    private convertMessages;
     /**
-     * 获取当前配置
+     * 解析 Qwen 流式响应
      */
-    getConfig(): Required<AgentConfig>;
+    private parseStream;
+}
+/**
+ * 创建 Qwen Adapter
+ */
+declare function createQwenAdapter(config: AdapterConfig): QwenAdapter;
+
+/**
+ * Gemini Adapter
+ *
+ * 职责：
+ * - 将标准消息转换为 Gemini SDK 格式
+ * - 调用 SDK 并解析响应为标准 StreamChunk
+ * - 不处理工具执行和消息历史
+ */
+
+/** Gemini 支持的模型 */
+declare const GEMINI_MODELS: string[];
+/** Gemini Adapter 配置 */
+interface GeminiAdapterConfig {
+    apiKey: string;
+}
+/**
+ * Gemini Adapter
+ *
+ * 使用 @google/genai SDK
+ */
+declare class GeminiAdapter implements ProviderAdapter {
+    readonly name = "gemini";
+    readonly supportedModels: string[];
+    private client;
+    private apiKey;
+    constructor(config: GeminiAdapterConfig);
+    /** 懒加载客户端 */
+    private getClient;
+    supportsModel(model: string): boolean;
     /**
-     * 获取模型能力
+     * 单次流式调用
      */
-    getModelCapabilities(model: string): ModelCapabilities | undefined;
+    streamOnce(messages: StandardMessage[], tools: SimpleToolDefinition[], options: StreamOnceOptions): AsyncGenerator<StreamChunk>;
     /**
-     * 获取所有支持的模型
+     * 转换标准消息为 Gemini 格式
      */
-    getSupportedModels(): ModelConfig[];
+    private convertMessages;
 }
-
 /**
- * 工具定义和默认执行器
+ * 创建 Gemini Adapter
  */
+declare function createGeminiAdapter(config: GeminiAdapterConfig): GeminiAdapter;
+
+declare const DEFAULT_MODEL: string;
 
 /**
- * 创建工具定义
+ * 工具执行器
  */
-declare function createToolDefinitions(workingDir?: string): ToolDefinition[];
+
 /**
  * 创建默认工具执行器（Node.js 环境）
+ *
+ * 用于执行 shell 命令，包含基本安全检查
+ * 支持通过 AbortSignal 取消命令执行
+ */
+declare function createDefaultToolExecutor(defaultCwd?: string): ToolExecutor$1;
+
+/**
+ * 获取当前工作目录工具（Vite 插件风格）
+ */
+
+declare function getCwdTool(): ToolPlugin;
+
+/**
+ * 获取平台信息工具（Vite 插件风格）
+ */
+
+declare function getPlatformTool(): ToolPlugin;
+
+/**
+ * 执行命令工具（Vite 插件风格）
+ */
+
+declare function executeCommandTool(): ToolPlugin;
+
+/**
+ * 分析图片工具（Vite 插件风格）
+ */
+
+declare function analyzeImageTool(): ToolPlugin;
+
+/**
+ * 生成图片工具（Vite 插件风格）
+ */
+
+declare function generateImageTool(): ToolPlugin;
+
+/**
+ * 分析视频工具（Vite 插件风格）
+ */
+
+declare function analyzeVideoTool(): ToolPlugin;
+
+/**
+ * 天气查询工具（Vite 插件风格）
+ *
+ * 使用高德天气 API
+ * - 稳定可靠，国内服务
+ * - 支持全国 337 个地级市
+ * - 中文输出
+ *
+ * 返回数据格式匹配 @huyooo/ai-chat-shared 的 WeatherData 类型
+ */
+
+declare function getWeatherTool(): ToolPlugin;
+
+/**
+ * UI 动作工具（Vite 插件风格）
+ *
+ * 将前端 UI 事件封装成 AI 可调用的工具
+ * 前端通过监听 onToolComplete 的 sideEffects 来执行相应的 UI 操作
+ */
+
+/**
+ * 显示 Toast 通知
+ */
+declare function showToastTool(): ToolPlugin;
+/**
+ * 打开确认对话框
+ */
+declare function openConfirmDialogTool(): ToolPlugin;
+/**
+ * 打开文件预览
+ */
+declare function openFilePreviewTool(): ToolPlugin;
+/**
+ * 跳转到指定目录
+ */
+declare function navigateToDirectoryTool(): ToolPlugin;
+/**
+ * 所有 UI 动作工具（已废弃，使用函数形式）
+ * @deprecated 使用 showToastTool() 等函数形式
+ */
+declare const uiActionTools: ToolPlugin[];
+
+/**
+ * 文档搜索工具集成
+ *
+ * 可选依赖 @huyooo/ai-search
+ * 如果未安装，工具会返回友好提示
+ *
+ * 注意：这个模块使用 eval + require 来避免 tsup 打包时解析依赖
+ */
+
+/**
+ * 搜索工具配置
+ */
+interface SearchToolsOptions {
+    /** 搜索数据存储目录 */
+    dataDir?: string;
+    /** 默认索引目录（首次使用时自动索引） */
+    defaultDirectories?: string[];
+    /** 是否在初始化时自动索引 */
+    autoIndex?: boolean;
+}
+/**
+ * 创建文档搜索工具
+ *
+ * 如果 @huyooo/ai-search 未安装，返回占位工具（提示用户安装）
+ *
+ * @example
+ * ```typescript
+ * import { createDocumentSearchTools } from '@huyooo/ai-chat-core';
+ *
+ * const searchTools = await createDocumentSearchTools({
+ *   dataDir: './.search-data',
+ *   defaultDirectories: ['~/Documents'],
+ * });
+ *
+ * const agent = new HybridAgent({
+ *   ...config,
+ *   tools: [...otherTools, ...searchTools],
+ * });
+ * ```
+ */
+declare function createDocumentSearchTools(options?: SearchToolsOptions): Promise<Tool[]>;
+/**
+ * 获取搜索插件实例（高级用法）
  */
-declare function createDefaultToolExecutor(workingDir?: string): ToolExecutor$1;
+declare function getDocumentSearchInstance(dataDir?: string, workspace?: string): Promise<{
+    tools: Tool[];
+    [key: string]: unknown;
+} | null>;
 
-export { AVAILABLE_MODELS, type AgentConfig, ArkProvider, type ChatContext, type ChatMessage, type ChatMode, type ChatOptions, type ChatProgress, type ChatProgressType, type ChatProvider, type DeepSeekMessage, type DeepSeekTool, GeminiProvider, HybridAgent, type ImageProgress, type ModelCapabilities, type ModelConfig, type ModelProvider, OpenRouterProvider, type ToolExecutor as ProviderToolExecutor, QwenProvider, type SearchResultProgress, type SearchStartProgress, type TextDeltaProgress, type TextProgress, type ThinkingMode, type ThinkingProgress, type ToolCallProgress, type ToolDefinition, type ToolExecutor$1 as ToolExecutor, type ToolResultProgress, createDefaultToolExecutor, createToolDefinitions };
+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 };