@mearl/client 2.22.0 → 2.22.2

package/README.md

@@ -72,6 +72,77 @@ mearl browser_list
 mearl browser_release
 ```
 
+### Agent 脚本
+
+`mearl run` 从 stdin 或 `--file <path>` 读取 JavaScript，预注入 `mearl` SDK，支持顶层 `await`、条件、循环和数据处理，无需在任务目录安装依赖：
+
+```bash
+mearl run --session new <<'JS'
+const tab = await mearl.tabOpen({ url: 'https://example.com', reuse: 'prefer' });
+console.log({ tabId: tab.tabId, session: mearl.session });
+console.log(await mearl.pageSnapshot({ tabId: tab.tabId, mode: 'viewport' }));
+JS
+
+mearl run --session '<sessionId>' --file /absolute/path/next-step.mjs
+```
+
+方法名与 SDK 一致，例如 `mearl.pageClick(params, options?)`、`mearl.getRequests(params, options?)`、
+`mearl.tabList(options?)`，通用调用使用 `mearl.invoke(action, payload, options?)`。
+参数和返回值沿用普通 action，可查 `mearl <action> --help`；动作失败仍以 `action.success`、
+`stage` 和 `attempt` 表达，由脚本判断后续逻辑。`console.log` 输出必要结果，`console.error` 输出诊断；
+返回数据不会自动打印。`run_actions` 适合无需判断的紧密序列；脚本适合结果可由代码判断的组合流程。
+需要模型理解页面时，输出最小观察并在下一轮继续。
+
+脚本用 `help` 查询现有命令定义，返回文本由调用方按需输出；CLI `--help` 与脚本共用同一份参数、结果说明、约束和示例。
+
+```javascript
+console.log(await mearl.help()); // 方法与已注册插件清单
+console.log(await mearl.help('pageClick')); // 也接受 page_click
+console.log(await mearl.help({ plugin: 'yuque', command: 'read' }));
+
+const result = await mearl.invokePlugin('yuque', { command: 'read', input: { url: '文档链接' } });
+console.log(mearl.structure(result));
+```
+
+`structure(value, options?)` 同步提取已取得结果的结构，叶子值替换为类型；默认深度 5、每对象 50 个字段、
+每数组 1 个样本、总计 2000 个节点，可通过 `maxDepth`、`maxKeys`、`arraySamples`、`maxNodes` 调整。
+输出包含数组总长度与样本，遇到循环引用、访问器或资源限制会标记；样本不保证覆盖所有可选字段或不同数组元素，
+业务含义以命令帮助为准。普通 SDK 同样导出 `structure`，它与请求 `keysOnly` 使用相同的提取逻辑；
+`keysOnly` 也遵循上述默认字段和节点上限，超出部分会标记截断。
+插件帮助在隔离进程中加载注册信息，不执行所查询的业务命令。
+
+已注册 Skill 命令也可直接组合，命令名和输入来自该插件的 `--help`：
+
+```javascript
+const result = await mearl.invokePlugin('yuque', {
+  command: 'read',
+  input: { url: 'https://aliyuque.antfin.com/group/book/doc' },
+});
+console.log(result);
+```
+
+脚本的 `--browser`、`--session`、`--connector`、`--local`、`--cdp` 由浏览器 API 和插件调用继承；
+单次调用的 `options` 可覆盖。`--server` 指定 cloud-server。`--session new` 成功建立会话后，
+后续调用自动使用返回的 ID，`mearl.session` 和 CLI stderr 同时提供会话信息。
+先 await 建立会话的浏览器调用，再执行并发或 Skill 命令。脚本结束断开 SDK 连接，控制会话保留；
+按任务生命周期显式调用 `mearl.browserRelease`。每轮重建 JS 变量，使用已返回的 `sessionId` 和 `tabId` 继续任务。
+
+每次脚本在独立 Node.js 进程运行，继承调用方的工作目录和环境，拥有该宿主的 Node.js 权限；
+它不是安全沙箱。用 `await import('node:fs/promises')` 等动态 import 加载模块；
+`--file` 的内容也作为脚本函数执行，不支持静态 `import` / `export`。本地模块建议使用绝对文件 URL。
+`window` / `document` 仅在 `mearl.pageEval` 的页面表达式中可用。插件 registry、本地文件和身份认证均属于运行 CLI 的宿主。
+
+`--timeout <seconds>` 限制整个脚本，默认 60 秒；单次 API 的 `options.timeoutSec` 限制该调用。
+stdout 与 stderr 合计最多 256 KiB，源码最多 1 MiB。await 所有 SDK 调用；漏写 await、超时、取消或脚本异常以退出码 1 结束，
+输入错误以 2 结束。取消和超时停止脚本及其进程组，并向仍在等待的 Skill 调用传递取消信号；已派发的浏览器或业务操作可能继续生效，
+错误中的 `pendingActions` / `mayHaveLateEffects` 用于判断是否需要核验现场，不能直接重跑整段脚本。
+Skill 命令使用既有隔离执行器，stdout/stderr 计入脚本输出上限；异常诊断也会按大小裁剪。
+执行结果的 `success` 仅表示脚本正常完成，动作结果与业务成功仍需由代码检查。
+
+SDK 宿主可从 `@mearl/client/script` 导入 `executeScript(code, options)`，得到
+`{ success, stdout, stderr, session?, error?, executionStopped, mayHaveLateEffects, pendingActions }`。
+它支持 `signal` 取消和 `executionTimeoutSec`，与 CLI、MCP 共用执行器。
+
 ### 控制会话与文件
 
 多步骤任务首次 `tab_open` 或 `page_snapshot` 使用 `--session new`，响应在原结果旁附带 `session`，后续用其 `sessionId` 自动路由，无需额外创建/查询 action。Session 绑定一个浏览器与传输；页面首次使用自动关联，复用页面与新建页面分别记录。同一页面只允许一个会话控制，旧调用不能绕过占用；Session 不隔离 Cookie 或存储。
@@ -150,6 +221,10 @@ stdout 在管道或重定向时默认输出紧凑 JSON，在交互终端默认
 需要同时读取全文时显式传 `includeBody:true`。省略正文时不返回 `postData` / `responseBody` 字段；
 未指定字段时默认返回正文。
 
+`send_request` 默认携带所选浏览器中匹配完整目标 URL 的未分区 Cookie，保留不同路径下的同名 Cookie；不额外拼入父站点的 host-only Cookie，也不猜测页面的 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 或签名传到其他地址。
+
 Mearl 默认聚合当前机器和已配置 cloud-server 下的浏览器，并通过 `browser_list` 返回的全局
 `browserId` 自动路由。以下覆盖参数仅在限定宿主或连接、传输排障时使用，因此不出现在默认 help：
 
@@ -250,7 +325,7 @@ const result = await invokePlugin(
 
 MCP Server 通过固定工具 `plugin_invoke` 接受同样的 `plugin`、`command` 和 `input`，不会把插件子命令动态扩展成 MCP 工具。SDK 与 MCP 不接受任意入口路径；调用尚未注册的 `buc`、`authx` 或 `tdbank` 时，会通过匹配当前 client 版本的 setup 自动安装并重试一次。其他未注册名称返回 `PLUGIN_NOT_REGISTERED`。
 
-长命令使用本机持久任务服务。服务按注册目录隔离并自动启动，CLI、SDK、MCP 与工具箱共享任务记录；调用方退出不取消执行。服务重启后将未完成任务标记为 `interrupted`，不自动重放。后台任务固定接受时的源码快照、工作目录与环境；静态第三方 JS 依赖需要预先打包进 Skill，状态文件放在源码目录之外。
+长命令使用本机持久任务服务。服务按注册目录隔离并自动启动，CLI、SDK、MCP 与工具箱共享任务记录；调用方退出不取消执行。服务重启后将未完成任务标记为 `interrupted`，不自动重放。后台任务固定接受时的源码快照、工作目录与环境；第三方 JS 依赖应预先打包进 Skill，状态文件放在源码目录之外。快照只固定源码和相对资源，不预解析 JS 依赖；缺失依赖和语法错误由执行器加载代码时报告。
 
 ```ts
 import { PluginTaskClient } from '@mearl/client';
