@mearl/client 2.11.0 → 2.13.0

package/README.md

@@ -77,10 +77,36 @@ mearl browser_list
 mearl browser_release
 ```
 
+### 外部浏览器 Provider
+
+Provider 浏览器与扩展、CDP 和 AgentBay 浏览器一起出现在 `browser_list` 中，并使用同一个
+全局 `browserId` 参与路由。Provider 的安装、更新和卸载由 `@mearl/setup` 管理：
+
+```bash
+npx @mearl/setup provider install @ali/mearl-provider-brow
+
+# 让 Brow 创建一个配对实例；debugId 可省略并自动生成
+mearl browser_launch --payload '{"provider":"brow","providerOptions":{"debugId":"my-device"}}'
+
+# 扫码后确认同一个实例已经连接
+mearl browser_list
+
+# 后续操作使用 browser_list 返回的全局 Browser ID
+mearl page_snapshot --browser '<browserId>'
+
+npx @mearl/setup provider update brow
+npx @mearl/setup provider uninstall brow
+```
+
+`browser_launch` 创建 `pairing` 实例时会直接返回 `pairing.url` 和可选的配对码；Agent 应把 URL 直接渲染为
+二维码交给用户，扫码后确认同一 Browser ID 变为 `connected`，再开始页面操作。在设备连入前
+该实例不会成为默认操作目标；可用 `browser_close` 删除对应 Provider 实例。每个 Provider
+只接收它为该浏览器显式声明支持的 actions，截图能力同时标明为原生截图、重建画面或不支持。
+
 输入不存在或拼写有误的 action 时，CLI 会基于可用命令和常见别名直接返回最多三个候选及调用示例，
 不连接浏览器，也不会自动执行推荐命令。例如 `mearl tab new` 会优先推荐 `mearl tab_open`。
 
-**通用选项：**
+**常用选项：**
 
 | 选项                     | 说明                     |
 | ------------------------ | ------------------------ |
@@ -90,12 +116,55 @@ mearl browser_release
 | `--compact`              | stdout 紧凑输出          |
 | `--output <path>`        | 将结果写入文件（如截图） |
 | `--browser <id\|名称>`   | 指定目标浏览器           |
-| `--connector <id\|名称>` | 限制到一台远端机器       |
-| `--local`                | 只使用当前机器           |
-| `--cdp`                  | 当前机器强制使用 CDP     |
-| `--server <url>`         | 覆盖 cloud-server 地址   |
 
-`check` 有独立的选项说明，运行 `mearl check --help` 查看。其中 `--json` 仅用于输出机器可读的检查结果。
+Mearl 默认聚合当前机器和已配置 cloud-server 下的浏览器，并通过 `browser_list` 返回的全局
+`browserId` 自动路由。以下覆盖参数仅在限定宿主或连接、传输排障时使用，因此不出现在默认 help：
+
+| 选项                     | 说明                                  |
+| ------------------------ | ------------------------------------- |
+| `--connector <id\|名称>` | 限制到一台远端机器                    |
+| `--local`                | 只使用当前机器                        |
+| `--cdp`                  | 当前机器强制使用 CDP，并隐含 `--local` |
+| `--server <url>`         | 覆盖自动读取的 cloud-server 地址      |
+
+`browser_list --help` 和 `browser_launch --help` 会按场景展示宿主选择参数；连接或传输排障运行
+`mearl check --help`。其中 `--json` 仅用于输出机器可读的检查结果。
+
+## Skill CLI 插件
+
+安装 skill 并自动注册命令，或直接注册已有入口：
+
+```bash
+npx @mearl/setup plugin install trip/mearl --skill yuque-doc-fetch --yes
+npx @mearl/setup plugin yuque /absolute/path/to/yuque-doc-fetch
+npx @mearl/setup plugin uninstall yuque
+mearl yuque read "https://aliyuque.antfin.com/group/book/doc"
+mearl yuque --payload '{"command":"read","input":{"url":"https://aliyuque.antfin.com/group/book/doc"}}'
+mearl yuque --help
+mearl yuque --version
+```
+
+目录默认使用 `scripts/main.mjs`。入口默认导出 `register(app)`，可导出简短的 `description`
+显示在 `mearl` 插件列表中，并通过 `app.command(signature, handler, description?)`
+注册动作、`app.invoke(action, payload, options?)` 复用当前浏览器上下文，并用 `app.progress(message)` 报告可选进度。CLI 默认只输出最终结果，传入
+`--verbose` 时才把进度写入 stderr。handler 返回文本或 JSON，宿主统一处理 `--output`、连接和错误。写命令在用户调用后直接执行，业务模块负责目标、状态、幂等和结果校验。
+自动注册默认以 skill 安装目录名作为命令名，也可在入口导出 `name` 指定短名称。
+setup 会补齐缺失或低于自身版本的 client、native-host；安装参数透传给 Ali Skills，并固定全局共享安装。
+
+需要单独检查插件时运行 `mearl <name> --version`。命令会解析注册记录并加载入口，但不连接浏览器；
+退出码为 0 表示插件已注册且入口可加载，stdout 返回同目录 `SKILL.md` 的版本，缺少版本元数据时返回 `unknown`。
+未注册、入口丢失或加载失败会以退出码 2 和对应的 `PLUGIN_*` 错误结束。普通业务调用无需预先检查，直接处理同样的错误即可。
+
+插件接受位置参数或包含 command/input 的 `--payload`，两种形式不能混用。JSON 保留业务字段类型；正文等文件输入
+按具体 skill 的字段约定处理。插件不使用上表中内置 action 的 `--payload-file` 入口。
+
+注册记录在 `~/.mearl/plugins/<name>.json`，保存入口路径和可选的简短描述；skill 业务代码原地更新直接生效，换路径或更新描述后重新注册。
+`plugin uninstall <name>` 会对 `~/.agents/skills` 中的全局 Skill 调用 `ali-skills remove --global --yes`，
+成功后清除相关注册；即使入口目录已被手动删除，也会完成 Ali Skills 跟踪记录的清理。
+手工路径只解除注册并保留源码。
+`PLUGIN_NOT_REGISTERED` 表示插件尚未注册。`PLUGIN_ENTRY_MISSING` 会显示失效入口，并给出带有实际插件名的
+卸载清理命令。其他错误按实际原因处理。
+编写规范见 [Mearl Skill Creator 的 CLI 插件规范](../skills/mearl-skill-creator/references/cli-plugin.md)。
 
 ## 支持的操作
 
@@ -120,7 +189,9 @@ mearl browser_release
 
 重复文本点击可用 `page_click.scope` 限定 CSS / ref 子树；浏览器扩展后端中，容器或 iframe 内的点坐标使用 `coordinateSpace: "active-frame"`，CSS/text 查询可用 `frameId` 显式指定 frame。点击结果通过 `requestedTarget`、`resolvedTarget`、`dispatchTarget`、`hitTarget` 和 `coordinates` 区分请求语义、DOM 解析、派发节点与可信输入实际命中；ref 指向滚动容器内的子节点时，可用 `page_scroll.containerPolicy: "nearest"` 自动解析最近可滚动祖先。
 
-`browser_list` 统一列出普通浏览器和托管浏览器。`type` 区分 `regular` / `managed`，`status` 区分 `connected` / `running_disconnected` / `stopped`；只有 `connected` 的浏览器可作为操作目标。
+`browser_list` 统一列出普通浏览器、Provider 浏览器和托管浏览器。`type` 区分
+`regular` / `managed`，`status` 区分 `connected` / `pairing` / `running_disconnected` /
+`stopped`；只有 `connected` 的浏览器可作为常规操作目标。
 
 按 `sessionId` 接入的 AgentBay 浏览器用 `browser_release` 收尾：它会移除本机 attachment 并退出对应宿主，但不会关闭云端 Session。其他浏览器仅在用户明确要求结束调试、退出接管或清理会话资源时调用；它会释放 debugger/CDP 控制和会话级临时状态（包括设备/时区模拟），保留浏览器及全部标签页，后续浏览器操作可自动重新建立控制。
 
@@ -131,8 +202,10 @@ mearl browser_release
 ```
 @mearl/client (CLI / SDK)
   ├─ 本机 → @mearl/native-host → Chrome Extension / CDP
+  ├─ 本机 → @mearl/provider runtime → External Provider
   └─ WebSocket → @mearl/cloud-server → @mearl/cloud-connector
