mooncat-browser 0.2.4 → 0.2.5

package/dist/actions.md

@@ -1,17 +1,57 @@
-# operate action 清单
+# SDK 能力清单
 
-`BrowserClient.operate({ pageHandle, action, params })` 的全部 action 取值与参数。
+`BrowserClient` 有两套入口:
+1. **直接方法**(`browser.xxx()`)— 不走 operate,见下表一。
+2. **operate(action)**(`browser.operate({ pageHandle, action, params })`)— 见下表二。
 
-> 自动生成，来自 `browser-op/backend/browserd.cjs` 的 `@action` 标注。这是 browser 内核的公开契约，始终最新。
+> 自动生成。operate(action) 来自 `browser-op/backend/browserd.cjs` 的 `@action` 标注;
+> 直接方法来自 `src/client.ts`(脚本内维护,改公开方法时同步)。始终权威。
 
 ## 约定
 
-- **pageHandle**：所有 action 都需要，由 `newTab()` / `listTabs()` 返回的 `tab.pageHandle` 提供。
-- **selector 语法**：CSS / `aria-ref=eN`（来自 snapshot 的 ref）/ `.cls>>nth(n)` / `.cls>>last`。
-- **ext 列**：action 在双路由（CDP / WebPlater 扩展）的可用性。
+- **pageHandle**:operate(action) 都需要,由 `newTab()` / `listTabs()` 返回的 `tab.pageHandle` 提供。
+- **selector 语法**:CSS / `aria-ref=eN`(来自 snapshot 的 ref)/ `.cls>>nth(n)` / `.cls>>last`。
+- **ext 列**:action 在双路由(CDP / WebPlater 扩展)的可用性。
   - ✓ = CDP 与扩展均支持
-  - ✗ = 仅 CDP（扩展路不支持，如 `waitForFunction`，因扩展路 CSP 拦截 eval）
-  - 仅 ext = 仅扩展路（如 `setDialogHandler`、`listDownloads`，依赖扩展 API）
+  - ✗ = 仅 CDP(扩展路不支持,如 `waitForFunction`,因扩展路 CSP 拦截 eval)
+  - 仅 ext = 仅扩展路(如 `setDialogHandler`、`listDownloads`,依赖扩展 API)
+
+## 一、BrowserClient 直接方法(不走 operate)
+
+### 生命周期 / tab
+
+| 方法 | 签名 | 说明 |
+| --- | --- | --- |
+| `health` | health(timeoutMs?) | 探测 browserd 是否就绪 + browser 是否 open。返回 null = 连不上 |
+| `open` | open({ routeMode: "cdp"\|"extension", headless? }) | 打开/复用浏览器(幂等)。routeMode 必填(无 auto) |
+| `close` | close() | graceful 关浏览器(保留登录态)。用户满意前不要 close |
+| `newTab` | newTab({ url?, force? }) | 新建 tab(或复用同 url 的 tab)。返回含 pageHandle |
+| `listTabs` | listTabs() | 列所有 tab(每项含 pageHandle) |
+| `reuseTab` | reuseTab({ url?, urlMatch? }) | 按 url/urlMatch 找已有 tab 复用;没有才 newTab。高危平台频繁重开触发风控,已开的 tab 应复用 |
+
+### cookie
+
+| 方法 | 签名 | 说明 |
+| --- | --- | --- |
+| `getCookies` | getCookies({ url?, domain? }) | 读 cookie(按 url 或 domain 过滤) |
+| `setCookies` | setCookies(cookies[]) | 写 cookie |
+| `clearCookies` | clearCookies({ url? \| domain? }) | 清 cookie(按 url 或 domain;不传清该域全部) |
+
+### 下载(仅 extension 路)
+
+| 方法 | 签名 | 说明 |
+| --- | --- | --- |
+| `listDownloads` | listDownloads(limit?) | 列最近下载(默认 20) |
+| `getDownload` | getDownload(id) | 查单个下载状态 |
+| `waitForDownload` | waitForDownload({ filenameRegex?, sinceMs?, timeoutMs?, intervalMs? }) | 轮询等下载完成(reason=complete 成功,timeout 超时)。点了下载按钮后调用 |
+
+### 通用等待
+
+| 方法 | 签名 | 说明 |
+| --- | --- | --- |
+| `waitFor` | waitFor({ tab, selector?, text?, pollTimeoutMs?, intervalMs?, maxRefresh?, refreshSettleMs?, frameId? }) | 等 DOM 节点(selector)或文本(text)出现。延迟重试+刷新重试。SPA 异步加载用,比 sleep 固定等待稳 |
+
+## 二、operate(action) 清单
 
 ### 交互
 
