mooncat-browser 0.2.3 → 0.2.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/dist/actions.md +49 -13
  2. package/package.json +1 -1
  3. package/skills/browser/SKILL.md +6 -4
  4. package/skills/browser/references/operate-actions.md +48 -8
package/dist/actions.md CHANGED
@@ -1,17 +1,57 @@
1
- # operate action 清单
1
+ # SDK 能力清单
2
2
 
3
- `BrowserClient.operate({ pageHandle, action, params })` 的全部 action 取值与参数。
3
+ `BrowserClient` 有两套入口:
4
+ 1. **直接方法**(`browser.xxx()`)— 不走 operate,见下表一。
5
+ 2. **operate(action)**(`browser.operate({ pageHandle, action, params })`)— 见下表二。
4
6
 
5
- > 自动生成，来自 `browser-op/backend/browserd.cjs` 的 `@action` 标注。这是 browser 内核的公开契约，始终最新。
7
+ > 自动生成。operate(action) 来自 `browser-op/backend/browserd.cjs` 的 `@action` 标注;
8
+ > 直接方法来自 `src/client.ts`(脚本内维护,改公开方法时同步)。始终权威。
6
9
 
7
10
  ## 约定
8
11
 
9
- - **pageHandle**：所有 action 都需要，由 `newTab()` / `listTabs()` 返回的 `tab.pageHandle` 提供。
10
- - **selector 语法**：CSS / `aria-ref=eN`（来自 snapshot 的 ref）/ `.cls>>nth(n)` / `.cls>>last`。
11
- - **ext 列**：action 在双路由（CDP / WebPlater 扩展）的可用性。
12
+ - **pageHandle**:operate(action) 都需要,由 `newTab()` / `listTabs()` 返回的 `tab.pageHandle` 提供。
13
+ - **selector 语法**:CSS / `aria-ref=eN`(来自 snapshot 的 ref)/ `.cls>>nth(n)` / `.cls>>last`。
14
+ - **ext 列**:action 在双路由(CDP / WebPlater 扩展)的可用性。
12
15
  - ✓ = CDP 与扩展均支持
13
- - ✗ = 仅 CDP（扩展路不支持，如 `waitForFunction`，因扩展路 CSP 拦截 eval）
14
- - 仅 ext = 仅扩展路（如 `setDialogHandler`、`listDownloads`，依赖扩展 API）
16
+ - ✗ = 仅 CDP(扩展路不支持,如 `waitForFunction`,因扩展路 CSP 拦截 eval)
17
+ - 仅 ext = 仅扩展路(如 `setDialogHandler`、`listDownloads`,依赖扩展 API)
18
+
19
+ ## 一、BrowserClient 直接方法(不走 operate)
20
+
21
+ ### 生命周期 / tab
22
+
23
+ | 方法 | 签名 | 说明 |
24
+ | --- | --- | --- |
25
+ | `health` | health(timeoutMs?) | 探测 browserd 是否就绪 + browser 是否 open。返回 null = 连不上 |
26
+ | `open` | open({ routeMode: "cdp"\|"extension", headless? }) | 打开/复用浏览器(幂等)。routeMode 必填(无 auto) |
27
+ | `close` | close() | graceful 关浏览器(保留登录态)。用户满意前不要 close |
28
+ | `newTab` | newTab({ url?, force? }) | 新建 tab(或复用同 url 的 tab)。返回含 pageHandle |
29
+ | `listTabs` | listTabs() | 列所有 tab(每项含 pageHandle) |
30
+ | `reuseTab` | reuseTab({ url?, urlMatch? }) | 按 url/urlMatch 找已有 tab 复用;没有才 newTab。高危平台频繁重开触发风控,已开的 tab 应复用 |
31
+
32
+ ### cookie
33
+
34
+ | 方法 | 签名 | 说明 |
35
+ | --- | --- | --- |
36
+ | `getCookies` | getCookies({ url?, domain? }) | 读 cookie(按 url 或 domain 过滤) |
37
+ | `setCookies` | setCookies(cookies[]) | 写 cookie |
38
+ | `clearCookies` | clearCookies({ url? \| domain? }) | 清 cookie(按 url 或 domain;不传清该域全部) |
39
+
40
+ ### 下载(仅 extension 路)
41
+
42
+ | 方法 | 签名 | 说明 |
43
+ | --- | --- | --- |
44
+ | `listDownloads` | listDownloads(limit?) | 列最近下载(默认 20) |
45
+ | `getDownload` | getDownload(id) | 查单个下载状态 |
46
+ | `waitForDownload` | waitForDownload({ filenameRegex?, sinceMs?, timeoutMs?, intervalMs? }) | 轮询等下载完成(reason=complete 成功,timeout 超时)。点了下载按钮后调用 |
47
+
48
+ ### 通用等待
49
+
50
+ | 方法 | 签名 | 说明 |
51
+ | --- | --- | --- |
52
+ | `waitFor` | waitFor({ tab, selector?, text?, pollTimeoutMs?, intervalMs?, maxRefresh?, refreshSettleMs?, frameId? }) | 等 DOM 节点(selector)或文本(text)出现。延迟重试+刷新重试。SPA 异步加载用,比 sleep 固定等待稳 |
53
+
54
+ ## 二、operate(action) 清单
15
55
 