-                                      → @mearl/native-host → Chrome Extension / CDP
+                                      ├─ @mearl/native-host → Chrome Extension / CDP
+                                      └─ @mearl/provider runtime → External Provider
 ```
 
 基础设施组件必须避免递归路由：`@mearl/cloud-connector` 使用 `@mearl/client/local` 子路径直连所在机器的 native-host。普通 Agent、CLI 与 MCP 集成均使用包根入口。

package/dist/browserRegistry.d.ts

@@ -8,6 +8,7 @@
  * registry directory and record shape; reading scans every *.json in the dir,
  * so it never needs to replicate daemon-core's filename hashing.
  */
+import type { BrowserCapabilities, BrowserPairingInfo, BrowserTransport } from './generated-browser-action-protocol.js';
 export interface LiveBrowser {
     pid: number;
     browserId: string;
@@ -15,7 +16,15 @@ export interface LiveBrowser {
     browserName: string;
     extensionVersion?: string;
     nativeHostVersion?: string;
-    transport?: 'extension' | 'cdp';
+    transport?: BrowserTransport;
+    providerBrowserId?: string;
+    providerId?: string;
+    providerName?: string;
+    providerVersion?: string;
+    providerProtocolVersion?: number;
+    capabilities?: BrowserCapabilities;
+    status?: 'connected' | 'pairing';
+    pairing?: BrowserPairingInfo;
     lastFocusedAt?: number;
     updatedAt?: number;
 }

package/dist/check.d.ts

@@ -1,9 +1,17 @@
 import type { CloudConnectorInfo } from '@mearl/cloud-types';
+import type { BrowserCapabilities } from './generated-browser-action-protocol.js';
 import { type UnifiedClientOptions, type UnifiedInvokeOptions } from './unified.js';
 export interface UnifiedCheckVersions {
     nativeHost?: string;
     extension?: string | null;
     browser?: string | null;
+    provider?: ProviderVersionInfo;
+}
+export interface ProviderVersionInfo {
+    providerId: string;
+    name: string;
+    version: string;
+    protocolVersion: number;
 }
 export type BrowserAccessCapability = {
     kind: 'agentbay';
@@ -25,7 +33,11 @@ interface BrowserInfo {
     status: string;
     type?: string;
     provider?: 'local' | 'agentbay';
-    transport?: 'extension' | 'cdp';
+    providerId?: string;
+    providerName?: string;
+    providerVersion?: string;
+    providerProtocolVersion?: number;
+    transport?: 'extension' | 'cdp' | 'provider';
 }
 interface CheckItem {
     status: 'ok' | 'warning' | 'error';
@@ -38,6 +50,7 @@ export interface ExtensionInstallationInfo {
 }
 export interface UnifiedCheckBrowserResult extends BrowserInfo {
     browserAccess?: BrowserAccess;
+    capabilities?: BrowserCapabilities;
     check?: {
         errors?: string[];
         label: string;

package/dist/check.js

@@ -56,7 +56,9 @@ function formatBrowser(browser, isDefault) {
         ? ' [CDP]'
         : browser.transport === 'extension'
             ? ' [Extension]'
-            : '';
+            : browser.transport === 'provider'
+                ? ` [Provider: ${browser.providerName || browser.providerId || 'external'}]`
+                : '';
     const type = browser.type === 'managed' ? ' [Managed]' : '';
     return `  ${isDefault ? '★' : ' '} ${browser.name} [${shortBrowserId(browser.browserId)}]${type}${transport}`;
 }
@@ -220,12 +222,20 @@ export async function runUnifiedCheck(options, dependencies = {}) {
                     ...(versions.nativeHost ? { nativeHost: versions.nativeHost } : {}),
                     ...(versions.extension !== undefined ? { extension: versions.extension } : {}),
                     ...(versions.browser !== undefined ? { browser: versions.browser } : {}),
+                    ...(versions.provider ? { provider: versions.provider } : {}),
                 };
                 const details = [
                     versions.nativeHost ? `native-host v${versions.nativeHost}` : null,
                     versions.extension ? `extension v${versions.extension}` : null,
                     versions.browser ? `Chrome ${versions.browser}` : null,
+                    versions.provider
+                        ? `${versions.provider.name} v${versions.provider.version} (protocol v${versions.provider.protocolVersion})`
+                        : null,
                 ].filter((value) => value !== null);
+                const capabilities = options.browser ? versions.capabilities : undefined;
+                if (capabilities) {
+                    details.push(`capabilities (${capabilities.actions.length}): ${capabilities.actions.join(', ') || 'none'}`, `screenshot: ${capabilities.screenshot}`);
+                }
                 let extensionInstallation;
                 if (options.local &&
                     browser.transport === 'extension' &&
@@ -253,6 +263,7 @@ export async function runUnifiedCheck(options, dependencies = {}) {
                 browserChecks.push({
                     ...(browserAccess ? { browserAccess } : {}),
                     browser,
+                    ...(capabilities ? { capabilities } : {}),
                     ...(extensionInstallation ? { extensionInstallation } : {}),
                     item: {
                         status: accessUrlWarning ? 'warning' : 'ok',
@@ -302,6 +313,7 @@ export async function runUnifiedCheck(options, dependencies = {}) {
                         ...browserIdentity,
                         selected: targets.some(target => target.browserId === browser.browserId),
                         ...(check?.browserAccess ? { browserAccess: check.browserAccess } : {}),
+                        ...(check?.capabilities ? { capabilities: check.capabilities } : {}),
                         ...(check?.item
                             ? {
                                 check: {

package/dist/cli.d.ts

@@ -16,6 +16,11 @@ export interface ParsedArgs {
     serverUrlSource?: string;
     timeoutSec: number;
     timeoutOption?: string;
+    pluginArgs?: string[];
+    help?: boolean;
+    version?: boolean;
+    verbose?: boolean;
+    hasPayload?: boolean;
 }
-export declare function parseClientArgs(args: string[]): ParsedArgs;
+export declare function parseClientArgs(args: string[], plugin?: boolean): ParsedArgs;
 export declare function runMearlCli(args: string[], options?: MearlCliOptions): Promise<number>;

package/dist/cli.js

@@ -1,13 +1,16 @@
 import { readFileSync, writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { Command, CommanderError } from 'commander';
+import { listInstalledProviders } from '@mearl/provider/host';
 import { resolveActionTimeoutSec } from './actionTimeouts.js';
 import { runUnifiedCheck, parseCheckTimeout } from './check.js';
 import { commandInput, findCommandSuggestions, formatCommandSuggestions, } from './commandSuggestions.js';
 import { COMMANDS, COMMAND_MAP } from './commands.js';
 import { CLIENT_VERSION } from './socket.js';
 import { UnifiedClient } from './unified.js';
+import { findPluginEntry, findPluginRegistration, listPluginNames, loadPlugin, PluginError, } from './plugin.js';
 import { getCloudServerConfigPath, loadCloudServerConfig } from './unifiedConfig.js';
+const TOP_LEVEL_COMMAND_NAME_WIDTH = 22;
 const CATEGORIES = [
     {
         title: 'API 调试',
@@ -73,24 +76,20 @@ function printUsage(commandName, version) {
         '  browser_list 默认聚合当前机器及已配置 cloud-server 下的浏览器。',
         '  后续操作通过 --browser <browserId> 指定目标，客户端会自动选择本地或远端传输。',
         '',
-        '通用选项：',
+        '常用选项：',
         '  --payload <json>      直接传入 JSON 参数',
         '  --payload-file <path> 从文件读取整个 JSON 参数',
         '  --timeout <seconds>   超时时间（默认按 action 推导）',
         '  --compact             stdout 输出紧凑格式 JSON',
         '  --output <path>       保存输出或截图',
         '  --browser <id|名称>   指定 browser_list 返回的浏览器',
-        '  --connector <id|名称> 限制到一台远端 connector',
-        '  --local               只使用当前机器上的浏览器',
-        '  --cdp                 当前机器强制使用 CDP（隐含 --local）',
-        '  --server <url>        覆盖 cloud-server WebSocket URL',
         '',
         '其他选项：',
         '  -h, --help            查看帮助',
         '  -v, --version         查看版本',
         '',
         '内置命令：',
-        '  check                 检查指定浏览器，未指定时检查全部已连接浏览器',
+        `  ${'check'.padEnd(TOP_LEVEL_COMMAND_NAME_WIDTH)}检查指定浏览器，未指定时检查全部已连接浏览器`,
     ];
     for (const category of CATEGORIES) {
         lines.push('', `  ${category.title}`);
@@ -100,6 +99,30 @@ function printUsage(commandName, version) {
                 lines.push(`    ${name.padEnd(26)}${command.summary ?? command.description}`);
         }
     }
+    try {
+        const plugins = listPluginNames();
+        if (plugins.length) {
+            const entries = plugins.map(name => {
+                try {
+                    const description = findPluginRegistration(name)?.description;
+                    return description
+                        ? `  ${name.padEnd(TOP_LEVEL_COMMAND_NAME_WIDTH)}${description}`
+                        : `  ${name}`;
+                }
+                catch {
+                    return `  ${name}`;
+                }
+            });
+            lines.push('', '已注册插件：', ...entries);
+        }
+    }
+    catch (error) {
+        lines.push('', error instanceof Error ? error.message : String(error));
+    }
+    const providers = listInstalledProviders();
+    if (providers.length) {
+        lines.push('', '已注册 Provider：', ...providers.map(provider => `  ${provider.providerId.padEnd(TOP_LEVEL_COMMAND_NAME_WIDTH)}${provider.name} v${provider.version} (${provider.packageName})`));
+    }
     lines.push('', `运行 ${commandName} <action> --help 查看 action 参数。`);
     console.error(lines.join('\n'));
 }
@@ -140,7 +163,7 @@ function printCommandHelp(commandName, command) {
         `  ${command.description}`,
         '',
         '用法：',
-        `  ${commandName} ${command.name}${payloadUsage} [通用选项]`,
+        `  ${commandName} ${command.name}${payloadUsage} [常用选项]`,
         '',
     ];
     if (command.params?.length) {
@@ -151,18 +174,24 @@ function printCommandHelp(commandName, command) {
         }
         lines.push('');
     }
+    if (command.name === 'browser_list') {
+        lines.push('目标范围（按需）：', '  --local               只列出当前机器上的浏览器', '  --connector <id|名称> 只列出指定远端 connector 的浏览器', '');
+    }
+    else if (command.name === 'browser_launch') {
+        lines.push('宿主选择（本机与远端同时可用时）：', '  --local               在当前机器启动', '  --connector <id|名称> 在指定远端 connector 启动', '  --browser <id|名称>   在控制浏览器所在宿主启动，并可作为 Cookie/UA 来源', '');
+    }
     if (command.examples?.length) {
         lines.push('示例：');
         for (const example of command.examples)
             lines.push(`  ${commandName} ${example}`);
     }
-    lines.push('', `运行 ${commandName} --help 查看通用选项。`);
+    lines.push('', `运行 ${commandName} --help 查看常用选项。`);
     console.error(lines.join('\n'));
 }
 function printUnknownCommand(commandName, args) {
     const input = commandInput(args) || args[0] || '';
     const suggestions = findCommandSuggestions(args, SUGGESTABLE_COMMANDS);
-    const lines = [`不支持的命令: ${input}`];
+    const lines = [`PLUGIN_NOT_REGISTERED: 不支持的命令: ${input}`];
     if (suggestions.length > 0) {
         lines.push('', '你可能想用：', ...formatCommandSuggestions(commandName, suggestions));
     }
@@ -213,7 +242,32 @@ function resolveServer(explicit) {
         ? { serverUrl: config.server, serverUrlSource: getCloudServerConfigPath() }
         : {};
 }
-export function parseClientArgs(args) {
+function normalizeScreenshotOutput(action, payload, explicitOutput) {
+    if (action !== 'page_screenshot' || !Object.hasOwn(payload, 'output')) {
+        return { payload, ...(explicitOutput ? { outputPath: explicitOutput } : {}) };
+    }
+    const payloadOutput = payload.output;
+    if (typeof payloadOutput !== 'string' || payloadOutput.trim() === '') {
+        throw new Error('page_screenshot 的 payload.output 必须是非空路径');
+    }
+    if (explicitOutput !== undefined) {
+        throw new Error('page_screenshot 的 payload.output 不能与 --output 同时使用');
+    }
+    const { output: _output, ...normalizedPayload } = payload;
+    return { payload: normalizedPayload, outputPath: payloadOutput };
+}
+function actionInvocationFailed(action, result) {
+    if (result?.action?.success === false)
+        return true;
+    if (action !== 'run_actions')
+        return false;
+    if (Number.isInteger(result?.failedStep))
+        return true;
+    return Array.isArray(result?.results)
+        ? result.results.some((step) => step?.success === false)
+        : false;
+}
+export function parseClientArgs(args, plugin = false) {
     const program = new Command()
         .name('mearl')
         .helpOption(false)
@@ -232,6 +286,12 @@ export function parseClientArgs(args) {
         .option('--local')
         .option('--cdp')
         .option('--server <url>');
+    if (plugin)
+        program
+            .argument('[pluginArgs...]')
+            .option('-h, --help')
+            .option('-v, --version')
+            .option('--verbose');
     try {
         program.parse(['node', 'mearl', ...args]);
     }
@@ -243,10 +303,14 @@ export function parseClientArgs(args) {
     }
     const action = program.processedArgs[0];
     const options = program.opts();
+    if (plugin && options.payloadFile !== undefined) {
+        throw new Error('插件使用 --payload 传入 command 和 input；正文文件可由业务字段引用');
+    }
     const json = options.json === true;
     if (json && action !== 'check')
         throw new Error('--json 仅适用于 check');
-    const payload = parsePayload(options.payload, options.payloadFile);
+    const parsedPayload = parsePayload(options.payload, options.payloadFile);
+    const { payload, outputPath } = normalizeScreenshotOutput(action, parsedPayload, options.output);
     const fallbackTimeout = resolveActionTimeoutSec(action, payload, 60);
     const forceCdp = options.cdp === true;
     const local = forceCdp || options.local === true;
@@ -262,12 +326,89 @@ export function parseClientArgs(args) {
         forceCdp,
         json,
         local,
-        ...(options.output ? { outputPath: options.output } : {}),
+        ...(outputPath ? { outputPath } : {}),
         ...(options.browser ? { browser: options.browser } : {}),
         ...(connector ? { connector } : {}),
         ...resolveServer(options.server),
+        ...(plugin
+            ? {
+                pluginArgs: program.processedArgs[1],
+                help: options.help === true,
+                version: options.version === true,
+                verbose: options.verbose === true,
+                hasPayload: options.payload !== undefined,
+            }
+            : {}),
     };
 }
+async function runPluginCli(args, entry, commandName) {
+    let parsed;
+    try {
+        parsed = parseClientArgs(args, true);
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        return 2;
+    }
+    let client;
+    try {
+        const invokeOptions = {
+            ...(parsed.timeoutOption ? { timeoutSec: parsed.timeoutSec } : {}),
+            ...(parsed.browser ? { browser: parsed.browser } : {}),
+            ...(parsed.connector ? { connector: parsed.connector } : {}),
+            ...(parsed.local ? { local: true } : {}),
+            ...(parsed.forceCdp ? { transport: 'cdp' } : {}),
+        };
+        const plugin = await loadPlugin(entry, {
+            options: invokeOptions,
+            progress(message) {
+                if (parsed.verbose) {
+                    process.stderr.write(message.endsWith('\n') ? message : `${message}\n`);
+                }
+            },
+            async invoke(action, payload, options) {
+                client ??= new UnifiedClient({
+                    ...(parsed.serverUrl ? { serverUrl: parsed.serverUrl } : {}),
+                });
+                const result = await client.invoke(action, payload, { ...invokeOptions, ...options });
+                if (result?.action?.success === false)
+                    throw new Error(result.action.error || `${action} failed`);
+                return result;
+            },
+        }, parsed.action);
+        if (parsed.version) {
+            console.log(plugin.version ?? 'unknown');
+            return 0;
+        }
+        if (parsed.help || (!parsed.pluginArgs?.length && !parsed.hasPayload)) {
+            console.error(plugin.help(`${commandName} ${parsed.action}`, parsed.pluginArgs?.[0]));
+            return 0;
+        }
+        const result = await plugin.run(parsed.pluginArgs ?? [], parsed.hasPayload ? parsed.payload : undefined);
+        if (result !== undefined) {
+            if (parsed.outputPath)
+                writeOutput('', result, parsed.outputPath);
+            else if (typeof result === 'string')
+                process.stdout.write(result.endsWith('\n') ? result : `${result}\n`);
+            else
+                process.stdout.write(`${JSON.stringify(result, null, parsed.compact ? undefined : 2)}\n`);
+        }
+        return result &&
+            typeof result === 'object' &&
+            !Array.isArray(result) &&
+            'success' in result &&
+            result.success === false
+            ? 1
+            : 0;
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        return error instanceof PluginError ? 2 : 1;
+    }
+    finally {
+        client?.disconnect();
+    }
+}
 function screenshotData(action, result) {
     if (typeof result === 'string' && result.startsWith('data:image')) {
         return result.split(',')[1] ?? null;
@@ -294,7 +435,23 @@ export async function runMearlCli(args, options = {}) {
     const clientVersion = options.clientVersion ?? CLIENT_VERSION;
     if (args[0] === 'capture_checkpoint')
         args = ['tab_checkpoint', ...args.slice(1)];
-    if (args.includes('--version') || args.includes('-v')) {
+    if (args[0] &&
+        !args[0].startsWith('-') &&
+        !args[0].startsWith('__') &&
+        args[0] !== 'check' &&
+        !ADVANCED_BUILTIN_COMMANDS.has(args[0]) &&
+        !COMMAND_MAP.has(args[0])) {
+        try {
+            const entry = findPluginEntry(args[0]);
+            if (entry)
+                return await runPluginCli(args, entry, commandName);
+        }
+        catch (error) {
+            console.error(error instanceof Error ? error.message : String(error));
+            return 2;
+        }
+    }
+    if (args[0] === '--version' || args[0] === '-v') {
         console.log(clientVersion);
         return 0;
     }
@@ -377,7 +534,7 @@ export async function runMearlCli(args, options = {}) {
         else {
             process.stdout.write(`${parsed.compact ? JSON.stringify(result) : JSON.stringify(result, null, 2)}\n`);
         }
-        return result?.action?.success === false ? 1 : 0;
+        return actionInvocationFailed(parsed.action, result) ? 1 : 0;
     }
     catch (error) {
         console.error(error instanceof Error ? error.message : String(error));

package/dist/commands.d.ts

@@ -391,15 +391,19 @@ export declare const COMMANDS: readonly [{
     readonly examples: ["browser_release", "browser_release --browser chrome-a"];
 }, {
     readonly name: "browser_launch";
-    readonly description: "启动本地 Chrome、创建/复用同名 AgentBay 云浏览器，或用 sessionId 接入现有云端 Session";
+    readonly description: "启动本地 Chrome、创建/复用 AgentBay 云浏览器，或通过已注册 Provider 创建浏览器实例";
     readonly params: [{
         readonly name: "name";
         readonly type: "string";
         readonly description: "实例名称，创建浏览器时必填；按 sessionId 接入时可省略";
     }, {
         readonly name: "provider";
-        readonly type: "\"local\" | \"agentbay\"";
-        readonly description: "运行环境，默认 local；传 sessionId 时自动使用 agentbay，否则 agentbay 从 AGENTBAY_KEY 创建云浏览器";
+        readonly type: "string";
+        readonly description: "运行环境，默认 local；可传 agentbay 或 mearl --help 中展示的已注册 Provider ID";
+    }, {
+        readonly name: "providerOptions";
+        readonly type: "Record<string, string>";
+        readonly description: "外部 Provider 注册时声明的实例创建参数";
     }, {
         readonly name: "sessionId";
         readonly type: "string";
@@ -457,7 +461,7 @@ export declare const COMMANDS: readonly [{
         readonly type: "string[] | \"mearl-services\" | { presets?: [\"mearl-services\"]; domains?: string[] }";
         readonly description: "从控制浏览器复制 Cookie：可传域名数组、Mearl 登录态预设，或组合预设与额外域名";
     }];
-    readonly examples: ["browser_launch --payload '{\"name\":\"cloud-a\",\"provider\":\"agentbay\",\"userAgentMode\":\"desktop\",\"url\":\"https://example.com\"}'", "browser_launch --payload '{\"name\":\"cloud-public\",\"provider\":\"agentbay\",\"imageId\":\"browser_latest\",\"url\":\"https://example.com\"}'", "browser_launch --payload '{\"name\":\"cloud-login\",\"provider\":\"agentbay\",\"persistent\":true,\"copyCookieDomains\":[\"example.com\"],\"url\":\"https://example.com/account\"}'", "browser_launch --payload '{\"name\":\"cloud-login\",\"provider\":\"agentbay\",\"reuse\":\"require\",\"copyCookieDomains\":[\"example.com\"]}'", "browser_launch --browser '<本地浏览器 browserId>' --payload '{\"sessionId\":\"<AgentBay sessionId>\",\"copyCookieDomains\":[\"example.com\"]}'", "browser_launch --payload '{\"name\":\"cloud-tools\",\"provider\":\"agentbay\",\"copyCookieDomains\":\"mearl-services\"}'", "browser_launch --payload '{\"name\":\"cloud-tools\",\"provider\":\"agentbay\",\"copyCookieDomains\":{\"presets\":[\"mearl-services\"],\"domains\":[\"figma.com\"]}}'", "browser_launch --payload '{\"name\":\"account-a\",\"headless\":true,\"accountId\":12345}'", "browser_launch --payload '{\"name\":\"figma\",\"userAgentMode\":\"desktop\",\"copyCookieDomains\":[\"figma.com\"]}'", "browser_launch --payload '{\"name\":\"account-b\",\"query\":\"test_account\",\"url\":\"https://www.taobao.com\"}'", "browser_launch --payload '{\"name\":\"with-cookies\",\"copyCookieDomains\":[\"example.com\",\"sub.example.org\"]}'"];
+    readonly examples: ["browser_launch --payload '{\"provider\":\"brow\",\"providerOptions\":{}}'", "browser_launch --payload '{\"name\":\"cloud-a\",\"provider\":\"agentbay\",\"userAgentMode\":\"desktop\",\"url\":\"https://example.com\"}'", "browser_launch --payload '{\"name\":\"cloud-public\",\"provider\":\"agentbay\",\"imageId\":\"browser_latest\",\"url\":\"https://example.com\"}'", "browser_launch --payload '{\"name\":\"cloud-login\",\"provider\":\"agentbay\",\"persistent\":true,\"copyCookieDomains\":[\"example.com\"],\"url\":\"https://example.com/account\"}'", "browser_launch --payload '{\"name\":\"cloud-login\",\"provider\":\"agentbay\",\"reuse\":\"require\",\"copyCookieDomains\":[\"example.com\"]}'", "browser_launch --browser '<本地浏览器 browserId>' --payload '{\"sessionId\":\"<AgentBay sessionId>\",\"copyCookieDomains\":[\"example.com\"]}'", "browser_launch --payload '{\"name\":\"cloud-tools\",\"provider\":\"agentbay\",\"copyCookieDomains\":\"mearl-services\"}'", "browser_launch --payload '{\"name\":\"cloud-tools\",\"provider\":\"agentbay\",\"copyCookieDomains\":{\"presets\":[\"mearl-services\"],\"domains\":[\"figma.com\"]}}'", "browser_launch --payload '{\"name\":\"account-a\",\"headless\":true,\"accountId\":12345}'", "browser_launch --payload '{\"name\":\"figma\",\"userAgentMode\":\"desktop\",\"copyCookieDomains\":[\"figma.com\"]}'", "browser_launch --payload '{\"name\":\"account-b\",\"query\":\"test_account\",\"url\":\"https://www.taobao.com\"}'", "browser_launch --payload '{\"name\":\"with-cookies\",\"copyCookieDomains\":[\"example.com\",\"sub.example.org\"]}'"];
 }, {
     readonly name: "browser_close";
     readonly description: "关闭指定托管浏览器并按策略保留或清理本地 Profile / AgentBay Context";

package/dist/commands.js

@@ -296,7 +296,7 @@ export const COMMANDS = [
     },
     {
         name: 'browser_launch',
-        description: '启动本地 Chrome、创建/复用同名 AgentBay 云浏览器，或用 sessionId 接入现有云端 Session',
+        description: '启动本地 Chrome、创建/复用 AgentBay 云浏览器，或通过已注册 Provider 创建浏览器实例',
         params: [
             {
                 name: 'name',
@@ -305,8 +305,13 @@ export const COMMANDS = [
             },
             {
                 name: 'provider',
-                type: '"local" | "agentbay"',
-                description: '运行环境，默认 local；传 sessionId 时自动使用 agentbay，否则 agentbay 从 AGENTBAY_KEY 创建云浏览器',
+                type: 'string',
+                description: '运行环境，默认 local；可传 agentbay 或 mearl --help 中展示的已注册 Provider ID',
+            },
+            {
+                name: 'providerOptions',
+                type: 'Record<string, string>',
+                description: '外部 Provider 注册时声明的实例创建参数',
             },
             {
                 name: 'sessionId',
@@ -360,6 +365,7 @@ export const COMMANDS = [
             },
         ],
         examples: [
+            `browser_launch --payload '{"provider":"brow","providerOptions":{}}'`,
             `browser_launch --payload '{"name":"cloud-a","provider":"agentbay","userAgentMode":"desktop","url":"https://example.com"}'`,
             `browser_launch --payload '{"name":"cloud-public","provider":"agentbay","imageId":"browser_latest","url":"https://example.com"}'`,
             `browser_launch --payload '{"name":"cloud-login","provider":"agentbay","persistent":true,"copyCookieDomains":["example.com"],"url":"https://example.com/account"}'`,

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

@@ -123,7 +123,15 @@ export interface TdbankAccountParams {
     tabId?: number;
     identityId?: string | number;
 }
-export type BrowserStatus = 'connected' | 'running_disconnected' | 'stopped';
+export type BrowserStatus = 'connected' | 'pairing' | 'running_disconnected' | 'stopped';
+export type BrowserTransport = 'extension' | 'cdp' | 'provider';
+export interface BrowserPairingInfo {
+    kind: 'qr';
+    url: string;
+    /** Optional human-readable or provider-specific pairing code. */
+    code?: string;
+    label?: string;
+}
 export interface BrowserSource {
     kind: 'local' | 'remote';
     connectorId?: string;
@@ -139,11 +147,28 @@ export interface BrowserInfoBase {
     source?: BrowserSource;
     extensionVersion?: string;
     nativeHostVersion?: string;
-    transport?: 'extension' | 'cdp';
+    transport?: BrowserTransport;
+    /** External control-provider identity. Present only when transport is provider. */
+    providerId?: string;
+    /** Human-readable Provider name; providerId remains the stable identity. */
+    providerName?: string;
+    providerVersion?: string;
+    providerProtocolVersion?: number;
+    /** Setup information exposed by a provider while it waits for an external device. */
+    pairing?: BrowserPairingInfo;
+}
+export type BrowserScreenshotKind = 'native' | 'reconstructed' | 'none';
+/** Browser-targeted actions that an external provider may implement. */
+export type BrowserCapabilityAction = ExtensionBrowserAction;
+/** Capabilities advertised by an external browser-control provider. */
+export interface BrowserCapabilities {
+    actions: BrowserCapabilityAction[];
+    /** Pixel fidelity of page_screenshot, or none when that action is unavailable. */
+    screenshot: BrowserScreenshotKind;
 }
 export interface RegularBrowserInfo extends BrowserInfoBase {
     type: 'regular';
-    status: 'connected';
+    status: 'connected' | 'pairing';
 }
 export interface ManagedBrowserAccount {
     accountId?: string;
@@ -152,6 +177,7 @@ export interface ManagedBrowserAccount {
 }
 export interface ManagedBrowserInfo extends BrowserInfoBase {
     type: 'managed';
+    status: 'connected' | 'running_disconnected' | 'stopped';
     provider?: 'local' | 'agentbay';
     headless: boolean;
     persistent: boolean;
@@ -199,7 +225,7 @@ export interface BrowserReleaseFailure {
 export interface BrowserReleaseResult {
     released: boolean;
     hadActiveControl: boolean;
-    transports: Array<'extension' | 'cdp'>;
+    transports: BrowserTransport[];
     affectedTabIds: number[];
     /** True when browser_release also removed a sessionId-based local AgentBay attachment. */
     detached?: boolean;
@@ -217,8 +243,10 @@ export interface CookieCopyScope {
 export interface BrowserLaunchParams {
     /** Required when creating a browser; optional when attaching by AgentBay sessionId. */
     name?: string;
-    /** Browser runtime provider. Defaults to local Chrome unless sessionId is present. */
-    provider?: 'local' | 'agentbay';
+    /** Built-in runtime or the id of a registered external Provider. */
+    provider?: string;
+    /** Creation parameters declared by a registered external Provider. */
+    providerOptions?: Record<string, string>;
     /** Attach to an exact live AgentBay session without creating or owning it. */
     sessionId?: string;
     /** AgentBay running-session reuse policy. Defaults to never. */
@@ -879,5 +907,6 @@ export declare const EXTENSION_BROWSER_ACTIONS: {
 };
 export declare function isBrowserAction(value: unknown): value is BrowserAction;
 export declare function isBrowserCommandAction(value: unknown): value is BrowserCommandAction;
+export declare function isBrowserCapabilityAction(value: unknown): value is BrowserCapabilityAction;
 export declare function isExtensionBrowserAction(value: unknown): value is ExtensionBrowserAction;
 export {};

package/dist/generated-browser-action-protocol.js

@@ -200,6 +200,9 @@ export function isBrowserAction(value) {
 export function isBrowserCommandAction(value) {
     return typeof value === 'string' && Object.hasOwn(BROWSER_COMMAND_ACTIONS, value);
 }
+export function isBrowserCapabilityAction(value) {
+    return isExtensionBrowserAction(value);
+}
 export function isExtensionBrowserAction(value) {
     return typeof value === 'string' && Object.hasOwn(EXTENSION_BROWSER_ACTIONS, value);
 }

package/dist/index.d.ts

@@ -6,8 +6,8 @@
  */
 export { UnifiedClient, UnifiedClient as MearlClient, decodeBrowserTarget, invoke, listCloudConnectors, } from './unified.js';
 export type { UnifiedClientOptions, UnifiedInvokeOptions, UnifiedInvokeOptions as InvokeOptions, } from './unified.js';
-export { APP_PROFILE_NAMES, BROWSER_DEVICE_PRESET_NAMES, BROWSER_ACTIONS, BROWSER_COMMAND_ACTIONS, EXTENSION_BROWSER_ACTIONS, PAGE_ACT_ACTIONS, SEND_REQUEST_MAX_FILES, SEND_REQUEST_MAX_TOTAL_BASE64_FILE_BYTES, SEND_REQUEST_MAX_TOTAL_FILE_BYTES, isBrowserAction, isBrowserCommandAction, isExtensionBrowserAction, } from './generated-browser-action-protocol.js';
-export type { ActionStep, AppProfileName, BrowserAction, BrowserActionMap, BrowserActionRequest, BrowserActionResponse, BrowserCloseParams, BrowserCommandAction, BrowserInfo, BrowserInfoBase, BrowserLaunchParams, BrowserListResult, BrowserReleaseFailure, BrowserReleaseResult, BrowserSource, BrowserStatus, CaptureCheckpointParams, CaptureCheckpointResult, BrowserDevicePresetName, BrowserEmulationOptions, ExtensionBrowserAction, GetApiSchemaParams, GetCookieParams, GetCookieResult, GetEventsParams, GetLogsParams, GetMocksParams, GetRequestsParams, GetUserInfoParams, ManagedBrowserAccount, ManagedBrowserInfo, PageClickParams, PageDragEndpoint, PageDragParams, PageDragPoint, PageActAction, PageDiagnosticsOptions, PageDiagnosticsSetting, PageEvalParams, PageFramesParams, PageHoverParams, PageNavigateParams, PageObservationWaitOptions, PagePressParams, PageScreenshotParams, PageScrollParams, PageSelectedElementParams, PageSnapshotParams, PageSnapshotQuery, PageTypeParams, PageUploadParams, PageWaitParams, RecordParams, RegularBrowserInfo, RequestDomainPermissionParams, RulesResult, RunActionName, RunActionsParams, SelectBrowserParams, SelectBrowserResult, SendRequestFile, SendRequestFormValue, SendMtopRequestParams, SendRequestParams, SetAppProfileParams, SetCookieParams, SetCookieResult, SetDeviceEmulationParams, SetMockParams, SetRuleParams, SetTimezoneParams, SetTimezoneResult, TabCloseParams, TabOpenParams, TdbankAccountParams, } from './generated-browser-action-protocol.js';
+export { APP_PROFILE_NAMES, BROWSER_DEVICE_PRESET_NAMES, BROWSER_ACTIONS, BROWSER_COMMAND_ACTIONS, EXTENSION_BROWSER_ACTIONS, PAGE_ACT_ACTIONS, SEND_REQUEST_MAX_FILES, SEND_REQUEST_MAX_TOTAL_BASE64_FILE_BYTES, SEND_REQUEST_MAX_TOTAL_FILE_BYTES, isBrowserAction, isBrowserCapabilityAction, isBrowserCommandAction, isExtensionBrowserAction, } from './generated-browser-action-protocol.js';
+export type { ActionStep, AppProfileName, BrowserAction, BrowserActionMap, BrowserActionRequest, BrowserActionResponse, BrowserCapabilities, BrowserCapabilityAction, BrowserCloseParams, BrowserCommandAction, BrowserInfo, BrowserInfoBase, BrowserLaunchParams, BrowserListResult, BrowserPairingInfo, BrowserReleaseFailure, BrowserReleaseResult, BrowserSource, BrowserStatus, BrowserScreenshotKind, BrowserTransport, CaptureCheckpointParams, CaptureCheckpointResult, BrowserDevicePresetName, BrowserEmulationOptions, ExtensionBrowserAction, GetApiSchemaParams, GetCookieParams, GetCookieResult, GetEventsParams, GetLogsParams, GetMocksParams, GetRequestsParams, GetUserInfoParams, ManagedBrowserAccount, ManagedBrowserInfo, PageClickParams, PageDragEndpoint, PageDragParams, PageDragPoint, PageActAction, PageDiagnosticsOptions, PageDiagnosticsSetting, PageEvalParams, PageFramesParams, PageHoverParams, PageNavigateParams, PageObservationWaitOptions, PagePressParams, PageScreenshotParams, PageScrollParams, PageSelectedElementParams, PageSnapshotParams, PageSnapshotQuery, PageTypeParams, PageUploadParams, PageWaitParams, RecordParams, RegularBrowserInfo, RequestDomainPermissionParams, RulesResult, RunActionName, RunActionsParams, SelectBrowserParams, SelectBrowserResult, SendRequestFile, SendRequestFormValue, SendMtopRequestParams, SendRequestParams, SetAppProfileParams, SetCookieParams, SetCookieResult, SetDeviceEmulationParams, SetMockParams, SetRuleParams, SetTimezoneParams, SetTimezoneResult, TabCloseParams, TabOpenParams, TdbankAccountParams, } from './generated-browser-action-protocol.js';
 import { type UnifiedInvokeOptions } from './unified.js';
 import type * as Protocol from './generated-browser-action-protocol.js';
 export declare function tabCheckpoint(params?: Protocol.CaptureCheckpointParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'tab_checkpoint'>>;

package/dist/index.js

@@ -5,7 +5,7 @@
  * then routes actions using the global browser ids returned by browser_list.
  */
 export { UnifiedClient, UnifiedClient as MearlClient, decodeBrowserTarget, invoke, listCloudConnectors, } from './unified.js';
-export { APP_PROFILE_NAMES, BROWSER_DEVICE_PRESET_NAMES, BROWSER_ACTIONS, BROWSER_COMMAND_ACTIONS, EXTENSION_BROWSER_ACTIONS, PAGE_ACT_ACTIONS, SEND_REQUEST_MAX_FILES, SEND_REQUEST_MAX_TOTAL_BASE64_FILE_BYTES, SEND_REQUEST_MAX_TOTAL_FILE_BYTES, isBrowserAction, isBrowserCommandAction, isExtensionBrowserAction, } from './generated-browser-action-protocol.js';
+export { APP_PROFILE_NAMES, BROWSER_DEVICE_PRESET_NAMES, BROWSER_ACTIONS, BROWSER_COMMAND_ACTIONS, EXTENSION_BROWSER_ACTIONS, PAGE_ACT_ACTIONS, SEND_REQUEST_MAX_FILES, SEND_REQUEST_MAX_TOTAL_BASE64_FILE_BYTES, SEND_REQUEST_MAX_TOTAL_FILE_BYTES, isBrowserAction, isBrowserCapabilityAction, isBrowserCommandAction, isExtensionBrowserAction, } from './generated-browser-action-protocol.js';
 import { invoke } from './unified.js';
 export function tabCheckpoint(params = {}, options) {
     return invoke('tab_checkpoint', params, options);

package/dist/plugin.d.ts

@@ -0,0 +1,18 @@
+import type { UnifiedInvokeOptions } from './unified.js';
+export { assertPluginName, findPluginEntry, findPluginRegistration, listPluginNames, registerPlugin, resolvePluginEntry, unregisterPlugin, PluginError, type PluginRegistration, } from './pluginRegistry.js';
+export type PluginOptions = UnifiedInvokeOptions;
+export interface PluginApp {
+    readonly options: Readonly<PluginOptions>;
+    command(signature: string, handler: PluginHandler, description?: string): void;
+    invoke(action: string, payload?: Record<string, any>, options?: UnifiedInvokeOptions): Promise<any>;
+    progress(message: string): void;
+}
+export type PluginHandler = (input: Record<string, any>) => unknown | Promise<unknown>;
+/** 注册和执行共享一个 app；仅 handler 执行期间开放浏览器调用。 */
+export declare function loadPlugin(entry: string, context: Pick<PluginApp, 'invoke' | 'options' | 'progress'>, pluginName?: string): Promise<{
+    name: string | undefined;
+    description: string | undefined;
+    version: string | undefined;
+    help(namespace: string, name?: string): string;
+    run(positionals: string[], payload?: unknown): Promise<unknown>;
+}>;

package/dist/plugin.js

@@ -0,0 +1,173 @@
+import { readFileSync, statSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { Command } from 'commander';
+import { PluginError } from './pluginRegistry.js';
+export { assertPluginName, findPluginEntry, findPluginRegistration, listPluginNames, registerPlugin, resolvePluginEntry, unregisterPlugin, PluginError, } from './pluginRegistry.js';
+function readPluginVersion(entry) {
+    try {
+        const content = readFileSync(resolve(dirname(entry), '..', 'SKILL.md'), 'utf8');
+        const frontmatter = content.match(/^---\r?\n([\s\S]*?)\r?\n---/)?.[1];
+        const versionLine = frontmatter?.split(/\r?\n/).find(line => /^version:\s*/.test(line));
+        return versionLine?.match(/^version:\s*["']?([^"'#\s]+)["']?\s*$/)?.[1];
+    }
+    catch {
+        return undefined;
+    }
+}
+function isObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function missingPluginEntryMessage(entry, pluginName) {
+    const name = pluginName ?? '<name>';
+    return [
+        '插件入口已失效',
+        '',
+        `插件：${name}`,
+        `入口：${entry}`,
+        '',
+        `卸载命令：npx @mearl/setup plugin uninstall ${name}`,
+    ].join('\n');
+}
+/** 注册和执行共享一个 app；仅 handler 执行期间开放浏览器调用。 */
+export async function loadPlugin(entry, context, pluginName) {
+    try {
+        if (!statSync(entry).isFile())
+            throw new Error('not a file');
+    }
+    catch {
+        throw new PluginError('PLUGIN_ENTRY_MISSING', missingPluginEntryMessage(entry, pluginName));
+    }
+    const commands = new Map();
+    let executing = false;
+    let registering = true;
+    let name;
+    let description;
+    const app = Object.freeze({
+        options: Object.freeze({ ...context.options }),
+        command(signature, handler, description = '') {
+            if (!registering)
+                throw new Error('命令只能在入口注册阶段声明');
+            const [name, ...args] = signature.trim().split(/\s+/);
+            if (!/^[a-z][a-z0-9-]*$/.test(name) || commands.has(name) || typeof handler !== 'function') {
+                throw new Error(`无效或重复的命令: ${signature}`);
+            }
+            const command = new Command(name).description(description);
+            for (const argument of args) {
+                if (!/^(?:<[a-zA-Z][\w-]*(?:\.\.\.)?>|\[[a-zA-Z][\w-]*(?:\.\.\.)?\])$/.test(argument)) {
+                    throw new Error(`无效的位置参数: ${argument}`);
+                }
+                command.argument(argument);
+            }
+            const names = command.registeredArguments.map(argument => argument.name());
+            if (new Set(names).size !== names.length)
+                throw new Error(`参数名称重复: ${signature}`);
+            commands.set(name, { command, signature, handler });
+        },
+        invoke(action, payload = {}, options = {}) {
+            if (!executing)
+                throw new Error('app.invoke 只能在命令执行期间调用');
+            return context.invoke(action, payload, options);
+        },
+        progress(message) {
+            if (!executing)
+                throw new Error('app.progress 只能在命令执行期间调用');
+            if (typeof message !== 'string' || !message)
+                throw new Error('app.progress 需要非空字符串');
+            context.progress(message);
+        },
+    });
+    try {
+        const module = await import(pathToFileURL(entry).href);
+        if (module.name !== undefined && typeof module.name !== 'string')
+            throw new Error('入口的 name 导出必须为字符串');
+        name = module.name;
+        if (module.description !== undefined && typeof module.description !== 'string')
+            throw new Error('入口的 description 导出必须为字符串');
+        description = module.description;
+        if (typeof module.default !== 'function')
+            throw new Error('入口必须默认导出 register(app) 函数');
+        await module.default(app);
+        if (commands.size === 0)
+            throw new Error('入口未注册任何命令');
+    }
+    catch (error) {
+        throw new PluginError('PLUGIN_LOAD_FAILED', `${entry}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    finally {
+        registering = false;
+    }
+    const find = (name) => {
+        const command = commands.get(name);
+        if (!command)
+            throw new PluginError('PLUGIN_COMMAND_NOT_FOUND', `未知子命令: ${name}`);
+        return command;
+    };
+    return {
+        name,
+        description,
+        version: readPluginVersion(entry),
+        help(namespace, name) {
+            const selected = name ? [find(name)] : [...commands.values()];
+            const example = selected[0].command;
+            const input = Object.fromEntries(example.registeredArguments.map(argument => [
+                argument.name(),
+                argument.variadic ? [`<${argument.name()}>`] : `<${argument.name()}>`,
+            ]));
+            return [
+                ...selected.map(({ command, signature }) => `  ${namespace} ${signature}  ${command.description()}`),
+                '',
+                `  ${namespace} --payload '${JSON.stringify({ command: example.name(), input })}'`,
+                '',
+                '常用选项: --browser --timeout --compact --output',
+                '连接或传输排障运行 mearl check --help。',
+                '插件选项: --verbose; -h, --help; -v, --version',
+                'JSON input 直接传给 handler；业务字段与校验规则见对应 skill。',
+            ].join('\n');
+        },
+        async run(positionals, payload) {
+            if (payload !== undefined && positionals.length > 0) {
+                throw new PluginError('PLUGIN_INVALID_INPUT', '位置参数调用与 --payload 调用不能混用');
+            }
+            if (payload !== undefined &&
+                (!isObject(payload) || typeof payload.command !== 'string' || !isObject(payload.input))) {
+                throw new PluginError('PLUGIN_INVALID_INPUT', '--payload 必须为 {"command":"...","input":{...}}');
+            }
+            const envelope = payload;
+            const { command, handler } = find(envelope?.command ?? positionals[0] ?? '');
+            const input = envelope
+                ? { ...envelope.input }
+                : Object.fromEntries(command.registeredArguments
+                    .map((argument, index) => [
+                    argument.name(),
+                    argument.variadic ? positionals.slice(index + 1) : positionals[index + 1],
+                ])
+                    .filter(([, value]) => value !== undefined));
+            if (!envelope &&
+                !command.registeredArguments.some(argument => argument.variadic) &&
+                positionals.length - 1 > command.registeredArguments.length) {
+                throw new PluginError('PLUGIN_INVALID_INPUT', '位置参数过多');
+            }
+            for (const argument of command.registeredArguments) {
+                const value = Object.hasOwn(input, argument.name()) ? input[argument.name()] : undefined;
+                if (argument.required &&
+                    (value === undefined ||
+                        value === null ||
+                        value === '' ||
+                        (Array.isArray(value) && value.length === 0))) {
+                    throw new PluginError('PLUGIN_INVALID_INPUT', `缺少必填参数: ${argument.name()}`);
+                }
+                if (argument.variadic && value !== undefined && !Array.isArray(value)) {
+                    throw new PluginError('PLUGIN_INVALID_INPUT', `${argument.name()} 必须为数组`);
+                }
+            }
+            executing = true;
+            try {
+                return await handler(input);
+            }
+            finally {
+                executing = false;
+            }
+        },
+    };
+}

