@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.
Files changed (65) hide show
  1. package/README.md +119 -38
  2. package/README_zh.md +165 -110
  3. package/dist/core/browser-driver.d.ts +5 -4
  4. package/dist/core/browser-driver.d.ts.map +1 -1
  5. package/dist/core/browser-driver.js.map +1 -1
  6. package/dist/core/errors.d.ts +6 -4
  7. package/dist/core/errors.d.ts.map +1 -1
  8. package/dist/core/errors.js +14 -8
  9. package/dist/core/errors.js.map +1 -1
  10. package/dist/core/locator.d.ts +7 -0
  11. package/dist/core/locator.d.ts.map +1 -1
  12. package/dist/core/locator.js +48 -25
  13. package/dist/core/locator.js.map +1 -1
  14. package/dist/core/session.d.ts +6 -4
  15. package/dist/core/session.d.ts.map +1 -1
  16. package/dist/core/session.js +58 -23
  17. package/dist/core/session.js.map +1 -1
  18. package/dist/core/unified-session.d.ts +11 -8
  19. package/dist/core/unified-session.d.ts.map +1 -1
  20. package/dist/core/unified-session.js +71 -27
  21. package/dist/core/unified-session.js.map +1 -1
  22. package/dist/extension/bridge.d.ts +3 -3
  23. package/dist/extension/bridge.d.ts.map +1 -1
  24. package/dist/extension/bridge.js +50 -20
  25. package/dist/extension/bridge.js.map +1 -1
  26. package/dist/extension/http-server.d.ts.map +1 -1
  27. package/dist/extension/http-server.js +9 -0
  28. package/dist/extension/http-server.js.map +1 -1
  29. package/dist/tools/browse.d.ts.map +1 -1
  30. package/dist/tools/browse.js +10 -4
  31. package/dist/tools/browse.js.map +1 -1
  32. package/dist/tools/challenge.d.ts.map +1 -1
  33. package/dist/tools/challenge.js +12 -15
  34. package/dist/tools/challenge.js.map +1 -1
  35. package/dist/tools/evaluate.d.ts.map +1 -1
  36. package/dist/tools/evaluate.js +10 -0
  37. package/dist/tools/evaluate.js.map +1 -1
  38. package/dist/tools/extract.d.ts.map +1 -1
  39. package/dist/tools/extract.js +30 -22
  40. package/dist/tools/extract.js.map +1 -1
  41. package/dist/tools/input.d.ts.map +1 -1
  42. package/dist/tools/input.js +83 -57
  43. package/dist/tools/input.js.map +1 -1
  44. package/dist/tools/manage.d.ts.map +1 -1
  45. package/dist/tools/manage.js +16 -30
  46. package/dist/tools/manage.js.map +1 -1
  47. package/dist/tools/post-condition.d.ts.map +1 -1
  48. package/dist/tools/post-condition.js +23 -9
  49. package/dist/tools/post-condition.js.map +1 -1
  50. package/dist/tools/target-diagnostics.d.ts +9 -1
  51. package/dist/tools/target-diagnostics.d.ts.map +1 -1
  52. package/dist/tools/target-diagnostics.js +60 -17
  53. package/dist/tools/target-diagnostics.js.map +1 -1
  54. package/dist/tools/wait.d.ts.map +1 -1
  55. package/dist/tools/wait.js +19 -7
  56. package/dist/tools/wait.js.map +1 -1
  57. package/extension/dist/assets/{content.ts-loader-CnJuCGhl.js → content.ts-loader-DUWbDHRS.js} +1 -1
  58. package/extension/dist/assets/{content.ts-C4imZ6A9.js → content.ts-qe6IB5DK.js} +1 -1
  59. package/extension/dist/assets/{index.ts-GeHNZBml.js → index.ts-D7_LCUoV.js} +559 -212
  60. package/extension/dist/assets/{page-scripts-CMIY1zhd.js → page-scripts-D508WLkW.js} +50 -51
  61. package/extension/dist/assets/{popup.html-CgtWL6Py.js → popup.html-B-eVq48O.js} +6 -4
  62. package/extension/dist/manifest.json +4 -4
  63. package/extension/dist/service-worker-loader.js +1 -1
  64. package/extension/dist/src/popup/popup.html +1 -1
  65. 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)`。脚本让 Chrome 进程保持前台运行,并报告退出码;使用独立 profile,避免请求被已有 Chrome 实例接管。
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。旧版 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 本地连接”。关闭后会立即取消进行中的 health
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。`browse(action="connect", port=9222)`
186
+ > 已连接的 Extension 是所有工具的默认模式,Extension 不可用时才回退到 CDP,`browse(action="connect", port=9222)`
167
187
  > 会为后续工具显式选择 CDP;调用不带 port 的 `browse(action="connect")`
168
- > 会回到 Extension。仅因回退而建立的 CDP 连接会在 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`。`defaultTargetId`
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` 自动创建页面的场景。两个 driver 的 `open` 和 `refresh` 都支持
211
+ warning/error 和失败网络请求摘要,也覆盖首次 `open` 自动创建页面的场景,两个 driver 的 `open` 和 `refresh` 都支持
192
212
  `wait="load"`、`wait="domcontentloaded"` 和
193
- `wait="networkidle"`。等待器会在命令前建立,并绑定命令产生的新主文档,上一导航的迟到生命周期事件不会提前完成等待。CDP模式的
213
+ `wait="networkidle"`,等待器会在命令前建立,并绑定命令产生的新主文档,上一导航的迟到生命周期事件不会提前完成等待,CDP模式的
194
214
  `networkidle` 等待当前主 frame loader 的 `networkIdle`
195
215
  事件;Extension 模式会等待当前文档完成、所有已跟踪响应 body 结束和 500
196
- ms 静默窗口。请求跟踪发生丢失时返回超时,不会误报空闲。`close` 必须传
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
- 仍可用;同时提供时两者必须一致。显式目标只作用于当前操作,结束后恢复原默认目标。`browse.close` 和 `manage.closePage`
223
- 必须显式指定 ID。页面动作成功或失败时,响应中的 `pageContext`
241
+ 仍可用;同时提供时两者必须一致,显式目标只作用于当前操作,结束后恢复原默认目标,`browse.close` 和 `manage.closePage`
242
+ 必须显式指定 ID,页面动作成功或失败时,响应中的 `pageContext`
224
243
  包含实际目标及来源(`explicit`、`default`、`created`、`reused`、`unconfirmed`)、前后 URL/revision、默认目标前后状态,以及 Extension 报告的浏览器活动目标;创建页面失败且未返回创建 ID 时标为
225
- `unconfirmed`。CDP 的活动状态标为不可用,不把操作目标当作前台页面
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 和元数据。revision 由 backend
249
- epoch 与单页计数构成;Extension 跟踪主 frame 导航和 MCP 动作,CDP 跟踪已附加页面的导航,并保守计入发出的变更命令,包括 evaluate。网页自身的任意 DOM 更改不在跟踪范围内,条件动作前应重新获取 URL/revision。`browse`
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。Extension 模式下,导航先不启用 debugger 日志采集,连续八秒被动读取真实 tab 标题。interstitial 持续存在时,才检查可见 Turnstile 控件,找到后才点击。Extension
280
- inspect 走 isolated world,检查前先卸掉 debugger。同页测试按钮走页面点击;出现 Cloudflare Turnstile
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`。widget 点 compact
286
- Turnstile 卡片左侧 checkbox,宿主 wrapper 比卡片宽时也只点左侧卡片,不点文案。DOM 里已有 Cloudflare
308
+ `mouse_event`,widget 点 compact
309
+ Turnstile 卡片左侧 checkbox,宿主 wrapper 比卡片宽时也只点左侧卡片,不点文案,DOM 里已有 Cloudflare
287
310
  iframe 时,即使 iframe 尺寸为 0,也走系统鼠标,不改用页面点击,后续宿主页 `Verify you are human` / `请验证您是真人`
