keepwork-sdk 1.0.0

package/dist-npm/types/src/ai-chat/AIGenerators.media.d.ts

@@ -0,0 +1,208 @@
+/**
+ * AIGenerators.media.ts — 图片/视频生成层
+ *
+ * 继承 AIGeneratorsBase，添加：
+ * - genImage（Keepwork proxy + 直连 OpenAI/Google/OpenRouter）
+ * - genVideo（Keepwork proxy + OpenRouter 直连）
+ * - getVideoTaskStatus / pollVideoTask
+ * - CloudDrive 上传辅助（_maybeUploadDataURI）
+ * - OpenRouter 视频直连辅助（_genVideoOpenRouter / _pollVideoTaskOpenRouter 等）
+ * - 图片相关辅助（_toOpenRouterImageParts / _buildOpenRouterImageMessages 等）
+ */
+import { AIGeneratorsBase, type AIGeneratorsSDKRef, type GenChatOptions } from './AIGenerators.base';
+/** genImage 选项 */
+export interface GenImageOptions {
+    width?: number;
+    height?: number;
+    provider?: string;
+    apiKey?: string;
+    model?: string;
+    compressionRatio?: number;
+    images?: Array<{
+        url?: string;
+        image_url?: {
+            url: string;
+        };
+        role?: string;
+    }>;
+    /** 是否上传 data URI 到 Keepwork CDN（默认 true） */
+    uploadResultToKeepwork?: boolean;
+    fileName?: string;
+    /** CloudDrive 临时文件生命周期天数（默认 180） */
+    expire?: number;
+    preferDirect?: boolean;
+    directOnly?: boolean;
+    directProvider?: string;
+    aspectRatio?: string;
+    aspect_ratio?: string;
+    imageSize?: string;
+    image_size?: string;
+    size?: string;
+    modalities?: string[];
+    outputModalities?: string[];
+    output_modalities?: string[];
+    onMessage?: GenChatOptions['onMessage'];
+    onReasoning?: GenChatOptions['onReasoning'];
+    onImage?: GenChatOptions['onImage'];
+    extraHeaders?: Record<string, string>;
+    stream?: boolean;
+    [key: string]: unknown;
+}
+/** genVideo 选项 */
+export interface GenVideoOptions {
+    model?: string;
+    duration?: number;
+    resolution?: string;
+    ratio?: string;
+    size?: string;
+    generateAudio?: boolean;
+    watermark?: boolean;
+    seed?: number;
+    apiKey?: string;
+    images?: Array<{
+        url?: string;
+        role?: string;
+    }>;
+    videos?: Array<{
+        url?: string;
+        role?: string;
+    }>;
+    audios?: Array<{
+        url?: string;
+        role?: string;
+    }>;
+    directLink?: boolean;
+    preferDirect?: boolean;
+    directOnly?: boolean;
+    extraHeaders?: Record<string, string>;
+    providerOptions?: Record<string, unknown>;
+    callbackUrl?: string;
+    [key: string]: unknown;
+}
+/** 视频任务状态 */
+export interface VideoTaskStatus {
+    status: 'succeeded' | 'failed' | 'pending' | 'in_progress' | 'timeout' | 'cancelled' | 'expired' | string;
+    videoUrl?: string;
+    contentUrl?: string;
+    duration?: number;
+    usage?: unknown;
+    error?: string | object;
+    raw?: unknown;
+}
+/** pollVideoTask 回调 */
+export interface PollVideoCallbacks {
+    onStatus?: (status: string, data: unknown) => void;
+    interval?: number;
+    timeout?: number;
+    apiKey?: string;
+    model?: string;
+    directLink?: boolean;
+}
+/**
+ * AIGenerators — 继承自 AIGeneratorsBase，提供图片/视频生成能力。
+ */
+declare class AIGenerators extends AIGeneratorsBase {
+    constructor(sdk: AIGeneratorsSDKRef);
+    /** 推断图片生成 provider（优先 caller > model 自动检测，默认 seedream）。 */
+    _inferImageProvider(model?: string, provider?: string): string;
+    /**
+     * 将参考图片列表转换为 OpenRouter chat-completions 格式的 image_url parts。
+     */
+    _toOpenRouterImageParts(images?: Array<{
+        url?: string;
+        image_url?: {
+            url: string;
+        };
+        [key: string]: unknown;
+    }>): Array<{
+        type: string;
+        image_url: {
+            url: string;
+        };
+    }>;
+    /** 构建包含参考图片的 OpenRouter 多模态 user 消息。 */
+    _buildOpenRouterImageMessages(prompt: string, images?: GenImageOptions['images']): Array<{
+        role: string;
+        content: unknown;
+    }>;
+    /** 从 caller opts 构建 OpenRouter image_config（aspect_ratio + image_size）。 */
+    _buildOpenRouterImageConfig(opts?: GenImageOptions): {
+        aspect_ratio?: string;
+        image_size?: string;
+    } | null;
+    /** 根据 model 决定 OpenRouter 图片生成的 output modalities。 */
+    _buildOpenRouterImageModalities(model: string, opts?: GenImageOptions): string[];
+    /** 构建图片生成失败时的详细错误信息。 */
+    _buildNoImageError(data: unknown, model?: string): string;
+    /**
+     * 生成图片（via Keepwork genImage API 或直连 provider）。
+     *
+     * 路由逻辑：
+     * 1. 有 apiKey + preferDirect → 直连（OpenAI / Google / OpenRouter）
+     * 2. directOnly 但无 key → 抛出
+     * 3. 其余 → 通过 Keepwork proxy
+     *
+     * @param prompt - 图片描述
+     * @param opts   - 尺寸 / provider / apiKey / model / 参考图片等
+     * @returns 生成的图片 URL（或 data URI）
+     */
+    genImage(prompt: string, opts?: GenImageOptions): Promise<string | null>;
+    /** @private 直连 provider 生成图片的分发器。 */
+    private _genImageDirect;
+    private _genImageOpenAI;
+    private _genImageGoogle;
+    private _genImageOpenRouter;
+    /**
+     * 将 data URI 上传到 Keepwork CDN（默认行为）。
+     * 优先使用用户个人 CloudDrive，失败时回退 tempvision bucket。
+     * 传入 `uploadResultToKeepwork:false` 保留原始 data URI。
+     */
+    _maybeUploadDataURI(dataURI: string, opts?: {
+        uploadResultToKeepwork?: boolean;
+        fileName?: string;
+        expire?: number;
+    }): Promise<string>;
+    private _uploadDataURIToCloudDrive;
+    /**
+     * 提交视频生成任务（via Keepwork genVideo API 或 OpenRouter 直连）。
+     *
+     * @param prompt - 视频描述
+     * @param opts   - 时长 / 分辨率 / 宽高比 / 参考图片 / provider 等
+     * @returns taskId 字符串（OpenRouter 任务以 `openrouter:` 前缀标识）
+     */
+    genVideo(prompt: string, opts?: GenVideoOptions): Promise<string>;
+    /**
+     * 单次轮询视频生成任务状态。
+     * 支持 Keepwork 任务 ID 和 `openrouter:` 前缀的 OpenRouter 任务 ID。
+     */
+    getVideoTaskStatus(taskId: string, opts?: {
+        apiKey?: string;
+        model?: string;
+    }): Promise<VideoTaskStatus>;
+    /**
+     * 持续轮询视频任务直到完成或失败。
+     * 支持 Keepwork 任务 ID 和 `openrouter:` 前缀 ID。
+     *
+     * @param taskId    - 任务 ID
+     * @param callbacks - onStatus / interval / timeout / apiKey / model / directLink
+     */
+    pollVideoTask(taskId: string, callbacks?: PollVideoCallbacks): Promise<VideoTaskStatus>;
+    private _genVideoOpenRouter;
+    _extractOpenRouterErrorMessage(data: unknown): string;
+    _resolveOpenRouterApiKey(opts?: {
+        apiKey?: string;
+        model?: string;
+    }): string;
+    /** 从 taskId 中剥离 'openrouter:' 前缀得到 OpenRouter jobId（保持与重构前 AIGenerators.js 原型方法一致）。 */
+    _openRouterJobIdFromTaskId(taskId: unknown): string;
+    _normalizeOpenRouterVideoStatus(data: Record<string, unknown>): VideoTaskStatus & {
+        contentUrl?: string;
+    };
+    _resolveOpenRouterVideoDirectLink(contentUrl: string | undefined, apiKey: string, opts?: {
+        directLink?: boolean;
+    }): Promise<string | undefined>;
+    private _getVideoTaskStatusOpenRouter;
+    private _pollVideoTaskOpenRouter;
+}
+export default AIGenerators;
+//# sourceMappingURL=AIGenerators.media.d.ts.map

