@mearl/client 2.10.0 → 2.12.0

package/README.md

@@ -69,7 +69,9 @@ 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":"cloud-login","provider":"agentbay","persistent":true,"userAgentMode":"desktop","copyCookieDomains":["example.com"],"url":"https://example.com/account"}'
 mearl browser_launch --browser '<控制浏览器 browserId>' --payload '{"name":"cloud-login","provider":"agentbay","reuse":"require","copyCookieDomains":["example.com"]}'
+mearl browser_launch --browser '<本地来源 browserId>' --payload '{"sessionId":"<其他设备创建的 AgentBay sessionId>","copyCookieDomains":["example.com"]}'
 mearl browser_launch --payload '{"name":"cloud-tools","provider":"agentbay","copyCookieDomains":"mearl-services"}'
+mearl browser_launch --payload '{"name":"cloud-tools-plus","provider":"agentbay","copyCookieDomains":{"presets":["mearl-services"],"domains":["figma.com"]}}'
 mearl browser_launch --payload '{"name":"figma","userAgentMode":"desktop","copyCookieDomains":["figma.com"]}'
 mearl browser_list
 mearl browser_release
@@ -95,6 +97,41 @@ mearl browser_release
 
 `check` 有独立的选项说明，运行 `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)`，通过 `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)。
+
 ## 支持的操作
 
 | 分类          | Actions                                                                                                                              |
@@ -120,9 +157,9 @@ mearl browser_release
 
 `browser_list` 统一列出普通浏览器和托管浏览器。`type` 区分 `regular` / `managed`，`status` 区分 `connected` / `running_disconnected` / `stopped`；只有 `connected` 的浏览器可作为操作目标。
 
-`browser_release` 仅在用户明确要求结束调试、退出接管或清理会话资源时使用，不作为普通任务收尾。它会释放当前目标浏览器的 debugger/CDP 控制和会话级临时状态（包括设备/时区模拟），保留浏览器及全部标签页；后续浏览器操作可自动重新建立控制。
+按 `sessionId` 接入的 AgentBay 浏览器用 `browser_release` 收尾：它会移除本机 attachment 并退出对应宿主，但不会关闭云端 Session。其他浏览器仅在用户明确要求结束调试、退出接管或清理会话资源时调用；它会释放 debugger/CDP 控制和会话级临时状态（包括设备/时区模拟），保留浏览器及全部标签页，后续浏览器操作可自动重新建立控制。
 
-托管浏览器使用独立 Profile。控制浏览器需先登录 TDBank；生成的 SSO 地址在本地内部传递，本地实例可以使用 `headless: true`（默认）完成测试账号登录。AgentBay 固定为非 headless，传 `headless: true` 会被拒绝；`imageId` 可指定镜像别名或具体镜像 ID，省略时使用已验证的 Linux Browser Use 内网镜像。`persistent: true` 会让本地实例保留 Profile，让 AgentBay 同名实例绑定稳定的云端 Browser Context；正常关闭时同步 Cookie、LocalStorage、IndexedDB 等状态，下次启动无需再次复制本地登录态。`deleteProfile: true` 会显式删除对应 Profile 或 Context。AgentBay 的 `reuse` 支持 `never`（默认）、`prefer` 和 `require`：`prefer` 存在运行实例时复用、否则创建，`require` 只复用且不会意外创建计费会话。`copyCookieDomains` 传数组时把控制浏览器指定域的 Cookie 写入目标，传 `"mearl-services"` 时同步 Mearl 依赖平台登录态。Cookie 值不会经过 cloud-server，也不会出现在命令结果或日志中；`userAgentMode: "desktop"` 让本地实例使用匹配本机 Chrome 版本的桌面 UA，AgentBay 则复用当前控制浏览器的桌面 UA。`browser_list` 仅返回浏览器的稳定配置，不携带 AgentBay 串流入口或沙箱 noVNC 地址。需要时显式运行 `mearl check --browser <id|名称>`，由统一的浏览器访问入口能力实时返回 `browserAccess`；AgentBay、OpenSandbox 和 AONE Sandbox 地址都应按敏感信息处理。完整设计见 [托管浏览器与 TDBank 多账号设计](../../docs/managed-browsers.md)。
+托管浏览器使用独立 Profile。控制浏览器需先登录 TDBank；生成的 SSO 地址在本地内部传递，本地实例可以使用 `headless: true`（默认）完成测试账号登录。AgentBay 固定为非 headless，传 `headless: true` 会被拒绝；`imageId` 可指定镜像别名或具体镜像 ID，省略时使用已验证的 Linux Browser Use 内网镜像。`persistent: true` 会让本地实例保留 Profile，让 AgentBay 同名实例绑定稳定的云端 Browser Context；正常关闭时同步 Cookie、LocalStorage、IndexedDB 等状态，下次启动无需再次复制本地登录态。`deleteProfile: true` 会显式删除对应 Profile 或 Context。AgentBay 的 `reuse` 支持 `never`（默认）、`prefer` 和 `require`：`prefer` 存在运行实例时复用、否则创建，`require` 只复用且不会意外创建计费会话。另一台设备已知确切 Session 时，可传 `sessionId` 直接通过 AgentBay CDP 接入，不需要 cloud-server；当前设备需配置能访问该 Session 的 `AGENTBAY_KEY`。provider-local ID 为 `managed:agentbay:session:<sessionId>`，跨 CLI 调用使用启动响应中的全局 `browserId`，且本机只持有 attachment。`copyCookieDomains` 传数组时复制指定域，传 `"mearl-services"` 时同步 Mearl 依赖平台登录态；需要同时复制基础登录态和额外站点时传 `{ "presets": ["mearl-services"], "domains": [...] }`。Cookie 值不会经过 cloud-server，也不会出现在命令结果或日志中；`userAgentMode: "desktop"` 让本地实例使用匹配本机 Chrome 版本的桌面 UA，AgentBay 则复用当前控制浏览器的桌面 UA。`browser_list` 仅返回浏览器的稳定配置，不携带 AgentBay 串流入口或沙箱 noVNC 地址。需要时显式运行 `mearl check --browser <id|名称>`，由统一的浏览器访问入口能力实时返回 `browserAccess`；AgentBay、OpenSandbox 和 AONE Sandbox 地址都应按敏感信息处理。完整设计见 [托管浏览器与 TDBank 多账号设计](../../docs/managed-browsers.md)。
 
 ## 架构
 

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

@@ -7,6 +7,7 @@ import { commandInput, findCommandSuggestions, formatCommandSuggestions, } from
 import { COMMANDS, COMMAND_MAP } from './commands.js';
 import { CLIENT_VERSION } from './socket.js';
 import { UnifiedClient } from './unified.js';
+import { findPluginEntry, listPluginNames, loadPlugin, PluginError } from './plugin.js';
 import { getCloudServerConfigPath, loadCloudServerConfig } from './unifiedConfig.js';
 const CATEGORIES = [
     {
@@ -100,6 +101,14 @@ function printUsage(commandName, version) {
                 lines.push(`    ${name.padEnd(26)}${command.summary ?? command.description}`);
         }
     }
+    try {
+        const plugins = listPluginNames();
+        if (plugins.length)
+            lines.push('', '已注册插件：', ...plugins.map(name => `  ${name}`));
+    }
+    catch (error) {
+        lines.push('', error instanceof Error ? error.message : String(error));
+    }
     lines.push('', `运行 ${commandName} <action> --help 查看 action 参数。`);
     console.error(lines.join('\n'));
 }
@@ -162,7 +171,7 @@ function printCommandHelp(commandName, command) {
 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 +222,7 @@ function resolveServer(explicit) {
         ? { serverUrl: config.server, serverUrlSource: getCloudServerConfigPath() }
         : {};
 }
-export function parseClientArgs(args) {
+export function parseClientArgs(args, plugin = false) {
     const program = new Command()
         .name('mearl')
         .helpOption(false)
@@ -232,6 +241,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,6 +258,9 @@ 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');
@@ -266,8 +284,85 @@ export function parseClientArgs(args) {
         ...(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 +389,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;
     }

package/dist/commands.d.ts

@@ -386,21 +386,24 @@ export declare const COMMANDS: readonly [{
     readonly examples: ["browser_list"];
 }, {
     readonly name: "browser_release";
-    readonly description: "按用户明确要求释放调试控制和会话级临时效果（含设备/时区模拟），保留浏览器和全部标签页；不用于普通任务收尾";
-    readonly summary: "释放浏览器调试控制及会话级临时效果";
+    readonly description: "sessionId 接入的 AgentBay 浏览器用它解除本机 attachment且不关闭云端 Session；其他浏览器仅按用户明确要求释放调试控制和会话级临时效果（含设备/时区模拟），不用于普通任务收尾";
+    readonly summary: "释放浏览器控制或解除 Session attachment";
     readonly examples: ["browser_release", "browser_release --browser chrome-a"];
 }, {
     readonly name: "browser_launch";
-    readonly description: "启动本地 Chrome，或创建/显式复用 AgentBay 云浏览器，并通过 CDP 接入 Mearl";
+    readonly description: "启动本地 Chrome、创建/复用同名 AgentBay 云浏览器，或用 sessionId 接入现有云端 Session";
     readonly params: [{
         readonly name: "name";
         readonly type: "string";
-        readonly required: true;
-        readonly description: "实例名称，最多 64 个字符";
+        readonly description: "实例名称，创建浏览器时必填；按 sessionId 接入时可省略";
     }, {
         readonly name: "provider";
         readonly type: "\"local\" | \"agentbay\"";
-        readonly description: "运行环境，默认 local；agentbay 从 AGENTBAY_KEY 创建云浏览器";
+        readonly description: "运行环境，默认 local；传 sessionId 时自动使用 agentbay，否则 agentbay 从 AGENTBAY_KEY 创建云浏览器";
+    }, {
+        readonly name: "sessionId";
+        readonly type: "string";
+        readonly description: "显式接入现有 AgentBay Session；不会创建、初始化或取得其生命周期所有权";
     }, {
         readonly name: "reuse";
         readonly type: "\"never\" | \"prefer\" | \"require\"";
@@ -451,10 +454,10 @@ export declare const COMMANDS: readonly [{
         readonly description: "CDP 控制浏览器中用于读取 TDBank Cookie 的标签页";
     }, {
         readonly name: "copyCookieDomains";
-        readonly type: "string[] | \"mearl-services\"";
-        readonly description: "从控制浏览器复制 Cookie：传域名数组，或传 mearl-services 同步 Mearl 依赖平台登录态";
+        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 --payload '{\"name\":\"cloud-tools\",\"provider\":\"agentbay\",\"copyCookieDomains\":\"mearl-services\"}'", "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 '{\"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

@@ -290,19 +290,28 @@ export const COMMANDS = [
     },
     {
         name: 'browser_release',
-        description: '按用户明确要求释放调试控制和会话级临时效果（含设备/时区模拟），保留浏览器和全部标签页；不用于普通任务收尾',
-        summary: '释放浏览器调试控制及会话级临时效果',
+        description: 'sessionId 接入的 AgentBay 浏览器用它解除本机 attachment且不关闭云端 Session；其他浏览器仅按用户明确要求释放调试控制和会话级临时效果（含设备/时区模拟），不用于普通任务收尾',
+        summary: '释放浏览器控制或解除 Session attachment',
         examples: ['browser_release', 'browser_release --browser chrome-a'],
     },
     {
         name: 'browser_launch',
-        description: '启动本地 Chrome，或创建/显式复用 AgentBay 云浏览器，并通过 CDP 接入 Mearl',
+        description: '启动本地 Chrome、创建/复用同名 AgentBay 云浏览器，或用 sessionId 接入现有云端 Session',
         params: [
-            { name: 'name', type: 'string', required: true, description: '实例名称，最多 64 个字符' },
+            {
+                name: 'name',
+                type: 'string',
+                description: '实例名称，创建浏览器时必填；按 sessionId 接入时可省略',
+            },
             {
                 name: 'provider',
                 type: '"local" | "agentbay"',
-                description: '运行环境，默认 local；agentbay 从 AGENTBAY_KEY 创建云浏览器',
+                description: '运行环境，默认 local；传 sessionId 时自动使用 agentbay，否则 agentbay 从 AGENTBAY_KEY 创建云浏览器',
+            },
+            {
+                name: 'sessionId',
+                type: 'string',
+                description: '显式接入现有 AgentBay Session；不会创建、初始化或取得其生命周期所有权',
             },
             {
                 name: 'reuse',
@@ -346,8 +355,8 @@ export const COMMANDS = [
             },
             {
                 name: 'copyCookieDomains',
-                type: 'string[] | "mearl-services"',
-                description: '从控制浏览器复制 Cookie：传域名数组，或传 mearl-services 同步 Mearl 依赖平台登录态',
+                type: 'string[] | "mearl-services" | { presets?: ["mearl-services"]; domains?: string[] }',
+                description: '从控制浏览器复制 Cookie：可传域名数组、Mearl 登录态预设，或组合预设与额外域名',
             },
         ],
         examples: [
@@ -355,7 +364,9 @@ export const COMMANDS = [
             `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"}'`,

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