16
56
  ### 交互
17
57
 
@@ -30,8 +70,6 @@
30
70
  | `selectOption` | `selector`:string, `value`:string | {ok,selector,value} | 选择option | ✓ |
31
71
  | `dblclick` | `selector`:string | {ok,selector} | 双击元素 | ✓ |
32
72
  | `mouseMove` | `x`:number, `y`:number | {ok,x,y} | 移动鼠标到坐标 | ✓ |
33
- | `clickAt` | `x`:number, `y`:number, `button`?:string=left, `clickCount`?:number=1 | {ok,x,y,route} | 坐标点击(CDP路page.mouse真实鼠标) | ✓ |
34
- | `clickByText` | `text`:string, `exact`?:boolean=false, `index`?:number=0, `offsetX`?:number=0, `offsetY`?:number=0 | {ok,text,x,y,match,route} | 定位可见文本后立即点击(CDP路原子) | ✓ |
35
73
  | `dragTo` | `source`:string, `target`:string | {ok,source,target} | 拖拽source到target(双兼容mouse+HTML5) | ✓ |
36
74
 
37
75
  ### 读取
@@ -39,7 +77,6 @@
39
77
  | action | params | returns | description | ext |
40
78
  | --- | --- | --- | --- | --- |
41
79
  | `locateVisibleText` | `text`:string, `exact`?:boolean=false, `index`?:number=0 | {ok,matches:[{text,x,y,width,height,centerX,centerY,visible}]} | 定位可见文本节点返回bbox(不返回DOM handle) | ✓ |
42
- | `locateVisibleText` | `text`:string, `exact`?:boolean=false, `index`?:number=0 | {ok,matches:[{text,x,y,width,height,centerX,centerY,visible}]} | 定位可见文本节点返回bbox | ✓ |
43
80
  | `innerHTML` | `selector`:string | {ok,selector,value} | 读元素innerHTML | ✓ |
44
81
  | `innerText` | `selector`:string | {ok,selector,value} | 读元素innerText | ✓ |
45
82
  | `textContent` | `selector`:string | {ok,selector,value} | 读元素textContent | ✓ |
@@ -55,7 +92,6 @@
55
92
  | --- | --- | --- | --- | --- |
56
93
  | `operateSequence` | `steps`:array | {ok,results} | 原子序列执行(locate/click/wait在同一页面上下文串行) | ✓ |
57
94
  | `setDialogHandler` | `handler`:string | {ok} | 设置JS对话框处理 | 仅 ext |
58
- | `operateSequence` | `steps`:array | {ok,results} | 原子序列执行 | ✓ |
59
95
  | `evaluate` | `source`:string, `args`?:any | 由函数返回值决定 | 执行页面JS函数(返回其结果) | ✓ |
60
96
  | `setInputFiles` | `selector`:string, `files`:array, `timeout`?:number=10000 | {ok,selector,count} | 上传文件到file input | ✓ |
61
97
 
@@ -67,7 +103,7 @@
67
103
  | `goBack` | `timeout`?:number=15000 | {ok,url} | 后退一页 | ✓ |
68
104
  | `goForward` | `timeout`?:number=15000 | {ok,url} | 前进一页 | ✓ |
69
105
  | `reload` | `timeout`?:number=15000 | {ok,url} | 刷新当前页 | ✓ |
70
- | `status` | — | {ok,url,title,readyState,textLength} | 读当前页状态(url/title/readyState) | ✓ |
106
+ | `status` | — | {ok,url,title,readyState,textLength} | 读当前页状态(url/title/readyState/textLength) | ✓ |
71
107
 
72
108
  ### 等待
73
109
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mooncat-browser",
3
- "version": "0.2.3",
3
+ "version": "0.2.5",
4
4
  "description": "浏览器自动化工具包：可独立启动的本地服务（browserd）+ JS/TS client。双路由（WebPlater 扩展 / CDP），不依赖 mooncat 总发行体。",
5
5
  "type": "module",
6
6
  "main": "./dist/client.js",