@@ -30,8 +70,6 @@
 | `selectOption` | `selector`:string, `value`:string | {ok,selector,value} | 选择option | ✓ |
 | `dblclick` | `selector`:string | {ok,selector} | 双击元素 | ✓ |
 | `mouseMove` | `x`:number, `y`:number | {ok,x,y} | 移动鼠标到坐标 | ✓ |
-| `clickAt` | `x`:number, `y`:number, `button`?:string=left, `clickCount`?:number=1 | {ok,x,y,route} | 坐标点击(CDP路page.mouse真实鼠标) | ✓ |
-| `clickByText` | `text`:string, `exact`?:boolean=false, `index`?:number=0, `offsetX`?:number=0, `offsetY`?:number=0 | {ok,text,x,y,match,route} | 定位可见文本后立即点击(CDP路原子) | ✓ |
 | `dragTo` | `source`:string, `target`:string | {ok,source,target} | 拖拽source到target(双兼容mouse+HTML5) | ✓ |
 
 ### 读取
@@ -39,7 +77,6 @@
 | action | params | returns | description | ext |
 | --- | --- | --- | --- | --- |
 | `locateVisibleText` | `text`:string, `exact`?:boolean=false, `index`?:number=0 | {ok,matches:[{text,x,y,width,height,centerX,centerY,visible}]} | 定位可见文本节点返回bbox(不返回DOM handle) | ✓ |
-| `locateVisibleText` | `text`:string, `exact`?:boolean=false, `index`?:number=0 | {ok,matches:[{text,x,y,width,height,centerX,centerY,visible}]} | 定位可见文本节点返回bbox | ✓ |
 | `innerHTML` | `selector`:string | {ok,selector,value} | 读元素innerHTML | ✓ |
 | `innerText` | `selector`:string | {ok,selector,value} | 读元素innerText | ✓ |
 | `textContent` | `selector`:string | {ok,selector,value} | 读元素textContent | ✓ |
@@ -55,7 +92,6 @@
 | --- | --- | --- | --- | --- |
 | `operateSequence` | `steps`:array | {ok,results} | 原子序列执行(locate/click/wait在同一页面上下文串行) | ✓ |
 | `setDialogHandler` | `handler`:string | {ok} | 设置JS对话框处理 | 仅 ext |
-| `operateSequence` | `steps`:array | {ok,results} | 原子序列执行 | ✓ |
 | `evaluate` | `source`:string, `args`?:any | 由函数返回值决定 | 执行页面JS函数(返回其结果) | ✓ |
 | `setInputFiles` | `selector`:string, `files`:array, `timeout`?:number=10000 | {ok,selector,count} | 上传文件到file input | ✓ |
 
@@ -67,7 +103,7 @@
 | `goBack` | `timeout`?:number=15000 | {ok,url} | 后退一页 | ✓ |
 | `goForward` | `timeout`?:number=15000 | {ok,url} | 前进一页 | ✓ |
 | `reload` | `timeout`?:number=15000 | {ok,url} | 刷新当前页 | ✓ |
-| `status` | — | {ok,url,title,readyState,textLength} | 读当前页状态(url/title/readyState) | ✓ |
+| `status` | — | {ok,url,title,readyState,textLength} | 读当前页状态(url/title/readyState/textLength) | ✓ |
 
 ### 等待
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mooncat-browser",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "浏览器自动化工具包：可独立启动的本地服务（browserd）+ JS/TS client。双路由（WebPlater 扩展 / CDP），不依赖 mooncat 总发行体。",
   "type": "module",
   "main": "./dist/client.js",

package/skills/browser/references/operate-actions.md

@@ -1,128 +1,132 @@
 # SDK 能力清单
 
-`BrowserClient` 有**两套**入口，不要混：
+`BrowserClient` 有**两套**入口,不要混:
 
-1. **直接方法**（`browser.xxx()`）— 生命周期 / tab / cookie / 下载 / 通用等待。不走 operate。
-2. **operate(action)**（`browser.operate({ pageHandle, action, params })`）— 页面内动作（导航/交互/读取/存储/截图），40+ 个 action。
+1. **直接方法**(`browser.xxx()`)— 生命周期/tab/cookie/下载/通用等待。不走 operate。
+2. **operate(action)**(`browser.operate({ pageHandle, action, params })`)— 页面内动作,见下表。
 