@@ -157,6 +157,8 @@ export interface ManagedBrowserInfo extends BrowserInfoBase {
     persistent: boolean;
     cdpPort?: number;
     agentbaySessionId?: string;
+    /** Whether this host owns the AgentBay session lifecycle or only attaches to it. */
+    agentbaySessionMode?: 'owned' | 'attached';
     /** AgentBay image used to create the session. */
     agentbayImageId?: string;
     /** Persistent AgentBay browser context ID when enabled for this instance. */
@@ -199,12 +201,26 @@ export interface BrowserReleaseResult {
     hadActiveControl: boolean;
     transports: Array<'extension' | 'cdp'>;
     affectedTabIds: number[];
+    /** True when browser_release also removed a sessionId-based local AgentBay attachment. */
+    detached?: boolean;
+    /** Attached sessions remain alive in AgentBay after the local attachment is released. */
+    sessionClosed?: boolean;
+    agentbaySessionId?: string;
     failures?: BrowserReleaseFailure[];
 }
+export interface CookieCopyScope {
+    /** Maintained authentication-domain presets to include. */
+    presets?: Array<'mearl-services'>;
+    /** Additional domains or URLs to copy alongside the selected presets. */
+    domains?: string[];
+}
 export interface BrowserLaunchParams {
-    name: string;
-    /** Browser runtime provider. Defaults to local Chrome. */
+    /** 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';
+    /** Attach to an exact live AgentBay session without creating or owning it. */
+    sessionId?: string;
     /** AgentBay running-session reuse policy. Defaults to never. */
     reuse?: 'never' | 'prefer' | 'require';
     /** AgentBay image alias or concrete image ID. Only supported by the AgentBay provider. */
@@ -221,8 +237,8 @@ export interface BrowserLaunchParams {
     site?: string | number;
     query?: string;
     tabId?: number;
-    /** Copy explicit domains or the fixed Mearl-service preset from the control browser. */
-    copyCookieDomains?: string[] | 'mearl-services';
+    /** Copy explicit domains, the Mearl-service preset, or a combination of both. */
+    copyCookieDomains?: string[] | 'mearl-services' | CookieCopyScope;
 }
 export interface BrowserCloseParams {
     browser: string;

package/dist/plugin.d.ts

@@ -0,0 +1,17 @@
+import type { UnifiedInvokeOptions } from './unified.js';
+export { assertPluginName, findPluginEntry, listPluginNames, registerPlugin, resolvePluginEntry, unregisterPlugin, PluginError, } 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;
+    version: string | undefined;
+    help(namespace: string, name?: string): string;
+    run(positionals: string[], payload?: unknown): Promise<unknown>;
+}>;

package/dist/plugin.js

@@ -0,0 +1,167 @@
+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, 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;
+    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 (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,
+        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 --connector --local --cdp --server --timeout --compact --output',
+                '插件选项: --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,11 @@
+export declare class PluginError extends Error {
+    readonly code: string;
+    constructor(code: string, message: 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): string;
+export declare function unregisterPlugin(name: string): boolean;
+export declare function findPluginEntry(name: string): string | undefined;
+export declare function listPluginNames(): string[];

package/dist/pluginRegistry.js

@@ -0,0 +1,108 @@
+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) {
+    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`;
+    try {
+        writeFileSync(temporary, `${JSON.stringify({ entry })}\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 findPluginEntry(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');
+        return record.entry;
+    }
+    catch {
+        throw new PluginError('PLUGIN_REGISTRY_INVALID', `无效的插件记录: ${file}`);
+    }
+}
+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

@@ -11,6 +11,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { createRequire } from 'node:module';
+import { StringDecoder } from 'node:string_decoder';
 import { resolveFileRefs } from './fileRefs.js';
 import { listLiveBrowsers, findBrowser, describeBrowser } from './browserRegistry.js';
 import { resolveActionTimeoutSec } from './actionTimeouts.js';
@@ -255,6 +256,7 @@ function invokeOnce(action, data, timeoutSec, transport, socketPath, controlSour
         const socket = net.createConnection(socketPath);
         let settled = false;
         let buffer = '';
+        const decoder = new StringDecoder('utf8');
         const settle = (error, result) => {
             if (settled)
                 return;
@@ -283,7 +285,7 @@ function invokeOnce(action, data, timeoutSec, transport, socketPath, controlSour
             socket.write(JSON.stringify(message) + '\n');
         });
         socket.on('data', chunk => {
-            buffer += chunk.toString('utf-8');
+            buffer += decoder.write(chunk);
             if (Buffer.byteLength(buffer, 'utf-8') > MAX_SOCKET_BUFFER_SIZE) {
                 settle(new Error(`Socket 响应超过 ${MAX_SOCKET_BUFFER_SIZE} 字节限制`));
                 return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/client",
-  "version": "2.10.0",
+  "version": "2.12.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,7 @@
     "commander": "^15.0.0",
     "fastest-levenshtein": "^1.0.16",
     "ws": "^8.18.0",
-    "@mearl/cloud-types": "2.10.0"
+    "@mearl/cloud-types": "2.12.0"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",