@@ -270,6 +345,8 @@ try {
 
 `wait` 超时或其 signal 中止只结束等待；`cancel(taskId)` 才取消执行。浏览器任务需显式传 `browser`，名称会在接受前解析为固定 ID。`get/list` 返回任务快照与结果引用，`list` 返回有界分页及 `nextCursor`；`events` 返回游标、缺口标记和最新快照，`subscribe` 封装长轮询。`result(taskId)` 分块读取并校验完整业务结果，最大 64 MiB；终态记录和结果保留 7 天。
 
+插件宿主握手与 `tasks.status()` 返回 `version/buildId`，构建标识用于定位运行代码，兼容性由握手中的协议版本决定。协议相同时，即使版本、构建标识不同或旧宿主未提供标识，任务、模型、页面和状态请求仍可继续使用现有服务，不中断活动任务或页面实例。需要切换到新构建时，确认没有活动任务及页面操作后调用 `tasks.stopHost()`，下次业务调用将启动当前构建；重新注册插件不会重启宿主。本地修改客户端或宿主代码后执行根目录 `pnpm build`，同步生成指纹并构建双方产物；仅运行 `tsc --watch` 不会更新构建指纹。
+
 任务能力由 SDK `PluginTaskClient` 与工具箱 `host.task.*` 使用。对外命令由具体插件按业务需要提供，CLI 使用 `mearl <plugin> <command>`，MCP 使用 `plugin_invoke`。任务、模型、状态、页面实例和宿主诊断不单独暴露为全局 CLI/MCP 命令。仅注册工具箱内部命令的插件不会列入 CLI 插件列表；直接运行其名称会提示工具的打开位置。工具页可用 `window.mearl.waitTask(taskId)`、`readTaskResult(taskId)`、`listTasks()`，范围限定为所属插件的工具箱任务。
 
 `tasks.diagnose({ taskId?, plugin?, instanceId?, includeErrorMessages?, includeLocalPaths? })` 读取当前调用范围内的有界诊断报告。默认不包含业务输入、提示词、进度正文、检查点数据、结果正文、完整 URL、环境变量和凭证，也省略错误消息及本地路径；后两项可显式选择包含。报告的 coverage 和历史 gap 表示采集范围及保留历史限制。
@@ -284,7 +361,15 @@ try {
 
 插件可选导出 `toolbox`，注册后会出现在扩展 Popup 的工具箱中。页面资源放在 Skill 目录内，注册时由
 Mearl 将入口 HTML 引用的本地 CSS、JavaScript 和图片内联为不可变页面包，不需要启动 HTTP 服务，
-也不要求普通 HTML/CSS/JS 页面自行构建：
+也不要求普通 HTML/CSS/JS 页面自行构建。
+
+右键工具箱中的工具可单独禁用或启用对应 Skill；禁用状态显示在标题右侧，工具页面和命令仍可使用。禁用将该目录的
+`SKILL.md` 重命名为 `SKILL.md.mearl-disabled`，启用时恢复，作用于共享此目录的所有 Agent；
+软链接安装会作用于源目录。已有会话可能仍保留已载入的 Skill，需要重启 Agent 或新建会话。
+工具箱内更新和重新安装会保留禁用状态；外部安装器的更新不受此状态管理，若出现两份清单，需先处理冲突。
+独立复制安装的同名 Skill 需分别禁用。没有 Skill 清单的普通插件不显示此开关。
+
+工具箱元数据示例：
 
 ```javascript
 export const toolbox = {
@@ -462,7 +547,7 @@ ISC
 
 ### 插件页面实例
 
-`PluginPageClient` 通过本地插件服务管理 attach/get/list/send/detach/events/activation。插件导出独立 `pageRuntime` 声明并用 `app.page()` 调用。扩展与纯 CDP 共用实例、事件、激活和文档运行时；实例绑定 documentId，同插件同文档的所有入口共享初始化，导航后旧实例失效，启用的激活规则负责重建。`frame` 接受 `main`、`business` 或 `page_frames` 返回的 frame ID（扩展为数字，CDP 为字符串）。外部 Provider 仍须明确声明 `page_runtime` 能力。
+`PluginPageClient` 通过本地插件服务管理 attach/get/list/send/detach/events/activation。插件导出独立 `pageRuntime` 声明并用 `app.page()` 调用。宿主用 Node 内置编译器检查 code 的表达式语法，不执行代码；代码必须在网页中求值得到自包含函数，非函数或外部引用错误在页面运行时报告。扩展与纯 CDP 共用实例、事件、激活和文档运行时；实例绑定 documentId，同插件同文档的所有入口共享初始化，导航后旧实例失效，启用的激活规则负责重建。`frame` 接受 `main`、`business` 或 `page_frames` 返回的 frame ID（扩展为数字，CDP 为字符串）。外部 Provider 仍须明确声明 `page_runtime` 能力。
 
 显式手动 `attach` 复用自动激活的实例时，实例转为手动归属，初始化与在途任务继续复用；随后收窄自动激活范围不会清理该实例。
 
@@ -476,7 +561,7 @@ try {
 } finally { pages.disconnect(); }
 ```
 
-后台事件声明 schema 和串行、latest 合并或有限并发策略，处理器用 `app.runtimeCommand()` 注册并通过 `context.page` 访问固定文档。文档绑定任务可用 `app.page('activation')` 只读查询本插件激活规则，不允许设置或关闭规则。页面消息/结果各上限 24 MiB，宿主自动分块并校验；事件负载上限 32 KiB。工具箱使用 `host.page.*`，UI 订阅实例历史与后台执行独立。完整契约见 [插件宿主能力](../native-host/README.md#页面运行时和事件)。
+后台事件声明 schema 和串行、latest 合并或有限并发策略；schema 是格式元数据，事件处理器负责验证负载。处理器用 `app.runtimeCommand()` 注册并通过 `context.page` 访问固定文档。文档绑定任务可用 `app.page('activation')` 只读查询本插件激活规则，不允许设置或关闭规则。页面消息/结果各上限 24 MiB，宿主自动分块并校验；事件负载上限 32 KiB。工具箱使用 `host.page.*`，UI 订阅实例历史与后台执行独立。完整契约见 [插件宿主能力](../native-host/README.md#页面运行时和事件)。
 
 Python 入口同样导出 `pageRuntime` 字典，其中 `code` 仍是运行于网页中的 JavaScript 函数字符串；后台初始化与事件处理器通过 `app.runtimeCommand(...)` 或其装饰器注册。`app.page(operation, payload)`、`context.page.send(message)` 和 `context.page.get()` 都是同步调用，后两者仅在绑定页面实例的处理器中可用。JS 和 Python 的 `context.page.send(message, {timeoutSec: 120})` 可指定单次响应超时（大于 0 且最多 300 秒，Python 使用字典）；`app.page("send", {instanceId, message, timeoutSec})` 和 SDK `pages.send(plugin, instanceId, message, {timeoutSec})` 同样支持。该设置不改变其他请求，任务取消和文档解绑仍立即中断执行，传输失败也会取消对应网页请求。runtime-only 命令不出现在公开命令帮助中，也不能由 CLI 或工具箱直接执行；声明在页面事件中的普通 `app.command` 仍保留公开调用能力。
 
@@ -496,7 +581,7 @@ try {
 } finally { models.disconnect(); }
 ```
 
-`start` 返回持久 taskId；`run` 的 signal 取消模型执行并等待清理。`app.model(request, { onProgress })` / `context.model(request, { onProgress })` 可订阅当前这一次调用的 `model.delta`，并发调用的回调互相隔离；Python 使用 `context.model(request, on_progress=callback)`。增量 `data` 含 `delta/index/partial`，可用时带 `itemId/phase`；按消息隔离、跳过 commentary，序号缺失时回退到最终结果。增量只供临时展示，最终结果来自成功 turn 的完整消息并经过宿主 schema 校验；临时显示必须在失败时撤回，不能直接作为缓存或业务成功依据。模型目录与执行通过 `PluginModelClient` 或插件上下文使用。工具页使用 `host.model.capabilities/list/start` 和 `waitTask`。
+`start` 返回持久 taskId；`run` 的 signal 取消模型执行并等待清理。`app.model(request, { onProgress })` / `context.model(request, { onProgress })` 可订阅当前这一次调用的 `model.delta`，并发调用的回调互相隔离；Python 使用 `context.model(request, on_progress=callback)`。增量 `data` 含 `delta/index/partial`，可用时带 `itemId/phase`；按消息隔离、跳过 commentary，序号缺失时回退到最终结果。增量只供临时展示，最终结果来自成功 turn 的完整消息；outputSchema 透传模型 Provider，宿主解析 JSON，插件负责验证结果结构与业务约束；临时显示必须在失败时撤回，不能直接作为缓存或业务成功依据。模型目录与执行通过 `PluginModelClient` 或插件上下文使用。工具页使用 `host.model.capabilities/list/start` 和 `waitTask`。
 
 插件入口声明状态集合，然后从命令上下文访问：
 
@@ -512,11 +597,11 @@ export default app => app.command('save', async (input, context) => {
 });
 ```
 
-SDK `PluginStateClient.get/getMany/list/transact` 与工具箱 `host.state.*` 共享集合。每次写入需 CAS，冲突后重新读取、合并再重试；`schemaVersion` 升级用显式迁移事务。浏览器会话/实例可声明 `cache` 或 `memory`，页面身份由宿主验证。`memory` 只保存在插件执行宿主进程中，支持同样的 CAS、schema、TTL 与分块值限制；刷新文档时保留浏览器会话范围，浏览器会话变化后隔离，执行宿主重启时清空。内存状态全宿主合计最多 128 MiB / 512 个集合命名空间，按需占用；单集合 `maxBytes` 最大 128 MiB，实例结束释放其内存。容量、TTL 和完整契约见[插件宿主能力](../native-host/README.md#状态和激活)。二进制资产继续使用文件或资源通道。
+SDK `PluginStateClient.get/getMany/list/transact` 与工具箱 `host.state.*` 共享集合。schema 保留为格式描述和版本身份，写入与迁移的数据由插件自行验证；宿主检查 JSON、大小、版本和事务约束。每次写入需 CAS，冲突后重新读取、合并再重试；`schemaVersion` 升级用显式迁移事务。浏览器会话/实例可声明 `cache` 或 `memory`，页面身份由宿主验证。`memory` 只保存在插件执行宿主进程中，支持同样的 CAS、格式版本、TTL 与分块值限制；刷新文档时保留浏览器会话范围，浏览器会话变化后隔离，执行宿主重启时清空。内存状态全宿主合计最多 128 MiB / 512 个集合命名空间，按需占用；单集合 `maxBytes` 最大 128 MiB，实例结束释放其内存。容量、TTL 和完整契约见[插件宿主能力](../native-host/README.md#状态和激活)。二进制资产继续使用文件或资源通道。
 
 ### 显式任务恢复
 
-插件声明 `taskRecovery`（每个命令的 checkpointVersion/schema）并注册 `app.recoveryCommand(command, handler)`，命令通过 `context.checkpoint(data, expectedSequence)` 保存最多 64 KiB 的恢复依据。检查点数据、版本、宿主 schemaHash、序号和事件与任务记录原子写入；写入必须 CAS。
+插件声明 `taskRecovery`（每个命令的 checkpointVersion/schema）并注册 `app.recoveryCommand(command, handler)`，命令通过 `context.checkpoint(data, expectedSequence)` 保存最多 64 KiB 的恢复依据。检查点数据、版本、宿主 schemaHash、序号和事件与任务记录原子写入；写入必须 CAS。schema 用于声明身份和格式兼容比较，检查点及迁移数据的结构由插件验证。
 
 `tasks.checkpoint(taskId)` 读取检查点；`tasks.resume(taskId, { environment?, revision? })` 为终态根命令建立新 attempt，保持旧任务终态，固定原安装、源码快照、输入、目录和路由。默认提交调用进程的新环境，旧环境不持久化。恢复入口读取 `context.recovery`，先核对外部操作状态；宿主不重放原 handler，也不保证外部提交与检查点原子。
 

package/dist/cli.js

@@ -6,6 +6,7 @@ import { resolveActionTimeoutSec } from './actionTimeouts.js';
 import { runUnifiedCheck, parseCheckTimeout } from './check.js';
 import { commandInput, findCommandSuggestions, formatCommandSuggestions, } from './commandSuggestions.js';
 import { COMMANDS, COMMAND_MAP } from './commands.js';
+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';
@@ -59,6 +60,11 @@ const CATEGORIES = [
     },
 ];
 const BUILTIN_COMMANDS = [
+    {
+        name: 'run',
+        description: '执行预注入 mearl SDK 的 Node.js 脚本',
+        examples: ['run --file task.mjs'],
+    },
     {
         name: 'check',
         description: '检查指定浏览器，未指定时检查全部已连接浏览器',
@@ -120,6 +126,7 @@ function printUsage(commandName, version) {
         `  ${commandName} <action> [选项]`,
         `  ${commandName} <action> --help`,
         `  ${commandName} check [选项]`,
+        `  ${commandName} run [--file <path>] [选项]`,
         '',
         '常用选项：',
         '  --payload <json>      直接传入 JSON 参数',
@@ -135,6 +142,7 @@ function printUsage(commandName, version) {
         '  -v, --version         查看版本',
         '',
         '内置命令：',
+        `  ${'run'.padEnd(TOP_LEVEL_COMMAND_NAME_WIDTH)}执行 Node.js 脚本，支持浏览器 API 与 Skill 命令`,
         `  ${'check'.padEnd(TOP_LEVEL_COMMAND_NAME_WIDTH)}检查指定浏览器，未指定时检查全部已连接浏览器`,
     ];
     for (const category of CATEGORIES) {
@@ -300,46 +308,6 @@ function printAdvancedCommandHelp(commandName, action) {
         '结果包含 count 与 connectors；每项包含 ID、名称、可选版本、连接时间和最后心跳。',
     ].join('\n'));
 }
-function printCommandHelp(commandName, command) {
-    const payloadUsage = command.params?.length ? ' [--payload <json> | --payload-file <path>]' : '';
-    const lines = [
-        `${command.name}`,
-        `  ${command.description}`,
-        '',
-        '用法：',
-        `  ${commandName} ${command.name}${payloadUsage} [常用选项]`,
-        '',
-    ];
-    if (command.params?.length) {
-        lines.push('参数（--payload JSON 字段）：');
-        for (const parameter of command.params) {
-            const required = parameter.required ? '必填' : '可选';
-            lines.push(`  ${parameter.name.padEnd(22)}${required.padEnd(6)}${parameter.type.padEnd(28)}  ${parameter.description}`);
-            for (const detail of parameter.details ?? [])
-                lines.push(`    ${detail}`);
-        }
-        lines.push('');
-    }
-    if (command.name === 'browser_list') {
-        lines.push('目标范围（按需）：', '  --local               只列出当前机器上的浏览器', '  --connector <id|名称> 只列出指定远端 connector 的浏览器', '');
-    }
-    else if (command.name === 'browser_launch') {
-        lines.push('宿主选择（本机与远端同时可用时）：', '  --local               在当前机器启动', '  --connector <id|名称> 在指定远端 connector 启动', '  --browser <id|名称>   在控制浏览器所在宿主启动，并可作为 Cookie/UA 来源', '');
-    }
-    if (command.notes?.length) {
-        lines.push('约束与行为：', ...command.notes.map(note => `  ${note}`), '');
-    }
-    if (command.result?.length) {
-        lines.push('结果：', ...command.result.map(line => `  ${line}`), '');
-    }
-    if (command.examples?.length) {
-        lines.push('示例：');
-        for (const example of command.examples)
-            lines.push(`  ${commandName} ${example}`);
-    }
-    lines.push('', `运行 ${commandName} --help 查看常用选项。`);
-    console.error(lines.join('\n'));
-}
 function printUnknownCommand(commandName, args) {
     const input = commandInput(args) || args[0] || '';
     const suggestions = findCommandSuggestions(args, SUGGESTABLE_COMMANDS);
@@ -605,6 +573,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] === 'run') {
+        const { runScriptCli } = await import('./scriptCli.js');
+        return runScriptCli(args.slice(1), commandName);
+    }
     if (args[0] === 'capture_checkpoint')
         args = ['tab_checkpoint', ...args.slice(1)];
     const provider = installedProvider(args[0]);
@@ -641,7 +613,7 @@ export async function runMearlCli(args, options = {}) {
     if (args.includes('--help') || args.includes('-h')) {
         const command = COMMAND_MAP.get(args[0]);
         if (command)
-            printCommandHelp(commandName, command);
+            console.error(formatCommandHelp(commandName, command));
         else if (args[0] === 'check')
             printCheckHelp(commandName);
         else if (ADVANCED_BUILTIN_COMMANDS.has(args[0])) {

package/dist/commandHelp.d.ts

@@ -0,0 +1,3 @@
+import { type CommandDef } from './commands.js';
+export declare function getCommandHelp(target?: string): string;
+export declare function formatCommandHelp(commandName: string, command: CommandDef): string;

package/dist/commandHelp.js

@@ -0,0 +1,79 @@
+import { COMMANDS, COMMAND_MAP } from './commands.js';
+import { SDK_METHOD_ACTIONS, SDK_OPTIONS_ONLY_METHODS } from './sdkMethods.js';
+import { listPluginNames } from './plugins/pluginRegistry.js';
+const HELPER_HELP = {
+    invoke: 'invoke(action, payload?, options?) — 调用浏览器 action，返回普通 action 的原始结果',
+    invokePlugin: 'invokePlugin(name, { command, input }, options?) — 调用已注册 Skill 命令，返回该命令的原始结果',
+    help: 'help(methodOrAction?) / help({ plugin, command? }) — 返回共享命令帮助文本；无参数时列出方法；用 console.log 输出',
+    structure: 'structure(value, { maxDepth=5, maxKeys=50, arraySamples=1, maxNodes=2000 }?) — 同步返回有界结构样本；叶子值替换为类型，标注数组样本、循环引用和截断；不能证明未采样内容或业务语义',
+    saveArtifact: 'saveArtifact(artifact, absolutePath, options?) — 保存浏览器文件产物，返回保存结果',
+    selectBrowser: 'selectBrowser({ browser? }, options?) — 选择默认目标；返回 { selected }；browser 使用 browserList 返回的 ID 或名称，空字符串清除默认目标',
+};
+export function getCommandHelp(target) {
+    if (!target)
+        return [
+            ...COMMANDS.map((command) => `${[...SDK_METHOD_ACTIONS].find(([, action]) => action === command.name)?.[0] ?? command.name} (${command.name}) — ${command.summary ?? command.description}`),
+            ...Object.values(HELPER_HELP),
+            ...listPluginNames().map(plugin => `Skill ${plugin} — help({ plugin: '${plugin}' })`),
+        ].join('\n');
+    if (Object.hasOwn(HELPER_HELP, target))
+        return HELPER_HELP[target];
+    const resolved = SDK_METHOD_ACTIONS.get(target) ?? target;
+    const action = resolved === 'capture_checkpoint' ? 'tab_checkpoint' : resolved;
+    if (action === 'browser_select_browser')
+        return HELPER_HELP.selectBrowser;
+    const command = COMMAND_MAP.get(action);
+    if (!command)
+        throw new Error(`Unknown command or SDK method: ${target}`);
+    return formatCommandHelp('mearl', command);
+}
+export function formatCommandHelp(commandName, command) {
+    const payloadUsage = command.params?.length ? ' [--payload <json> | --payload-file <path>]' : '';
+    const lines = [
+        `${command.name}`,
+        `  ${command.description}`,
+        '',
+        '用法：',
+        `  ${commandName} ${command.name}${payloadUsage} [常用选项]`,
+        '',
+    ];
+    const method = [...SDK_METHOD_ACTIONS].find(([, action]) => action === command.name)?.[0];
+    if (method)
+        lines.push('SDK：', ...(method === 'browserRelease'
+            ? [
+                '  await mearl.browserRelease(options?)',
+                '  await mearl.browserRelease(params, options)',
+            ]
+            : [
+                `  await mearl.${method}(${SDK_OPTIONS_ONLY_METHODS.has(method) ? 'options?' : 'params, options?'})`,
+            ]), '');
+    if (command.params?.length) {
+        lines.push('参数（--payload JSON 字段）：');
+        for (const parameter of command.params) {
+            const required = parameter.required ? '必填' : '可选';
+            lines.push(`  ${parameter.name.padEnd(22)}${required.padEnd(6)}${parameter.type.padEnd(28)}  ${parameter.description}`);
+            for (const detail of parameter.details ?? [])
+                lines.push(`    ${detail}`);
+        }
+        lines.push('');
+    }
+    if (command.name === 'browser_list') {
+        lines.push('目标范围（按需）：', '  --local               只列出当前机器上的浏览器', '  --connector <id|名称> 只列出指定远端 connector 的浏览器', '');
+    }
+    else if (command.name === 'browser_launch') {
+        lines.push('宿主选择（本机与远端同时可用时）：', '  --local               在当前机器启动', '  --connector <id|名称> 在指定远端 connector 启动', '  --browser <id|名称>   在控制浏览器所在宿主启动，并可作为 Cookie/UA 来源', '');
+    }
+    if (command.notes?.length) {
+        lines.push('约束与行为：', ...command.notes.map(note => `  ${note}`), '');
+    }
+    if (command.result?.length) {
+        lines.push('结果：', ...command.result.map(line => `  ${line}`), '');
+    }
+    if (command.examples?.length) {
+        lines.push('示例：');
+        for (const example of command.examples)
+            lines.push(`  ${commandName} ${example}`);
+    }
+    lines.push('', `运行 ${commandName} --help 查看常用选项。`);
+    return lines.join('\n');
+}

package/dist/commands.d.ts

@@ -297,7 +297,7 @@ export declare const COMMANDS: readonly [{
         readonly type: "string";
         readonly description: "规则说明";
     }];
-    readonly notes: readonly ["扩展模式规则持久化；CDP 仅支持会话级 modifyHeaders 请求头 set，不支持响应头、initiatorDomains 或其他动作。Provider 是否支持以其能力声明为准。"];
+    readonly notes: readonly ["扩展模式规则持久化；CDP 仅支持会话级 modifyHeaders 请求头 set，不支持响应头、initiatorDomains 或其他动作。Provider 是否支持以其能力声明为准。", "扩展模式会检查规则请求 URL 和显式来源域名的访问权限；缺失时仍保存规则，返回 warnings 和 missingOrigins，不自动弹窗。可在请求规则页面授权，或按提示调用 request_domain_permission。复杂 URL 表达式无法完整推断域名时会提示手动检查。"];
     readonly examples: ["set_rule --payload '{\"actionType\":\"block\",\"filter\":\"^https://example\\\\.com/ads/.*\"}'", "set_rule --payload '{\"ruleId\":42,\"enabled\":false}'"];
 }, {
     readonly name: "get_rules";
@@ -613,7 +613,7 @@ export declare const COMMANDS: readonly [{
         readonly required: true;
         readonly description: "目标标签页 ID";
     }];
-    readonly result: readonly ["默认返回 { 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 结束。", "observation.effects 返回通知、控件和焦点增量，可直接复用 node.ref/selector；changed=true 且 effects 为空不表示失败。", "effects.texts 按需返回普通可见文本的 selector/text，不代表可点击控件或业务成功；超限或覆盖不完整时仍提示补快照。", "fullSnapshotRecommended/snapshotReasons 提示是否补充快照；openedTabs 返回可继续操作的 tabId 和 ready。navigation 模式的 ready 表示新页面就绪。", "显式开启的诊断通道在 diagnostics 中返回动作期间增量，与 observe 独立。"];
+    readonly result: readonly ["默认返回 { action, observation }；action.success 只表示动作成功，业务效果需结合 observation 和目标状态判断。", "observe=false 且未开启 diagnostics 时返回裸动作结果（如 { clicked: true }），没有 action/observation；开启 diagnostics 时返回 { action, diagnostics }。", "包装结果中的 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 独立。"];
     readonly notes: readonly ["selector / text / point 必须且只能提供一个。隐藏页 auto 使用 DOM；只有明确依赖真实用户手势时才激活页面。", "原生 select 可按 option 文本点击；checkbox/radio 返回 controlState.checkedBefore/checkedAfter。"];
     readonly examples: ["page_click --payload '{\"tabId\":12345,\"text\":\"提交\"}'", "page_click --payload '{\"tabId\":12345,\"text\":\"退款明细\",\"role\":\"button\"}'", "page_click --payload '{\"tabId\":12345,\"text\":\"确定\",\"scope\":\"@e12\"}'", "page_click --payload '{\"tabId\":12345,\"selector\":\"@e3\"}'", "page_click --payload '{\"tabId\":12345,\"selector\":\".submit-btn\"}'", "page_click --payload '{\"tabId\":12345,\"selector\":\".gesture-btn\",\"clickMode\":\"touch\"}'", "page_click --payload '{\"tabId\":12345,\"point\":{\"x\":336,\"y\":117}}'", "page_click --payload '{\"tabId\":12345,\"point\":{\"x\":196,\"y\":240},\"coordinateSpace\":\"active-frame\"}'"];
 }, {
@@ -643,7 +643,7 @@ export declare const COMMANDS: readonly [{
         readonly required: true;
         readonly description: "目标标签页 ID";
     }];
-    readonly result: readonly ["默认返回 { 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 结束。", "observation.effects 返回通知、控件和焦点增量，可直接复用 node.ref/selector；changed=true 且 effects 为空不表示失败。", "effects.texts 按需返回普通可见文本的 selector/text，不代表可点击控件或业务成功；超限或覆盖不完整时仍提示补快照。", "fullSnapshotRecommended/snapshotReasons 提示是否补充快照；openedTabs 返回可继续操作的 tabId 和 ready。navigation 模式的 ready 表示新页面就绪。", "显式开启的诊断通道在 diagnostics 中返回动作期间增量，与 observe 独立。"];
+    readonly result: readonly ["默认返回 { action, observation }；action.success 只表示动作成功，业务效果需结合 observation 和目标状态判断。", "observe=false 且未开启 diagnostics 时返回裸动作结果（如 { clicked: true }），没有 action/observation；开启 diagnostics 时返回 { action, diagnostics }。", "包装结果中的 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 独立。"];
     readonly notes: readonly ["起点会自动滚入视口，终点必须同时位于当前视口；否则先滚动页面。隐藏页 auto 使用 DOM，不切换活动页。"];
     readonly examples: ["page_drag --payload '{\"tabId\":12345,\"from\":{\"x\":350,\"y\":80},\"to\":{\"x\":80,\"y\":80}}'", "page_drag --payload '{\"tabId\":12345,\"from\":\"@e3\",\"to\":\"#drop-zone\",\"dragMode\":\"mouse\"}'"];
 }, {
@@ -669,7 +669,7 @@ export declare const COMMANDS: readonly [{
         readonly required: true;
         readonly description: "目标标签页 ID";
     }];
-    readonly result: readonly ["默认返回 { 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 结束。", "observation.effects 返回通知、控件和焦点增量，可直接复用 node.ref/selector；changed=true 且 effects 为空不表示失败。", "effects.texts 按需返回普通可见文本的 selector/text，不代表可点击控件或业务成功；超限或覆盖不完整时仍提示补快照。", "fullSnapshotRecommended/snapshotReasons 提示是否补充快照；openedTabs 返回可继续操作的 tabId 和 ready。navigation 模式的 ready 表示新页面就绪。", "显式开启的诊断通道在 diagnostics 中返回动作期间增量，与 observe 独立。"];
+    readonly result: readonly ["默认返回 { action, observation }；action.success 只表示动作成功，业务效果需结合 observation 和目标状态判断。", "observe=false 且未开启 diagnostics 时返回裸动作结果（如 { clicked: true }），没有 action/observation；开启 diagnostics 时返回 { action, diagnostics }。", "包装结果中的 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 独立。"];
     readonly examples: ["page_type --payload '{\"tabId\":12345,\"selector\":\"@e6\",\"text\":\"搜索关键词\"}'"];
 }, {
     readonly name: "page_hover";
@@ -685,7 +685,7 @@ export declare const COMMANDS: readonly [{
         readonly required: true;
         readonly description: "目标标签页 ID";
     }];
-    readonly result: readonly ["默认返回 { 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 结束。", "observation.effects 返回通知、控件和焦点增量，可直接复用 node.ref/selector；changed=true 且 effects 为空不表示失败。", "effects.texts 按需返回普通可见文本的 selector/text，不代表可点击控件或业务成功；超限或覆盖不完整时仍提示补快照。", "fullSnapshotRecommended/snapshotReasons 提示是否补充快照；openedTabs 返回可继续操作的 tabId 和 ready。navigation 模式的 ready 表示新页面就绪。", "显式开启的诊断通道在 diagnostics 中返回动作期间增量，与 observe 独立。"];
+    readonly result: readonly ["默认返回 { action, observation }；action.success 只表示动作成功，业务效果需结合 observation 和目标状态判断。", "observe=false 且未开启 diagnostics 时返回裸动作结果（如 { clicked: true }），没有 action/observation；开启 diagnostics 时返回 { action, diagnostics }。", "包装结果中的 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 独立。"];
     readonly examples: ["page_hover --payload '{\"tabId\":12345,\"selector\":\".nav-menu\"}'"];
 }, {
     readonly name: "page_scroll";
@@ -713,7 +713,7 @@ export declare const COMMANDS: readonly [{
         readonly required: true;
         readonly description: "目标标签页 ID";
     }];
-    readonly result: readonly ["默认返回 { 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 结束。", "observation.effects 返回通知、控件和焦点增量，可直接复用 node.ref/selector；changed=true 且 effects 为空不表示失败。", "effects.texts 按需返回普通可见文本的 selector/text，不代表可点击控件或业务成功；超限或覆盖不完整时仍提示补快照。", "fullSnapshotRecommended/snapshotReasons 提示是否补充快照；openedTabs 返回可继续操作的 tabId 和 ready。navigation 模式的 ready 表示新页面就绪。", "显式开启的诊断通道在 diagnostics 中返回动作期间增量，与 observe 独立。", "action.data 返回 moved、atTop/atBottom、scrollYBefore/After、maxScrollY、resolvedContainer 和 ancestorDistance；自动发现的内部容器提供可复用 containerSelector。"];
+    readonly result: readonly ["默认返回 { action, observation }；action.success 只表示动作成功，业务效果需结合 observation 和目标状态判断。", "observe=false 且未开启 diagnostics 时返回裸动作结果（如 { clicked: true }），没有 action/observation；开启 diagnostics 时返回 { action, diagnostics }。", "包装结果中的 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 独立。", "action.data 返回 moved、atTop/atBottom、scrollYBefore/After、maxScrollY、resolvedContainer 和 ancestorDistance；自动发现的内部容器提供可复用 containerSelector。"];
     readonly examples: ["page_scroll --payload '{\"tabId\":12345,\"direction\":\"down\"}'", "page_scroll --payload '{\"tabId\":12345,\"direction\":\"bottom\"}'", "page_scroll --payload '{\"tabId\":12345,\"selector\":\".virtual-list\",\"direction\":\"down\",\"distance\":800}'", "page_scroll --payload '{\"tabId\":12345,\"selector\":\"@e8\",\"containerPolicy\":\"nearest\",\"direction\":\"bottom\"}'"];
 }, {
     readonly name: "page_runtime";
@@ -821,7 +821,7 @@ export declare const COMMANDS: readonly [{
         readonly description: "目标标签页 ID";
     }];
     readonly notes: readonly ["隐藏页 DOM 模式支持 Tab 焦点移动、原生控件 Enter/Space 激活和输入框 Enter 提交；编辑、选择、方向键和页面滚动等原生行为需可见页与 pressMode=keyboard。"];
-    readonly result: readonly ["默认返回 { 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 结束。", "observation.effects 返回通知、控件和焦点增量，可直接复用 node.ref/selector；changed=true 且 effects 为空不表示失败。", "effects.texts 按需返回普通可见文本的 selector/text，不代表可点击控件或业务成功；超限或覆盖不完整时仍提示补快照。", "fullSnapshotRecommended/snapshotReasons 提示是否补充快照；openedTabs 返回可继续操作的 tabId 和 ready。navigation 模式的 ready 表示新页面就绪。", "显式开启的诊断通道在 diagnostics 中返回动作期间增量，与 observe 独立。", "action.data.dispatchMode / fallbackReason / defaultAction 说明实际输入路径。"];
+    readonly result: readonly ["默认返回 { action, observation }；action.success 只表示动作成功，业务效果需结合 observation 和目标状态判断。", "observe=false 且未开启 diagnostics 时返回裸动作结果（如 { clicked: true }），没有 action/observation；开启 diagnostics 时返回 { action, diagnostics }。", "包装结果中的 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 独立。", "action.data.dispatchMode / fallbackReason / defaultAction 说明实际输入路径。"];
     readonly examples: ["page_press --payload '{\"tabId\":12345,\"key\":\"Enter\"}'"];
 }, {
     readonly name: "page_wait";
@@ -911,7 +911,7 @@ export declare const COMMANDS: readonly [{
         readonly required: true;
         readonly description: "目标标签页 ID";
     }];
-    readonly result: readonly ["默认返回 { 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 结束。", "observation.effects 返回通知、控件和焦点增量，可直接复用 node.ref/selector；changed=true 且 effects 为空不表示失败。", "effects.texts 按需返回普通可见文本的 selector/text，不代表可点击控件或业务成功；超限或覆盖不完整时仍提示补快照。", "fullSnapshotRecommended/snapshotReasons 提示是否补充快照；openedTabs 返回可继续操作的 tabId 和 ready。navigation 模式的 ready 表示新页面就绪。", "显式开启的诊断通道在 diagnostics 中返回动作期间增量，与 observe 独立。"];
+    readonly result: readonly ["默认返回 { action, observation }；action.success 只表示动作成功，业务效果需结合 observation 和目标状态判断。", "observe=false 且未开启 diagnostics 时返回裸动作结果（如 { clicked: true }），没有 action/observation；开启 diagnostics 时返回 { action, diagnostics }。", "包装结果中的 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 独立。"];
     readonly notes: readonly ["直接写入 input[type=file]，不依赖 file chooser；隐藏的文件节点也可上传。外部 Provider 的文件中转能力查询 mearl <providerId>。"];
     readonly examples: ["page_upload --payload '{\"tabId\":12345,\"selector\":\"#file-input\",\"filePaths\":[\"/Users/me/photo.jpg\"]}'"];
 }, {
@@ -1093,7 +1093,7 @@ export declare const COMMANDS: readonly [{
     }, {
         readonly name: "mtopEnv";
         readonly type: "\"default\" | \"prod\" | \"pre\"";
-        readonly description: "可选 MTop 页面接口环境；default 关闭环境改写，省略时保持当前设置。扩展模式全局生效，CDP 模式仅作用于目标 tab";
+        readonly description: "可选 MTop 页面接口环境；default 关闭环境改写，省略时保持当前设置。仅作用于目标 tab";
     }, {
         readonly name: "emulation";
         readonly type: "object";
@@ -1211,7 +1211,7 @@ export declare const COMMANDS: readonly [{
         readonly required: true;
         readonly description: "需要授权的域名，如 example.com";
     }];
-    readonly notes: readonly ["domain 使用纯主机名，不传 URL。仅在非 BUC send_request 报域权限缺失时申请，BUC 不使用浏览器域权限。", "弹窗等待用户选择，90 秒超时或关闭按拒绝处理；granted=true 后才重试原请求。"];
+    readonly notes: readonly ["domain 使用纯主机名，不传 URL。在非 BUC send_request 报域权限缺失，或 set_rule 提示缺少域名权限时申请；BUC 不使用浏览器域权限。", "弹窗等待用户选择，90 秒超时或关闭按拒绝处理；granted=true 后才重试原请求。"];
     readonly result: readonly ["返回 granted、domain，授权成功时包含 origin。"];
     readonly examples: ["request_domain_permission --payload '{\"domain\":\"example.com\"}'"];
 }, {

package/dist/commands.js

@@ -30,7 +30,7 @@ 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 表示新页面就绪。',
@@ -298,6 +298,7 @@ export const COMMANDS = [
         ],
         notes: [
             '扩展模式规则持久化；CDP 仅支持会话级 modifyHeaders 请求头 set，不支持响应头、initiatorDomains 或其他动作。Provider 是否支持以其能力声明为准。',
+            '扩展模式会检查规则请求 URL 和显式来源域名的访问权限；缺失时仍保存规则，返回 warnings 和 missingOrigins，不自动弹窗。可在请求规则页面授权，或按提示调用 request_domain_permission。复杂 URL 表达式无法完整推断域名时会提示手动检查。',
         ],
         examples: [
             `set_rule --payload '{"actionType":"block","filter":"^https://example\\\\.com/ads/.*"}'`,
@@ -1200,7 +1201,7 @@ export const COMMANDS = [
             {
                 name: 'mtopEnv',
                 type: '"default" | "prod" | "pre"',
-                description: '可选 MTop 页面接口环境；default 关闭环境改写，省略时保持当前设置。扩展模式全局生效，CDP 模式仅作用于目标 tab',
+                description: '可选 MTop 页面接口环境；default 关闭环境改写，省略时保持当前设置。仅作用于目标 tab',
             },
             {
                 name: 'emulation',
@@ -1352,7 +1353,7 @@ export const COMMANDS = [
             },
         ],
         notes: [
-            'domain 使用纯主机名，不传 URL。仅在非 BUC send_request 报域权限缺失时申请，BUC 不使用浏览器域权限。',
+            'domain 使用纯主机名，不传 URL。在非 BUC send_request 报域权限缺失，或 set_rule 提示缺少域名权限时申请；BUC 不使用浏览器域权限。',
             '弹窗等待用户选择，90 秒超时或关闭按拒绝处理；granted=true 后才重试原请求。',
         ],
         result: ['返回 granted、domain，授权成功时包含 origin。'],

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

@@ -534,7 +534,7 @@ export interface SetAppProfileParams {
     bridgeConfig?: AppBridgeConfig;
     /**
      * 可选 MTop 接口环境。default 关闭环境改写；省略时保持当前设置。
-     * 扩展模式与插件设置页共享并全局生效；CDP 模式仅作用于目标 tab。
+     * 仅作用于目标 tab，扩展模式与该 tab 的快捷设置共享。
      */
     mtopEnv?: MtopEnvironment;
     /**

package/dist/generated/data-structure.d.ts

@@ -0,0 +1,8 @@
+export interface StructureOptions {
+    maxDepth?: number;
+    maxKeys?: number;
+    arraySamples?: number;
+    maxNodes?: number;
+}
+/** Describes a bounded sample of a value without invoking accessors or exposing leaf values. */
+export declare function getStructure(data: unknown, options?: StructureOptions): unknown;

package/dist/generated/data-structure.js

@@ -0,0 +1,58 @@
+/** Describes a bounded sample of a value without invoking accessors or exposing leaf values. */
+export function getStructure(data, options = {}) {
+    const { maxDepth = 5, maxKeys = 50, arraySamples = 1, maxNodes = 2000 } = options;
+    for (const [name, value, limit] of [
+        ['maxDepth', maxDepth, 20],
+        ['maxKeys', maxKeys, 1000],
+        ['arraySamples', arraySamples, 20],
+        ['maxNodes', maxNodes, 10000],
+    ]) {
+        if (!Number.isSafeInteger(value) || value < 1 || value > limit)
+            throw new Error(`${name} must be an integer between 1 and ${limit}`);
+    }
+    const ancestors = new WeakSet();
+    let nodes = 0;
+    const visit = (value, depth) => {
+        if (++nodes > maxNodes)
+            return '<max nodes reached>';
+        if (depth >= maxDepth)
+            return '<max depth reached>';
+        if (value === null)
+            return 'null';
+        if (typeof value !== 'object')
+            return typeof value;
+        if (ancestors.has(value))
+            return '<circular>';
+        ancestors.add(value);
+        try {
+            if (Array.isArray(value)) {
+                if (!value.length)
+                    return 'array[0]';
+                const samples = Array.from({ length: Math.min(value.length, arraySamples) }, (_, index) => {
+                    const descriptor = Object.getOwnPropertyDescriptor(value, index);
+                    return descriptor && 'value' in descriptor
+                        ? visit(descriptor.value, depth + 1)
+                        : descriptor
+                            ? '<accessor>'
+                            : 'undefined';
+                });
+                return {
+                    _type: `array[${value.length}]`,
+                    ...(arraySamples === 1 ? { _sample: samples[0] } : { _samples: samples }),
+                };
+            }
+            const keys = Object.keys(value);
+            const entries = keys.slice(0, maxKeys).map(key => {
+                const descriptor = Object.getOwnPropertyDescriptor(value, key);
+                return [key, 'value' in descriptor ? visit(descriptor.value, depth + 1) : '<accessor>'];
+            });
+            if (keys.length > maxKeys)
+                entries.push(['<truncated keys>', keys.length - maxKeys]);
+            return Object.fromEntries(entries);
+        }
+        finally {
+            ancestors.delete(value);
+        }
+    };
+    return visit(data, 0);
+}

package/dist/generated/plugin-host-build.d.ts

@@ -0,0 +1 @@
+export declare const PLUGIN_HOST_BUILD_ID = "e5c7f6cfb7a597a523293c0ea2929b4970aa9eb86e7aeb672f85a37c317bc258";

package/dist/generated/plugin-host-build.js

@@ -0,0 +1,2 @@
+// Generated by scripts/generate-plugin-host-build.mjs.
+export const PLUGIN_HOST_BUILD_ID = 'e5c7f6cfb7a597a523293c0ea2929b4970aa9eb86e7aeb672f85a37c317bc258';