@mearl/client 2.1.0 → 2.2.0

package/dist/commands.js

@@ -5,7 +5,7 @@ export const COMMANDS = [
         description: '获取最近的网络请求（mtop 或普通 xhr/fetch）',
         params: [
             { name: 'tabId', type: 'number', description: '目标标签页 ID，从 tab_list 获取' },
-            { name: 'count', type: 'number', description: '返回条数，默认 20' },
+            { name: 'count', type: 'number', description: '返回条数，默认 10' },
             {
                 name: 'source',
                 type: '"mtop" | "requests"',
@@ -61,7 +61,11 @@ export const COMMANDS = [
         description: '获取 API 接口 schema（出入参定义）',
         params: [
             { name: 'api', type: 'string', required: true, description: 'API 名称' },
-            { name: 'type', type: '"schema" | "hsf" | "all"', description: '返回类型，默认 all' },
+            {
+                name: 'fields',
+                type: '("schema" | "hsf")[]',
+                description: '指定返回内容；不填时返回全部可用内容',
+            },
         ],
         examples: [`get_api_schema --payload '{"api":"mtop.trade.order.detail"}'`],
     },
@@ -184,7 +188,7 @@ export const COMMANDS = [
     },
     {
         name: 'browser_release',
-        description: '释放 Agent 对当前浏览器的调试控制，保留浏览器和全部标签页',
+        description: '按用户明确要求释放调试控制和会话级临时效果（含设备/时区模拟），保留浏览器和全部标签页；不用于普通任务收尾',
         examples: ['browser_release', 'browser_release --browser chrome-a'],
     },
     {
@@ -658,7 +662,7 @@ export const COMMANDS = [
     // ── 移动端模拟 ────────────────────────────────────────────────────────────
     {
         name: 'set_device_emulation',
-        description: '把目标 tab 切换为移动端模拟（视口/UA/触摸），等价 DevTools 设备工具栏，作用域 per-tab',
+        description: '把目标 tab 切换为移动端模拟（视口/UA/触摸），等价 DevTools 设备工具栏，作用域 per-tab；需保持调试控制才持续生效',
         params: [
             { name: 'enabled', type: 'boolean', required: true, description: 'true=启用，false=清除' },
             {
@@ -799,4 +803,4 @@ export const COMMANDS = [
         ],
     },
 ];
-export const COMMAND_MAP = new Map(COMMANDS.map(c => [c.name, c]));
+export const COMMAND_MAP = new Map(COMMANDS.map(command => [command.name, command]));

package/dist/generated-browser-action-protocol.d.ts

@@ -0,0 +1,677 @@
+export interface GetRequestsParams {
+    tabId?: number;
+    count?: number;
+    filter?: string;
+    since?: number;
+    includeBody?: boolean;
+    includeHeaders?: boolean;
+    maxBodySize?: number;
+    fields?: string[];
+    keysOnly?: boolean;
+    applyHiddenFilter?: boolean;
+    source?: 'mtop' | 'requests';
+}
+export interface GetLogsParams {
+    tabId?: number;
+    level?: 'log' | 'warn' | 'error' | 'info' | 'all';
+    since?: number;
+    limit?: number;
+    filter?: string;
+}
+export interface GetEventsParams {
+    tabId?: number;
+    source?: 'rum' | 'aplus' | 'arms' | 'all';
+    event_type?: string;
+    filter?: string;
+    since?: number;
+    limit?: number;
+    includeRaw?: boolean;
+}
+export interface SetMockParams {
+    tabId?: number;
+    apiName: string;
+    mockData?: unknown;
+    fields?: Array<{
+        path: string;
+        value: unknown;
+    }>;
+    enabled?: boolean;
+    duration?: number;
+    conditions?: Record<string, unknown>;
+}
+export interface GetMocksParams {
+    tabId?: number;
+    apiName?: string;
+}
+export interface GetApiSchemaParams {
+    api: string;
+    version?: string;
+    fields?: Array<'schema' | 'hsf'>;
+}
+export interface SendRequestParams {
+    url: string;
+    method?: string;
+    headers?: Record<string, string>;
+    params?: Record<string, string>;
+    body?: unknown;
+    withCookies?: boolean;
+    cookieDomain?: string;
+    responseType?: 'json' | 'text' | 'auto';
+    timeout?: number;
+}
+export interface SendMtopRequestParams {
+    api: string;
+    data?: unknown;
+    version?: string;
+    method?: string;
+    appKey?: string;
+    env?: string;
+    timeout?: number;
+}
+export interface TdbankAccountParams {
+    operation?: 'current' | 'list' | 'switch' | 'borrow';
+    pageIndex?: number;
+    refresh?: boolean;
+    query?: string;
+    accountId?: string | number;
+    havanaId?: string | number;
+    site?: string | number;
+    tabId?: number;
+}
+export type BrowserStatus = 'connected' | 'running_disconnected' | 'stopped';
+export interface BrowserInfoBase {
+    browserId: string;
+    name: string;
+    status: BrowserStatus;
+    extensionVersion?: string;
+    nativeHostVersion?: string;
+    transport?: 'extension' | 'cdp';
+}
+export interface RegularBrowserInfo extends BrowserInfoBase {
+    type: 'regular';
+    status: 'connected';
+}
+export interface ManagedBrowserAccount {
+    accountId?: string;
+    loginId?: string;
+    nickname: string;
+}
+export interface ManagedBrowserInfo extends BrowserInfoBase {
+    type: 'managed';
+    headless: boolean;
+    persistent: boolean;
+    cdpPort: number;
+    createdAt: string;
+    account?: ManagedBrowserAccount;
+    copiedCookies?: {
+        domains: string[];
+        count: number;
+    };
+}
+export type BrowserInfo = RegularBrowserInfo | ManagedBrowserInfo;
+export interface BrowserListResult {
+    count: number;
+    connectedCount: number;
+    defaultBrowserId: string | null;
+    browsers: BrowserInfo[];
+}
+export interface SelectBrowserParams {
+    browser?: string;
+}
+export interface SelectBrowserResult {
+    selected: {
+        browserId: string;
+        name: string;
+    } | null;
+    note?: string;
+}
+export interface BrowserReleaseFailure {
+    tabId: number;
+    stage: string;
+    error: string;
+}
+export interface BrowserReleaseResult {
+    released: boolean;
+    hadActiveControl: boolean;
+    transports: Array<'extension' | 'cdp'>;
+    affectedTabIds: number[];
+    failures?: BrowserReleaseFailure[];
+}
+export interface BrowserLaunchParams {
+    name: string;
+    headless?: boolean;
+    userAgentMode?: 'default' | 'desktop';
+    persistent?: boolean;
+    executablePath?: string;
+    url?: string;
+    accountId?: string | number;
+    havanaId?: string | number;
+    site?: string | number;
+    query?: string;
+    tabId?: number;
+    copyCookieDomains?: string[];
+}
+export interface BrowserCloseParams {
+    browser: string;
+    deleteProfile?: boolean;
+}
+export interface SetRuleParams {
+    actionType: 'redirect' | 'block' | 'allow' | 'upgradeScheme' | 'modifyHeaders';
+    filter: string;
+    redirectUrl?: string;
+    requestHeaders?: Array<{
+        header: string;
+        operation: 'set' | 'append' | 'remove';
+        value?: string;
+    }>;
+    responseHeaders?: Array<{
+        header: string;
+        operation: 'set' | 'append' | 'remove';
+        value?: string;
+    }>;
+    initiatorDomains?: string;
+    resourceTypes?: string[];
+    priority?: number;
+    description?: string;
+}
+export interface RulesResult {
+    enabled: boolean;
+    rules: Array<Record<string, unknown>>;
+}
+export interface PageScreenshotParams {
+    tabId?: number;
+    selector?: string;
+    format?: 'png' | 'jpeg';
+    quality?: number;
+}
+export interface PageSelectedElementParams {
+    tabId?: number;
+    includeOuterHTML?: boolean;
+    includeScreenshot?: boolean;
+}
+export type BrowserDevicePresetName = 'iphone-15-pro' | 'iphone-se' | 'pixel-8' | 'ipad-mini' | 'galaxy-s23';
+export interface BrowserEmulationOptions {
+    preset?: BrowserDevicePresetName;
+    width?: number;
+    height?: number;
+    deviceScaleFactor?: number;
+    mobile?: boolean;
+    userAgent?: string;
+    orientation?: 'portrait' | 'landscape';
+    touch?: boolean;
+}
+export interface TabOpenParams {
+    url: string;
+    active?: boolean;
+    closeExisting?: boolean;
+    reuse?: 'never' | 'prefer' | 'require';
+    match?: {
+        urlPattern?: string;
+        ignoreSearch?: boolean;
+        ignoreHash?: boolean;
+        onMultiple?: 'error' | 'first';
+    };
+    restoreFocusOnClose?: boolean;
+    emulation?: BrowserEmulationOptions;
+    group?: string;
+}
+export interface TabCloseParams {
+    tabId: number;
+}
+export interface PageObservationWaitOptions {
+    quietMs?: number;
+    firstChangeTimeoutMs?: number;
+    timeoutMs?: number;
+    navigationGraceMs?: number;
+    navigationTimeoutMs?: number;
+    networkIdleMs?: number;
+    contentReadyAfterMs?: number;
+}
+export interface PageClickParams {
+    tabId?: number;
+    selector?: string;
+    text?: string;
+    point?: {
+        x: number;
+        y: number;
+    };
+    role?: string;
+    exact?: boolean;
+    scope?: string;
+    clickMode?: 'auto' | 'dom' | 'mouse' | 'touch';
+    observe?: PageObservationWaitOptions | false;
+}
+export interface PageTypeParams {
+    tabId?: number;
+    selector: string;
+    text: string;
+    clearFirst?: boolean;
+    observe?: PageObservationWaitOptions | false;
+}
+export interface PageScrollParams {
+    tabId?: number;
+    direction: 'up' | 'down' | 'top' | 'bottom';
+    distance?: number;
+    selector?: string;
+    containerPolicy?: 'self' | 'nearest';
+    observe?: PageObservationWaitOptions | false;
+}
+export interface PageHoverParams {
+    tabId?: number;
+    selector: string;
+    observe?: PageObservationWaitOptions | false;
+}
+export interface PageEvalParams {
+    tabId?: number;
+    expression: string;
+    frameId?: string;
+    awaitPromise?: boolean;
+    observe?: PageObservationWaitOptions;
+}
+export interface PageSnapshotQuery {
+    text?: string;
+    role?: string;
+    exact?: boolean;
+}
+export interface PageSnapshotParams {
+    tabId?: number;
+    depth?: number;
+    maxChars?: number;
+    maxNodes?: number;
+    rootSelector?: string;
+    rootRef?: string;
+    ancestorDepth?: number;
+    query?: PageSnapshotQuery;
+    mode?: 'full' | 'interactive' | 'viewport';
+}
+export interface PagePressParams {
+    tabId?: number;
+    key: string;
+    modifiers?: string[];
+    observe?: PageObservationWaitOptions | false;
+}
+export interface PageWaitParams {
+    tabId?: number;
+    time?: number;
+    selector?: string;
+    condition?: string;
+    timeout?: number;
+    interval?: number;
+}
+export interface PageNavigateParams {
+    tabId?: number;
+    url?: string;
+    refresh?: boolean;
+    history?: 'back' | 'forward';
+}
+export interface PageUploadParams {
+    tabId?: number;
+    selector: string;
+    filePaths: string[];
+    observe?: PageObservationWaitOptions | false;
+}
+export interface PageFramesParams {
+    tabId?: number;
+}
+export interface SetDeviceEmulationParams extends BrowserEmulationOptions {
+    tabId?: number;
+    enabled: boolean;
+    reload?: boolean;
+}
+export interface SetTimezoneParams {
+    tabId?: number;
+    timezone: string;
+}
+export interface SetTimezoneResult {
+    enabled: boolean;
+    timezone: string | null;
+}
+export interface GetCookieParams {
+    tabId?: number;
+    name: string;
+    domain?: string;
+    path?: string;
+}
+export interface GetCookieResult {
+    tabId?: number;
+    url: string;
+    name: string;
+    found: boolean;
+    value?: string;
+    domain?: string;
+    path?: string;
+}
+export interface SetCookieParams {
+    tabId?: number;
+    name: string;
+    value: string;
+    domain?: string;
+    path?: string;
+    reload?: boolean;
+}
+export interface SetCookieResult {
+    tabId?: number;
+    url: string;
+    name: string;
+    domain: string;
+    path: string;
+    reloaded: boolean;
+}
+export interface GetUserInfoParams {
+    detail?: boolean;
+}
+export interface RecordParams {
+    tabId?: number;
+}
+export interface RequestDomainPermissionParams {
+    domain: string;
+}
+export type RunActionName = Exclude<ExtensionBrowserAction, 'run_actions' | 'browser_release'>;
+export interface ActionStep {
+    action: RunActionName;
+    data?: Record<string, unknown>;
+}
+export interface RunActionsParams {
+    actions: ActionStep[];
+    tabId: number;
+}
+export interface BrowserActionMap {
+    get_requests: {
+        request: GetRequestsParams;
+        response: unknown;
+    };
+    get_logs: {
+        request: GetLogsParams;
+        response: unknown;
+    };
+    get_events: {
+        request: GetEventsParams;
+        response: unknown;
+    };
+    get_api_schema: {
+        request: GetApiSchemaParams;
+        response: unknown;
+    };
+    set_mock: {
+        request: SetMockParams;
+        response: unknown;
+    };
+    get_mocks: {
+        request: GetMocksParams;
+        response: unknown;
+    };
+    set_rule: {
+        request: SetRuleParams;
+        response: unknown;
+    };
+    get_rules: {
+        request: undefined;
+        response: RulesResult;
+    };
+    send_request: {
+        request: SendRequestParams;
+        response: unknown;
+    };
+    send_mtop_request: {
+        request: SendMtopRequestParams;
+        response: unknown;
+    };
+    tdbank_account: {
+        request: TdbankAccountParams;
+        response: unknown;
+    };
+    browser_list: {
+        request: undefined;
+        response: BrowserListResult;
+    };
+    browser_select_browser: {
+        request: SelectBrowserParams;
+        response: SelectBrowserResult;
+    };
+    browser_release: {
+        request: undefined;
+        response: BrowserReleaseResult;
+    };
+    browser_launch: {
+        request: BrowserLaunchParams;
+        response: unknown;
+    };
+    browser_close: {
+        request: BrowserCloseParams;
+        response: unknown;
+    };
+    page_screenshot: {
+        request: PageScreenshotParams;
+        response: unknown;
+    };
+    page_selected_element: {
+        request: PageSelectedElementParams;
+        response: unknown;
+    };
+    tab_open: {
+        request: TabOpenParams;
+        response: unknown;
+    };
+    tab_close: {
+        request: TabCloseParams;
+        response: unknown;
+    };
+    tab_list: {
+        request: undefined;
+        response: unknown;
+    };
+    page_click: {
+        request: PageClickParams;
+        response: unknown;
+    };
+    page_type: {
+        request: PageTypeParams;
+        response: unknown;
+    };
+    page_scroll: {
+        request: PageScrollParams;
+        response: unknown;
+    };
+    page_hover: {
+        request: PageHoverParams;
+        response: unknown;
+    };
+    page_eval: {
+        request: PageEvalParams;
+        response: unknown;
+    };
+    page_snapshot: {
+        request: PageSnapshotParams;
+        response: unknown;
+    };
+    page_press: {
+        request: PagePressParams;
+        response: unknown;
+    };
+    page_wait: {
+        request: PageWaitParams;
+        response: unknown;
+    };
+    page_navigate: {
+        request: PageNavigateParams;
+        response: unknown;
+    };
+    page_upload: {
+        request: PageUploadParams;
+        response: unknown;
+    };
+    page_frames: {
+        request: PageFramesParams;
+        response: unknown;
+    };
+    set_device_emulation: {
+        request: SetDeviceEmulationParams;
+        response: unknown;
+    };
+    set_timezone: {
+        request: SetTimezoneParams;
+        response: SetTimezoneResult;
+    };
+    get_cookie: {
+        request: GetCookieParams;
+        response: GetCookieResult;
+    };
+    set_cookie: {
+        request: SetCookieParams;
+        response: SetCookieResult;
+    };
+    record_start: {
+        request: RecordParams;
+        response: unknown;
+    };
+    record_stop: {
+        request: RecordParams;
+        response: unknown;
+    };
+    request_domain_permission: {
+        request: RequestDomainPermissionParams;
+        response: unknown;
+    };
+    get_user_info: {
+        request: GetUserInfoParams;
+        response: unknown;
+    };
+    run_actions: {
+        request: RunActionsParams;
+        response: unknown;
+    };
+}
+export type BrowserAction = keyof BrowserActionMap;
+export type BrowserActionRequest<A extends BrowserAction> = BrowserActionMap[A]['request'];
+export type BrowserActionResponse<A extends BrowserAction> = BrowserActionMap[A]['response'];
+export type BrowserCommandAction = Exclude<BrowserAction, 'browser_select_browser'>;
+export type ExtensionBrowserAction = Exclude<BrowserCommandAction, 'browser_list' | 'browser_launch' | 'browser_close'>;
+export declare const PAGE_ACT_ACTIONS: readonly ["page_click", "page_type", "page_hover", "page_scroll", "page_press", "page_upload", "page_eval"];
+export type PageActAction = (typeof PAGE_ACT_ACTIONS)[number];
+export declare const BROWSER_ACTIONS: {
+    readonly get_requests: true;
+    readonly get_logs: true;
+    readonly get_events: true;
+    readonly get_api_schema: true;
+    readonly set_mock: true;
+    readonly get_mocks: true;
+    readonly set_rule: true;
+    readonly get_rules: true;
+    readonly send_request: true;
+    readonly send_mtop_request: true;
+    readonly tdbank_account: true;
+    readonly browser_list: true;
+    readonly browser_select_browser: true;
+    readonly browser_release: true;
+    readonly browser_launch: true;
+    readonly browser_close: true;
+    readonly page_screenshot: true;
+    readonly page_selected_element: true;
+    readonly tab_open: true;
+    readonly tab_close: true;
+    readonly tab_list: true;
+    readonly page_click: true;
+    readonly page_type: true;
+    readonly page_scroll: true;
+    readonly page_hover: true;
+    readonly page_eval: true;
+    readonly page_snapshot: true;
+    readonly page_press: true;
+    readonly page_wait: true;
+    readonly page_navigate: true;
+    readonly page_upload: true;
+    readonly page_frames: true;
+    readonly set_device_emulation: true;
+    readonly set_timezone: true;
+    readonly get_cookie: true;
+    readonly set_cookie: true;
+    readonly record_start: true;
+    readonly record_stop: true;
+    readonly request_domain_permission: true;
+    readonly get_user_info: true;
+    readonly run_actions: true;
+};
+export declare const BROWSER_COMMAND_ACTIONS: {
+    readonly get_requests: true;
+    readonly get_logs: true;
+    readonly get_events: true;
+    readonly get_api_schema: true;
+    readonly set_mock: true;
+    readonly get_mocks: true;
+    readonly set_rule: true;
+    readonly get_rules: true;
+    readonly send_request: true;
+    readonly send_mtop_request: true;
+    readonly tdbank_account: true;
+    readonly browser_list: true;
+    readonly browser_release: true;
+    readonly browser_launch: true;
+    readonly browser_close: true;
+    readonly page_screenshot: true;
+    readonly page_selected_element: true;
+    readonly tab_open: true;
+    readonly tab_close: true;
+    readonly tab_list: true;
+    readonly page_click: true;
+    readonly page_type: true;
+    readonly page_scroll: true;
+    readonly page_hover: true;
+    readonly page_eval: true;
+    readonly page_snapshot: true;
+    readonly page_press: true;
+    readonly page_wait: true;
+    readonly page_navigate: true;
+    readonly page_upload: true;
+    readonly page_frames: true;
+    readonly set_device_emulation: true;
+    readonly set_timezone: true;
+    readonly get_cookie: true;
+    readonly set_cookie: true;
+    readonly record_start: true;
+    readonly record_stop: true;
+    readonly request_domain_permission: true;
+    readonly get_user_info: true;
+    readonly run_actions: true;
+};
+export declare const EXTENSION_BROWSER_ACTIONS: {
+    readonly get_requests: true;
+    readonly get_logs: true;
+    readonly get_events: true;
+    readonly get_api_schema: true;
+    readonly set_mock: true;
+    readonly get_mocks: true;
+    readonly set_rule: true;
+    readonly get_rules: true;
+    readonly send_request: true;
+    readonly send_mtop_request: true;
+    readonly tdbank_account: true;
+    readonly browser_release: true;
+    readonly page_screenshot: true;
+    readonly page_selected_element: true;
+    readonly tab_open: true;
+    readonly tab_close: true;
+    readonly tab_list: true;
+    readonly page_click: true;
+    readonly page_type: true;
+    readonly page_scroll: true;
+    readonly page_hover: true;
+    readonly page_eval: true;
+    readonly page_snapshot: true;
+    readonly page_press: true;
+    readonly page_wait: true;
+    readonly page_navigate: true;
+    readonly page_upload: true;
+    readonly page_frames: true;
+    readonly set_device_emulation: true;
+    readonly set_timezone: true;
+    readonly get_cookie: true;
+    readonly set_cookie: true;
+    readonly record_start: true;
+    readonly record_stop: true;
+    readonly request_domain_permission: true;
+    readonly get_user_info: true;
+    readonly run_actions: true;
+};
+export declare function isBrowserAction(value: unknown): value is BrowserAction;
+export declare function isBrowserCommandAction(value: unknown): value is BrowserCommandAction;
+export declare function isExtensionBrowserAction(value: unknown): value is ExtensionBrowserAction;