@huyooo/ai-chat-bridge-electron 0.2.44 → 0.3.4

package/dist/main/asr/client.d.ts

@@ -0,0 +1,112 @@
+/**
+ * 火山引擎大模型流式语音识别 - WebSocket 客户端
+ *
+ * 在 Electron 主进程中运行，处理与火山引擎 ASR 服务的通信
+ */
+import { type AsrResult } from './protocol';
+/** ASR 客户端配置 */
+export interface AsrClientConfig {
+    /** 火山引擎 App ID */
+    appId: string;
+    /** 火山引擎 Access Key */
+    accessKey: string;
+    /** 资源 ID */
+    resourceId?: string;
+    /** 使用双向流式优化版 */
+    useAsyncMode?: boolean;
+}
+/** ASR 事件回调 */
+export interface AsrCallbacks {
+    /** 连接成功 */
+    onConnected?: () => void;
+    /** 收到识别结果 */
+    onResult?: (result: AsrResult, isLast: boolean) => void;
+    /** 发生错误 */
+    onError?: (error: Error) => void;
+    /** 连接关闭 */
+    onClose?: () => void;
+}
+/** ASR 会话配置 */
+export interface AsrSessionConfig {
+    /** 音频格式 */
+    format?: 'pcm' | 'wav';
+    /** 采样率 */
+    sampleRate?: number;
+    /** 启用标点 */
+    enablePunc?: boolean;
+    /** 启用 ITN（数字规整） */
+    enableItn?: boolean;
+    /** 启用语义顺滑 */
+    enableDdc?: boolean;
+    /** 输出分句信息 */
+    showUtterances?: boolean;
+}
+/**
+ * ASR WebSocket 客户端
+ *
+ * @example
+ * ```ts
+ * const client = new AsrClient({
+ *   appId: 'your-app-id',
+ *   accessKey: 'your-access-key',
+ * });
+ *
+ * await client.connect({
+ *   onResult: (result, isLast) => {
+ *     console.log('识别结果:', result.result?.text);
+ *   },
+ *   onError: (error) => {
+ *     console.error('错误:', error);
+ *   },
+ * });
+ *
+ * client.sendAudio(audioBuffer);
+ * client.finish(); // 发送最后一包
+ * ```
+ */
+export declare class AsrClient {
+    private config;
+    private ws;
+    private callbacks;
+    private connectId;
+    private isConnected;
+    private sessionConfig;
+    constructor(config: AsrClientConfig);
+    /**
+     * 获取 WebSocket 连接地址
+     */
+    private getWsUrl;
+    /**
+     * 获取资源 ID
+     */
+    private getResourceId;
+    /**
+     * 连接到 ASR 服务
+     */
+    connect(callbacks: AsrCallbacks, sessionConfig?: AsrSessionConfig): Promise<void>;
+    /**
+     * 发送首包（Full Client Request）
+     */
+    private sendFullClientRequest;
+    /**
+     * 发送音频数据
+     * @param audioData PCM 音频数据（16bit, 16kHz, 单声道）
+     */
+    sendAudio(audioData: Buffer): void;
+    /**
+     * 发送最后一包并结束识别
+     */
+    finish(): void;
+    /**
+     * 断开连接
+     */
+    disconnect(): void;
+    /**
+     * 检查是否已连接
+     */
+    get connected(): boolean;
+}
+/**
+ * 创建 ASR 客户端实例
+ */
+export declare function createAsrClient(config: AsrClientConfig): AsrClient;

package/dist/main/asr/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * ASR 模块导出
+ */
+export * from './protocol';
+export * from './client';
+/** ASR 桥接配置 */
+export interface AsrBridgeConfig {
+    /** IPC channel 前缀 */
+    channelPrefix?: string;
+    /** 火山引擎 App ID */
+    appId: string;
+    /** 火山引擎 Access Key */
+    accessKey: string;
+    /** 资源 ID */
+    resourceId?: string;
+}
+/**
+ * 创建 ASR Electron 桥接
+ *
+ * 在主进程中调用，注册 ASR 相关的 IPC handlers
+ *
+ * @example
+ * ```ts
+ * import { createAsrBridge } from '@huyooo/ai-chat-bridge-electron/main';
+ *
+ * createAsrBridge({
+ *   appId: process.env.VOLC_APP_ID!,
+ *   accessKey: process.env.VOLC_ACCESS_KEY!,
+ * });
+ * ```
+ */
+export declare function createAsrBridge(config: AsrBridgeConfig): {
+    /** 清理所有会话 */
+    cleanup: () => void;
+};

