@pyrokine/mcp-chrome 2.4.4 → 3.0.0

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 (116) hide show
  1. package/README.md +401 -102
  2. package/README_zh.md +319 -79
  3. package/dist/anti-detection/injection.js +3 -3
  4. package/dist/cdp/client.d.ts +1 -1
  5. package/dist/cdp/client.d.ts.map +1 -1
  6. package/dist/cdp/client.js +18 -7
  7. package/dist/cdp/client.js.map +1 -1
  8. package/dist/cdp/launcher.d.ts +2 -3
  9. package/dist/cdp/launcher.d.ts.map +1 -1
  10. package/dist/cdp/launcher.js +84 -24
  11. package/dist/cdp/launcher.js.map +1 -1
  12. package/dist/core/auto-wait.d.ts +3 -3
  13. package/dist/core/auto-wait.d.ts.map +1 -1
  14. package/dist/core/auto-wait.js +45 -20
  15. package/dist/core/auto-wait.js.map +1 -1
  16. package/dist/core/browser-driver.d.ts +101 -12
  17. package/dist/core/browser-driver.d.ts.map +1 -1
  18. package/dist/core/browser-driver.js.map +1 -1
  19. package/dist/core/errors.d.ts +16 -0
  20. package/dist/core/errors.d.ts.map +1 -1
  21. package/dist/core/errors.js +77 -0
  22. package/dist/core/errors.js.map +1 -1
  23. package/dist/core/locator.d.ts.map +1 -1
  24. package/dist/core/locator.js +6 -4
  25. package/dist/core/locator.js.map +1 -1
  26. package/dist/core/os-mouse.d.ts +15 -2
  27. package/dist/core/os-mouse.d.ts.map +1 -1
  28. package/dist/core/os-mouse.js +52 -8
  29. package/dist/core/os-mouse.js.map +1 -1
  30. package/dist/core/session.d.ts +34 -19
  31. package/dist/core/session.d.ts.map +1 -1
  32. package/dist/core/session.js +574 -130
  33. package/dist/core/session.js.map +1 -1
  34. package/dist/core/types.d.ts +2 -0
  35. package/dist/core/types.d.ts.map +1 -1
  36. package/dist/core/types.js.map +1 -1
  37. package/dist/core/unified-session.d.ts +95 -20
  38. package/dist/core/unified-session.d.ts.map +1 -1
  39. package/dist/core/unified-session.js +489 -117
  40. package/dist/core/unified-session.js.map +1 -1
  41. package/dist/core/utils.d.ts +5 -0
  42. package/dist/core/utils.d.ts.map +1 -1
  43. package/dist/core/utils.js +475 -54
  44. package/dist/core/utils.js.map +1 -1
  45. package/dist/extension/bridge.d.ts +46 -36
  46. package/dist/extension/bridge.d.ts.map +1 -1
  47. package/dist/extension/bridge.js +269 -112
  48. package/dist/extension/bridge.js.map +1 -1
  49. package/dist/extension/http-server.d.ts +3 -0
  50. package/dist/extension/http-server.d.ts.map +1 -1
  51. package/dist/extension/http-server.js +19 -2
  52. package/dist/extension/http-server.js.map +1 -1
  53. package/dist/index.js +7 -0
  54. package/dist/index.js.map +1 -1
  55. package/dist/tools/browse.d.ts.map +1 -1
  56. package/dist/tools/browse.js +241 -171
  57. package/dist/tools/browse.js.map +1 -1
  58. package/dist/tools/challenge.d.ts +1 -1
  59. package/dist/tools/challenge.d.ts.map +1 -1
  60. package/dist/tools/challenge.js +75 -37
  61. package/dist/tools/challenge.js.map +1 -1
  62. package/dist/tools/cookies.d.ts.map +1 -1
  63. package/dist/tools/cookies.js +5 -3
  64. package/dist/tools/cookies.js.map +1 -1
  65. package/dist/tools/diagnostics.d.ts +3 -3
  66. package/dist/tools/diagnostics.d.ts.map +1 -1
  67. package/dist/tools/diagnostics.js +13 -12
  68. package/dist/tools/diagnostics.js.map +1 -1
  69. package/dist/tools/evaluate.d.ts.map +1 -1
  70. package/dist/tools/evaluate.js +57 -26
  71. package/dist/tools/evaluate.js.map +1 -1
  72. package/dist/tools/extract.d.ts.map +1 -1
  73. package/dist/tools/extract.js +107 -175
  74. package/dist/tools/extract.js.map +1 -1
  75. package/dist/tools/input.d.ts +1 -1
  76. package/dist/tools/input.d.ts.map +1 -1
  77. package/dist/tools/input.js +380 -158
  78. package/dist/tools/input.js.map +1 -1
  79. package/dist/tools/logs.d.ts.map +1 -1
  80. package/dist/tools/logs.js +5 -5
  81. package/dist/tools/logs.js.map +1 -1
  82. package/dist/tools/manage.d.ts.map +1 -1
  83. package/dist/tools/manage.js +380 -57
  84. package/dist/tools/manage.js.map +1 -1
  85. package/dist/tools/page-context.d.ts +17 -0
  86. package/dist/tools/page-context.d.ts.map +1 -0
  87. package/dist/tools/page-context.js +103 -0
  88. package/dist/tools/page-context.js.map +1 -0
  89. package/dist/tools/png.d.ts +5 -0
  90. package/dist/tools/png.d.ts.map +1 -1
  91. package/dist/tools/png.js +84 -19
  92. package/dist/tools/png.js.map +1 -1
  93. package/dist/tools/post-condition.d.ts.map +1 -1
  94. package/dist/tools/post-condition.js +5 -2
  95. package/dist/tools/post-condition.js.map +1 -1
  96. package/dist/tools/schema.d.ts +9 -0
  97. package/dist/tools/schema.d.ts.map +1 -1
  98. package/dist/tools/schema.js +15 -0
  99. package/dist/tools/schema.js.map +1 -1
  100. package/dist/tools/target-diagnostics.d.ts.map +1 -1
  101. package/dist/tools/target-diagnostics.js +32 -19
  102. package/dist/tools/target-diagnostics.js.map +1 -1
  103. package/dist/tools/wait.d.ts.map +1 -1
  104. package/dist/tools/wait.js +19 -25
  105. package/dist/tools/wait.js.map +1 -1
  106. package/extension/dist/assets/content.ts-C4imZ6A9.js +13 -0
  107. package/extension/dist/assets/content.ts-loader-CnJuCGhl.js +13 -0
  108. package/extension/dist/assets/{index.ts-Bqcu2qiN.js → index.ts-GeHNZBml.js} +2040 -2111
  109. package/extension/dist/assets/page-scripts-CMIY1zhd.js +1379 -0
  110. package/extension/dist/assets/{popup.html-B81xccfq.js → popup.html-CgtWL6Py.js} +48 -1
  111. package/extension/dist/manifest.json +4 -3
  112. package/extension/dist/service-worker-loader.js +1 -1
  113. package/extension/dist/src/popup/popup.html +11 -1
  114. package/package.json +9 -7
  115. package/scripts/start-chrome.ps1 +58 -0
  116. package/extension/dist/assets/content.ts-Cj_iiU2s.js +0 -25
package/README_zh.md CHANGED
@@ -12,7 +12,7 @@ Chrome 浏览器自动化 MCP Server,双模式架构: **Extension 模式**
12
12
 
13
13
  - **双模式**:Extension 模式共享登录状态;CDP 模式用于无头/隔离场景
14
14
  - **8 个统一工具**:基于 action 的设计,覆盖浏览、输入、提取、等待、执行、管理、Cookie、日志
15
- - **多 Tab 并行**:`tabId` 参数支持对任意 Tab 操作,无需切换焦点
15
+ - **多页面定位**:`targetId` 在两种 backend 中指定操作页面,无需切换浏览器焦点;`tabId` 保留为兼容别名
16
16
  - **iframe 穿透**:`frame` 参数支持操作 iframe 内元素(CSS 选择器或索引,Extension 模式)
17
17
  - **语义化定位**:11 种元素定位方式(role、text、label、css、css+文本组合、xpath、坐标等)
18
18
  - **自动等待**:内置可点击性、可输入性检测,基于 deadline 的超时预算机制
@@ -22,6 +22,17 @@ Chrome 浏览器自动化 MCP Server,双模式架构: **Extension 模式**
22
22
  - **反检测**:可选的指纹伪装和行为模拟
23
23
  - **结构化错误**:每个错误包含 code、message、suggestion、context
24
24
 