-下面两段分开列。表里没有 ≠ 工具没有 —— 先看另一段。
+两段分开看。表里没有 ≠ 工具没有 —— 先看另一段。
 
-## 一、BrowserClient 直接方法（不走 operate）
+## 一、BrowserClient 直接方法(不走 operate)
 
 ### 生命周期 / tab
 
 | 方法 | 签名 | 说明 |
 | --- | --- | --- |
-| `health` | `health(timeoutMs?)` → `/health` body 或 null | 探测 browserd 是否就绪 + browser 是否 open。返回 null = 连不上 |
-| `open` | `open({ routeMode: "cdp"\|"extension", headless? })` → BrowserHandle | 打开/复用浏览器（幂等）。routeMode 必填（无 auto） |
-| `close` | `close()` → `{ ok, closed }` | graceful 关浏览器（保留登录态）。用户满意前不要 close |
-| `newTab` | `newTab({ url?, force? })` → TabInfo | 新建 tab（或复用同 url 的 tab）。返回含 `pageHandle` |
-| `listTabs` | `listTabs()` → TabInfo[] | 列所有 tab（每项含 pageHandle） |
-| `reuseTab` | `reuseTab({ url?, urlMatch? })` → TabInfo & { reused } | 按 url/urlMatch 找已有 tab 复用；没有才 newTab。**高危平台频繁重开触发风控，已开的 tab 应复用** |
+| `health` | health(timeoutMs?) | 探测 browserd 是否就绪 + browser 是否 open。返回 null = 连不上 |
+| `open` | open({ routeMode: "cdp"\|"extension", headless? }) | 打开/复用浏览器(幂等)。routeMode 必填(无 auto) |
+| `close` | close() | graceful 关浏览器(保留登录态)。用户满意前不要 close |
+| `newTab` | newTab({ url?, force? }) | 新建 tab(或复用同 url 的 tab)。返回含 pageHandle |
+| `listTabs` | listTabs() | 列所有 tab(每项含 pageHandle) |
+| `reuseTab` | reuseTab({ url?, urlMatch? }) | 按 url/urlMatch 找已有 tab 复用;没有才 newTab。高危平台频繁重开触发风控,已开的 tab 应复用 |
 
 ### cookie
 
 | 方法 | 签名 | 说明 |
 | --- | --- | --- |
-| `getCookies` | `getCookies({ url?, domain? })` → `{ cookies }` | 读 cookie（按 url 或 domain 过滤） |
-| `setCookies` | `setCookies(cookies[])` → `{ ok, count }` | 写 cookie |
-| `clearCookies` | `clearCookies({ url? \| domain? })` | 清 cookie（按 url 或 domain；不传清该域全部） |
+| `getCookies` | getCookies({ url?, domain? }) | 读 cookie(按 url 或 domain 过滤) |
+| `setCookies` | setCookies(cookies[]) | 写 cookie |
+| `clearCookies` | clearCookies({ url? \| domain? }) | 清 cookie(按 url 或 domain;不传清该域全部) |
 
-### 下载（仅 extension 路，chrome.downloads API）
+### 下载(仅 extension 路)
 
 | 方法 | 签名 | 说明 |
 | --- | --- | --- |
-| `listDownloads` | `listDownloads(limit?)` → `{ downloads }` | 列最近下载（默认 20） |
-| `getDownload` | `getDownload(id)` → `{ download }` | 查单个下载状态 |
-| `waitForDownload` | `waitForDownload({ filenameRegex?, sinceMs?, timeoutMs?, intervalMs? })` → `{ download, reason }` | 轮询等下载完成（reason=complete 成功，timeout 超时）。**点了下载按钮后调用** |
+| `listDownloads` | listDownloads(limit?) | 列最近下载(默认 20) |
+| `getDownload` | getDownload(id) | 查单个下载状态 |
+| `waitForDownload` | waitForDownload({ filenameRegex?, sinceMs?, timeoutMs?, intervalMs? }) | 轮询等下载完成(reason=complete 成功,timeout 超时)。点了下载按钮后调用 |
 
-### 通用等待（轮询页面，复用 operate(evaluate)）
+### 通用等待
 
 | 方法 | 签名 | 说明 |
 | --- | --- | --- |