package/dist/main/asr/protocol.d.ts

@@ -0,0 +1,135 @@
+/**
+ * 火山引擎大模型流式语音识别 - 二进制协议编解码
+ *
+ * 协议结构：
+ * - Header (4 bytes)
+ * - [Sequence (4 bytes, optional)]
+ * - Payload size (4 bytes)
+ * - Payload (variable)
+ */
+/** 消息类型 */
+export declare const MessageType: {
+    /** 客户端发送：包含请求参数的完整请求 */
+    readonly FULL_CLIENT_REQUEST: 1;
+    /** 客户端发送：仅包含音频数据 */
+    readonly AUDIO_ONLY_REQUEST: 2;
+    /** 服务端响应：包含识别结果 */
+    readonly FULL_SERVER_RESPONSE: 9;
+    /** 服务端响应：错误消息 */
+    readonly ERROR_RESPONSE: 15;
+};
+/** 消息类型特定标志 */
+export declare const MessageFlags: {
+    /** 无特殊标志 */
+    readonly NONE: 0;
+    /** header 后 4 字节为正 sequence number */
+    readonly HAS_SEQUENCE: 1;
+    /** 最后一包（负包） */
+    readonly LAST_PACKET: 2;
+    /** 最后一包且有 sequence number */
+    readonly LAST_PACKET_WITH_SEQUENCE: 3;
+};
+/** 序列化方法 */
+export declare const SerializationMethod: {
+    readonly NONE: 0;
+    readonly JSON: 1;
+};
+/** 压缩方法 */
+export declare const CompressionMethod: {
+    readonly NONE: 0;
+    readonly GZIP: 1;
+};
+/** ASR 请求配置 */
+export interface AsrRequestConfig {
+    /** 用户相关配置 */
+    user?: {
+        uid?: string;
+        did?: string;
+        platform?: string;
+        sdk_version?: string;
+        app_version?: string;
+    };
+    /** 音频配置 */
+    audio: {
+        format: 'pcm' | 'wav' | 'ogg' | 'mp3';
+        codec?: 'raw' | 'opus';
+        rate?: number;
+        bits?: number;
+        channel?: number;
+        /** 语种（仅流式输入模式支持） */
+        language?: string;
+    };
+    /** 请求配置 */
+    request: {
+        model_name: 'bigmodel';
+        /** 启用 ITN（数字规整） */
+        enable_itn?: boolean;
+        /** 启用标点 */
+        enable_punc?: boolean;
+        /** 启用语义顺滑 */
+        enable_ddc?: boolean;
+        /** 输出语音停顿、分句、分词信息 */
+        show_utterances?: boolean;
+        /** 结果返回方式：full(全量)/single(增量) */
+        result_type?: 'full' | 'single';
+        /** 启用首字返回加速 */
+        enable_accelerate_text?: boolean;
+        /** 首字返回加速率 (0-20) */
+        accelerate_score?: number;
+        /** 语义切句最大静音阈值 (ms) */
+        vad_segment_duration?: number;
+        /** 强制判停时间 (ms) */
+        end_window_size?: number;
+        /** 热词等语料配置 */
+        corpus?: {
+            boosting_table_name?: string;
+            boosting_table_id?: string;
+            correct_table_name?: string;
+            correct_table_id?: string;
+            context?: string;
+        };
+    };
+}
+/** ASR 识别结果 */
+export interface AsrResult {
+    result?: {
+        text: string;
+        utterances?: Array<{
+            text: string;
+            start_time: number;
+            end_time: number;
+            definite: boolean;
+            words?: Array<{
+                text: string;
+                start_time: number;
+                end_time: number;
+                blank_duration: number;
+            }>;
+        }>;
+    };
+    audio_info?: {
+        duration: number;
+    };
+}
+/** 服务端响应 */
+export interface ServerResponse {
+    type: 'result' | 'error';
+    sequence?: number;
+    isLast: boolean;
+    data: AsrResult | {
+        code: number;
+        message: string;
+    };
+}
+/**
+ * 编码 Full Client Request（首包）
+ */
+export declare function encodeFullClientRequest(config: AsrRequestConfig, useGzip?: boolean): Buffer;
+/**
+ * 编码 Audio Only Request（音频包）
+ */
+export declare function encodeAudioOnlyRequest(audioData: Buffer, isLast?: boolean, useGzip?: boolean): Buffer;
+/**
+ * 解码服务端响应
+ */
+export declare function decodeServerResponse(data: Buffer): ServerResponse;

