@huyooo/ai-chat-core 0.2.38 → 0.2.41

package/dist/events-GWl1-vbT.d.ts

@@ -0,0 +1,1073 @@
+/**
+ * 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;
+}
+
+/**
+ * 模型注册表
+ *
+ * 核心设计：Protocol + Family 分离
+ * - Protocol：负责 API 通信协议（HTTP/SSE/认证）
+ * - Family：负责模型行为差异（thinking格式、搜索方式、工具格式）
+ *
+ * 这样设计的好处：
+ * 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';
+/**
+ * 搜索实现方式（谁提供搜索、行为是否由我们统一）
+ * - 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';
+/**
+ * 模型家族配置
+ * 定义同一家族模型的共同行为特征
+ */
+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[];
+}
+/** 豆包家族（联网搜索统一走 web_search_ai/Tavily，与其它模型事件与数据格式一致） */
+declare const DOUBAO_FAMILY: ModelFamilyConfig;
+/** DeepSeek 家族（联网搜索统一走 web_search_ai/Tavily，与其它模型事件与数据格式一致） */
+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 {
+    /** Protocol 类型 */
+    provider: ProviderType;
+    /** 是否未注册（使用默认 Provider） */
+    isDefault: boolean;
+    /** 模型注册信息 */
+    registryEntry?: ModelRegistryEntry;
+    /** 模型家族配置 */
+    familyConfig?: ModelFamilyConfig;
+}
+/**
+ * 获取模型的 Provider
+ */
+declare function routeModelToProvider(model: string): ProviderType;
+/**
+ * 获取模型的完整路由信息
+ */
+declare function routeModelWithDetails(model: string): RouteResult;
+/**
+ * 获取默认 Provider
+ */
+declare function getDefaultProvider(): ProviderType;
+/**
+ * 检查模型是否属于指定 Provider
+ */
+declare function isModelForProvider(model: string, provider: ProviderType): boolean;
+
+/**
+ * AI Chat Core 类型定义
+ */
+
+/** 对话模式 */
+type ChatMode = 'agent' | 'ask';
+
+/** 模型选项（前端显示用） */
+interface ModelOption {
+    /** 模型 ID（发送给 API） */
+    modelId: string;
+    /** 显示名称 */
+    displayName: string;
+    /** 是否支持深度思考 */
+    supportsThinking: boolean;
+    /** 是否支持图片理解 */
+    supportsVision: boolean;
+    /** 用于模型项 hover 的特性描述（由后端定义，前端只渲染） */
+    tooltip?: {
+        features?: string[];
+        /** 开销信息（数组，分行显示） */
+        cost?: string[];
+        description?: string;
+    };
+}
+/**
+ * 预定义模型列表
+ */
+declare const MODELS: ModelOption[];
+/** 根据 modelId 获取模型 */
+declare function getModelByModelId(modelId: string): ModelOption | undefined;
+/** 工具批准回调函数 */
+type ToolApprovalCallback = (toolCall: {
+    id: string;
+    name: string;
+    args: Record<string, unknown>;
+}) => Promise<boolean>;
+/** Agent 配置 */
+interface AgentConfig {
+    /** 豆包/火山引擎 API Key (用于豆包和 DeepSeek) */
+    arkApiKey: string;
+    /** 豆包 API URL */
+    arkApiUrl?: string;
+    /** 通义千问 API Key */
+    qwenApiKey?: string;
+    /** 通义千问 API URL */
+    qwenApiUrl?: string;
+    /** OpenRouter API Key */
+    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） */
+    cwd?: string;
+    /**
+     * 工具列表（Vite 插件风格）
+     *
+     * 支持多种形式：
+     * - 单个工具：getCwdTool
+     * - 工具插件：searchPlugin({ dataDir, workspace })
+     * - Promise：await asyncPlugin()
+     *
+     * @example
+     * ```typescript
+     * tools: [
+     *   getCwdTool,
+     *   executeCommandTool,
+     *   searchPlugin({ dataDir: '/path', workspace: '/project' }),
+     * ]
+     * ```
+     */
+    tools?: ToolConfigItem[];
+    /**
+     * 工具批准回调（manual 模式使用）
+     * 返回 true 表示批准执行，false 表示跳过
+     */
+    onToolApprovalRequest?: ToolApprovalCallback;
+    /**
+     * 动态获取自动运行配置回调
+     * 每次检查工具批准时调用，获取最新配置
+     */
+    getAutoRunConfig?: () => Promise<AutoRunConfig | 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';
+/** 自动运行模式 */
+type AutoRunMode = 'run-everything' | 'manual';
+/** 自动运行配置 */
+interface AutoRunConfig {
+    /**
+     * 自动运行模式
+     * - 'run-everything': 运行所有内容（自动执行）
+     * - 'manual': 手动批准（每次执行前询问）
+     */
+    mode?: AutoRunMode;
+}
+/** 聊天消息格式（用于传递历史） */
+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 {
+    /** 对话模式 */
+    mode?: ChatMode;
+    /** 使用的模型 */
+    model?: string;
+    /** 模型提供商 */
+    provider?: ProviderType;
+    /** 是否启用联网搜索 */
+    enableWebSearch?: boolean;
+    /**
+     * 深度思考模式
+     * - 'enabled': 强制开启深度思考
+     * - 'disabled': 强制关闭深度思考
+     */
+    thinkingMode?: ThinkingMode;
+    /** 启用的工具名称列表（agent 模式有效，ask 模式强制禁用） */
+    enabledTools?: string[];
+    /** 自动运行配置 */
+    autoRunConfig?: AutoRunConfig;
+    /** 对话历史（从数据库加载，无状态架构） */
+    history?: ChatHistoryMessage[];
+    /**
+     * 用户自定义工具（透传模式）
+     *
+     * 这些工具不在服务端执行，而是：
+     * 1. 传递给 AI 模型
+     * 2. AI 返回 tool_call 时，发送 tool_call_request 事件给客户端
+     * 3. 客户端执行后，发新请求继续对话
+     */
+    userTools?: UserToolDefinition[];
+    /**
+     * 上次请求的计划快照（可选，仅用于断点续传）
+     *
+     * 正常流程不需要传：AI 会在单次请求内自主创建和管理计划。
+     *
+     * 仅在请求被中断后需要恢复时使用：
+     * - 客户端工具透传模式（请求中断，等客户端执行后重新发请求）
+     * - 用户 abort 后想继续
+     */
+    /**
+     * 宿主平台提示词（可选）
+     *
+     * 由宿主应用（如 smart-finder）注入的平台特定 system prompt 扩展。
+     * 用于描述平台特有的能力、工具编排、记忆管理等，避免在核心库中硬编码具体工具名。
+     *
+     * 注入位置：基础 prompt 之后、Skills 内容之前。
+     */
+    platformPrompt?: string;
+    /**
+     * Skills 内容（启用的 Skills 的 content 数组，由前端/服务端拼好传入）
+     *
+     * 自动注入到 system prompt 的【用户指令】段落。
+     * 前端合并「默认启用的 skills + @ 手动选的 skills」后传入。
+     */
+    skillContents?: string[];
+}
+/** 前端渲染组件类型（可扩展） */
+type RenderType = 'weather' | 'chart' | 'browser' | 'plan' | string;
+/** 前端动作类型（可扩展） */
+type ActionType = 'toast' | 'notification' | 'reload' | string;
+/**
+ * 工具 UI 声明（互斥）
+ * - render: 在对话流中渲染自定义组件
+ * - action: 触发前端动作（通知、刷新等）
+ */
+type ToolUI = {
+    type: 'render';
+    name: RenderType;
+    props?: Record<string, unknown>;
+} | {
+    type: 'action';
+    name: ActionType;
+};
+/** Shell 命令执行结果 */
+interface ExecResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+/** 工具执行上下文 */
+interface ToolContext {
+    /** 当前工作目录（可选，工具需要时由框架注入） */
+    cwd?: string;
+    /** 执行 Shell 命令（可选，工具需要时由框架注入） */
+    exec?: (cmd: string, args?: string[]) => Promise<ExecResult>;
+    /** 中断信号（用于取消长时间操作） */
+    signal?: AbortSignal;
+}
+/** 工具错误码 */
+type ToolErrorCode = 'INVALID_PARAMS' | 'NOT_FOUND' | 'PERMISSION_DENIED' | 'OPERATION_FAILED' | 'TIMEOUT' | 'NETWORK_ERROR' | string;
+/** 工具错误结构 */
+interface ToolError {
+    message: string;
+    code?: ToolErrorCode;
+    suggestion?: string;
+    retryable?: boolean;
+}
+/** 判断是否为结构化工具错误 */
+declare function isToolError(e: unknown): e is Error & {
+    toolError: ToolError;
+};
+/** 抛出结构化工具错误 */
+declare function throwToolError(message: string, code?: ToolErrorCode, opts?: {
+    suggestion?: string;
+    retryable?: boolean;
+}): never;
+/** 重新抛出工具错误（非工具错误则包装后抛出） */
+declare function rethrowToolError(error: unknown, code?: ToolErrorCode, opts?: {
+    suggestion?: string;
+    retryable?: boolean;
+}): never;
+/** 从 args 中安全提取类型化参数 */
+declare function getArg<T>(args: Record<string, unknown>, key: string): T | undefined;
+/** 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;
+}
+/**
+ * 工具接口
+ *
+ * @example
+ * ```typescript
+ * const myTool: Tool = {
+ *   name: 'my_tool',
+ *   description: '我的自定义工具',
+ *   parameters: { type: 'object', properties: { query: { type: 'string' } }, required: ['query'] },
+ *   execute: async (args) => ({ result: getArg<string>(args, 'query') })
+ * };
+ * ```
+ */
+interface Tool {
+    /** 工具名称 */
+    name: string;
+    /** 工具描述（供 AI 理解） */
+    description: string;
+    /** 参数定义（JSON Schema） */
+    parameters: JsonSchemaObject;
+    /**
+     * UI 声明（可选）
+     * - render: 在对话流中渲染自定义组件
+     * - action: 执行成功后触发前端动作
+     */
+    ui?: ToolUI;
+    /**
+     * 是否需要用户手动批准（覆盖全局 autoRunMode）
+     *
+     * 设为 true 时无论全局配置如何，该工具必须用户确认才执行
+     */
+    requiresApproval?: boolean;
+    /** 超时时间（毫秒），由框架通过 AbortSignal 强制执行 */
+    timeout?: number;
+    /** 扩展字段，供宿主应用存放元数据 */
+    meta?: Record<string, unknown>;
+    /**
+     * 执行函数
+     *
+     * 成功返回 object，框架自动 JSON.stringify 后传给 LLM。
+     * 失败统一 throw（推荐使用 throwToolError()）。
+     */
+    execute: (args: Record<string, unknown>, context: ToolContext) => Promise<object>;
+}
+/** 工具执行器接口（供 Agent 内部使用，自定义命令执行环境） */
+interface ToolExecutor {
+    /** 执行 Shell 命令 */
+    executeCommand(command: string, cwd?: string, signal?: AbortSignal, hooks?: {
+        onStdout?: (chunk: string) => void;
+        onStderr?: (chunk: string) => void;
+    }): Promise<{
+        success: boolean;
+        output?: string;
+        error?: string;
+    }>;
+}
+/**
+ * 工具插件实例
+ *
+ * 由 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 = Tool | ToolPlugin | Promise<Tool | ToolPlugin>;
+/**
+ * 解析工具配置，统一转换为 Tool[]
+ *
+ * 支持三种形式：
+ * - Tool: 单个工具（直接使用）
+ * - ToolPlugin: 工具插件（展开 .tools 数组）
+ * - Promise<Tool | ToolPlugin>: 异步工具/插件
+ */
+declare function resolveTools(items: ToolConfigItem[]): Promise<Tool[]>;
+/** 工具定义（OpenAI 格式，内部使用） */
+interface ToolDefinition {
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: JsonSchemaObject;
+    };
+}
+/** 聊天消息（内部格式） */
+interface ChatMessage {
+    /** 消息 ID */
+    id?: string;
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: string;
+    /** 深度思考内容 */
+    reasoning_content?: string;
+    tool_call_id?: string;
+    tool_calls?: Array<{
+        id: string;
+        type: 'function';
+        function: {
+            name: string;
+            arguments: string;
+        };
+        /** Gemini 模型需要的 thought_signature（用于工具调用循环） */
+        thought_signature?: string;
+    }>;
+}
+/** 火山引擎 Responses API 工具定义 */
+interface ResponsesApiTool {
+    type: 'function' | 'web_search';
+    name?: string;
+    description?: string;
+    parameters?: Record<string, unknown>;
+    max_keyword?: number;
+    limit?: number;
+    sources?: string[];
+}
+
+/**
+ * AI Chat 事件系统
+ *
+ * 模块化的事件类型定义，用于 Agent 与前端之间的通信。
+ *
+ * 设计原则：
+ * 1. 每种事件类型有明确的数据结构
+ * 2. 事件分组便于管理和扩展
+ * 3. 类型安全，避免 unknown
+ * 4. 统一的时间追踪（开始/结束/耗时）
+ */
+/**
+ * 搜索结果项（统一契约）
+ * 无论搜索来源是厂商原生（ARK annotation）还是 Tavily 工具，协议/编排层都会归一为此结构，
+ * 前端只需依赖 title/url/snippet 即可。
+ */
+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';
+
+/** 内部使用的 ToolErrorShape 别名 */
+type ToolErrorShape = ToolError;
+/** 错误详情 - 结构化错误信息 */
+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;
+    };
+}
+/** 工具调用结果事件 */
+interface ToolCallResultEvent {
+    type: 'tool_call_result';
+    data: {
+        /** 工具调用 ID */
+        id: string;
+        /** 工具名称 */
+        name: string;
+        /** 执行结果（JSON 字符串） */
+        result: string;
+        /** 是否成功 */
+        success: boolean;
+        /** 错误信息（失败时） */
+        error?: ToolErrorShape;
+        /** 结束时间戳（毫秒） */
+        endedAt: number;
+        /** 执行耗时（毫秒） */
+        duration: number;
+        /** 工具 UI 声明（成功时） */
+        ui?: ToolUIShape;
+    };
+}
+/** ToolUI 形状（对应 types.ts 中的 ToolUI，避免循环依赖） */
+interface ToolUIShape {
+    type: 'render' | 'action';
+    name: string;
+    props?: Record<string, unknown>;
+}
+/** 工具输出增量事件（用于 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;
+    };
+}
+/**
+ * 客户端工具调用请求事件（透传模式）
+ *
+ * 用于用户自定义工具：
+ * - AI 返回 tool_call
+ * - 服务端不执行，透传给客户端
+ * - 客户端执行后，发新请求继续对话
+ */
+interface ToolCallRequestEvent {
+    type: 'tool_call_request';
+    data: {
+        /** 工具调用 ID */
+        id: string;
+        /** 工具名称 */
+        name: string;
+        /** 工具参数 */
+        args: Record<string, unknown>;
+        /** 请求时间戳 */
+        requestedAt: number;
+    };
+}
+/** 工具相关事件联合类型 */
+type ToolEvent = ToolCallStartEvent | ToolCallResultEvent | ToolApprovalRequestEvent | ToolCallOutputEvent | ToolCallRequestEvent;
+/** 文本增量事件 */
+interface TextDeltaEvent {
+    type: 'text_delta';
+    data: {
+        /** 增量文本 */
+        content: string;
+    };
+}
+/** 文本相关事件联合类型 */
+type TextEvent = TextDeltaEvent;
+/** 计划步骤状态 */
+type PlanStepStatus = 'pending' | 'in_progress' | 'done' | 'failed';
+/** 计划步骤 */
+interface PlanStep {
+    /** 步骤 ID（模型生成，如 "1", "scan", "move-images"） */
+    id: string;
+    /** 步骤描述 */
+    title: string;
+    /** 步骤状态 */
+    status: PlanStepStatus;
+}
+/** 完成事件 */
+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 = 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;
+/**
+ * Agent 当前阶段：前端根据此字段直接渲染 loading 状态，不需要「猜」。
+ *
+ * - thinking：模型正在思考（初始请求 / 工具执行完后等待下一轮）→ 显示「正在思考...」
+ * - null：有可见活动（思考/搜索/工具/文字流），不需要额外 loading
+ */
+type AgentPhase = 'thinking' | null;
+/** Agent 状态事件（前端用于渲染 loading 提示） */
+interface AgentStatusEvent {
+    type: 'agent_status';
+    data: {
+        /** 当前阶段 */
+        phase: AgentPhase;
+    };
+}
+/** 创建 agent_status 事件 */
+declare function createAgentStatus(phase: AgentPhase): AgentStatusEvent;
+/** 所有事件类型 */
+type ChatEvent = ThinkingEvent | SearchEvent | ToolEvent | TextEvent | StatusEvent | StepEvent | AgentStatusEvent;
+/** 事件类型字符串 */
+type ChatEventType = ChatEvent['type'];
+/** 所有合法事件类型（用于契约测试：Orchestrator/适配器产出必须在此集合内） */
+declare const CHAT_EVENT_TYPES: readonly ChatEventType[];
+/**
+ * 创建思考开始事件
+ */
+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?: ToolErrorShape, ui?: ToolUIShape): ToolCallResultEvent;
+/**
+ * 创建工具输出增量事件
+ */
+declare function createToolCallOutput(id: string, name: string, stream: 'stdout' | 'stderr', chunk: string): ToolCallOutputEvent;
+/**
+ * 创建客户端工具调用请求事件（透传模式）
+ *
+ * 用于用户自定义工具，服务端不执行，透传给客户端
+ */
+declare function createToolCallRequest(id: string, name: string, args: Record<string, unknown>): ToolCallRequestEvent;
+/**
+ * 创建文本增量事件
+ */
+declare function createTextDelta(content: string): TextDeltaEvent;
+/**
+ * 创建完成事件
+ */
+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 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 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;
+
+export { resolveTools as $, type AgentConfig as A, type AutoRunConfig as B, type ChatOptions as C, DOUBAO_FAMILY as D, type ToolDefinition as E, type ResponsesApiTool as F, GEMINI_FAMILY as G, type ProviderType as H, type ToolContext as I, type JsonSchemaObject as J, type ToolUI as K, type RenderType as L, type ModelFamilyConfig as M, type ActionType as N, type ExecResult as O, type ProtocolId as P, QWEN_FAMILY as Q, type RouteResult as R, type SearchStrategy as S, type ToolExecutor as T, type ToolError as U, type ToolErrorCode as V, type ToolPlugin as W, type ToolConfigItem as X, type UserToolDefinition as Y, MODELS as Z, getModelByModelId as _, type ChatEvent as a, isTextEvent as a$, tool as a0, tools as a1, throwToolError as a2, rethrowToolError as a3, isToolError as a4, getArg as a5, type SearchResult as a6, type ToolCallStatus as a7, type ToolCallInfo as a8, type TokenUsage as a9, type StepEndEvent as aA, type StepEvent as aB, type ChatEventType as aC, createThinkingStart as aD, createThinkingDelta as aE, createThinkingEnd as aF, createSearchStart as aG, createSearchResult as aH, createSearchEnd as aI, createToolCallStart as aJ, createToolCallResult as aK, createToolCallOutput as aL, createToolCallRequest as aM, createTextDelta as aN, createDone as aO, createError as aP, createApiError as aQ, createRateLimitError as aR, createToolError as aS, createTimeoutError as aT, createParseError as aU, createAbort as aV, createStepStart as aW, createStepEnd as aX, isThinkingEvent as aY, isSearchEvent as aZ, isToolEvent as a_, type ErrorCategory as aa, type ErrorDetails as ab, type ToolUIShape as ac, type ThinkingStartEvent as ad, type ThinkingDeltaEvent as ae, type ThinkingEndEvent as af, type ThinkingEvent as ag, type SearchStartEvent as ah, type SearchResultEvent as ai, type SearchEndEvent as aj, type SearchEvent as ak, type ToolCallStartEvent as al, type ToolCallResultEvent as am, type ToolCallOutputEvent as an, type ToolApprovalRequestEvent as ao, type ToolCallRequestEvent as ap, type ToolEvent as aq, type TextDeltaEvent as ar, type TextEvent as as, type PlanStep as at, type PlanStepStatus as au, type DoneEvent as av, type ErrorEvent as aw, type AbortEvent as ax, type StatusEvent as ay, type StepStartEvent as az, type ModelOption as b, isStatusEvent as b0, isErrorEvent as b1, isAbortEvent as b2, isStepEvent as b3, isRetryableError as b4, CHAT_EVENT_TYPES as b5, routeModelToProvider as b6, routeModelWithDetails as b7, getDefaultProvider as b8, isModelForProvider as b9, type McpServerConfig as ba, type McpConnectionStatus as bb, type AgentPhase as bc, type AgentStatusEvent as bd, createAgentStatus as be, type McpConnectionInfo as c, type Tool as d, type ChatMessage as e, MODEL_FAMILIES as f, DEEPSEEK_FAMILY as g, GPT_FAMILY as h, CLAUDE_FAMILY as i, MODEL_REGISTRY as j, getModelEntry as k, getModelFamily as l, getModelProtocol as m, getVisibleModels as n, getModelsByFamily as o, getModelsByProtocol as p, modelSupportsThinking as q, modelSupportsNativeSearch as r, getModelSearchStrategy as s, type ModelFamilyId as t, type ThinkingFormat as u, type ToolCallFormat as v, type ModelRegistryEntry as w, type ChatMode as x, type ThinkingMode as y, type AutoRunMode as z };