@huyooo/ai-chat-core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,496 @@
+/**
+ * AI Chat Core 类型定义
+ */
+/** 对话模式 */
+type ChatMode = 'agent' | 'plan' | 'ask';
+/** 可用模型 */
+type ModelProvider = 'doubao' | 'deepseek' | 'qwen' | 'gemini' | 'openrouter';
+/** 模型配置 */
+interface ModelConfig {
+    provider: ModelProvider;
+    model: string;
+    displayName: string;
+    supportsTools: boolean;
+    supportsWebSearch: boolean;
+    /** 支持的深度思考模式 */
+    supportedThinkingModes: ThinkingMode[];
+}
+/** 预定义模型列表 */
+declare const AVAILABLE_MODELS: ModelConfig[];
+/** 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;
+    /** Gemini API Key (用于图片/视频) */
+    geminiApiKey: string;
+    /** 工作目录 */
+    workingDir?: string;
+}
+/** 深度思考模式 */
+type ThinkingMode = 'enabled' | 'disabled';
+/** 聊天配置（每次聊天可变的选项） */
+interface ChatOptions {
+    /** 对话模式 */
+    mode?: ChatMode;
+    /** 使用的模型 */
+    model?: string;
+    /** 模型提供商 */
+    provider?: ModelProvider;
+    /** 是否启用联网搜索 */
+    enableWebSearch?: boolean;
+    /**
+     * 深度思考模式
+     * - 'enabled': 强制开启深度思考
+     * - '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;
+        }>;
+    };
+}
+/** 文本进度 */
+interface TextProgress {
+    type: 'text';
+    data: string;
+}
+/** 流式文本增量 */
+interface TextDeltaProgress {
+    type: 'text_delta';
+    data: string;
+}
+/** 思考进度 */
+interface ThinkingProgress {
+    type: 'thinking';
+    data: {
+        content: string;
+        isComplete?: boolean;
+    };
+}
+/** 图片进度 */
+interface ImageProgress {
+    type: 'image';
+    data: {
+        path?: string;
+        base64?: string;
+    };
+}
+/** 工具执行器接口（可由使用方实现） */
+interface ToolExecutor$1 {
+    /** 执行 Shell 命令 */
+    executeCommand(command: string, workingDir?: string): 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 格式） */
+interface ToolDefinition {
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: {
+            type: 'object';
+            properties: Record<string, {
+                type: string;
+                description: string;
+                enum?: string[];
+                items?: {
+                    type: string;
+                };
+            }>;
+            required: string[];
+        };
+    };
+}
+/** 聊天消息（内部格式） */
+interface ChatMessage {
+    /** 消息 ID（豆包 Responses API 需要） */
+    id?: string;
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: string;
+    /** 深度思考内容（DeepSeek 思考模式下需要回传） */
+    reasoning_content?: string;
+    tool_call_id?: string;
+    tool_calls?: Array<{
+        id: string;
+        type: 'function';
+        function: {
+            name: string;
+            arguments: string;
+        };
+    }>;
+}
+/** DeepSeek Responses API 消息格式 */
+interface DeepSeekMessage {
+    role: 'user' | 'assistant';
+    content: Array<{
+        type: 'input_text' | 'output_text';
+        text: string;
+    }>;
+}
+/** DeepSeek / 火山引擎 Responses API 工具定义 */
+interface DeepSeekTool {
+    type: 'function' | 'web_search';
+    function?: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+    max_keyword?: number;
+    limit?: number;
+    sources?: string[];
+}
+
+/**
+ * Provider 基础接口定义
+ *
+ * 所有 AI 模型提供商都实现这个统一接口
+ */
+
+/** 工具执行器类型 */
+type ToolExecutor = (name: string, args: Record<string, unknown>) => Promise<string>;
+/** 聊天上下文 */
+interface ChatContext {
+    /** 对话历史 */
+    history: ChatMessage[];
+    /** 系统提示词 */
+    systemPrompt: string;
+    /** 工作目录 */
+    workingDir: string;
+    /** 工具执行器 */
+    executeTool: ToolExecutor;
+    /** 取消信号 */
+    signal: AbortSignal;
+}
+/** 模型能力定义 */
+interface ModelCapabilities {
+    supportsTools: boolean;
+    supportsWebSearch: boolean;
+    supportsThinking: boolean;
+    supportedThinkingModes: Array<'enabled' | 'disabled'>;
+}
+/**
+ * ChatProvider 接口
+ *
+ * 每个 AI 模型提供商都需要实现这个接口
+ */
+interface ChatProvider {
+    /** 提供商名称 */
+    readonly name: string;
+    /** 支持的模型列表 */
+    readonly supportedModels: string[];
+    /**
+     * 检查是否支持指定模型
+     */
+    supportsModel(model: string): boolean;
+    /**
+     * 获取模型能力
+     */
+    getModelCapabilities(model: string): ModelCapabilities;
+    /**
+     * 执行聊天
+     *
+     * @param message 用户消息
+     * @param model 模型名称
+     * @param options 聊天选项
+     * @param context 聊天上下文
+     * @returns 异步生成器，产出聊天进度事件
+     */
+    chat(message: string, model: string, options: ChatOptions, context: ChatContext): AsyncGenerator<ChatProgress>;
+}
+
+/**
+ * ARK Provider (火山引擎)
+ *
+ * 统一使用 Responses API，支持：
+ * - 函数调用 Function Calling
+ * - 联网搜索 Web Search
+ * - 深度思考 Thinking
+ * - 上下文缓存 Caching
+ *
+ * 支持模型：豆包 (doubao-*), DeepSeek (deepseek-*)
+ */
+
+/** ARK Provider 配置 */
+interface ArkProviderConfig {
+    apiKey: string;
+    apiUrl?: string;
+    /** 是否启用上下文缓存 */
+    enableCaching?: boolean;
+}
+/**
+ * ARK Provider 实现
+ *
+ * 统一使用 Responses API
+ */
+declare class ArkProvider implements ChatProvider {
+    readonly name = "ark";
+    readonly supportedModels: string[];
+    private apiKey;
+    private apiUrl;
+    private enableCaching;
+    constructor(config: ArkProviderConfig);
+    supportsModel(model: string): boolean;
+    getModelCapabilities(model: string): ModelCapabilities;
+    /**
+     * 聊天入口 - 统一使用 Responses API
+     */
+    chat(message: string, model: string, options: ChatOptions, context: ChatContext): AsyncGenerator<ChatProgress>;
+}
+
+/**
+ * Qwen Provider (通义千问)
+ *
+ * 使用 DashScope 原生协议以获得完整功能：
+ * - 联网搜索引用 (search_info)
+ * - 角标标注 (enable_citation)
+ * - 深度思考 (enable_thinking)
+ */
+
+/** Qwen Provider 配置 */
+interface QwenProviderConfig {
+    apiKey: string;
+    apiUrl?: string;
+}
+/**
+ * Qwen 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;
+}
+
+/**
+ * Gemini 3 Provider (Google)
+ *
+ * 使用 @google/genai SDK
+ *
+ * Gemini 3 新特性：
+ * - thinking_level: 'low' | 'high' (控制推理深度，替代旧的 thinking_budget)
+ * - thoughtSignature (维持推理上下文，必须返回给模型)
+ * - includeThoughts (返回思考摘要)
+ *
+ * 限制：
+ * - Google Search + 自定义 Function Calling 仍然不兼容
+ * - 内置工具可组合：google_search + url_context + code_execution
+ *
+ * 参考：https://ai.google.dev/docs/gemini-3
+ */
+
+/** Gemini Provider 配置 */
+interface GeminiProviderConfig {
+    apiKey: string;
+}
+/**
+ * Gemini Provider 实现
+ */
+declare class GeminiProvider implements ChatProvider {
+    readonly name = "gemini";
+    readonly supportedModels: string[];
+    private geminiClient;
+    private apiKey;
+    constructor(config: GeminiProviderConfig);
+    /** 懒加载 Gemini 客户端 */
+    private getClient;
+    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;
+}
+
+/**
+ * OpenRouter Provider
+ *
+ * 使用 OpenAI 兼容格式，支持多种模型：
+ * - Claude (anthropic/claude-*)
+ * - GPT (openai/gpt-*)
+ * - Gemini (google/gemini-*)
+ *
+ * 特性：
+ * - Web Search 插件支持
+ * - URL 引用 annotations
+ * - Extended Thinking (reasoning) 支持
+ */
+
+/** OpenRouter Provider 配置 */
+interface OpenRouterProviderConfig {
+    apiKey: string;
+    apiUrl?: string;
+}
+/**
+ * OpenRouter Provider 实现
+ */
+declare class OpenRouterProvider implements ChatProvider {
+    readonly name = "openrouter";
+    readonly supportedModels: string[];
+    private apiKey;
+    private apiUrl;
+    constructor(config: OpenRouterProviderConfig);
+    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>;
+    /**
+     * 中断当前请求
+     */
+    abort(): void;
+    /**
+     * 清空对话历史
+     */
+    clearHistory(): void;
+    /**
+     * 获取对话历史
+     */
+    getHistory(): ChatMessage[];
+    /**
+     * 设置工作目录
+     */
+    setWorkingDir(dir: string): void;
+    /**
+     * 获取当前配置
+     */
+    getConfig(): Required<AgentConfig>;
+    /**
+     * 获取模型能力
+     */
+    getModelCapabilities(model: string): ModelCapabilities | undefined;
+    /**
+     * 获取所有支持的模型
+     */
+    getSupportedModels(): ModelConfig[];
+}
+
+/**
+ * 工具定义和默认执行器
+ */
+
+/**
+ * 创建工具定义
+ */
+declare function createToolDefinitions(workingDir?: string): ToolDefinition[];
+/**
+ * 创建默认工具执行器（Node.js 环境）
+ */
+declare function createDefaultToolExecutor(workingDir?: string): ToolExecutor$1;
+
+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 };