25
+ ## 迁移到 3.0
26
+
27
+ - `manage(action="closePage")` 必须显式传入 `targetId`,不再关闭缺省页面
28
+ - Extension 模式显式 `adoptPage`
29
+ 后,已有页面获得与新建受控页相同的读取、输入、脚本、截图、debugger 和日志能力,受控页面无需 popup 普通只读授权
30
+ - 单页普通读取授权覆盖 text、HTML、attribute、computed
31
+ style 与 state,不开放任意 JavaScript、CDP/debugger、input 或 screenshot
32
+ - `tmp:` 文件只属于当前 MCP server 会话;重启后需重新生成,需保留的文件应在服务器退出前保存到 `cwd:`
33
+
34
+ 本地零配置自动连接保持不变,刷新 Extension 或重启 MCP client 后不需要手动点击“连接”
35
+
25
36
  ## 兼容客户端
26
37
 
27
38
  | 客户端 | 状态 |
@@ -61,6 +72,20 @@ claude mcp add chrome -- node "$PWD/dist/index.js"
61
72
 
62
73
  Extension 模式需要在 Chrome 中加载 `extension/dist`。
63
74
 
75
+ ### Windows CDP 启动
76
+
77
+ Chrome 自动查找 Windows App Paths、`PATH`、已安装的 Chrome channels、Chromium、Chrome for Testing,以及
78
+ `MCP_CHROME_PORTABLE_DIR` 或 `%USERPROFILE%\\.mcp-chrome\\portable`,也可以在 PowerShell 中启动独立的 CDP 浏览器:
79
+
80
+ ```powershell
81
+ & '<npm-root>\@pyrokine\mcp-chrome\scripts\start-chrome.ps1' -Port 9222
82
+ # 也可显式指定便携版可执行文件和独立 profile:
83
+ & '<npm-root>\@pyrokine\mcp-chrome\scripts\start-chrome.ps1' -Port 9222 -ExecutablePath 'C:\Browsers\chrome.exe' -ProfileDir 'C:\Temp\mcp-chrome-profile'
84
+ ```
85
+
86
+ 随后调用
87
+ `browse(action="connect", port=9222)`。脚本让 Chrome 进程保持前台运行,并报告退出码;使用独立 profile,避免请求被已有 Chrome 实例接管。
88
+
64
89
  ## 快速开始
65
90
 
66
91
  ### 模式一:Extension 模式(推荐)
