@pyrokine/mcp-chrome 2.4.0 → 2.4.4

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 +220 -149
  2. package/README_zh.md +245 -179
  3. package/dist/anti-detection/behavior.js +1 -1
  4. package/dist/anti-detection/behavior.js.map +1 -1
  5. package/dist/anti-detection/injection.d.ts.map +1 -1
  6. package/dist/anti-detection/injection.js +2 -1
  7. package/dist/anti-detection/injection.js.map +1 -1
  8. package/dist/cdp/client.d.ts +2 -2
  9. package/dist/cdp/client.d.ts.map +1 -1
  10. package/dist/cdp/client.js +7 -4
  11. package/dist/cdp/client.js.map +1 -1
  12. package/dist/core/browser-driver.d.ts +9 -3
  13. package/dist/core/browser-driver.d.ts.map +1 -1
  14. package/dist/core/browser-driver.js +1 -0
  15. package/dist/core/browser-driver.js.map +1 -1
  16. package/dist/core/errors.d.ts +9 -0
  17. package/dist/core/errors.d.ts.map +1 -1
  18. package/dist/core/errors.js +16 -1
  19. package/dist/core/errors.js.map +1 -1
  20. package/dist/core/os-mouse.d.ts +65 -0
  21. package/dist/core/os-mouse.d.ts.map +1 -0
  22. package/dist/core/os-mouse.js +334 -0
  23. package/dist/core/os-mouse.js.map +1 -0
  24. package/dist/core/session.d.ts +16 -6
  25. package/dist/core/session.d.ts.map +1 -1
  26. package/dist/core/session.js +160 -55
  27. package/dist/core/session.js.map +1 -1
  28. package/dist/core/types.d.ts +10 -0
  29. package/dist/core/types.d.ts.map +1 -1
  30. package/dist/core/types.js +2 -0
  31. package/dist/core/types.js.map +1 -1
  32. package/dist/core/unified-session.d.ts +34 -5
  33. package/dist/core/unified-session.d.ts.map +1 -1
  34. package/dist/core/unified-session.js +172 -30
  35. package/dist/core/unified-session.js.map +1 -1
  36. package/dist/extension/bridge.d.ts +24 -2
  37. package/dist/extension/bridge.d.ts.map +1 -1
  38. package/dist/extension/bridge.js +32 -1
  39. package/dist/extension/bridge.js.map +1 -1
  40. package/dist/extension/http-server.d.ts +17 -0
  41. package/dist/extension/http-server.d.ts.map +1 -1
  42. package/dist/extension/http-server.js +69 -9
  43. package/dist/extension/http-server.js.map +1 -1
  44. package/dist/extension/index.d.ts +1 -0
  45. package/dist/extension/index.d.ts.map +1 -1
  46. package/dist/extension/index.js.map +1 -1
  47. package/dist/tools/browse.d.ts +1 -1
  48. package/dist/tools/browse.d.ts.map +1 -1
  49. package/dist/tools/browse.js +73 -26
  50. package/dist/tools/browse.js.map +1 -1
  51. package/dist/tools/challenge.d.ts +153 -0
  52. package/dist/tools/challenge.d.ts.map +1 -0
  53. package/dist/tools/challenge.js +573 -0
  54. package/dist/tools/challenge.js.map +1 -0
  55. package/dist/tools/cookies.d.ts.map +1 -1
  56. package/dist/tools/cookies.js +8 -4
  57. package/dist/tools/cookies.js.map +1 -1
  58. package/dist/tools/diagnostics.d.ts +2 -2
  59. package/dist/tools/diagnostics.d.ts.map +1 -1
  60. package/dist/tools/diagnostics.js +28 -9
  61. package/dist/tools/diagnostics.js.map +1 -1
  62. package/dist/tools/evaluate.d.ts +8 -0
  63. package/dist/tools/evaluate.d.ts.map +1 -1
  64. package/dist/tools/evaluate.js +92 -14
  65. package/dist/tools/evaluate.js.map +1 -1
  66. package/dist/tools/extract.d.ts.map +1 -1
  67. package/dist/tools/extract.js +119 -59
  68. package/dist/tools/extract.js.map +1 -1
  69. package/dist/tools/input.d.ts +4 -0
  70. package/dist/tools/input.d.ts.map +1 -1
  71. package/dist/tools/input.js +248 -94
  72. package/dist/tools/input.js.map +1 -1
  73. package/dist/tools/logs.d.ts +7 -4
  74. package/dist/tools/logs.d.ts.map +1 -1
  75. package/dist/tools/logs.js +11 -8
  76. package/dist/tools/logs.js.map +1 -1
  77. package/dist/tools/manage.d.ts.map +1 -1
  78. package/dist/tools/manage.js +20 -7
  79. package/dist/tools/manage.js.map +1 -1
  80. package/dist/tools/network-sanitizer.d.ts +15 -0
  81. package/dist/tools/network-sanitizer.d.ts.map +1 -0
  82. package/dist/tools/network-sanitizer.js +62 -0
  83. package/dist/tools/network-sanitizer.js.map +1 -0
  84. package/dist/tools/png.js +5 -3
  85. package/dist/tools/png.js.map +1 -1
  86. package/dist/tools/post-condition.d.ts.map +1 -1
  87. package/dist/tools/post-condition.js +17 -4
  88. package/dist/tools/post-condition.js.map +1 -1
  89. package/dist/tools/target-diagnostics.d.ts +7 -0
  90. package/dist/tools/target-diagnostics.d.ts.map +1 -1
  91. package/dist/tools/target-diagnostics.js +25 -2
  92. package/dist/tools/target-diagnostics.js.map +1 -1
  93. package/dist/tools/wait.d.ts.map +1 -1
  94. package/dist/tools/wait.js +42 -40
  95. package/dist/tools/wait.js.map +1 -1
  96. package/extension/dist/assets/content.ts-Cj_iiU2s.js +25 -0
  97. package/extension/dist/assets/{index.ts-BMmrcSQ6.js → index.ts-Bqcu2qiN.js} +620 -290
  98. package/extension/dist/manifest.json +3 -3
  99. package/extension/dist/service-worker-loader.js +1 -1
  100. package/extension/dist/src/popup/popup.html +44 -44
  101. package/package.json +8 -7
  102. package/dist/extension/native-host-installer.d.ts +0 -21
  103. package/dist/extension/native-host-installer.d.ts.map +0 -1
  104. package/dist/extension/native-host-installer.js +0 -147
  105. package/dist/extension/native-host-installer.js.map +0 -1
  106. package/dist/extension/socket-server.d.ts +0 -32
  107. package/dist/extension/socket-server.d.ts.map +0 -1
  108. package/dist/extension/socket-server.js +0 -177
  109. package/dist/extension/socket-server.js.map +0 -1
  110. package/dist/extension/ws-server.d.ts +0 -40
  111. package/dist/extension/ws-server.d.ts.map +0 -1
  112. package/dist/extension/ws-server.js +0 -246
  113. package/dist/extension/ws-server.js.map +0 -1
  114. package/dist/native-host/index.js +0 -280
  115. package/dist/native-host/mcp-chrome-host +0 -2
  116. package/extension/dist/assets/content.ts-pEASbjEL.js +0 -6