package/dist-npm/types/src/ai-chat/AIGenerators.media.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AIGenerators.media.d.ts","sourceRoot":"","sources":["../../../../src/ai-chat/AIGenerators.media.ts"],"names":[],"mappings":"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"}

package/dist-npm/types/src/ai-chat/ChildSessionMixin.d.ts

@@ -0,0 +1,153 @@
+/**
+ * ChildSessionMixin.ts — 子 agent 会话共享逻辑
+ *
+ * 向任意 session 类（ChatSession、RTCChatSession 等）注入子 agent 状态和方法。
+ * 子 session 始终是通过 `sdk.aiChat.createSession()` 创建的文本型 ChatSession。
+ *
+ * ## 使用方式
+ * ```ts
+ * // 构造函数中：
+ * initChildSessionState(this, options);
+ *
+ * // prototype 上（只需一次）：
+ * Object.assign(MySession.prototype, childSessionMethods);
+ * ```
+ *
+ * ## 宿主类要求
+ * - `this.sdk` — KeepworkSDK 实例（需有 `.aiChat.createSession()`）
+ * - `this.model` — 默认模型名称
+ * - `this.options` — 会话选项（可含 `.enableTools`）
+ * - `this._triggerImmediateCallback()` — **必须**在宿主类中覆盖实现
+ */
+/** 子任务对象 */
+export interface ChildTask {
+    id: string;
+    task: string;
+    description: string | null;
+    tools: string[];
+    maxIterations: number;
+    systemPrompt: string | null;
+    model: string | null;
+    thinking: unknown;
+    callbackMode: string;
+    debounceSeconds: number;
+    resolve: (value: unknown) => void;
+    reject: (reason: unknown) => void;
+    promise: Promise<unknown>;
+}
+/** 子 session 注册表条目 */
+export interface ChildSessionEntry {
+    session: ChildSessionHost;
+    queue: ChildTask[];
+    isRunning: boolean;
+}
+/** 待处理子 agent 结果 */
+export interface PendingChildResult {
+    agentName: string;
+    taskId: string;
+    taskSummary: string;
+    result: unknown;
+}
+/** 子 agent 流式事件 */
+export interface ChildStreamEvent {
+    agentPath: string;
+    agentName: string;
+    taskId: string;
+    type: 'message' | 'toolCall' | 'complete' | 'error' | string;
+    content: unknown;
+    fullResponse?: unknown;
+}
+/** 宿主 session 最小接口（避免循环引用） */
+export interface ChildSessionHost {
+    name?: string | null;
+    parentSession?: ChildSessionHost | null;
+    sdk?: unknown;
+    aiChat?: {
+        sdk?: unknown;
+        createSession?: (opts: unknown) => ChildSessionHost;
+    };
+    model?: string;
+    workspace?: string | null;
+    sandbox?: unknown;
+    options?: {
+        enableTools?: string[];
+        [key: string]: unknown;
+    };
+    customTools?: unknown[];
+    enabledToolCategories?: string[];
+    messages?: Array<{
+        role: string;
+        content: string;
+    }>;
+    _history?: unknown[];
+    _childSessions: Record<string, ChildSessionEntry>;
+    _pendingChildResults: PendingChildResult[];
+    _debounceTimers: ReturnType<typeof setTimeout>[];
+    _isSending: boolean;
+    _lastSendOptions: Record<string, unknown>;
+    _maxChildSessions: number;
+    _depth: number;
+    _maxDepth: number;
+    onChildStream: ((event: ChildStreamEvent) => void) | null;
+    _triggerImmediateCallback(): Promise<void>;
+    send?: (msg: unknown, opts?: unknown) => Promise<unknown>;
+    clear?: () => void;
+}
+/** initChildSessionState 选项 */
+export interface ChildSessionInitOptions {
+    name?: string;
+    parentSession?: ChildSessionHost | null;
+    onChildStream?: ((event: ChildStreamEvent) => void) | null;
+    _depth?: number;
+    _maxDepth?: number;
+    [key: string]: unknown;
+}
+/** 生成 UUID v4（浏览器原生优先）。 */
+export declare function _generateUUID(): string;
+/**
+ * 将值截断为可读摘要字符串，用于日志输出。
+ * @param value     - 任意值
+ * @param maxLength - 截断字符数（默认 180）
+ */
+export declare function _summarize(value: unknown, maxLength?: number): string;
+/**
+ * 在 session 实例上初始化子 agent 状态字段。
+ * 在宿主类构造函数内调用。
+ *
+ * @param self    - session 实例（`this`）
+ * @param options - 构造选项
+ */
+export declare function initChildSessionState(self: ChildSessionHost, options?: ChildSessionInitOptions): void;
+/**
+ * 要注入到宿主类 prototype 的子 agent 方法集。
+ *
+ * 宿主类最低要求：
+ * - `this.sdk`（或 `this.aiChat`）——有 `.aiChat.createSession()`
+ * - `this.model`——默认模型名
+ * - `this.options`——选项（可含 `enableTools`）
+ * - `this._triggerImmediateCallback()`——**必须在宿主类中覆盖**
+ */
+export declare const childSessionMethods: Partial<ChildSessionHost> & {
+    createChildSession(name: string, options?: Record<string, unknown>): ChildSessionEntry;
+    enqueueChildTask(name: string, task: string, tools?: string[], maxIterations?: number, systemPrompt?: string, extra?: Record<string, unknown>): Promise<unknown>;
+    _processChildQueue(name: string): Promise<void>;
+    _buildAgentPath(childName: string): string;
+    _emitChildStream(event: ChildStreamEvent): void;
+    _bubbleChildStream(event: ChildStreamEvent): void;
+    _consumePendingChildResults(): PendingChildResult[];
+    _handleChildCallback(mode: string, debounceSeconds?: number): void;
+    _triggerImmediateCallback(): Promise<void>;
+    _triggerDebounceCallback(seconds?: number): void;
+    _cancelDebounceTimers(): void;
+    getParentContext(messageCount?: number): {
+        systemPrompt: string | null;
+        recentMessages: unknown[];
+        model?: string;
+        workspace?: string | null;
+    } | null;
+    getChildSession(name: string): ChildSessionEntry | undefined;
+    getChildSessionNames(): string[];
+    _cleanupChildSessions(): void;
+};
+export { initChildSessionState as default };
+//# sourceMappingURL=ChildSessionMixin.d.ts.map