package/skills/browser/SKILL.md CHANGED
@@ -93,9 +93,11 @@ await browser.operate({ pageHandle: tab.pageHandle, action: "click", params: { s
93
93
  快速开个页面看 Chrome 能不能起、扩展连没连。**不是程序化自动化的方式**;
94
94
  正经自动化用上面的 BrowserClient。open 的 `--route-mode` 必填(无 auto)。
95
95
 
96
- **操作清单不在本 skill 列**——`operate` 的 40+ 个 action(导航/交互/读取/等待/存储/截图)
97
- 是公开契约,查包内 `README.md` 的 "operate 的 action 清单" 或
98
- `browser-op/backend/browserd.cjs` 的 `rpcOperate`(始终权威)。
96
+ **SDK 能力清单见** [references/operate-actions.md](references/operate-actions.md) —— 分两段:
97
+ BrowserClient **直接方法**(`reuseTab`/`listDownloads`/`waitFor`/`waitForDownload` 等,不走 operate)
98
+ + **operate(action)** 的 40+ 个 action(导航/交互/读取/等待/存储/截图)。
99
+ **两套是不同入口,别把 operate 表当全集**——reuseTab/listFrames 这些是 client 直接方法,不在 operate 表里。
100
+ 始终权威源:`browser-op/backend/browserd.cjs` 的 `rpcOperate`(action) + `src/client.ts`(直接方法)。
99
101
 
100
102
  ## 步进式 co-work 的标准节奏
101
103
 
@@ -147,4 +149,4 @@ await browser.operate({ pageHandle: tab.pageHandle, action: "click", params: { s
147
149
  - [references/collect.md](references/collect.md) — **★标准采集工作流**：三件套范式（复用 tab / 清弹窗 / 等就绪），SPA 采集必读
148
150
  - [references/probing.md](references/probing.md) — **★探查方法论**：frame 意识（元素查不到怎么系统性枚举）/ 同名消歧（位置 context）/ SOP 截图识图纪律
149
151
  - [references/high-risk.md](references/high-risk.md) — 高危平台专题（淘宝/京东/银行）：扩展路由 + 验证码 + 拟人化
150
- - [references/operate-actions.md](references/operate-actions.md) — operate 的 40+ 个 action 速查（按导航/交互/读取/等待/存储/截图分组）
152
+ - [references/operate-actions.md](references/operate-actions.md) — **★SDK 能力清单**：BrowserClient 直接方法（reuseTab/listDownloads/waitFor 等，不走 operate）+ operate(action) 40+ 个 action。**两套分开看，别把 operate 表当全集**
package/skills/browser/references/operate-actions.md CHANGED
@@ -1,7 +1,51 @@
1
- # operate 的 action 速查
1
+ # SDK 能力清单
2
2
 
3
- `browser.operate({ pageHandle, action, params })` 支持 40+ 个 action，覆盖导航/交互/读取/等待/存储/截图。
4
- 这是内核公开契约的速查表；完整说明见包内 `dist/actions.md`。
3
+ `BrowserClient` 有**两套**入口,不要混:
4
+
5
+ 1. **直接方法**(`browser.xxx()`)— 生命周期/tab/cookie/下载/通用等待。不走 operate。
6
+ 2. **operate(action)**(`browser.operate({ pageHandle, action, params })`)— 页面内动作,见下表。
7
+
8
+ 两段分开看。表里没有 ≠ 工具没有 —— 先看另一段。
9
+
10
+ ## 一、BrowserClient 直接方法(不走 operate)
11
+
12
+ ### 生命周期 / tab
13
+
14
+ | 方法 | 签名 | 说明 |
15
+ | --- | --- | --- |
16
+ | `health` | health(timeoutMs?) | 探测 browserd 是否就绪 + browser 是否 open。返回 null = 连不上 |
17
+ | `open` | open({ routeMode: "cdp"\|"extension", headless? }) | 打开/复用浏览器(幂等)。routeMode 必填(无 auto) |
18
+ | `close` | close() | graceful 关浏览器(保留登录态)。用户满意前不要 close |
19
+ | `newTab` | newTab({ url?, force? }) | 新建 tab(或复用同 url 的 tab)。返回含 pageHandle |
20
+ | `listTabs` | listTabs() | 列所有 tab(每项含 pageHandle) |
21
+ | `reuseTab` | reuseTab({ url?, urlMatch? }) | 按 url/urlMatch 找已有 tab 复用;没有才 newTab。高危平台频繁重开触发风控,已开的 tab 应复用 |
22
+
23
+ ### cookie
24
+
25
+ | 方法 | 签名 | 说明 |
26
+ | --- | --- | --- |
27
+ | `getCookies` | getCookies({ url?, domain? }) | 读 cookie(按 url 或 domain 过滤) |
28
+ | `setCookies` | setCookies(cookies[]) | 写 cookie |
29
+ | `clearCookies` | clearCookies({ url? \| domain? }) | 清 cookie(按 url 或 domain;不传清该域全部) |
30
+
31
+ ### 下载(仅 extension 路)
32
+
33
+ | 方法 | 签名 | 说明 |
34
+ | --- | --- | --- |
35
+ | `listDownloads` | listDownloads(limit?) | 列最近下载(默认 20) |
36
+ | `getDownload` | getDownload(id) | 查单个下载状态 |
37
+ | `waitForDownload` | waitForDownload({ filenameRegex?, sinceMs?, timeoutMs?, intervalMs? }) | 轮询等下载完成(reason=complete 成功,timeout 超时)。点了下载按钮后调用 |
38
+
39
+ ### 通用等待
40
+
41
+ | 方法 | 签名 | 说明 |
42
+ | --- | --- | --- |
43
+ | `waitFor` | waitFor({ tab, selector?, text?, pollTimeoutMs?, intervalMs?, maxRefresh?, refreshSettleMs?, frameId? }) | 等 DOM 节点(selector)或文本(text)出现。延迟重试+刷新重试。SPA 异步加载用,比 sleep 固定等待稳 |
44
+
45
+ ## 二、operate(action) 清单
46
+
47
+ `browser.operate({ pageHandle, action, params })` 的全部 action。**都要传 pageHandle**(从 newTab/listTabs/reuseTab 拿)。
48
+ 完整说明见包内 `dist/actions.md`。
5
49
 
6
50
  ### 交互
7
51
 
@@ -20,8 +64,6 @@
20
64
  | `selectOption` | `selector`:string, `value`:string | {ok,selector,value} | 选择option | ✓ |
21
65
  | `dblclick` | `selector`:string | {ok,selector} | 双击元素 | ✓ |
22
66
  | `mouseMove` | `x`:number, `y`:number | {ok,x,y} | 移动鼠标到坐标 | ✓ |
23
- | `clickAt` | `x`:number, `y`:number, `button`?:string=left, `clickCount`?:number=1 | {ok,x,y,route} | 坐标点击(CDP路page.mouse真实鼠标) | ✓ |
24
- | `clickByText` | `text`:string, `exact`?:boolean=false, `index`?:number=0, `offsetX`?:number=0, `offsetY`?:number=0 | {ok,text,x,y,match,route} | 定位可见文本后立即点击(CDP路原子) | ✓ |
25
67
  | `dragTo` | `source`:string, `target`:string | {ok,source,target} | 拖拽source到target(双兼容mouse+HTML5) | ✓ |
26
68
 
27
69
  ### 读取
@@ -29,7 +71,6 @@
29
71
  | action | params | returns | description | ext |
30
72
  | --- | --- | --- | --- | --- |
31
73
  | `locateVisibleText` | `text`:string, `exact`?:boolean=false, `index`?:number=0 | {ok,matches:[{text,x,y,width,height,centerX,centerY,visible}]} | 定位可见文本节点返回bbox(不返回DOM handle) | ✓ |
32
- | `locateVisibleText` | `text`:string, `exact`?:boolean=false, `index`?:number=0 | {ok,matches:[{text,x,y,width,height,centerX,centerY,visible}]} | 定位可见文本节点返回bbox | ✓ |
33
74
  | `innerHTML` | `selector`:string | {ok,selector,value} | 读元素innerHTML | ✓ |
34
75
  | `innerText` | `selector`:string | {ok,selector,value} | 读元素innerText | ✓ |
35
76
  | `textContent` | `selector`:string | {ok,selector,value} | 读元素textContent | ✓ |
@@ -45,7 +86,6 @@
45
86
  | --- | --- | --- | --- | --- |
46
87
  | `operateSequence` | `steps`:array | {ok,results} | 原子序列执行(locate/click/wait在同一页面上下文串行) | ✓ |
47
88
  | `setDialogHandler` | `handler`:string | {ok} | 设置JS对话框处理 | 仅 ext |
48
- | `operateSequence` | `steps`:array | {ok,results} | 原子序列执行 | ✓ |
49
89
  | `evaluate` | `source`:string, `args`?:any | 由函数返回值决定 | 执行页面JS函数(返回其结果) | ✓ |
50
90
  | `setInputFiles` | `selector`:string, `files`:array, `timeout`?:number=10000 | {ok,selector,count} | 上传文件到file input | ✓ |
51
91
 
@@ -57,7 +97,7 @@
57
97
  | `goBack` | `timeout`?:number=15000 | {ok,url} | 后退一页 | ✓ |
58
98
  | `goForward` | `timeout`?:number=15000 | {ok,url} | 前进一页 | ✓ |
59
99
  | `reload` | `timeout`?:number=15000 | {ok,url} | 刷新当前页 | ✓ |
60
- | `status` | — | {ok,url,title,readyState,textLength} | 读当前页状态(url/title/readyState) | ✓ |
100
+ | `status` | — | {ok,url,title,readyState,textLength} | 读当前页状态(url/title/readyState/textLength) | ✓ |
61
101
 
62
102
  ### 等待
63
103