@mearl/client 2.19.2 → 2.20.0

package/README.md

@@ -72,6 +72,29 @@ mearl browser_list
 mearl browser_release
 ```
 
+### 控制会话与文件
+
+多步骤任务首次 `tab_open` 或 `page_snapshot` 使用 `--session new`，响应在原结果旁附带 `session`，后续用其 `sessionId` 自动路由，无需额外创建/查询 action。Session 绑定一个浏览器与传输；页面首次使用自动关联，复用页面与新建页面分别记录。同一页面只允许一个会话控制，旧调用不能绕过占用；Session 不隔离 Cookie 或存储。
+
+旧调用不必传 `--session`，现有动作、`run_actions` 批次和上传 `filePaths` 参数继续可用。活动会话存在时，旧调用不能操作其占用页面、执行浏览器级释放/关闭或修改共享设置；旧批次中的开页/关闭浏览器需改为独立调用。CDP Mock 按标签页生效，跨页使用同一 Mock 时需分别配置。
+
+```bash
+mearl tab_open --session new --payload '{"url":"https://example.com"}'
+mearl page_snapshot --session '<sessionId>' --payload '{"tabId":12345}'
+mearl browser_control --session '<sessionId>' --payload '{"operation":"handoff","reason":"请完成扫码"}'
+mearl page_download --session '<sessionId>' --payload '{"tabId":12345,"trigger":{"selector":"#export"}}' --output /absolute/path/report.csv
+mearl page_upload --session '<sessionId>' --payload '{"tabId":12345,"selector":"input[type=file]","files":[{"filePath":"/absolute/path/report.csv"}]}'
+mearl browser_release --session '<sessionId>' --payload '{"closeCreatedTabs":true,"keepTabIds":[12345]}'
+```
+
+用户在 Popup 的浏览器管理页接管、交还或结束会话。交接后排队旧请求和批次后续步骤停止；已派发动作可能仍然生效。交还后重新取快照。CDP-only 环境可在用户明确确认后用同一 `browser_control` 的 `operation:"resume"` 交还，无需额外 action。会话跨 CLI 连接保留，宿主进程退出后失效；不会根据空闲时间清理用户正在操作的会话。
+
+带 Session 的释放只影响该会话，默认保留页面及环境；`closeCreatedTabs` 只关闭新建页，`keepTabIds` 保留结果页，复用的用户页面始终保留。`preserveEnvironment:false` 清理这些页面的环境。活动会话存在时，浏览器级释放与关闭会被拒绝。
+
+`page_download` 先监听再点击，返回浏览器文件产物；CLI `--output` 或 SDK `saveArtifact(artifact, absolutePath, { session })` 以 256 KiB 分块导出到调用方。`page_upload.files` 接受调用方绝对路径 `{filePath}` 或浏览器 `{artifactId}`，`filePaths` 仍指浏览器宿主路径。单文件最多 256 MiB；保存到调用方的结果独立于临时产物。会话释放清理临时产物，`keepArtifactIds` 可保留指定产物；无会话产物空闲一小时回收，宿主退出清理暂存。
+
+扩展捕获下载需要匹配来源页 referrer 或明确的预期 `url`，无法归属时不会认领最近下载。CDP 只在托管浏览器中使用临时下载目录，共享浏览器保持默认目录，Chrome 未返回完成文件路径时明确报错。下载超时可能已经触发，需检查现场再决定下一步。当前会话与下载适配 Extension/CDP；直接处理页面动作的外部 Provider 对不支持的能力明确报错。
+
 ### 外部浏览器 Provider
 
 Provider 浏览器与扩展、CDP 浏览器一起出现在 `browser_list` 中，并使用同一个
@@ -123,7 +146,7 @@ Mearl 默认聚合当前机器和已配置 cloud-server 下的浏览器，并通
 | ------------------------ | ------------------------------------- |
 | `--connector <id\|名称>` | 限制到一台远端机器                    |
 | `--local`                | 只使用当前机器                        |
-| `--cdp`                  | 当前机器强制使用 CDP，并隐含 `--local` |
+| `--cdp`                  | 当前机器强制使用 CDP；清单只列 CDP 浏览器，并隐含 `--local` |
 | `--server <url>`         | 覆盖自动读取的 cloud-server 地址      |
 
 `browser_list --help` 和 `browser_launch --help` 会按场景展示宿主选择参数；连接或传输排障运行
@@ -268,13 +291,18 @@ Preact、Hooks 和 HTM 运行时。页面从 `window.mearl.ui` 读取 `html`、`
 `--mearl-accent` 等语义变量；主操作按钮使用 `--mearl-action-primary`、
 `--mearl-action-primary-hover` 和 `--mearl-action-primary-text`，以保持与扩展按钮一致。
 
