@mearl/provider 2.13.0 → 2.14.0

package/README.md

@@ -1,36 +1,29 @@
 # @mearl/provider
 
-External browser providers use this package to register themselves with Mearl, publish their
-available browsers, and handle Mearl browser actions over a local socket.
+`@mearl/provider` 是 Mearl 的统一浏览器 Provider 契约与运行时。内置的 Local Chrome、AgentBay
+和外部 Provider 使用相同的 `BrowserProviderDefinition`；区别只在于运行时位于 Native Host
+进程内，还是通过本地 Provider Socket 接入。
 
-## Installation
+## 核心模型
 
-Provider packages should declare `@mearl/provider` as a runtime dependency:
+Provider v2 分开表达实例状态与控制方式：
 
-```bash
-pnpm add @mearl/provider
-```
+- `status`：实例处于 `connected`、`pairing`、`running_disconnected` 或 `stopped`。
+- `control`：页面操作由 Provider 自己处理、由宿主的 Extension/CDP 处理，或当前没有控制通道。
 
-Provider implementations import the package root. The `/host` and `/runtime` subpaths are for
-Mearl's setup, discovery, and routing processes rather than Provider business code.
+实例还会声明 `ownership`、`persistence`、当前允许的资源 `operations`、稳定
+`references` 和可公开展示的 `details`。因此 Provider identity 不再等同于控制传输，持久化实例
+也不需要伪装成已连接浏览器。
 
-## Provider lifecycle
+## 外部 Provider 安装
 
-1. The provider package declares its protocol entry in `package.json#mearl.provider`.
-2. `npx @mearl/setup provider install <package>` installs the package and registers its metadata.
-3. `mearl browser_list` starts an `on-demand` provider when necessary.
-4. The provider starts `createProviderServer()` and publishes browsers with `updateBrowsers()`.
-5. Mearl reads browser discovery from the shared registry and routes each supported browser action
-   to the provider socket with the provider-local browser id.
-6. The provider removes its live browser records when it stops.
+外部 Provider 包将 `@mearl/provider` 声明为运行依赖：
 
-Mearl discovers only explicit manifests in `~/.mearl/providers/installed`. It does not scan or
-execute arbitrary global packages.
-
-## Package metadata
+```bash
+pnpm add @mearl/provider
+```
 
-Provider packages do not need a user-facing binary or lifecycle scripts. Their `package.json`
-declares an internal Node.js entry owned by the package:
+包的 `package.json#mearl.provider` 声明协议入口、浏览器类型和结构化启动参数：
 
 ```json
 {
@@ -41,90 +34,111 @@ declares an internal Node.js entry owned by the package:
     "provider": {
       "providerId": "example-device",
       "name": "Example device provider",
-      "protocolVersion": 1,
+      "protocolVersion": 2,
       "entry": "./dist/runtime.js",
       "browserType": {
         "name": "Device",
-        "parameters": [
-          { "key": "code", "label": "Pairing code", "placeholder": "Generated by default" }
-        ]
+        "inputSchema": {
+          "type": "object",
+          "properties": {
+            "code": {
+              "type": "string",
+              "title": "Pairing code",
+              "placeholder": "Generated by default"
+            }
+          }
+        }
       }
     }
   }
 }
 ```
 
-The entry must be a relative path to a file inside the installed package. Mearl launches registered
-providers on demand with the current Node.js runtime; packages cannot register arbitrary commands,
-arguments, working directories, or environment overrides.
+Schema 支持 string、number、boolean、array 和递归 object；Provider 配置也可通过
+`browserType.configuration.inputSchema` 声明。`local` 和 `agentbay` 是内置保留 ID。
 
