@mearl/client 3.0.0-beta.5 → 3.0.0-beta.8

package/README.md

@@ -1,6 +1,10 @@
 # @mearl/client
 
-本仓库仍在迁移完整宿主。此包已可独立构建和测试，setup/native-host/extension 的公开发行接入尚未完成；下列产品命令描述其现有合同，不代表已发布 3.0。
+CLI、TypeScript SDK 与脚本入口共用浏览器路由和插件运行时。运行时连接与安装由 `@mearl/setup` 管理。
+
+首次使用当前版本可运行 `mearl guide`，默认只读取核心工作流。`mearl guide --list` 列出专题；例如 `mearl guide run` 读取 SDK 组合调用，`mearl guide environment` 读取设备与 App 指引。指南只读 npm 包内资源，不连接浏览器、加载插件、安装环境或触发自动更新。动作参数继续使用 `mearl <action> --help`，目标的已安装能力继续按现有目录查询。
+
+指南正文唯一维护在本包的 `guides/`，构建时复制到 `dist/guides/`，`pnpm check:skills` 校验一致性。CLI 输出将本地文档链接转换为下一条指南命令。`skills/mearl/` 只分发精简的 `SKILL.md`，不附带正文副本；仅使用 MCP、无法执行 CLI 时，直接使用当前工具说明与 schema。组织发行版的安装、认证与业务补充仍由其独立 Skill 提供。
 
 统一浏览器 SDK 与 CLI。它会发现当前机器及已配置 cloud-server 下所有 connector 的浏览器，并根据 `browser_list` 返回的全局 `browserId` 自动选择本地 Socket 或云端 WebSocket 链路。
 
@@ -9,9 +13,9 @@
 ## 安装
 
 ```bash
-npm install @mearl/client
+npm install @mearl/client@beta
 # 或
-pnpm add @mearl/client
+pnpm add @mearl/client@beta
 ```
 
 ## SDK 使用
@@ -60,7 +64,7 @@ mearl check
 mearl check --local --json
 
 # 更新本地环境
-npx @mearl/setup update --local
+npx @mearl/setup@beta update --local
 
 # 查看某个 action 的帮助
 mearl <action> --help
@@ -224,8 +228,8 @@ stdout 在管道或重定向时默认输出紧凑 JSON，在交互终端默认
 未指定字段时默认返回正文。
 
 `send_request` 默认携带所选浏览器中匹配完整目标 URL 的普通 Cookie，以及目标 URL 第一方站点对应的 CHIPS Cookie。例如 `https://app.example.com/` 使用 `https://example.com` 分区，不依赖已打开页面。站点按协议和公共后缀列表（含私有后缀）确定；排除其他站点、其他协议、跨站祖先及不透明分区。保留不同路径下的同名 Cookie，不额外拼入父站点的 host-only Cookie。嵌入其他站点的第三方分区、页面签名或完整页面身份仍需使用目标页面中的 `page_eval` 请求。
