@mearl/provider 2.14.0 → 2.15.0

package/README.md

@@ -1,8 +1,8 @@
 # @mearl/provider
 
-`@mearl/provider` 是 Mearl 的统一浏览器 Provider 契约与运行时。内置的 Local Chrome、AgentBay
-和外部 Provider 使用相同的 `BrowserProviderDefinition`；区别只在于运行时位于 Native Host
-进程内，还是通过本地 Provider Socket 接入。
+`@mearl/provider` 是 Mearl 的统一浏览器 Provider 契约与运行时。内置 Local Chrome 和外部
+Provider 使用相同的 `BrowserProviderDefinition`；区别只在于运行时位于 Native Host 进程内，
+还是通过本地 Provider Socket 接入。
 
 ## 核心模型
 
@@ -38,6 +38,7 @@ pnpm add @mearl/provider
       "entry": "./dist/runtime.js",
       "browserType": {
         "name": "Device",
+        "help": ["Pair a device, then use its browserId with Mearl actions."],
         "inputSchema": {
           "type": "object",
           "properties": {
@@ -55,7 +56,8 @@ pnpm add @mearl/provider
 ```
 
 Schema 支持 string、number、boolean、array 和递归 object；Provider 配置也可通过
-`browserType.configuration.inputSchema` 声明。`local` 和 `agentbay` 是内置保留 ID。
+`browserType.configuration.inputSchema` 声明。`browserType.help` 由 `mearl <providerId>` 和
+`mearl <providerId> --help` 展示，让 Provider 的操作说明随独立包版本演进。`local` 是内置保留 ID。
 
 ## 最小外部运行时
 
@@ -112,14 +114,19 @@ Runtime 会统一校验 schema、状态机、操作能力和页面 action capabi
 公共 `browser_launch` 对所有 Provider 接收 `{ provider, providerOptions }`，返回与
 `browser_list.browsers[]` 相同的 `ManagedBrowserInfo`（对象形式的 Provider identity、状态、
 持久化策略、操作和安全元数据）。管理器内部字段、控制连接和临时访问地址不进入该结果。
-Local/AgentBay 的 CLI 顶层参数是便捷输入，由协调层转换；不得与 `providerOptions` 混用。
+Local 的 CLI 顶层参数是便捷输入；外部 Provider 参数必须放在 `providerOptions`，两者不得混用。
 
-内置浏览器保留针对本地启动、云端创建和接管的专用交互；外部 Provider 根据
-`browserType.inputSchema` 生成输入项。两者提交同一结构的 `providerOptions`。
+内置浏览器保留本地启动交互；外部 Provider 根据 `browserType.inputSchema` 生成输入项。
+两者提交同一结构的 `providerOptions`。
 Schema 的顶层 `oneOf` 可声明多个完整对象约束，
 例如创建与接管会话；每个分支用 `title` 命名，Runtime 要求输入恰好匹配一个分支，
 `not` 可排除不允许的字段组合。`default` 是表单初始值，不会隐式修改调用方参数。
-对象字段 `copyCookieDomains` 约定使用 `{ presets?, domains? }` Cookie 范围结构；内置浏览器表单保留范围选择与授权交互。
+对象字段 `copyCookieDomains` 约定使用 `{ presets?, domains? }` Cookie 范围结构。
+为这个字段声明 `component: "cookie-sync"` 后，Mearl 浏览器管理器会使用统一的 Cookie
+范围选择组件，并在提交前申请所选站点权限；未声明组件时仍按普通 object 字段渲染。
+Provider 可用 `component: "switch"` 渲染紧凑布尔开关；`formHidden` 隐藏仅供 CLI/API
+使用的高级字段，`formWidth` 控制字段宽度，`formDefault` 设置不影响运行时默认值的表单初值，
+`formHideOptional` 只隐藏可选标识而不改变校验，`formVisibleWhen` 根据另一个字段是否为空控制显示与提交。
 `browserType.documentationUrl` 声明 HTTP(S) 文档地址；`configuration.inputSchema` 声明配置参数，
 配置只传给所选 Provider 的 `configure`，不存入页面本地存储。
 
@@ -131,9 +138,9 @@ Schema 的顶层 `oneOf` 可声明多个完整对象约束，
 
 ## 内置运行时
 
-Native Host 使用 `createProviderRuntime(definition)` 直接运行内置 Provider，不需要创建 Socket
+Native Host 使用 `createProviderRuntime(definition)` 直接运行内置 Local Provider，不需要创建 Socket
 或注册安装记录。内置与外部实现共享同一份 schema 校验、状态机和生命周期派发逻辑；需要宿主服务的进程内调用可通过 `ProviderContext.host` 注入，Provider 合同本身不依赖 Extension、Native Messaging 或
-AgentBay SDK。
+具体浏览器服务 SDK。
 
 外部 Provider 的安装、发现与启动仍由 `@mearl/setup` 管理：
 

package/dist/generated-provider-actions.d.ts

@@ -1,3 +1,3 @@
-export declare const PROVIDER_ACTIONS: readonly ["tab_checkpoint", "capture_checkpoint", "get_requests", "get_logs", "get_events", "get_api_schema", "set_mock", "get_mocks", "set_rule", "get_rules", "send_request", "send_mtop_request", "tdbank_account", "browser_release", "page_screenshot", "page_selected_element", "tab_open", "tab_close", "tab_list", "page_click", "page_drag", "page_type", "page_scroll", "page_hover", "page_eval", "page_snapshot", "page_press", "page_wait", "page_navigate", "page_upload", "page_frames", "set_device_emulation", "set_app_profile", "set_timezone", "get_cookie", "set_cookie", "record_start", "record_stop", "request_domain_permission", "get_user_info", "run_actions"];
+export declare const PROVIDER_ACTIONS: readonly ["tab_checkpoint", "capture_checkpoint", "get_requests", "get_logs", "get_events", "set_mock", "get_mocks", "set_rule", "get_rules", "send_request", "send_mtop_request", "browser_release", "page_screenshot", "page_selected_element", "tab_open", "tab_close", "tab_list", "page_click", "page_drag", "page_type", "page_scroll", "page_hover", "page_eval", "page_snapshot", "page_press", "page_wait", "page_navigate", "page_upload", "page_frames", "set_device_emulation", "set_app_profile", "set_timezone", "get_cookie", "set_cookie", "record_start", "record_stop", "request_domain_permission", "run_actions"];
 export type ProviderAction = (typeof PROVIDER_ACTIONS)[number];
 export declare function isProviderAction(value: unknown): value is ProviderAction;

package/dist/generated-provider-actions.js

@@ -6,14 +6,12 @@ export const PROVIDER_ACTIONS = [
     'get_requests',
     'get_logs',
     'get_events',
-    'get_api_schema',
     'set_mock',
     'get_mocks',
     'set_rule',
     'get_rules',
     'send_request',
     'send_mtop_request',
-    'tdbank_account',
     'browser_release',
     'page_screenshot',
     'page_selected_element',
@@ -40,7 +38,6 @@ export const PROVIDER_ACTIONS = [
     'record_start',
     'record_stop',
     'request_domain_permission',
-    'get_user_info',
     'run_actions',
 ];
 const providerActionSet = new Set(PROVIDER_ACTIONS);

package/dist/provider-runtime.js

@@ -35,7 +35,20 @@ export function isProviderInputSchema(value, depth = 0) {
     const schema = value;
     if (!isOptionalString(schema.title) ||
         !isOptionalString(schema.description) ||
-        (schema.default !== undefined && !isJsonValue(schema.default))) {
+        (schema.component !== undefined &&
+            !['cookie-sync', 'switch'].includes(String(schema.component))) ||
+        (schema.default !== undefined && !isJsonValue(schema.default)) ||
+        (schema.formDefault !== undefined && !isJsonValue(schema.formDefault)) ||
+        (schema.formHidden !== undefined && typeof schema.formHidden !== 'boolean') ||
+        (schema.formWidth !== undefined && !['half', 'full'].includes(String(schema.formWidth))) ||
+        (schema.formHideOptional !== undefined && typeof schema.formHideOptional !== 'boolean') ||
+        (schema.formVisibleWhen !== undefined &&
+            (!schema.formVisibleWhen ||
+                typeof schema.formVisibleWhen !== 'object' ||
+                Array.isArray(schema.formVisibleWhen) ||
+                typeof schema.formVisibleWhen.field !== 'string' ||
+                !schema.formVisibleWhen.field ||
+                typeof schema.formVisibleWhen.empty !== 'boolean'))) {
         return false;
     }
     if (schema.type === 'string') {
@@ -98,6 +111,12 @@ export function isProviderInputSchema(value, depth = 0) {
         if (!Object.values(properties).every(item => isProviderInputSchema(item, depth + 1))) {
             return false;
         }
+        if (Object.values(properties).some(item => {
+            const condition = item.formVisibleWhen;
+            return condition !== undefined && !(String(condition.field) in properties);
+        })) {
+            return false;
+        }
         if (schema.not !== undefined &&
             (!isProviderInputSchema(schema.not, depth + 1) || schema.not.type !== 'object'))
             return false;
@@ -113,6 +132,10 @@ export function isProviderInputSchema(value, depth = 0) {
             return false;
         }
     }
+    if (schema.component === 'cookie-sync' && schema.type !== 'object')
+        return false;
+    if (schema.component === 'switch' && schema.type !== 'boolean')
+        return false;
     if (schema.default !== undefined) {
         try {
             validateSchemaValue(value, schema.default, 'default');
@@ -121,6 +144,14 @@ export function isProviderInputSchema(value, depth = 0) {
             return false;
         }
     }
+    if (schema.formDefault !== undefined) {
+        try {
+            validateSchemaValue(value, schema.formDefault, 'formDefault');
+        }
+        catch {
+            return false;
+        }
+    }
     return true;
 }
 function fail(path, message) {
@@ -326,11 +357,6 @@ export function validateProviderBrowser(browser) {
                     !Number.isFinite(Date.parse(details.createdAt)))) ||
             (details.cdpPort !== undefined &&
                 (!Number.isInteger(details.cdpPort) || details.cdpPort < 1 || details.cdpPort > 65535)) ||
-            (details.account !== undefined &&
-                (!details.account ||
-                    typeof details.account.nickname !== 'string' ||
-                    !isOptionalString(details.account.accountId) ||
-                    !isOptionalString(details.account.loginId))) ||
             (details.copiedCookies !== undefined &&
                 (!details.copiedCookies ||
                     !strings(details.copiedCookies.domains) ||

package/dist/registry.js

@@ -11,9 +11,14 @@ export const PROVIDER_SOCKETS_SUBDIR = 'providers/sockets';
 export const PROVIDER_DATA_SUBDIR = 'providers/data';
 export const BROWSERS_SUBDIR = 'browsers';
 export const PROVIDER_START_TOKEN_ENV = 'MEARL_PROVIDER_START_TOKEN';
-const RESERVED_PROVIDER_IDS = new Set(['local', 'agentbay']);
+const RESERVED_PROVIDER_IDS = new Set(['local']);
 export function providerBrowserKey(providerId, browserId) {
-    return `provider:${encodeURIComponent(providerId)}:${encodeURIComponent(browserId)}`;
+    const redundantPrefix = `managed:${providerId}:`;
+    const scopedBrowserId = browserId.toLowerCase().startsWith(redundantPrefix.toLowerCase())
+        ? browserId.slice(redundantPrefix.length)
+        : browserId;
+    const encodedBrowserId = encodeURIComponent(scopedBrowserId).replace(/%3A/gi, ':');
+    return `provider:${encodeURIComponent(providerId)}:${encodedBrowserId}`;
 }
 export function providerSocketPath(providerId) {
     const suffix = hashKey(providerId);
@@ -144,6 +149,10 @@ function isProviderBrowserType(value) {
         (typeof browserType.documentationUrl !== 'string' ||
             !/^https?:\/\//.test(browserType.documentationUrl)))
         return false;
+    if (browserType.help !== undefined &&
+        (!Array.isArray(browserType.help) ||
+            browserType.help.some(item => typeof item !== 'string' || !item.trim())))
+        return false;
     if (!isProviderObjectSchema(browserType.inputSchema))
         return false;
     return (browserType.configuration === undefined ||

package/dist/server.js

@@ -12,6 +12,15 @@ const activeProviderIds = new Set();
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
+function isProviderHostContextData(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const host = value;
+    return ((host.userAgent === undefined || typeof host.userAgent === 'string') &&
+        (host.cookies === undefined ||
+            (Array.isArray(host.cookies) &&
+                host.cookies.every(cookie => cookie && typeof cookie === 'object' && !Array.isArray(cookie)))));
+}
 function isProviderActionRequest(value) {
     if (!value || typeof value !== 'object' || Array.isArray(value))
         return false;
@@ -26,7 +35,30 @@ function isProviderActionRequest(value) {
                 !Array.isArray(request.data))) &&
         (request.browserId === undefined || typeof request.browserId === 'string') &&
         (request.version === undefined || typeof request.version === 'string') &&
-        (request.controlSource === undefined || typeof request.controlSource === 'string'));
+        (request.controlSource === undefined || typeof request.controlSource === 'string') &&
+        (request.host === undefined || isProviderHostContextData(request.host)));
+}
+function providerContext(request) {
+    const hostData = request.host;
+    return {
+        controlSource: request.controlSource,
+        ...(hostData
+            ? {
+                host: {
+                    async request(method) {
+                        if (method === 'export_cookies')
+                            return (hostData.cookies ?? []);
+                        if (method === 'get_browser_user_agent') {
+                            if (!hostData.userAgent)
+                                throw new Error('Host browser user agent is unavailable');
+                            return hostData.userAgent;
+                        }
+                        throw new Error(`Unsupported Provider host service: ${method}`);
+                    },
+                },
+            }
+            : {}),
+    };
 }
 export function createProviderServer(options) {
     const runtime = createProviderRuntime(options.definition);
@@ -49,24 +81,25 @@ export function createProviderServer(options) {
         throw new Error('browserId is required when the provider has multiple browsers');
     }
     async function dispatch(request) {
+        const context = providerContext(request);
         if (request.action === 'browser_launch') {
             if (request.browserId)
                 throw new Error('browser_launch does not accept browserId');
-            return runtime.launch(request.data ?? {}, { controlSource: request.controlSource });
+            return runtime.launch(request.data ?? {}, context);
         }
         if (request.action === 'browser_provider_configure') {
             if (request.browserId)
                 throw new Error('Provider configuration does not accept browserId');
-            return runtime.configure(request.data ?? {}, { controlSource: request.controlSource });
+            return runtime.configure(request.data ?? {}, context);
         }
         if (request.action === 'browser_manager_start') {
-            return runtime.start({ browserId: await providerBrowserId(request.browserId) }, { controlSource: request.controlSource });
+            return runtime.start({ browserId: await providerBrowserId(request.browserId) }, context);
         }
         if (request.action === 'browser_manager_sync_cookies') {
             return runtime.syncCookies({
                 browserId: await providerBrowserId(request.browserId),
                 scope: request.data?.scope,
-            }, { controlSource: request.controlSource });
+            }, context);
         }
         if (request.action !== 'get_versions' &&
             request.action !== 'browser_close' &&
@@ -76,11 +109,11 @@ export function createProviderServer(options) {
         }
         const browserId = await providerBrowserId(request.browserId);
         if (request.action === 'browser_close') {
-            return runtime.close({ browserId, deleteData: request.data?.deleteProfile === true }, { controlSource: request.controlSource });
+            return runtime.close({ browserId, deleteData: request.data?.deleteProfile === true }, context);
         }
         if (request.action === 'get_browser_access_url') {
             return {
-                browserAccess: await runtime.getAccess({ browserId }, { controlSource: request.controlSource }),
+                browserAccess: await runtime.getAccess({ browserId }, context),
             };
         }
         if (request.action === 'get_versions') {
@@ -101,7 +134,7 @@ export function createProviderServer(options) {
         if (request.action === 'browser_release') {
             const found = (await runtime.listBrowsers()).find(browser => browser.browserId === browserId);
             if (found?.operations.includes('detach')) {
-                return runtime.detach({ browserId }, { controlSource: request.controlSource });
+                return runtime.detach({ browserId }, context);
             }
         }
         touchProviderBrowser(providerBrowserKey(descriptor.providerId, browserId));

package/dist/types.d.ts

@@ -24,10 +24,27 @@ export interface ProviderDescriptor {
     protocolVersion?: number;
     builtin?: boolean;
 }
+export type ProviderInputComponent = 'cookie-sync' | 'switch';
+export interface ProviderInputVisibility {
+    field: string;
+    empty: boolean;
+}
 interface ProviderSchemaBase {
     title?: string;
     description?: string;
     default?: JsonValue;
+    /** Optional Mearl form component used to edit this schema value. */
+    component?: ProviderInputComponent;
+    /** Presentation-only default used by Mearl forms without changing runtime semantics. */
+    formDefault?: JsonValue;
+    /** Excludes an advanced runtime option from generated Mearl forms. */
+    formHidden?: boolean;
+    /** Places compact fields side by side in generated Mearl forms. */
+    formWidth?: 'half' | 'full';
+    /** Hides the optional badge without changing schema validation. */
+    formHideOptional?: boolean;
+    /** Conditionally displays and submits this field based on another form value. */
+    formVisibleWhen?: ProviderInputVisibility;
 }
 export interface ProviderStringSchema extends ProviderSchemaBase {
     type: 'string';
@@ -68,6 +85,8 @@ export interface ProviderConfigurationDefinition {
 export interface ProviderBrowserType {
     name: string;
     documentationUrl?: string;
+    /** Provider-owned usage guidance rendered by `mearl <providerId>`. */
+    help?: readonly string[];
     inputSchema: ProviderObjectSchema;
     configuration?: ProviderConfigurationDefinition;
 }
@@ -91,11 +110,6 @@ export type ProviderBrowserDetails = JsonObject & {
     headless?: boolean;
     createdAt?: string;
     cdpPort?: number;
-    account?: {
-        nickname: string;
-        accountId?: string;
-        loginId?: string;
-    };
     copiedCookies?: {
         domains: string[];
         count: number;
@@ -143,6 +157,7 @@ export interface ProviderActionRequest {
     browserId?: string;
     version?: string;
     controlSource?: string;
+    host?: ProviderHostContextData;
 }
 export interface ProviderActionContext {
     browserId: string;
@@ -153,6 +168,11 @@ export interface ProviderActionContext {
 export interface ProviderHostServices {
     request<T = JsonValue>(method: string, data?: JsonObject): Promise<T>;
 }
+/** Host-derived launch data carried over the local Provider protocol. */
+export interface ProviderHostContextData {
+    cookies?: JsonObject[];
+    userAgent?: string;
+}
 export interface ProviderContext {
     host?: ProviderHostServices;
     controlSource?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/provider",
-  "version": "2.14.0",
+  "version": "2.15.0",
   "description": "Unified contracts and runtime utilities for built-in and external Mearl browser providers",
   "type": "module",
   "main": "dist/index.js",
@@ -35,7 +35,7 @@
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
-    "@mearl/daemon-core": "2.14.0"
+    "@mearl/daemon-core": "2.15.0"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",