package/dist/main/create-electron-chat.d.ts

@@ -0,0 +1,100 @@
+/**
+ * createElectronChat - Electron 平台声明式 AI Chat 入口
+ *
+ * 将 AssetManager + ElectronBridge + ASR 合并为一次配置调用。
+ *
+ * @example
+ * ```ts
+ * import { createElectronChat } from '@huyooo/ai-chat-bridge-electron/main';
+ * import Database from 'better-sqlite3';
+ *
+ * const chat = await createElectronChat({
+ *   dataDir: app.getPath('userData'),
+ *   sqliteFactory: (sqlitePath) => new Database(sqlitePath),
+ *   llm: { models: { ... } },
+ *   tools: [
+ *     tavilySearchTool(API_KEY),
+ *     getWeatherTool(),
+ *   ],
+ *   asr: { appId: '...', accessKey: '...' },
+ * });
+ * ```
+ */
+import type { LLMConfig, Tool, ToolPlugin, ChatOptions, DataEngineContext } from '@huyooo/ai-chat-core';
+import type { StorageContext, StorageAdapter, SqliteDatabaseFactory } from '@huyooo/ai-chat-storage';
+import { type AssetManager, type AssetMetadataStore } from '@huyooo/ai-chat-host-node';
+/** ASR 语音识别配置 */
+export interface AsrConfig {
+    appId: string;
+    accessKey: string;
+    resourceId?: string;
+}
+/**
+ * Electron AI Chat 配置
+ *
+ * 平台无关字段：llm, tools（由 ai-chat-core 定义类型）
+ * Electron 特有字段：dataDir, assetsDir, metadataStore, asr, channelPrefix
+ */
+export interface ElectronChatConfig {
+    /**
+     * 应用数据根目录
+     *
+     * 内部结构（可被 assetsDir 覆盖）：
+     *   dataDir/data/              → SQLite + 搜索索引
+   *   dataDir/assets/skills/     → 技能文件夹
+     *   dataDir/assets/skills-state.json → 技能启用状态（默认）
+     */
+    dataDir: string;
+    /** 资产文件目录，默认 dataDir/assets */
+    assetsDir?: string;
+    /** 元数据存储（技能启用状态等），不传则用 skills-state.json */
+    metadataStore?: AssetMetadataStore;
+    /** LLM 模型配置 */
+    llm: LLMConfig;
+    /** 最大模型轮次（可选，默认不限制） */
+    maxIterations?: number;
+    /** 最大总执行时长，单位毫秒（可选，默认不限制） */
+    maxDurationMs?: number;
+    /** 最大工具调用次数（可选，默认不限制） */
+    maxToolCalls?: number;
+    /** 最大累计 token 数（可选，默认不限制） */
+    maxTotalTokens?: number;
+    /** 代码级工具（Agent 启动即可用） */
+    tools?: (Tool | ToolPlugin)[];
+    /** 预加载的工具引用（支持 id / alias / 原始名称） */
+    preloadTools?: string[] | true;
+    /** ASR 语音识别（可选） */
+    asr?: AsrConfig;
+    /** IPC channel 前缀，默认 'ai-chat' */
+    channelPrefix?: string;
+    /** 当前工作目录 */
+    cwd?: string;
+    /** 默认租户上下文 */
+    defaultContext?: StorageContext;
+    /** 宿主提供的 better-sqlite3 工厂 */
+    sqliteFactory: SqliteDatabaseFactory;
+    /** 发送消息前钩子 */
+    beforeChat?: (options: ChatOptions) => ChatOptions | Promise<ChatOptions>;
+    /** 宿主应用注入的数据引擎接口（可选，传递给 ToolContext.dataEngine） */
+    dataEngine?: DataEngineContext;
+}
+/** createElectronChat 返回值 */
+export interface ElectronChat {
+    /** ChatRuntime 实例 */
+    agent: unknown;
+    /** 持久化存储 */
+    storage: StorageAdapter;
+    /** 统一资产管理器 */
+    assetManager: AssetManager;
+}
+/**
+ * 创建 Electron AI Chat 实例（声明式一步到位）
+ *
+ * 内部自动完成：
+ * 1. assetManager（工具注册 + 技能扫描 + 预加载）
+ * 2. createElectronBridge（Agent + IPC + Storage）
+ * 3. manager.bind(agent)（运行时工具注入）
+ * 4. createAsrBridge（语音识别，可选）
+ * 5. 技能内容自动注入 system prompt（通过 beforeChat 组合）
+ */
+export declare function createElectronChat(config: ElectronChatConfig): Promise<ElectronChat>;