-响应中的 `Set-Cookie` 会更新原浏览器，后续调用可以使用刷新后的登录态；`withCookies:false` 同时关闭自动携带与响应回写。扩展由 Chrome 处理响应 Cookie；CDP 的 Node 请求在返回前通过原页面的浏览器连接回写，支持 HttpOnly、默认路径、过期时间和删除。CDP 响应存在 `Set-Cookie` 时附带 `cookieSync: { updatedCount, rejectedCount, failedCount }`，不返回 Cookie 值；无法确定分区的 Partitioned 响应 Cookie 计入拒绝数。同步失败不撤销已完成的 HTTP 操作，应检查状态而非直接重发业务请求。MTop 普通请求及流式请求使用相同的响应刷新机制。
-扩展的临时凭据注入仅匹配原始完整请求 URL，重定向由 Chrome 按新 URL 选择 Cookie。CDP 的 Node 请求（含 MTop 流式请求）不自动跟随重定向，避免将原 URL 的 Cookie 或签名传到其他地址。
+响应中的 `Set-Cookie` 会更新原浏览器，后续调用可以使用刷新后的登录态；`withCookies:false` 同时关闭自动携带与响应回写。扩展由 Chrome 处理响应 Cookie；CDP 的 Node 请求在返回前通过原页面的浏览器连接回写，支持 HttpOnly、默认路径、过期时间和删除。CDP 响应存在 `Set-Cookie` 时附带 `cookieSync: { updatedCount, rejectedCount, failedCount }`，不返回 Cookie 值；无法确定分区的 Partitioned 响应 Cookie 计入拒绝数。同步失败不撤销已完成的 HTTP 操作，应检查状态而非直接重发业务请求。Protocol 普通请求及流式请求使用相同的响应刷新机制。
+扩展的临时凭据注入仅匹配原始完整请求 URL，重定向由 Chrome 按新 URL 选择 Cookie。CDP 的 Node 请求（含 Protocol 流式请求）不自动跟随重定向，避免将原 URL 的 Cookie 或签名传到其他地址。
 
 Mearl 默认聚合当前机器和已配置 cloud-server 下的浏览器，并通过 `browser_list` 返回的全局
 `browserId` 自动路由。以下覆盖参数仅在限定宿主或连接、传输排障时使用，因此不出现在默认 help：
@@ -242,7 +246,7 @@ Mearl 默认聚合当前机器和已配置 cloud-server 下的浏览器，并通
 client、native-host、cloud-connector 和扩展的最新发布版本。发布版本查询最长等待约 1.5 秒，
 无法访问发布源时会提示无法确认更新，不影响浏览器可用性检查。`--json` 输出机器可读的检查结果，
 与 `--updates` 同用时包含更新状态。发现更新时会提示适用的命令：client/native-host 使用
-`npx @mearl/setup update`，setup 管理的扩展使用 `npx @mearl/setup extension`。
+`npx @mearl/setup@beta update`，setup 管理的扩展使用 `npx @mearl/setup extension`。
 
 全局安装的 `mearl` CLI 默认在每天首次使用后启动独立后台进程，查询最新发布版本，并比较
 client、native-host、cloud-server 和 MCP server 的已安装版本。发现更新时调用
@@ -267,7 +271,7 @@ client、native-host、cloud-server 和 MCP server 的已安装版本。发现
 安装 skill 并自动注册命令，或直接注册已有入口：
 
 ```bash
-npx @mearl/setup plugin install https://github.com/F-loat/mearl --skill browser-tab-manager --yes
+npx @mearl/setup plugin install https://github.com/mearlhq/mearl --skill browser-tab-manager --yes
 npx @mearl/setup plugin /absolute/path/to/browser-tab-manager
 npx @mearl/setup plugin uninstall tabs
 mearl tabs summary
@@ -309,7 +313,7 @@ const result = await invokePlugin(
 );
 ```
 
-MCP Server 通过固定工具 `plugin_invoke` 接受同样的 `plugin`、`command` 和 `input`，不会把插件子命令动态扩展成 MCP 工具。SDK 与 MCP 不接受任意入口路径；本地受管理目录中的插件未注册时，会通过匹配当前 client 版本的 setup 自动安装并重试一次。目录由安装宿主显式保存，核心没有组织专属名单；其他未注册名称返回 `PLUGIN_NOT_REGISTERED`。
+MCP Server 通过固定工具 `plugin_invoke` 接受 `plugin`、`command` 和 `input`。SDK 与 MCP 使用已注册插件；安装宿主管理的插件目录可触发匹配当前 client 版本的 setup 安装与一次重试，其他未注册名称返回 `PLUGIN_NOT_REGISTERED`。
 
 长命令使用本机持久任务服务。服务按注册目录隔离并自动启动，CLI、SDK、MCP 与工具箱共享任务记录；调用方退出不取消执行。服务重启后将未完成任务标记为 `interrupted`，不自动重放。后台任务固定接受时的源码快照、工作目录与环境；第三方 JS 依赖应预先打包进 Skill，状态文件放在源码目录之外。快照只固定源码和相对资源，不预解析 JS 依赖；缺失依赖和语法错误由执行器加载代码时报告。
 