288
- 按钮同样走系统鼠标。系统鼠标只在受控测试页已经是已聚焦窗口的活动 tab 时使用,混合窗口不会调用 `focusWindow`。
311
+ 按钮同样走系统鼠标,系统鼠标只在受控测试页已经是已聚焦窗口的活动 tab 时使用,混合窗口不会调用 `focusWindow`
289
312
 
290
- 系统点击前会卸掉 debugger,再读一次视口。缺少系统鼠标工具或窗口未聚焦时返回可见错误,不会静默改用 CDP 点击。
313
+ 系统点击前会卸掉 debugger,再读一次视口,缺少系统鼠标工具或窗口未聚焦时返回可见错误,不会静默改用 CDP 点击
291
314
 
292
- widget 要连续两次 inspect 到同一坐标才点,不以普通元素的尺寸认定 widget;系统鼠标从远处过来时从控件附近起步。同一类 checkbox 或 compact
315
+ widget 要连续两次 inspect 到同一坐标才点,不以普通元素的尺寸认定 widget;系统鼠标从远处过来时从控件附近起步,同一类 checkbox 或 compact
293
316
  widget 在同一次等待里最多点一次;Cloudflare 随后换成可见的 `Verify you are human` 或 `请验证您是真人`
294
- 按钮时,inspect 判成 `verify` 后再点一次。访问受 Cloudflare 保护的页面默认保持
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
- 检测覆盖 `Just a moment...`、`请稍候…` 等标题、Challenge DOM、正文标记和 `Verify you are human` / `请验证您是真人`
298
- 控件,包括精确匹配这两种文案的可见 `button` 元素;没有 Cloudflare iframe 时,同页按钮使用页面点击 CDP 用
299
- `Target.getTargetInfo` 读取实时标题。页面恢复后残留的 Cloudflare iframe 不算等待中,缓存标题不参与判定。不会调用 CAPTCHA
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`,表示已过盾但目标页面尚未加载。隐藏的成功文案(例如 `display:none`
306
- 的标题)不算过盾,可见 Turnstile 勾选框仍视为等待中。Challenge 成功和失败响应都含 `mode`。超时返回 `CHALLENGE_TIMEOUT`
307
- 且 `retryable=true`,并带 `clickedTurnstile` 和实际观察到的 `challengeKind`(点过 Turnstile 时不会报成 `js`)。Access
308
- denied 返回 `CHALLENGE_DENIED`。交互式验证码、Bot Fight
309
- Mode 和 IP 声誉检查无法靠等待或点击 checkbox 完成。之后的正常主文档响应才会清掉 header 标记,普通 iframe 文档响应和清空网络日志都不会清掉它,
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` 至少需要一个事件。参数:`humanize` 启用贝塞尔曲线移动和随机延迟,`diagnostics=true` 返回动作后新增 console
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。`postCondition.script` 可传表达式、函数、async
336
- function 或 Promise 表达式;函数会被调用,最终 Promise 值会被等待后再判定,抛错或 reject 会让检查失败。`targetId`(或旧版
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`。指定 `target` 的截图未匹配、`nth`
432
+ 差异图输出,`diffOutput` 必须同时传 `compareWith`,指定 `target` 的截图未匹配、`nth`
396
433
  越界或尺寸为零时返回目标错误,不会静默返回视口截图,截图响应包含
397
434
  `metadata.format`、`width`、`height`、`dimensionSource`、`byteSize`、`fullPage`、`scale`、`clip` 和
398
- `capabilities`。截图在执行前限制单边 16,384 像素、总计 12,000,000 像素、预计 RGBA 内存 48 MiB 和编码数据 25
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` 控制 DOM 遍历深度(默认 15),减小可降低大页面的返回数据量, `mode` 选择数据源 —
418
- `accessibility`(默认,从无障碍树派生)或 `domsnapshot`(CDP `DOMSnapshot.captureSnapshot`,仅 CDP 模式,返回带 computed
419
- style 的扁平节点数组,便于二次处理),
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 模式等待网络静默。两种模式的默认 `ms` 都是 500ms,响应返回 `idleKind` 和
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,并最多重放一次,`Runtime.evaluate`
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,自动保存仍受该上限约束。两条路径均保留深度 8、节点 2000 和不可序列化结果拒绝,字符预算按 UTF-16
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` | 激活受控 Tab 并聚焦所在窗口 |
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 配置仅支持 Extension 模式,操作已有对象时用 `targetId`、`targetIds`、`windowId` 或 `groupId`
512
- 明确指定目标,返回 `affected.before/after`,分组结果还返回 `tabsBefore/tabsAfter`,`ungroupPages`
513
- 由 Chrome 删除空组,不撤销成员的受控权限分组名称、颜色、折叠更新和整组移动要求所有成员受控,窗口更新、调整和聚焦要求窗口内所有 tab 受控,缓存的 MCP
514
- window ID 不改变此规则 Extension 模式不支持 `clearCache`,会返回 `UNSUPPORTED_MODE` 且不清除任何内容;清 Cookie 请用带
515
- `url` 或 `domain` 过滤的 `cookies(action="clear")`,清 storage 或 cache 请改用 CDP 模式。`focusWindow`
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`。持久的 `adoptPage`、`releasePage`
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 和元数据传 `details="full"`
536
- 获取选中、静音、自动丢弃、来源 tab ID 和可用原生只读属性,false 值保留 `targetIds` 与 `managedOnly=true`
537
- 筛选页面及所属窗口、分组;`totalTargetCount`、`totalWindowCount` 和 `totalTabCount` 区分总量与选中数量窗口通过
538
- `targetIds` 引用页面,不重复完整对象;favicon data URL 不内联,完整结果用 `favIconInline=true`
539
- 标明存在分组保留名称、颜色、折叠/共享、窗口、首个成员位置和成员 ID,颜色只属于分组,只读属性只回显,不作为写入参数列表操作不读取页面正文,不导航或改变焦点
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` 等级会在过滤和返回前转换。清空 fallback
565
- console 日志会保留 hook。debugger 采集恢复后,fallback 采集会停用;仍指向 MCP
566
- wrapper 的 console 方法会恢复,页面之后安装的 wrapper 保持不变。network 日志在 `loadingFinished` 或 `loadingFailed`
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`。日志尽量返回 `method`、
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`。`name` 只能在该范围内进一步过滤,避免误删其他站点的同名 Cookie。返回的
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 会话。临时输出整个会话最多 256 项、128
706
- MiB;启动时只清理超过 24 小时且所属进程已退出的带归属标记目录。成功写入 `tmp:` 文件或目录的响应会返回 `retention`
707
- 清理条件,`cwd:` 响应不带此字段。重启后仍需通过 MCP 访问的文件使用
708
- `cwd:`。输出路径拒绝 Windows 保留设备名、ADS、非法字符以及末尾空格或点号;Windows 上写入敏感内容前须验证私有 DACL。
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`。 `usage.complete=false` 时,占用只为已观察下界,`remaining`/`projected`
716
- 为 null;已有输出保留。evaluate 的输出失败保留
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。JS Challenge 和 Turnstile
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`。页面脚本抛异常时返回 `actionExecuted=true` 和 `actionStatus="failed"`;结果展开或序列化失败时返回
887
- `actionStatus="completed"` 和 `failureStage="output"`。页面前置条件不符时,input 和 evaluate 返回
888
- `actionExecuted=false`、`actionStatus="not_started"`。diagnostics 是附加能力,失败时返回
889
- `diagnosticsStatus`,不会覆盖主动作结果。browse 和 wait 的主动作失败时,也会保留失败前已收集的 diagnostics。目标诊断会读取当前 tab 的实时状态,不依赖 attach 时缓存的 URL 和标题。
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
- 原生脚本终止,以及 CDP `Runtime` 脚本命令返回 `Internal error` 时,evaluate 和 `manage cdp` 保留原错误码,返回
892
- `actionExecuted=true`、`actionStatus="unknown"`、`retryable=false`,不重放命令;evaluate 的执行中 RPC 超时或过期 execution
893
- context 导致结果未知时也不可直接重试;执行开始前的超时仍可重试;页面主动抛出的同名异常仍按动作失败处理
944
+ Extension 中已识别的原生 CDP 拒绝返回 `CDP_ERROR`,保留 method、目标、原生消息和可用的协议 code,context 区分 Debugger
945
+ 域未启用、scriptId 失效、浏览器级命令限制、方法不存在、命令权限拒绝(`Not allowed`)及原生结果序列化失败,资源或方法查找失败不会推断为整个域不支持
946
+ 这些调用保持失败并输出 warning,未知异常继续按 error 报告,原生快照或权限检查发现的已关闭 tab 按目标失败处理,与页面主动抛出的同文案异常分开
894
947
 
895
- Extension 的 accessibility state 不读取 password
896
- value 生成元素名称,标签、placeholder、title 和普通输入值保留;显式脚本、HTML 和属性读取保持原有行为
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 使用文本选区。其他 input 类型通过原生完整 value 更新,并返回请求值与浏览器规范化后的实际值。对不支持选区的类型单独执行
900
- `select` 会返回 `UNSUPPORTED_SELECTION`。CDP模式下,`select` 和 `replace` 的 locator target 通过 CDP
901
- locator 聚焦,不调用 Extension refId。password value 不进入 input 失败 context 和 text
902
- post-condition 观测值,失败响应还会脱敏传入的 `find` 和替换 `text`。password 的 `select`/`replace`
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。precise iframe
960
+ 作用域会在 input、wait、logs、extract 开始前确定活动 backend,动作和验证使用同一个目标 backend,precise iframe
907
961
  evaluate 默认使用 `staleContextRetry="never"`,context 失效时不重放脚本; `readOnly` 允许 Extension 校验 frame
908
- identity 并解析新 execution context 后重放一次。响应包含策略、`retryAttempted`、限量的 `retryReason`,以及最终 Extension
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,无需刷新或重新导航端口扫描会把普通的 WebSocket
911
- open 前失败聚合为 debug;已识别 MCP server 的认证或协议拒绝只在摘要变化时输出一条限量 warning
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: BrowserTabGroupInfo[];
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
  /**