package/dist/main/index.d.ts

@@ -1,169 +1,13 @@
-import { AgentConfig, ToolConfigItem, ChatOptions, HybridAgent } from '@huyooo/ai-chat-core';
-export { AgentConfig, ChatEvent, ChatMode, ChatOptions, MODELS, ProviderType } from '@huyooo/ai-chat-core';
-import { StorageContext, StorageAdapter } from '@huyooo/ai-chat-storage';
-export { MessageRecord, SessionRecord, StorageAdapter, StorageContext } from '@huyooo/ai-chat-storage';
-
-/** ASR 请求配置 */
-interface AsrRequestConfig {
-    /** 用户相关配置 */
-    user?: {
-        uid?: string;
-        did?: string;
-        platform?: string;
-        sdk_version?: string;
-        app_version?: string;
-    };
-    /** 音频配置 */
-    audio: {
-        format: 'pcm' | 'wav' | 'ogg' | 'mp3';
-        codec?: 'raw' | 'opus';
-        rate?: number;
-        bits?: number;
-        channel?: number;
-        /** 语种（仅流式输入模式支持） */
-        language?: string;
-    };
-    /** 请求配置 */
-    request: {
-        model_name: 'bigmodel';
-        /** 启用 ITN（数字规整） */
-        enable_itn?: boolean;
-        /** 启用标点 */
-        enable_punc?: boolean;
-        /** 启用语义顺滑 */
-        enable_ddc?: boolean;
-        /** 输出语音停顿、分句、分词信息 */
-        show_utterances?: boolean;
-        /** 结果返回方式：full(全量)/single(增量) */
-        result_type?: 'full' | 'single';
-        /** 启用首字返回加速 */
-        enable_accelerate_text?: boolean;
-        /** 首字返回加速率 (0-20) */
-        accelerate_score?: number;
-        /** 语义切句最大静音阈值 (ms) */
-        vad_segment_duration?: number;
-        /** 强制判停时间 (ms) */
-        end_window_size?: number;
-        /** 热词等语料配置 */
-        corpus?: {
-            boosting_table_name?: string;
-            boosting_table_id?: string;
-            correct_table_name?: string;
-            correct_table_id?: string;
-            context?: string;
-        };
-    };
-}
-/** ASR 识别结果 */
-interface AsrResult {
-    result?: {
-        text: string;
-        utterances?: Array<{
-            text: string;
-            start_time: number;
-            end_time: number;
-            definite: boolean;
-            words?: Array<{
-                text: string;
-                start_time: number;
-                end_time: number;
-                blank_duration: number;
-            }>;
-        }>;
-    };
-    audio_info?: {
-        duration: number;
-    };
-}
-
-/**
- * 火山引擎大模型流式语音识别 - WebSocket 客户端
- *
- * 在 Electron 主进程中运行，处理与火山引擎 ASR 服务的通信
- */
-
-/** ASR 客户端配置 */
-interface AsrClientConfig {
-    /** 火山引擎 App ID */
-    appId: string;
-    /** 火山引擎 Access Key */
-    accessKey: string;
-    /** 资源 ID */
-    resourceId?: string;
-    /** 使用双向流式优化版 */
-    useAsyncMode?: boolean;
-}
-/** ASR 事件回调 */
-interface AsrCallbacks {
-    /** 连接成功 */
-    onConnected?: () => void;
-    /** 收到识别结果 */
-    onResult?: (result: AsrResult, isLast: boolean) => void;
-    /** 发生错误 */
-    onError?: (error: Error) => void;
-    /** 连接关闭 */
-    onClose?: () => void;
-}
-/** ASR 会话配置 */
-interface AsrSessionConfig {
-    /** 音频格式 */
-    format?: 'pcm' | 'wav';
-    /** 采样率 */
-    sampleRate?: number;
-    /** 启用标点 */
-    enablePunc?: boolean;
-    /** 启用 ITN（数字规整） */
-    enableItn?: boolean;
-    /** 启用语义顺滑 */
-    enableDdc?: boolean;
-    /** 输出分句信息 */
-    showUtterances?: boolean;
-}
-
-/**
- * ASR 模块导出
- */
-
-/** ASR 桥接配置 */
-interface AsrBridgeConfig {
-    /** IPC channel 前缀 */
-    channelPrefix?: string;
-    /** 火山引擎 App ID */
-    appId: string;
-    /** 火山引擎 Access Key */
-    accessKey: string;
-    /** 资源 ID */
-    resourceId?: string;
-}
-/**
- * 创建 ASR Electron 桥接
- *
- * 在主进程中调用，注册 ASR 相关的 IPC handlers
- *
- * @example
- * ```ts
- * import { createAsrBridge } from '@huyooo/ai-chat-bridge-electron/main';
- *
- * createAsrBridge({
- *   appId: process.env.VOLC_APP_ID!,
- *   accessKey: process.env.VOLC_ACCESS_KEY!,
- * });
- * ```
- */
-declare function createAsrBridge(config: AsrBridgeConfig): {
-    /** 清理所有会话 */
-    cleanup: () => void;
-};
-
 /**
  * Electron 主进程桥接
  *
  * 在主进程中调用，注册 IPC handlers
  * 集成 SQLite 存储
  */