@@ -121,7 +146,8 @@ MCP_CHROME_PAIRING_TOKEN="your-token" node /path/to/mcp-chrome/dist/index.js
121
146
  ```
122
147
 
123
148
  需要强制配对 token 时,在 server 设置 `MCP_CHROME_ALLOW_INSECURE_NO_TOKEN=0`,并在 Extension
124
- popup 关闭“允许无 token本地连接”,
149
+ popup 关闭“允许无 token 本地连接”。关闭后会立即取消进行中的 health
150
+ check、WebSocket 握手和已安排的重连,旧的无 token 连接尝试不会在策略更新后重新连入,
125
151
 
126
152
  ### 模式二:CDP 模式(回退)
127
153
 
@@ -158,21 +184,104 @@ browse(action="open", url="https://example.com")
158
184
  | `close` | 关闭 `targetId` 指定的页面 |
159
185
 
160
186
  Extension 特有:`list` 返回 flat `targets` 数组和树状 `windows`,每个 target 含 `managed`(Tab 是否由 MCP
161
- Chrome 受控)、 `isActive`(是否为当前操作目标)、
162
- `windowId`、`index`、`pinned`、`incognito`、`status`(`loading`/`complete`),树状结构含
163
- `windowCount`、`focusedWindowId`、 `activeTargetId` 和每个窗口按顺序排列的 `tabs`,可区分每个窗口内的 active
164
- tab 和当前人眼看到的 focused window 页面,`open` 自动创建 Tab 分组(cyan 色),`open`、`back`、`forward`、`refresh` 支持
165
- `diagnostics=true`,返回动作期间新增的 console warning/error 和失败网络请求摘要,也覆盖首次 `open`
166
- 自动创建页面的场景,`close` 必须传 `targetId`,且只关闭该页面,不会关闭整个 CDP 连接,
187
+ Chrome 受控)、`isActive`(该窗口中 Chrome 的活动 Tab)、`windowId`、`index`、`pinned`、`incognito`、`status`(`loading`/`complete`),树状结构含
188
+ `windowCount`、`focusedWindowId`、`activeTargetId` 和每个窗口按顺序排列的 `tabs`。`defaultTargetId`
189
+ 是默认操作目标,CDP 不用选中的操作目标推断浏览器前台页面,`open`
190
+ 自动创建 Tab 分组(cyan 色),`open`、`back`、`forward`、`refresh` 支持 `diagnostics=true`,返回动作期间新增的 console
191
+ warning/error 和失败网络请求摘要,也覆盖首次 `open` 自动创建页面的场景。两个 driver 的 `open` 和 `refresh` 都支持
192
+ `wait="load"`、`wait="domcontentloaded"` 和
193
+ `wait="networkidle"`。等待器会在命令前建立,并绑定命令产生的新主文档,上一导航的迟到生命周期事件不会提前完成等待。CDP模式的
194
+ `networkidle` 等待当前主 frame loader 的 `networkIdle`
195
+ 事件;Extension 模式会等待当前文档完成、所有已跟踪响应 body 结束和 500
196
+ ms 静默窗口。请求跟踪发生丢失时返回超时,不会误报空闲。`close` 必须传
197
+ `targetId`,且只关闭该页面,不会关闭整个 CDP 连接,
198
+
199
+ Extension 模式的 `back/forward`
200
+ 优先使用浏览器原生历史,只有原生 API 明确报告无历史时才允许尝试页面脚本;受限 URL 和浏览器错误页不注入没有可用历史时返回
201
+ `navigated=false`,其他原生错误保留;execution
202
+ context 失效或浏览器拒绝向错误页注入时,仍返回操作失败,Extension 将其记录为预期操作警告;任意 debugger 命令不自动重放
203
+
204
+ `open`、`back`、`forward`、`refresh` 的 `timeout`
205
+ 从请求入口开始计时,页面准备、排队、协议请求、加载、Challenge 检查与点击、诊断和目标恢复共用剩余预算,导航 RPC 不额外增加传输时间队列中的动作到期后不再派发,后续请求仍等待原在途动作结束;显式
206
+ `timeout=0` 在导航派发前拒绝,页面创建保留独立的加载等待与传输余量合同
207
+
208
+ 超时不会撤回已经派发的 Chrome 操作,结果未知时返回 `TIMEOUT`、`actionExecuted="unknown"`、`actionStatus="unknown"` 和
209
+ `retryable=false`,应读取实际页面状态,不重放导航 `pageContext.after` 使用实时快照,无法取得时为 null 并附
210
+ `contextError`;恢复预算耗尽时单独报告恢复失败,保留主动作结果 CDP 历史等待接受当前 session 主 frame 的 BFCache 恢复或同文档事件,普通 frame
211
+ commit、子 frame 和其他 session 的事件不作为完成信号
212
+
213
+ Challenge 点击、detach 和检查 RPC 携带剩余 deadline,排队或页面校验耗尽预算后不再派发;系统鼠标移动与 fallback 进程使用同一 deadline
214
+ CDP 已开始的按下始终尝试向原连接、原 session 释放,清理最多等待 1 秒,不向后来选择的目标发送只读 Challenge 检查到期返回
215
+ `CHALLENGE_TIMEOUT`,保留已知主动作状态;点击结果未知时返回 `TIMEOUT`、已知主动作状态、
216
+ `verificationStatus="unknown"`、`verificationActionExecuted` 和 `retryable=false`,不自动重放导航或点击
217
+
218
+ evaluate 在成功、动作失败、后置验证不匹配和输出失败时保留 Challenge 结果字段 `originResponsePending=true`
219
+ 表示验证成功但源站尚未响应,不表示目标内容已加载
220
+
221
+ 页面类工具在两种 backend 中都接受 `targetId`,旧版 `tabId`
222
+ 仍可用;同时提供时两者必须一致。显式目标只作用于当前操作,结束后恢复原默认目标。`browse.close` 和 `manage.closePage`
223
+ 必须显式指定 ID。页面动作成功或失败时,响应中的 `pageContext`
224
+ 包含实际目标及来源(`explicit`、`default`、`created`、`reused`、`unconfirmed`)、前后 URL/revision、默认目标前后状态,以及 Extension 报告的浏览器活动目标;创建页面失败且未返回创建 ID 时标为
225
+ `unconfirmed`。CDP 的活动状态标为不可用,不把操作目标当作前台页面
226
+
227
+ 旧 Extension 缺少 `page_snapshot` 时,无条件页面动作仍可使用实时页面列表中的 URL,`pageContext.before` 和 `after`
228
+ 的快照返回 `revision=null`,并通过 `warning` 说明 revision 与原子条件不可用,传入 `expectedUrl` 或 `expectedRevision`
229
+ 时在派发前返回 `DRIVER_CAPABILITY_ERROR`、`actionExecuted=false` 和
230
+ `actionStatus="not_started"`,更新 Extension 后才能使用这些条件 evaluate 和 input 保留
231
+ `failureStage="precondition"`,顶层状态与错误上下文一致,不派发脚本或输入事件其他快照错误仍阻止动作,兼容读取共用原 timeout 预算
232
+
233
+ Extension 页面快照确认目标 tab 已不存在时返回 `TARGET_NOT_FOUND`,保留 `context.targetId` 和原始
234
+ `context.nativeMessage`;输入派发前被拒绝时保留
235
+ `eventsExecuted=0`、`actionExecuted=false`,不改用其他页面或重放动作,用户脚本主动抛出同文案不归类为缺页
236
+
237
+ Chrome 已返回创建标识后,失败响应保留 `error.context.createdTargetId`、窗口 ID、实际 `managed`、`actionExecuted`、
238
+ `actionStatus="partial"` 和 `failureStage`;RPC 结果未知时,`actionStatus` 与 `actionExecuted` 均为 `"unknown"`
239
+ 未取得创建标识的失败响应中 `pageContext.targetId=null`,不指向原默认页,不自动重复创建或删除
240
+
241
+ 临时目标的恢复结果通过 `pageContext.targetRestoration` 单独报告,`restored` 表示恢复原默认目标,`cleared`
242
+ 表示原先无默认目标并清除临时选择,`previous_target_closed` 表示原默认页已关闭并清除选择,`failed`
243
+ 表示恢复或清理失败并清除临时选择;`error` 与 `cleanupError` 分别保存对应错误信息
244
+
245
+ 主动作结果或原错误保留,已完成的输入不会重放,也不会报为未执行;`browse attach` 与 `manage adoptPage`
246
+ 继续持久选择默认目标,并发响应记录各自实际操作的页面
247
+
248
+ `browse.list` 返回各页面的 revision 和元数据。revision 由 backend
249
+ epoch 与单页计数构成;Extension 跟踪主 frame 导航和 MCP 动作,CDP 跟踪已附加页面的导航,并保守计入发出的变更命令,包括 evaluate。网页自身的任意 DOM 更改不在跟踪范围内,条件动作前应重新获取 URL/revision。`browse`
250
+ 导航/关闭、`input`、`evaluate` 及适用的 `manage` 页面动作接受 `expectedUrl` 和
251
+ `expectedRevision`;backend 检查不符时返回
252
+ `ACTION_PRECONDITION_FAILED`,不发送对应页面动作,复合动作在首个变更命令前检查,不在每个事件前重复检查;失败或超时后如已产生部分效果,revision 仍可能变化
253
+
254
+ `browse` 仅 `open`、`back`、`forward`、`refresh`、`close` 接受这两个条件,`attach` 等其他动作在改变目标前返回
255
+ `INVALID_ARGUMENT`
256
+
257
+ 显式 `manage(action="adoptPage", targetId=...)` 将已有页面设为完整受控页,不聚焦或导航,`browse attach`
258
+ 只选择目标;创建来源、分组归属和颜色不决定页面权限,`releasePage`
259
+ 撤销完整权限,保留页面、窗口归属和分组,清理 MCP 日志状态、debugger 和 console 采集资源;Chrome 阻止资源清理时返回
260
+ `warnings`,完整权限仍被撤销
261
+
262
+ 受控页在 Service Worker 重启后可继续使用本 Extension 已有的调试连接,其他调试器占用仍返回 `DEBUGGER_BLOCKED`
263
+
264
+ 通过 `manage(action="grantReadAccess", targetId=...)` 授予普通读取权限,用 `revokeReadAccess`
265
+ 撤销,无需点击 popup;两个动作必须显式指定目标,可传
266
+ `expectedUrl`/`expectedRevision`;授权限定当前调用服务器实例、documentId、URL 和 revision,存储失败返回错误,不报告授权成功;popup 保留为可选入口,同一连接和文档未变化时,Service
267
+ Worker 重启后仍可读取;导航、关闭页面或断开连接后授权失效,仅指定 `targetId`
268
+ 不授予读取权限;普通只读授权覆盖定向文本、HTML、属性、计算样式及页面状态读取,任意脚本、debugger、截图、输入和 Cookie 访问不继承授权,现有 Cookie 工具仍按独立的 URL/name 过滤规则执行
269
+
270
+ 页面管理或导航因缺少受控权限而被拒绝时,不更新 revision,已有有效的普通只读授权保持不变
271
+
272
+ `manage(action="pageMetadata", targetId=...)` 可以读取或更新
273
+ `taskHint`、`note`,列表还会显示创建与最近使用时间;读取和更新都支持 `expectedUrl`/`expectedRevision`,不匹配时返回
274
+ `ACTION_PRECONDITION_FAILED`,不读取或更新备注;这些元数据只在服务器进程中保存,关闭页面时删除,不参与内容读取授权
167
275
 
168
276
  ### 访问验证
169
277
 
170
278
  `open`、`back`、`forward`、`refresh`、`input` 和 `evaluate` 之后,MCP Chrome 会等待 Cloudflare JS Challenge 或 Turnstile
171
279
  checkbox。Extension 模式下,导航先不启用 debugger 日志采集,连续八秒被动读取真实 tab 标题。interstitial 持续存在时,才检查可见 Turnstile 控件,找到后才点击。Extension
172
280
  inspect 走 isolated world,检查前先卸掉 debugger。同页测试按钮走页面点击;出现 Cloudflare Turnstile
173
- iframe 时,把 inspect 的 CSS 坐标换成屏幕坐标,系统鼠标沿路径移动、悬停后再按下抬起:Linux 用
174
- `xdotool`,并以当前 X11 活动窗口原点加窗口边距为准,且窗口标题必须对应该测试页,不用 Chrome `screenX`,也不用
175
- `outerHeight - innerHeight` 当顶栏;macOS 用 `cliclick` 或 System Events;Windows 用 PowerShell
281
+ iframe 时,把 inspect 的 CSS 坐标换成屏幕坐标,系统鼠标沿路径移动、悬停后再按下抬起:Linux 用 `xdotool` 读取活动 Chrome
282
+ client 窗口几何,用 `xprop` 读取 GTK frame
283
+ extents,窗口标题必须对应该测试页缺少工具、窗口数据无效或与页面视口不符时停止点击,不用 Chrome `screenX` 或
284
+ `outerHeight - innerHeight` 猜测内容原点;macOS 用 `cliclick` 或 System Events;Windows 用 PowerShell
176
285
  `mouse_event`。widget 点 compact
177
286
  Turnstile 卡片左侧 checkbox,宿主 wrapper 比卡片宽时也只点左侧卡片,不点文案。DOM 里已有 Cloudflare
178
287
  iframe 时,即使 iframe 尺寸为 0,也走系统鼠标,不改用页面点击,后续宿主页 `Verify you are human` / `请验证您是真人`
@@ -180,14 +289,15 @@ iframe 时,即使 iframe 尺寸为 0,也走系统鼠标,不改用页面点
180
289
 
181
290
  系统点击前会卸掉 debugger,再读一次视口。缺少系统鼠标工具或窗口未聚焦时返回可见错误,不会静默改用 CDP 点击。
182
291
 
183
- widget 要连续两次 inspect 到同一坐标才点;系统鼠标从远处过来时从控件附近起步。同一类 checkbox 或 compact
292
+ widget 要连续两次 inspect 到同一坐标才点,不以普通元素的尺寸认定 widget;系统鼠标从远处过来时从控件附近起步。同一类 checkbox 或 compact
184
293
  widget 在同一次等待里最多点一次;Cloudflare 随后换成可见的 `Verify you are human` 或 `请验证您是真人`
185
294
  按钮时,inspect 判成 `verify` 后再点一次。访问受 Cloudflare 保护的页面默认保持
186
295
  `diagnostics=false`,因为 diagnostics 会启用 debugger 的 console 和 network 采集。
187
296
 
188
297
  检测覆盖 `Just a moment...`、`请稍候…` 等标题、Challenge DOM、正文标记和 `Verify you are human` / `请验证您是真人`
189
- 控件。CDP 用 `Target.getTargetInfo` 读取实时标题。页面恢复后残留的 Cloudflare
190
- iframe 不算等待中,缓存标题不参与判定。不会调用 CAPTCHA solver、不会自动重试导航,也不会导出 `cf_clearance`
298
+ 控件,包括精确匹配这两种文案的可见 `button` 元素;没有 Cloudflare iframe 时,同页按钮使用页面点击 CDP 用
299
+ `Target.getTargetInfo` 读取实时标题。页面恢复后残留的 Cloudflare iframe 不算等待中,缓存标题不参与判定。不会调用 CAPTCHA
300
+ solver、不会自动重试导航,也不会导出 `cf_clearance`
191
301
  的值。CDP 超时不代表网站在用户真实 Chrome 中无法通过,排查网站前先检查返回的 `mode`。
192
302
 
193
303
  过盾成功时返回 `challengeResolved=true`、`challengeKind`、`waitedMs`、`clickedTurnstile` 和 `clearanceCookiePresent`
@@ -196,7 +306,7 @@ iframe 不算等待中,缓存标题不参与判定。不会调用 CAPTCHA solv
196
306
  的标题)不算过盾,可见 Turnstile 勾选框仍视为等待中。Challenge 成功和失败响应都含 `mode`。超时返回 `CHALLENGE_TIMEOUT`
197
307
  且 `retryable=true`,并带 `clickedTurnstile` 和实际观察到的 `challengeKind`(点过 Turnstile 时不会报成 `js`)。Access
198
308
  denied 返回 `CHALLENGE_DENIED`。交互式验证码、Bot Fight
199
- Mode 和 IP 声誉检查无法靠等待或点击 checkbox 完成。之后的正常主文档响应才会清掉 header 标记,清空网络日志不会清掉它,
309
+ Mode 和 IP 声誉检查无法靠等待或点击 checkbox 完成。之后的正常主文档响应才会清掉 header 标记,普通 iframe 文档响应和清空网络日志都不会清掉它,
200
310
 
201
311
  ### input - 键鼠输入
202
312
 
@@ -222,17 +332,40 @@ Mode 和 IP 声誉检查无法靠等待或点击 checkbox 完成。之后的正
222
332
  `events` 至少需要一个事件。参数:`humanize` 启用贝塞尔曲线移动和随机延迟,`diagnostics=true` 返回动作后新增 console
223
333
  warning/error 和失败网络请求, `postCondition`
224
334
  会在事件发送后等待页面状态,便于区分输入事件已发送和页面业务状态已完成,`postCondition.timeout` 默认 3000 ms、最大 60000
225
- ms,`postCondition.interval` 默认 100 ms、范围 50-5000 ms,`tabId` 指定目标 Tab,`frame`
226
- 指定目标 iframe(CSS 选择器或索引),均限 Extension 模式,传入任一作用域时,动作、诊断和 post-condition 使用该目标作用域选定的同一个 backend,
335
+ ms,`postCondition.interval` 默认 100 ms、范围 50-5000 ms。`postCondition.script` 可传表达式、函数、async
336
+ function 或 Promise 表达式;函数会被调用,最终 Promise 值会被等待后再判定,抛错或 reject 会让检查失败。`targetId`(或旧版
337
+ `tabId`)在两种 backend 中指定页面;`frame`
338
+ 在 Extension 模式中指定 iframe(CSS 选择器或索引),传入任一作用域时,动作、诊断和 post-condition 使用该目标作用域选定的同一个 backend,
339
+
340
+ 键盘 `type` 的 `timeout` 包含 Challenge 等待、焦点准备、字符输入和 `delay`/`humanize` 延迟,Extension
341
+ precise/stealth 与 CDP 使用本次剩余预算,显式预算如 `timeout=45000`
342
+ 允许合法输入持续超过默认的 30000ms,到期后停止后续字符与事件;已派发的输入不能撤回,超时可能留下部分输入,响应为
343
+ `actionExecuted=true`、`actionStatus="unknown"` 和 `retryable=false` 时,应独立读取页面确认实际值,不重放整个事件序列
344
+
345
+ 鼠标目标查找、分步移动和 `humanize`
346
+ 延迟也共用 input 剩余预算,每次移动和后续点击前检查截止时间,到期后停止后续移动和点击;已派发的原生事件不能撤回,结果为 unknown 时独立读取页面,不重放操作
347
+
348
+ 命令聚焦、文本选择和替换共用事件剩余预算,到期后停止后续动作;Shift 按下后仍尝试释放,释放失败不隐藏原动作错误,CDP 分步触摸移动到期后也停止后续触摸点与事件
349
+
350
+ Stealth 的 `delay` 只作用于字符之间,首字符不额外等待;后台页面受定时器节流时,后续间隔会延长,本次预算仍限制后续输入
227
351
 
228
- **`click` 专属参数**:`force: true` 跳过可操作性检查(适用于测试隐藏元素等场景),可操作性失败返回
352
+ Extension precise 与 CDP 的键盘输入使用当前光标和选区,提供 `target`
353
+ 会先点击目标并改变插入位置,向 contenteditable 末尾追加时,先聚焦并将光标放到末尾,再发送不带 `target` 的
354
+ `type`,避免再次点击改变位置
355
+
356
+ 后台 CDP 点击和键盘输入无需激活页面,仍检查元素是否可见、可用且位置和尺寸稳定,必要时滚动到视口;点击还会检查遮挡目标查找、可操作性检查和最终坐标读取共用事件剩余预算,任一阶段耗尽预算后不派发鼠标或键盘事件
357
+
358
+ **`click` 专属参数**:`force: true` 必须提供 `forceReason` 和非坐标型元素
359
+ `target`,它会跳过可操作性检查(适用于测试隐藏元素等场景),但仍只分发标准 DOM 鼠标事件序列,不会直接调用框架私有 handler 中键、右键和多击采用同一检查规则,坐标型或省略 target 的点击不能使用 force,可操作性失败返回
229
360
  `ACTIONABILITY_FAILED`,包含 `rect`、`clickPoint`、遮挡元素、候选遮挡物和修复建议, **`type`
230
361
  专属参数**:`mode="controlled"` 或 `dispatch: true` 直接设置 `.value` 并触发 `input`/`change`
231
362
  事件,兼容 React/Vue 等框架的受控组件(键盘事件无法触发状态更新时使用),需要非坐标型
232
- `target`,仅限 Extension 模式,受控输入和目标查找失败时返回结构化 context,包含 `target`、`matchCount`、`nth`、
233
- `activeElement`、`selection` 和候选控件,password input 的 value 不进入失败诊断, 失败响应也会脱敏 input 事件传入的
234
- `find` 和替换 `text`,`select` 和 `replace` 的事件级 `nth` 表示文本第 N 次出现,嵌套的 `target.nth`
235
- 表示第 N 个目标元素,两者都从 0 开始并可同时使用,CDP 模式的 locator target 不依赖 Extension refId,
363
+ `target`,仅限 Extension 模式,受控输入和目标查找失败时返回结构化 context,包含
364
+ `locator`、`matchCount`、`nth`、有数量上限的 `candidates` 和不含输入值的 `activeElement`
365
+ 摘要,焦点不可取得时返回 null,DOM 查询失败时还返回 `diagnosticError` 选区相关错误另含编辑器与选区状态,password
366
+ input 的 value 不进入失败诊断,失败响应也会脱敏 input 事件传入的 `find` 和替换 `text`,`select` 和 `replace` 的事件级
367
+ `nth` 表示文本第 N 次出现,嵌套的 `target.nth` 表示第 N 个目标元素,两者都从 0 开始并可同时使用,CDP 模式的 locator
368
+ target 不依赖 Extension refId,
236
369
 
237
370
  **`keydown` 专属参数**:
238
371
 
@@ -253,17 +386,30 @@ ms,`postCondition.interval` 默认 100 ms、范围 50-5000 ms,`tabId` 指定
253
386
  | `state` | 获取页面状态(URL、标题、可交互元素) |
254
387
  | `metadata` | 提取页面元信息(标题、OG、JSON-LD 等) |
255
388
 
389
+ 文本提取对整页和所选 HTML 元素使用浏览器的 `innerText`,已渲染区域不包含后代 `style`/`script`
390
+ 源码或隐藏后代文本;显式选择不可渲染的 HTML 元素时遵循浏览器 `innerText` 规则,SVG/XML 节点使用
391
+ `textContent`,源码请使用 `html`
392
+
256
393
  参数:`output` 将结果保存到文件(`images=data` 时为输出目录),`images`(`info`/`data`)提取 HTML 中的图片元信息或数据,
257
394
  `frameHtml` 在 `frame` 路由后提取当前 iframe 文档,截图支持 `clip` 坐标区域、`compareWith` PNG 基准对比和 `diffOutput`
258
395
  差异图输出,`diffOutput` 必须同时传 `compareWith`。指定 `target` 的截图未匹配、`nth`
259
396
  越界或尺寸为零时返回目标错误,不会静默返回视口截图,截图响应包含
260
397
  `metadata.format`、`width`、`height`、`dimensionSource`、`byteSize`、`fullPage`、`scale`、`clip` 和
261
- `capabilities`,PNG 对比在解码前限制为单个 PNG 25 MiB 和 12,000,000 像素,超出时使用 `clip` 或 `scale`
262
- 缩小截图,Extension hidden tab 截图返回 `HIDDEN_TAB_SCREENSHOT`,不会自动切前台,`state` 返回
263
- `interactiveElements`,Extension 和 CDP 模式下 `metadata` 都返回
264
- `frames`,如果其他 debugger 占用 precise 截图路径,可视区域 fallback 会返回 `degraded`、`fallback` 和
265
- `limitations`;fallback 不支持的参数返回结构化 `SCREENSHOT_FALLBACK_UNSUPPORTED`,`tabId` 指定目标 Tab,`frame`
266
- 指定目标 iframe,均限 Extension 模式,
398
+ `capabilities`。截图在执行前限制单边 16,384 像素、总计 12,000,000 像素、预计 RGBA 内存 48 MiB 和编码数据 25
399
+ MiB;基准 PNG 在读取前检查文件大小,对比在解码前限制单个 PNG 25
400
+ MiB 和 12,000,000 像素,解压时按已校验尺寸限制输出,并要求 scanline 长度精确匹配;损坏或异常膨胀的 PNG 会被拒绝,较大截图应使用
401
+ `clip` 或 `scale` 缩小,截图与 diagnosticBundle 在 Extension 和 CDP 模式中都返回
402
+ `hiddenTabScreenshot=false`,Extension 隐藏页截图返回 `HIDDEN_TAB_SCREENSHOT`,不自动激活,`state` 返回
403
+ `interactiveElements`,Extension 和 CDP 模式下 `metadata` 都返回 `frames` 和实际文档 `url`,Extension 指定 `frame`
404
+ 时返回该 iframe 文档地址;CDP 无法取得的已声明帧字段保留为 `null`,包括 DOM
405
+ selector 和所属元素 rect,帧树顺序与 ID 保持不变;元信息还返回页面当前的 `managed` 状态与 `metadata` 对象,其
406
+ `createdBy`、`createdAt`、`lastUsedAt`、`taskHint` 和 `note` 与 `browse list`、`manage pageMetadata`
407
+ 一致,inline 与文件输出包含相同字段;`frame` 指定 iframe 文档时,备注仍属于该页面,`managed`
408
+ 表示 Extension 页面托管状态,CDP 返回 false,不限制已连接 CDP 的正常操作,备注只保存在当前 Server 进程,未知创建来源返回
409
+ `unknown`,其他 Server 不继承这些备注,不能据此判断跨会话归属或取得权限;如果其他 debugger 占用 precise 截图路径,可视区域 fallback 会返回
410
+ `degraded`、`fallback` 和 `limitations`;fallback 不支持的参数返回结构化
411
+ `SCREENSHOT_FALLBACK_UNSUPPORTED`,`targetId`(或旧版 `tabId`)在两种 backend 中指定页面,`frame`
412
+ 仅在 Extension 模式中指定 iframe,
267
413
 
268
414
  **`attribute` 特殊前缀**:`computed:<属性名>` 返回 computed CSS 样式值(如 `computed:color`、`computed:font-size`),
269
415
  `computed:*` 返回全部计算样式(300+ 属性,建议配合 `output` 写文件),
@@ -281,7 +427,10 @@ style 的扁平节点数组,便于二次处理),
281
427
  | `time` | 固定延迟 |
282
428
  | `idle` | 等待 DOM 或网络静默期 |
283
429
 
284
- 参数:`tabId` 指定目标 Tab,`frame` 指定目标 iframe,均限 Extension 模式,
430
+ 参数:`targetId`(或旧版 `tabId`)在两种 backend 中指定页面,`frame` 在 Extension 模式中指定 iframe,
431
+
432
+ CDP 模式的 `visible` 要求 DOM 矩形宽高非零,且 CSS 不隐藏元素(`display:none` 或 `visibility:hidden/collapse`) `hidden`
433
+ 接受这些隐藏状态或元素不存在,`attached` 和 `detached` 只检查元素是否存在
285
434
 
286
435
  **`idle` 说明**:Extension 模式会在 `readyState === 'complete'` 后注入 `MutationObserver`,等待 `ms`
287
436
  毫秒内无 DOM 变更;CDP 模式等待网络静默。两种模式的默认 `ms` 都是 500ms,响应返回 `idleKind` 和
@@ -291,19 +440,19 @@ style 的扁平节点数组,便于二次处理),
291
440
 
292
441
  在页面上下文执行 JavaScript,
293
442
 
294
- | 参数 | 描述 |
295
- | ------------------- | ------------------------------------------------------- |
296
- | `script` | JavaScript 代码,裸 `return` 语句自动包裹 IIFE |
297
- | `scriptFile` | 从本地文件读取脚本,与 `script` 二选一 |
298
- | `args` | 传递给脚本的参数,script 须为函数表达式 |
299
- | `mode` | `precise`(默认,debugger API)或 `stealth`(JS 注入) |
300
- | `staleContextRetry` | iframe stale context 策略,`never`(默认)或 `readOnly` |
301
- | `output` | 将结果保存到文件 |
302
- | `tabId` | 指定目标 Tab(Extension 模式) |
303
- | `frame` | 指定目标 iframe(CSS 选择器或索引,Extension 模式) |
304
- | `timeout` | 端到端超时预算(毫秒) |
305
- | `diagnostics` | 执行后返回新增 console warning/error 和失败网络请求摘要 |
306
- | `postCondition` | 执行后等待文本、selector、URL 片段或脚本结果匹配 |
443
+ | 参数 | 描述 |
444
+ | -------------------- | ------------------------------------------------------- |
445
+ | `script` | JavaScript 代码,裸 `return` 语句自动包裹 IIFE |
446
+ | `scriptFile` | 从本地文件读取脚本,与 `script` 二选一 |
447
+ | `args` | 函数参数,`[]` 调用零参函数;省略时按原脚本语义执行 |
448
+ | `mode` | `precise`(默认,debugger API)或 `stealth`(JS 注入) |
449
+ | `staleContextRetry` | iframe stale context 策略,`never`(默认)或 `readOnly` |
450
+ | `output` | 将结果保存到文件 |
451
+ | `targetId` / `tabId` | 在两种 backend 中指定页面(`tabId` 为兼容别名) |
452
+ | `frame` | 指定目标 iframe(CSS 选择器或索引,Extension 模式) |
453
+ | `timeout` | 端到端超时预算(毫秒) |
454
+ | `diagnostics` | 执行后返回新增 console warning/error 和失败网络请求摘要 |
455
+ | `postCondition` | 执行后等待文本、selector、URL 片段或脚本结果匹配 |
307
456
 
308
457
  `script` 和 `scriptFile` 至少提供一个,互斥使用,相对 `scriptFile` 和 `output` 路径默认写到 `mcp-chrome`
309
458
  管理的系统临时目录,需要把文件留在当前工作目录时,用 `cwd:relative/path` 显式指定,相对路径会拒绝
@@ -320,36 +469,83 @@ precise 执行默认不在 execution context 失效后重放脚本,只有脚
320
469
  发出后发生 stale context 时返回
321
470
  `actionExecuted=true`、`actionStatus="unknown"`,因为脚本可能已经产生部分副作用,但无法取得最终结果,
322
471
 
472
+ Extension precise 主 frame 的对象结果,显式指定 `output` 时字符预算为 16
473
+ Mi(16777216),未指定时保留 1000000,自动保存仍受该上限约束。两条路径均保留深度 8、节点 2000 和不可序列化结果拒绝,字符预算按 UTF-16
474
+ code units 计,不等于输出文件的 UTF-8 字节数;`tmp:`
475
+ 文件还受临时输出配额约束。超限返回当前上限,并保留脚本已完成、输出失败的状态,不重放脚本。
476
+
323
477
  ### manage - 页面与环境管理
324
478
 
325
- | Action | 描述 |
326
- | -------------- | ------------------------------------------------ |
327
- | `newPage` | 新建受控页面/Tab |
328
- | `closePage` | 关闭受控页面并返回 `affected.before/after` |
329
- | `adoptPage` | 将已有 Tab 标记为受控页,不切前台 |
330
- | `releasePage` | 将受控页移出管理,不关闭页面 |
331
- | `movePage` | 将受控 Tab 移到指定窗口或 index |
332
- | `reorderPage` | 调整受控 Tab 在当前窗口内的顺序 |
333
- | `pinPage` | 固定受控 Tab |
334
- | `unpinPage` | 取消固定受控 Tab |
335
- | `activatePage` | 激活受控 Tab 并聚焦所在窗口 |
336
- | `focusWindow` | 聚焦显式指定的窗口 |
337
- | `resizeWindow` | 调整显式指定窗口的尺寸或状态 |
338
- | `newWindow` | 新建受控窗口 |
339
- | `closeWindow` | 仅当窗口内全是 managed tab 时关闭窗口 |
340
- | `clearCache` | 清除缓存/存储(清除 Cookie 请用 `cookies` 工具) |
341
- | `viewport` | 设置视口大小 |
342
- | `userAgent` | 设置 User-Agent |
343
- | `emulate` | 设备模拟(iPhone、iPad 等) |
344
- | `inputMode` | 查询或设置输入模式(`precise` / `stealth`) |
345
- | `stealth` | 注入反检测脚本 |
346
- | `cdp` | 发送原始 CDP 命令(高级,如 `Runtime.evaluate`) |
347
-
348
- Tab/window 管理动作仅支持 Extension 模式,改变浏览器可见状态的动作必须显式传 `targetId` 或 `windowId`,并返回
349
- `affected.before/after`。Extension 模式不支持 `clearCache`,会返回 `UNSUPPORTED_MODE` 且不清除任何内容;清 Cookie 请用带
479
+ | Action | 描述 |
480
+ | ------------------ | ------------------------------------------------ |
481
+ | `newPage` | 新建受控页面/Tab |
482
+ | `pageMetadata` | 读取或设置页面的 `taskHint`、`note` |
483
+ | `closePage` | 关闭受控页面并返回 `affected.before/after` |
484
+ | `adoptPage` | 授予已有 Tab 完整受控能力,不改变前台 |
485
+ | `releasePage` | 将受控页移出管理,不关闭页面 |
486
+ | `grantReadAccess` | 为当前调用实例授予显式页面的普通只读权限 |
487
+ | `revokeReadAccess` | 撤销当前调用实例的普通只读授权 |
488
+ | `updatePage` | 更新原生 tab 属性并返回实际状态 |
489
+ | `movePage` | 将受控 Tab 移到指定窗口或 index |
490
+ | `reorderPage` | 调整受控 Tab 在当前窗口内的顺序 |
491
+ | `pinPage` | 固定受控 Tab |
492
+ | `unpinPage` | 取消固定受控 Tab |
493
+ | `activatePage` | 激活受控 Tab 并聚焦所在窗口 |
494
+ | `focusWindow` | 聚焦显式指定的窗口 |
495
+ | `resizeWindow` | 调整显式指定窗口的尺寸或状态 |
496
+ | `newWindow` | 新建受控窗口 |
497
+ | `closeWindow` | 仅当窗口内全是 managed tab 时关闭窗口 |
498
+ | `updateWindow` | 更新原生窗口位置、状态、焦点或提醒 |
499
+ | `groupPages` | 创建分组或将受控页加入已有分组 |
500
+ | `ungroupPages` | 解除分组归属,保留受控权限 |
501
+ | `updateGroup` | 更新分组名称、颜色和折叠状态 |
502
+ | `moveGroup` | 将分组及其成员移动到指定窗口或位置 |
503
+ | `clearCache` | 清除缓存/存储(清除 Cookie 请用 `cookies` 工具) |
504
+ | `viewport` | 设置视口大小 |
505
+ | `userAgent` | 设置 User-Agent |
506
+ | `emulate` | 设备模拟(iPhone、iPad 等) |
507
+ | `inputMode` | 查询或设置输入模式(`precise` / `stealth`) |
508
+ | `stealth` | 注入反检测脚本 |
509
+ | `cdp` | 发送原始 CDP 命令(高级,如 `Runtime.evaluate`) |
510
+
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 请用带
350
515
  `url` 或 `domain` 过滤的 `cookies(action="clear")`,清 storage 或 cache 请改用 CDP 模式。`focusWindow`
351
516
  只有在观测到目标窗口已聚焦后才返回成功,否则返回 `WINDOW_FOCUS_NOT_OBSERVED`,`closeWindow`
352
- 遇到混有非托管 tab 的窗口会返回 `WINDOW_HAS_UNMANAGED_TABS`
517
+ 遇到混有非托管 tab 的窗口会返回 `WINDOW_HAS_UNMANAGED_TABS`。持久的 `adoptPage`、`releasePage`
518
+ 目标变更与指定 tab 的操作串行执行,并发多事件 input 会始终留在指定 tab,持久目标变更会在该操作结束后生效
519
+
520
+ | 动作 | 原生参数 | 行为 |
521
+ | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
522
+ | `newPage` | `url`、`windowId`、`index`、`active`、`pinned`、`openerTabId`、`groupId`、`timeout` | `active` 默认 false,`groupId=-1` 不分组,显式位置不受默认显示分组改变 |
523
+ | `updatePage` | `url`、`active`、`pinned`、`highlighted`、`muted`、`autoDiscardable`、`openerTabId` | 必须传 `targetId`,只支持 `active=true` 且不聚焦窗口,`active=false` 在任何更新前拒绝 |
524
+ | `groupPages` | `targetIds`、`groupId`、`windowId`、`title`、`color`、`collapsed` | 省略 `groupId` 时在成员原窗口创建分组,跨窗口成员须指定 `windowId`,加入已有组仅传 `targetIds/groupId` |
525
+ | `ungroupPages` | `targetIds` | 解除分组,保留受控能力 |
526
+ | `updateGroup` | `groupId`、`title`、`color`、`collapsed` | 空名称及 false 折叠值按原值设置 |
527
+ | `moveGroup` | `groupId`、`windowId`、`index` | 移动全部成员,`index=-1` 表示窗口末尾 |
528
+ | `newWindow` | `url` 或 `urls`、`targetId`、`windowType`、`focused`、`incognito`、`left`、`top`、`width`、`height`、`windowState`、`setSelfAsOpener` | normal 支持多 URL 及同时移入已有受控页,popup 只接受一个页面,所有新建页受控且分别记录创建来源 |
529
+ | `updateWindow` / `resizeWindow` | `windowId`、`left`、`top`、`width`、`height`、`windowState`、`focused`、`drawAttention` | 应用 Chrome 支持的窗口配置并返回观测状态 |
530
+
531
+ `updateWindow` 与 `resizeWindow` 修改状态或几何后等待浏览器观测稳定,非 normal 窗口同时请求 `windowState="normal"`
532
+ 和 bounds 时,状态转换完成后才应用一次几何参数,OS 调整后的几何按实际值返回有界等待内仍未观测到稳定状态时,`WINDOW_UPDATE_NOT_OBSERVED`
533
+ 返回部分执行状态及最后观测的窗口信息,再次更新前用 `browse list` 检查实际状态
534
+
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,颜色只属于分组,只读属性只回显,不作为写入参数列表操作不读取页面正文,不导航或改变焦点
540
+
541
+ 页面和分组移动接受
542
+ `index=-1`,新建页的 index 非负,来源 tab 与显式分组、窗口必须位于同一窗口,固定页不能在分组中创建窗口状态与位置/尺寸的冲突、动作不支持的字段在修改前拒绝,CDP 明确拒绝不支持的 Chrome
543
+ UI 配置,不静默忽略 `newWindow` 的 `url` 与 `urls` 是两种互斥输入方式,在 normal 窗口中可与 `targetId`
544
+ 同时使用 popup 只接受单个 URL 或一个已有页面,不能同时创建额外 URL 页面,明确的创建前拒绝保留
545
+ `actionExecuted=false`、`actionStatus="not_started"`、`failureStage="preflight"`,更新在执行前拒绝时保留原 revision,原生更新已派发后的失败仍使 revision 失效
546
+
547
+ `emulate` 在两个 backend 中设置设备视口、像素密度、触摸能力和 User-Agent,`viewport`
548
+ 恢复桌面视口与页面缩放并关闭触摸模拟,User-Agent 通过 `userAgent` 单独恢复
353
549
 
354
550
  **Stealth 模式档位**(CDP launch 参数,通过 `browse action=launch stealth=...` 设置):
355
551
 
@@ -365,14 +561,23 @@ Tab/window 管理动作仅支持 Extension 模式,改变浏览器可见状态
365
561
  | `network` | 网络请求日志(支持 URL 过滤) |
366
562
 
367
563
  参数:`output` 将结果保存到文件,console 日志统一返回公开级别 `error`、`warning`、`info`、`debug`,浏览器原始的 `warn`、
368
- `log` 等级会在过滤和返回前转换,network 日志包含已完成请求、HTTP 4xx/5xx 响应和加载失败请求,尽量返回
369
- `errorText`、`method`、 `url`、`status`、`timestamp`、`duration`,URL
564
+ `log` 等级会在过滤和返回前转换。清空 fallback
565
+ console 日志会保留 hook。debugger 采集恢复后,fallback 采集会停用;仍指向 MCP
566
+ wrapper 的 console 方法会恢复,页面之后安装的 wrapper 保持不变。network 日志在 `loadingFinished` 或 `loadingFailed`
567
+ 时才完成记录,不会在收到 headers 时提前结束,因此 body 失败会同时保留 HTTP status 和
568
+ `errorText`,传输中的 body 也会继续计入 `networkidle`。日志尽量返回 `method`、
569
+ `url`、`status`、`timestamp`、`duration`,URL
370
570
  query 中常见的认证、签名、密码和 token 参数会在内联响应、diagnostics 和 显式 `output` 文件中替换为 `[REDACTED]`,并返回
371
571
  `urlRedacted`、`urlOriginalLength` 和
372
572
  `redactedQueryParameters`,内联 network 结果会把脱敏后的单条 URL 限制为 2048 字符,截断时返回 `urlLength` 和
373
573
  `urlTruncated: true`,`urlPattern` 支持 `*` 匹配任意长度字符、`?` 匹配单个字符,`tabId`
374
574
  指定目标 Tab(Extension 模式),`frame` 不适用于日志,
375
575
 
576
+ Extension debugger 不可用时,network 每次读取都会刷新 performance 记录并标记
577
+ `source="performance"`;状态使用浏览器提供的 `responseStatus`,无法取得时为
578
+ `0`,未知请求方法保留空值,重复读取保留记录序列号;`clear`
579
+ 清除 MCP 记录并推进当前文档的读取边界,不清除网页共享的 performance 数据,新文档重新建立边界,读取失败返回错误,不冒充空日志
580
+
376
581
  ### cookies - Cookie 管理
377
582
 
378
583
  | Action | 描述 |
@@ -382,7 +587,8 @@ query 中常见的认证、签名、密码和 token 参数会在内联响应、d
382
587
  | `delete` | 删除 Cookie |
383
588
  | `clear` | 在 URL 或域名范围内删除 Cookie,可用 `name` 进一步过滤 |
384
589
 
385
- **说明**:`clear` 必须指定 `url` 或 `domain`。`name` 只能在该范围内进一步过滤,避免误删其他站点的同名 Cookie
590
+ **说明**:`clear` 必须指定 `url` 或 `domain`。`name` 只能在该范围内进一步过滤,避免误删其他站点的同名 Cookie。返回的
591
+ `count` 只统计 Chrome 确认已删除的 Cookie;列出后、删除前已消失的 Cookie 不计数
386
592
 
387
593
  ## Target:统一元素定位器
388
594
 
@@ -490,12 +696,27 @@ extract(type="html", target={ css: ".article" }, images="info")
490
696
 
491
697
  // 获取 HTML + 图片数据,保存到目录
492
698
  extract(type="html", images="data", output="tmp:page")
493
- // 生成:<系统临时目录>/claude-tools/mcp-chrome/page/content.html, images/*, index.json
699
+ // 生成:<系统临时目录>/claude-tools/mcp-chrome/session-<id>/page/content.html, images/*, index.json
494
700
 
495
701
  // 获取 HTML + 图片数据(内联返回,最多 20 张)
496
702
  extract(type="html", target={ css: ".card" }, images="data")
497
703
  ```
