@mearl/client 3.0.0-beta.0 → 3.0.0-beta.10

package/dist/commands.js

@@ -1,6 +1,4 @@
-import { APP_PROFILE_NAMES, BROWSER_DEVICE_PRESET_NAMES, } from '@mearl/browser-core';
-/** 容器档案名列表（拼进参数说明，新增档案无需改本文件） */
-const APP_PROFILE_NAME_LIST = APP_PROFILE_NAMES.join('/');
+import { BROWSER_DEVICE_PRESET_NAMES, } from '@mearl/browser-core';
 const DEVICE_PRESET_TYPE = BROWSER_DEVICE_PRESET_NAMES.map(name => JSON.stringify(name)).join(' | ');
 const PAGE_DIAGNOSTICS_PARAM = {
     name: 'diagnostics',
@@ -30,13 +28,20 @@ const PAGE_OBSERVE_PARAM = {
 const PAGE_ACTION_RESULT = [
     '默认返回 { action, observation }；action.success 只表示动作成功，业务效果需结合 observation 和目标状态判断。',
     'observe=false 且未开启 diagnostics 时返回裸动作结果（如 { clicked: true }），没有 action/observation；开启 diagnostics 时返回 { action, diagnostics }。',
-    '包装结果中的 action.stage=precondition 表示未派发，省略 observation/diagnostics；dispatch-uncertain 表示可能已派发，先查看 action.attempt 与可用观察或最小快照核验，避免重复提交。失败以退出码 1 结束。',
+    '包装结果中的 action.stage=precondition 表示未派发，省略 observation/diagnostics；dispatch-uncertain 表示可能已派发，先查看 action.attempt 与可用观察或最小快照核验，避免重复提交。CLI 单次调用失败以退出码 1 结束；脚本需检查 action.success。',
     'observation.effects 返回通知、控件和焦点增量，可直接复用 node.ref/selector；changed=true 且 effects 为空不表示失败。',
     'effects.texts 按需返回普通可见文本的 selector/text，不代表可点击控件或业务成功；超限或覆盖不完整时仍提示补快照。',
     'fullSnapshotRecommended/snapshotReasons 提示是否补充快照；openedTabs 返回可继续操作的 tabId 和 ready。navigation 模式的 ready 表示新页面就绪。',
     '显式开启的诊断通道在 diagnostics 中返回动作期间增量，与 observe 独立。',
 ];
 export const COMMANDS = [
+    {
+        name: 'get_capabilities',
+        description: '只读查询当前目标浏览器的动作、设备和已安装 App 能力、限制与 Skill/帮助入口；不打开页面或启用模拟',
+        params: [{ name: 'app', type: 'string', description: '可选，使用目录中的完整 App ID 查询桥方法、可调设置和默认版本详情' }],
+        notes: ['沿用 --browser / --session 路由；不传 app 返回摘要。apps.status=partial 表示目录未完整取得，unsupported 表示目标未提供目录；不能把两者当作未安装。', 'available=false 的 App 当前不可启用；支持某个 action 不代表已有域名权限或真实设备授权。按需读取 usage.skills / usage.documentation，查询不会自动安装或加载 Skill。'],
+        examples: ['get_capabilities', `get_capabilities --payload '{"app":"example/app"}'`],
+    },
     {
         name: 'browser_control',
         description: '把控制会话交给用户；用户在 Mearl 浏览器管理页交还后重新观察页面',
@@ -96,7 +101,7 @@ export const COMMANDS = [
     },
     {
         name: 'get_requests',
-        description: '获取最近的网络请求（mtop 或普通 xhr/fetch）',
+        description: '获取最近的网络请求（协议请求或普通 xhr/fetch）',
         params: [
             {
                 name: 'tabId',
@@ -107,8 +112,8 @@ export const COMMANDS = [
             { name: 'count', type: 'number', description: '返回条数，默认 10' },
             {
                 name: 'source',
-                type: '"mtop" | "requests" | "all"',
-                description: '数据来源，不填时默认 mtop；all 返回全部业务请求',
+                type: '"protocol" | "requests" | "all"',
+                description: '数据来源，不填时默认 all；all 返回全部业务请求',
             },
             { name: 'filter', type: 'string', description: '按 URL 或 API 名称过滤，支持正则' },
             { name: 'since', type: 'number', description: '只返回最近 N 秒内的请求' },
@@ -128,7 +133,7 @@ export const COMMANDS = [
             { name: 'keysOnly', type: 'boolean', description: '只返回数据结构，不返回叶子值' },
         ],
         notes: [
-            '流式请求开始后即进入缓冲区；页面及 App 桥代发的 MTop SSE 都归入 mtop。无法归属当前页面 target 的 Service Worker 请求不在采集范围内。',
+            '流式请求开始后即进入缓冲区；页面及 App 桥代发的 协议 SSE 都归入 protocol。无法归属当前页面 target 的 Service Worker 请求不在采集范围内。',
         ],
         result: [
             'nextCursor 用于同类查询续读，hasMore 表示还有数据，gap 表示缓冲区淘汰造成缺口；checkpoint cursor 可分别用于三类查询的初始边界。',
@@ -137,7 +142,7 @@ export const COMMANDS = [
         ],
         examples: [
             `get_requests --payload '{"tabId":12345,"count":5}'`,
-            `get_requests --payload '{"tabId":12345,"source":"mtop","filter":"cart"}'`,
+            `get_requests --payload '{"tabId":12345,"source":"protocol","filter":"cart"}'`,
         ],
     },
     {
@@ -244,7 +249,7 @@ export const COMMANDS = [
             '大字段可用顶层 @<绝对路径> 文件引用或 --payload-file；文件展开后仍受 Native Messaging 单条消息大小限制。',
         ],
         examples: [
-            `set_mock --payload '{"tabId":12345,"apiName":"mtop.cart.query","mockData":{"ret":["SUCCESS::调用成功"]}}'`,
+            `set_mock --payload '{"tabId":12345,"apiName":"cart.query","mockData":{"ret":["SUCCESS::调用成功"]}}'`,
             `set_mock --payload-file ./mock-data.json`,
         ],
     },
@@ -298,7 +303,7 @@ export const COMMANDS = [
         ],
         notes: [
             '扩展模式规则持久化；CDP 仅支持会话级 modifyHeaders 请求头 set，不支持响应头、initiatorDomains 或其他动作。Provider 是否支持以其能力声明为准。',
-            '扩展模式会检查规则请求 URL 和显式来源域名的访问权限；缺失时仍保存规则，返回 warnings 和 missingOrigins，不自动弹窗。可在请求规则页面授权，或按提示调用 request_domain_permission。复杂 URL 表达式无法完整推断域名时会提示手动检查。',
+            '扩展模式会检查规则请求 URL 和显式来源域名的访问权限；缺失时仍保存规则，返回 warnings 和 missingOrigins，不自动弹窗。可在请求规则页面授权，或按提示调用 request_permission。复杂 URL 表达式无法完整推断域名时会提示手动检查。',
         ],
         examples: [
             `set_rule --payload '{"actionType":"block","filter":"^https://example\\\\.com/ads/.*"}'`,
@@ -363,33 +368,16 @@ export const COMMANDS = [
             `send_request --payload '{"url":"https://api.example.com/upload","method":"POST","bodyFile":{"filePath":"/absolute/path/image.png","contentType":"image/png"}}'`,
         ],
     },
-    {
-        name: 'send_mtop_request',
-        description: '使用目标浏览器 Cookie 发起 mtop 请求，自动处理签名和 token',
-        params: [
-            { name: 'api', type: 'string', required: true, description: 'mtop API 名称' },
-            { name: 'data', type: 'object', description: '请求数据' },
-            { name: 'version', type: 'string', description: 'API 版本，默认 1.0' },
-            { name: 'method', type: 'string', description: 'HTTP 方法，默认 GET' },
-            { name: 'appKey', type: 'string', description: '签名使用的 appKey，默认 12574478' },
-            { name: 'env', type: '"prod" | "pre"', description: '请求环境，默认 prod' },
-            { name: 'timeout', type: 'number', description: '超时毫秒数，默认 10000' },
-        ],
-        notes: [
-            '需要目标浏览器有对应登录态；Mearl 自动处理签名，不依赖页面脚本。api 以 mopen. 开头时使用 mopen 协议。',
-            'env=prod 使用 h5api.m.taobao.com，pre 使用 h5api.wapa.taobao.com。',
-        ],
-        result: ['返回 success、response、requestData；业务成功需检查 response.ret。'],
-        examples: [
-            `send_mtop_request --payload '{"api":"mtop.trade.order.detail","data":{"orderId":"123"}}'`,
-        ],
-    },
     // ── 浏览器 ────────────────────────────────────────────────────────────────
     {
         name: 'browser_list',
         description: '列出所有浏览器及其连接状态、类型和 Provider 托管实例信息',
         summary: '列出本地及远端浏览器与连接状态',
-        examples: ['browser_list'],
+        params: [
+            { name: 'provider', type: 'string', description: '配合 launchForm，仅查询一个本机已安装 Provider 的启动候选；需 --local' },
+            { name: 'launchForm', type: 'object', description: '现有动态启动表单请求：{variant?,values:{}}，不创建或接入实例' },
+        ],
+        examples: ['browser_list', 'browser_list --local'],
     },
     {
         name: 'browser_release',
@@ -496,6 +484,9 @@ export const COMMANDS = [
         name: 'tab_open',
         description: '打开或按 URL 规则复用 Tab，并等待新页面加载完成',
         aliases: ['tab_new', 'new_tab', 'tab_create', 'create_tab'],
+        aliasExamples: {
+            tab_activate: `tab_open --payload '{"url":"https://example.com","reuse":"require","active":true}'`,
+        },
         params: [
             { name: 'url', type: 'string', required: true, description: '要打开的 URL' },
             {
@@ -541,7 +532,7 @@ export const COMMANDS = [
             {
                 name: 'appProfile',
                 type: 'string',
-                description: '按已安装档案应用 App 环境；内置基础档案只提供 UA/版本，完整桥由能力包提供。需要 iframe WebView 和系统栏时同时传 emulation.deviceShell=true',
+                description: '按已安装档案应用 App 环境，ID 与限制见当前动态帮助。需要 iframe WebView 和系统栏时同时传 emulation.deviceShell=true',
             },
             {
                 name: 'os',
@@ -567,9 +558,9 @@ export const COMMANDS = [
             `tab_open --payload '{"url":"https://example.com"}'`,
             `tab_open --payload '{"url":"https://example.com/page","reuse":"prefer","match":{"ignoreSearch":true}}'`,
             `tab_open --payload '{"url":"https://m.example.com","emulation":{"preset":"iphone-17-pro"}}'`,
-            `tab_open --payload '{"url":"https://example.com/app/home","appProfile":"fliggy"}'`,
-            `tab_open --payload '{"url":"https://example.com/app/home","appProfile":"fliggy","emulation":{"preset":"ipad-mini-a17-pro","orientation":"landscape","deviceShell":true,"splitScreen":true}}'`,
-            `tab_open --payload '{"url":"https://example.com","appProfile":"fliggy","os":"android"}'`,
+            `tab_open --payload '{"url":"https://example.com/app/home","appProfile":"reader"}'`,
+            `tab_open --payload '{"url":"https://example.com/app/home","appProfile":"reader","emulation":{"preset":"ipad-mini-a17-pro","orientation":"landscape","deviceShell":true,"splitScreen":true}}'`,
+            `tab_open --payload '{"url":"https://example.com","appProfile":"reader","os":"android"}'`,
             `tab_open --payload '{"url":"https://example.com","group":"验证任务"}'`,
         ],
     },
@@ -613,6 +604,9 @@ export const COMMANDS = [
     {
         name: 'page_click',
         description: '点击页面元素，支持 CSS/@ref、可见文本或视口坐标定位',
+        aliasExamples: {
+            page_select: `page_click --payload '{"tabId":12345,"text":"选项文案","role":"option"}'`,
+        },
         params: [
             {
                 name: 'selector',
@@ -666,7 +660,8 @@ export const COMMANDS = [
         result: PAGE_ACTION_RESULT,
         notes: [
             'selector / text / point 必须且只能提供一个。隐藏页 auto 使用 DOM；只有明确依赖真实用户手势时才激活页面。',
-            '原生 select 可按 option 文本点击；checkbox/radio 返回 controlState.checkedBefore/checkedAfter。',
+            'auto 对原生 option、checkbox/radio 使用状态感知的 DOM 路径；显式 mouse/touch 保留可信输入。',
+            '原生 select 可按 option 文本点击；auto/dom 返回 selectionState.valueBefore/valueAfter/selectedAfter，检查选中状态是否保持。checkbox/radio 返回 controlState.checkedBefore/checkedAfter。',
         ],
         examples: [
             `page_click --payload '{"tabId":12345,"text":"提交"}'`,
@@ -721,6 +716,9 @@ export const COMMANDS = [
     {
         name: 'page_type',
         description: '向输入框填写文本，兼容 React 受控组件',
+        aliasExamples: {
+            page_fill: `page_type --payload '{"tabId":12345,"selector":"@e6","text":"填写内容","clearFirst":true}'`,
+        },
         params: [
             {
                 name: 'selector',
@@ -906,6 +904,8 @@ export const COMMANDS = [
                 description: '按键名称：Enter/Tab/Escape/Backspace 等',
             },
             { name: 'modifiers', type: 'string[]', description: '修饰键数组：ctrl/alt/shift/meta/cmd' },
+            { name: 'dialogId', type: 'string', description: '原生弹窗回执或 page_snapshot 中的 dialog.id；仅配合 Enter 接受或 Escape 取消' },
+            { name: 'promptText', type: 'string', description: '仅用于 dialogId + Enter 接受原生 prompt 时填写文本' },
             {
                 name: 'pressMode',
                 type: '"auto" | "dom" | "keyboard"',
@@ -917,6 +917,7 @@ export const COMMANDS = [
         ],
         notes: [
             '隐藏页 DOM 模式支持 Tab 焦点移动、原生控件 Enter/Space 激活和输入框 Enter 提交；编辑、选择、方向键和页面滚动等原生行为需可见页与 pressMode=keyboard。',
+            '原生 alert/confirm/prompt/beforeunload 弹窗需显式传 dialogId；普通 Enter 不处理弹窗。弹窗处理绕过 DOM 观察，不自动重放被中断的动作；处理后重新读取页面。',
         ],
         result: [
             ...PAGE_ACTION_RESULT,
@@ -956,6 +957,7 @@ export const COMMANDS = [
         ],
         notes: [
             'time / selector / text / condition 必须且只能提供一个；time 范围 0–60000ms。页面交互已有内置观察，仅在需要独立等待条件时使用。',
+            '等待后须立即执行已知动作时，用 mearl run 在同一脚本中 await pageWait 后紧接 pageClick，避免模型往返。整体 --timeout 须覆盖等待及后续动作；等待失败不继续点击。',
         ],
         examples: [
             `page_wait --payload '{"tabId":12345,"time":1000}'`,
@@ -968,6 +970,9 @@ export const COMMANDS = [
     {
         name: 'page_navigate',
         description: '在当前标签页内导航到 URL、刷新页面，或沿浏览历史后退/前进',
+        aliasExamples: {
+            page_reload: `page_navigate --payload '{"tabId":12345,"refresh":true}'`,
+        },
         params: [
             {
                 name: 'url',
@@ -1167,14 +1172,14 @@ export const COMMANDS = [
     },
     {
         name: 'set_app_profile',
-        description: '设置已安装的 App 档案；完整 JSBridge 由能力包提供。可同时设置 MTop 页面接口环境，传 emulation 时联动设备模拟',
+        description: '设置已安装的 App 档案；完整 JSBridge 由能力包提供。可同时设置已安装的网络控件，传 emulation 时联动设备模拟',
         summary: '设置或清除目标标签页的 App 容器模拟',
         params: [
             { name: 'enabled', type: 'boolean', required: true, description: 'true=启用，false=清除' },
             {
                 name: 'profile',
                 type: 'string',
-                description: `容器档案名（enabled=true 时必填）；内置 ${APP_PROFILE_NAME_LIST}`,
+                description: '已安装的容器档案 ID（enabled=true 时必填）；当前动态帮助直接展示目标浏览器目录',
             },
             { name: 'os', type: '"ios" | "android"', description: '容器系统，默认 ios' },
             {
@@ -1199,9 +1204,9 @@ export const COMMANDS = [
                 description: '声明式覆盖桥方法，形如 {methods:{api:{behavior|response|noop,silent?}}}；不执行配置脚本',
             },
             {
-                name: 'mtopEnv',
-                type: '"default" | "prod" | "pre"',
-                description: '可选 MTop 页面接口环境；default 关闭环境改写，省略时保持当前设置。仅作用于目标 tab',
+                name: 'networkControl',
+                type: 'object | null',
+                description: '可选已安装网络控件 {id,value}；null 清除，省略时保持当前设置。仅作用于目标 tab',
             },
             {
                 name: 'emulation',
@@ -1217,15 +1222,15 @@ export const COMMANDS = [
             'bridgeConfig.methods 按方法声明 behavior / response / noop 三选一，可传 silent；只支持受控行为、固定 JSON 回包或成功空实现，不执行配置脚本。',
         ],
         result: [
-            '返回 enabled、profile、label、userAgent、os、mtopEnv、reloaded；联动设备时额外返回实际 emulation。',
+            '返回 enabled、profile、label、userAgent、os、networkControl、reloaded；联动设备时额外返回实际 emulation。',
         ],
         examples: [
-            `set_app_profile --payload '{"tabId":12345,"enabled":true,"profile":"fliggy"}'`,
-            `set_app_profile --payload '{"tabId":12345,"enabled":true,"profile":"fliggy","mtopEnv":"pre"}'`,
-            `set_app_profile --payload '{"tabId":12345,"enabled":false,"mtopEnv":"prod"}'`,
-            `set_app_profile --payload '{"tabId":12345,"enabled":true,"profile":"fliggy","emulation":{}}'`,
-            `set_app_profile --payload '{"tabId":12345,"enabled":true,"profile":"alipay","emulation":{"preset":"pixel-11","deviceShell":true}}'`,
-            `set_app_profile --payload '{"tabId":12345,"enabled":true,"profile":"fliggy","emulation":{"preset":"ipad-mini-a17-pro","orientation":"landscape","deviceShell":true,"splitScreen":true}}'`,
+            `set_app_profile --payload '{"tabId":12345,"enabled":true,"profile":"reader"}'`,
+            `set_app_profile --payload '{"tabId":12345,"enabled":true,"profile":"reader","networkControl":{"id":"environment","value":"pre"}}'`,
+            `set_app_profile --payload '{"tabId":12345,"enabled":false,"networkControl":null}'`,
+            `set_app_profile --payload '{"tabId":12345,"enabled":true,"profile":"reader","emulation":{}}'`,
+            `set_app_profile --payload '{"tabId":12345,"enabled":true,"profile":"wallet","emulation":{"preset":"pixel-11","deviceShell":true}}'`,
+            `set_app_profile --payload '{"tabId":12345,"enabled":true,"profile":"reader","emulation":{"preset":"ipad-mini-a17-pro","orientation":"landscape","deviceShell":true,"splitScreen":true}}'`,
             `set_app_profile --payload '{"tabId":12345,"enabled":false}'`,
             `set_app_profile --payload '{"tabId":12345,"enabled":false,"emulation":{}}'`,
         ],
@@ -1280,9 +1285,9 @@ export const COMMANDS = [
         result: ['找到时 found=true 并返回 value/domain/path；不存在时 found=false。'],
         examples: [
             `get_cookie --payload '{"tabId":12345,"name":"feature_flag"}'`,
-            `get_cookie --payload '{"url":"https://www.taobao.com/","name":"tracknick"}'`,
+            `get_cookie --payload '{"url":"https://www.shop.com/","name":"account_name"}'`,
             `get_cookie --payload '{"tabId":12345,"name":"feature_channel","domain":"example.com"}'`,
-            `get_cookie --payload '{"tabId":12345,"name":"tracknick","url":"https://www.taobao.com/","domain":"example.com","path":"/"}'`,
+            `get_cookie --payload '{"tabId":12345,"name":"account_name","url":"https://www.shop.com/","domain":"example.com","path":"/"}'`,
         ],
     },
     {
@@ -1327,7 +1332,7 @@ export const COMMANDS = [
         result: ['返回 url/name/domain/path/reloaded，指定标签页时包含 tabId；不回显 Cookie 值。'],
         examples: [
             `set_cookie --payload '{"tabId":12345,"name":"feature_flag","value":"enabled"}'`,
-            `set_cookie --payload '{"url":"https://www.taobao.com/","name":"feature_flag","value":"enabled"}'`,
+            `set_cookie --payload '{"url":"https://www.shop.com/","name":"feature_flag","value":"enabled"}'`,
             `set_cookie --payload '{"tabId":12345,"name":"feature_channel","value":"3.6.63","domain":"example.com","reload":true}'`,
         ],
     },
@@ -1342,7 +1347,7 @@ export const COMMANDS = [
         examples: [`page_frames --payload '{"tabId":12345}'`],
     },
     {
-        name: 'request_domain_permission',
+        name: 'request_permission',
         description: '申请访问指定域名的权限（必要时弹窗让用户授权）',
         params: [
             {
@@ -1357,7 +1362,7 @@ export const COMMANDS = [
             '弹窗等待用户选择，90 秒超时或关闭按拒绝处理；granted=true 后才重试原请求。',
         ],
         result: ['返回 granted、domain，授权成功时包含 origin。'],
-        examples: [`request_domain_permission --payload '{"domain":"example.com"}'`],
+        examples: [`request_permission --payload '{"domain":"example.com"}'`],
     },
     // ── 组合调用 ────────────────────────────────────────────────────────────────
     {

package/dist/guide.d.ts

@@ -0,0 +1,46 @@
+/** One catalog drives CLI navigation and the build-time resource copy. */
+export declare const GUIDE_TOPICS: readonly [{
+    readonly id: "core";
+    readonly file: "core.md";
+    readonly title: "核心工作流与按需导航";
+}, {
+    readonly id: "automation";
+    readonly file: "api-page-automation.md";
+    readonly title: "控件、文件、弹窗与结果判读";
+}, {
+    readonly id: "run";
+    readonly file: "scripting.md";
+    readonly title: "SDK、代码组合、超时与不确定结果";
+}, {
+    readonly id: "debugging";
+    readonly file: "api-page-debugging.md";
+    readonly title: "布局、遮挡、iframe 与视觉验证";
+}, {
+    readonly id: "environment";
+    readonly file: "api-page-environment.md";
+    readonly title: "设备、App、时区与 Cookie";
+}, {
+    readonly id: "diagnostics";
+    readonly file: "api-request-debugging.md";
+    readonly title: "接口、日志、埋点、权限与 Mock";
+}, {
+    readonly id: "browsers";
+    readonly file: "api-browser-setup.md";
+    readonly title: "目标、会话、远端与 Provider";
+}, {
+    readonly id: "cooperation";
+    readonly file: "browser-tool-cooperation.md";
+    readonly title: "与其他浏览器工具协作";
+}, {
+    readonly id: "skills";
+    readonly file: "related-skills.md";
+    readonly title: "专用 Skill 使用与安装";
+}, {
+    readonly id: "troubleshooting";
+    readonly file: "troubleshooting.md";
+    readonly title: "安装、连接与环境排查";
+}];
+export declare function renderGuideLinks(source: string, commandName?: string): string;
+/** Only packaged files are read; unknown IDs never become filesystem paths. */
+export declare function readGuide(id: string, commandName?: string, version?: string): Promise<string>;
+export declare function runGuideCli(args: string[], commandName?: string, version?: string): Promise<number>;

package/dist/guide.js

@@ -0,0 +1,80 @@
+import { readFileSync } from 'node:fs';
+import { CLIENT_VERSION } from './runtimePaths.js';
+/** One catalog drives CLI navigation and the build-time resource copy. */
+export const GUIDE_TOPICS = [
+    { id: 'core', file: 'core.md', title: '核心工作流与按需导航' },
+    { id: 'automation', file: 'api-page-automation.md', title: '控件、文件、弹窗与结果判读' },
+    { id: 'run', file: 'scripting.md', title: 'SDK、代码组合、超时与不确定结果' },
+    { id: 'debugging', file: 'api-page-debugging.md', title: '布局、遮挡、iframe 与视觉验证' },
+    { id: 'environment', file: 'api-page-environment.md', title: '设备、App、时区与 Cookie' },
+    { id: 'diagnostics', file: 'api-request-debugging.md', title: '接口、日志、埋点、权限与 Mock' },
+    { id: 'browsers', file: 'api-browser-setup.md', title: '目标、会话、远端与 Provider' },
+    { id: 'cooperation', file: 'browser-tool-cooperation.md', title: '与其他浏览器工具协作' },
+    { id: 'skills', file: 'related-skills.md', title: '专用 Skill 使用与安装' },
+    { id: 'troubleshooting', file: 'troubleshooting.md', title: '安装、连接与环境排查' },
+];
+export function renderGuideLinks(source, commandName = 'mearl') {
+    return source.replace(/\[([^\]\n]+)\]\(([^)\s]+)\)/g, (original, label, href) => {
+        if (/^[a-z][a-z0-9+.-]*:/i.test(href) || href.startsWith('#'))
+            return original;
+        const [file, section] = href.replace(/^\.\//, '').split('#');
+        const topic = GUIDE_TOPICS.find(topic => topic.file === file);
+        if (!topic)
+            throw new Error(`指南包含未打包的本地链接：${href}`);
+        return `${label}（\`${commandName} guide ${topic.id}\`${section ? `，小节 \`${section}\`` : ''}）`;
+    });
+}
+/** Only packaged files are read; unknown IDs never become filesystem paths. */
+export async function readGuide(id, commandName = 'mearl', version = CLIENT_VERSION) {
+    const topic = GUIDE_TOPICS.find(topic => topic.id === id);
+    if (!topic)
+        throw new Error(`未知指南主题：${id}。用 ${commandName} guide --list 查看主题。`);
+    let source;
+    try {
+        source = readFileSync(new URL(`./guides/${topic.file}`, import.meta.url), 'utf8');
+    }
+    catch (error) {
+        throw new Error(`当前安装缺少指南资源：${topic.id}。请通过当前发行版的安装入口修复安装包；参数可用 ${commandName} <action> --help 查询。`, { cause: error });
+    }
+    let management;
+    if (source.includes('{{setup}}')) {
+        const { readInstallationManagement, setupManagementCommand } = await import('@mearl/daemon-core/installation');
+        const installed = await readInstallationManagement();
+        const command = setupManagementCommand(installed.setup ?? { package: '@mearl/setup', version: 'beta' });
+        source = source.replaceAll('{{setup}}', command);
+        management = installed.source ? `管理入口：${command}；沿用本机已选 preset。` : `首次安装入口：${command}；本机尚未选择 preset，组织发行环境使用其首次安装指引。`;
+    }
+    return [
+        `[mearl:guide] CLI ${version} · ${topic.id}`,
+        '本指南随 CLI 分发；扩展、远端宿主与已安装能力仍须按目标实际帮助核验。',
+        ...(management ? [management] : []),
+        '',
+        renderGuideLinks(source.trim(), commandName),
+        '',
+        `其他主题：${commandName} guide --list；具体参数：${commandName} <action> --help。`,
+        `[mearl:guide] end ${topic.id}`,
+    ].join('\n');
+}
+export async function runGuideCli(args, commandName = 'mearl', version = CLIENT_VERSION) {
+    const list = () => GUIDE_TOPICS.map(topic => `  ${topic.id.padEnd(18)}${topic.title}`).join('\n');
+    if (args.length === 1 && (args[0] === '--help' || args[0] === '-h')) {
+        console.log(`${commandName} guide — CLI ${version}\n\n用法：${commandName} guide [topic]\n      ${commandName} guide --list\n\n默认只读 core；按需读取单个专题。只读本地资源，不连接浏览器或检查更新。\n\n${list()}`);
+        return 0;
+    }
+    if (args.length === 1 && args[0] === '--list') {
+        console.log(`${commandName} guide — CLI ${version}\n${list()}`);
+        return 0;
+    }
+    if (args.length > 1 || args[0]?.startsWith('-') || !GUIDE_TOPICS.some(topic => topic.id === (args[0] ?? 'core'))) {
+        console.error(`未知指南主题或选项：${args.join(' ')}。用 ${commandName} guide --list 查看主题。`);
+        return 2;
+    }
+    try {
+        console.log(await readGuide(args[0] ?? 'core', commandName, version));
+        return 0;
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        return 1;
+    }
+}

package/dist/guides/api-browser-setup.md

@@ -0,0 +1,93 @@
+# Mearl API 场景：浏览器初始化与管理
+
+需要管理控制会话、选择远端 connector、在同一 connector 下选择浏览器，或列出、启动、关闭、释放普通及 Provider 托管浏览器实例时读取本文件。设备、时区和 Cookie 操作见 [页面测试环境准备](./api-page-environment.md)。
+
+## 目录
+
+- [浏览器实例](#browser-instances)
+- [控制会话与人工交接](#control-sessions)
+- [目标宿主与高级路由参数](#cloud-connectors)
+- [可选浏览器 Provider](#browser-providers)
+
+<a id="browser-instances"></a>
+
+## 浏览器实例
+
+`browser_list` 返回普通浏览器和 Provider 托管浏览器。顶层包含 `count`、`connectedCount`、`defaultBrowserId`、`browsers`，部分来源发现失败时还会返回 `warnings`。公共字段包括 `browserId`、`name`、`type` 和 `status`：
+
+- `type` 为 `regular` 或 `managed`。
+- `status` 为 `connected`、`pairing`、`running_disconnected` 或 `stopped`；只有 `connected` 可作为页面操作目标。
+- Provider 实例还会返回 `provider`、`ownership`、`persistence`、`operations`、`references`、`details` 和可选的 `pairing`。用 `operations` 判断当前可执行的生命周期操作。
+
+`browser_launch` 默认启动本地独立 Chrome。外部 Provider 使用以下通用结构，具体 `providerOptions` 必须通过 `mearl <providerId>` 查询：
+
+```bash
+mearl browser_launch --payload '{"provider":"<providerId>","providerOptions":{}}'
+```
+
+本机与远端 connector 同时存在时，用 `--local`、`--connector <id|name>`，或用 `--browser <global-id>` 同时指定宿主和 Cookie/UA 的来源浏览器。启动响应中的全局 `browserId` 用于首次操作和交付；建立控制会话后，后续操作由 `--session` 固定目标，无会话时继续传选定的 `--browser`。
+
+`browser_close` 关闭托管实例；`deleteProfile: true` 表示同时删除 Provider 持久化数据。是否支持关闭、删除、启动、同步 Cookie、detach 或访问入口，以实例的 `operations` 和 Provider 命令帮助为准。
+
+不带 `--session` 的 `browser_release` 通过 `--browser <id|名称>` 选择普通浏览器，只在用户明确要求结束调试、退出接管或清理环境时调用。它会释放 debugger/CDP 控制，清理依赖当前调试连接的 Mock、设备/时区模拟与持续采集，保留浏览器和标签页；存在活动控制会话时拒绝浏览器级释放。用户要求的终态依赖这些效果时保持控制。会话任务的收尾见[控制会话](#control-sessions)；Provider 的 detach 或其他收尾遵循 `mearl <providerId>`。
+
+浏览器访问入口不会出现在 `browser_list` 中。只有用户明确需要时才运行 `mearl check --browser <id|名称>`，并把返回的 `browserAccess.url` 按敏感信息处理，不写入日志或转发给无关方。
+
+<a id="control-sessions"></a>
+
+## 控制会话与人工交接
+
+扩展免打扰默认开启；`tab_open active:true` 为 HTTP(S) 页面启用后台焦点模拟，新页在首次导航前生效，不切换标签页或窗口。关闭免打扰后，`active:true` 才会真实激活并恢复最小化窗口。普通页面操作不会自动启用模拟。`activation.mode` 区分 `background` / `foreground`；模拟后的 `document.visibilityState` 可为 `visible`，不能据此判断窗口在前台。交给用户、释放控制或扩展连接断开时恢复，`preserveEnvironment` 不保留此临时状态；交还后按需用 `reuse:"require", active:true` 再次激活。未带会话时通过 `browser_release` 清理。纯 CDP 和外部 Provider 沿用各自激活能力。
+
+首次 `tab_open` / `page_snapshot` / `page_screenshot` 传 `--session new`，后续命令传 `--session <sessionId>`，使用响应的完整 `session.sessionId`。会话绑定浏览器与传输，页面操作同时指定 `tabId`；仅支持视觉感知的 Provider 可从截图建立会话。
+
+扩展新建的后台页面默认进入折叠的 `Mearl` 标签组，前台新页进入展开的 `Mearl · 待操作` 组；两个管理组复用同一个已有窗口，页面打开的后续标签继承源组状态。复用用户的普通页面保留原窗口和分组，`tab_open.group` 可指定其他分组。接管时会话内的管理页移入待操作组，交还后收回 `Mearl` 组；用户正在查看组内其他页面或窗口没有其他页面时保留展开状态。纯 CDP 和外部 Provider 沿用各自的页面组织方式。
+
+常规响应的 session 只包含 ID、浏览器、传输、状态、代次和可选 reason，不重复标签页清单。页面列表用 tab_list 查询；browser_control 的交接结果还包含会话页面的 tabs。CLI、SDK、MCP 使用同一结构。
+
+会话自动记录新建与复用页面，串行执行同页面操作，并阻止其他会话或无会话调用占用其页面。不同任务使用独立会话；会话不隔离 Cookie 与存储，账号或浏览器共享资源冲突时使用独立浏览器。Extension、CDP 和采用 Mearl 控制的 Provider 共用这些规则；声明外部控制的 Provider（如 Ego）拒绝 Mearl 会话，交接和收尾沿用原工具。
+
+`browser_control` 的 `operation:"handoff"` 将控制权交给用户，`tabId` 指定会话页面，`reason` 说明需要用户处理的事项。用户在 Mearl Popup 浏览器管理页接管和交还；无扩展 UI 的环境，在用户明确确认交还后调用 `operation:"resume"`。
+
+- `CONTROL_SESSION_PAUSED`：停止派发动作，交还后重新快照或截图，根据当前状态继续，不重放未完成批次；已派发的操作可能仍然生效。
+- `CONTROL_SESSION_NOT_FOUND`：会话不存在或已失效，在原浏览器以普通调用执行 `tab_list`，获取当前 `tabId` 并检查操作结果，再按任务需要建立新会话，避免重复写操作。
+
+任务结束调用 `browser_release --session <sessionId>`，释放该会话的控制归属并清理临时文件，默认保留页面、Mock 与模拟环境。payload 支持以下保留与清理选项：
+
+| 参数 | 行为 |
+| --- | --- |
+| `closeCreatedTabs:true` | 关闭确认不再需要的会话新建页；复用的用户页面始终保留 |
+| `keepTabIds` | 配合关闭新建页时保留结果页面 |
+| `preserveEnvironment:false` | 清理会话页面的 Mock 与模拟环境 |
+| `keepArtifactIds` | 保留指定浏览器文件产物，其他会话临时文件清理 |
+
+会话释放保留 Provider 实例；关闭、退出接管和同步 Cookie 使用原有实例操作，存在活动控制会话时先释放所属会话。
+
+<a id="cloud-connectors"></a>
+
+## 目标宿主与高级路由参数
+
+默认不传宿主、连接或传输覆盖参数。`browser_list` 会同时查询当前机器和全部远端 connector，结果名称带机器前缀，`source` 包含远端机器的 `connectorId` 和 `connectorName`，全局 `browserId` 可跨 CLI 调用并自动选择本地或远端传输。需要指定目标时优先传这个全局 ID；完整实例名称跨来源唯一时也可由客户端解析。建立控制会话后，后续 action 只需传 `--session <sessionId>` 和页面参数。不要依赖名称片段的模糊匹配。
+
+| 参数 | 作用 | 使用时机 |
+| --- | --- | --- |
+| `--local` | 只使用当前机器 | 限定本机清单、检查，或让 `browser_launch` 落到本机 |
+| `--connector <id\|name>` | 只使用一台远端 connector | 限定远端清单、检查或启动宿主；名称或 ID 片段必须唯一 |
+| `--cdp` | 本机强制使用 CDP，并隐含 `--local` | 需要验证或绕过 Extension 控制链路时 |
+| `--server <url>` | 覆盖当前调用使用的 cloud-server URL | 自动配置不可用或临时排障时 |
+
+`--local` / `--cdp` 不能与 `--connector` 同时使用。全局远端 `browserId` 已包含 connector，普通页面 action 不重复传 `--connector`。`--server` 的解析顺序见 `mearl check --help`，连接排障见[环境安装与连接排查](./troubleshooting.md#cloud-agent)。高级诊断命令 `mearl connector_list` 只用于查看没有可列出浏览器的 connector，普通浏览器操作无需先调用它。
+
+<a id="browser-providers"></a>
+
+## 可选浏览器 Provider
+
+Provider 的参数、配置和生命周期随独立包演进，Skill 只保留能力与安装入口。安装后必须读取 Provider 自带的当前帮助，不从本文件推断字段。
+
+支持的平台和设备来源以已安装 Provider 的能力声明及配套 Skill 为准。
+
+只询问能力或配置时不创建实例。执行任务前先运行 `mearl browser_list`：已有符合目标且 `status: "connected"` 的实例时直接复用；需要创建、配对、接入或收尾时，遵循对应 Provider 命令帮助。实例返回的全局 `browserId` 用于选择目标，无会话时后续统一页面 action 继续使用该 ID。
+
+用户只要求移动视口、移动 UA、触摸事件或机型样式时使用设备模拟，无需创建外部 Provider 实例。通过 connector 接入远端浏览器属于控制链路，平台实例由对应 Provider 管理。
+
+已有 Ego 任务的接入、只读候选查询及页面目标映射见[与其他浏览器工具协作](./browser-tool-cooperation.md)。该流程仅查询明确选择的本机 Provider，不广播查询全部来源。