-## Minimal runtime
+## 最小外部运行时
 
 ```ts
-import { createProviderServer } from '@mearl/provider';
+import { createProviderServer, type BrowserProviderDefinition } from '@mearl/provider';
 
-const server = createProviderServer({
-  descriptor: { providerId: 'example', name: 'Example provider', version: '1.0.0' },
-  handleAction: async ({ browserId, action, data }) => {
-    // Translate Mearl actions to the external browser-control backend.
-    return { browserId, action, data };
+const definition: BrowserProviderDefinition = {
+  descriptor: {
+    providerId: 'example-device',
+    name: 'Example device provider',
+    version: '1.0.0',
+  },
+  browserType: {
+    name: 'Device',
+    inputSchema: {
+      type: 'object',
+      properties: { code: { type: 'string', title: 'Pairing code' } },
+    },
   },
-  createBrowser: async parameters => createDevice(parameters),
-  deleteBrowser: async browserId => deleteDevice(browserId),
-});
+  launch: async options => createDevice(String(options.code ?? '')),
+  close: async ({ browserId }) => removeDevice(browserId),
+  handleAction: async ({ browserId, action, data }) =>
+    dispatchDeviceAction(browserId, action, data),
+};
 
+const server = createProviderServer({ definition });
 await server.start();
 server.updateBrowsers([
   {
     browserId: 'device-1',
     name: 'Example device',
-    capabilities: {
-      actions: ['tab_list', 'page_snapshot', 'page_click'],
-      screenshot: 'none',
+    status: 'connected',
+    control: {
+      kind: 'provider',
+      capabilities: {
+        actions: ['tab_list', 'page_snapshot', 'page_click'],
+        screenshot: 'none',
+      },
     },
+    ownership: 'owned',
+    persistence: 'persistent',
+    operations: ['close'],
   },
 ]);
 ```
 
-`createBrowser` returns the Provider-local `browserId`, display `name`, and initial `status`.
-When the initial status is `pairing`, it also returns the same `pairing` metadata published during
-discovery, so `browser_launch` callers can present the QR URL without an extra `browser_list` call.
-Mearl converts that local id into the same global id shape returned by `browser_list`.
-
-A device provider can remain discoverable before its hardware is online by publishing a pairing
-browser. Mearl keeps it out of implicit action routing and can render its QR URL:
+配对中的设备使用 `status: "pairing"` 并提供 `pairing`；停止的持久化实例使用
+`status: "stopped"` 和 `control: { kind: "none" }`。运行但尚未接通控制链路时使用
+`status: "running_disconnected"`。
+Runtime 会统一校验 schema、状态机、操作能力和页面 action capability，校验通过后才调用实现。
+`start`、`detach`、`getAccess`、`syncCookies` 等可选实现必须与实例声明的 operation 对应；
+这些是 Provider runtime 的内部能力，不会要求 Mearl 公共协议增加一一对应的 action。
+
+公共 `browser_launch` 对所有 Provider 接收 `{ provider, providerOptions }`，返回与
+`browser_list.browsers[]` 相同的 `ManagedBrowserInfo`（对象形式的 Provider identity、状态、
+持久化策略、操作和安全元数据）。管理器内部字段、控制连接和临时访问地址不进入该结果。
+Local/AgentBay 的 CLI 顶层参数是便捷输入，由协调层转换；不得与 `providerOptions` 混用。
+
+内置浏览器保留针对本地启动、云端创建和接管的专用交互；外部 Provider 根据
+`browserType.inputSchema` 生成输入项。两者提交同一结构的 `providerOptions`。
+Schema 的顶层 `oneOf` 可声明多个完整对象约束，
+例如创建与接管会话；每个分支用 `title` 命名，Runtime 要求输入恰好匹配一个分支，
+`not` 可排除不允许的字段组合。`default` 是表单初始值，不会隐式修改调用方参数。
+对象字段 `copyCookieDomains` 约定使用 `{ presets?, domains? }` Cookie 范围结构；内置浏览器表单保留范围选择与授权交互。
+`browserType.documentationUrl` 声明 HTTP(S) 文档地址；`configuration.inputSchema` 声明配置参数，
+配置只传给所选 Provider 的 `configure`，不存入页面本地存储。
+
+`details` 中的通用键具有固定类型：`headless` 为布尔值，`createdAt` 为可解析时间字符串，
+`cdpPort` 为有效端口，`account` 包含 `nickname` 和可选的字符串 `accountId/loginId`，
+`copiedCookies` 包含字符串数组 `domains` 和非负整数 `count`。其余键允许非敏感 JSON，界面同样展示。
+`references` 的 `kind` 表示资源类别，`id` 为不透明标识，`label` 为展示名；
+通用类别包括 `profile/session/image/context/context-name`，也允许 Provider 自定义类别。
+
+## 内置运行时
+
+Native Host 使用 `createProviderRuntime(definition)` 直接运行内置 Provider，不需要创建 Socket
+或注册安装记录。内置与外部实现共享同一份 schema 校验、状态机和生命周期派发逻辑；需要宿主服务的进程内调用可通过 `ProviderContext.host` 注入，Provider 合同本身不依赖 Extension、Native Messaging 或
+AgentBay SDK。
+
+外部 Provider 的安装、发现与启动仍由 `@mearl/setup` 管理：
 