-| `waitFor` | `waitFor({ tab, selector?, text?, pollTimeoutMs?, intervalMs?, maxRefresh?, refreshSettleMs?, frameId? })` → `{ ok, matched, refreshCount, elapsedMs }` | 等 DOM 节点（selector）或文本（text）出现。延迟重试 + 刷新重试。SPA 异步加载用，比 sleep 固定等待稳 |
-
-> `waitFor` 内部用 operate(evaluate) 轮询，但它本身是直接方法（语义封装，不让你手写 operate+evaluate 循环）。
+| `waitFor` | waitFor({ tab, selector?, text?, pollTimeoutMs?, intervalMs?, maxRefresh?, refreshSettleMs?, frameId? }) | 等 DOM 节点(selector)或文本(text)出现。延迟重试+刷新重试。SPA 异步加载用,比 sleep 固定等待稳 |
 
 ## 二、operate(action) 清单
 
-`browser.operate({ pageHandle, action, params })` 的 40+ 个 action。**都要传 pageHandle**（从 newTab/listTabs/reuseTab 拿）。
-
-### 导航
-
-| action | params | returns | 说明 | ext |
-| --- | --- | --- | --- | --- |
-| `goto` | `url`:string | {ok,url} | 导航到 URL，等待 DOMContentLoaded | ✓ |
-| `goBack` | `timeout?`:number=15000 | {ok,url} | 后退一页 | ✓ |
-| `goForward` | `timeout?`:number=15000 | {ok,url} | 前进一页 | ✓ |
-| `reload` | `timeout?`:number=15000 | {ok,url} | 刷新当前页 | ✓ |
-| `status` | — | {ok,url,title,readyState,textLength} | 读当前页状态 | ✓ |
+`browser.operate({ pageHandle, action, params })` 的全部 action。**都要传 pageHandle**(从 newTab/listTabs/reuseTab 拿)。
+完整说明见包内 `dist/actions.md`。
 
 ### 交互
 
-| action | params | returns | 说明 | ext |
+| action | params | returns | description | ext |
 | --- | --- | --- | --- | --- |
-| `click` | `selector`:string, `x`?, `y`? | {ok,selector} | 点击元素（或坐标 x,y） | ✓ |
-| `clickAt` | `x`:number, `y`:number, `button?`=left, `clickCount?`=1 | {ok,x,y,route} | 坐标点击（绕过 selector） | ✓ |
-| `clickByText` | `text`:string, `exact?`=false, `index?`=0, `offsetX?`, `offsetY?` | {ok,text,x,y,match,route} | 定位可见文本后立即点击（原子，防 DOM 重渲染） | ✓ |
-| `fill` | `selector`:string, `value`:string | {ok,selector,value} | 在 selector 元素填文本（先清空） | ✓ |
-| `type` | `selector`:string, `value`:string, `delay?`=0 | {ok,selector} | 逐字输入（带延迟，模拟键盘） | ✓ |
+| `clickAt` | `x`:number, `y`:number, `button`?:string=left, `clickCount`?:number=1 | {ok,x,y,route} | 坐标点击(绕过selector,CDP路真实鼠标/扩展路合成事件) | ✓ |
+| `clickByText` | `text`:string, `exact`?:boolean=false, `index`?:number=0, `offsetX`?:number=0, `offsetY`?:number=0 | {ok,text,x,y,match,route} | 定位可见文本后立即点击(原子,防DOM重渲染) | ✓ |
+| `click` | `selector`:string, `x`?:number, `y`?:number | {ok,selector} | 点击元素(或坐标x,y) | ✓ |
+| `fill` | `selector`:string, `value`:string | {ok,selector,value} | 在selector元素填入文本(先清空) | ✓ |
+| `type` | `selector`:string, `value`:string, `delay`?:number=0 | {ok,selector} | 逐字输入(带延迟,模拟键盘) | ✓ |
 | `press` | `selector`:string, `key`:string | {ok,selector,key} | 在元素上按键 | ✓ |
-| `hover` | `selector`:string, `x`?, `y`? | {ok,selector} | 悬停（或坐标） | ✓ |
+| `hover` | `selector`:string, `x`?:number, `y`?:number | {ok,selector} | 悬停元素(或坐标) | ✓ |
 | `focus` | `selector`:string | {ok,selector} | 聚焦元素 | ✓ |
-| `check` | `selector`:string | {ok,selector} | 勾选 checkbox/radio | ✓ |
+| `check` | `selector`:string | {ok,selector} | 勾选checkbox/radio | ✓ |
 | `uncheck` | `selector`:string | {ok,selector} | 取消勾选 | ✓ |
