@mearl/client 2.0.0

package/README.md

@@ -0,0 +1,119 @@
+# @mearl/client
+
+本地客户端 SDK 与 CLI，通过 **Unix Domain Socket** 与 Chrome 扩展的 native host 通信，调用浏览器调试与操作能力。
+
+提供两种用法：类型安全的具名方法（`getRequests`、`sendRequest` 等），以及灵活的底层 `invoke(action, payload)`。
+
+## 安装
+
+```bash
+npm install @mearl/client
+# 或
+pnpm add @mearl/client
+```
+
+## SDK 使用
+
+```typescript
+import * as client from '@mearl/client';
+
+// 具名方法（类型安全）
+const requests = await client.getRequests({ count: 5 });
+const result = await client.sendRequest({
+  url: 'https://api.example.com',
+  method: 'GET',
+  withCookies: true,
+});
+
+// 底层通用方法（灵活扩展）
+const data = await client.invoke('send_request', { url: '...' });
+```
+
+## CLI 使用
+
+安装后提供 `mearl` 命令：
+
+```bash
+# 获取最近 5 个请求
+mearl get_requests --payload '{"count":5}'
+
+# 代理一个 HTTP 请求
+mearl send_request --payload '{"url":"https://api.example.com","method":"GET"}'
+
+# 截图并保存
+mearl page_screenshot --output ./screenshot.png
+
+# 从文件读取大体积参数（如 mock 数据）
+mearl set_mock --payload-file ./mock-data.json
+
+# 环境自检
+mearl check
+
+# 查看某个 action 的帮助
+mearl <action> --help
+
+# 启动两个隔离的 headless Chrome，并分别登录不同 TDBank 账号
+mearl browser_launch --payload '{"name":"account-a","accountId":12345}'
+mearl browser_launch --payload '{"name":"account-b","query":"test_account"}'
+mearl browser_launch --payload '{"name":"cookie-copy","copyCookieDomains":["example.com"]}'
+mearl browser_launch --payload '{"name":"figma","userAgentMode":"desktop","copyCookieDomains":["figma.com"]}'
+mearl browser_list
+```
+
+**通用选项：**
+
+| 选项                    | 说明                     |
+| ----------------------- | ------------------------ |
+| `--payload <json>`      | 直接传入 JSON 参数       |
+| `--payload-file <path>` | 从文件读取 JSON 参数     |
+| `--timeout <seconds>`   | 请求超时时间             |
+| `--compact`             | 紧凑输出                 |
+| `--output <path>`       | 将结果写入文件（如截图） |
+
+## 支持的操作
+
+| 分类        | Actions                                                                                                              |
+| ----------- | -------------------------------------------------------------------------------------------------------------------- |
+| API 调试    | `get_requests` `get_logs` `get_events` `get_api_schema`                                                              |
+| Mock & 规则 | `set_mock` `get_mocks` `set_rule` `get_rules`                                                                                    |
+| 网络代理    | `send_request` `send_mtop_request`                                                                                  |
+| 标签页      | `tab_open` `tab_close` `tab_list`                                                                                    |
+| 页面操作    | `page_click` `page_type` `page_scroll` `page_eval` `page_press` `page_wait` `page_navigate` `page_upload`            |
+| 页面感知    | `page_snapshot` `page_screenshot` `page_selected_element` `page_frames`                                                |
+| 环境模拟    | `set_device_emulation` `set_timezone`                                                                                |
+| 用户信息    | `get_user_info`                                                                                                      |
+| 录制        | `record_start` `record_stop`                                                                            |
+| TDBank      | `tdbank_account`                                                                                                     |
+| 浏览器      | `browser_list` `browser_launch` `browser_close`                                                                      |
+
+页面交互动作（`page_click` / `page_type` / `page_hover` / `page_scroll` / `page_press` / `page_upload`）默认内置观察：同一次调用内执行动作并等待异步稳定，返回 `{ action, observation }`；传 `observe: false` 可关闭观察仅执行裸动作。观察结果不替代完整页面理解：`mode: "delta"` 只返回主文档中的 `effects.notifications`、`effects.interactives` 和 `effects.focus` 等高置信度信号，并明确携带 `scope: "main-document"`；`mode: "navigation"` 且 `ready: true` 时，页面已通过网络静默、骨架状态或保守的内容稳定判定，可在新页面重建快照。仅在 `fullSnapshotRecommended` 为 true 时根据 `snapshotReasons` 回退到完整快照或截图。
+
+`page_snapshot` 默认返回完整 AX Tree；长列表可传 `mode: "viewport"`，只需要控件时传 `mode: "interactive"`，已知区域时传 `rootSelector`。页面缺少 AX 控件语义时，`interactive` 会自动回退到 viewport，并返回 `fallbackMode: "viewport"`。`maxNodes` / `maxChars` 截断会同时保留首尾内容。
+
+`browser_list` 统一列出普通浏览器和托管浏览器。`type` 区分 `regular` / `managed`，`status` 区分 `connected` / `running_disconnected` / `stopped`；只有 `connected` 的浏览器可作为操作目标。
+
+托管浏览器使用独立 Profile 和动态 CDP 端口。控制浏览器需先登录 TDBank；生成的 SSO 地址在本地内部传递，新实例可以使用 `headless: true`（默认）完成测试账号登录。`copyCookieDomains` 可把控制浏览器指定域的 Cookie 复制到新实例，Cookie 值不会出现在命令结果或日志中；`userAgentMode: "desktop"` 可让实例使用匹配本机 Chrome 版本的桌面 UA。完整设计见 [托管浏览器与 TDBank 多账号设计](../../docs/managed-browsers.md)。
+
+## 架构
+
+```
+@mearl/client (CLI / SDK)
+  ↓ (Unix Socket)
+@mearl/native-host
+  ↓ (Native Messaging)
+Chrome Extension / CDP
+```
+
+> 云端远程调用场景请使用 [@mearl/cloud-client](../cloud/cloud-client)，其操作集与本包完全一致。
+
+## 构建
+
+```bash
+pnpm build      # tsc 编译到 dist/，并赋予 cli.js 执行权限
+pnpm dev        # tsc --watch
+pnpm typecheck  # 仅类型检查
+```
+
+## License
+
+ISC