package/dist-npm/types/src/ai-chat/ChildSessionMixin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChildSessionMixin.d.ts","sourceRoot":"","sources":["../../../../src/ai-chat/ChildSessionMixin.ts"],"names":[],"mappings":"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"}

package/dist-npm/types/src/ai-chat/CopilotTools.d.ts

@@ -0,0 +1,150 @@
+/**
+ * CopilotTools.ts — AI 工具分类注册与调度中心（TypeScript 版）
+ *
+ * 管理所有可供 AI 会话使用的工具分类（category），提供：
+ * - `registerToolCategory()`：注册自定义工具分类（含 definitions / executor / onConfig）
+ * - `getToolDefinitions()`：按分类名获取 OpenAI 格式工具定义（支持按函数名过滤和排除）
+ * - `execute()`：按函数名分发工具调用到对应分类的 executor
+ * - `resolveEnabledCategories()`：将 toolsConfig 对象解析为分类名数组
+ * - `setToolConfig()`：更新分类的运行时配置
+ *
+ * ## 内置工具分类
+ * | 分类名       | 工具                        |
+ * |-------------|----------------------------|
+ * | mqtt         | mqtt_publish/get/subscribe  |
+ * | read         | read_file, list_dir         |
+ * | edit         | replace_string_in_file, create_file, multi_replace |
+ * | search       | grep_search                 |
+ * | fileOps      | read + edit + search 合集   |
+ * | execute      | run_app_cmd                 |
+ * | web          | fetch_webpage               |
+ * | personalPage | personal_page_load/save     |
+ * | agent        | runAsyncAgentTask 等        |
+ * | app          | read_app, click_element 等  |
+ * | summarize    | summarize_conversation 等   |
+ */
+import AppTools from '../tools/AppTools';
+/** 工具函数定义（OpenAI Function Calling 格式） */
+export interface ToolDefinition {
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+}
+/** 工具分类注册表条目 */
+export interface ToolCategoryEntry {
+    definitions: ToolDefinition[];
+    /** 工具执行器（fnName, fnArgs, config） => result */
+    executor: (fnName: string, fnArgs: unknown, config?: unknown) => Promise<unknown>;
+    /** 运行时配置更新回调 */
+    onConfig?: (config: unknown) => void;
+    /**
+     * 为 true 时，此分类的工具不会被 SandboxToolEnv 的分类级代理自动路由；
+     * 需通过 toolProxy.functions 明确指定才会走代理路径。
+     */
+    disableAutoProxy?: boolean;
+}
+/** SDK 最小接口 */
+interface SDKRef {
+    agentRouter?: {
+        instanceId?: string;
+        hasRemoteAgent?: (name: string) => boolean;
+        submitTask?: (name: string, payload: unknown, callbacks?: unknown) => Promise<unknown>;
+    };
+    [key: string]: unknown;
+}
+declare class CopilotTools {
+    /** 工具分类注册表 */
+    _registry: Record<string, ToolCategoryEntry>;
+    /** 函数名 → 主分类名 反向索引 */
+    _fnNameToCategory: Record<string, string>;
+    /** 各分类的运行时配置 */
+    toolConfigs: Record<string, unknown>;
+    /** AppTools 类引用（供外部访问） */
+    static AppTools: typeof AppTools;
+    AppTools: typeof AppTools;
+    private mqttTool;
+    private fileTools;
+    private agentTool;
+    private personalPageTool;
+    private executeTool;
+    private webTool;
+    private summarizeTool;
+    private appTools;
+    constructor(sdk: SDKRef);
+    /**
+     * 注册一个工具分类。
+     *
+     * 同一函数名可属于多个分类；第一个注册该函数名的分类成为其主执行者。
+     * 后续包含同名函数的分类（如 'fileOps' 包含 read/edit/search 中的所有函数）
+     * 仍可通过 `getToolDefinitions` 暴露定义，但执行调度以先注册者为准。
+     *
+     * @param name  - 分类名（如 'mqtt' / 'fileOps'）
+     * @param entry - 分类入口（definitions / executor / onConfig / disableAutoProxy）
+     */
+    registerToolCategory(name: string, entry: ToolCategoryEntry): void;
+    /**
+     * 获取指定分类列表对应的 OpenAI 格式工具定义（去重）。
+     *
+     * 支持格式：
+     * - `"category"`：包含该分类所有函数
+     * - `"category.fnName"`：仅包含指定函数
+     * - `"-category.fnName"`：从完整分类包含中排除指定函数
+     *
+     * @param categoryNames - 分类名数组（空 / undefined 时返回 []）
+     */
+    getToolDefinitions(categoryNames?: string[]): ToolDefinition[];
+    /**
+     * 导出指定分类的工具定义（可序列化格式）。
+     * 供 DigitalHumanFrame 将父级工具定义传入子 iframe。
+     *
+     * @param categoryNames - 要导出的分类（空 / undefined 时导出全部）
+     */
+    getExportableDefinitions(categoryNames?: string[]): Record<string, ToolDefinition[]>;
+    /**
+     * 检查指定函数名是否在任意注册分类中可执行。
+     * @param fnName - 工具函数名
+     */
+    canExecute(fnName: string): boolean;
+    /**
+     * 按函数名执行工具，分发到对应分类的 executor。
+     *
+     * @param fnName - 工具函数名
+     * @param fnArgs - 工具参数
+     * @param config - 运行时配置
+     */
+    execute(fnName: string, fnArgs: unknown, config?: unknown): Promise<unknown>;
+    /**
+     * 将 toolsConfig 对象解析为分类名数组（供 AIChat / SandboxToolEnv 使用）。
+     *
+     * 支持的 key 格式：
+     * - `"category": { enabled: true }` — 启用整个分类
+     * - `"category.fnName": { enabled: true }` — 仅启用该分类中的指定函数
+     * - `"category.fnName": { enabled: false }` — 从完整分类包含中排除指定函数（生成 `-category.fnName` 条目）
+     *
+     * @param toolsConfig - 工具配置对象
+     * @returns 已启用分类名数组（含点分函数名和排除标记）
+     */
+    resolveEnabledCategories(toolsConfig: Record<string, {
+        enabled?: boolean;
+    }>): string[];
+    /**
+     * 设置指定分类的运行时配置。
+     * 支持新名称（'mqtt' / 'personalPage'）和旧别名（'MqttTool' 等）。
+     *
+     * @param categoryName - 分类名或旧别名
+     * @param config       - 运行时配置对象
+     */
+    setToolConfig(categoryName: string, config: unknown): void;
+    /**
+     * 注册所有内置工具分类（构造函数内自动调用）。
+     * 原子分类（read / edit / search）先注册，fileOps 作为合集后注册；
+     * 原子分类的执行优先级高于 fileOps。
+     * @private
+     */
+    private _registerBuiltinTools;
+}
+export default CopilotTools;
+//# sourceMappingURL=CopilotTools.d.ts.map