498
704
 
705
+ `tmp:` 路径属于当前 server 会话。临时输出整个会话最多 256 项、128
706
+ MiB;启动时只清理超过 24 小时且所属进程已退出的带归属标记目录。成功写入 `tmp:` 文件或目录的响应会返回 `retention`
707
+ 清理条件,`cwd:` 响应不带此字段。重启后仍需通过 MCP 访问的文件使用
708
+ `cwd:`。输出路径拒绝 Windows 保留设备名、ADS、非法字符以及末尾空格或点号;Windows 上写入敏感内容前须验证私有 DACL。
709
+
710
+ 路径语法错误返回 `INVALID_ARGUMENT`,允许 `.` 组件,继续拒绝 `..` 组件根目录外的路径及链接越界返回
711
+ `PATH_NOT_ALLOWED`,两类错误均在 `error.context.cwd` 返回 server 的实际工作目录,范围拒绝另返回 `allowedRoots` 使用
712
+ `cwd:` 指定相对于该目录的路径,或使用 `tmp:` 保存会话输出,`scriptFile` 与 `compareWith` 遵循相同校验
713
+
714
+ 配额拒绝返回 `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:` 指定仓库内路径。
719
+
499
720
  ### 页面元信息
500
721
 
501
722
  ```
@@ -522,7 +743,16 @@ input(events=[
522
743
 
523
744
  CSS 选择器和数字索引按父文档的 DOM
524
745
  iframe 顺序定位,DOM 中不存在的子 frame(包括其他 Extension 加入的 frame)不会改变索引,也不会成为候选目标,所选元素无法对应到唯一 Chrome
525
- frame 时返回 `FRAME_IDENTITY_UNAVAILABLE`,不会选择其他frame
746
+ frame 时返回 `FRAME_IDENTITY_UNAVAILABLE`,不会选择其他 frame;precise
747
+ evaluate 按含 query 和 fragment 的完整 URL 定位,并按所选 DOM iframe 区分 URL 相同的 frame,包括
748
+ `about:srcdoc`,无法确认身份时拒绝执行
749
+
750
+ frame 定位失败分别返回 `INVALID_FRAME_SELECTOR`、`FRAME_NOT_IFRAME` 或 `FRAME_NOT_FOUND`,读取注入区分
751
+ `INVALID_SELECTOR`、`FRAME_STALE_CONTEXT`、`FRAME_INJECTION_DENIED`、`FRAME_SCRIPT_FAILED`、 `FRAME_INJECTION_FAILED` 和
752
+ `FRAME_SCRIPT_NO_RESULT`,并报告注入或脚本结果阶段,无结果不等于 selector 非法,空文本、空元素数组、null 属性值和 void 脚本调用保持原语义,错误不会重放脚本;成功定位后的读取失败在
753
+ `pageContext.frameContext` 保留 DOM 索引、Chrome frame ID 和可取得的文档身份;frame
754
+ URL 诊断去掉认证、query 和 fragment,长度限制为 500 字符,`data:` 与 `javascript:` 只返回协议;无法解析的 URL 返回
755
+ `url=null` 和 `urlStatus="unavailable"`
526
756
 
527
757
  ### 等待元素
528
758
 
@@ -654,18 +884,28 @@ input 和 evaluate 返回值追加 `actionExecuted`、`actionStatus`、`verifica
654
884
  `retryable`。验证状态分为