package/README_zh.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  [English](README.md) | 中文
4
4
 
5
- Chrome 浏览器自动化 MCP Server,双模式架构:**Extension 模式**(推荐)操控现有浏览器,**CDP 模式**(回退)启动独立实例
5
+ Chrome 浏览器自动化 MCP Server,双模式架构: **Extension 模式**(推荐)操控现有浏览器, **CDP 模式**(回退)启动独立实例
6
6
 
7
7
  [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
8
8
  [![Node](https://img.shields.io/badge/node-%3E%3D20.19-green.svg)](https://nodejs.org/)
@@ -24,13 +24,13 @@ Chrome 浏览器自动化 MCP Server,双模式架构:**Extension 模式**(
24
24
 
25
25
  ## 兼容客户端
26
26
 
27
- | 客户端 | 状态 |
28
- |----------------|----|
29
- | Claude Code | ✅ |
30
- | Claude Desktop | ✅ |
31
- | Cursor | ✅ |
32
- | Windsurf | ✅ |
33
- | 其他 MCP 兼容客户端 | ✅ |
27
+ | 客户端 | 状态 |
28
+ | ------------------- | ---- |
29
+ | Claude Code | ✅ |
30
+ | Claude Desktop | ✅ |
31
+ | Cursor | ✅ |
32
+ | Windsurf | ✅ |
33
+ | 其他 MCP 兼容客户端 | ✅ |
34
34
 
35
35
  ## 安装
36
36
 
@@ -44,7 +44,8 @@ claude mcp add chrome -- mcp-chrome
44
44
  npm root -g
45
45
  ```
46
46
 
47
- Extension 模式需要打开 `chrome://extensions/`,启用开发者模式,点击“加载已解压的扩展程序”,选择 `<npm-root>/@pyrokine/mcp-chrome/extension/dist`。
47
+ Extension 模式需要打开 `chrome://extensions/`,启用开发者模式,点击“加载已解压的扩展程序”,选择
48
+ `<npm-root>/@pyrokine/mcp-chrome/extension/dist`。
48
49
 
49
50
  ### 从源码安装
50
51
 
@@ -87,20 +88,22 @@ Claude Desktop / 其他客户端:
87
88
 
88
89
  ```json
89
90
  {
90
- "mcpServers": {
91
- "chrome": {
92
- "command": "node",
93
- "args": [
94
- "/path/to/mcp-chrome/dist/index.js"
95
- ]
91
+ "mcpServers": {
92
+ "chrome": {
93
+ "command": "node",
94
+ "args": ["/path/to/mcp-chrome/dist/index.js"]
95
+ }
96
96
  }
97
- }
98
97
  }
99
98
  ```
100
99
 
101
100
  **第三步:连接**
102
101
 
103
102
  Extension 通过 HTTP/WebSocket 自动连接 MCP Server(端口 19222-19299),点击工具栏图标可查看连接状态,
103
+ `browse(action="connect")` 和本地 `/api/info`
104
+ 会返回当前活动 Extension 后台 bundle 的 hash,并与 server 附带的 bundle 比较, `bundleStatus="stale"`
105
+ 表示 Chrome 仍在执行旧的已解压 Extension,需要在 `chrome://extensions/` 刷新该 Extension。旧版 Extension 缺少
106
+ `network_challenge_state` 时会回退为 tab 标题和 DOM 的 Challenge 检测,bundle identity 不会关闭零配置自动连接,
104
107
 
105
108
  ```
106
109
  browse(action="list") // 列出所有 Tab
@@ -110,13 +113,15 @@ extract(type="screenshot")
110
113
 
111
114
  **配对 token**
112
115
 
113
- Extension 模式默认保留零配置本地自动连接,在多用户机器、CI runner、或不可信本地进程可访问 `127.0.0.1:19222-19299` 的容器环境中,启动 MCP server 时设置 `MCP_CHROME_PAIRING_TOKEN`,再在 Extension popup 中输入同一个 token:
116
+ Extension 模式默认保留零配置本地自动连接,在多用户机器、CI runner、或不可信本地进程可访问 `127.0.0.1:19222-19299`
117
+ 的容器环境中,启动 MCP server 时设置 `MCP_CHROME_PAIRING_TOKEN`,再在 Extension popup 中输入同一个 token:
114
118
 
115
119
  ```bash
116
120
  MCP_CHROME_PAIRING_TOKEN="your-token" node /path/to/mcp-chrome/dist/index.js
117
121
  ```
118
122
 
119
- 需要强制配对 token 时,在 server 设置 `MCP_CHROME_ALLOW_INSECURE_NO_TOKEN=0`,并在 Extension popup 关闭“允许无 token 本地连接”,
123
+ 需要强制配对 token 时,在 server 设置 `MCP_CHROME_ALLOW_INSECURE_NO_TOKEN=0`,并在 Extension
124
+ popup 关闭“允许无 token本地连接”,
120
125
 
121
126
  ### 模式二:CDP 模式(回退)
122
127
 
@@ -132,166 +137,219 @@ browse(action="connect", port=9222)
132
137
  browse(action="open", url="https://example.com")
133
138
  ```
134
139
 
135
- > Extension 已连接时,所有工具自动使用 Extension 模式,仅当 Extension 不可用时才激活 CDP 模式,
140
+ > 已连接的 Extension 是所有工具的默认模式,Extension 不可用时才回退到 CDP。`browse(action="connect", port=9222)`
141
+ > 会为后续工具显式选择 CDP;调用不带 port 的 `browse(action="connect")`
142
+ > 会回到 Extension。仅因回退而建立的 CDP 连接会在 Extension 重连后让出默认模式,
136
143
 
137
144
  ## 可用工具(8 个)
138
145
 
139
146
  ### browse - 浏览器管理与导航
140
147
 
141
- | Action | 描述 |
142
- |-----------|-----------------------|
143
- | `launch` | 启动新 Chrome 实例(CDP 模式) |
144
- | `connect` | 连接已运行的 Chrome(CDP 模式) |
145
- | `list` | 列出所有页面/Tab |
146
- | `attach` | 附加到指定页面/Tab |
147
- | `open` | 导航到 URL |
148
- | `back` | 后退 |
149
- | `forward` | 前进 |
150
- | `refresh` | 刷新 |
151
- | `close` | 关闭浏览器连接 |
152
-
153
- Extension 特有:`list` 返回 flat `targets` 数组和树状 `windows`,每个 target 含 `managed`(Tab 是否由 MCP Chrome 受控)、
154
- `isActive`(是否为当前操作目标)、
155
- `windowId`、`index`、`pinned`、`incognito`、`status`(`loading`/`complete`),树状结构含 `windowCount`、`focusedWindowId`、
156
- `activeTargetId` 和每个窗口按顺序排列的 `tabs`,可区分每个窗口内的 active tab 和当前人眼看到的 focused window 页面,`open`
157
- 自动创建 Tab 分组(cyan 色),`open`、`back`、`forward`、`refresh` 支持 `diagnostics=true`,返回动作期间新增的 console
158
- warning/error 和失败网络请求摘要,也覆盖首次 `open` 自动创建页面的场景,
148
+ | Action | 描述 |
149
+ | --------- | -------------------------------------------- |
150
+ | `launch` | Extension 可用时创建受控 Tab,否则启动 CDP |
151
+ | `connect` | 默认确认 Extension,传 `port` 时显式选择 CDP |
152
+ | `list` | 列出所有页面/Tab |
153
+ | `attach` | 附加到指定页面/Tab |
154
+ | `open` | 导航到 URL |
155
+ | `back` | 后退 |
156
+ | `forward` | 前进 |
157
+ | `refresh` | 刷新 |
158
+ | `close` | 关闭 `targetId` 指定的页面 |
159
+
160
+ 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 连接,
167
+
168
+ ### 访问验证
169
+
170
+ `open`、`back`、`forward`、`refresh`、`input` 和 `evaluate` 之后,MCP Chrome 会等待 Cloudflare JS Challenge 或 Turnstile
171
+ checkbox。Extension 模式下,导航先不启用 debugger 日志采集,连续八秒被动读取真实 tab 标题。interstitial 持续存在时,才检查可见 Turnstile 控件,找到后才点击。Extension
172
+ 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
176
+ `mouse_event`。widget 点 compact
177
+ Turnstile 卡片左侧 checkbox,宿主 wrapper 比卡片宽时也只点左侧卡片,不点文案。DOM 里已有 Cloudflare
178
+ iframe 时,即使 iframe 尺寸为 0,也走系统鼠标,不改用页面点击,后续宿主页 `Verify you are human` / `请验证您是真人`
179
+ 按钮同样走系统鼠标。系统鼠标只在受控测试页已经是已聚焦窗口的活动 tab 时使用,混合窗口不会调用 `focusWindow`。
180
+
181
+ 系统点击前会卸掉 debugger,再读一次视口。缺少系统鼠标工具或窗口未聚焦时返回可见错误,不会静默改用 CDP 点击。
182
+
183
+ widget 要连续两次 inspect 到同一坐标才点;系统鼠标从远处过来时从控件附近起步。同一类 checkbox 或 compact
184
+ widget 在同一次等待里最多点一次;Cloudflare 随后换成可见的 `Verify you are human` 或 `请验证您是真人`
185
+ 按钮时,inspect 判成 `verify` 后再点一次。访问受 Cloudflare 保护的页面默认保持
186
+ `diagnostics=false`,因为 diagnostics 会启用 debugger 的 console 和 network 采集。
187
+
188
+ 检测覆盖 `Just a moment...`、`请稍候…` 等标题、Challenge DOM、正文标记和 `Verify you are human` / `请验证您是真人`
189
+ 控件。CDP 用 `Target.getTargetInfo` 读取实时标题。页面恢复后残留的 Cloudflare
190
+ iframe 不算等待中,缓存标题不参与判定。不会调用 CAPTCHA solver、不会自动重试导航,也不会导出 `cf_clearance`
191
+ 的值。CDP 超时不代表网站在用户真实 Chrome 中无法通过,排查网站前先检查返回的 `mode`。
192
+
193
+ 过盾成功时返回 `challengeResolved=true`、`challengeKind`、`waitedMs`、`clickedTurnstile` 和 `clearanceCookiePresent`
194
+ (只表示 cookie 名是否存在)。页面可见文案显示验证成功、正在等待源站时,响应还会含
195
+ `originResponsePending=true`,表示已过盾但目标页面尚未加载。隐藏的成功文案(例如 `display:none`
196
+ 的标题)不算过盾,可见 Turnstile 勾选框仍视为等待中。Challenge 成功和失败响应都含 `mode`。超时返回 `CHALLENGE_TIMEOUT`
197
+ 且 `retryable=true`,并带 `clickedTurnstile` 和实际观察到的 `challengeKind`(点过 Turnstile 时不会报成 `js`)。Access
198
+ denied 返回 `CHALLENGE_DENIED`。交互式验证码、Bot Fight
199
+ Mode 和 IP 声誉检查无法靠等待或点击 checkbox 完成。之后的正常主文档响应才会清掉 header 标记,清空网络日志不会清掉它,
159
200
 
160
201
  ### input - 键鼠输入
161
202
 
162
203
  事件序列模型,支持任意组合:
163
204
 
164
- | 事件类型 | 描述 |
165
- |-----------------------------------------|----------------------------------------------------|
166
- | `keydown` / `keyup` | 按键按下/释放 |
167
- | `click` | 点击(含可操作性检查:可见性、是否启用、遮挡检测、自动滚动) |
168
- | `mousedown` / `mouseup` | 鼠标按下/释放 |
169
- | `mousemove` | 鼠标移动 |
170
- | `wheel` | 滚轮滚动 |
171
- | `touchstart` / `touchmove` / `touchend` | 触摸事件 |
172
- | `type` | 输入文本 |
173
- | `wait` | 事件间暂停 |
174
- | `select` | 按内容选中文本(鼠标模拟) |
175
- | `replace` | 查找并替换文本 |
205
+ | 事件类型 | 描述 |
206
+ | --------------------------------------- | ------------------------------------------------------------- |
207
+ | `keydown` / `keyup` | 按键按下/释放 |
208
+ | `click` | 点击(含可操作性检查:可见性、是否启用、遮挡检测、自动滚动) |
209
+ | `mousedown` / `mouseup` | 鼠标按下/释放 |
210
+ | `mousemove` | 鼠标移动 |
211
+ | `wheel` | 滚轮滚动 |
212
+ | `touchstart` / `touchmove` / `touchend` | 触摸事件 |
213
+ | `type` | 输入文本 |
214
+ | `wait` | 事件间暂停 |
215
+ | `select` | 按内容选中文本(鼠标模拟) |
216
+ | `replace` | 查找并替换文本 |
176
217
  | `drag` | HTML5 拖放(MAIN 世界 DragEvent,需 `target` 源 + `to` 目标) |
177
- | `editorContext` | 读取当前编辑器和选区上下文 |
178
- | `editorInsert` | 在当前编辑器选区插入文本 |
218
+ | `editorContext` | 读取当前编辑器和选区上下文 |
219
+ | `editorInsert` | 在当前编辑器选区插入文本 |
179
220
  | `editorCommand` | 执行 `bold`、`insertOrderedList` 等浏览器编辑命令 |
180
221
 
181
- 参数:`humanize` 启用贝塞尔曲线移动和随机延迟,`diagnostics=true` 返回动作后新增 console warning/error 和失败网络请求,
182
- `postCondition` 会在事件发送后等待页面状态,便于区分输入事件已发送和页面业务状态已完成,`postCondition.timeout` 默认 3000
183
- ms、最大 60000 ms,`postCondition.interval` 默认 100 ms、范围 50-5000 ms,`tabId` 指定目标 Tab,`frame` 指定目标 iframe(CSS
184
- 选择器或索引),均限 Extension 模式,
185
-
186
- **`click` 专属参数**:`force: true` 跳过可操作性检查(适用于测试隐藏元素等场景),可操作性失败返回 `ACTIONABILITY_FAILED`,包含
187
- `rect`、`clickPoint`、遮挡元素、候选遮挡物和修复建议,
188
- **`type` 专属参数**:`mode="controlled"` 或 `dispatch: true` 直接设置 `.value` 并触发 `input`/`change` 事件,兼容
189
- React/Vue 等框架的受控组件(键盘事件无法触发状态更新时使用),需要非坐标型 `target`,仅限 Extension 模式,受控输入和目标查找失败时返回结构化
190
- context,包含 `target`、`matchCount`、`nth`、`activeElement`、`selection` 和候选控件,`select` 和 `replace` 的事件级
191
- `nth` 表示文本第 N 次出现,嵌套的 `target.nth` 表示第 N 个目标元素,两者都从 0 开始并可同时使用,
222
+ `events` 至少需要一个事件。参数:`humanize` 启用贝塞尔曲线移动和随机延迟,`diagnostics=true` 返回动作后新增 console
223
+ warning/error 和失败网络请求, `postCondition`
224
+ 会在事件发送后等待页面状态,便于区分输入事件已发送和页面业务状态已完成,`postCondition.timeout` 默认 3000 ms、最大 60000
225
+ ms,`postCondition.interval` 默认 100 ms、范围 50-5000 ms,`tabId` 指定目标 Tab,`frame`
226
+ 指定目标 iframe(CSS 选择器或索引),均限 Extension 模式,传入任一作用域时,动作、诊断和 post-condition 使用该目标作用域选定的同一个 backend,
227
+
228
+ **`click` 专属参数**:`force: true` 跳过可操作性检查(适用于测试隐藏元素等场景),可操作性失败返回
229
+ `ACTIONABILITY_FAILED`,包含 `rect`、`clickPoint`、遮挡元素、候选遮挡物和修复建议, **`type`
230
+ 专属参数**:`mode="controlled"` 或 `dispatch: true` 直接设置 `.value` 并触发 `input`/`change`
231
+ 事件,兼容 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,
192
236
 
193
237
  **`keydown` 专属参数**:
194
238
 
195
- - `commands`:触发浏览器原生编辑命令(如 `["selectAll"]`、`["copy"]`、`["paste"]`、`["cut"]`、`["undo"]`、`["redo"]`),仅
196
- precise 模式可用,stealth 模式下抛错(CDP commands API 没有 JS 事件等价物)
239
+ - `commands`:触发浏览器原生编辑命令(如 `["selectAll"]`、`["copy"]`、`["paste"]`、`["cut"]`、`["undo"]`、`["redo"]`
240
+ ),成功表示浏览器已接受命令分发,页面结果需用 `postCondition` 或 `extract`
241
+ 验证,仅 precise 模式可用,stealth 模式下抛错(CDP commands API 没有 JS 事件等价物)
197
242
  - 连续 `keydown` 同一 key 自动切换为 `rawKeyDown` + `autoRepeat`,模拟长按重复(与 Puppeteer 一致)
198
243
 
199
244
  ### extract - 内容提取
200
245
 
201
- | Type | 描述 |
202
- |--------------|--------------------------|
203
- | `text` | 提取文本内容 |
204
- | `html` | 提取 HTML 源码 |
205
- | `frameHtml` | 提取指定 iframe 的 HTML |
206
- | `attribute` | 提取元素属性 |
207
- | `screenshot` | 截图(支持 `target` 元素裁剪) |
208
- | `state` | 获取页面状态(URL、标题、可交互元素) |
246
+ | Type | 描述 |
247
+ | ------------ | -------------------------------------- |
248
+ | `text` | 提取文本内容 |
249
+ | `html` | 提取 HTML 源码 |
250
+ | `frameHtml` | 提取指定 iframe 的 HTML |
251
+ | `attribute` | 提取元素属性 |
252
+ | `screenshot` | 截图(支持 `target` 元素裁剪) |
253
+ | `state` | 获取页面状态(URL、标题、可交互元素) |
209
254
  | `metadata` | 提取页面元信息(标题、OG、JSON-LD 等) |
210
255
 
211
256
  参数:`output` 将结果保存到文件(`images=data` 时为输出目录),`images`(`info`/`data`)提取 HTML 中的图片元信息或数据,
212
257
  `frameHtml` 在 `frame` 路由后提取当前 iframe 文档,截图支持 `clip` 坐标区域、`compareWith` PNG 基准对比和 `diffOutput`
213
- 差异图输出,截图响应包含 `metadata.format`、`width`、`height`、`dimensionSource`、`byteSize`、`fullPage`、`scale`、`clip` 和
214
- `capabilities`,PNG 对比在解码前限制为单个 PNG 25 MiB 和 12,000,000 像素,超出时使用 `clip` 或 `scale` 缩小截图,Extension
215
- hidden tab 截图返回 `HIDDEN_TAB_SCREENSHOT`,不会自动切前台,`state` 返回 `interactiveElements`,Extension 和 CDP 模式下
216
- `metadata` 都返回 `frames`,如果其他 debugger 占用 precise 截图路径,可视区域 fallback 会返回 `degraded`、`fallback` 和
217
- `limitations`;fallback 不支持的参数返回结构化 `SCREENSHOT_FALLBACK_UNSUPPORTED`,`tabId` 指定目标 Tab,`frame` 指定目标
218
- iframe,均限 Extension 模式,
258
+ 差异图输出,`diffOutput` 必须同时传 `compareWith`。指定 `target` 的截图未匹配、`nth`
259
+ 越界或尺寸为零时返回目标错误,不会静默返回视口截图,截图响应包含
260
+ `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 模式,
219
267
 
220
268
  **`attribute` 特殊前缀**:`computed:<属性名>` 返回 computed CSS 样式值(如 `computed:color`、`computed:font-size`),
221
269
  `computed:*` 返回全部计算样式(300+ 属性,建议配合 `output` 写文件),
222
270
 
223
- **`state` 专属参数**:`depth` 控制 DOM 遍历深度(默认 15),减小可降低大页面的返回数据量,
224
- `mode` 选择数据源 — `accessibility`(默认,从无障碍树派生)或 `domsnapshot`(CDP `DOMSnapshot.captureSnapshot`,仅 CDP 模式,返回带
225
- computed style 的扁平节点数组,便于二次处理),
271
+ **`state` 专属参数**:`depth` 控制 DOM 遍历深度(默认 15),减小可降低大页面的返回数据量, `mode` 选择数据源 —
272
+ `accessibility`(默认,从无障碍树派生)或 `domsnapshot`(CDP `DOMSnapshot.captureSnapshot`,仅 CDP 模式,返回带 computed
273
+ style 的扁平节点数组,便于二次处理),
226
274
 
227
275
  ### wait - 等待条件
228
276
 
229
- | For | 描述 |
230
- |--------------|----------------------------------------|
277
+ | For | 描述 |
278
+ | ------------ | -------------------------------------------- |
231
279
  | `element` | 等待元素(visible/hidden/attached/detached) |
232
280
  | `navigation` | 等待导航完成 |
233
- | `time` | 固定延迟 |
234
- | `idle` | 等待页面加载完成 + DOM mutation 静默期 |
281
+ | `time` | 固定延迟 |
282
+ | `idle` | 等待 DOM 或网络静默期 |
235
283
 
236
284
  参数:`tabId` 指定目标 Tab,`frame` 指定目标 iframe,均限 Extension 模式,
237
285
 
238
- **`idle` 说明**:`readyState === 'complete'` 后注入 `MutationObserver`,等待 `ms` 毫秒内无 DOM 变更(默认 500ms),返回
239
- `domStable: true` 表示 DOM 已稳定,`domStable: false` 表示预算用完时 DOM 仍在变化,
286
+ **`idle` 说明**:Extension 模式会在 `readyState === 'complete'` 后注入 `MutationObserver`,等待 `ms`
287
+ 毫秒内无 DOM 变更;CDP 模式等待网络静默。两种模式的默认 `ms` 都是 500ms,响应返回 `idleKind` 和
288
+ `idlePeriodMs`,Extension 响应还返回 `domStable`,
240
289
 
241
290
  ### evaluate - JavaScript 执行
242
291
 
243
292
  在页面上下文执行 JavaScript,
244
293
 
245
- | 参数 | 描述 |
246
- |-----------------|-------------------------------------------------------------|
247
- | `script` | JavaScript 代码,裸 `return` 语句自动包裹 IIFE |
248
- | `scriptFile` | 从本地文件读取脚本(与 `script` 二选一,相对路径默认走受控临时目录,仓库内文件请显式写 `cwd:`) |
249
- | `args` | 传递给脚本的参数(script 须为函数表达式) |
250
- | `mode` | `precise`(默认,debugger API)或 `stealth`(JS 注入) |
251
- | `output` | 将结果保存到文件(相对路径默认走受控临时目录,写入仓库请显式写 `cwd:`,字符串写原始文本,其他类型写 JSON) |
252
- | `tabId` | 指定目标 Tab(Extension 模式) |
253
- | `frame` | 指定目标 iframe(CSS 选择器或索引,Extension 模式) |
254
- | `timeout` | 端到端超时预算(毫秒) |
255
- | `diagnostics` | 执行后返回新增 console warning/error 和失败网络请求摘要 |
256
- | `postCondition` | 执行后等待文本、selector、URL 片段或脚本结果匹配 |
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 片段或脚本结果匹配 |
257
307
 
258
308
  `script` 和 `scriptFile` 至少提供一个,互斥使用,相对 `scriptFile` 和 `output` 路径默认写到 `mcp-chrome`
259
- 管理的系统临时目录,需要把文件留在当前工作目录时,用 `cwd:relative/path` 显式指定,相对路径会拒绝 `..`,Windows 下也会拒绝
260
- `:`,避免落到 NTFS alternate data stream,
261
-
262
- 结果超过 100KB 时自动写入文件到受控的系统临时目录,返回文件路径和大小,返回 DOM 节点、`NodeList` 或 `HTMLCollection` 时返回
263
- `NON_SERIALIZABLE_EVALUATE_RESULT`,并提示改为返回 `textContent`、`outerHTML` 等简单字段,evaluate 即使在全局
264
- `inputMode=stealth` 时也默认使用 `precise`,其 `postCondition` 检查与主动作使用相同 evaluate mode,`postCondition` 不传时,
265
- `success=true` 只表示脚本完成执行并返回;传入后如果超时仍不匹配,返回 `POST_CONDITION_FAILED` 和最后一次检查结果,
309
+ 管理的系统临时目录,需要把文件留在当前工作目录时,用 `cwd:relative/path` 显式指定,相对路径会拒绝
310
+ `..`,Windows 下也会拒绝 `:`,避免落到 NTFS alternate data stream,`output` 对字符串写原始文本,对其他类型写 JSON,
311
+
312
+ 结果超过 100KB 时自动写入文件到受控的系统临时目录,返回文件路径和大小,返回 DOM 节点、`NodeList` 或 `HTMLCollection`
313
+ 时返回 `NON_SERIALIZABLE_EVALUATE_RESULT`,并提示改为返回 `textContent`、`outerHTML`
314
+ 等简单字段,结果展开或序列化失败时返回 `actionExecuted=true`、`actionStatus="completed"` 和
315
+ `failureStage="output"`,因为页面脚本已经完成,evaluate 即使在全局 `inputMode=stealth` 时也默认使用 `precise`,其
316
+ `postCondition` 检查与主动作使用相同 evaluate mode,`postCondition` 不传时, `success=true`
317
+ 只表示脚本完成执行并返回;传入后如果超时仍不匹配,返回 `POST_CONDITION_FAILED` 和最后一次检查结果,iframe
318
+ precise 执行默认不在 execution context 失效后重放脚本,只有脚本无副作用时才应传
319
+ `staleContextRetry="readOnly"`,Extension 会在剩余 timeout 内重新解析 context,并最多重放一次,`Runtime.evaluate`
320
+ 发出后发生 stale context 时返回
321
+ `actionExecuted=true`、`actionStatus="unknown"`,因为脚本可能已经产生部分副作用,但无法取得最终结果,
266
322
 
267
323
  ### manage - 页面与环境管理
268
324
 
269
- | Action | 描述 |
270
- |----------------|--------------------------------------|
271
- | `newPage` | 新建受控页面/Tab |
272
- | `closePage` | 关闭受控页面并返回 `affected.before/after` |
273
- | `adoptPage` | 将已有 Tab 标记为受控页,不切前台 |
274
- | `releasePage` | 将受控页移出管理,不关闭页面 |
275
- | `movePage` | 将受控 Tab 移到指定窗口或 index |
276
- | `reorderPage` | 调整受控 Tab 在当前窗口内的顺序 |
277
- | `pinPage` | 固定受控 Tab |
278
- | `unpinPage` | 取消固定受控 Tab |
279
- | `activatePage` | 激活受控 Tab 并聚焦所在窗口 |
280
- | `focusWindow` | 聚焦显式指定的窗口 |
281
- | `resizeWindow` | 调整显式指定窗口的尺寸或状态 |
282
- | `newWindow` | 新建受控窗口 |
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` | 新建受控窗口 |
283
339
  | `closeWindow` | 仅当窗口内全是 managed tab 时关闭窗口 |
284
- | `clearCache` | 清除缓存/存储(清除 Cookie 请用 `cookies` 工具) |
285
- | `viewport` | 设置视口大小 |
286
- | `userAgent` | 设置 User-Agent |
287
- | `emulate` | 设备模拟(iPhone、iPad 等) |
288
- | `inputMode` | 查询或设置输入模式(`precise` / `stealth`) |
289
- | `stealth` | 注入反检测脚本 |
340
+ | `clearCache` | 清除缓存/存储(清除 Cookie 请用 `cookies` 工具) |
341
+ | `viewport` | 设置视口大小 |
342
+ | `userAgent` | 设置 User-Agent |
343
+ | `emulate` | 设备模拟(iPhone、iPad 等) |
344
+ | `inputMode` | 查询或设置输入模式(`precise` / `stealth`) |
345
+ | `stealth` | 注入反检测脚本 |
290
346
  | `cdp` | 发送原始 CDP 命令(高级,如 `Runtime.evaluate`) |
291
347
 
292
348
  Tab/window 管理动作仅支持 Extension 模式,改变浏览器可见状态的动作必须显式传 `targetId` 或 `windowId`,并返回
293
- `affected.before/after`,`focusWindow` 只有在观测到目标窗口已聚焦后才返回成功,否则返回
294
- `WINDOW_FOCUS_NOT_OBSERVED`,`closeWindow` 遇到混有非托管 tab 的窗口会返回 `WINDOW_HAS_UNMANAGED_TABS`
349
+ `affected.before/after`。Extension 模式不支持 `clearCache`,会返回 `UNSUPPORTED_MODE` 且不清除任何内容;清 Cookie 请用带
350
+ `url` 或 `domain` 过滤的 `cookies(action="clear")`,清 storage 或 cache 请改用 CDP 模式。`focusWindow`
351
+ 只有在观测到目标窗口已聚焦后才返回成功,否则返回 `WINDOW_FOCUS_NOT_OBSERVED`,`closeWindow`
352
+ 遇到混有非托管 tab 的窗口会返回 `WINDOW_HAS_UNMANAGED_TABS`
295
353
 
296
354
  **Stealth 模式档位**(CDP launch 参数,通过 `browse action=launch stealth=...` 设置):
297
355
 
@@ -301,27 +359,30 @@ Tab/window 管理动作仅支持 Extension 模式,改变浏览器可见状态
301
359
 
302
360
  ### logs - 浏览器日志
303
361
 
304
- | Type | 描述 |
305
- |-----------|-------------------|
306
- | `console` | 控制台日志(支持级别过滤) |
362
+ | Type | 描述 |
363
+ | --------- | ----------------------------- |
364
+ | `console` | 控制台日志(支持级别过滤) |
307
365
  | `network` | 网络请求日志(支持 URL 过滤) |
308
366
 
309
367
  参数:`output` 将结果保存到文件,console 日志统一返回公开级别 `error`、`warning`、`info`、`debug`,浏览器原始的 `warn`、
310
- `log` 等级会在过滤和返回前转换,network 日志包含已完成请求、HTTP 4xx/5xx 响应和加载失败请求,尽量返回 `errorText`、`method`、
311
- `url`、`status`、`timestamp`、`duration`,内联 network 结果会把单条 URL 限制为 2048 字符,截断时返回 `urlLength` 和
312
- `urlTruncated: true`,显式 `output` 仍保存完整 URL,`urlPattern` 支持 `*` 匹配任意长度字符、`?` 匹配单个字符,`tabId`
368
+ `log` 等级会在过滤和返回前转换,network 日志包含已完成请求、HTTP 4xx/5xx 响应和加载失败请求,尽量返回
369
+ `errorText`、`method`、 `url`、`status`、`timestamp`、`duration`,URL
370
+ query 中常见的认证、签名、密码和 token 参数会在内联响应、diagnostics 和 显式 `output` 文件中替换为 `[REDACTED]`,并返回
371
+ `urlRedacted`、`urlOriginalLength` 和
372
+ `redactedQueryParameters`,内联 network 结果会把脱敏后的单条 URL 限制为 2048 字符,截断时返回 `urlLength` 和
373
+ `urlTruncated: true`,`urlPattern` 支持 `*` 匹配任意长度字符、`?` 匹配单个字符,`tabId`
313
374
  指定目标 Tab(Extension 模式),`frame` 不适用于日志,
314
375
 
315
376
  ### cookies - Cookie 管理
316
377
 
317
- | Action | 描述 |
318
- |----------|-----------------------------------------------|
319
- | `get` | 获取 Cookie |
320
- | `set` | 设置 Cookie |
321
- | `delete` | 删除 Cookie |
322
- | `clear` | 按过滤参数删除 Cookie(`name`/`domain`/`url`,必须 ≥1 个) |
378
+ | Action | 描述 |
379
+ | -------- | ------------------------------------------------------ |
380
+ | `get` | 获取 Cookie |
381
+ | `set` | 设置 Cookie |
382
+ | `delete` | 删除 Cookie |
383
+ | `clear` | 在 URL 或域名范围内删除 Cookie,可用 `name` 进一步过滤 |
323
384
 
324
- **说明**:`clear` 必须指定 `name`、`domain`、`url` 中至少一个过滤参数,否则拒绝调用以避免误清用户登录态
385
+ **说明**:`clear` 必须指定 `url` 或 `domain`。`name` 只能在该范围内进一步过滤,避免误删其他站点的同名 Cookie
325
386
 
326
387
  ## Target:统一元素定位器
327
388
 
@@ -329,57 +390,43 @@ Tab/window 管理动作仅支持 Extension 模式,改变浏览器可见状态
329
390
 
330
391
  ```typescript
331
392
  // 按可访问性(推荐 - 最稳定)
332
- { role: "button", name: "提交" }
393
+ const byRole = { role: 'button', name: '提交' }
333
394
 
334
395
  // 按可访问性精确匹配名称
335
- { role: "button", name: "提交", exact: true }
396
+ const byExactRole = { role: 'button', name: '提交', exact: true }
336
397
 
337
398
  // 按文本内容
338
- { text: "点击这里", exact: true }
399
+ const byText = { text: '点击这里', exact: true }
339
400
 
340
401
  // 按表单 label
341
- {
342
- label: "邮箱"
343
- }
402
+ const byLabel = { label: '邮箱' }
344
403
 
345
404
  // 按 placeholder
346
- {
347
- placeholder: "请输入姓名"
348
- }
405
+ const byPlaceholder = { placeholder: '请输入姓名' }
349
406
 
350
407
  // 按 title 属性
351
- {
352
- title: "关闭对话框"
353
- }
408
+ const byTitle = { title: '关闭对话框' }
354
409
 
355
410
  // 按 alt 文本(图片)
356
- {
357
- alt: "头像"
358
- }
411
+ const byAlt = { alt: '头像' }
359
412
 
360
413
  // 按 test ID
361
- {
362
- testId: "submit-button"
363
- }
414
+ const byTestId = { testId: 'submit-button' }
364
415
 
365
416
  // 按 CSS 选择器
366
- {
367
- css: "#login-form .submit-btn"
368
- }
417
+ const byCss = { css: '#login-form .submit-btn' }
369
418
 
370
419
  // 多匹配消歧(从 0 开始)
371
- { css: ".ant-select-input", nth: 1 }
420
+ const secondMatch = { css: '.ant-select-input', nth: 1 }
372
421
 
373
422
  // 按 CSS + 文本(按文本内容过滤)
374
- { css: "button", text: "提交", exact: true }
423
+ const byCssText = { css: 'button', text: '提交', exact: true }
375
424
 
376
425
  // 按 XPath
377
- {
378
- xpath: "//button[@type='submit']"
379
- }
426
+ const byXPath = { xpath: "//button[@type='submit']" }
380
427
 
381
428
  // 按坐标
382
- { x: 100, y: 200 }
429
+ const byCoordinates = { x: 100, y: 200 }
383
430
  ```
384
431
 
385
432
  ## 使用示例
@@ -473,6 +520,10 @@ input(events=[
473
520
  ], frame="iframe.login-frame")
474
521
  ```
475
522
 
523
+ CSS 选择器和数字索引按父文档的 DOM
524
+ iframe 顺序定位,DOM 中不存在的子 frame(包括其他 Extension 加入的 frame)不会改变索引,也不会成为候选目标,所选元素无法对应到唯一 Chrome
525
+ frame 时返回 `FRAME_IDENTITY_UNAVAILABLE`,不会选择其他frame
526
+
476
527
  ### 等待元素
477
528
 
478
529
  ```
@@ -562,24 +613,24 @@ mcp-chrome/
562
613
  ## 安全说明
563
614
 
564
615
  - **信任边界**:Extension 模式默认自动连接本地 MCP server,在多用户系统、CI runner、`--net=host` 容器等不可信代码可访问
565
- `127.0.0.1:19222-19299` 的环境中,应使用 `MCP_CHROME_PAIRING_TOKEN`,或设置 `MCP_CHROME_ALLOW_INSECURE_NO_TOKEN=0`,WebSocket 握手要求 `chrome-extension://`
566
- Origin 头,可挡掉浏览器页面和 curl,但拦不住同 UID 的本地恶意进程
616
+ `127.0.0.1:19222-19299` 的环境中,应使用 `MCP_CHROME_PAIRING_TOKEN`,或设置 `MCP_CHROME_ALLOW_INSECURE_NO_TOKEN=0`
617
+ ,WebSocket 握手要求 `chrome-extension://` Origin 头,可挡掉浏览器页面和 curl,但拦不住同 UID 的本地恶意进程
567
618
  - Extension 模式:共享浏览器会话,请仅在受信任的机器上使用
568
619
  - CDP 模式:通过 DevTools Protocol 提供完整浏览器控制能力
569
620
  - 默认端口仅绑定到 127.0.0.1(本地访问)
570
621
  - `evaluate` 工具可执行任意 JavaScript
571
622
  - `manage cdp` 操作可发送任意 CDP 命令
572
- - 网络日志可能包含敏感信息
623
+ - 网络 URL 中的常见认证参数默认会脱敏,但 console 文本和非标准参数名仍可能包含敏感信息
573
624
 
574
625
  ### 反检测(stealth)—— 实际能力
575
626
 
576
627
  `stealth` 模式(`safe` / `aggressive`)仅覆盖少量指纹面:
577
628
 
578
629
  - **覆盖**:`navigator.webdriver`、`cdc_*` 属性、User-Agent 字符串、若干 WebGL vendor/renderer 值、Chrome runtime 属性
579
- - **不覆盖**:Canvas 指纹、AudioContext 指纹、Font 枚举、TLS 层指纹(JA3/JA4)、CDP attach 横幅("Chrome 正受自动化软件控制"
580
- )、扩展自身存在的探测
581
- - **警告**:禁止使用本功能绕过商业 anti-bot 服务(Cloudflare Turnstile、Akamai、DataDome、PerimeterX),真实的 bot
582
- 检测发生在多个我们无法在页面内部修补的层级
630
+ - **不覆盖**:Canvas 指纹、AudioContext 指纹、Font 枚举、TLS 层指纹(JA3/JA4)、CDP
631
+ attach 横幅("Chrome 正受自动化软件控制")、扩展自身存在的探测
632
+ - **警告**:这些修补不能过 Cloudflare。JS Challenge 和 Turnstile
633
+ checkbox 由导航、input、evaluate 之后在真实浏览器里等待处理,不覆盖 Akamai、DataDome、PerimeterX、交互式验证码或 IP 声誉
583
634
 
584
635
  ## 已知限制
585
636
 
@@ -597,9 +648,24 @@ MIT 许可证 - 详见 [LICENSE](LICENSE)
597
648
  - [Model Context Protocol](https://modelcontextprotocol.io/) - MCP 规范
598
649
  - [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/) - CDP 文档
599
650
 
600
-
601
651
  ## 操作状态与诊断
602
652
 
603
- input 和 evaluate 返回值追加 `actionExecuted`、`actionStatus`、`verificationStatus`、`failureStage` 和 `retryable`。验证状态分为 `matched`、`not_matched`、`unavailable`、`error`;debugger 超时且无法证明脚本已停止时,动作状态为 `unknown`。diagnostics 是附加能力,失败时返回 `diagnosticsStatus`,不会覆盖主动作结果。browse 和 wait 的主动作失败时,也会保留失败前已收集的 diagnostics。
604
-
605
- `replace` 仅对 `textarea` 以及 `text`、`search`、`tel`、`url`、`password` 类型的 input 使用文本选区。其他 input 类型通过原生完整 value 更新,并返回请求值与浏览器规范化后的实际值。对不支持选区的类型单独执行 `select` 会返回 `UNSUPPORTED_SELECTION`。目标超时返回限量的 locator、tab、frame、匹配数和候选上下文。precise iframe evaluate 遇到失效执行上下文只重试一次,重复 URL 导致 frame 不唯一时拒绝猜测,响应包含 `retryAttempted`、限量的 `retryReason`,以及最终 Extension frame、parent frame、URL、CDP frame 和 execution context ID 组成的 `frameContext`。端口扫描会把普通的 WebSocket open 前失败聚合为 debug;已识别 MCP server 的认证或协议拒绝只在摘要变化时输出一条限量 warning。
653
+ input 和 evaluate 返回值追加 `actionExecuted`、`actionStatus`、`verificationStatus`、`failureStage` 和
654
+ `retryable`。验证状态分为
655
+ `matched`、`not_matched`、`unavailable`、`error`;debugger 超时且无法证明脚本已停止时,动作状态为
656
+ `unknown`。页面脚本抛异常时返回 `actionExecuted=true` 和 `actionStatus="failed"`;结果展开或序列化失败时返回
657
+ `actionStatus="completed"` 和 `failureStage="output"`。diagnostics 是附加能力,失败时返回
658
+ `diagnosticsStatus`,不会覆盖主动作结果。browse 和 wait 的主动作失败时,也会保留失败前已收集的 diagnostics。目标诊断会读取当前 tab 的实时状态,不依赖 attach 时缓存的 URL 和标题。
659
+
660
+ `replace` 仅对 `textarea` 以及 `text`、`search`、`tel`、`url`、`password`
661
+ 类型的 input 使用文本选区。其他 input 类型通过原生完整 value 更新,并返回请求值与浏览器规范化后的实际值。对不支持选区的类型单独执行
662
+ `select` 会返回 `UNSUPPORTED_SELECTION`。CDP模式下,`select` 和 `replace` 的 locator target 通过 CDP
663
+ locator 聚焦,不调用 Extension refId。password value 不进入 input 失败 context 和 text
664
+ post-condition 观测值,失败响应还会脱敏传入的 `find` 和替换
665
+ `text`。目标超时返回限量的locator、tab、frame、匹配数和候选上下文。显式 `tabId` 或 `frame`
666
+ 作用域会在 input、wait、logs、extract 开始前确定活动 backend,动作和验证使用同一个目标 backend。precise iframe
667
+ evaluate 默认使用 `staleContextRetry="never"`,context 失效时不重放脚本; `readOnly` 允许 Extension 校验 frame
668
+ 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。
@@ -26,7 +26,7 @@ export function randomDelay(min, max) {
26
26
  export function generateBezierPath(from, to, steps) {
27
27
  // 计算距离
28
28
  const distance = Math.sqrt(Math.pow(to.x - from.x, 2) + Math.pow(to.y - from.y, 2));
29
- // 根据距离计算步数,距离越远步数越多
29
+ // 距离越远,路径点越多
30
30
  const numSteps = steps ?? Math.max(20, Math.floor(distance / 10));
31
31
  // 生成随机控制点
32
32
  const control1 = {