-需要 BUC 身份的内部 HTTP 接口通过官方 `buc` 插件调用。CLI 使用 `mearl buc request`，业务插件使用
+需要 BUC 身份的内部 HTTP 接口通过官方 `buc` 插件调用。CLI 使用 `mearl buc request <url> [app]`，业务插件使用
 `app.invoke('buc', { command: 'request', input })`；当前身份和人员资料分别使用 `whoami` 与 `profile`
 子命令。BUC 插件按请求创建一次性凭据，只接受无 URL 凭据的 HTTPS 地址，过滤认证字段与 Cookie；
 调用方须按已验证的业务契约确认目标服务可信。请求始终在运行 CLI、SDK 或 MCP Server 的机器上执行，
 不随浏览器或 connector 转发。
 `buc request` 支持与 `send_request` 同结构的 `formData` 和 `files`；`files[].filePath` 从该插件执行
 宿主读取，而不是浏览器 native-host，无法引用宿主路径时使用 Base64 内容与 `filename`。
+省略 `app` 时从内置 URL 映射选择；Mearl 正式与预发的 `/api` 地址均映射到 `Mearl`。未登记的地址
+必须显式传入服务登记的 `app`，显式值优先；SDK、MCP 与插件调用的 `input.app` 遵循相同规则。
+AuthX 对应 `mearl authx request <url> [audience]`，省略 `audience` 时同样使用已登记的 URL 映射。
+两者的 `--help` 和 `request --help` 均包含完整 `--payload '{"command":"request","input":{...}}'`
+示例，涵盖 JSON 请求与文件上传。
 
 ## 支持的操作
 
