@pyrokine/mcp-chrome 2.4.1 → 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.
- package/README.md +213 -158
- package/README_zh.md +245 -187
- package/dist/anti-detection/behavior.js +1 -1
- package/dist/anti-detection/behavior.js.map +1 -1
- package/dist/anti-detection/injection.d.ts.map +1 -1
- package/dist/anti-detection/injection.js +2 -1
- package/dist/anti-detection/injection.js.map +1 -1
- package/dist/cdp/client.d.ts +2 -2
- package/dist/cdp/client.d.ts.map +1 -1
- package/dist/cdp/client.js +7 -4
- package/dist/cdp/client.js.map +1 -1
- package/dist/core/browser-driver.d.ts +3 -2
- package/dist/core/browser-driver.d.ts.map +1 -1
- package/dist/core/browser-driver.js +1 -0
- package/dist/core/browser-driver.js.map +1 -1
- package/dist/core/errors.d.ts +9 -0
- package/dist/core/errors.d.ts.map +1 -1
- package/dist/core/errors.js +16 -1
- package/dist/core/errors.js.map +1 -1
- package/dist/core/os-mouse.d.ts +65 -0
- package/dist/core/os-mouse.d.ts.map +1 -0
- package/dist/core/os-mouse.js +334 -0
- package/dist/core/os-mouse.js.map +1 -0
- package/dist/core/session.d.ts +14 -4
- package/dist/core/session.d.ts.map +1 -1
- package/dist/core/session.js +159 -54
- package/dist/core/session.js.map +1 -1
- package/dist/core/types.d.ts +10 -0
- package/dist/core/types.d.ts.map +1 -1
- package/dist/core/types.js +2 -0
- package/dist/core/types.js.map +1 -1
- package/dist/core/unified-session.d.ts +24 -3
- package/dist/core/unified-session.d.ts.map +1 -1
- package/dist/core/unified-session.js +143 -25
- package/dist/core/unified-session.js.map +1 -1
- package/dist/extension/bridge.d.ts +16 -0
- package/dist/extension/bridge.d.ts.map +1 -1
- package/dist/extension/bridge.js +27 -0
- package/dist/extension/bridge.js.map +1 -1
- package/dist/extension/http-server.d.ts.map +1 -1
- package/dist/extension/http-server.js +6 -1
- package/dist/extension/http-server.js.map +1 -1
- package/dist/tools/browse.d.ts +1 -1
- package/dist/tools/browse.d.ts.map +1 -1
- package/dist/tools/browse.js +72 -26
- package/dist/tools/browse.js.map +1 -1
- package/dist/tools/challenge.d.ts +153 -0
- package/dist/tools/challenge.d.ts.map +1 -0
- package/dist/tools/challenge.js +573 -0
- package/dist/tools/challenge.js.map +1 -0
- package/dist/tools/cookies.d.ts.map +1 -1
- package/dist/tools/cookies.js +8 -4
- package/dist/tools/cookies.js.map +1 -1
- package/dist/tools/diagnostics.d.ts +2 -2
- package/dist/tools/diagnostics.d.ts.map +1 -1
- package/dist/tools/diagnostics.js +26 -8
- package/dist/tools/diagnostics.js.map +1 -1
- package/dist/tools/evaluate.d.ts.map +1 -1
- package/dist/tools/evaluate.js +61 -9
- package/dist/tools/evaluate.js.map +1 -1
- package/dist/tools/extract.d.ts.map +1 -1
- package/dist/tools/extract.js +110 -51
- package/dist/tools/extract.js.map +1 -1
- package/dist/tools/input.d.ts.map +1 -1
- package/dist/tools/input.js +148 -22
- package/dist/tools/input.js.map +1 -1
- package/dist/tools/logs.js +2 -2
- package/dist/tools/logs.js.map +1 -1
- package/dist/tools/manage.d.ts.map +1 -1
- package/dist/tools/manage.js +20 -7
- package/dist/tools/manage.js.map +1 -1
- package/dist/tools/network-sanitizer.d.ts.map +1 -1
- package/dist/tools/network-sanitizer.js +1 -0
- package/dist/tools/network-sanitizer.js.map +1 -1
- package/dist/tools/png.js +5 -3
- package/dist/tools/png.js.map +1 -1
- package/dist/tools/post-condition.d.ts.map +1 -1
- package/dist/tools/post-condition.js +12 -3
- package/dist/tools/post-condition.js.map +1 -1
- package/dist/tools/target-diagnostics.d.ts +7 -0
- package/dist/tools/target-diagnostics.d.ts.map +1 -1
- package/dist/tools/target-diagnostics.js +18 -1
- package/dist/tools/target-diagnostics.js.map +1 -1
- package/dist/tools/wait.d.ts.map +1 -1
- package/dist/tools/wait.js +41 -39
- package/dist/tools/wait.js.map +1 -1
- package/extension/dist/assets/{index.ts-GG6dPUPX.js → index.ts-Bqcu2qiN.js} +286 -9
- package/extension/dist/manifest.json +1 -1
- package/extension/dist/service-worker-loader.js +1 -1
- package/extension/dist/src/popup/popup.html +44 -44
- package/package.json +8 -7
- package/dist/extension/native-host-installer.d.ts +0 -21
- package/dist/extension/native-host-installer.d.ts.map +0 -1
- package/dist/extension/native-host-installer.js +0 -147
- package/dist/extension/native-host-installer.js.map +0 -1
- package/dist/extension/socket-server.d.ts +0 -32
- package/dist/extension/socket-server.d.ts.map +0 -1
- package/dist/extension/socket-server.js +0 -177
- package/dist/extension/socket-server.js.map +0 -1
- package/dist/extension/ws-server.d.ts +0 -40
- package/dist/extension/ws-server.d.ts.map +0 -1
- package/dist/extension/ws-server.js +0 -246
- package/dist/extension/ws-server.js.map +0 -1
- package/dist/native-host/index.js +0 -280
- package/dist/native-host/mcp-chrome-host +0 -2
package/README_zh.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
[English](README.md) | 中文
|
|
4
4
|
|
|
5
|
-
Chrome 浏览器自动化 MCP Server
|
|
5
|
+
Chrome 浏览器自动化 MCP Server,双模式架构: **Extension 模式**(推荐)操控现有浏览器, **CDP 模式**(回退)启动独立实例
|
|
6
6
|
|
|
7
7
|
[](LICENSE)
|
|
8
8
|
[](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/`,启用开发者模式,点击“加载已解压的扩展程序”,选择
|
|
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
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
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
|
-
Extension 通过 HTTP/WebSocket 自动连接 MCP Server(端口 19222-19299
|
|
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`
|
|
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
|
|
123
|
+
需要强制配对 token 时,在 server 设置 `MCP_CHROME_ALLOW_INSECURE_NO_TOKEN=0`,并在 Extension
|
|
124
|
+
popup 关闭“允许无 token本地连接”,
|
|
120
125
|
|
|
121
126
|
### 模式二:CDP 模式(回退)
|
|
122
127
|
|
|
@@ -132,171 +137,219 @@ browse(action="connect", port=9222)
|
|
|
132
137
|
browse(action="open", url="https://example.com")
|
|
133
138
|
```
|
|
134
139
|
|
|
135
|
-
>
|
|
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` |
|
|
144
|
-
| `connect` |
|
|
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
|
|
154
|
-
`isActive`(是否为当前操作目标)、
|
|
155
|
-
`windowId`、`index`、`pinned`、`incognito`、`status`(`loading`/`complete`),树状结构含
|
|
156
|
-
`activeTargetId` 和每个窗口按顺序排列的 `tabs`,可区分每个窗口内的 active
|
|
157
|
-
自动创建 Tab 分组(cyan 色),`open`、`back`、`forward`、`refresh` 支持
|
|
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
|
-
|
|
182
|
-
`postCondition`
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
`
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
`
|
|
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,
|
|
193
236
|
|
|
194
237
|
**`keydown` 专属参数**:
|
|
195
238
|
|
|
196
|
-
- `commands`:触发浏览器原生编辑命令(如 `["selectAll"]`、`["copy"]`、`["paste"]`、`["cut"]`、`["undo"]`、`["redo"]
|
|
197
|
-
`postCondition` 或 `extract`
|
|
239
|
+
- `commands`:触发浏览器原生编辑命令(如 `["selectAll"]`、`["copy"]`、`["paste"]`、`["cut"]`、`["undo"]`、`["redo"]`
|
|
240
|
+
),成功表示浏览器已接受命令分发,页面结果需用 `postCondition` 或 `extract`
|
|
241
|
+
验证,仅 precise 模式可用,stealth 模式下抛错(CDP commands API 没有 JS 事件等价物)
|
|
198
242
|
- 连续 `keydown` 同一 key 自动切换为 `rawKeyDown` + `autoRepeat`,模拟长按重复(与 Puppeteer 一致)
|
|
199
243
|
|
|
200
244
|
### extract - 内容提取
|
|
201
245
|
|
|
202
|
-
| Type | 描述
|
|
203
|
-
|
|
204
|
-
| `text` | 提取文本内容
|
|
205
|
-
| `html` | 提取 HTML 源码
|
|
206
|
-
| `frameHtml` | 提取指定 iframe 的 HTML
|
|
207
|
-
| `attribute` | 提取元素属性
|
|
208
|
-
| `screenshot` | 截图(支持 `target` 元素裁剪)
|
|
209
|
-
| `state` | 获取页面状态(URL、标题、可交互元素)
|
|
246
|
+
| Type | 描述 |
|
|
247
|
+
| ------------ | -------------------------------------- |
|
|
248
|
+
| `text` | 提取文本内容 |
|
|
249
|
+
| `html` | 提取 HTML 源码 |
|
|
250
|
+
| `frameHtml` | 提取指定 iframe 的 HTML |
|
|
251
|
+
| `attribute` | 提取元素属性 |
|
|
252
|
+
| `screenshot` | 截图(支持 `target` 元素裁剪) |
|
|
253
|
+
| `state` | 获取页面状态(URL、标题、可交互元素) |
|
|
210
254
|
| `metadata` | 提取页面元信息(标题、OG、JSON-LD 等) |
|
|
211
255
|
|
|
212
256
|
参数:`output` 将结果保存到文件(`images=data` 时为输出目录),`images`(`info`/`data`)提取 HTML 中的图片元信息或数据,
|
|
213
257
|
`frameHtml` 在 `frame` 路由后提取当前 iframe 文档,截图支持 `clip` 坐标区域、`compareWith` PNG 基准对比和 `diffOutput`
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
`
|
|
218
|
-
|
|
219
|
-
|
|
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 模式,
|
|
220
267
|
|
|
221
268
|
**`attribute` 特殊前缀**:`computed:<属性名>` 返回 computed CSS 样式值(如 `computed:color`、`computed:font-size`),
|
|
222
269
|
`computed:*` 返回全部计算样式(300+ 属性,建议配合 `output` 写文件),
|
|
223
270
|
|
|
224
|
-
**`state` 专属参数**:`depth` 控制 DOM 遍历深度(默认 15),减小可降低大页面的返回数据量,
|
|
225
|
-
`
|
|
226
|
-
|
|
271
|
+
**`state` 专属参数**:`depth` 控制 DOM 遍历深度(默认 15),减小可降低大页面的返回数据量, `mode` 选择数据源 —
|
|
272
|
+
`accessibility`(默认,从无障碍树派生)或 `domsnapshot`(CDP `DOMSnapshot.captureSnapshot`,仅 CDP 模式,返回带 computed
|
|
273
|
+
style 的扁平节点数组,便于二次处理),
|
|
227
274
|
|
|
228
275
|
### wait - 等待条件
|
|
229
276
|
|
|
230
|
-
| For | 描述
|
|
231
|
-
|
|
277
|
+
| For | 描述 |
|
|
278
|
+
| ------------ | -------------------------------------------- |
|
|
232
279
|
| `element` | 等待元素(visible/hidden/attached/detached) |
|
|
233
280
|
| `navigation` | 等待导航完成 |
|
|
234
|
-
| `time` | 固定延迟
|
|
235
|
-
| `idle` |
|
|
281
|
+
| `time` | 固定延迟 |
|
|
282
|
+
| `idle` | 等待 DOM 或网络静默期 |
|
|
236
283
|
|
|
237
284
|
参数:`tabId` 指定目标 Tab,`frame` 指定目标 iframe,均限 Extension 模式,
|
|
238
285
|
|
|
239
|
-
**`idle`
|
|
240
|
-
|
|
286
|
+
**`idle` 说明**:Extension 模式会在 `readyState === 'complete'` 后注入 `MutationObserver`,等待 `ms`
|
|
287
|
+
毫秒内无 DOM 变更;CDP 模式等待网络静默。两种模式的默认 `ms` 都是 500ms,响应返回 `idleKind` 和
|
|
288
|
+
`idlePeriodMs`,Extension 响应还返回 `domStable`,
|
|
241
289
|
|
|
242
290
|
### evaluate - JavaScript 执行
|
|
243
291
|
|
|
244
292
|
在页面上下文执行 JavaScript,
|
|
245
293
|
|
|
246
|
-
| 参数
|
|
247
|
-
|
|
248
|
-
| `script`
|
|
249
|
-
| `scriptFile`
|
|
250
|
-
| `args`
|
|
251
|
-
| `mode`
|
|
252
|
-
| `staleContextRetry` | iframe stale context 策略,`never`(默认)或 `readOnly`
|
|
253
|
-
| `output`
|
|
254
|
-
| `tabId`
|
|
255
|
-
| `frame`
|
|
256
|
-
| `timeout`
|
|
257
|
-
| `diagnostics`
|
|
258
|
-
| `postCondition`
|
|
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 片段或脚本结果匹配 |
|
|
259
307
|
|
|
260
308
|
`script` 和 `scriptFile` 至少提供一个,互斥使用,相对 `scriptFile` 和 `output` 路径默认写到 `mcp-chrome`
|
|
261
|
-
管理的系统临时目录,需要把文件留在当前工作目录时,用 `cwd:relative/path` 显式指定,相对路径会拒绝
|
|
262
|
-
`:`,避免落到 NTFS alternate data stream,
|
|
263
|
-
|
|
264
|
-
结果超过 100KB 时自动写入文件到受控的系统临时目录,返回文件路径和大小,返回 DOM 节点、`NodeList` 或 `HTMLCollection`
|
|
265
|
-
`NON_SERIALIZABLE_EVALUATE_RESULT`,并提示改为返回 `textContent`、`outerHTML`
|
|
266
|
-
`actionExecuted=true`、`actionStatus="completed"` 和
|
|
267
|
-
`inputMode=stealth` 时也默认使用 `precise`,其
|
|
268
|
-
`
|
|
269
|
-
|
|
270
|
-
|
|
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"`,因为脚本可能已经产生部分副作用,但无法取得最终结果,
|
|
271
322
|
|
|
272
323
|
### manage - 页面与环境管理
|
|
273
324
|
|
|
274
|
-
| Action | 描述
|
|
275
|
-
|
|
276
|
-
| `newPage` | 新建受控页面/Tab
|
|
277
|
-
| `closePage` | 关闭受控页面并返回 `affected.before/after`
|
|
278
|
-
| `adoptPage` | 将已有 Tab 标记为受控页,不切前台
|
|
279
|
-
| `releasePage` | 将受控页移出管理,不关闭页面
|
|
280
|
-
| `movePage` | 将受控 Tab 移到指定窗口或 index
|
|
281
|
-
| `reorderPage` | 调整受控 Tab 在当前窗口内的顺序
|
|
282
|
-
| `pinPage` | 固定受控 Tab
|
|
283
|
-
| `unpinPage` | 取消固定受控 Tab
|
|
284
|
-
| `activatePage` | 激活受控 Tab 并聚焦所在窗口
|
|
285
|
-
| `focusWindow` | 聚焦显式指定的窗口
|
|
286
|
-
| `resizeWindow` | 调整显式指定窗口的尺寸或状态
|
|
287
|
-
| `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` | 新建受控窗口 |
|
|
288
339
|
| `closeWindow` | 仅当窗口内全是 managed tab 时关闭窗口 |
|
|
289
|
-
| `clearCache` | 清除缓存/存储(清除 Cookie 请用 `cookies` 工具)
|
|
290
|
-
| `viewport` | 设置视口大小
|
|
291
|
-
| `userAgent` | 设置 User-Agent
|
|
292
|
-
| `emulate` | 设备模拟(iPhone、iPad 等)
|
|
293
|
-
| `inputMode` | 查询或设置输入模式(`precise` / `stealth`)
|
|
294
|
-
| `stealth` | 注入反检测脚本
|
|
340
|
+
| `clearCache` | 清除缓存/存储(清除 Cookie 请用 `cookies` 工具) |
|
|
341
|
+
| `viewport` | 设置视口大小 |
|
|
342
|
+
| `userAgent` | 设置 User-Agent |
|
|
343
|
+
| `emulate` | 设备模拟(iPhone、iPad 等) |
|
|
344
|
+
| `inputMode` | 查询或设置输入模式(`precise` / `stealth`) |
|
|
345
|
+
| `stealth` | 注入反检测脚本 |
|
|
295
346
|
| `cdp` | 发送原始 CDP 命令(高级,如 `Runtime.evaluate`) |
|
|
296
347
|
|
|
297
348
|
Tab/window 管理动作仅支持 Extension 模式,改变浏览器可见状态的动作必须显式传 `targetId` 或 `windowId`,并返回
|
|
298
|
-
`affected.before/after
|
|
299
|
-
`
|
|
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`
|
|
300
353
|
|
|
301
354
|
**Stealth 模式档位**(CDP launch 参数,通过 `browse action=launch stealth=...` 设置):
|
|
302
355
|
|
|
@@ -306,28 +359,30 @@ Tab/window 管理动作仅支持 Extension 模式,改变浏览器可见状态
|
|
|
306
359
|
|
|
307
360
|
### logs - 浏览器日志
|
|
308
361
|
|
|
309
|
-
| Type | 描述
|
|
310
|
-
|
|
311
|
-
| `console` | 控制台日志(支持级别过滤)
|
|
362
|
+
| Type | 描述 |
|
|
363
|
+
| --------- | ----------------------------- |
|
|
364
|
+
| `console` | 控制台日志(支持级别过滤) |
|
|
312
365
|
| `network` | 网络请求日志(支持 URL 过滤) |
|
|
313
366
|
|
|
314
367
|
参数:`output` 将结果保存到文件,console 日志统一返回公开级别 `error`、`warning`、`info`、`debug`,浏览器原始的 `warn`、
|
|
315
|
-
`log` 等级会在过滤和返回前转换,network 日志包含已完成请求、HTTP 4xx/5xx 响应和加载失败请求,尽量返回
|
|
316
|
-
`url`、`status`、`timestamp`、`duration`,URL
|
|
317
|
-
显式 `output` 文件中替换为 `[REDACTED]`,并返回
|
|
318
|
-
|
|
319
|
-
|
|
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`
|
|
374
|
+
指定目标 Tab(Extension 模式),`frame` 不适用于日志,
|
|
320
375
|
|
|
321
376
|
### cookies - Cookie 管理
|
|
322
377
|
|
|
323
|
-
| Action | 描述
|
|
324
|
-
|
|
325
|
-
| `get` | 获取 Cookie
|
|
326
|
-
| `set` | 设置 Cookie
|
|
327
|
-
| `delete` | 删除 Cookie
|
|
328
|
-
| `clear` |
|
|
378
|
+
| Action | 描述 |
|
|
379
|
+
| -------- | ------------------------------------------------------ |
|
|
380
|
+
| `get` | 获取 Cookie |
|
|
381
|
+
| `set` | 设置 Cookie |
|
|
382
|
+
| `delete` | 删除 Cookie |
|
|
383
|
+
| `clear` | 在 URL 或域名范围内删除 Cookie,可用 `name` 进一步过滤 |
|
|
329
384
|
|
|
330
|
-
**说明**:`clear` 必须指定 `
|
|
385
|
+
**说明**:`clear` 必须指定 `url` 或 `domain`。`name` 只能在该范围内进一步过滤,避免误删其他站点的同名 Cookie
|
|
331
386
|
|
|
332
387
|
## Target:统一元素定位器
|
|
333
388
|
|
|
@@ -335,57 +390,43 @@ network 结果会把脱敏后的单条 URL 限制为 2048 字符,截断时返
|
|
|
335
390
|
|
|
336
391
|
```typescript
|
|
337
392
|
// 按可访问性(推荐 - 最稳定)
|
|
338
|
-
{ role:
|
|
393
|
+
const byRole = { role: 'button', name: '提交' }
|
|
339
394
|
|
|
340
395
|
// 按可访问性精确匹配名称
|
|
341
|
-
{ role:
|
|
396
|
+
const byExactRole = { role: 'button', name: '提交', exact: true }
|
|
342
397
|
|
|
343
398
|
// 按文本内容
|
|
344
|
-
{ text:
|
|
399
|
+
const byText = { text: '点击这里', exact: true }
|
|
345
400
|
|
|
346
401
|
// 按表单 label
|
|
347
|
-
{
|
|
348
|
-
label: "邮箱"
|
|
349
|
-
}
|
|
402
|
+
const byLabel = { label: '邮箱' }
|
|
350
403
|
|
|
351
404
|
// 按 placeholder
|
|
352
|
-
{
|
|
353
|
-
placeholder: "请输入姓名"
|
|
354
|
-
}
|
|
405
|
+
const byPlaceholder = { placeholder: '请输入姓名' }
|
|
355
406
|
|
|
356
407
|
// 按 title 属性
|
|
357
|
-
{
|
|
358
|
-
title: "关闭对话框"
|
|
359
|
-
}
|
|
408
|
+
const byTitle = { title: '关闭对话框' }
|
|
360
409
|
|
|
361
410
|
// 按 alt 文本(图片)
|
|
362
|
-
{
|
|
363
|
-
alt: "头像"
|
|
364
|
-
}
|
|
411
|
+
const byAlt = { alt: '头像' }
|
|
365
412
|
|
|
366
413
|
// 按 test ID
|
|
367
|
-
{
|
|
368
|
-
testId: "submit-button"
|
|
369
|
-
}
|
|
414
|
+
const byTestId = { testId: 'submit-button' }
|
|
370
415
|
|
|
371
416
|
// 按 CSS 选择器
|
|
372
|
-
{
|
|
373
|
-
css: "#login-form .submit-btn"
|
|
374
|
-
}
|
|
417
|
+
const byCss = { css: '#login-form .submit-btn' }
|
|
375
418
|
|
|
376
419
|
// 多匹配消歧(从 0 开始)
|
|
377
|
-
{ css:
|
|
420
|
+
const secondMatch = { css: '.ant-select-input', nth: 1 }
|
|
378
421
|
|
|
379
422
|
// 按 CSS + 文本(按文本内容过滤)
|
|
380
|
-
{ css:
|
|
423
|
+
const byCssText = { css: 'button', text: '提交', exact: true }
|
|
381
424
|
|
|
382
425
|
// 按 XPath
|
|
383
|
-
{
|
|
384
|
-
xpath: "//button[@type='submit']"
|
|
385
|
-
}
|
|
426
|
+
const byXPath = { xpath: "//button[@type='submit']" }
|
|
386
427
|
|
|
387
428
|
// 按坐标
|
|
388
|
-
{ x: 100, y: 200 }
|
|
429
|
+
const byCoordinates = { x: 100, y: 200 }
|
|
389
430
|
```
|
|
390
431
|
|
|
391
432
|
## 使用示例
|
|
@@ -479,7 +520,9 @@ input(events=[
|
|
|
479
520
|
], frame="iframe.login-frame")
|
|
480
521
|
```
|
|
481
522
|
|
|
482
|
-
CSS 选择器和数字索引按父文档的 DOM
|
|
523
|
+
CSS 选择器和数字索引按父文档的 DOM
|
|
524
|
+
iframe 顺序定位,DOM 中不存在的子 frame(包括其他 Extension 加入的 frame)不会改变索引,也不会成为候选目标,所选元素无法对应到唯一 Chrome
|
|
525
|
+
frame 时返回 `FRAME_IDENTITY_UNAVAILABLE`,不会选择其他frame
|
|
483
526
|
|
|
484
527
|
### 等待元素
|
|
485
528
|
|
|
@@ -570,8 +613,8 @@ mcp-chrome/
|
|
|
570
613
|
## 安全说明
|
|
571
614
|
|
|
572
615
|
- **信任边界**:Extension 模式默认自动连接本地 MCP server,在多用户系统、CI runner、`--net=host` 容器等不可信代码可访问
|
|
573
|
-
`127.0.0.1:19222-19299` 的环境中,应使用 `MCP_CHROME_PAIRING_TOKEN`,或设置 `MCP_CHROME_ALLOW_INSECURE_NO_TOKEN=0
|
|
574
|
-
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 的本地恶意进程
|
|
575
618
|
- Extension 模式:共享浏览器会话,请仅在受信任的机器上使用
|
|
576
619
|
- CDP 模式:通过 DevTools Protocol 提供完整浏览器控制能力
|
|
577
620
|
- 默认端口仅绑定到 127.0.0.1(本地访问)
|
|
@@ -584,10 +627,10 @@ mcp-chrome/
|
|
|
584
627
|
`stealth` 模式(`safe` / `aggressive`)仅覆盖少量指纹面:
|
|
585
628
|
|
|
586
629
|
- **覆盖**:`navigator.webdriver`、`cdc_*` 属性、User-Agent 字符串、若干 WebGL vendor/renderer 值、Chrome runtime 属性
|
|
587
|
-
- **不覆盖**:Canvas 指纹、AudioContext 指纹、Font 枚举、TLS 层指纹(JA3/JA4)、CDP
|
|
588
|
-
)、扩展自身存在的探测
|
|
589
|
-
-
|
|
590
|
-
|
|
630
|
+
- **不覆盖**:Canvas 指纹、AudioContext 指纹、Font 枚举、TLS 层指纹(JA3/JA4)、CDP
|
|
631
|
+
attach 横幅("Chrome 正受自动化软件控制")、扩展自身存在的探测
|
|
632
|
+
- **警告**:这些修补不能过 Cloudflare。JS Challenge 和 Turnstile
|
|
633
|
+
checkbox 由导航、input、evaluate 之后在真实浏览器里等待处理,不覆盖 Akamai、DataDome、PerimeterX、交互式验证码或 IP 声誉
|
|
591
634
|
|
|
592
635
|
## 已知限制
|
|
593
636
|
|
|
@@ -605,9 +648,24 @@ MIT 许可证 - 详见 [LICENSE](LICENSE)
|
|
|
605
648
|
- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP 规范
|
|
606
649
|
- [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/) - CDP 文档
|
|
607
650
|
|
|
608
|
-
|
|
609
651
|
## 操作状态与诊断
|
|
610
652
|
|
|
611
|
-
input 和 evaluate 返回值追加 `actionExecuted`、`actionStatus`、`verificationStatus`、`failureStage` 和
|
|
612
|
-
|
|
613
|
-
`
|
|
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。
|