655
885
  `matched`、`not_matched`、`unavailable`、`error`;debugger 超时且无法证明脚本已停止时,动作状态为
656
886
  `unknown`。页面脚本抛异常时返回 `actionExecuted=true` 和 `actionStatus="failed"`;结果展开或序列化失败时返回
657
- `actionStatus="completed"` 和 `failureStage="output"`。diagnostics 是附加能力,失败时返回
887
+ `actionStatus="completed"` 和 `failureStage="output"`。页面前置条件不符时,input 和 evaluate 返回
888
+ `actionExecuted=false`、`actionStatus="not_started"`。diagnostics 是附加能力,失败时返回
658
889
  `diagnosticsStatus`,不会覆盖主动作结果。browse 和 wait 的主动作失败时,也会保留失败前已收集的 diagnostics。目标诊断会读取当前 tab 的实时状态,不依赖 attach 时缓存的 URL 和标题。
659
890
 
891
+ 原生脚本终止,以及 CDP `Runtime` 脚本命令返回 `Internal error` 时,evaluate 和 `manage cdp` 保留原错误码,返回
892
+ `actionExecuted=true`、`actionStatus="unknown"`、`retryable=false`,不重放命令;evaluate 的执行中 RPC 超时或过期 execution
893
+ context 导致结果未知时也不可直接重试;执行开始前的超时仍可重试;页面主动抛出的同名异常仍按动作失败处理
894
+
895
+ Extension 的 accessibility state 不读取 password
896
+ value 生成元素名称,标签、placeholder、title 和普通输入值保留;显式脚本、HTML 和属性读取保持原有行为
897
+
660
898
  `replace` 仅对 `textarea` 以及 `text`、`search`、`tel`、`url`、`password`