-| `selectOption` | `selector`:string, `value`:string | {ok,selector,value} | 选择 option | ✓ |
+| `selectOption` | `selector`:string, `value`:string | {ok,selector,value} | 选择option | ✓ |
 | `dblclick` | `selector`:string | {ok,selector} | 双击元素 | ✓ |
 | `mouseMove` | `x`:number, `y`:number | {ok,x,y} | 移动鼠标到坐标 | ✓ |
-| `dragTo` | `source`:string, `target`:string | {ok,source,target} | 拖拽 source 到 target | ✓ |
-| `setInputFiles` | `selector`:string, `files`:array, `timeout?`=10000 | {ok,selector,count} | 上传文件到 file input | ✓ |
+| `dragTo` | `source`:string, `target`:string | {ok,source,target} | 拖拽source到target(双兼容mouse+HTML5) | ✓ |
 
 ### 读取
 
-| action | params | returns | 说明 | ext |
+| action | params | returns | description | ext |
 | --- | --- | --- | --- | --- |
-| `snapshot` | `depth?`, `timeout?`=15000, `rootSelector?`, `interactiveOnly?`, `chunkId?`, `chunkSize?`, `refresh?` | {ok,yaml,...} | aria 无障碍快照（返回 yaml，可分块） | ✓ |
-| `innerHTML` | `selector`:string | {ok,selector,value} | 读 innerHTML | ✓ |
-| `innerText` | `selector`:string | {ok,selector,value} | 读 innerText | ✓ |
-| `textContent` | `selector`:string | {ok,selector,value} | 读 textContent | ✓ |
+| `locateVisibleText` | `text`:string, `exact`?:boolean=false, `index`?:number=0 | {ok,matches:[{text,x,y,width,height,centerX,centerY,visible}]} | 定位可见文本节点返回bbox(不返回DOM handle) | ✓ |
+| `innerHTML` | `selector`:string | {ok,selector,value} | 读元素innerHTML | ✓ |
+| `innerText` | `selector`:string | {ok,selector,value} | 读元素innerText | ✓ |
+| `textContent` | `selector`:string | {ok,selector,value} | 读元素textContent | ✓ |
 | `getAttribute` | `selector`:string, `name`:string | {ok,selector,name,value} | 读元素属性 | ✓ |
-| `inputValue` | `selector`:string, `timeout?`=10000 | {ok,selector,value} | 读 input/select 当前值 | ✓ |
-| `boundingBox` | `selector`:string | {ok,selector,x,y,width,height} | 读元素包围盒 | ✓ |
-| `count` | `selector`:string | {ok,selector,count} | 统计 selector 匹配数 | ✓ |
-| `locateVisibleText` | `text`:string, `exact?`=false, `index?`=0 | {ok,matches:[{text,x,y,width,height,centerX,centerY,visible}]} | 定位可见文本节点返回 bbox（不返回 DOM handle） | ✓ |
-| `evaluate` | `source`:string, `args?`:any | 函数返回值 | 执行页面 JS 函数，返回其结果 | ✓ |
-| `listFrames` | — | [{frameId,url,parentFrameId}] | 列当前 tab 的所有 frame（iframe 结构） | ✓ |
+| `inputValue` | `selector`:string, `timeout`?:number=10000 | {ok,selector,value} | 读input/select当前值 | ✓ |
+| `boundingBox` | `selector`:string | {ok,selector,x,y,width,height} | 读元素包围盒(坐标+尺寸) | ✓ |
+| `count` | `selector`:string | {ok,selector,count} | 统计selector匹配数 | ✓ |
+| `snapshot` | `depth`?:number, `timeout`?:number=15000 | {ok,yaml,totalChars} | aria无障碍快照(返回yaml) | ✓ |
+
+### 进阶
+
+| action | params | returns | description | ext |
+| --- | --- | --- | --- | --- |
+| `operateSequence` | `steps`:array | {ok,results} | 原子序列执行(locate/click/wait在同一页面上下文串行) | ✓ |
+| `setDialogHandler` | `handler`:string | {ok} | 设置JS对话框处理 | 仅 ext |
+| `evaluate` | `source`:string, `args`?:any | 由函数返回值决定 | 执行页面JS函数(返回其结果) | ✓ |
+| `setInputFiles` | `selector`:string, `files`:array, `timeout`?:number=10000 | {ok,selector,count} | 上传文件到file input | ✓ |
+
+### 导航
+
+| action | params | returns | description | ext |
+| --- | --- | --- | --- | --- |
+| `goto` | `url`:string | {ok,url} | 导航到URL,等待DOMContentLoaded | ✓ |
+| `goBack` | `timeout`?:number=15000 | {ok,url} | 后退一页 | ✓ |
+| `goForward` | `timeout`?:number=15000 | {ok,url} | 前进一页 | ✓ |
+| `reload` | `timeout`?:number=15000 | {ok,url} | 刷新当前页 | ✓ |
+| `status` | — | {ok,url,title,readyState,textLength} | 读当前页状态(url/title/readyState/textLength) | ✓ |
 
 ### 等待
 