-
+import { ChatRuntime, buildModelOptions, type LLMConfig, type ChatEvent, type ChatOptions, type ChatMode, type ProtocolId, type ToolConfigItem, type ModelOption, type McpServerConfig, type DataEngineContext, type ToolExecutionAuditHooks } from '@huyooo/ai-chat-core';
+import type { AtResolvedFileContext } from '@huyooo/ai-chat-types';
 /** 文件信息 */
-interface FileInfo {
+export interface FileInfo {
     name: string;
     path: string;
     isDirectory: boolean;
@@ -171,12 +15,22 @@ interface FileInfo {
     modifiedAt: Date;
     extension: string;
 }
-
-interface ElectronBridgeOptions extends Omit<AgentConfig, 'tools'> {
+import { type StorageAdapter, type StorageContext, type SqliteDatabaseFactory, type SessionRecord, type MessageRecord } from '@huyooo/ai-chat-storage';
+export interface ElectronBridgeOptions {
+    /** 统一 LLM 配置（endpoints + models 降级链） */
+    llmConfig: LLMConfig;
+    /** 当前工作目录 */
+    cwd?: string;
+    /** 最大模型轮次（可选，默认不限制） */
+    maxIterations?: number;
+    /** 最大总执行时长，单位毫秒（可选，默认不限制） */
+    maxDurationMs?: number;
+    /** 最大工具调用次数（可选，默认不限制） */
+    maxToolCalls?: number;
+    /** 最大累计 token 数（可选，默认不限制） */
+    maxTotalTokens?: number;
     /** IPC channel 前缀 */
     channelPrefix?: string;
-    /** Tavily API Key（用于统一 Web Search；可选） */
-    tavilyApiKey?: string;
     /**
      * 统一数据目录（必填）
      * 所有数据都存储在此目录下：
@@ -186,16 +40,75 @@ interface ElectronBridgeOptions extends Omit<AgentConfig, 'tools'> {
     dataDir: string;
     /** 默认租户上下文 */
     defaultContext?: StorageContext;
+    /** 宿主提供的 better-sqlite3 工厂 */
+    sqliteFactory: SqliteDatabaseFactory;
     /**
      * 工具列表（Vite 插件风格）
      * 支持：ToolPlugin、Promise<ToolPlugin>
      */
     tools?: ToolConfigItem[];
+    /**
+     * 外部 MCP Server（stdio / HTTP 等），由 ChatRuntime 连接并注册工具到会话
+     */
+    mcpServers?: McpServerConfig[];
     /**
      * 发送消息前的钩子（可注入额外 options，如本地 Skills 内容）
      * 返回修改后的 options，或 undefined 保持不变
      */
     beforeChat?: (options: ChatOptions) => ChatOptions | Promise<ChatOptions>;
+    /** 宿主应用注入的数据引擎接口（可选，传递给 ToolContext.dataEngine） */
+    dataEngine?: DataEngineContext;
+    /** 宿主应用注入的审计钩子（可选，桥接层只负责传递会话/请求边界） */
+    audit?: {
+        startTurn(input: {
+            conversationId?: string | null;
+            model?: string | null;
+            mode?: string | null;
+            userMessage?: string | null;
+            metadata?: Record<string, unknown>;
+        }): string;
+        finishTurn(input: {
+            turnId: string;
+            eventCount?: number;
+            completedAt?: string;
+        }): void;
+        failTurn(input: {
+            turnId: string;
+            eventCount?: number;
+            completedAt?: string;
+            error: unknown;
+        }): void;
+        runWithContext<T>(context: {
+            conversationId?: string | null;
+            turnId?: string | null;
+        }, fn: () => T): T;
+        recordToolApprovalRequest?(input: {
+            id: string;
+            name: string;
+            toolName?: string | null;
+            extensionId?: string | null;
+            displayName?: string | null;
+            args: Record<string, unknown>;
+            context?: {
+                conversationId?: string | null;
+                turnId?: string | null;
+            };
+        }): void;
+        recordToolApprovalResponse?(input: {
+            id: string;
+            name?: string | null;
+            toolName?: string | null;
+            extensionId?: string | null;
+            displayName?: string | null;
+            approved: boolean;
+            context?: {
+                conversationId?: string | null;
+                turnId?: string | null;
+            };
+        }): void;
+    } & ToolExecutionAuditHooks;
+    /** 宿主提供的 @ 文件上下文解析器（可选，用于 PDF/Docx/Notebook 等高级解析） */
+    resolveAtFileContext?: (filePath: string) => Promise<AtResolvedFileContext | null>;
 }
 /**
  * 创建 Electron IPC 桥接
@@ -206,15 +119,21 @@ interface ElectronBridgeOptions extends Omit<AgentConfig, 'tools'> {
  *
  * app.whenReady().then(async () => {
  *   const { agent, storage } = await createElectronBridge({
- *     arkApiKey: 'xxx',
- *     geminiApiKey: 'xxx',
+ *     llmConfig: { endpoints: {...}, models: {...} },
+ *     dataDir: '/path/to/data',
+ *     sqliteFactory: (sqlitePath) => new Database(sqlitePath),
  *   });
  * });
  * ```
  */
-declare function createElectronBridge(options: ElectronBridgeOptions): Promise<{
-    agent: HybridAgent;
+export declare function createElectronBridge(options: ElectronBridgeOptions): Promise<{
+    agent: ChatRuntime;
     storage: StorageAdapter;
 }>;
-
-export { type AsrBridgeConfig, type AsrCallbacks, type AsrClientConfig, type AsrRequestConfig, type AsrResult, type AsrSessionConfig, type ElectronBridgeOptions, type FileInfo, createAsrBridge, createElectronBridge };
+export type { LLMConfig, ChatEvent, ChatOptions, ChatMode, ProtocolId, ModelOption, StorageAdapter, StorageContext, SessionRecord, MessageRecord, };
+export { buildModelOptions };
+export { createAsrBridge, type AsrBridgeConfig } from './asr';
+export type { AsrClientConfig, AsrSessionConfig, AsrCallbacks } from './asr/client';
+export type { AsrResult, AsrRequestConfig } from './asr/protocol';
+export { createElectronChat } from './create-electron-chat';
+export type { ElectronChatConfig, ElectronChat, AsrConfig } from './create-electron-chat';