package/dist/actionTimeouts.d.ts

@@ -0,0 +1,2 @@
+export declare function resolveObservedActionTimeoutSec(data: Record<string, any>): number;
+export declare function resolveActionTimeoutSec(action: string, data: Record<string, any>, fallback?: number): number;

package/dist/actionTimeouts.js

@@ -0,0 +1,49 @@
+function boundedNumber(value, fallback, minimum, maximum) {
+    const numeric = Number(value);
+    if (!Number.isFinite(numeric))
+        return fallback;
+    return Math.min(Math.max(numeric, minimum), maximum);
+}
+// 默认内置观察的页面交互动作。client 作为零依赖包本地维护，
+// 需与 browser-core/pageAct.ts 的 PAGE_ACT_ACTIONS 保持一致。
+const OBSERVED_PAGE_ACTIONS = new Set([
+    'page_click',
+    'page_type',
+    'page_hover',
+    'page_scroll',
+    'page_press',
+    'page_upload',
+]);
+export function resolveObservedActionTimeoutSec(data) {
+    const observe = data.observe ?? {};
+    const observationMs = boundedNumber(observe.timeoutMs, 3000, 500, 30000);
+    const navigationGraceMs = boundedNumber(observe.navigationGraceMs, 1000, 0, 5000);
+    const navigationTimeoutMs = boundedNumber(observe.navigationTimeoutMs, 15000, 1000, 30000);
+    const totalMs = observationMs + navigationGraceMs + 4000 + navigationTimeoutMs + 5000;
+    return Math.max(20, Math.ceil(totalMs / 1000));
+}
+export function resolveActionTimeoutSec(action, data, fallback = 15) {
+    if (action === 'send_request') {
+        return Math.max(fallback, Math.ceil(((data.timeout ?? 30000) + 5000) / 1000));
+    }
+    if (action === 'send_mtop_request') {
+        return Math.max(fallback, Math.ceil(((data.timeout ?? 10000) + 5000) / 1000));
+    }
+    if (action === 'page_wait') {
+        const waitMs = data.time ?? data.timeout ?? 10000;
+        return Math.max(fallback, Math.ceil((Number(waitMs) + 5000) / 1000));
+    }
+    if (action === 'browser_launch')
+        return Math.max(fallback, 90);
+    if (action === 'browser_close' || action === 'tdbank_account')
+        return Math.max(fallback, 20);
+    // 页面交互动作默认内置观察，超时需覆盖观察与导航窗口；observe:false 时是裸动作，用默认超时
+    if (OBSERVED_PAGE_ACTIONS.has(action) && data.observe !== false) {
+        return Math.max(fallback, resolveObservedActionTimeoutSec(data));
+    }
+    if (action === 'run_actions') {
+        const steps = Array.isArray(data.actions) ? data.actions.length : 1;
+        return Math.max(fallback, steps * 15);
+    }
+    return fallback;
+}

