@pyrokine/mcp-chrome 3.0.0 → 3.0.1
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.
- package/README.md +119 -38
- package/README_zh.md +165 -110
- package/dist/core/browser-driver.d.ts +5 -4
- package/dist/core/browser-driver.d.ts.map +1 -1
- package/dist/core/browser-driver.js.map +1 -1
- package/dist/core/errors.d.ts +6 -4
- package/dist/core/errors.d.ts.map +1 -1
- package/dist/core/errors.js +14 -8
- package/dist/core/errors.js.map +1 -1
- package/dist/core/locator.d.ts +7 -0
- package/dist/core/locator.d.ts.map +1 -1
- package/dist/core/locator.js +48 -25
- package/dist/core/locator.js.map +1 -1
- package/dist/core/session.d.ts +6 -4
- package/dist/core/session.d.ts.map +1 -1
- package/dist/core/session.js +58 -23
- package/dist/core/session.js.map +1 -1
- package/dist/core/unified-session.d.ts +11 -8
- package/dist/core/unified-session.d.ts.map +1 -1
- package/dist/core/unified-session.js +71 -27
- package/dist/core/unified-session.js.map +1 -1
- package/dist/extension/bridge.d.ts +3 -3
- package/dist/extension/bridge.d.ts.map +1 -1
- package/dist/extension/bridge.js +50 -20
- package/dist/extension/bridge.js.map +1 -1
- package/dist/extension/http-server.d.ts.map +1 -1
- package/dist/extension/http-server.js +9 -0
- package/dist/extension/http-server.js.map +1 -1
- package/dist/tools/browse.d.ts.map +1 -1
- package/dist/tools/browse.js +10 -4
- package/dist/tools/browse.js.map +1 -1
- package/dist/tools/challenge.d.ts.map +1 -1
- package/dist/tools/challenge.js +12 -15
- package/dist/tools/challenge.js.map +1 -1
- package/dist/tools/evaluate.d.ts.map +1 -1
- package/dist/tools/evaluate.js +10 -0
- package/dist/tools/evaluate.js.map +1 -1
- package/dist/tools/extract.d.ts.map +1 -1
- package/dist/tools/extract.js +30 -22
- package/dist/tools/extract.js.map +1 -1
- package/dist/tools/input.d.ts.map +1 -1
- package/dist/tools/input.js +83 -57
- package/dist/tools/input.js.map +1 -1
- package/dist/tools/manage.d.ts.map +1 -1
- package/dist/tools/manage.js +16 -30
- package/dist/tools/manage.js.map +1 -1
- package/dist/tools/post-condition.d.ts.map +1 -1
- package/dist/tools/post-condition.js +23 -9
- package/dist/tools/post-condition.js.map +1 -1
- package/dist/tools/target-diagnostics.d.ts +9 -1
- package/dist/tools/target-diagnostics.d.ts.map +1 -1
- package/dist/tools/target-diagnostics.js +60 -17
- package/dist/tools/target-diagnostics.js.map +1 -1
- package/dist/tools/wait.d.ts.map +1 -1
- package/dist/tools/wait.js +19 -7
- package/dist/tools/wait.js.map +1 -1
- package/extension/dist/assets/{content.ts-loader-CnJuCGhl.js → content.ts-loader-DUWbDHRS.js} +1 -1
- package/extension/dist/assets/{content.ts-C4imZ6A9.js → content.ts-qe6IB5DK.js} +1 -1
- package/extension/dist/assets/{index.ts-GeHNZBml.js → index.ts-D7_LCUoV.js} +559 -212
- package/extension/dist/assets/{page-scripts-CMIY1zhd.js → page-scripts-D508WLkW.js} +50 -51
- package/extension/dist/assets/{popup.html-CgtWL6Py.js → popup.html-B-eVq48O.js} +6 -4
- package/extension/dist/manifest.json +4 -4
- package/extension/dist/service-worker-loader.js +1 -1
- package/extension/dist/src/popup/popup.html +1 -1
- package/package.json +12 -6
package/README_zh.md
CHANGED
|
@@ -33,6 +33,26 @@ Chrome 浏览器自动化 MCP Server,双模式架构: **Extension 模式**
|
|
|
33
33
|
|
|
34
34
|
本地零配置自动连接保持不变,刷新 Extension 或重启 MCP client 后不需要手动点击“连接”
|
|
35
35
|
|
|
36
|
+
## 请求范围与失败处理
|
|
37
|
+
|
|
38
|
+
一组输入事件在执行和恢复目标期间保持同一后端、同一页面,并发的 `browse(action="connect")` 等待该请求结束;CDP 请求带
|
|
39
|
+
`frame` 时,在定位或操作 Extension 页面前返回能力错误
|
|
40
|
+
|
|
41
|
+
Extension 通过所选 document 与原生 iframe owner 核对身份,同 URL iframe 重排后不按旧 DOM 索引执行
|
|
42
|
+
|
|
43
|
+
显式 `wait="networkidle"` 在导航前启用 Network 观测,等待请求完成后持续静默 500 ms;观测缺失或中断时返回错误,默认
|
|
44
|
+
`load` 路径不会为了网络空闲检查附加 debugger
|
|
45
|
+
|
|
46
|
+
CDP 网络日志在响应体传输失败时保留 HTTP 状态,每个请求只记录一次终态;临时选择其他 CDP 页面会保留各目标独立的日志
|
|
47
|
+
|
|
48
|
+
输入的 `timeout` 包含页面选择、准备和按键 RPC,最后一次响应超过期限时仍返回超时;执行结果无法确认时返回
|
|
49
|
+
`actionStatus="unknown"` 与 `retryable=false`,读取当前页面状态后再决定下一步
|
|
50
|
+
|
|
51
|
+
分组操作与页面解除受控按涉及的页面串行执行,并在持锁期间重新检查成员和操作权限;创建页面使用 `active`,`activate`
|
|
52
|
+
仅适用于 `movePage`
|
|
53
|
+
|
|
54
|
+
Popup 设置保存失败会显示错误,延迟返回的旧设置不会覆盖新设置;本地默认自动连接继续无需手动配对或点击连接
|
|
55
|
+
|
|
36
56
|
## 兼容客户端
|
|
37
57
|
|
|
38
58
|
| 客户端 | 状态 |
|
|
@@ -45,7 +65,7 @@ Chrome 浏览器自动化 MCP Server,双模式架构: **Extension 模式**
|
|
|
45
65
|
|
|
46
66
|
## 安装
|
|
47
67
|
|
|
48
|
-
需要 Node.js 20.19
|
|
68
|
+
需要 Node.js 20.19 或更新版本
|
|
49
69
|
|
|
50
70
|
### npm
|
|
51
71
|
|
|
@@ -56,7 +76,7 @@ npm root -g
|
|
|
56
76
|
```
|
|
57
77
|
|
|
58
78
|
Extension 模式需要打开 `chrome://extensions/`,启用开发者模式,点击“加载已解压的扩展程序”,选择
|
|
59
|
-
`<npm-root>/@pyrokine/mcp-chrome/extension/dist
|
|
79
|
+
`<npm-root>/@pyrokine/mcp-chrome/extension/dist`
|
|
60
80
|
|
|
61
81
|
### 从源码安装
|
|
62
82
|
|
|
@@ -70,7 +90,7 @@ npm --prefix extension run build
|
|
|
70
90
|
claude mcp add chrome -- node "$PWD/dist/index.js"
|
|
71
91
|
```
|
|
72
92
|
|
|
73
|
-
Extension 模式需要在 Chrome 中加载 `extension/dist
|
|
93
|
+
Extension 模式需要在 Chrome 中加载 `extension/dist`
|
|
74
94
|
|
|
75
95
|
### Windows CDP 启动
|
|
76
96
|
|
|
@@ -84,13 +104,13 @@ Chrome 自动查找 Windows App Paths、`PATH`、已安装的 Chrome channels、
|
|
|
84
104
|
```
|
|
85
105
|
|
|
86
106
|
随后调用
|
|
87
|
-
`browse(action="connect", port=9222)
|
|
107
|
+
`browse(action="connect", port=9222)`,脚本让 Chrome 进程保持前台运行,并报告退出码;使用独立 profile,避免请求被已有 Chrome 实例接管
|
|
88
108
|
|
|
89
109
|
## 快速开始
|
|
90
110
|
|
|
91
111
|
### 模式一:Extension 模式(推荐)
|
|
92
112
|
|
|
93
|
-
Extension 模式操控你现有的 Chrome——共享登录状态、Cookie
|
|
113
|
+
Extension 模式操控你现有的 Chrome——共享登录状态、Cookie 和浏览上下文
|
|
94
114
|
|
|
95
115
|
**第一步:安装 Chrome Extension**
|
|
96
116
|
|
|
@@ -127,8 +147,8 @@ Claude Desktop / 其他客户端:
|
|
|
127
147
|
Extension 通过 HTTP/WebSocket 自动连接 MCP Server(端口 19222-19299),点击工具栏图标可查看连接状态,
|
|
128
148
|
`browse(action="connect")` 和本地 `/api/info`
|
|
129
149
|
会返回当前活动 Extension 后台 bundle 的 hash,并与 server 附带的 bundle 比较, `bundleStatus="stale"`
|
|
130
|
-
表示 Chrome 仍在执行旧的已解压 Extension,需要在 `chrome://extensions/` 刷新该 Extension
|
|
131
|
-
`network_challenge_state` 时会回退为 tab 标题和 DOM 的 Challenge 检测,bundle identity
|
|
150
|
+
表示 Chrome 仍在执行旧的已解压 Extension,需要在 `chrome://extensions/` 刷新该 Extension,旧版 Extension 缺少
|
|
151
|
+
`network_challenge_state` 时会回退为 tab 标题和 DOM 的 Challenge 检测,bundle identity 不会关闭零配置自动连接
|
|
132
152
|
|
|
133
153
|
```
|
|
134
154
|
browse(action="list") // 列出所有 Tab
|
|
@@ -146,12 +166,12 @@ MCP_CHROME_PAIRING_TOKEN="your-token" node /path/to/mcp-chrome/dist/index.js
|
|
|
146
166
|
```
|
|
147
167
|
|
|
148
168
|
需要强制配对 token 时,在 server 设置 `MCP_CHROME_ALLOW_INSECURE_NO_TOKEN=0`,并在 Extension
|
|
149
|
-
popup 关闭“允许无 token
|
|
150
|
-
check、WebSocket 握手和已安排的重连,旧的无 token
|
|
169
|
+
popup 关闭“允许无 token 本地连接”,关闭后会立即取消进行中的 health
|
|
170
|
+
check、WebSocket 握手和已安排的重连,旧的无 token 连接尝试不会在策略更新后重新连入
|
|
151
171
|
|
|
152
172
|
### 模式二:CDP 模式(回退)
|
|
153
173
|
|
|
154
|
-
CDP 模式启动或连接独立的 Chrome 实例,适用于未安装 Extension
|
|
174
|
+
CDP 模式启动或连接独立的 Chrome 实例,适用于未安装 Extension 或需要无头/隔离的场景
|
|
155
175
|
|
|
156
176
|
```bash
|
|
157
177
|
# 启动带远程调试的 Chrome
|
|
@@ -163,9 +183,9 @@ browse(action="connect", port=9222)
|
|
|
163
183
|
browse(action="open", url="https://example.com")
|
|
164
184
|
```
|
|
165
185
|
|
|
166
|
-
> 已连接的 Extension 是所有工具的默认模式,Extension 不可用时才回退到 CDP
|
|
186
|
+
> 已连接的 Extension 是所有工具的默认模式,Extension 不可用时才回退到 CDP,`browse(action="connect", port=9222)`
|
|
167
187
|
> 会为后续工具显式选择 CDP;调用不带 port 的 `browse(action="connect")`
|
|
168
|
-
> 会回到 Extension
|
|
188
|
+
> 会回到 Extension,仅因回退而建立的 CDP 连接会在 Extension 重连后让出默认模式
|
|
169
189
|
|
|
170
190
|
## 可用工具(8 个)
|
|
171
191
|
|
|
@@ -185,16 +205,15 @@ browse(action="open", url="https://example.com")
|
|
|
185
205
|
|
|
186
206
|
Extension 特有:`list` 返回 flat `targets` 数组和树状 `windows`,每个 target 含 `managed`(Tab 是否由 MCP
|
|
187
207
|
Chrome 受控)、`isActive`(该窗口中 Chrome 的活动 Tab)、`windowId`、`index`、`pinned`、`incognito`、`status`(`loading`/`complete`),树状结构含
|
|
188
|
-
`windowCount`、`focusedWindowId`、`activeTargetId` 和每个窗口按顺序排列的 `tabs
|
|
208
|
+
`windowCount`、`focusedWindowId`、`activeTargetId` 和每个窗口按顺序排列的 `tabs`,`defaultTargetId`
|
|
189
209
|
是默认操作目标,CDP 不用选中的操作目标推断浏览器前台页面,`open`
|
|
190
210
|
自动创建 Tab 分组(cyan 色),`open`、`back`、`forward`、`refresh` 支持 `diagnostics=true`,返回动作期间新增的 console
|
|
191
|
-
warning/error 和失败网络请求摘要,也覆盖首次 `open`
|
|
211
|
+
warning/error 和失败网络请求摘要,也覆盖首次 `open` 自动创建页面的场景,两个 driver 的 `open` 和 `refresh` 都支持
|
|
192
212
|
`wait="load"`、`wait="domcontentloaded"` 和
|
|
193
|
-
`wait="networkidle"
|
|
213
|
+
`wait="networkidle"`,等待器会在命令前建立,并绑定命令产生的新主文档,上一导航的迟到生命周期事件不会提前完成等待,CDP模式的
|
|
194
214
|
`networkidle` 等待当前主 frame loader 的 `networkIdle`
|
|
195
215
|
事件;Extension 模式会等待当前文档完成、所有已跟踪响应 body 结束和 500
|
|
196
|
-
ms
|
|
197
|
-
`targetId`,且只关闭该页面,不会关闭整个 CDP 连接,
|
|
216
|
+
ms 静默窗口,请求跟踪发生丢失时返回超时,不会误报空闲,`close` 必须传 `targetId`,且只关闭该页面,不会关闭整个 CDP 连接
|
|
198
217
|
|
|
199
218
|
Extension 模式的 `back/forward`
|
|
200
219
|
优先使用浏览器原生历史,只有原生 API 明确报告无历史时才允许尝试页面脚本;受限 URL 和浏览器错误页不注入没有可用历史时返回
|
|
@@ -219,10 +238,10 @@ evaluate 在成功、动作失败、后置验证不匹配和输出失败时保
|
|
|
219
238
|
表示验证成功但源站尚未响应,不表示目标内容已加载
|
|
220
239
|
|
|
221
240
|
页面类工具在两种 backend 中都接受 `targetId`,旧版 `tabId`
|
|
222
|
-
|
|
223
|
-
必须显式指定 ID
|
|
241
|
+
仍可用;同时提供时两者必须一致,显式目标只作用于当前操作,结束后恢复原默认目标,`browse.close` 和 `manage.closePage`
|
|
242
|
+
必须显式指定 ID,页面动作成功或失败时,响应中的 `pageContext`
|
|
224
243
|
包含实际目标及来源(`explicit`、`default`、`created`、`reused`、`unconfirmed`)、前后 URL/revision、默认目标前后状态,以及 Extension 报告的浏览器活动目标;创建页面失败且未返回创建 ID 时标为
|
|
225
|
-
`unconfirmed
|
|
244
|
+
`unconfirmed`,CDP 的活动状态标为不可用,不把操作目标当作前台页面
|
|
226
245
|
|
|
227
246
|
旧 Extension 缺少 `page_snapshot` 时,无条件页面动作仍可使用实时页面列表中的 URL,`pageContext.before` 和 `after`
|
|
228
247
|
的快照返回 `revision=null`,并通过 `warning` 说明 revision 与原子条件不可用,传入 `expectedUrl` 或 `expectedRevision`
|
|
@@ -245,8 +264,8 @@ Chrome 已返回创建标识后,失败响应保留 `error.context.createdTarge
|
|
|
245
264
|
主动作结果或原错误保留,已完成的输入不会重放,也不会报为未执行;`browse attach` 与 `manage adoptPage`
|
|
246
265
|
继续持久选择默认目标,并发响应记录各自实际操作的页面
|
|
247
266
|
|
|
248
|
-
`browse.list` 返回各页面的 revision
|
|
249
|
-
epoch 与单页计数构成;Extension 跟踪主 frame 导航和 MCP 动作,CDP 跟踪已附加页面的导航,并保守计入发出的变更命令,包括 evaluate
|
|
267
|
+
`browse.list` 返回各页面的 revision 和元数据,revision 由 backend
|
|
268
|
+
epoch 与单页计数构成;Extension 跟踪主 frame 导航和 MCP 动作,CDP 跟踪已附加页面的导航,并保守计入发出的变更命令,包括 evaluate,网页自身的任意 DOM 更改不在跟踪范围内,条件动作前应重新获取 URL/revision,`browse`
|
|
250
269
|
导航/关闭、`input`、`evaluate` 及适用的 `manage` 页面动作接受 `expectedUrl` 和
|
|
251
270
|
`expectedRevision`;backend 检查不符时返回
|
|
252
271
|
`ACTION_PRECONDITION_FAILED`,不发送对应页面动作,复合动作在首个变更命令前检查,不在每个事件前重复检查;失败或超时后如已产生部分效果,revision 仍可能变化
|
|
@@ -259,6 +278,10 @@ epoch 与单页计数构成;Extension 跟踪主 frame 导航和 MCP 动作,C
|
|
|
259
278
|
撤销完整权限,保留页面、窗口归属和分组,清理 MCP 日志状态、debugger 和 console 采集资源;Chrome 阻止资源清理时返回
|
|
260
279
|
`warnings`,完整权限仍被撤销
|
|
261
280
|
|
|
281
|
+
受控权限在 Service Worker 重启后保留,重载 Extension 后,仍存活且原文档身份一致的受控页也会恢复权限,无需刷新页面或重新 adopt
|
|
282
|
+
文档身份不可取得的页面在重载 Extension 后需要显式 `adoptPage`;正常导航保留受控权限,`releasePage`
|
|
283
|
+
撤销的权限在重启或重载后仍保持撤销,仅复用 tab ID 不会授权另一文档
|
|
284
|
+
|
|
262
285
|
受控页在 Service Worker 重启后可继续使用本 Extension 已有的调试连接,其他调试器占用仍返回 `DEBUGGER_BLOCKED`
|
|
263
286
|
|
|
264
287
|
通过 `manage(action="grantReadAccess", targetId=...)` 授予普通读取权限,用 `revokeReadAccess`
|
|
@@ -276,37 +299,38 @@ Worker 重启后仍可读取;导航、关闭页面或断开连接后授权失
|
|
|
276
299
|
### 访问验证
|
|
277
300
|
|
|
278
301
|
`open`、`back`、`forward`、`refresh`、`input` 和 `evaluate` 之后,MCP Chrome 会等待 Cloudflare JS Challenge 或 Turnstile
|
|
279
|
-
checkbox
|
|
280
|
-
inspect 走 isolated world
|
|
302
|
+
checkbox,Extension 模式下,导航先不启用 debugger 日志采集;Challenge 标题持续期间,前八秒只被动读取真实 tab 标题,interstitial 持续存在时,才检查可见 Turnstile 控件,找到后才点击,Extension
|
|
303
|
+
inspect 走 isolated world,Challenge 标题在检查前卸掉 debugger,普通页面检查保留已有调试连接,发现可见验证控件或仍需验证的正文后才卸除;同页测试按钮走页面点击,出现 Cloudflare Turnstile
|
|
281
304
|
iframe 时,把 inspect 的 CSS 坐标换成屏幕坐标,系统鼠标沿路径移动、悬停后再按下抬起:Linux 用 `xdotool` 读取活动 Chrome
|
|
282
305
|
client 窗口几何,用 `xprop` 读取 GTK frame
|
|
283
306
|
extents,窗口标题必须对应该测试页缺少工具、窗口数据无效或与页面视口不符时停止点击,不用 Chrome `screenX` 或
|
|
284
307
|
`outerHeight - innerHeight` 猜测内容原点;macOS 用 `cliclick` 或 System Events;Windows 用 PowerShell
|
|
285
|
-
`mouse_event
|
|
286
|
-
Turnstile 卡片左侧 checkbox,宿主 wrapper
|
|
308
|
+
`mouse_event`,widget 点 compact
|
|
309
|
+
Turnstile 卡片左侧 checkbox,宿主 wrapper 比卡片宽时也只点左侧卡片,不点文案,DOM 里已有 Cloudflare
|
|
287
310
|
iframe 时,即使 iframe 尺寸为 0,也走系统鼠标,不改用页面点击,后续宿主页 `Verify you are human` / `请验证您是真人`
|
|
288
|
-
|
|
311
|
+
按钮同样走系统鼠标,系统鼠标只在受控测试页已经是已聚焦窗口的活动 tab 时使用,混合窗口不会调用 `focusWindow`
|
|
289
312
|
|
|
290
|
-
系统点击前会卸掉 debugger
|
|
313
|
+
系统点击前会卸掉 debugger,再读一次视口,缺少系统鼠标工具或窗口未聚焦时返回可见错误,不会静默改用 CDP 点击
|
|
291
314
|
|
|
292
|
-
widget 要连续两次 inspect 到同一坐标才点,不以普通元素的尺寸认定 widget
|
|
315
|
+
widget 要连续两次 inspect 到同一坐标才点,不以普通元素的尺寸认定 widget;系统鼠标从远处过来时从控件附近起步,同一类 checkbox 或 compact
|
|
293
316
|
widget 在同一次等待里最多点一次;Cloudflare 随后换成可见的 `Verify you are human` 或 `请验证您是真人`
|
|
294
|
-
按钮时,inspect 判成 `verify`
|
|
295
|
-
`diagnostics=false`,因为 diagnostics 会启用 debugger 的 console 和 network
|
|
317
|
+
按钮时,inspect 判成 `verify` 后再点一次,访问受 Cloudflare 保护的页面默认保持
|
|
318
|
+
`diagnostics=false`,因为 diagnostics 会启用 debugger 的 console 和 network 采集
|
|
319
|
+
|
|
320
|
+
检测覆盖 `Just a moment...`、`请稍候…` 等标题、可见的 Challenge DOM、正文标记和 `Verify you are human` / `请验证您是真人`
|
|
321
|
+
控件,包括精确匹配这两种文案的可见 `button` 元素;普通标题也会进行有界的可见内容检查,可见的“正在进行安全验证”会阻止业务动作,隐藏标记不计入判定,无验证标记的页面不会固定等待八秒
|
|
296
322
|
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
`
|
|
300
|
-
solver、不会自动重试导航,也不会导出 `cf_clearance`
|
|
301
|
-
的值。CDP 超时不代表网站在用户真实 Chrome 中无法通过,排查网站前先检查返回的 `mode`。
|
|
323
|
+
没有 Cloudflare iframe 时,同页按钮使用页面点击,CDP 用 `Target.getTargetInfo` 读取实时标题
|
|
324
|
+
页面恢复后,仅残留 Cloudflare iframe 或旧 pending header 不算等待中,也不触发滚动或点击,缓存标题不参与判定
|
|
325
|
+
不会调用 CAPTCHA solver、自动重试导航或导出 `cf_clearance` 的值,CDP 超时不代表网站在用户真实 Chrome 中无法通过,排查网站前先检查返回的 `mode`
|
|
302
326
|
|
|
303
327
|
过盾成功时返回 `challengeResolved=true`、`challengeKind`、`waitedMs`、`clickedTurnstile` 和 `clearanceCookiePresent`
|
|
304
|
-
(只表示 cookie
|
|
305
|
-
`originResponsePending=true
|
|
306
|
-
的标题)不算过盾,可见 Turnstile
|
|
307
|
-
且 `retryable=true`,并带 `clickedTurnstile` 和实际观察到的 `challengeKind`(点过 Turnstile 时不会报成 `js
|
|
308
|
-
denied 返回 `CHALLENGE_DENIED
|
|
309
|
-
Mode 和 IP 声誉检查无法靠等待或点击 checkbox
|
|
328
|
+
(只表示 cookie 名是否存在),页面可见文案显示验证成功、正在等待源站时,响应还会含
|
|
329
|
+
`originResponsePending=true`,表示已过盾但目标页面尚未加载,隐藏的成功文案(例如 `display:none`
|
|
330
|
+
的标题)不算过盾,可见 Turnstile 勾选框仍视为等待中,Challenge 成功和失败响应都含 `mode`,超时返回 `CHALLENGE_TIMEOUT`
|
|
331
|
+
且 `retryable=true`,并带 `clickedTurnstile` 和实际观察到的 `challengeKind`(点过 Turnstile 时不会报成 `js`),Access
|
|
332
|
+
denied 返回 `CHALLENGE_DENIED`,交互式验证码、Bot Fight
|
|
333
|
+
Mode 和 IP 声誉检查无法靠等待或点击 checkbox 完成,之后的正常主文档响应才会清掉 header 标记,普通 iframe 文档响应和清空网络日志都不会清掉它
|
|
310
334
|
|
|
311
335
|
### input - 键鼠输入
|
|
312
336
|
|
|
@@ -329,13 +353,17 @@ Mode 和 IP 声誉检查无法靠等待或点击 checkbox 完成。之后的正
|
|
|
329
353
|
| `editorInsert` | 在当前编辑器选区插入文本 |
|
|
330
354
|
| `editorCommand` | 执行 `bold`、`insertOrderedList` 等浏览器编辑命令 |
|
|
331
355
|
|
|
332
|
-
`events`
|
|
356
|
+
`events` 至少需要一个事件,参数:`humanize` 启用贝塞尔曲线移动和随机延迟,`diagnostics=true` 返回动作后新增 console
|
|
333
357
|
warning/error 和失败网络请求, `postCondition`
|
|
334
358
|
会在事件发送后等待页面状态,便于区分输入事件已发送和页面业务状态已完成,`postCondition.timeout` 默认 3000 ms、最大 60000
|
|
335
|
-
ms,`postCondition.interval` 默认 100 ms、范围 50-5000 ms
|
|
336
|
-
function 或 Promise 表达式;函数会被调用,最终 Promise 值会被等待后再判定,抛错或 reject
|
|
359
|
+
ms,`postCondition.interval` 默认 100 ms、范围 50-5000 ms,`postCondition.script` 可传表达式、函数、async
|
|
360
|
+
function 或 Promise 表达式;函数会被调用,最终 Promise 值会被等待后再判定,抛错或 reject 会让检查失败,`targetId`(或旧版
|
|
337
361
|
`tabId`)在两种 backend 中指定页面;`frame`
|
|
338
|
-
在 Extension 模式中指定 iframe(CSS 选择器或索引),传入任一作用域时,动作、诊断和 post-condition 使用该目标作用域选定的同一个 backend
|
|
362
|
+
在 Extension 模式中指定 iframe(CSS 选择器或索引),传入任一作用域时,动作、诊断和 post-condition 使用该目标作用域选定的同一个 backend
|
|
363
|
+
|
|
364
|
+
验证期间 frame、执行 context 或 debugger 不可用时返回 `verificationStatus="unavailable"`,脚本抛错或 reject 返回
|
|
365
|
+
`error`,即使错误文案相同也按脚本异常处理;已完成的主动作保留 `actionStatus="completed"` 和
|
|
366
|
+
`failureStage="verification"`,验证不会重新执行主动作
|
|
339
367
|
|
|
340
368
|
键盘 `type` 的 `timeout` 包含 Challenge 等待、焦点准备、字符输入和 `delay`/`humanize` 延迟,Extension
|
|
341
369
|
precise/stealth 与 CDP 使用本次剩余预算,显式预算如 `timeout=45000`
|
|
@@ -347,6 +375,9 @@ precise/stealth 与 CDP 使用本次剩余预算,显式预算如 `timeout=4500
|
|
|
347
375
|
|
|
348
376
|
命令聚焦、文本选择和替换共用事件剩余预算,到期后停止后续动作;Shift 按下后仍尝试释放,释放失败不隐藏原动作错误,CDP 分步触摸移动到期后也停止后续触摸点与事件
|
|
349
377
|
|
|
378
|
+
Stealth 左键派发 `click`,中键派发 `auxclick`,右键派发 `contextmenu`,每次按下和释放携带对应的点击
|
|
379
|
+
`detail`;只有左键多击在 `detail=2` 时派发 `dblclick`,独立 stealth `mouseup` 使用相同的按键映射
|
|
380
|
+
|
|
350
381
|
Stealth 的 `delay` 只作用于字符之间,首字符不额外等待;后台页面受定时器节流时,后续间隔会延长,本次预算仍限制后续输入
|
|
351
382
|
|
|
352
383
|
Extension precise 与 CDP 的键盘输入使用当前光标和选区,提供 `target`
|
|
@@ -365,13 +396,19 @@ Extension precise 与 CDP 的键盘输入使用当前光标和选区,提供 `t
|
|
|
365
396
|
摘要,焦点不可取得时返回 null,DOM 查询失败时还返回 `diagnosticError` 选区相关错误另含编辑器与选区状态,password
|
|
366
397
|
input 的 value 不进入失败诊断,失败响应也会脱敏 input 事件传入的 `find` 和替换 `text`,`select` 和 `replace` 的事件级
|
|
367
398
|
`nth` 表示文本第 N 次出现,嵌套的 `target.nth` 表示第 N 个目标元素,两者都从 0 开始并可同时使用,CDP 模式的 locator
|
|
368
|
-
target 不依赖 Extension refId
|
|
399
|
+
target 不依赖 Extension refId
|
|
400
|
+
|
|
401
|
+
两种 backend 的 `input`、`extract`、`wait` 定位失败都在请求预算内返回失败 locator、从 0 开始的 `nth`、URL、tab/frame 作用域、managed 状态、最后定位状态及最多 10 个候选摘要
|
|
402
|
+
`matchCount` 表示实际观察到的匹配总量,不受候选摘要上限限制,nth 越界不会把 15 个匹配写成 0;匹配数或 managed 状态无法确认时返回 null,诊断不可用时返回 `diagnosticError`
|
|
403
|
+
CDP 查找失败保留 `ELEMENT_NOT_FOUND`,元素等待保留 `TIMEOUT`,原 URL 和日志字段继续保留,诊断在退出失败目标作用域前读取,不重放输入
|
|
369
404
|
|
|
370
405
|
**`keydown` 专属参数**:
|
|
371
406
|
|
|
372
407
|
- `commands`:触发浏览器原生编辑命令(如 `["selectAll"]`、`["copy"]`、`["paste"]`、`["cut"]`、`["undo"]`、`["redo"]`
|
|
373
408
|
),成功表示浏览器已接受命令分发,页面结果需用 `postCondition` 或 `extract`
|
|
374
|
-
验证,仅 precise 模式可用,stealth 模式下抛错(CDP commands API 没有 JS
|
|
409
|
+
验证,仅 precise 模式可用,stealth 模式下抛错(CDP commands API 没有 JS 事件等价物)命令分发前只聚焦元素或坐标
|
|
410
|
+
`target`,不派发鼠标事件,坐标聚焦不会改变 checkbox、跟随链接或调用 click 监听器;目标缺失或无法聚焦时,在分发命令前返回错误,Extension 的
|
|
411
|
+
`frame` 坐标相对于所选 iframe
|
|
375
412
|
- 连续 `keydown` 同一 key 自动切换为 `rawKeyDown` + `autoRepeat`,模拟长按重复(与 Puppeteer 一致)
|
|
376
413
|
|
|
377
414
|
### extract - 内容提取
|
|
@@ -392,10 +429,10 @@ target 不依赖 Extension refId,
|
|
|
392
429
|
|
|
393
430
|
参数:`output` 将结果保存到文件(`images=data` 时为输出目录),`images`(`info`/`data`)提取 HTML 中的图片元信息或数据,
|
|
394
431
|
`frameHtml` 在 `frame` 路由后提取当前 iframe 文档,截图支持 `clip` 坐标区域、`compareWith` PNG 基准对比和 `diffOutput`
|
|
395
|
-
差异图输出,`diffOutput` 必须同时传 `compareWith
|
|
432
|
+
差异图输出,`diffOutput` 必须同时传 `compareWith`,指定 `target` 的截图未匹配、`nth`
|
|
396
433
|
越界或尺寸为零时返回目标错误,不会静默返回视口截图,截图响应包含
|
|
397
434
|
`metadata.format`、`width`、`height`、`dimensionSource`、`byteSize`、`fullPage`、`scale`、`clip` 和
|
|
398
|
-
`capabilities
|
|
435
|
+
`capabilities`,截图在执行前限制单边 16,384 像素、总计 12,000,000 像素、预计 RGBA 内存 48 MiB 和编码数据 25
|
|
399
436
|
MiB;基准 PNG 在读取前检查文件大小,对比在解码前限制单个 PNG 25
|
|
400
437
|
MiB 和 12,000,000 像素,解压时按已校验尺寸限制输出,并要求 scanline 长度精确匹配;损坏或异常膨胀的 PNG 会被拒绝,较大截图应使用
|
|
401
438
|
`clip` 或 `scale` 缩小,截图与 diagnosticBundle 在 Extension 和 CDP 模式中都返回
|
|
@@ -409,14 +446,16 @@ selector 和所属元素 rect,帧树顺序与 ID 保持不变;元信息还
|
|
|
409
446
|
`unknown`,其他 Server 不继承这些备注,不能据此判断跨会话归属或取得权限;如果其他 debugger 占用 precise 截图路径,可视区域 fallback 会返回
|
|
410
447
|
`degraded`、`fallback` 和 `limitations`;fallback 不支持的参数返回结构化
|
|
411
448
|
`SCREENSHOT_FALLBACK_UNSUPPORTED`,`targetId`(或旧版 `tabId`)在两种 backend 中指定页面,`frame`
|
|
412
|
-
仅在 Extension 模式中指定 iframe
|
|
449
|
+
仅在 Extension 模式中指定 iframe
|
|
413
450
|
|
|
414
451
|
**`attribute` 特殊前缀**:`computed:<属性名>` 返回 computed CSS 样式值(如 `computed:color`、`computed:font-size`),
|
|
415
|
-
`computed:*` 返回全部计算样式(300+ 属性,建议配合 `output`
|
|
452
|
+
`computed:*` 返回全部计算样式(300+ 属性,建议配合 `output` 写文件)
|
|
416
453
|
|
|
417
|
-
**`state` 专属参数**:`depth`
|
|
418
|
-
`accessibility`(默认,从无障碍树派生)或 `domsnapshot
|
|
419
|
-
|
|
454
|
+
**`state` 专属参数**:`depth` 控制无障碍树的 DOM 遍历深度(默认 15),减小可降低大页面的返回数据量 `mode` 选择
|
|
455
|
+
`accessibility`(默认,从无障碍树派生)或 `domsnapshot`(原始
|
|
456
|
+
`DOMSnapshot.captureSnapshot`,支持 CDP 或受控 Extension 页面)DOMSnapshot 返回整页快照,传入 `target`、`frame` 或
|
|
457
|
+
`depth` 限定时明确拒绝,普通只读授权不包含 debugger 权限无关 iframe 探测失败时,metadata 通过 `unavailableFrames`
|
|
458
|
+
和对应帧的 `unavailableReason` 标明原因,能够唯一验证的所选 iframe 继续可用
|
|
420
459
|
|
|
421
460
|
### wait - 等待条件
|
|
422
461
|
|
|
@@ -427,18 +466,18 @@ style 的扁平节点数组,便于二次处理),
|
|
|
427
466
|
| `time` | 固定延迟 |
|
|
428
467
|
| `idle` | 等待 DOM 或网络静默期 |
|
|
429
468
|
|
|
430
|
-
参数:`targetId`(或旧版 `tabId`)在两种 backend 中指定页面,`frame` 在 Extension 模式中指定 iframe
|
|
469
|
+
参数:`targetId`(或旧版 `tabId`)在两种 backend 中指定页面,`frame` 在 Extension 模式中指定 iframe
|
|
431
470
|
|
|
432
471
|
CDP 模式的 `visible` 要求 DOM 矩形宽高非零,且 CSS 不隐藏元素(`display:none` 或 `visibility:hidden/collapse`) `hidden`
|
|
433
472
|
接受这些隐藏状态或元素不存在,`attached` 和 `detached` 只检查元素是否存在
|
|
434
473
|
|
|
435
474
|
**`idle` 说明**:Extension 模式会在 `readyState === 'complete'` 后注入 `MutationObserver`,等待 `ms`
|
|
436
|
-
毫秒内无 DOM 变更;CDP
|
|
437
|
-
`idlePeriodMs`,Extension 响应还返回 `domStable
|
|
475
|
+
毫秒内无 DOM 变更;CDP 模式等待网络静默,两种模式的默认 `ms` 都是 500ms,响应返回 `idleKind` 和
|
|
476
|
+
`idlePeriodMs`,Extension 响应还返回 `domStable`
|
|
438
477
|
|
|
439
478
|
### evaluate - JavaScript 执行
|
|
440
479
|
|
|
441
|
-
在页面上下文执行 JavaScript
|
|
480
|
+
在页面上下文执行 JavaScript
|
|
442
481
|
|
|
443
482
|
| 参数 | 描述 |
|
|
444
483
|
| -------------------- | ------------------------------------------------------- |
|
|
@@ -456,7 +495,7 @@ CDP 模式的 `visible` 要求 DOM 矩形宽高非零,且 CSS 不隐藏元素
|
|
|
456
495
|
|
|
457
496
|
`script` 和 `scriptFile` 至少提供一个,互斥使用,相对 `scriptFile` 和 `output` 路径默认写到 `mcp-chrome`
|
|
458
497
|
管理的系统临时目录,需要把文件留在当前工作目录时,用 `cwd:relative/path` 显式指定,相对路径会拒绝
|
|
459
|
-
`..`,Windows 下也会拒绝 `:`,避免落到 NTFS alternate data stream,`output` 对字符串写原始文本,对其他类型写 JSON
|
|
498
|
+
`..`,Windows 下也会拒绝 `:`,避免落到 NTFS alternate data stream,`output` 对字符串写原始文本,对其他类型写 JSON
|
|
460
499
|
|
|
461
500
|
结果超过 100KB 时自动写入文件到受控的系统临时目录,返回文件路径和大小,返回 DOM 节点、`NodeList` 或 `HTMLCollection`
|
|
462
501
|
时返回 `NON_SERIALIZABLE_EVALUATE_RESULT`,并提示改为返回 `textContent`、`outerHTML`
|
|
@@ -465,14 +504,14 @@ CDP 模式的 `visible` 要求 DOM 矩形宽高非零,且 CSS 不隐藏元素
|
|
|
465
504
|
`postCondition` 检查与主动作使用相同 evaluate mode,`postCondition` 不传时, `success=true`
|
|
466
505
|
只表示脚本完成执行并返回;传入后如果超时仍不匹配,返回 `POST_CONDITION_FAILED` 和最后一次检查结果,iframe
|
|
467
506
|
precise 执行默认不在 execution context 失效后重放脚本,只有脚本无副作用时才应传
|
|
468
|
-
`staleContextRetry="readOnly"`,Extension 会在剩余 timeout 内重新解析 context
|
|
507
|
+
`staleContextRetry="readOnly"`,Extension 会在剩余 timeout 内重新解析 context,并最多重放一次,重试解析期间 Chrome 仍返回已移除的 document 时,会在同一预算内等待当前 document,不增加脚本执行次数;权限拒绝立即结束,`Runtime.evaluate`
|
|
469
508
|
发出后发生 stale context 时返回
|
|
470
|
-
`actionExecuted=true`、`actionStatus="unknown"
|
|
509
|
+
`actionExecuted=true`、`actionStatus="unknown"`,因为脚本可能已经产生部分副作用,但无法取得最终结果
|
|
471
510
|
|
|
472
511
|
Extension precise 主 frame 的对象结果,显式指定 `output` 时字符预算为 16
|
|
473
|
-
Mi(16777216),未指定时保留 1000000
|
|
512
|
+
Mi(16777216),未指定时保留 1000000,自动保存仍受该上限约束,两条路径均保留深度 8、节点 2000 和不可序列化结果拒绝,字符预算按 UTF-16
|
|
474
513
|
code units 计,不等于输出文件的 UTF-8 字节数;`tmp:`
|
|
475
|
-
|
|
514
|
+
文件还受临时输出配额约束,超限返回当前上限,并保留脚本已完成、输出失败的状态,不重放脚本
|
|
476
515
|
|
|
477
516
|
### manage - 页面与环境管理
|
|
478
517
|
|
|
@@ -490,7 +529,7 @@ code units 计,不等于输出文件的 UTF-8 字节数;`tmp:`
|
|
|
490
529
|
| `reorderPage` | 调整受控 Tab 在当前窗口内的顺序 |
|
|
491
530
|
| `pinPage` | 固定受控 Tab |
|
|
492
531
|
| `unpinPage` | 取消固定受控 Tab |
|
|
493
|
-
| `activatePage` |
|
|
532
|
+
| `activatePage` | 激活显式页面,Extension 要求目标 Tab 受控 |
|
|
494
533
|
| `focusWindow` | 聚焦显式指定的窗口 |
|
|
495
534
|
| `resizeWindow` | 调整显式指定窗口的尺寸或状态 |
|
|
496
535
|
| `newWindow` | 新建受控窗口 |
|
|
@@ -508,15 +547,22 @@ code units 计,不等于输出文件的 UTF-8 字节数;`tmp:`
|
|
|
508
547
|
| `stealth` | 注入反检测脚本 |
|
|
509
548
|
| `cdp` | 发送原始 CDP 命令(高级,如 `Runtime.evaluate`) |
|
|
510
549
|
|
|
511
|
-
原生 tab/window/group
|
|
512
|
-
明确指定目标,返回 `affected.before/after`,分组结果还返回
|
|
513
|
-
|
|
514
|
-
|
|
515
|
-
|
|
550
|
+
原生 tab/window/group 配置使用 Extension 模式,`activatePage` 同时支持 CDP,操作已有对象时用
|
|
551
|
+
`targetId`、`targetIds`、`windowId` 或 `groupId` 明确指定目标,返回 `affected.before/after`,分组结果还返回
|
|
552
|
+
`tabsBefore/tabsAfter`,`ungroupPages`
|
|
553
|
+
由 Chrome 删除空组,不撤销成员的受控权限窗口显示操作和分组名称、颜色、折叠更新按显式 `windowId` 或 `groupId`
|
|
554
|
+
执行,允许包含非托管成员,成员页面权限保持不变整组移动和关闭整窗继续要求全部受影响成员受控,加入或解除指定页面分组只检查指定页面,无关成员变化不阻止有效选择默认创建页面继续复用有效的缓存 MCP 窗口,混入非托管 tab 不触发新建窗口 Extension 模式不支持
|
|
555
|
+
`clearCache`,会返回 `UNSUPPORTED_MODE` 且不清除任何内容;清 Cookie 请用带 `url` 或 `domain` 过滤的
|
|
556
|
+
`cookies(action="clear")`,清 storage 或 cache 请改用 CDP 模式,`focusWindow`
|
|
516
557
|
只有在观测到目标窗口已聚焦后才返回成功,否则返回 `WINDOW_FOCUS_NOT_OBSERVED`,`closeWindow`
|
|
517
|
-
遇到混有非托管 tab 的窗口会返回 `WINDOW_HAS_UNMANAGED_TABS
|
|
558
|
+
遇到混有非托管 tab 的窗口会返回 `WINDOW_HAS_UNMANAGED_TABS`,持久的 `adoptPage`、`releasePage`
|
|
518
559
|
目标变更与指定 tab 的操作串行执行,并发多事件 input 会始终留在指定 tab,持久目标变更会在该操作结束后生效
|
|
519
560
|
|
|
561
|
+
CDP 的 `activatePage` 保留默认操作目标,只返回该 backend 能实际读取的字段,不构造 `active`
|
|
562
|
+
值或系统窗口焦点状态 Extension 的 `viewport`、`userAgent`、`emulate`、原始 `cdp` 和 precise `evaluate` 支持受控
|
|
563
|
+
`about:blank` 页面,Chrome 内部页和 Extension 页继续受原生访问限制不带 `device` 的 `manage(action="emulate")`
|
|
564
|
+
直接查询本地设备目录,无需有效页面,携带页面条件时明确拒绝;实际设置设备继续校验目标页面和条件
|
|
565
|
+
|
|
520
566
|
| 动作 | 原生参数 | 行为 |
|
|
521
567
|
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
|
|
522
568
|
| `newPage` | `url`、`windowId`、`index`、`active`、`pinned`、`openerTabId`、`groupId`、`timeout` | `active` 默认 false,`groupId=-1` 不分组,显式位置不受默认显示分组改变 |
|
|
@@ -532,11 +578,14 @@ window ID 不改变此规则 Extension 模式不支持 `clearCache`,会返回
|
|
|
532
578
|
和 bounds 时,状态转换完成后才应用一次几何参数,OS 调整后的几何按实际值返回有界等待内仍未观测到稳定状态时,`WINDOW_UPDATE_NOT_OBSERVED`
|
|
533
579
|
返回部分执行状态及最后观测的窗口信息,再次更新前用 `browse list` 检查实际状态
|
|
534
580
|
|
|
535
|
-
`browse list` 默认 `details="summary"`,返回页面标识、URL/标题、位置、managed/revision
|
|
536
|
-
获取选中、静音、自动丢弃、来源 tab ID 和可用原生只读属性,false
|
|
537
|
-
筛选页面及所属窗口、分组;`totalTargetCount`、`totalWindowCount` 和 `totalTabCount`
|
|
538
|
-
`targetIds` 引用页面,不重复完整对象;favicon data URL 不内联,完整结果用 `favIconInline=true`
|
|
539
|
-
|
|
581
|
+
`browse list` 默认 `details="summary"`,返回页面标识、URL/标题、位置、managed/revision 和元数据;传 `details="full"`
|
|
582
|
+
获取选中、静音、自动丢弃、来源 tab ID 和可用原生只读属性,false 值保留,`targetIds` 与 `managedOnly=true`
|
|
583
|
+
筛选页面及所属窗口、分组;`totalTargetCount`、`totalWindowCount` 和 `totalTabCount` 区分总量与选中数量
|
|
584
|
+
窗口通过 `targetIds` 引用页面,不重复完整对象;favicon data URL 不内联,完整结果用 `favIconInline=true` 标明存在
|
|
585
|
+
分组保留名称、颜色、折叠/共享、窗口、首个成员位置和成员 ID,颜色只属于分组,只读属性只回显,不作为写入参数,列表操作不读取页面正文,不导航或改变焦点
|
|
586
|
+
|
|
587
|
+
旧 Extension 只返回分组摘要、未提供成员数组时,按同次响应的窗口和 tab 归属恢复组成员及首个成员位置,summary/full 和筛选继续可用,无需额外 RPC
|
|
588
|
+
完全没有分组信息时,响应省略 `groups`,并用 warning 说明分组信息不可用;明确提供的 `groups: []` 表示没有分组,只提供一个成员数组等畸形分组数据返回错误
|
|
540
589
|
|
|
541
590
|
页面和分组移动接受
|
|
542
591
|
`index=-1`,新建页的 index 非负,来源 tab 与显式分组、窗口必须位于同一窗口,固定页不能在分组中创建窗口状态与位置/尺寸的冲突、动作不支持的字段在修改前拒绝,CDP 明确拒绝不支持的 Chrome
|
|
@@ -561,17 +610,17 @@ UI 配置,不静默忽略 `newWindow` 的 `url` 与 `urls` 是两种互斥输
|
|
|
561
610
|
| `network` | 网络请求日志(支持 URL 过滤) |
|
|
562
611
|
|
|
563
612
|
参数:`output` 将结果保存到文件,console 日志统一返回公开级别 `error`、`warning`、`info`、`debug`,浏览器原始的 `warn`、
|
|
564
|
-
`log`
|
|
565
|
-
console 日志会保留 hook
|
|
566
|
-
wrapper 的 console 方法会恢复,页面之后安装的 wrapper
|
|
613
|
+
`log` 等级会在过滤和返回前转换,清空 fallback
|
|
614
|
+
console 日志会保留 hook,debugger 采集恢复后,fallback 采集会停用;仍指向 MCP
|
|
615
|
+
wrapper 的 console 方法会恢复,页面之后安装的 wrapper 保持不变,network 日志在 `loadingFinished` 或 `loadingFailed`
|
|
567
616
|
时才完成记录,不会在收到 headers 时提前结束,因此 body 失败会同时保留 HTTP status 和
|
|
568
|
-
`errorText`,传输中的 body 也会继续计入 `networkidle
|
|
617
|
+
`errorText`,传输中的 body 也会继续计入 `networkidle`,日志尽量返回 `method`、
|
|
569
618
|
`url`、`status`、`timestamp`、`duration`,URL
|
|
570
619
|
query 中常见的认证、签名、密码和 token 参数会在内联响应、diagnostics 和 显式 `output` 文件中替换为 `[REDACTED]`,并返回
|
|
571
620
|
`urlRedacted`、`urlOriginalLength` 和
|
|
572
621
|
`redactedQueryParameters`,内联 network 结果会把脱敏后的单条 URL 限制为 2048 字符,截断时返回 `urlLength` 和
|
|
573
622
|
`urlTruncated: true`,`urlPattern` 支持 `*` 匹配任意长度字符、`?` 匹配单个字符,`tabId`
|
|
574
|
-
指定目标 Tab(Extension 模式),`frame`
|
|
623
|
+
指定目标 Tab(Extension 模式),`frame` 不适用于日志
|
|
575
624
|
|
|
576
625
|
Extension debugger 不可用时,network 每次读取都会刷新 performance 记录并标记
|
|
577
626
|
`source="performance"`;状态使用浏览器提供的 `responseStatus`,无法取得时为
|
|
@@ -587,7 +636,7 @@ Extension debugger 不可用时,network 每次读取都会刷新 performance
|
|
|
587
636
|
| `delete` | 删除 Cookie |
|
|
588
637
|
| `clear` | 在 URL 或域名范围内删除 Cookie,可用 `name` 进一步过滤 |
|
|
589
638
|
|
|
590
|
-
**说明**:`clear` 必须指定 `url` 或 `domain
|
|
639
|
+
**说明**:`clear` 必须指定 `url` 或 `domain`,`name` 只能在该范围内进一步过滤,避免误删其他站点的同名 Cookie,返回的
|
|
591
640
|
`count` 只统计 Chrome 确认已删除的 Cookie;列出后、删除前已消失的 Cookie 不计数
|
|
592
641
|
|
|
593
642
|
## Target:统一元素定位器
|
|
@@ -702,20 +751,20 @@ extract(type="html", images="data", output="tmp:page")
|
|
|
702
751
|
extract(type="html", target={ css: ".card" }, images="data")
|
|
703
752
|
```
|
|
704
753
|
|
|
705
|
-
`tmp:` 路径属于当前 server
|
|
706
|
-
MiB;启动时只清理超过 24
|
|
707
|
-
清理条件,`cwd:`
|
|
708
|
-
`cwd
|
|
754
|
+
`tmp:` 路径属于当前 server 会话,临时输出整个会话最多 256 项、128
|
|
755
|
+
MiB;启动时只清理超过 24 小时且所属进程已退出的带归属标记目录,成功写入 `tmp:` 文件或目录的响应会返回 `retention`
|
|
756
|
+
清理条件,`cwd:` 响应不带此字段,重启后仍需通过 MCP 访问的文件使用
|
|
757
|
+
`cwd:`,输出路径拒绝 Windows 保留设备名、ADS、非法字符以及末尾空格或点号;Windows 上写入敏感内容前须验证私有 DACL
|
|
709
758
|
|
|
710
759
|
路径语法错误返回 `INVALID_ARGUMENT`,允许 `.` 组件,继续拒绝 `..` 组件根目录外的路径及链接越界返回
|
|
711
760
|
`PATH_NOT_ALLOWED`,两类错误均在 `error.context.cwd` 返回 server 的实际工作目录,范围拒绝另返回 `allowedRoots` 使用
|
|
712
761
|
`cwd:` 指定相对于该目录的路径,或使用 `tmp:` 保存会话输出,`scriptFile` 与 `compareWith` 遵循相同校验
|
|
713
762
|
|
|
714
763
|
配额拒绝返回 `TEMP_OUTPUT_QUOTA_EXCEEDED`,`error.context` 包含 `limits`、`usage`、`remaining`、`requested` 和
|
|
715
|
-
`projected
|
|
716
|
-
为 null
|
|
717
|
-
`actionExecuted=true`、`actionStatus=completed`、`failureStage=output`、`retryable=false
|
|
718
|
-
`cwd:`
|
|
764
|
+
`projected`, `usage.complete=false` 时,占用只为已观察下界,`remaining`/`projected`
|
|
765
|
+
为 null;已有输出保留,evaluate 的输出失败保留
|
|
766
|
+
`actionExecuted=true`、`actionStatus=completed`、`failureStage=output`、`retryable=false`,不重放脚本,后续输出可使用
|
|
767
|
+
`cwd:` 指定仓库内路径
|
|
719
768
|
|
|
720
769
|
### 页面元信息
|
|
721
770
|
|
|
@@ -859,7 +908,7 @@ mcp-chrome/
|
|
|
859
908
|
- **覆盖**:`navigator.webdriver`、`cdc_*` 属性、User-Agent 字符串、若干 WebGL vendor/renderer 值、Chrome runtime 属性
|
|
860
909
|
- **不覆盖**:Canvas 指纹、AudioContext 指纹、Font 枚举、TLS 层指纹(JA3/JA4)、CDP
|
|
861
910
|
attach 横幅("Chrome 正受自动化软件控制")、扩展自身存在的探测
|
|
862
|
-
- **警告**:这些修补不能过 Cloudflare
|
|
911
|
+
- **警告**:这些修补不能过 Cloudflare,JS Challenge 和 Turnstile
|
|
863
912
|
checkbox 由导航、input、evaluate 之后在真实浏览器里等待处理,不覆盖 Akamai、DataDome、PerimeterX、交互式验证码或 IP 声誉
|
|
864
913
|
|
|
865
914
|
## 已知限制
|
|
@@ -881,31 +930,37 @@ MIT 许可证 - 详见 [LICENSE](LICENSE)
|
|
|
881
930
|
## 操作状态与诊断
|
|
882
931
|
|
|
883
932
|
input 和 evaluate 返回值追加 `actionExecuted`、`actionStatus`、`verificationStatus`、`failureStage` 和
|
|
884
|
-
`retryable
|
|
933
|
+
`retryable`,验证状态分为
|
|
885
934
|
`matched`、`not_matched`、`unavailable`、`error`;debugger 超时且无法证明脚本已停止时,动作状态为
|
|
886
|
-
`unknown
|
|
887
|
-
`actionStatus="completed"` 和 `failureStage="output"
|
|
888
|
-
`actionExecuted=false`、`actionStatus="not_started"
|
|
889
|
-
`diagnosticsStatus
|
|
935
|
+
`unknown`,页面脚本抛异常时返回 `actionExecuted=true` 和 `actionStatus="failed"`;原生执行已返回结果后,本地结果展开或序列化失败时返回
|
|
936
|
+
`actionStatus="completed"` 和 `failureStage="output"`,页面前置条件不符时,input 和 evaluate 返回
|
|
937
|
+
`actionExecuted=false`、`actionStatus="not_started"`,diagnostics 是附加能力,失败时返回
|
|
938
|
+
`diagnosticsStatus`,不会覆盖主动作结果,browse 和 wait 的主动作失败时,也会保留失败前已收集的 diagnostics,目标诊断会读取当前 tab 的实时状态,不依赖 attach 时缓存的 URL 和标题
|
|
939
|
+
|
|
940
|
+
原生脚本终止,以及 CDP `Runtime` 脚本命令返回 `Internal error`、`Object couldn't be returned by value` 或
|
|
941
|
+
`Object reference chain is too long` 时,evaluate 和 `manage cdp` 保留原错误码,返回 `actionExecuted=true`、`actionStatus="unknown"`、`retryable=false`,不重放命令;evaluate 的执行中
|
|
942
|
+
RPC 超时或过期 execution context 导致结果未知时也不可直接重试;执行开始前的超时仍可重试;页面主动抛出的同名异常按动作失败处理,重试标记为 false
|
|
890
943
|
|
|
891
|
-
|
|
892
|
-
|
|
893
|
-
|
|
944
|
+
Extension 中已识别的原生 CDP 拒绝返回 `CDP_ERROR`,保留 method、目标、原生消息和可用的协议 code,context 区分 Debugger
|
|
945
|
+
域未启用、scriptId 失效、浏览器级命令限制、方法不存在、命令权限拒绝(`Not allowed`)及原生结果序列化失败,资源或方法查找失败不会推断为整个域不支持
|
|
946
|
+
这些调用保持失败并输出 warning,未知异常继续按 error 报告,原生快照或权限检查发现的已关闭 tab 按目标失败处理,与页面主动抛出的同文案异常分开
|
|
894
947
|
|
|
895
|
-
Extension 的 accessibility state
|
|
896
|
-
value
|
|
948
|
+
Extension 的 accessibility state 在生成元素名称和状态正文时,均不访问 `input[type=hidden]` 与 `input[type=password]`
|
|
949
|
+
的 value getter,默认 `all`、目标子树和文件输出使用相同规则隐藏控件仍可返回
|
|
950
|
+
`visible=false`,标签、placeholder、title 和普通输入值保留;显式脚本、HTML 和属性读取保持原有行为
|
|
897
951
|
|
|
898
952
|
`replace` 仅对 `textarea` 以及 `text`、`search`、`tel`、`url`、`password`
|
|
899
|
-
类型的 input
|
|
900
|
-
`select` 会返回 `UNSUPPORTED_SELECTION
|
|
901
|
-
locator 聚焦,不调用 Extension refId
|
|
902
|
-
post-condition 观测值,失败响应还会脱敏传入的 `find` 和替换 `text
|
|
953
|
+
类型的 input 使用文本选区,其他 input 类型通过原生完整 value 更新,并返回请求值与浏览器规范化后的实际值,对不支持选区的类型单独执行
|
|
954
|
+
`select` 会返回 `UNSUPPORTED_SELECTION`,CDP模式下,`select` 和 `replace` 的 locator target 通过 CDP
|
|
955
|
+
locator 聚焦,不调用 Extension refId,password value 不进入 input 失败 context 和 text
|
|
956
|
+
post-condition 观测值,失败响应还会脱敏传入的 `find` 和替换 `text`,password 的 `select`/`replace`
|
|
903
957
|
成功和失败响应均隐藏 console 与 network 诊断正文,返回 `diagnostics.redacted=true` 和
|
|
904
|
-
`reason="sensitive_input_or_unresolved_target"`;无法安全确认选择目标时也隐藏这些正文普通输入保留诊断,密码保护仅持续到当前 input 请求结束目标超时返回限量的locator、tab、frame
|
|
958
|
+
`reason="sensitive_input_or_unresolved_target"`;无法安全确认选择目标时也隐藏这些正文普通输入保留诊断,密码保护仅持续到当前 input 请求结束目标超时返回限量的locator、tab、frame、匹配数和候选上下文,显式
|
|
905
959
|
`tabId` 或 `frame`
|
|
906
|
-
作用域会在 input、wait、logs、extract 开始前确定活动 backend,动作和验证使用同一个目标 backend
|
|
960
|
+
作用域会在 input、wait、logs、extract 开始前确定活动 backend,动作和验证使用同一个目标 backend,precise iframe
|
|
907
961
|
evaluate 默认使用 `staleContextRetry="never"`,context 失效时不重放脚本; `readOnly` 允许 Extension 校验 frame
|
|
908
|
-
identity 并解析新 execution context
|
|
962
|
+
identity 并解析新 execution context 后重放一次,响应包含策略、`retryAttempted`、限量的 `retryReason`,以及最终 Extension
|
|
909
963
|
frame、parent frame、URL、CDP frame 和 execution context ID 组成的 `frameContext`,URL 相同的 frame 仅在所选 DOM
|
|
910
|
-
iframe 无法唯一确认目标时拒绝执行;Extension 重载后可继续访问原页面中的 iframe
|
|
911
|
-
|
|
964
|
+
iframe 无法唯一确认目标时拒绝执行;Extension 重载后可继续访问原页面中的 iframe,无需刷新或重新导航,探测上下文失效时输出 warning 并停止监听,避免未捕获的消息调用异常
|
|
965
|
+
发现摘要在首次扫描和端口集合变化时输出,包含从有 Server 到空集合的变化,相同集合的扫描及自动重连不重复输出;每次仍检查完整端口范围,显式 disconnect 后重新开始报告
|
|
966
|
+
普通 WebSocket open 前失败仍聚合为 debug;已识别 MCP server 的认证或协议拒绝只在摘要变化时输出一条限量 warning
|
|
@@ -264,7 +264,7 @@ export interface BrowserTopology {
|
|
|
264
264
|
focusedWindowId?: number;
|
|
265
265
|
activeTargetId?: string;
|
|
266
266
|
windows: BrowserWindowInfo[];
|
|
267
|
-
groups
|
|
267
|
+
groups?: BrowserTabGroupInfo[];
|
|
268
268
|
}
|
|
269
269
|
export interface BrowserTabGroupInfo {
|
|
270
270
|
id: number;
|
|
@@ -390,11 +390,11 @@ export interface IBrowserDriver {
|
|
|
390
390
|
typeRef(refId: string, text: string, clear?: boolean): Promise<void>;
|
|
391
391
|
scrollAt(x: number, y: number, refId?: string): Promise<void>;
|
|
392
392
|
getAttribute(selector: string | undefined, refId: string | undefined, attribute: string): Promise<string | null>;
|
|
393
|
-
inputKey(type: InputKeyType, options?: InputKeyOptions): Promise<void>;
|
|
393
|
+
inputKey(type: InputKeyType, options?: InputKeyOptions, timeout?: number): Promise<void>;
|
|
394
394
|
inputMouse(type: InputMouseType, x: number, y: number, options?: InputMouseOptions, timeout?: number): Promise<void>;
|
|
395
395
|
inputTouch(type: InputTouchType, touchPoints: InputTouchPoint[]): Promise<void>;
|
|
396
396
|
inputType(text: string, delay?: number, timeout?: number): Promise<void>;
|
|
397
|
-
stealthKey(key: string, type: 'down' | 'up' | 'press', modifiers: string[]): Promise<void>;
|
|
397
|
+
stealthKey(key: string, type: 'down' | 'up' | 'press', modifiers: string[], timeout?: number): Promise<void>;
|
|
398
398
|
stealthClick(x: number, y: number, button?: string, clickCount?: number, refId?: string, timeout?: number): Promise<void>;
|
|
399
399
|
stealthMouse(type: string, x: number, y: number, button?: string, timeout?: number): Promise<void>;
|
|
400
400
|
stealthType(text: string, delay?: number, timeout?: number): Promise<void>;
|
|
@@ -445,6 +445,7 @@ export interface IBrowserDriver {
|
|
|
445
445
|
newPage(url?: string, timeout?: number, options?: NewPageOptions): Promise<NewTabResult>;
|
|
446
446
|
closePage(targetId: string): Promise<void | PageManagementResult>;
|
|
447
447
|
activatePage(targetId: string): Promise<void>;
|
|
448
|
+
activatePageWithAffected?(targetId: string): Promise<PageManagementResult>;
|
|
448
449
|
selectPage(targetId: string, timeout?: number): Promise<void>;
|
|
449
450
|
getCurrentTargetId(): string | null;
|
|
450
451
|
setCurrentTargetId(targetId: string | null): void;
|
|
@@ -461,7 +462,7 @@ export interface IBrowserDriver {
|
|
|
461
462
|
} | null): void;
|
|
462
463
|
getState(): DriverState | null;
|
|
463
464
|
/** 仅 Extension 模式支持;CDP throw */
|
|
464
|
-
resolveFrame(frame: string | number): Promise<FrameResolveResult>;
|
|
465
|
+
resolveFrame(frame: string | number, timeout?: number): Promise<FrameResolveResult>;
|
|
465
466
|
getCurrentFrameId(): number;
|
|
466
467
|
setCurrentFrameId(frameId: number): void;
|
|
467
468
|
/**
|