661
899
  类型的 input 使用文本选区。其他 input 类型通过原生完整 value 更新,并返回请求值与浏览器规范化后的实际值。对不支持选区的类型单独执行
662
900
  `select` 会返回 `UNSUPPORTED_SELECTION`。CDP模式下,`select` 和 `replace` 的 locator target 通过 CDP
663
901
  locator 聚焦,不调用 Extension refId。password value 不进入 input 失败 context 和 text
664
- post-condition 观测值,失败响应还会脱敏传入的 `find` 和替换
665
- `text`。目标超时返回限量的locator、tab、frame、匹配数和候选上下文。显式 `tabId` 或 `frame`
902
+ post-condition 观测值,失败响应还会脱敏传入的 `find` 和替换 `text`。password 的 `select`/`replace`
903
+ 成功和失败响应均隐藏 console 与 network 诊断正文,返回 `diagnostics.redacted=true` 和
904
+ `reason="sensitive_input_or_unresolved_target"`;无法安全确认选择目标时也隐藏这些正文普通输入保留诊断,密码保护仅持续到当前 input 请求结束目标超时返回限量的locator、tab、frame、匹配数和候选上下文。显式
905
+ `tabId` 或 `frame`
666
906
  作用域会在 input、wait、logs、extract 开始前确定活动 backend,动作和验证使用同一个目标 backend。precise iframe