package/dist/browserRegistry.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Reader for the shared browser registry that native-host processes publish, so
+ * the client can discover every browser that currently has the extension
+ * connected and address a specific one.
+ *
+ * Kept dependency-free (no @mearl/daemon-core) because the client ships
+ * as a standalone npm package. It only has to agree with daemon-core on the
+ * registry directory and record shape; reading scans every *.json in the dir,
+ * so it never needs to replicate daemon-core's filename hashing.
+ */
+export interface LiveBrowser {
+    pid: number;
+    browserId: string;
+    socketPath: string;
+    browserName: string;
+    extensionVersion?: string;
+    nativeHostVersion?: string;
+    transport?: 'extension' | 'cdp';
+    lastFocusedAt?: number;
+    updatedAt?: number;
+}
+/**
+ * Every live browser record, most-recently-focused first.
+ *
+ * Read-only: dead records are filtered out but never deleted here. Deleting is
+ * left to the native-hosts (they overwrite their own record on reconnect and
+ * reconcile when serving browser_list). Otherwise many concurrent clients pruning at once
+ * could, in a narrow window, delete a record a browser just re-published on
+ * reconnect — making a live browser briefly vanish from the registry.
+ */
+export declare function listLiveBrowsers(): LiveBrowser[];
+/**
+ * Find the browser matching a user selector: exact browserId first, then an
+ * exact (case-insensitive) name, then a substring of id/name.
+ */
+export declare function findBrowser(browsers: LiveBrowser[], selector: string): LiveBrowser | null;
+/** Human-readable one-line label for a browser, used in listings and errors. */
+export declare function describeBrowser(b: LiveBrowser): string;

package/dist/browserRegistry.js