package/dist-npm/types/src/ai-chat/CopilotTools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CopilotTools.d.ts","sourceRoot":"","sources":["../../../../src/ai-chat/CopilotTools.ts"],"names":[],"mappings":"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"}

package/dist-npm/types/src/ai-chat/MqttManager.d.ts

@@ -0,0 +1,123 @@
+/**
+ * MqttManager.ts — MQTT 客户端管理器
+ *
+ * 运行时按需从 CDN 加载 mqtt.js，封装连接/订阅/发布等操作，
+ * 并通过内置事件系统通知状态变化和消息到达。
+ *
+ * ## 使用示例
+ * ```ts
+ * const mqtt = new MqttManager();
+ * mqtt.on('message', ({ topic, message }) => console.log(topic, message));
+ * await mqtt.connect({ host: 'broker.example.com', port: 8083, topics: ['my/topic'] });
+ * mqtt.publish('my/topic', 'hello');
+ * ```
+ *
+ * 注意：`mqtt.js` 在运行时从 CDN 加载（`window.mqtt`），
+ * 不包含在构建产物中。
+ */
+/** MQTT 连接配置 */
+export interface MqttConfig {
+    /** 协议（默认 'wss'） */
+    protocol?: string;
+    host: string;
+    port: number | string;
+    username?: string;
+    password?: string;
+    /** 客户端 ID（默认随机生成） */
+    clientId?: string;
+    /** KeepAlive 间隔秒数（默认 60） */
+    keepalive?: number;
+    /** 连接成功后自动订阅的 topic 列表 */
+    topics?: string[];
+    /** 兼容旧格式：单个 topic（自动转换为 topics 数组） */
+    topic?: string;
+}
+/** 连接状态 */
+export type MqttStatus = 'disconnected' | 'connecting' | 'connected' | 'error';
+/** message 事件载荷 */
+export interface MqttMessageEvent {
+    topic: string;
+    message: string;
+}
+/** MqttManager 支持的事件类型 */
+export type MqttEventName = 'statusChange' | 'message' | 'error';
+declare class MqttManager {
+    private client;
+    private listeners;
+    private config;
+    private retryCount;
+    private maxRetries;
+    status: MqttStatus;
+    /**
+     * 注册事件监听器。
+     * @param event    - 事件名（'statusChange' | 'message' | 'error'）
+     * @param callback - 回调函数
+     */
+    on(event: MqttEventName, callback: (data: unknown) => void): void;
+    /**
+     * 取消注册事件监听器。
+     * @param event    - 事件名
+     * @param callback - 要取消的回调
+     */
+    off(event: MqttEventName, callback: (data: unknown) => void): void;
+    /** @private 触发事件。 */
+    private emit;
+    /**
+     * 懒加载 mqtt.js（从 CDN）。
+     * 若已加载（window.mqtt 存在）则立即 resolve。
+     */
+    LoadMQTT(): Promise<void>;
+    /**
+     * 建立 MQTT 连接。
+     *
+     * 优先级：传入 config → 上次缓存的 config → localStorage 中保存的 config。
+     * 连接成功后自动订阅 `config.topics`（或 `config.topic`）中的所有 topic。
+     *
+     * @param config - 连接配置（可选，省略时使用缓存配置）
+     */
+    connect(config?: MqttConfig): Promise<void>;
+    /** @private 连接成功回调。 */
+    private OnConnect;
+    /** @private 连接关闭回调。 */
+    private OnClose;
+    /**
+     * @private 收到消息回调（持久化到 localStorage 并触发 message 事件）。
+     */
+    private OnMessage;
+    /**
+     * 断开 MQTT 连接并清理客户端实例。
+     */
+    disconnect(): void;
+    /**
+     * 订阅指定 topic。
+     * 若当前未连接则静默跳过（不抛错）。
+     *
+     * @param topic - MQTT topic 路径
+     */
+    subscribe(topic: string): void;
+    /**
+     * 等待指定 topic 的下一条消息（Promise 封装）。
+     * 若 localStorage 中已有缓存消息则立即 resolve。
+     *
+     * @param topic   - MQTT topic 路径
+     * @param timeout - 超时毫秒数（默认 5000）
+     * @returns 消息字符串
+     */
+    get(topic: string, timeout?: number): Promise<string>;
+    /**
+     * 向指定 topic 发布消息。
+     * 若当前未连接则返回 false。
+     *
+     * @param topic   - MQTT topic 路径
+     * @param message - 消息字符串
+     * @returns 是否成功发布
+     */
+    publish(topic: string, message: string): boolean;
+    /**
+     * 更新连接配置（不立即重连，下次 connect() 时生效）。
+     * @param config - 新的连接配置
+     */
+    setConfig(config: MqttConfig): void;
+}
+export default MqttManager;
+//# sourceMappingURL=MqttManager.d.ts.map