@@ -435,9 +439,9 @@ Preact、Hooks 和 HTM 运行时。页面从 `window.mearl.ui` 读取 `html`、`
 
 工具箱面向人，CLI 面向 Agent：复用业务操作、保持结果一致即可，不要求共享中间态。表单草稿、选择、预览等纯 UI 状态默认放浏览器内存；确需刷新或重新打开后恢复时再用浏览器存储。sandbox 页不能假定可直接访问 `localStorage`、IndexedDB 或 `chrome.storage`，应使用宿主提供的能力。只有业务记录、关闭页面后继续的任务、安全重试回执或受消息大小限制的资源传输才需要 Node 状态，并说明其生命周期及清理方式。
 
-组织认证及业务请求由已安装的 Skill 插件提供。CLI 使用 `mearl <plugin> <command>`，业务插件通过 `app.invoke(plugin, { command, input })` 复用同一操作；插件名称、认证方式、请求字段和上传约定以对应 Skill 的契约为准。
+Skill 插件可提供自定义请求与数据处理命令。CLI 使用 `mearl <plugin> <command>`，业务插件通过 `app.invoke(plugin, { command, input })` 复用同一操作；插件名称、认证方式、请求字段和上传约定以对应 Skill 的契约为准。
 
-Node 插件在运行 CLI、SDK 或 MCP Server 的宿主上执行，不随浏览器或 connector 转发。插件读取的文件路径属于该执行宿主；需要浏览器执行的操作应使用明确的浏览器目标。核心不内置组织认证插件或平台来源，安装宿主可通过能力目录提供按需安装信息。
+Node 插件在运行 CLI、SDK 或 MCP Server 的宿主上执行，不随浏览器或 connector 转发。插件读取的文件路径属于该执行宿主；需要浏览器执行的操作应使用明确的浏览器目标。安装宿主可通过能力目录提供按需安装信息。
 
 ## 支持的操作
 
@@ -445,7 +449,7 @@ Node 插件在运行 CLI、SDK 或 MCP Server 的宿主上执行，不随浏览
 | ------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
 | API 调试      | `tab_checkpoint` `get_requests` `get_logs` `get_events`                                                                              |
 | Mock & 规则   | `set_mock` `get_mocks` `set_rule` `get_rules`                                                                                        |
-| 网络请求      | `send_request` `send_mtop_request` `request_domain_permission`                                                                       |
+| 网络请求      | `send_request` `request_permission`                                                                       |
 | 标签页        | `tab_open` `tab_list` `tab_close`                                                                                                    |
 | 页面感知      | `page_snapshot` `page_inspect` `page_screenshot` `page_frames`                                                                       |
 | 页面操作      | `page_click` `page_drag` `page_type` `page_hover` `page_scroll` `page_press` `page_wait` `page_navigate` `page_upload` `page_eval`    |
@@ -586,7 +590,7 @@ SDK 使用 `tasks.checkpoint(taskId)` / `tasks.resume(taskId)`。当前仅支持
 
 插件 CLI 调用失败以非零退出码和 stderr JSON `{ "error": { "code", "message" } }` 返回，保留 SDK/MCP 的 code，不输出任意异常附加字段。`PLUGIN_TASK_WAIT_TIMEOUT` 仅停止等待；`PLUGIN_EXECUTION_CANCELLED` / `PLUGIN_EXECUTION_DEADLINE` 表示执行取消或到期；`PLUGIN_PAGE_TARGET_CHANGED` / `PLUGIN_PAGE_INVALIDATED` 要求重新获取页面实例；`PLUGIN_STATE_CONFLICT` 需重新读取 CAS 版本；`PLUGIN_MODEL_CAPABILITY_UNSUPPORTED` 表示声明能力不支持；`PLUGIN_INVOCATION_CYCLE` / `PLUGIN_INVOCATION_DEPTH` 拒绝循环或过深组合。进程树无法确认停止时保留失败记录并拒绝恢复。
 
-开发环境可运行 `pnpm verify:plugin-host:default` 验证 SDK 与 PATH CLI 在原配置、原认证和默认模型下的完整执行；原配置保持不变。工具箱内显式页面 attach 缺少站点授权时会申请权限，由用户确认后继续；后台页面运行时不会自动弹窗申请。
+工具箱内显式页面 attach 缺少站点授权时会申请权限，由用户确认后继续；后台页面运行时不会自动弹窗申请。
 
 模型列表可通过 SDK `PluginModelClient.list()` 或工具箱 `host.model.list` 查询。模型项携带可用时的 `reasoningEfforts` 和 `defaultReasoningEffort`，界面按模型支持范围提供思考级别。宿主合并并发发现请求，已有模型目录立即返回，过期后后台刷新；刷新失败保留可用目录并短暂退避，不创建推理会话。状态批量读取使用 `get-many` 和 `keys`（SDK `getMany`、工具箱 `host.state.getMany`），一次读取同一 revision 的最多 128 个键，含缺失键的 CAS version，结果上限 1 MiB。
 
@@ -597,7 +601,7 @@ SDK 使用 `tasks.checkpoint(taskId)` / `tasks.resume(taskId)`。当前仅支持
 
 ## 受管理插件目录
 
-安装宿主可通过 client/plugin 的 replaceOfficialPluginCatalog(revision, plugins) 保存已选 preset 的插件目录。revision 为确切清单摘要，每项声明 description、skill 和安装器参数 installArgs，可选 setup 分组。目录以原子文件替换保存于当前插件注册目录的 .official-catalog.json；默认不存在任何预装组织项。安装源码与 preset 的信任校验由安装宿主负责，目录本身不触发安装。
+安装宿主可通过 client/plugin 的 replaceOfficialPluginCatalog(revision, plugins) 保存已选 preset 的插件目录。revision 为确切清单摘要，每项声明 description、skill 和安装器参数 installArgs，可选 setup 分组。目录以原子文件替换保存于当前插件注册目录的 .official-catalog.json；目录默认为空。安装源码与 preset 的信任校验由安装宿主负责，目录本身不触发安装。
 
 findOfficialPlugin/listOfficialPluginNames 每次读取当前目录，继续复用同一 setup 入口完成缺失插件安装。readOfficialPluginCatalog 向安装状态页报告损坏；普通插件和浏览器命令忽略损坏的可选目录，不影响已注册能力。OFFICIAL_PLUGINS 兼容导出反映本进程最近读取的目录。
 

package/dist/actionTimeouts.js

@@ -26,9 +26,6 @@ export function resolveActionTimeoutSec(action, data, fallback = 15) {
             : 0;
         return Math.max(fallback, Math.ceil(((data.timeout ?? 30000) + transferTimeoutMs + 5000) / 1000));
     }
-    if (action === 'send_mtop_request') {
-        return Math.max(fallback, Math.ceil(((data.timeout ?? 10000) + 5000) / 1000));
-    }
     if (action === 'page_download')
         return Math.max(fallback, Math.ceil((Number(data.timeout ?? 30000) + 10000) / 1000));
     if (action === 'page_wait') {

package/dist/autoUpdate.js

@@ -4,6 +4,7 @@ import { closeSync, existsSync, mkdirSync, openSync, readFileSync, realpathSync,
 import { homedir } from 'node:os';
 import { delimiter, dirname, join, resolve, win32 } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { npmExecEnvironment } from '@mearl/daemon-core';
 import { isNewerRelease, parseReleaseVersion } from './check.js';
 import { loadCliAutoUpdateIntervalDays } from './unifiedConfig.js';
 const CONFIG_DIR = join(homedir(), '.mearl');
@@ -207,7 +208,7 @@ export function setupUpdateCommand(version, packageRoot, profiles, updateClient)
     if (!parseReleaseVersion(version))
         throw new Error('A valid Mearl release is required');
     const [major, minor] = version.split('.');
-    const env = { ...process.env };
+    const env = npmExecEnvironment();
     delete env.MEARL_AUTO_UPDATE_CLIENT_ROOT;
     delete env.MEARL_AUTO_UPDATE_CLIENT_ONLY;
     delete env.MEARL_AUTO_UPDATE_PROFILES;

package/dist/bin.js

@@ -1,6 +1,13 @@
 #!/usr/bin/env node
-import { runMearlCli } from './cli.js';
-import { CLIENT_VERSION } from './socket.js';
-import { scheduleCliAutoUpdate } from './autoUpdate.js';
-process.exitCode = await runMearlCli(process.argv.slice(2));
-scheduleCliAutoUpdate(CLIENT_VERSION);
+import { CLIENT_VERSION } from './runtimePaths.js';
+const args = process.argv.slice(2);
+if (args[0] === 'guide') {
+    const { runGuideCli } = await import('./guide.js');
+    process.exitCode = runGuideCli(args.slice(1));
+}
+else {
+    const { runMearlCli } = await import('./cli.js');
+    process.exitCode = await runMearlCli(args);
+    const { scheduleCliAutoUpdate } = await import('./autoUpdate.js');
+    scheduleCliAutoUpdate(CLIENT_VERSION);
+}

package/dist/capabilityHelp.d.ts

@@ -0,0 +1,4 @@
+import type { BrowserCapabilityCatalog } from '@mearl/browser-core';
+/** Help reads an existing target with a short budget; it never installs an environment. */
+export declare function readHelpCapabilities(args: string[]): Promise<BrowserCapabilityCatalog | undefined>;
+export declare function formatCapabilityHelp(catalog: BrowserCapabilityCatalog | undefined, detailed?: boolean): string;

package/dist/capabilityHelp.js

@@ -0,0 +1,68 @@
+import { resolveServer } from './unifiedConfig.js';
+import { listLiveBrowsers } from './browserRegistry.js';
+import { UnifiedClient } from './unified.js';
+/** Help reads an existing target with a short budget; it never installs an environment. */
+export async function readHelpCapabilities(args) {
+    const value = (flag) => {
+        const index = args.indexOf(flag);
+        return index < 0 ? args.find(arg => arg.startsWith(`${flag}=`))?.slice(flag.length + 1) : args[index + 1];
+    };
+    const browser = value('--browser');
+    const session = value('--session');
+    const connector = value('--connector');
+    const { serverUrl } = resolveServer(value('--server'));
+    const local = args.includes('--local') || args.includes('--cdp');
+    if (local && connector || session === 'new')
+        return;
+    if (!browser && !connector && (local || !serverUrl) && !session && !listLiveBrowsers().length)
+        return;
+    const client = new UnifiedClient({ connectTimeoutSec: 1, requestTimeoutSec: 1, ...(serverUrl ? { serverUrl } : {}) });
+    let timer;
+    try {
+        const result = await Promise.race([
+            client.invoke('get_capabilities', {}, {
+                ...(browser ? { browser } : {}), ...(session ? { session } : {}),
+                ...(connector ? { connector } : {}), ...(local ? { local: true } : {}),
+                ...(args.includes('--cdp') ? { transport: 'cdp' } : {}),
+            }),
+            new Promise(resolve => { timer = setTimeout(() => resolve(undefined), 1500); }),
+        ]);
+        if (result && Array.isArray(result.actions) && Array.isArray(result.apps?.entries))
+            return result;
+    }
+    catch {
+        // Static help remains usable when the target is offline or does not expose a catalog.
+    }
+    finally {
+        clearTimeout(timer);
+        client.disconnect();
+    }
+}
+export function formatCapabilityHelp(catalog, detailed = false) {
+    if (!catalog)
+        return '当前浏览器能力暂不可读；以下为静态帮助。连接后再次运行 --help 可查看已安装 App。';
+    const lines = [
+        '当前浏览器已安装的 App：',
+    ];
+    if (!catalog.apps.entries.length)
+        lines.push(catalog.apps.status === 'available' ? '  暂无 App 档案；设备模拟可独立使用。' : '  App 目录暂不可读，不代表未安装。');
+    for (const app of catalog.apps.entries) {
+        lines.push(`  ${app.id} — ${app.label}${app.available ? '' : '（暂不可用）'}`);
+        if (!detailed)
+            continue;
+        lines.push(`    能力：${app.features.join(', ')}`);
+        if (app.usage?.skills?.length)
+            lines.push(`    Skill：${app.usage.skills.join(', ')}`);
+        if (app.usage?.description)
+            lines.push(`    ${app.usage.description}`);
+        if (app.usage?.limitations?.length)
+            lines.push(...app.usage.limitations.map(line => `    限制：${line}`));
+        if (app.usage?.documentation?.length)
+            lines.push(...app.usage.documentation.map(doc => `    说明：${doc.title} ${doc.url}`));
+    }
+    if (detailed)
+        lines.push(...catalog.limitations.map(line => `  ${line}`));
+    else
+        lines.push('  App 用法与限制：mearl set_app_profile --help');
+    return lines.join('\n');
+}

package/dist/check.js

@@ -4,7 +4,7 @@ const UPDATE_SOURCES = {
     client: 'https://registry.npmjs.org/@mearl%2Fclient/latest',
     'native-host': 'https://registry.npmjs.org/@mearl%2Fnative-host/latest',
     'cloud-connector': 'https://registry.npmjs.org/@mearl%2Fcloud-connector/latest',
-    extension: 'https://github.com/F-loat/mearl/releases/latest/download/config.json',
+    extension: 'https://github.com/mearlhq/mearl/releases/latest/download/config.json',
 };
 export function parseReleaseVersion(value) {
     if (typeof value !== 'string')

package/dist/cli.js

@@ -1,3 +1,4 @@
+import { readHelpCapabilities, formatCapabilityHelp } from './capabilityHelp.js';
 import { readFileSync, writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { Command, CommanderError } from 'commander';
@@ -10,7 +11,7 @@ import { formatCommandHelp } from './commandHelp.js';
 import { CLIENT_VERSION } from './socket.js';
 import { UnifiedClient } from './unified.js';
 import { findPluginEntry, findPluginRegistration, findOfficialPlugin, listPluginNames, listOfficialPluginNames, loadRegisteredPlugin, PluginError, } from './plugins/sdk/plugin.js';
-import { getCloudServerConfigPath, loadCloudServerConfig } from './unifiedConfig.js';
+import { resolveServer } from './unifiedConfig.js';
 const TOP_LEVEL_COMMAND_NAME_WIDTH = 22;
 const CATEGORIES = [
     {
@@ -20,9 +21,9 @@ const CATEGORIES = [
     { title: 'Mock & 规则', names: ['set_mock', 'get_mocks', 'set_rule', 'get_rules'] },
     {
         title: '网络请求',
-        names: ['send_request', 'send_mtop_request', 'request_domain_permission'],
+        names: ['send_request', 'request_permission'],
     },
-    { title: '标签页', names: ['tab_open', 'tab_list', 'tab_group', 'tab_close', 'get_capabilities'] },
+    { title: '标签页', names: ['tab_open', 'tab_list', 'tab_group', 'tab_close'] },
     {
         title: '页面感知',
         names: ['page_snapshot', 'page_inspect', 'page_screenshot', 'page_frames'],
@@ -60,6 +61,7 @@ const CATEGORIES = [
     },
 ];
 const BUILTIN_COMMANDS = [
+    { name: 'guide', description: '按需读取与当前 CLI 配套的本地指南', examples: ['guide', 'guide environment'] },
     {
         name: 'run',
         description: '执行预注入 mearl SDK 的 Node.js 脚本',
@@ -127,6 +129,7 @@ function printUsage(commandName, version) {
         `  ${commandName} <action> --help`,
         `  ${commandName} check [选项]`,
         `  ${commandName} run [--file <path>] [选项]`,
+        `  ${commandName} guide [topic]`,
         '',
         '常用选项：',
         '  --payload <json>      直接传入 JSON 参数',
@@ -142,6 +145,7 @@ function printUsage(commandName, version) {
         '  -v, --version         查看版本',
         '',
         '内置命令：',
+        `  ${'guide'.padEnd(TOP_LEVEL_COMMAND_NAME_WIDTH)}读取本地核心流程或单个专题；--list 查看主题`,
         `  ${'run'.padEnd(TOP_LEVEL_COMMAND_NAME_WIDTH)}执行 Node.js 脚本，支持浏览器 API 与 Skill 命令`,
         `  ${'check'.padEnd(TOP_LEVEL_COMMAND_NAME_WIDTH)}检查指定浏览器，未指定时检查全部已连接浏览器`,
     ];
@@ -351,17 +355,6 @@ function parsePayload(payloadRaw, payloadFile) {
     }
     return {};
 }
-function resolveServer(explicit) {
-    if (explicit)
-        return { serverUrl: explicit, serverUrlSource: '--server' };
-    if (process.env.MEARL_SERVER_URL) {
-        return { serverUrl: process.env.MEARL_SERVER_URL, serverUrlSource: 'MEARL_SERVER_URL' };
-    }
-    const config = loadCloudServerConfig();
-    return config?.server
-        ? { serverUrl: config.server, serverUrlSource: getCloudServerConfigPath() }
-        : {};
-}
 function normalizeScreenshotOutput(action, payload, explicitOutput) {
     if (action !== 'page_screenshot' || !Object.hasOwn(payload, 'output')) {
         return { payload, ...(explicitOutput ? { outputPath: explicitOutput } : {}) };
@@ -523,7 +516,7 @@ async function runPluginCli(args, commandName) {
             console.log(plugin.version ?? 'unknown');
             return 0;
         }
-        if (parsed.help || (!parsed.pluginArgs?.length && !parsed.hasPayload)) {
+        if (parsed.help || (!plugin.defaultCommand && !parsed.pluginArgs?.length && !parsed.hasPayload && !Object.keys(parsed.pluginInput ?? {}).length)) {
             console.error(plugin.help(`${commandName} ${parsed.action}`, parsed.pluginArgs?.[0]));
             return 0;
         }
@@ -573,6 +566,10 @@ function writeOutput(action, result, outputPath) {
 export async function runMearlCli(args, options = {}) {
     const commandName = options.commandName ?? 'mearl';
     const clientVersion = options.clientVersion ?? CLIENT_VERSION;
+    if (args[0] === 'guide') {
+        const { runGuideCli } = await import('./guide.js');
+        return runGuideCli(args.slice(1), commandName, clientVersion);
+    }
     if (args[0] === 'run') {
         const { runScriptCli } = await import('./scriptCli.js');
         return runScriptCli(args.slice(1), commandName);
@@ -612,8 +609,11 @@ export async function runMearlCli(args, options = {}) {
     }
     if (args.includes('--help') || args.includes('-h')) {
         const command = COMMAND_MAP.get(args[0]);
-        if (command)
+        if (command) {
             console.error(formatCommandHelp(commandName, command));
+            if (command.name === 'set_app_profile' || command.name === 'tab_open')
+                console.error(formatCapabilityHelp(await readHelpCapabilities(args), true));
+        }
         else if (args[0] === 'check')
             printCheckHelp(commandName);
         else if (ADVANCED_BUILTIN_COMMANDS.has(args[0])) {
@@ -621,6 +621,7 @@ export async function runMearlCli(args, options = {}) {
         }
         else if (args[0]?.startsWith('-')) {
             printUsage(commandName, clientVersion);
+            console.error(formatCapabilityHelp(await readHelpCapabilities(args)));
         }
         else {
             printUnknownCommand(commandName, args);

package/dist/commandHelp.js

@@ -39,10 +39,10 @@ export function formatCommandHelp(commandName, command) {
     ];
     const method = [...SDK_METHOD_ACTIONS].find(([, action]) => action === command.name)?.[0];
     if (method)
-        lines.push('SDK：', ...(method === 'browserRelease'
+        lines.push('SDK：', ...(method === 'browserRelease' || method === 'browserList'
             ? [
-                '  await mearl.browserRelease(options?)',
-                '  await mearl.browserRelease(params, options)',
+                `  await mearl.${method}(options?)`,
+                `  await mearl.${method}(params, options)`,
             ]
             : [
                 `  await mearl.${method}(${SDK_OPTIONS_ONLY_METHODS.has(method) ? 'options?' : 'params, options?'})`,

package/dist/commandSuggestions.d.ts

@@ -1,5 +1,7 @@
 export interface SuggestableCommand {
     readonly aliases?: readonly string[];
+    /** Suggestion-only expressions whose canonical invocation needs a specific payload. */
+    readonly aliasExamples?: Readonly<Record<string, string>>;
     readonly description: string;
     readonly examples?: readonly string[];
     readonly name: string;
@@ -7,6 +9,7 @@ export interface SuggestableCommand {
 export interface CommandSuggestion {
     command: SuggestableCommand;
     score: number;
+    example?: string;
 }
 export declare function commandInput(args: readonly string[]): string;
 export declare function findCommandSuggestions(args: readonly string[], commands: readonly SuggestableCommand[], limit?: number): CommandSuggestion[];

package/dist/commandSuggestions.js

@@ -40,9 +40,20 @@ export function findCommandSuggestions(args, commands, limit = 3) {
         return [];
     const ranked = commands
         .map(command => {
-        const keys = [command.name, ...(command.aliases ?? [])].map(normalizeCommand);
-        const score = Math.max(...queries.flatMap(query => keys.map(key => similarity(query, key))));
-        return { command, score };
+        const keys = [command.name, ...(command.aliases ?? [])].map(name => ({ name }));
+        for (const [name, example] of Object.entries(command.aliasExamples ?? {})) {
+            keys.push({ name, example });
+        }
+        let score = -1;
+        let example;
+        for (const key of keys) {
+            const candidate = Math.max(...queries.map(query => similarity(query, normalizeCommand(key.name))));
+            if (candidate > score) {
+                score = candidate;
+                example = key.example;
+            }
+        }
+        return { command, score, ...(example ? { example } : {}) };
     })
         .filter(suggestion => suggestion.score >= MIN_SIMILARITY)
         .sort((left, right) => right.score - left.score || left.command.name.localeCompare(right.command.name));
@@ -52,8 +63,8 @@ export function findCommandSuggestions(args, commands, limit = 3) {
     return ranked.filter(suggestion => bestScore - suggestion.score <= MAX_SCORE_GAP).slice(0, limit);
 }
 export function formatCommandSuggestions(commandName, suggestions) {
-    return suggestions.map(({ command }) => {
-        const invocation = command.examples?.[0] ?? command.name;
+    return suggestions.map(({ command, example }) => {
+        const invocation = example ?? command.examples?.[0] ?? command.name;
         return `  ${commandName} ${invocation}\n    ${command.description}`;
     });
 }