@@ -0,0 +1,80 @@
+/**
+ * Reader for the shared browser registry that native-host processes publish, so
+ * the client can discover every browser that currently has the extension
+ * connected and address a specific one.
+ *
+ * Kept dependency-free (no @mearl/daemon-core) because the client ships
+ * as a standalone npm package. It only has to agree with daemon-core on the
+ * registry directory and record shape; reading scans every *.json in the dir,
+ * so it never needs to replicate daemon-core's filename hashing.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+/** Must match @mearl/daemon-core's DAEMON_HOME + the native-host 'browsers' subdir. */
+const BROWSERS_DIR = path.join(os.homedir(), '.mearl', 'browsers');
+function isAlive(pid) {
+    if (!pid || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+/**
+ * Every live browser record, most-recently-focused first.
+ *
+ * Read-only: dead records are filtered out but never deleted here. Deleting is
+ * left to the native-hosts (they overwrite their own record on reconnect and
+ * reconcile when serving browser_list). Otherwise many concurrent clients pruning at once
+ * could, in a narrow window, delete a record a browser just re-published on
+ * reconnect — making a live browser briefly vanish from the registry.
+ */
+export function listLiveBrowsers() {
+    let files;
+    try {
+        files = fs.readdirSync(BROWSERS_DIR).filter(name => name.endsWith('.json'));
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of files) {
+        let rec;
+        try {
+            rec = JSON.parse(fs.readFileSync(path.join(BROWSERS_DIR, name), 'utf-8'));
+        }
+        catch {
+            // Corrupt or mid-write (a writer may be renaming it in); skip.
+            continue;
+        }
+        if (rec && typeof rec.pid === 'number' && rec.socketPath && isAlive(rec.pid)) {
+            out.push(rec);
+        }
+    }
+    return out.sort((a, b) => (b.lastFocusedAt ?? 0) - (a.lastFocusedAt ?? 0));
+}
+/**
+ * Find the browser matching a user selector: exact browserId first, then an
+ * exact (case-insensitive) name, then a substring of id/name.
+ */
+export function findBrowser(browsers, selector) {
+    const sel = selector.trim().toLowerCase();
+    if (!sel)
+        return null;
+    const byId = browsers.find(b => b.browserId.toLowerCase() === sel);
+    if (byId)
+        return byId;
+    const byExactName = browsers.find(b => b.browserName.toLowerCase() === sel);
+    if (byExactName)
+        return byExactName;
+    return (browsers.find(b => b.browserId.toLowerCase().includes(sel) || b.browserName.toLowerCase().includes(sel)) ?? null);
+}
+/** Human-readable one-line label for a browser, used in listings and errors. */
+export function describeBrowser(b) {
+    const idShort = b.browserId.length > 12 ? `${b.browserId.slice(0, 8)}…` : b.browserId;
+    return `${b.browserName} [${idShort}]`;
+}

package/dist/check.d.ts

@@ -0,0 +1 @@
+export declare function runCheck(): Promise<void>;

package/dist/check.js

@@ -0,0 +1,146 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execSync } from 'node:child_process';
+import { invoke, CLIENT_VERSION, SOCKET_PATH } from './socket.js';
+import { listLiveBrowsers, describeBrowser } from './browserRegistry.js';
+const EXTENSION_INSTALL_URL = 'https://chromewebstore.google.com/detail/mearl/aoehhjnofngknnjefamjbplchbolghkm';
+function resolveManifestDir() {
+    switch (process.platform) {
+        case 'darwin':
+            return path.join(os.homedir(), 'Library/Application Support/Google/Chrome/NativeMessagingHosts');
+        case 'linux':
+            return path.join(os.homedir(), '.config/google-chrome/NativeMessagingHosts');
+        case 'win32':
+            return path.join(process.env.PROGRAMDATA || 'C:\\ProgramData', 'Google\\Chrome\\NativeMessagingHosts');
+        default:
+            return '';
+    }
+}
+function checkCommandExists(command) {
+    try {
+        return execSync(`${command} --version`, { encoding: 'utf-8', timeout: 5000 }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+export async function runCheck() {
+    const env = [];
+    // 1. native-host CLI on PATH
+    const cliVersion = checkCommandExists('mearl-native-host');
+    env.push(cliVersion
+        ? { ok: true, label: 'native-host CLI' }
+        : {
+            ok: false,
+            label: 'native-host CLI not found',
+            fix: ['npm install -g @mearl/native-host'],
+        });
+    // 2. Native Messaging manifest
+    const manifestDir = resolveManifestDir();
+    const manifestName = 'com.alibaba.mearl.skills.json';
+    const manifestPath = manifestDir ? path.join(manifestDir, manifestName) : '';
+    env.push(manifestPath && fs.existsSync(manifestPath)
+        ? { ok: true, label: 'Native Messaging manifest' }
+        : {
+            ok: false,
+            label: 'Native Messaging manifest not found',
+            fix: ['mearl-native-host --init'],
+        });
+    // 3. Socket file (Windows uses Named Pipes — assume present, probe via invoke)
+    const isWindows = process.platform === 'win32';
+    const socketExists = isWindows || fs.existsSync(SOCKET_PATH);
+    if (isWindows) {
+        env.push({ ok: true, label: `Socket (Named Pipe)` });
+    }
+    else if (socketExists) {
+        env.push({ ok: true, label: 'Socket file' });
+    }
+    else {
+        env.push({
+            ok: false,
+            label: `Socket file not found at ${SOCKET_PATH}`,
+            fix: [
+                'native host is not running',
+                'Extension mode: ensure Chrome is running and the extension is enabled',
+                'CDP mode: chrome://inspect/#remote-debugging → "Discover network targets"',
+            ],
+        });
+    }
+    // 4. Connection + version fetch
+    let runtime = null;
+    let outdatedDaemon = false;
+    if (socketExists) {
+        try {
+            runtime = (await invoke('get_versions', {}, { timeoutSec: 5 }));
+            env.push({ ok: true, label: 'Connection' });
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            if (msg.includes('Unknown action')) {
+                // Old native-host responded but doesn't know get_versions — connection itself is fine.
+                outdatedDaemon = true;
+                env.push({ ok: true, label: 'Connection' });
+            }
+            else {
+                env.push({ ok: false, label: 'Connection failed', fix: [msg] });
+            }
+        }
+    }
+    // Build versions list
+    const versions = [['client', `v${CLIENT_VERSION}`]];
+    const nhVersion = runtime?.nativeHost ?? cliVersion;
+    if (nhVersion)
+        versions.push(['native-host', `v${nhVersion}`]);
+    if (runtime?.extension) {
+        versions.push(['extension', `v${runtime.extension}`]);
+    }
+    if (runtime?.browser) {
+        versions.push(['browser', `Chrome ${runtime.browser}`]);
+    }
+    // Print Versions section
+    const nameWidth = Math.max(...versions.map(([n]) => n.length));
+    console.error('\nVersions');
+    for (const [name, value] of versions) {
+        console.error(`  ${name.padEnd(nameWidth)}  ${value}`);
+    }
+    console.error('');
+    // Print Environment section
+    console.error('Environment');
+    let hasError = false;
+    for (const e of env) {
+        console.error(`  ${e.ok ? '✅' : '❌'} ${e.label}`);
+        if (!e.ok) {
+            hasError = true;
+            for (const fix of e.fix ?? [])
+                console.error(`     ${fix}`);
+        }
+    }
+    if (outdatedDaemon) {
+        console.error('  ⚠️  native-host daemon is outdated (missing get_versions). Restart Chrome or re-init: mearl-native-host --init');
+    }
+    console.error('');
+    // Connected browsers (multi-browser addressing)
+    const browsers = listLiveBrowsers();
+    if (browsers.length > 0) {
+        console.error('Connected browsers');
+        browsers.forEach((b, i) => {
+            const marker = i === 0 ? '★' : ' ';
+            const via = b.transport === 'cdp' ? ' [CDP]' : '';
+            console.error(`  ${marker} ${describeBrowser(b)}${via}`);
+        });
+        if (browsers.length > 1) {
+            console.error('  ★ = default target (most-recently focused). Use --browser to pick another.');
+        }
+        console.error('');
+    }
+    // Summary
+    if (hasError) {
+        console.error('⚠️  Some checks failed. See above for fix instructions.');
+        console.error(`   Install extension: ${EXTENSION_INSTALL_URL}`);
+        process.exit(1);
+    }
+    else {
+        console.error('🎉 All checks passed!');
+    }
+}

package/dist/cli.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * mearl CLI — 通过命令行调用 Mearl 浏览器插件能力
+ *
+ * 用法：
+ *   mearl <action> [--payload <json> | --payload-file <path>] [--timeout <seconds>] [--compact] [--output <path>]
+ *
+ * 示例：
+ *   mearl get_requests --payload '{"count":5}'
+ *   mearl send_request --payload '{"url":"https://api.example.com","method":"GET"}'
+ *   mearl page_screenshot --output ./screenshot.png
+ *   mearl set_mock --payload-file ./mock-data.json
+ */
+export {};