-| action | params | returns | 说明 | ext |
+| action | params | returns | description | ext |
 | --- | --- | --- | --- | --- |
-| `waitForLoadState` | `state?`=load, `timeout?`=30000 | {ok} | 等待指定加载状态（load/domcontentloaded/networkidle） | ✓ |
-| `waitForSelector` | `selector`:string, `timeout?`=30000 | {ok,selector,visible,inViewport} | 等 selector 元素可见 | ✓ |
-| `waitForFunction` | `source`:string, `timeout?`=30000 | 函数返回值 | 等页面函数返回 truthy | ✗（extension 路 CSP 拦 eval） |
-| `waitForURL` | `url`:string, `timeout?`=30000 | {ok,url} | 等 URL 匹配 | ✓ |
-| `waitForTimeout` | `ms?`=1000 | {ok,ms} | 固定等待 | ✓ |
+| `waitForLoadState` | `state`?:string=load, `timeout`?:number=30000 | {ok} | 等待指定加载状态 | ✓ |
+| `waitForSelector` | `selector`:string, `timeout`?:number=30000 | {ok,selector,visible,inViewport} | 等待selector元素可见 | ✓ |
+| `waitForFunction` | `source`:string, `timeout`?:number=30000 | 由函数返回值决定 | 等待页面函数返回truthy | ✗ (extension路CSP拦截eval) |
+| `waitForURL` | `url`:string, `timeout`?:number=30000 | {ok,url} | 等待URL匹配 | ✓ |
+| `waitForTimeout` | `ms`?:number=1000 | {ok,ms} | 固定等待 | ✓ |
 
-### 存储（localStorage）
+### 标签页
 
-| action | params | returns | 说明 | ext |
+| action | params | returns | description | ext |
 | --- | --- | --- | --- | --- |
-| `getLocalStorage` | `keys?`:array | {ok,storage} | 读 localStorage（不传读全部） | ✓ |
-| `setLocalStorage` | `items`:object | {ok,count} | 写 localStorage | ✓ |
-| `removeLocalStorage` | `keys?`:array | {ok,count} | 删 localStorage（不传删全部） | ✓ |
-| `clearLocalStorage` | — | {ok} | 清空 localStorage | ✓ |
+| `closeTab` | — | {ok} | 关闭当前page | ✓ |
+| `activate` | — | {ok} | 切到最前(仅可视) | ✓ |
 
-### 标签页 / 截图 / 对话框
+### 截图
 
-| action | params | returns | 说明 | ext |
+| action | params | returns | description | ext |
 | --- | --- | --- | --- | --- |
-| `closeTab` | — | {ok} | 关闭当前 page | ✓ |
-| `activate` | — | {ok} | 切到最前（仅可视） | ✓ |
-| `screenshot` | — | {ok,format,dataUrl} | 截整页 PNG（返回 dataUrl；extension 模式需先 activate） | ✓ |
-| `setDialogHandler` | `handler`:string | {ok} | 设置 JS 对话框处理 | 仅 ext |
-| `operateSequence` | `steps`:array | {ok,results} | 原子序列执行（locate/click/wait 在同页面上下文串行） | ✓ |
+| `screenshot` | — | {ok,format,dataUrl} | 截整页PNG(返回dataUrl) | ✓ |
 
-## ext 列说明
+### 存储
 
-`ext=✓` 表示 action 在 extension 路和 CDP 路行为一致。`✗` 或"仅 ext"见注释。多数 action 双路由统一（路由不泄漏原则）。
+| action | params | returns | description | ext |
+| --- | --- | --- | --- | --- |
+| `getLocalStorage` | `keys`?:array | {ok,storage} | 读localStorage(不传keys读全部) | ✓ |
+| `setLocalStorage` | `items`:object | {ok,count} | 写localStorage | ✓ |
+| `removeLocalStorage` | `keys`?:array | {ok,count} | 删localStorage(不传keys删全部) | ✓ |
+| `clearLocalStorage` | — | {ok} | 清空localStorage | ✓ |