weixin-devtools-mcp 0.0.1 → 0.1.1

package/build/MiniProgramContext.d.ts

@@ -0,0 +1,317 @@
+/**
+ * MiniProgramContext - 小程序自动化上下文管理类
+ *
+ * 参考 chrome-devtools-mcp 的 McpContext 设计模式
+ * 统一管理所有状态，提供类型安全的访问方法
+ *
+ * 使用 Collector 模式管理 Console 和 Network 数据
+ */
+import type { MiniProgram, Page, Element } from 'miniprogram-automator';
+import { ConsoleCollector, NetworkCollector } from './collectors/index.js';
+import type { ConsoleEntry, NetworkRequest } from './collectors/index.js';
+import { type ConnectionConnectResult, type ConnectionRequest, type ConnectionStatusSnapshot } from './connection/index.js';
+import type { ToolContext, ConsoleStorage, NetworkStorage, ConsoleMessage, ExceptionMessage } from './tools/ToolDefinition.js';
+import { type ElementMapInfo, type PageSnapshot } from './tools.js';
+/**
+ * MiniProgramContext 配置选项
+ */
+export interface MiniProgramContextOptions {
+    /** 最大保留的导航会话数 */
+    maxNavigations?: number;
+    /** 是否启用详细日志 */
+    verbose?: boolean;
+    /** 快照缓存 TTL（毫秒），默认 5000ms */
+    snapshotCacheTtl?: number;
+}
+/**
+ * MiniProgramContext 类
+ *
+ * 统一管理小程序自动化的所有状态：
+ * - miniProgram 实例
+ * - currentPage 当前页面
+ * - elementMap 元素映射
+ * - consoleCollector Console 数据收集器
+ * - networkCollector 网络请求收集器
+ */
+export declare class MiniProgramContext implements ToolContext {
+    #private;
+    /**
+     * 私有构造函数，使用工厂方法创建实例
+     */
+    private constructor();
+    /**
+     * 工厂方法：创建 MiniProgramContext 实例
+     */
+    static create(options?: MiniProgramContextOptions): MiniProgramContext;
+    /**
+     * 工厂方法：从已有的 MiniProgram 实例创建上下文
+     */
+    static from(miniProgram: MiniProgram, options?: MiniProgramContextOptions): Promise<MiniProgramContext>;
+    /**
+     * 获取 MiniProgram 实例
+     * @throws 如果未连接则抛出错误
+     */
+    getMiniProgram(): MiniProgram;
+    bindConsoleAndExceptionListeners(handlers: {
+        consoleHandler: (msg: {
+            type?: string;
+            args?: unknown[];
+        }) => void;
+        exceptionHandler: (err: {
+            message?: string;
+            stack?: string;
+        }) => void;
+    }): void;
+    /**
+     * 设置 MiniProgram 实例
+     */
+    setMiniProgram(miniProgram: MiniProgram): Promise<void>;
+    /**
+     * 检查是否已连接
+     */
+    isConnected(): boolean;
+    /**
+     * 断开连接，重置状态
+     */
+    disconnect(): void;
+    connectDevtools(request: ConnectionRequest): Promise<ConnectionConnectResult>;
+    reconnectDevtools(request?: ConnectionRequest): Promise<ConnectionConnectResult>;
+    disconnectDevtools(): Promise<ConnectionStatusSnapshot>;
+    getConnectionStatus(options?: {
+        refreshHealth?: boolean;
+    }): Promise<ConnectionStatusSnapshot>;
+    /**
+     * 获取当前页面
+     * @throws 如果未连接或没有当前页面则抛出错误
+     */
+    getCurrentPage(): Page;
+    /**
+     * 设置当前页面
+     */
+    setCurrentPage(page: Page): void;
+    /**
+     * 刷新当前页面引用
+     */
+    refreshCurrentPage(): Promise<Page>;
+    /**
+     * 获取元素映射表（只读）
+     */
+    getElementMap(): ReadonlyMap<string, ElementMapInfo>;
+    /**
+     * 设置元素映射
+     */
+    setElementMapEntry(uid: string, info: ElementMapInfo): void;
+    /**
+     * 批量设置元素映射
+     */
+    setElementMap(map: Map<string, ElementMapInfo>): void;
+    /**
+     * 清空元素映射
+     */
+    clearElementMap(): void;
+    /**
+     * 通过 UID 获取元素
+     * 统一处理：连接检查、快照检查、元素查找、索引定位
+     */
+    getElementByUid(uid: string): Promise<Element>;
+    /**
+     * 获取页面快照（带缓存）
+     *
+     * 缓存策略：
+     * - 在 TTL 内返回缓存的快照（避免重复调用 getPageSnapshot）
+     * - 页面路径变化时自动刷新缓存
+     * - 支持强制刷新
+     *
+     * @param options.forceRefresh 强制刷新缓存
+     * @param options.ttl 覆盖默认 TTL（毫秒）
+     * @returns 页面快照和元素映射
+     */
+    getPageSnapshotCached(options?: {
+        forceRefresh?: boolean;
+        ttl?: number;
+    }): Promise<{
+        snapshot: PageSnapshot;
+        elementMap: Map<string, ElementMapInfo>;
+    }>;
+    /**
+     * 使缓存失效
+     * 在导航后或 DOM 发生变化时调用
+     */
+    invalidateSnapshotCache(): void;
+    /**
+     * 获取缓存状态信息（用于调试）
+     */
+    getSnapshotCacheStatus(): {
+        isCached: boolean;
+        path: string;
+        age: number;
+        elementCount: number;
+        ttl: number;
+    };
+    /**
+     * 获取 Console 收集器（新 API）
+     */
+    getConsoleCollector(): ConsoleCollector;
+    /**
+     * 开始 Console 监听
+     */
+    startConsoleMonitoring(): void;
+    /**
+     * 停止 Console 监听
+     */
+    stopConsoleMonitoring(): void;
+    /**
+     * 检查是否正在监听 Console
+     */
+    isConsoleMonitoring(): boolean;
+    /**
+     * 添加 Console 消息
+     * @returns 分配的 msgid
+     */
+    addConsoleMessage(message: Omit<ConsoleMessage, 'msgid'>): number;
+    /**
+     * 添加异常消息
+     * @returns 分配的 msgid
+     */
+    addExceptionMessage(exception: Omit<ExceptionMessage, 'msgid'>): number;
+    /**
+     * 通过 ID 获取消息
+     */
+    getConsoleMessageById(msgid: number): ConsoleEntry | undefined;
+    /**
+     * 获取所有消息（支持分页和过滤）
+     */
+    getConsoleMessages(options?: {
+        includePreserved?: boolean;
+        types?: string[];
+        pageSize?: number;
+        pageIdx?: number;
+    }): ConsoleEntry[];
+    /**
+     * 在导航时分割存储（保留历史）
+     */
+    splitConsoleAfterNavigation(): void;
+    /**
+     * 清空 Console 消息
+     */
+    clearConsoleMessages(): void;
+    /**
+     * 获取 Network 收集器（新 API）
+     */
+    getNetworkCollector(): NetworkCollector;
+    /**
+     * 开始网络监听
+     */
+    startNetworkMonitoring(): void;
+    /**
+     * 停止网络监听
+     */
+    stopNetworkMonitoring(): void;
+    /**
+     * 检查是否正在监听网络
+     */
+    isNetworkMonitoring(): boolean;
+    /**
+     * 添加网络请求
+     */
+    addNetworkRequest(request: NetworkRequest): number;
+    /**
+     * 更新网络请求
+     */
+    updateNetworkRequest(id: string, updates: Partial<Pick<NetworkRequest, 'statusCode' | 'response' | 'responseHeaders' | 'error' | 'duration' | 'completedAt' | 'success' | 'pending'>>): boolean;
+    /**
+     * 完成网络请求
+     */
+    completeNetworkRequest(id: string, response: {
+        statusCode?: number;
+        data?: unknown;
+        headers?: Record<string, string>;
+        error?: string;
+    }): boolean;
+    /**
+     * 获取网络请求
+     */
+    getNetworkRequests(options?: {
+        type?: 'request' | 'uploadFile' | 'downloadFile' | 'all';
+        urlPattern?: string;
+        successOnly?: boolean;
+        failedOnly?: boolean;
+        since?: string;
+        limit?: number;
+    }): NetworkRequest[];
+    /**
+     * 清空网络请求
+     */
+    clearNetworkRequests(): void;
+    /**
+     * 在导航时分割存储（保留历史）
+     */
+    splitNetworkAfterNavigation(): void;
+    /**
+     * ToolContext 接口：获取 miniProgram
+     */
+    get miniProgram(): MiniProgram | null;
+    /**
+     * ToolContext 接口：设置 miniProgram
+     */
+    set miniProgram(value: MiniProgram | null);
+    /**
+     * ToolContext 接口：获取 currentPage
+     */
+    get currentPage(): Page | null;
+    /**
+     * ToolContext 接口：设置 currentPage
+     */
+    set currentPage(value: Page | null);
+    /**
+     * ToolContext 接口：获取 elementMap
+     */
+    get elementMap(): Map<string, ElementMapInfo>;
+    /**
+     * ToolContext 接口：设置 elementMap
+     */
+    set elementMap(value: Map<string, ElementMapInfo>);
+    /**
+     * ToolContext 接口：获取 consoleStorage（向后兼容适配器）
+     * 将 Collector 数据转换为 ConsoleStorage 格式
+     */
+    get consoleStorage(): ConsoleStorage;
+    /**
+     * ToolContext 接口：设置 consoleStorage（向后兼容适配器）
+     * 注意：这个 setter 主要用于兼容性，新代码应直接使用 Collector
+     */
+    set consoleStorage(value: ConsoleStorage);
+    /**
+     * ToolContext 接口：获取 networkStorage（向后兼容适配器）
+     * 将 Collector 数据转换为 NetworkStorage 格式
+     */
+    get networkStorage(): NetworkStorage;
+    /**
+     * ToolContext 接口：设置 networkStorage（向后兼容适配器）
+     * 注意：这个 setter 主要用于兼容性，新代码应直接使用 Collector
+     */
+    set networkStorage(value: NetworkStorage);
+    /**
+     * ToolContext 接口：获取 connectionStatus
+     */
+    get connectionStatus(): ConnectionStatusSnapshot;
+    /**
+     * ToolContext 接口：设置 connectionStatus（兼容层）
+     */
+    set connectionStatus(value: ConnectionStatusSnapshot);
+    /**
+     * 获取上下文状态摘要（用于调试）
+     */
+    getStatusSummary(): {
+        connected: boolean;
+        hasCurrentPage: boolean;
+        elementCount: number;
+        consoleMonitoring: boolean;
+        consoleMessageCount: number;
+        networkMonitoring: boolean;
+        networkRequestCount: number;
+        snapshotCached: boolean;
+        snapshotCacheAge: number;
+    };
+}
+//# sourceMappingURL=MiniProgramContext.d.ts.map

package/build/MiniProgramContext.d.ts.map

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