package/dist/pluginRegistry.d.ts

@@ -0,0 +1,16 @@
+export declare class PluginError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export interface PluginRegistration {
+    entry: string;
+    description?: string;
+}
+export declare function pluginDirectory(): string;
+export declare function assertPluginName(name: string): void;
+export declare function resolvePluginEntry(target: string): string;
+export declare function registerPlugin(name: string, target: string, description?: string): string;
+export declare function unregisterPlugin(name: string): boolean;
+export declare function findPluginRegistration(name: string): PluginRegistration | undefined;
+export declare function findPluginEntry(name: string): string | undefined;
+export declare function listPluginNames(): string[];

package/dist/pluginRegistry.js

@@ -0,0 +1,116 @@
+import { randomUUID } from 'node:crypto';
+import { mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync, } from 'node:fs';
+import { homedir } from 'node:os';
+import { isAbsolute, join, resolve } from 'node:path';
+import { COMMAND_MAP } from './commands.js';
+const RESERVED_NAMES = new Set([
+    'check',
+    'help',
+    'connector_list',
+    'capture_checkpoint',
+    'plugin',
+    'plugins',
+]);
+export class PluginError extends Error {
+    code;
+    constructor(code, message) {
+        super(`${code}: ${message}`);
+        this.code = code;
+    }
+}
+export function pluginDirectory() {
+    return resolve(process.env.MEARL_PLUGIN_DIR || join(homedir(), '.mearl', 'plugins'));
+}
+export function assertPluginName(name) {
+    if (!/^[a-z][a-z0-9-]*$/.test(name) || RESERVED_NAMES.has(name) || COMMAND_MAP.has(name)) {
+        throw new PluginError('PLUGIN_INVALID_NAME', `不可用的插件名称: ${name}`);
+    }
+}
+export function resolvePluginEntry(target) {
+    const absolute = resolve(target);
+    try {
+        const entry = statSync(absolute).isDirectory()
+            ? join(absolute, 'scripts', 'main.mjs')
+            : absolute;
+        if (!statSync(entry).isFile())
+            throw new Error('not a file');
+        return entry;
+    }
+    catch {
+        throw new PluginError('PLUGIN_ENTRY_MISSING', `入口不存在: ${absolute}（目录默认使用 scripts/main.mjs）`);
+    }
+}
+export function registerPlugin(name, target, description) {
+    assertPluginName(name);
+    const entry = resolvePluginEntry(target);
+    const directory = pluginDirectory();
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const file = join(directory, `${name}.json`);
+    // 每个插件独立保存，多个名称并发注册不会覆盖彼此；同名注册原子替换绑定。
+    const temporary = `${file}.${randomUUID()}.tmp`;
+    const summary = description?.trim();
+    const record = { entry, ...(summary ? { description: summary } : {}) };
+    try {
+        writeFileSync(temporary, `${JSON.stringify(record)}\n`, { mode: 0o600, flag: 'wx' });
+        renameSync(temporary, file);
+    }
+    finally {
+        rmSync(temporary, { force: true });
+    }
+    return entry;
+}
+export function unregisterPlugin(name) {
+    assertPluginName(name);
+    const file = join(pluginDirectory(), `${name}.json`);
+    try {
+        rmSync(file);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw new PluginError('PLUGIN_UNINSTALL_FAILED', `无法移除插件注册: ${file}`);
+    }
+}
+export function findPluginRegistration(name) {
+    if (!/^[a-z][a-z0-9-]*$/.test(name))
+        return undefined;
+    const file = join(pluginDirectory(), `${name}.json`);
+    let content;
+    try {
+        content = readFileSync(file, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw new PluginError('PLUGIN_REGISTRY_INVALID', `无法读取插件记录: ${file}`);
+    }
+    try {
+        const record = JSON.parse(content);
+        if (typeof record?.entry !== 'string' || !isAbsolute(record.entry))
+            throw new Error('invalid entry');
+        const description = typeof record.description === 'string' && record.description.trim()
+            ? record.description.trim()
+            : undefined;
+        return { entry: record.entry, ...(description ? { description } : {}) };
+    }
+    catch {
+        throw new PluginError('PLUGIN_REGISTRY_INVALID', `无效的插件记录: ${file}`);
+    }
+}
+export function findPluginEntry(name) {
+    return findPluginRegistration(name)?.entry;
+}
+export function listPluginNames() {
+    try {
+        return readdirSync(pluginDirectory())
+            .filter(file => /^[a-z][a-z0-9-]*\.json$/.test(file))
+            .map(file => file.slice(0, -5))
+            .sort();
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw new PluginError('PLUGIN_REGISTRY_INVALID', '无法读取插件目录');
+    }
+}

package/dist/socket.js

@@ -12,8 +12,9 @@ import os from 'node:os';
 import path from 'node:path';
 import { createRequire } from 'node:module';
 import { StringDecoder } from 'node:string_decoder';
+import { ensureInstalledProvidersRunning } from '@mearl/provider/runtime';
 import { resolveFileRefs } from './fileRefs.js';
-import { listLiveBrowsers, findBrowser, describeBrowser } from './browserRegistry.js';
+import { listLiveBrowsers, findBrowser, describeBrowser, } from './browserRegistry.js';
 import { resolveActionTimeoutSec } from './actionTimeouts.js';
 const require = createRequire(import.meta.url);
 export const CLIENT_VERSION = require('../package.json').version;
@@ -70,6 +71,42 @@ export function decorateBrowserListResult(result) {
         defaultBrowserId: selected?.browserId ?? null,
     };
 }