@@ -308,7 +336,11 @@ Preact、Hooks 和 HTM 运行时。页面从 `window.mearl.ui` 读取 `html`、`
 
 `browser_list` 统一列出普通浏览器、Provider 浏览器和托管浏览器。`type` 区分
 `regular` / `managed`，`status` 区分 `connected` / `pairing` / `running_disconnected` /
-`stopped`；只有 `connected` 的浏览器可作为常规操作目标。
+`stopped`；只有 `connected` 的浏览器可作为常规操作目标。本机没有已连接的插件浏览器时，
+`browser_list` 会自动探测默认 CDP 端点，即使已有 Provider 配对记录也无需传 `--cdp`。
+`browser_list --cdp` 在没有已注册的普通 CDP 浏览器时会主动探测该端点，并只返回 CDP 浏览器；
+插件浏览器已连接也不影响这次探测。设置 `MEARL_SOCKET_PATH` 时，清单请求沿用该实例 Socket。
+`check --cdp` 也只检查这些 CDP 浏览器。
 
 `browser_release` 仅在用户明确要求结束调试、退出接管或清理会话资源时调用；它会释放
 debugger/CDP 控制和会话级临时状态，保留浏览器及全部标签页。托管实例的启动、关闭、持久化、

package/dist/actionTimeouts.js

@@ -29,6 +29,8 @@ export function resolveActionTimeoutSec(action, data, fallback = 15) {
     if (action === 'send_mtop_request') {
         return Math.max(fallback, Math.ceil(((data.timeout ?? 10000) + 5000) / 1000));
     }
+    if (action === 'page_download')
+        return Math.max(fallback, Math.ceil((Number(data.timeout ?? 30000) + 10000) / 1000));
     if (action === 'page_wait') {
         const waitMs = data.time ?? data.timeout ?? 10000;
         return Math.max(fallback, Math.ceil((Number(waitMs) + 5000) / 1000));

package/dist/artifacts.d.ts

@@ -0,0 +1,17 @@
+import type { BrowserArtifact } from './generated-browser-action-protocol.js';
+import type { UnifiedInvokeOptions } from './unified.js';
+interface Invoker {
+    invoke(action: string, data?: Record<string, any>, options?: UnifiedInvokeOptions): Promise<any>;
+}
+export declare function stageFile(client: Invoker, filePath: string, options: UnifiedInvokeOptions): Promise<{
+    artifactId: string;
+    options: UnifiedInvokeOptions;
+}>;
+/** Atomically export browser-host data to the calling machine without large JSON responses. */
+export declare function exportArtifact(client: Invoker, artifact: BrowserArtifact & {
+    browserId?: string;
+}, outputPath: string, options?: UnifiedInvokeOptions): Promise<{
+    outputPath: string;
+    bytes: number;
+}>;
+export {};

package/dist/artifacts.js

@@ -0,0 +1,80 @@
+import { open, mkdir, rename, rm, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+const CHUNK_BYTES = 256 * 1024;
+export async function stageFile(client, filePath, options) {
+    if (!path.isAbsolute(filePath))
+        throw new Error('Caller-local file paths must be absolute');
+    const source = await open(filePath, 'r');
+    let id;
+    let pinned = options;
+    try {
+        const metadata = await source.stat();
+        if (!metadata.isFile() || metadata.size > 256 * 1024 * 1024)
+            throw new Error('Upload requires a regular file of at most 256 MiB');
+        const created = await client.invoke('__artifact_init', { filename: path.basename(filePath) }, options);
+        pinned = { ...options, browser: created.browserId };
+        id = created.artifact.artifactId;
+        let offset = 0;
+        for await (const chunk of source.createReadStream({
+            highWaterMark: CHUNK_BYTES,
+            autoClose: false,
+        })) {
+            await client.invoke('__artifact_write', { artifactId: id, offset, base64: chunk.toString('base64') }, pinned);
+            offset += chunk.length;
+        }
+        await client.invoke('__artifact_complete', { artifactId: id, bytes: offset }, pinned);
+        return { artifactId: id, options: pinned };
+    }
+    catch (error) {
+        if (id)
+            await client.invoke('__artifact_remove', { artifactId: id }, pinned).catch(() => { });
+        throw error;
+    }
+    finally {
+        await source.close();
+    }
+}
+/** Atomically export browser-host data to the calling machine without large JSON responses. */
+export async function exportArtifact(client, artifact, outputPath, options = {}) {
+    if (!Number.isSafeInteger(artifact.bytes) || artifact.bytes < 0)
+        throw new Error('Invalid artifact size');
+    if (!path.isAbsolute(outputPath))
+        throw new Error('Artifact output paths must be absolute');
+    if (!options.session && !artifact.browserId && !options.browser)
+        throw new Error('An artifact requires its originating browser');
+    const pinned = { ...options, ...(artifact.browserId ? { browser: artifact.browserId } : {}) };
+    await mkdir(path.dirname(outputPath), { recursive: true });
+    const temporary = `${outputPath}.${randomUUID()}.part`;
+    const target = await open(temporary, 'wx', 0o600);
+    try {
+        let offset = 0;
+        if (artifact.bytes === 0) {
+            const empty = await client.invoke('__artifact_read', { artifactId: artifact.artifactId, offset: 0 }, pinned);
+            if (empty.totalBytes !== 0 || empty.bytes !== 0 || empty.base64 !== '')
+                throw new Error('Artifact export size mismatch');
+        }
+        while (offset < artifact.bytes) {
+            const chunk = await client.invoke('__artifact_read', { artifactId: artifact.artifactId, offset }, pinned);
+            const bytes = Buffer.from(chunk.base64, 'base64');
+            if (!bytes.length ||
+                bytes.length !== chunk.bytes ||
+                chunk.totalBytes !== artifact.bytes ||
+                offset + bytes.length > artifact.bytes)
+                throw new Error('Invalid artifact chunk or truncated transfer');
+            await target.write(bytes);
+            offset += bytes.length;
+        }
+        await target.sync();
+        await target.close();
+        if ((await stat(temporary)).size !== artifact.bytes)
+            throw new Error('Artifact export size mismatch');
+        await rename(temporary, outputPath);
+        return { outputPath, bytes: artifact.bytes };
+    }
+    catch (error) {
+        await target.close().catch(() => { });
+        await rm(temporary, { force: true });
+        throw error;
+    }
+}

package/dist/check.js

@@ -174,7 +174,11 @@ export async function runUnifiedCheck(options, dependencies = {}) {
                 environment.push({
                     status: 'error',
                     label: `Cloud server or connector discovery failed${source}`,
-                    details: [formatError(error), redactServerUrl(options.serverUrl)],
+                    details: [
+                        formatError(error),
+                        redactServerUrl(options.serverUrl),
+                        'On the Agent machine, run `mearl-cloud-server status` to verify the server and current connection command. Use `mearl check --local` to isolate this machine.',
+                    ],
                 });
             }
         }
@@ -215,7 +219,8 @@ export async function runUnifiedCheck(options, dependencies = {}) {
                 details: [formatError(error)],
             });
         }
-        const connected = (browserList?.browsers ?? []).filter(browser => browser.status === 'connected');
+        const connected = (browserList?.browsers ?? []).filter(browser => browser.status === 'connected' &&
+            (options.transport !== 'cdp' || browser.transport === 'cdp'));
         let targets = connected;
         if (options.browser) {
             const matches = findBrowsers(connected, options.browser);
@@ -242,9 +247,16 @@ export async function runUnifiedCheck(options, dependencies = {}) {
         if (!options.browser && connected.length === 0 && browserList) {
             environment.push({
                 status: 'error',
-                label: 'No connected browser',
+                label: options.transport === 'cdp' ? 'No connected CDP browser' : 'No connected browser',
                 details: [
-                    'Open Chrome with the Mearl extension, start a managed browser, or connect a browser host.',
+                    options.transport === 'cdp'
+                        ? 'Enable a local CDP endpoint (see `mearl-native-host --help`) and run `mearl browser_list --cdp` to inspect discovery.'
+                        : 'Open Chrome with the Mearl extension, start a managed browser, or connect a browser host.',
+                    ...(!options.local && connectors.length > 0
+                        ? [
+                            'Connectors are connected but expose no ready browser. On the browser machine, run `mearl check --local`; use `mearl connector_list` for versions and heartbeat details.',
+                        ]
+                        : []),
                 ],
             });
         }

package/dist/cli.d.ts

@@ -3,6 +3,7 @@ export interface MearlCliOptions {
     clientVersion?: string;
 }
 export interface ParsedArgs {
+    session?: string;
     action: string;
     browser?: string;
     compact: boolean;

package/dist/cli.js

@@ -38,6 +38,7 @@ const CATEGORIES = [
             'page_wait',
             'page_navigate',
             'page_upload',
+            'page_download',
             'page_eval',
         ],
     },
@@ -48,7 +49,13 @@ const CATEGORIES = [
     },
     {
         title: '浏览器',
-        names: ['browser_list', 'browser_launch', 'browser_release', 'browser_close'],
+        names: [
+            'browser_list',
+            'browser_launch',
+            'browser_release',
+            'browser_close',
+            'browser_control',
+        ],
     },
 ];
 const BUILTIN_COMMANDS = [
@@ -119,6 +126,7 @@ function printUsage(commandName, version) {
         '  --timeout <seconds>   超时时间（默认按 action 推导）',
         '  --compact             stdout 输出紧凑格式 JSON',
         '  --output <path>       保存输出或截图',
+        '  --session <new|id>    首次建立或复用控制会话',
         '  --browser <id|名称>   指定 browser_list 返回的浏览器',
         '',
         '其他选项：',
@@ -270,6 +278,9 @@ function printCheckHelp(commandName) {
         '  --json                输出机器可读 JSON',
         '  --updates            查询已安装组件的发布版本',
         '  -h, --help            查看帮助',
+        '',
+        '检查本机及远端控制链路；发现错误时退出码为 1。',
+        'Server 地址优先级：--server > MEARL_SERVER_URL > ~/.mearl/cloud-server.json。',
     ].join('\n'));
 }
 function printAdvancedCommandHelp(commandName, action) {
@@ -281,6 +292,7 @@ function printAdvancedCommandHelp(commandName, action) {
         '',
         '用法：',
         `  ${commandName} connector_list [--server <url>] [--timeout <seconds>]`,
+        '结果包含 count 与 connectors；每项包含 ID、名称、可选版本、连接时间和最后心跳。',
     ].join('\n'));
 }
 function printCommandHelp(commandName, command) {
@@ -298,6 +310,8 @@ function printCommandHelp(commandName, command) {
         for (const parameter of command.params) {
             const required = parameter.required ? '必填' : '可选';
             lines.push(`  ${parameter.name.padEnd(22)}${required.padEnd(6)}${parameter.type.padEnd(28)}  ${parameter.description}`);
+            for (const detail of parameter.details ?? [])
+                lines.push(`    ${detail}`);
         }
         lines.push('');
     }
@@ -307,6 +321,12 @@ function printCommandHelp(commandName, command) {
     else if (command.name === 'browser_launch') {
         lines.push('宿主选择（本机与远端同时可用时）：', '  --local               在当前机器启动', '  --connector <id|名称> 在指定远端 connector 启动', '  --browser <id|名称>   在控制浏览器所在宿主启动，并可作为 Cookie/UA 来源', '');
     }
+    if (command.notes?.length) {
+        lines.push('约束与行为：', ...command.notes.map(note => `  ${note}`), '');
+    }
+    if (command.result?.length) {
+        lines.push('结果：', ...command.result.map(line => `  ${line}`), '');
+    }
     if (command.examples?.length) {
         lines.push('示例：');
         for (const example of command.examples)
@@ -410,6 +430,7 @@ export function parseClientArgs(args, plugin = false) {
         .option('--json')
         .option('--output <path>')
         .option('--browser <id-or-name>')
+        .option('--session <new-or-id>')
         .option('--connector <id-or-name>')
         .option('--local')
         .option('--updates')
@@ -472,6 +493,7 @@ export function parseClientArgs(args, plugin = false) {
         updates: options.updates === true,
         ...(outputPath ? { outputPath } : {}),
         ...(options.browser ? { browser: options.browser } : {}),
+        ...(options.session ? { session: options.session } : {}),
         ...(connector ? { connector } : {}),
         ...resolveServer(options.server),
         ...(plugin
@@ -500,6 +522,7 @@ async function runPluginCli(args, commandName) {
         const invokeOptions = {
             ...(parsed.timeoutOption ? { timeoutSec: parsed.timeoutSec } : {}),
             ...(parsed.browser ? { browser: parsed.browser } : {}),
+            ...(parsed.session ? { session: parsed.session } : {}),
             ...(parsed.connector ? { connector: parsed.connector } : {}),
             ...(parsed.local ? { local: true } : {}),
             ...(parsed.forceCdp ? { transport: 'cdp' } : {}),
@@ -653,6 +676,7 @@ export async function runMearlCli(args, options = {}) {
             ...(parsed.serverUrl ? { serverUrl: parsed.serverUrl } : {}),
             ...(parsed.serverUrlSource ? { serverUrlSource: parsed.serverUrlSource } : {}),
             ...(parsed.browser ? { browser: parsed.browser } : {}),
+            ...(parsed.session ? { session: parsed.session } : {}),
             ...(parsed.connector ? { connector: parsed.connector } : {}),
             ...(parsed.local ? { local: true } : {}),
             ...(parsed.forceCdp ? { transport: 'cdp' } : {}),
@@ -672,12 +696,25 @@ export async function runMearlCli(args, options = {}) {
         const result = await client.invoke(parsed.action, parsed.payload, {
             timeoutSec: parsed.timeoutSec,
             ...(parsed.browser ? { browser: parsed.browser } : {}),
+            ...(parsed.session ? { session: parsed.session } : {}),
             ...(parsed.connector ? { connector: parsed.connector } : {}),
             ...(parsed.local ? { local: true } : {}),
             ...(parsed.forceCdp ? { transport: 'cdp' } : {}),
         });
-        if (parsed.outputPath) {
+        if (parsed.outputPath && parsed.action === 'page_download') {
+            await client.saveArtifact(result.download, resolve(parsed.outputPath), {
+                ...(parsed.session ? { session: parsed.session } : {}),
+            });
+            process.stdout.write(JSON.stringify({ ...result, outputPath: resolve(parsed.outputPath) }) + '\n');
+            if (!parsed.session)
+                await client.invoke('__artifact_remove', { artifactId: result.download.artifactId }, { browser: result.download.browserId });
+        }
+        else if (parsed.outputPath) {
             writeOutput(parsed.action, result, parsed.outputPath);
+            if (parsed.action === 'page_screenshot' && result?.session) {
+                const { data: _image, ...metadata } = result;
+                process.stdout.write(JSON.stringify({ ...metadata, outputPath: resolve(parsed.outputPath) }) + '\n');
+            }
         }
         else {
             process.stdout.write(`${parsed.compact ? JSON.stringify(result) : JSON.stringify(result, null, 2)}\n`);
@@ -685,7 +722,14 @@ export async function runMearlCli(args, options = {}) {
         return actionInvocationFailed(parsed.action, result) ? 1 : 0;
     }
     catch (error) {
-        console.error(error instanceof Error ? error.message : String(error));
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(message);
+        if (/connection timeout/i.test(message)) {
+            console.error('连接未就绪，请运行 mearl check 定位控制链路故障。');
+        }
+        else if (/请求超时|(?:request|command) timeout|timed out/i.test(message)) {
+            console.error('超时不代表动作未执行。点击、提交或写入后先读取当前状态确认结果；只读查询可缩小范围或增加 --timeout（秒）后重试。');
+        }
         return 1;
     }
     finally {