-```ts
-const pairing = {
-  kind: 'qr' as const,
-  url: 'https://example.test/pair?id=device-pairing',
-  code: 'device-pairing',
-};
-
-const createBrowser = async () => ({
-  browserId: 'device-pairing',
-  name: 'Pair a device',
-  status: 'pairing' as const,
-  pairing,
-});
-
-server.updateBrowsers([
-  {
-    browserId: 'device-pairing',
-    name: 'Pair a device',
-    status: 'pairing',
-    pairing,
-    capabilities: { actions: [], screenshot: 'none' },
-  },
-]);
+```bash
+npx @mearl/setup provider install <package>
+npx @mearl/setup provider update <provider-id>
+npx @mearl/setup provider uninstall <provider-id>
 ```
-
-Screenshot capability is declared as `native`, `reconstructed`, or `none`, so callers can retain
-the image while distinguishing real pixels from an HTML reconstruction.
-
-Capabilities stay in Mearl's internal routing registry and are returned by `get_versions` for a
-selected provider browser. They are intentionally omitted from `browser_list`; use
-`mearl check --browser <id>` to inspect them. The package accepts only declared browser-targeted Mearl
-actions. Mearl owns discovery, while `browser_launch` and `browser_close` are routed to the
-Provider's `createBrowser` and `deleteBrowser` handlers. Requests for undeclared actions are
-rejected before reaching the provider.

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from './types.js';
 export { PROVIDER_ACTIONS, isProviderAction } from './generated-provider-actions.js';
 export { providerDataDir } from './registry.js';
+export { createProviderRuntime, validateProviderBrowser, validateProviderInput, } from './provider-runtime.js';
 export { createProviderServer } from './server.js';

package/dist/index.js

@@ -1,4 +1,5 @@
 export * from './types.js';
 export { PROVIDER_ACTIONS, isProviderAction } from './generated-provider-actions.js';
 export { providerDataDir } from './registry.js';
+export { createProviderRuntime, validateProviderBrowser, validateProviderInput, } from './provider-runtime.js';
 export { createProviderServer } from './server.js';

package/dist/provider-runtime.d.ts

@@ -0,0 +1,5 @@
+import type { BrowserProviderDefinition, JsonObject, ProviderBrowser, ProviderInputSchema, ProviderObjectSchema, ProviderRuntime } from './types.js';
+export declare function isProviderInputSchema(value: unknown, depth?: number): value is ProviderInputSchema;
+export declare function validateProviderInput(schema: ProviderObjectSchema, value: JsonObject): void;
+export declare function validateProviderBrowser(browser: ProviderBrowser): void;
+export declare function createProviderRuntime(definition: BrowserProviderDefinition): ProviderRuntime;