+function browserListFromProviderRecords(browsers) {
+    const providerBrowsers = browsers
+        .filter(browser => browser.transport === 'provider')
+        .map(browser => ({
+        browserId: browser.browserId,
+        name: browser.browserName,
+        type: 'regular',
+        status: browser.status === 'pairing' ? 'pairing' : 'connected',
+        transport: 'provider',
+        providerId: browser.providerId,
+        providerName: browser.providerName,
+        providerVersion: browser.providerVersion,
+        providerProtocolVersion: browser.providerProtocolVersion,
+        pairing: browser.pairing,
+    }));
+    return {
+        count: providerBrowsers.length,
+        connectedCount: providerBrowsers.filter(browser => browser.status === 'connected').length,
+        browsers: providerBrowsers,
+    };
+}
+function mergeWarnings(result, warnings) {
+    const resultWarnings = Array.isArray(result?.warnings)
+        ? result.warnings.filter((warning) => typeof warning === 'string')
+        : [];
+    const merged = [...new Set([...resultWarnings, ...warnings])];
+    return { ...result, ...(merged.length > 0 ? { warnings: merged } : {}) };
+}
+function supportsAction(browser, action) {
+    if (browser.transport === 'provider' &&
+        (action === 'get_versions' || action === 'browser_close')) {
+        return true;
+    }
+    return (browser.transport !== 'provider' ||
+        browser.capabilities?.actions.some(capability => capability === action) === true);
+}
 function selectBrowserResult(data) {
     const selector = typeof data.browser === 'string' ? data.browser.trim() : '';
     if (!selector) {
@@ -80,7 +117,8 @@ function selectBrowserResult(data) {
         };
     }
     const browsers = listLiveBrowsers();
-    const match = findBrowser(browsers, selector);
+    const controllableBrowsers = browsers.filter(browser => browser.status !== 'pairing');
+    const match = findBrowser(controllableBrowsers, selector);
     if (!match)
         throw new Error(formatNoMatchError(selector, browsers));
     setDefaultBrowser(match.browserId);
@@ -148,7 +186,11 @@ export function invoke(action, data = {}, options = {}) {
     // 统一解析 payload 顶层字段中的 `@<path>` 文件引用（所有 action 通用）
     const resolvedData = resolveFileRefs(data);
     if (action === 'browser_list') {
-        return dispatchInvoke(action, resolvedData, timeoutSec, undefined, undefined, controlSource).then(decorateBrowserListResult);
+        const hasNativeAggregator = listLiveBrowsers().some(liveBrowser => liveBrowser.transport !== 'provider');
+        const providerStartup = hasNativeAggregator
+            ? Promise.resolve([])
+            : ensureInstalledProvidersRunning();
+        return providerStartup.then(providerWarnings => dispatchInvoke(action, resolvedData, timeoutSec, undefined, undefined, controlSource).then(result => decorateBrowserListResult(mergeWarnings(result, providerWarnings))));
     }
     const selector = browser ?? defaultBrowser ?? process.env.MEARL_BROWSER ?? undefined;
     return dispatchInvoke(action, resolvedData, timeoutSec, transport, selector, controlSource);
@@ -176,14 +218,24 @@ async function dispatchInvoke(action, data, timeoutSec, transport, selector, con
         }
     }
     const browsers = listLiveBrowsers();
+    const controllableBrowsers = browsers.filter(browser => browser.status !== 'pairing');
     // Explicit target: must match a live browser; do not silently fall back.
     if (selector) {
         const match = findBrowser(browsers, selector);
         if (!match) {
             throw new Error(formatNoMatchError(selector, browsers));
         }
+        if (match.status === 'pairing' && action !== 'get_versions' && action !== 'browser_close') {
+            throw new Error(`Browser ${describeBrowser(match)} is waiting for device pairing`);
+        }
+        if (transport === 'cdp' && match.transport === 'provider') {
+            throw new Error(`Browser ${describeBrowser(match)} does not support the CDP transport`);
+        }
+        if (!supportsAction(match, action)) {
+            throw new Error(`Browser ${describeBrowser(match)} does not support ${action}`);
+        }
         try {
-            return await invokeOnce(action, data, timeoutSec, transport, match.socketPath, controlSource);
+            return await invokeOnce(action, data, timeoutSec, transport, match.socketPath, controlSource, match.providerBrowserId);
         }
         catch (error) {
             if (isConnError(error) || isSocketSandboxError(error)) {
@@ -196,18 +248,25 @@ async function dispatchInvoke(action, data, timeoutSec, transport, selector, con
     }
     // No explicit target: prefer the most-recently-focused live browser; on a
     // stale socket, fall through to the legacy path + auto-spawn.
-    if (browsers.length > 0) {
+    const routableBrowsers = controllableBrowsers.filter(browser => !(transport === 'cdp' && browser.transport === 'provider') && supportsAction(browser, action));
+    if (routableBrowsers.length > 0) {
+        const target = routableBrowsers[0];
         try {
-            return await invokeOnce(action, data, timeoutSec, transport, browsers[0].socketPath, controlSource);
+            return await invokeOnce(action, data, timeoutSec, transport, target.socketPath, controlSource, target.providerBrowserId);
         }
         catch (error) {
             if (isSocketSandboxError(error)) {
-                throw new Error(formatConnectError(error, browsers[0].socketPath), { cause: error });
+                throw new Error(formatConnectError(error, target.socketPath), {
+                    cause: error,
+                });
             }
             if (!isConnError(error))
                 throw error;
         }
     }
+    if (action === 'browser_list' && browsers.some(browser => browser.transport === 'provider')) {
+        return browserListFromProviderRecords(browsers);
+    }
     return invokeViaLegacy(action, data, timeoutSec, transport, controlSource, /* isRetry */ false);
 }
 /** Legacy well-known socket, auto-spawning a native-host on ENOENT and retrying once. */
@@ -229,8 +288,11 @@ async function invokeViaLegacy(action, data, timeoutSec, transport, controlSourc
                     /* isRetry */ true);
                 }
                 const browsers = listLiveBrowsers();
-                if (browsers.length > 0) {
-                    return invokeOnce(action, data, timeoutSec, transport, browsers[0].socketPath, controlSource);
+                const target = browsers.find(browser => browser.status !== 'pairing' &&
+                    !(transport === 'cdp' && browser.transport === 'provider') &&
+                    supportsAction(browser, action));
+                if (target) {
+                    return invokeOnce(action, data, timeoutSec, transport, target.socketPath, controlSource, target.providerBrowserId);
                 }
                 return invokeViaLegacy(action, data, timeoutSec, transport, controlSource, 
                 /* isRetry */ true);
@@ -241,7 +303,7 @@ async function invokeViaLegacy(action, data, timeoutSec, transport, controlSourc
         throw new Error(formatConnectError(err, SOCKET_PATH), { cause: error });
     }
 }
-function invokeOnce(action, data, timeoutSec, transport, socketPath, controlSource) {
+function invokeOnce(action, data, timeoutSec, transport, socketPath, controlSource, providerBrowserId) {
     const id = `${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
     return new Promise((resolve, reject) => {
         if (process.platform !== 'win32' && fs.existsSync(socketPath) && process.getuid) {
@@ -282,6 +344,8 @@ function invokeOnce(action, data, timeoutSec, transport, socketPath, controlSour
             };
             if (transport)
                 message.transport = transport;
+            if (providerBrowserId)
+                message.browserId = providerBrowserId;
             socket.write(JSON.stringify(message) + '\n');
         });
         socket.on('data', chunk => {

package/dist/unified.js

@@ -302,6 +302,9 @@ export class UnifiedClient {
             ? result.browsers
             : [];
         const browsers = rawBrowsers.map(browser => decorateBrowser(browser, source));
+        const resultWarnings = Array.isArray(result?.warnings)
+            ? result.warnings.filter((warning) => typeof warning === 'string')
+            : [];
         return {
             count: browsers.length,
             connectedCount: browsers.filter(browser => browser.status === 'connected').length,
@@ -312,6 +315,7 @@ export class UnifiedClient {
                 })
                 : null,
             browsers,
+            ...(resultWarnings.length > 0 ? { warnings: resultWarnings } : {}),
         };
     }
     applyConfiguredDefault(listing) {
@@ -374,6 +378,8 @@ export class UnifiedClient {
                 connectorName: connector.name,
             }));
         }
+        for (const listing of listings)
+            warnings.push(...(listing.warnings ?? []));
         const browsers = listings.flatMap(listing => listing.browsers);
         const defaults = listings
             .map(listing => listing.defaultBrowserId)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/client",
-  "version": "2.11.0",
+  "version": "2.13.0",
   "description": "Unified Mearl SDK & CLI for local and remote browsers",
   "type": "module",
   "main": "dist/index.js",
@@ -29,6 +29,10 @@
     "./cli": {
       "types": "./dist/cli.d.ts",
       "import": "./dist/cli.js"
+    },
+    "./plugin": {
+      "types": "./dist/plugin.d.ts",
+      "import": "./dist/plugin.js"
     }
   },
   "bin": {
@@ -55,7 +59,8 @@
     "commander": "^15.0.0",
     "fastest-levenshtein": "^1.0.16",
     "ws": "^8.18.0",
-    "@mearl/cloud-types": "2.11.0"
+    "@mearl/cloud-types": "2.13.0",
+    "@mearl/provider": "2.13.0"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",