package/dist-npm/types/src/ai-chat/MqttManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MqttManager.d.ts","sourceRoot":"","sources":["../../../../src/ai-chat/MqttManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAQH,gBAAgB;AAChB,MAAM,WAAW,UAAU;IACzB,mBAAmB;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qBAAqB;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4BAA4B;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0BAA0B;IAC1B,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,sCAAsC;IACtC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,WAAW;AACX,MAAM,MAAM,UAAU,GAAG,cAAc,GAAG,YAAY,GAAG,WAAW,GAAG,OAAO,CAAC;AAE/E,mBAAmB;AACnB,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,0BAA0B;AAC1B,MAAM,MAAM,aAAa,GAAG,cAAc,GAAG,SAAS,GAAG,OAAO,CAAC;AAkBjE,cAAM,WAAW;IACf,OAAO,CAAC,MAAM,CAAmC;IACjD,OAAO,CAAC,SAAS,CAAsD;IACvE,OAAO,CAAC,MAAM,CAA2B;IACzC,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,UAAU,CAAK;IACvB,MAAM,EAAE,UAAU,CAAkB;IAIpC;;;;OAIG;IACH,EAAE,CAAC,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI;IAKjE;;;;OAIG;IACH,GAAG,CAAC,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI;IAKlE,qBAAqB;IACrB,OAAO,CAAC,IAAI;IAMZ;;;OAGG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAc/B;;;;;;;OAOG;IACG,OAAO,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAgGjD,uBAAuB;IACvB,OAAO,CAAC,SAAS;IAOjB,uBAAuB;IACvB,OAAO,CAAC,OAAO;IAQf;;OAEG;IACH,OAAO,CAAC,SAAS;IAOjB;;OAEG;IACH,UAAU,IAAI,IAAI;IAWlB;;;;;OAKG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAQ9B;;;;;;;OAOG;IACH,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,SAAO,GAAG,OAAO,CAAC,MAAM,CAAC;IAkCnD;;;;;;;OAOG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO;IAQhD;;;OAGG;IACH,SAAS,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI;CAGpC;AAED,eAAe,WAAW,CAAC"}