667
907
  evaluate 默认使用 `staleContextRetry="never"`,context 失效时不重放脚本; `readOnly` 允许 Extension 校验 frame
668
908
  identity 并解析新 execution context 后重放一次。响应包含策略、`retryAttempted`、限量的 `retryReason`,以及最终 Extension
669
- frame、parent frame、URL、CDP frame 和 execution context ID 组成的
670
- `frameContext`,重复 URL 导致 frame 不唯一时拒绝选择任一 frame。端口扫描会把普通的 WebSocket
671
- open 前失败聚合为 debug;已识别 MCP server 的认证或协议拒绝只在摘要变化时输出一条限量 warning。
909
+ frame、parent frame、URL、CDP frame 和 execution context ID 组成的 `frameContext`,URL 相同的 frame 仅在所选 DOM
910
+ iframe 无法唯一确认目标时拒绝执行;Extension 重载后可继续访问原页面中的 iframe,无需刷新或重新导航端口扫描会把普通的 WebSocket
911
+ open 前失败聚合为 debug;已识别 MCP server 的认证或协议拒绝只在摘要变化时输出一条限量 warning
@@ -54,10 +54,10 @@ const COMMON_BODY = `
54
54
  // 3. 修改 navigator.userAgent 中的 Headless 标识
55
55
  // ============================================
56
56
  try {
57
- const originalUserAgent = navigator.userAgent;
58
- if (originalUserAgent.includes('HeadlessChrome')) {
57
+ const userAgentGetter = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(navigator), 'userAgent')?.get;
58
+ if (userAgentGetter && userAgentGetter.call(navigator).includes('HeadlessChrome')) {
59
59
  Object.defineProperty(navigator, 'userAgent', {
60
- get: () => originalUserAgent.replace('HeadlessChrome', 'Chrome'),
60
+ get: () => userAgentGetter.call(navigator).replace('HeadlessChrome', 'Chrome'),
61
61
  configurable: true,
62
62
  });
63
63
  }
@@ -42,7 +42,7 @@ export declare class CDPClient extends EventEmitter {
42
42
  *
43
43
  * close()/handleClose() 会立即 reject 所有活跃的等待者,不必等 timer 超时
44
44
  */
45
- waitForEvent<T = unknown>(event: string, predicate?: (params: T) => boolean, timeout?: number, sessionId?: string): Promise<T>;
45
+ waitForEvent<T = unknown>(event: string, predicate?: (params: T) => boolean, timeout?: number, sessionId?: string, signal?: AbortSignal): Promise<T>;
46
46
  /**
47
47
  * 关闭连接
48
48
  *
@@ -1 +1 @@
1
- {"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/cdp/client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAA;AAwBrC;;GAEG;AACH,KAAK,gBAAgB,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;AAErE;;GAEG;AACH,qBAAa,SAAU,SAAQ,YAAY;IACvC,aAAa;IACb,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,uBAAuB,CAAkB;IACjE,OAAO,CAAC,EAAE,CAAyB;IACnC,OAAO,CAAC,SAAS,CAAqC;IACtD,OAAO,CAAC,MAAM,CAAI;IAClB,OAAO,CAAC,cAAc,CAA2C;IACjE,OAAO,CAAC,kBAAkB,CAAyB;IAEnD,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED;;OAEG;IACG,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,SAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CA4CxE;IAED;;OAEG;IACG,IAAI,CAAC,CAAC,GAAG,OAAO,EAClB,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,MAAM,EACf,SAAS,CAAC,EAAE,MAAM,EAClB,OAAO,GAAE,MAA0C,GACpD,OAAO,CAAC,CAAC,CAAC,CA6CZ;IAED;;OAEG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CAKvD;IAED;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CAKxD;IAED;;;;OAIG;IACH,YAAY,CAAC,CAAC,GAAG,OAAO,EACpB,KAAK,EAAE,MAAM,EACb,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,OAAO,EAClC,OAAO,SAAkB,EACzB,SAAS,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,CAAC,CAAC,CA+BZ;IAED;;;;;OAKG;IACH,KAAK,IAAI,IAAI,CAUZ;IAED;;OAEG;IACH,OAAO,CAAC,aAAa;IAgDrB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAcxB;;OAEG;IACH,OAAO,CAAC,WAAW;CAStB;AAgCD;;GAEG;AACH,wBAAsB,oBAAoB,CACtC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,MAA6B,GACvC,OAAO,CAAC,MAAM,CAAC,CAGjB;AAED;;GAEG;AACH,wBAAsB,UAAU,CAC5B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,MAA6B,GACvC,OAAO,CAAC,KAAK,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,oBAAoB,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CAExG"}
1
+ {"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/cdp/client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAA;AAwBrC;;GAEG;AACH,KAAK,gBAAgB,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;AAErE;;GAEG;AACH,qBAAa,SAAU,SAAQ,YAAY;IACvC,aAAa;IACb,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,uBAAuB,CAAkB;IACjE,OAAO,CAAC,EAAE,CAAyB;IACnC,OAAO,CAAC,SAAS,CAAqC;IACtD,OAAO,CAAC,MAAM,CAAI;IAClB,OAAO,CAAC,cAAc,CAA2C;IACjE,OAAO,CAAC,kBAAkB,CAAyB;IAEnD,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED;;OAEG;IACG,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,SAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CA4CxE;IAED;;OAEG;IACG,IAAI,CAAC,CAAC,GAAG,OAAO,EAClB,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,MAAM,EACf,SAAS,CAAC,EAAE,MAAM,EAClB,OAAO,GAAE,MAA0C,GACpD,OAAO,CAAC,CAAC,CAAC,CA6CZ;IAED;;OAEG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CAKvD;IAED;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CAKxD;IAED;;;;OAIG;IACH,YAAY,CAAC,CAAC,GAAG,OAAO,EACpB,KAAK,EAAE,MAAM,EACb,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,OAAO,EAClC,OAAO,SAAkB,EACzB,SAAS,CAAC,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,WAAW,GACrB,OAAO,CAAC,CAAC,CAAC,CAwCZ;IAED;;;;;OAKG;IACH,KAAK,IAAI,IAAI,CAUZ;IAED;;OAEG;IACH,OAAO,CAAC,aAAa;IAgDrB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAcxB;;OAEG;IACH,OAAO,CAAC,WAAW;CAStB;AAiCD;;GAEG;AACH,wBAAsB,oBAAoB,CACtC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,MAA6B,GACvC,OAAO,CAAC,MAAM,CAAC,CAGjB;AAED;;GAEG;AACH,wBAAsB,UAAU,CAC5B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,MAA6B,GACvC,OAAO,CAAC,KAAK,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,oBAAoB,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CAExG"}