@pyrokine/mcp-chrome 3.0.1 → 3.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1060 -432
- package/README_zh.md +936 -349
- package/dist/cdp/client.d.ts +8 -3
- package/dist/cdp/client.d.ts.map +1 -1
- package/dist/cdp/client.js +260 -63
- package/dist/cdp/client.js.map +1 -1
- package/dist/cdp/launcher.d.ts +1 -1
- package/dist/cdp/launcher.d.ts.map +1 -1
- package/dist/cdp/launcher.js +33 -12
- package/dist/cdp/launcher.js.map +1 -1
- package/dist/core/auto-wait.d.ts.map +1 -1
- package/dist/core/auto-wait.js +88 -52
- package/dist/core/auto-wait.js.map +1 -1
- package/dist/core/browser-driver.d.ts +73 -15
- package/dist/core/browser-driver.d.ts.map +1 -1
- package/dist/core/browser-driver.js.map +1 -1
- package/dist/core/browser-event-schema.d.ts +287 -0
- package/dist/core/browser-event-schema.d.ts.map +1 -0
- package/dist/core/browser-event-schema.js +104 -0
- package/dist/core/browser-event-schema.js.map +1 -0
- package/dist/core/browser-events.d.ts +105 -0
- package/dist/core/browser-events.d.ts.map +1 -0
- package/dist/core/browser-events.js +1482 -0
- package/dist/core/browser-events.js.map +1 -0
- package/dist/core/challenge-page.d.ts +39 -0
- package/dist/core/challenge-page.d.ts.map +1 -0
- package/dist/core/challenge-page.js +231 -0
- package/dist/core/challenge-page.js.map +1 -0
- package/dist/core/dom-helpers.d.ts +28 -0
- package/dist/core/dom-helpers.d.ts.map +1 -0
- package/dist/core/dom-helpers.js +311 -0
- package/dist/core/dom-helpers.js.map +1 -0
- package/dist/core/error-sanitizer.d.ts.map +1 -1
- package/dist/core/error-sanitizer.js +2 -1
- package/dist/core/error-sanitizer.js.map +1 -1
- package/dist/core/errors.d.ts +4 -0
- package/dist/core/errors.d.ts.map +1 -1
- package/dist/core/errors.js +57 -9
- package/dist/core/errors.js.map +1 -1
- package/dist/core/file-upload.d.ts +22 -0
- package/dist/core/file-upload.d.ts.map +1 -0
- package/dist/core/file-upload.js +194 -0
- package/dist/core/file-upload.js.map +1 -0
- package/dist/core/locator.d.ts +11 -2
- package/dist/core/locator.d.ts.map +1 -1
- package/dist/core/locator.js +135 -206
- package/dist/core/locator.js.map +1 -1
- package/dist/core/os-mouse.d.ts +11 -0
- package/dist/core/os-mouse.d.ts.map +1 -1
- package/dist/core/os-mouse.js +104 -29
- package/dist/core/os-mouse.js.map +1 -1
- package/dist/core/retry.d.ts.map +1 -1
- package/dist/core/retry.js +4 -1
- package/dist/core/retry.js.map +1 -1
- package/dist/core/session.d.ts +62 -12
- package/dist/core/session.d.ts.map +1 -1
- package/dist/core/session.js +1174 -304
- package/dist/core/session.js.map +1 -1
- package/dist/core/types.d.ts +5 -1
- package/dist/core/types.d.ts.map +1 -1
- package/dist/core/types.js +16 -1
- package/dist/core/types.js.map +1 -1
- package/dist/core/unified-session.d.ts +48 -37
- package/dist/core/unified-session.d.ts.map +1 -1
- package/dist/core/unified-session.js +982 -294
- package/dist/core/unified-session.js.map +1 -1
- package/dist/core/utils.d.ts +8 -4
- package/dist/core/utils.d.ts.map +1 -1
- package/dist/core/utils.js +76 -18
- package/dist/core/utils.js.map +1 -1
- package/dist/extension/bridge.d.ts +48 -17
- package/dist/extension/bridge.d.ts.map +1 -1
- package/dist/extension/bridge.js +288 -46
- package/dist/extension/bridge.js.map +1 -1
- package/dist/extension/http-server.d.ts +8 -2
- package/dist/extension/http-server.d.ts.map +1 -1
- package/dist/extension/http-server.js +211 -49
- package/dist/extension/http-server.js.map +1 -1
- package/dist/index.js +15 -1
- package/dist/index.js.map +1 -1
- package/dist/tools/browse.d.ts.map +1 -1
- package/dist/tools/browse.js +56 -28
- package/dist/tools/browse.js.map +1 -1
- package/dist/tools/browser-event-output.d.ts +7 -0
- package/dist/tools/browser-event-output.d.ts.map +1 -0
- package/dist/tools/browser-event-output.js +19 -0
- package/dist/tools/browser-event-output.js.map +1 -0
- package/dist/tools/challenge.d.ts +18 -5
- package/dist/tools/challenge.d.ts.map +1 -1
- package/dist/tools/challenge.js +217 -200
- package/dist/tools/challenge.js.map +1 -1
- package/dist/tools/cookies.d.ts.map +1 -1
- package/dist/tools/cookies.js +34 -8
- package/dist/tools/cookies.js.map +1 -1
- package/dist/tools/diagnostics.d.ts.map +1 -1
- package/dist/tools/diagnostics.js +15 -0
- package/dist/tools/diagnostics.js.map +1 -1
- package/dist/tools/evaluate.d.ts +6 -5
- package/dist/tools/evaluate.d.ts.map +1 -1
- package/dist/tools/evaluate.js +94 -52
- package/dist/tools/evaluate.js.map +1 -1
- package/dist/tools/extract.d.ts.map +1 -1
- package/dist/tools/extract.js +293 -153
- package/dist/tools/extract.js.map +1 -1
- package/dist/tools/input.d.ts.map +1 -1
- package/dist/tools/input.js +747 -282
- package/dist/tools/input.js.map +1 -1
- package/dist/tools/logs.d.ts.map +1 -1
- package/dist/tools/logs.js +50 -11
- package/dist/tools/logs.js.map +1 -1
- package/dist/tools/manage.d.ts.map +1 -1
- package/dist/tools/manage.js +123 -18
- package/dist/tools/manage.js.map +1 -1
- package/dist/tools/network-sanitizer.d.ts +2 -0
- package/dist/tools/network-sanitizer.d.ts.map +1 -1
- package/dist/tools/network-sanitizer.js +53 -10
- package/dist/tools/network-sanitizer.js.map +1 -1
- package/dist/tools/page-context.d.ts +4 -3
- package/dist/tools/page-context.d.ts.map +1 -1
- package/dist/tools/page-context.js +57 -14
- package/dist/tools/page-context.js.map +1 -1
- package/dist/tools/png.d.ts.map +1 -1
- package/dist/tools/png.js +12 -3
- package/dist/tools/png.js.map +1 -1
- package/dist/tools/post-condition.d.ts +1 -1
- package/dist/tools/post-condition.d.ts.map +1 -1
- package/dist/tools/post-condition.js +163 -47
- package/dist/tools/post-condition.js.map +1 -1
- package/dist/tools/schema.d.ts +7 -4
- package/dist/tools/schema.d.ts.map +1 -1
- package/dist/tools/schema.js +32 -122
- package/dist/tools/schema.js.map +1 -1
- package/dist/tools/target-diagnostics.d.ts +3 -3
- package/dist/tools/target-diagnostics.d.ts.map +1 -1
- package/dist/tools/target-diagnostics.js +64 -34
- package/dist/tools/target-diagnostics.js.map +1 -1
- package/dist/tools/wait.d.ts.map +1 -1
- package/dist/tools/wait.js +94 -40
- package/dist/tools/wait.js.map +1 -1
- package/extension/dist/assets/{content.ts-qe6IB5DK.js → content.ts-C9QgtUYe.js} +1 -1
- package/extension/dist/assets/{content.ts-loader-DUWbDHRS.js → content.ts-loader-yqB_P8vu.js} +1 -1
- package/extension/dist/assets/index.ts-DBFNh8mZ.js +20275 -0
- package/extension/dist/assets/{page-scripts-D508WLkW.js → page-scripts-BjqQ0zXt.js} +258 -367
- package/extension/dist/assets/{popup.html-B-eVq48O.js → popup.html-DwwHo00N.js} +2 -2
- package/extension/dist/manifest.json +4 -4
- package/extension/dist/service-worker-loader.js +1 -1
- package/extension/dist/src/popup/popup.html +3 -3
- package/package.json +9 -7
- package/scripts/start-chrome.ps1 +9 -1
- package/extension/dist/assets/index.ts-D7_LCUoV.js +0 -9319
package/README_zh.md
CHANGED
|
@@ -13,7 +13,8 @@ Chrome 浏览器自动化 MCP Server,双模式架构: **Extension 模式**
|
|
|
13
13
|
- **双模式**:Extension 模式共享登录状态;CDP 模式用于无头/隔离场景
|
|
14
14
|
- **8 个统一工具**:基于 action 的设计,覆盖浏览、输入、提取、等待、执行、管理、Cookie、日志
|
|
15
15
|
- **多页面定位**:`targetId` 在两种 backend 中指定操作页面,无需切换浏览器焦点;`tabId` 保留为兼容别名
|
|
16
|
-
- **
|
|
16
|
+
- **frame 与 Shadow DOM**:两种后端的 `frame` 均支持子 frame 及逐层选择器/索引路径,CSS、文本和语义查询可进入 open
|
|
17
|
+
shadowRoot
|
|
17
18
|
- **语义化定位**:11 种元素定位方式(role、text、label、css、css+文本组合、xpath、坐标等)
|
|
18
19
|
- **自动等待**:内置可点击性、可输入性检测,基于 deadline 的超时预算机制
|
|
19
20
|
- **双输入模式**:`precise`(debugger API,可绕过 CSP)或 `stealth`(JS 注入,无调试横幅)
|
|
@@ -33,36 +34,6 @@ Chrome 浏览器自动化 MCP Server,双模式架构: **Extension 模式**
|
|
|
33
34
|
|
|
34
35
|
本地零配置自动连接保持不变,刷新 Extension 或重启 MCP client 后不需要手动点击“连接”
|
|
35
36
|
|
|
36
|
-
## 请求范围与失败处理
|
|
37
|
-
|
|
38
|
-
一组输入事件在执行和恢复目标期间保持同一后端、同一页面,并发的 `browse(action="connect")` 等待该请求结束;CDP 请求带
|
|
39
|
-
`frame` 时,在定位或操作 Extension 页面前返回能力错误
|
|
40
|
-
|
|
41
|
-
Extension 通过所选 document 与原生 iframe owner 核对身份,同 URL iframe 重排后不按旧 DOM 索引执行
|
|
42
|
-
|
|
43
|
-
显式 `wait="networkidle"` 在导航前启用 Network 观测,等待请求完成后持续静默 500 ms;观测缺失或中断时返回错误,默认
|
|
44
|
-
`load` 路径不会为了网络空闲检查附加 debugger
|
|
45
|
-
|
|
46
|
-
CDP 网络日志在响应体传输失败时保留 HTTP 状态,每个请求只记录一次终态;临时选择其他 CDP 页面会保留各目标独立的日志
|
|
47
|
-
|
|
48
|
-
输入的 `timeout` 包含页面选择、准备和按键 RPC,最后一次响应超过期限时仍返回超时;执行结果无法确认时返回
|
|
49
|
-
`actionStatus="unknown"` 与 `retryable=false`,读取当前页面状态后再决定下一步
|
|
50
|
-
|
|
51
|
-
分组操作与页面解除受控按涉及的页面串行执行,并在持锁期间重新检查成员和操作权限;创建页面使用 `active`,`activate`
|
|
52
|
-
仅适用于 `movePage`
|
|
53
|
-
|
|
54
|
-
Popup 设置保存失败会显示错误,延迟返回的旧设置不会覆盖新设置;本地默认自动连接继续无需手动配对或点击连接
|
|
55
|
-
|
|
56
|
-
## 兼容客户端
|
|
57
|
-
|
|
58
|
-
| 客户端 | 状态 |
|
|
59
|
-
| ------------------- | ---- |
|
|
60
|
-
| Claude Code | ✅ |
|
|
61
|
-
| Claude Desktop | ✅ |
|
|
62
|
-
| Cursor | ✅ |
|
|
63
|
-
| Windsurf | ✅ |
|
|
64
|
-
| 其他 MCP 兼容客户端 | ✅ |
|
|
65
|
-
|
|
66
37
|
## 安装
|
|
67
38
|
|
|
68
39
|
需要 Node.js 20.19 或更新版本
|
|
@@ -92,44 +63,9 @@ claude mcp add chrome -- node "$PWD/dist/index.js"
|
|
|
92
63
|
|
|
93
64
|
Extension 模式需要在 Chrome 中加载 `extension/dist`
|
|
94
65
|
|
|
95
|
-
###
|
|
66
|
+
### 其他 MCP 客户端
|
|
96
67
|
|
|
97
|
-
|
|
98
|
-
`MCP_CHROME_PORTABLE_DIR` 或 `%USERPROFILE%\\.mcp-chrome\\portable`,也可以在 PowerShell 中启动独立的 CDP 浏览器:
|
|
99
|
-
|
|
100
|
-
```powershell
|
|
101
|
-
& '<npm-root>\@pyrokine\mcp-chrome\scripts\start-chrome.ps1' -Port 9222
|
|
102
|
-
# 也可显式指定便携版可执行文件和独立 profile:
|
|
103
|
-
& '<npm-root>\@pyrokine\mcp-chrome\scripts\start-chrome.ps1' -Port 9222 -ExecutablePath 'C:\Browsers\chrome.exe' -ProfileDir 'C:\Temp\mcp-chrome-profile'
|
|
104
|
-
```
|
|
105
|
-
|
|
106
|
-
随后调用
|
|
107
|
-
`browse(action="connect", port=9222)`,脚本让 Chrome 进程保持前台运行,并报告退出码;使用独立 profile,避免请求被已有 Chrome 实例接管
|
|
108
|
-
|
|
109
|
-
## 快速开始
|
|
110
|
-
|
|
111
|
-
### 模式一:Extension 模式(推荐)
|
|
112
|
-
|
|
113
|
-
Extension 模式操控你现有的 Chrome——共享登录状态、Cookie 和浏览上下文
|
|
114
|
-
|
|
115
|
-
**第一步:安装 Chrome Extension**
|
|
116
|
-
|
|
117
|
-
1. 在 Chrome 中打开 `chrome://extensions/`
|
|
118
|
-
2. 开启右上角"开发者模式"
|
|
119
|
-
3. 点击"加载已解压的扩展程序" → 选择 `mcp-chrome/extension/dist/` 目录
|
|
120
|
-
4. 工具栏出现 MCP Chrome 图标
|
|
121
|
-
|
|
122
|
-
**第二步:配置 MCP 客户端**
|
|
123
|
-
|
|
124
|
-
```bash
|
|
125
|
-
# npm 安装
|
|
126
|
-
claude mcp add chrome -- mcp-chrome
|
|
127
|
-
|
|
128
|
-
# 源码构建
|
|
129
|
-
claude mcp add chrome -- node /path/to/mcp-chrome/dist/index.js
|
|
130
|
-
```
|
|
131
|
-
|
|
132
|
-
Claude Desktop / 其他客户端:
|
|
68
|
+
Claude Desktop 等客户端可使用以下配置,将路径替换为实际的 Server 入口:
|
|
133
69
|
|
|
134
70
|
```json
|
|
135
71
|
{
|
|
@@ -142,32 +78,39 @@ Claude Desktop / 其他客户端:
|
|
|
142
78
|
}
|
|
143
79
|
```
|
|
144
80
|
|
|
145
|
-
|
|
81
|
+
### Windows CDP 启动
|
|
146
82
|
|
|
147
|
-
|
|
148
|
-
`
|
|
149
|
-
会返回当前活动 Extension 后台 bundle 的 hash,并与 server 附带的 bundle 比较, `bundleStatus="stale"`
|
|
150
|
-
表示 Chrome 仍在执行旧的已解压 Extension,需要在 `chrome://extensions/` 刷新该 Extension,旧版 Extension 缺少
|
|
151
|
-
`network_challenge_state` 时会回退为 tab 标题和 DOM 的 Challenge 检测,bundle identity 不会关闭零配置自动连接
|
|
83
|
+
Chrome 自动查找 Windows App Paths、`PATH`、已安装的 Chrome channels、Chromium、Chrome for Testing,以及
|
|
84
|
+
`MCP_CHROME_PORTABLE_DIR` 或 `%USERPROFILE%\\.mcp-chrome\\portable`,也可以在 PowerShell 中启动独立的 CDP 浏览器:
|
|
152
85
|
|
|
86
|
+
```powershell
|
|
87
|
+
& '<npm-root>\@pyrokine\mcp-chrome\scripts\start-chrome.ps1' -Port 9222
|
|
88
|
+
# 也可显式指定便携版可执行文件和独立 profile:
|
|
89
|
+
& '<npm-root>\@pyrokine\mcp-chrome\scripts\start-chrome.ps1' -Port 9222 `
|
|
90
|
+
-ExecutablePath 'C:\Browsers\chrome.exe' -ProfileDir 'C:\Temp\mcp-chrome-profile'
|
|
153
91
|
```
|
|
154
|
-
browse(action="list") // 列出所有 Tab
|
|
155
|
-
browse(action="open", url="https://example.com")
|
|
156
|
-
extract(type="screenshot")
|
|
157
|
-
```
|
|
158
92
|
|
|
159
|
-
|
|
93
|
+
随后调用
|
|
94
|
+
`browse(action="connect", port=9222)`,脚本让 Chrome 进程保持前台运行,并报告退出码;使用独立 profile,避免请求被已有 Chrome 实例接管
|
|
95
|
+
|
|
96
|
+
## 快速开始
|
|
160
97
|
|
|
161
|
-
Extension
|
|
162
|
-
的容器环境中,启动 MCP server 时设置 `MCP_CHROME_PAIRING_TOKEN`,再在 Extension popup 中输入同一个 token:
|
|
98
|
+
### 模式一:Extension 模式(推荐)
|
|
163
99
|
|
|
164
|
-
|
|
165
|
-
|
|
100
|
+
完成[安装](#安装)后,Extension 通过 HTTP/WebSocket 自动连接端口 19222-19299 的本地 MCP
|
|
101
|
+
Server 连接共享现有 Chrome 的登录状态与 Cookie,普通本地使用无需手动配对或点击连接
|
|
102
|
+
|
|
103
|
+
先列出页面,按任务名称和备注复用合适的受控页;没有合适页面时,在现有窗口创建临时示例页;读取时使用返回的
|
|
104
|
+
`targetId`,结束后只关闭本次创建的页面:
|
|
105
|
+
|
|
106
|
+
```text
|
|
107
|
+
browse(action="list")
|
|
108
|
+
manage(action="newPage", url="https://example.com", taskHint="Read example", note="Temporary example page")
|
|
109
|
+
extract(type="text", targetId="CREATED_TARGET_ID")
|
|
110
|
+
manage(action="closePage", targetId="CREATED_TARGET_ID")
|
|
166
111
|
```
|
|
167
112
|
|
|
168
|
-
|
|
169
|
-
popup 关闭“允许无 token 本地连接”,关闭后会立即取消进行中的 health
|
|
170
|
-
check、WebSocket 握手和已安排的重连,旧的无 token 连接尝试不会在策略更新后重新连入
|
|
113
|
+
构建身份与重连见[连接状态与恢复](#连接状态与恢复),强制 token 的环境见[配对与本地访问](#配对与本地访问)
|
|
171
114
|
|
|
172
115
|
### 模式二:CDP 模式(回退)
|
|
173
116
|
|
|
@@ -187,67 +130,97 @@ browse(action="open", url="https://example.com")
|
|
|
187
130
|
> 会为后续工具显式选择 CDP;调用不带 port 的 `browse(action="connect")`
|
|
188
131
|
> 会回到 Extension,仅因回退而建立的 CDP 连接会在 Extension 重连后让出默认模式
|
|
189
132
|
|
|
190
|
-
##
|
|
133
|
+
## Target:统一元素定位器
|
|
191
134
|
|
|
192
|
-
|
|
135
|
+
所有工具使用统一的 `Target` 类型定位元素,CSS、文本、role 和 label 查询按稳定顺序进入 open
|
|
136
|
+
shadowRoot,XPath 保持原生文档树语义
|
|
137
|
+
`aria-labelledby` 按元素所在 DOM tree 查找 ID,保留多引用顺序并优先于
|
|
138
|
+
`aria-label`,`tab`、`checkbox`、`menuitem`
|
|
139
|
+
等允许内容命名的角色包含可见后代文字及嵌套 span,state 名称使用相同规则
|
|
140
|
+
普通 input 在 `value` 和 `pageContent`
|
|
141
|
+
中保留当前值,与名称分开;state 提取不读取 password、hidden 或 file input 的值
|
|
142
|
+
Extension 的 DOM 查询不进入 closed
|
|
143
|
+
shadowRoot
|
|
193
144
|
|
|
194
|
-
|
|
195
|
-
| --------- | -------------------------------------------- |
|
|
196
|
-
| `launch` | Extension 可用时创建受控 Tab,否则启动 CDP |
|
|
197
|
-
| `connect` | 默认确认 Extension,传 `port` 时显式选择 CDP |
|
|
198
|
-
| `list` | 列出所有页面/Tab |
|
|
199
|
-
| `attach` | 附加到指定页面/Tab |
|
|
200
|
-
| `open` | 导航到 URL |
|
|
201
|
-
| `back` | 后退 |
|
|
202
|
-
| `forward` | 前进 |
|
|
203
|
-
| `refresh` | 刷新 |
|
|
204
|
-
| `close` | 关闭 `targetId` 指定的页面 |
|
|
145
|
+
示例:
|
|
205
146
|
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
是默认操作目标,CDP 不用选中的操作目标推断浏览器前台页面,`open`
|
|
210
|
-
自动创建 Tab 分组(cyan 色),`open`、`back`、`forward`、`refresh` 支持 `diagnostics=true`,返回动作期间新增的 console
|
|
211
|
-
warning/error 和失败网络请求摘要,也覆盖首次 `open` 自动创建页面的场景,两个 driver 的 `open` 和 `refresh` 都支持
|
|
212
|
-
`wait="load"`、`wait="domcontentloaded"` 和
|
|
213
|
-
`wait="networkidle"`,等待器会在命令前建立,并绑定命令产生的新主文档,上一导航的迟到生命周期事件不会提前完成等待,CDP模式的
|
|
214
|
-
`networkidle` 等待当前主 frame loader 的 `networkIdle`
|
|
215
|
-
事件;Extension 模式会等待当前文档完成、所有已跟踪响应 body 结束和 500
|
|
216
|
-
ms 静默窗口,请求跟踪发生丢失时返回超时,不会误报空闲,`close` 必须传 `targetId`,且只关闭该页面,不会关闭整个 CDP 连接
|
|
147
|
+
```typescript
|
|
148
|
+
// 按可访问性(推荐 - 最稳定)
|
|
149
|
+
const byRole = { role: 'button', name: '提交' }
|
|
217
150
|
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
`navigated=false`,其他原生错误保留;execution
|
|
221
|
-
context 失效或浏览器拒绝向错误页注入时,仍返回操作失败,Extension 将其记录为预期操作警告;任意 debugger 命令不自动重放
|
|
151
|
+
// 按可访问性精确匹配名称
|
|
152
|
+
const byExactRole = { role: 'button', name: '提交', exact: true }
|
|
222
153
|
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
`timeout=0` 在导航派发前拒绝,页面创建保留独立的加载等待与传输余量合同
|
|
154
|
+
// 按文本内容
|
|
155
|
+
const byText = { text: '点击这里', exact: true }
|
|
226
156
|
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
`contextError`;恢复预算耗尽时单独报告恢复失败,保留主动作结果 CDP 历史等待接受当前 session 主 frame 的 BFCache 恢复或同文档事件,普通 frame
|
|
230
|
-
commit、子 frame 和其他 session 的事件不作为完成信号
|
|
157
|
+
// 按表单 label
|
|
158
|
+
const byLabel = { label: '邮箱' }
|
|
231
159
|
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
`CHALLENGE_TIMEOUT`,保留已知主动作状态;点击结果未知时返回 `TIMEOUT`、已知主动作状态、
|
|
235
|
-
`verificationStatus="unknown"`、`verificationActionExecuted` 和 `retryable=false`,不自动重放导航或点击
|
|
160
|
+
// 按 placeholder
|
|
161
|
+
const byPlaceholder = { placeholder: '请输入姓名' }
|
|
236
162
|
|
|
237
|
-
|
|
238
|
-
|
|
163
|
+
// 按 title 属性
|
|
164
|
+
const byTitle = { title: '关闭对话框' }
|
|
165
|
+
|
|
166
|
+
// 按 alt 文本(图片)
|
|
167
|
+
const byAlt = { alt: '头像' }
|
|
168
|
+
|
|
169
|
+
// 按 test ID
|
|
170
|
+
const byTestId = { testId: 'submit-button' }
|
|
171
|
+
|
|
172
|
+
// 按 CSS 选择器
|
|
173
|
+
const byCss = { css: '#login-form .submit-btn' }
|
|
174
|
+
|
|
175
|
+
// 多匹配消歧(从 0 开始)
|
|
176
|
+
const secondMatch = { css: '.ant-select-input', nth: 1 }
|
|
177
|
+
|
|
178
|
+
// 按 CSS + 文本(按文本内容过滤)
|
|
179
|
+
const byCssText = { css: 'button', text: '提交', exact: true }
|
|
180
|
+
|
|
181
|
+
// 按 XPath
|
|
182
|
+
const byXPath = { xpath: "//button[@type='submit']" }
|
|
183
|
+
|
|
184
|
+
// 按坐标
|
|
185
|
+
const byCoordinates = { x: 100, y: 200 }
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
纯文本 target 选择完整文本匹配的最内层元素,支持多个嵌套文本节点;显式 XPath 保持文档顺序;两种后端均结合 display、visibility 与非零尺寸判断可见性,
|
|
189
|
+
hidden/detached 的目标初始不存在时第一次查询即成功
|
|
190
|
+
|
|
191
|
+
两种 backend 的 `input`、`extract`、`wait` 定位失败都在请求预算内返回失败 locator、从 0 开始的
|
|
192
|
+
`nth`、URL、tab/frame 作用域、managed 状态、最后定位状态及最多 10 个候选摘要;`matchCount`
|
|
193
|
+
表示实际观察到的匹配总量,不受候选摘要上限限制,nth 越界不会把 15 个匹配写成 0;匹配数或 managed 状态无法确认时返回
|
|
194
|
+
null,诊断不可用时返回
|
|
195
|
+
`diagnosticError`
|
|
196
|
+
CDP 查找失败保留 `ELEMENT_NOT_FOUND`,元素等待保留
|
|
197
|
+
`TIMEOUT`,原 URL 和日志字段继续保留,诊断在退出失败目标作用域前读取,不重放输入
|
|
198
|
+
|
|
199
|
+
两种 backend 的定向操作均直接查询
|
|
200
|
+
`target.nth`,支持超过默认 50 条候选展示上限及纯文本第 200 项之后的索引;单目标结果只表示该目标是否存在,未经独立统计时,诊断中的
|
|
201
|
+
`matchCount` 为 `null`;元素等待检查选定目标,存在的高索引元素不会因候选展示有数量上限而满足 `hidden` 或 `detached`
|
|
239
202
|
|
|
240
203
|
页面类工具在两种 backend 中都接受 `targetId`,旧版 `tabId`
|
|
241
204
|
仍可用;同时提供时两者必须一致,显式目标只作用于当前操作,结束后恢复原默认目标,`browse.close` 和 `manage.closePage`
|
|
242
205
|
必须显式指定 ID,页面动作成功或失败时,响应中的 `pageContext`
|
|
243
|
-
包含实际目标及来源(`explicit`、`default`、`created`、`reused`、`unconfirmed`)、前后 URL/revision、默认目标前后状态,以及
|
|
206
|
+
包含实际目标及来源(`explicit`、`default`、`created`、`reused`、`unconfirmed`)、前后 URL/revision、默认目标前后状态,以及
|
|
207
|
+
Extension 报告的浏览器活动目标;
|
|
208
|
+
创建页面失败且未返回创建 ID 时标为
|
|
244
209
|
`unconfirmed`,CDP 的活动状态标为不可用,不把操作目标当作前台页面
|
|
245
210
|
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
211
|
+
这些快照、browse 结果、页面/窗口管理、state、metadata 和诊断包中的页面 URL 会脱敏 `ticket` 等认证查询参数,返回
|
|
212
|
+
`urlRedacted`、`urlOriginalLength` 和 `redactedQueryParameters`;原生 `pendingUrl`、`favIconUrl`
|
|
213
|
+
使用对应字段名前缀的标记;导航等待和导航错误文案使用相同展示脱敏,导航与 `expectedUrl`
|
|
214
|
+
比较使用原始 URL,页面正文和用户脚本结果保留请求的内容;条件操作使用 `expectedRevision`
|
|
215
|
+
或自行持有的原始 URL,脱敏后的展示 URL 不用于 `expectedUrl`
|
|
216
|
+
|
|
217
|
+
旧 Extension 缺少 `page_snapshot` 时,无条件页面动作使用实时页面列表中的 URL,`pageContext.before` 和 `after` 返回
|
|
218
|
+
`revision=null`,并通过 `warning` 说明 revision 与原子条件不可用;传入 `expectedUrl` 或 `expectedRevision`
|
|
219
|
+
时,在派发前返回 `DRIVER_CAPABILITY_ERROR`、`actionExecuted=false` 和
|
|
220
|
+
`actionStatus="not_started"`,更新 Extension 后才能使用这些条件
|
|
221
|
+
|
|
222
|
+
evaluate 和 input 保留
|
|
223
|
+
`failureStage="precondition"`,顶层状态与错误上下文一致,脚本和输入事件保持未派发;其他快照错误仍阻止动作,兼容读取共用原 timeout 预算
|
|
251
224
|
|
|
252
225
|
Extension 页面快照确认目标 tab 已不存在时返回 `TARGET_NOT_FOUND`,保留 `context.targetId` 和原始
|
|
253
226
|
`context.nativeMessage`;输入派发前被拒绝时保留
|
|
@@ -265,11 +238,162 @@ Chrome 已返回创建标识后,失败响应保留 `error.context.createdTarge
|
|
|
265
238
|
继续持久选择默认目标,并发响应记录各自实际操作的页面
|
|
266
239
|
|
|
267
240
|
`browse.list` 返回各页面的 revision 和元数据,revision 由 backend
|
|
268
|
-
epoch 与单页计数构成;Extension 跟踪主 frame 导航和 MCP 动作,CDP 跟踪已附加页面的导航,并保守计入发出的变更命令,包括
|
|
241
|
+
epoch 与单页计数构成;Extension 跟踪主 frame 导航和 MCP 动作,CDP 跟踪已附加页面的导航,并保守计入发出的变更命令,包括
|
|
242
|
+
evaluate,网页自身的任意 DOM 更改不在跟踪范围内,条件动作前应重新获取
|
|
243
|
+
URL/revision,`browse`
|
|
269
244
|
导航/关闭、`input`、`evaluate` 及适用的 `manage` 页面动作接受 `expectedUrl` 和
|
|
270
245
|
`expectedRevision`;backend 检查不符时返回
|
|
271
246
|
`ACTION_PRECONDITION_FAILED`,不发送对应页面动作,复合动作在首个变更命令前检查,不在每个事件前重复检查;失败或超时后如已产生部分效果,revision 仍可能变化
|
|
272
247
|
|
|
248
|
+
## 请求范围与失败处理
|
|
249
|
+
|
|
250
|
+
一组输入事件在执行与恢复目标期间保持同一后端、同一页面,并发的 `browse(action="connect")`
|
|
251
|
+
等待该请求结束;CDP 绑定所选 frame 的执行上下文与 OOPIF session;Extension 核对 document 与原生 iframe owner,同 URL
|
|
252
|
+
iframe 重排后仍保持所选身份
|
|
253
|
+
|
|
254
|
+
input 与 evaluate 的排队、页面选择、准备、派发和验证共用请求预算;MCP 取消或预算结算后,停止排队脚本、剩余事件及后续页面状态和诊断读取,使用独立有界的清理预算释放本次请求新按下的键;最终事件已确认时,
|
|
255
|
+
后续响应处理超期仍保留
|
|
256
|
+
`actionStatus="completed"`;已派发但未收到确认的动作保留 `unknown` 与 `retryable=false`,再次操作前独立读取当前页面
|
|
257
|
+
|
|
258
|
+
坐标输入等待同步滚动级联,包括准备期间出现的 open Shadow
|
|
259
|
+
roots,结束后读取当前 frame-local 矩形,目标稳定时不受无关 requestAnimationFrame 滚动阻挡;持续同步自滚动由请求期限终止,目标保持静止时也适用
|
|
260
|
+
|
|
261
|
+
MCP 取消也会停止排队的窗口和分组变更,Extension 在异步前置读取后、原生变更与尚未提交的受控状态、读取授权或备注更新前检查请求;存储提交成功后继续同步内存,创建后的登记与关闭后的清理继续完成;事件 ref 控制独立于页面队列,
|
|
262
|
+
其他操作等待期间仍可处理弹窗或暂停请求
|
|
263
|
+
|
|
264
|
+
extract 的排队、页面读取与导出使用同一取消信号,Cookie、日志、事件、evaluate 与 extract 输出在文件准备和最终发布前检查 signal 与 deadline;取消后停止后续读取、
|
|
265
|
+
未发布文件和后续日志 manifest,已发布文件保留,临时文件清理继续完成;脚本已完成时,输出取消仍保留其执行状态
|
|
266
|
+
|
|
267
|
+
## 操作状态与诊断
|
|
268
|
+
|
|
269
|
+
input 与 evaluate 分别报告执行事实和后置验证:
|
|
270
|
+
|
|
271
|
+
- `actionExecuted`
|
|
272
|
+
- 取值:`false`、`true`、`"unknown"`
|
|
273
|
+
- 含义:已知的用户主动作执行事实
|
|
274
|
+
|
|
275
|
+
- `actionStatus`
|
|
276
|
+
- 取值:`not_started`、`completed`、`failed`、`unknown`
|
|
277
|
+
- 含义:用户主动作结果
|
|
278
|
+
|
|
279
|
+
- `verificationStatus`
|
|
280
|
+
- 取值:`matched`、`not_matched`、`unavailable`、`error`
|
|
281
|
+
- 含义:后置条件观测结果
|
|
282
|
+
|
|
283
|
+
- `failureStage`
|
|
284
|
+
- 取值:context、precondition、queue、action、verification 或 output
|
|
285
|
+
- 含义:失败阶段
|
|
286
|
+
|
|
287
|
+
- `retryable`
|
|
288
|
+
- 取值:Boolean
|
|
289
|
+
- 含义:主动作是否适合重新执行
|
|
290
|
+
|
|
291
|
+
- `diagnosticsStatus`
|
|
292
|
+
- 取值:附加诊断状态
|
|
293
|
+
- 含义:保留主动作结果及失败前已收集的诊断
|
|
294
|
+
|
|
295
|
+
页面主动抛错时保留消息原文,包括空字符串、JSON 形式文本和 primitive 值,返回
|
|
296
|
+
`actionExecuted=true`、`actionStatus="failed"`,已有异常 description 与堆栈保持;脚本正常执行且返回值完成 Promise 等待后,类型检查、诊断字段读取、
|
|
297
|
+
结果与错误详情的 JSON 编码或解析失败返回
|
|
298
|
+
`actionExecuted=true`、`actionStatus="completed"`、`failureStage="output"` 和
|
|
299
|
+
`retryable=false`,stealth 模式使用相同规则;等待返回值时的 Promise 拒绝按页面动作失败处理,错误摘要无法解析时,通过
|
|
300
|
+
`error.context.originalOutputError` 保留首次输出诊断
|
|
301
|
+
|
|
302
|
+
初始快照读取失败返回 `false/not_started`、`failureStage="context"` 和 `pageContext.contextPhase="before"`;检查
|
|
303
|
+
`expectedUrl` 或 `expectedRevision` 的快照使用 `precondition`
|
|
304
|
+
阶段
|
|
305
|
+
目标、frame、Challenge、参数或逐事件准备 RPC 的回执未知或内部求值输出失败,且用户主动作尚未派发时,顶层仍为
|
|
306
|
+
`false/not_started/context`,原错误 context 保留辅助操作自身的执行事实,已确认的前序输入继续计数,迟到回执不派发或重放用户动作
|
|
307
|
+
|
|
308
|
+
页面条件不匹配返回 `false/not_started/precondition`,目标诊断读取当前 tab 实时状态
|
|
309
|
+
|
|
310
|
+
### 原生失败与诊断
|
|
311
|
+
|
|
312
|
+
原生脚本终止,以及 CDP `Runtime` 脚本命令返回 `Internal error`、`Object couldn't be returned by value` 或
|
|
313
|
+
`Object reference chain is too long` 时,evaluate 和 `manage cdp` 保留原错误码,返回
|
|
314
|
+
`actionExecuted=true`、`actionStatus="unknown"`、`retryable=false`,不重放命令;evaluate 的执行中 RPC 超时或过期 execution
|
|
315
|
+
context 导致结果未知时也不可直接重试;派发前失败按返回的 retryable 字段处理;页面主动抛出的同名异常按动作失败处理,重试标记为 false
|
|
316
|
+
|
|
317
|
+
Extension 中已识别的原生 CDP 拒绝返回
|
|
318
|
+
`CDP_ERROR`,保留 method、目标、原生消息和可用的协议 code,context 区分 Debugger 域未启用、scriptId 失效、浏览器级命令限制、方法不存在、
|
|
319
|
+
命令权限拒绝(`Not allowed`)及原生结果序列化失败;资源或方法查找失败保留对应类别,调用保持失败并输出 warning;未知异常继续按 error 报告;原生快照或权限检查发现的已关闭 tab 按目标失败处理,
|
|
320
|
+
页面主动抛出的同文案保留页面异常来源
|
|
321
|
+
|
|
322
|
+
Extension 将已识别的受限页诊断拒绝、已关闭弹窗、过期或类型不匹配的事件 ref、冲突的 Cookie 分区和已移除的 frame 按 warning
|
|
323
|
+
记录,调用保留原失败响应;页面脚本异常和未知故障继续按 error 记录
|
|
324
|
+
|
|
325
|
+
## 可用工具(8 个)
|
|
326
|
+
|
|
327
|
+
### browse - 浏览器管理与导航
|
|
328
|
+
|
|
329
|
+
| Action | 描述 |
|
|
330
|
+
| --------- | -------------------------------------------- |
|
|
331
|
+
| `launch` | Extension 可用时创建受控 Tab,否则启动 CDP |
|
|
332
|
+
| `connect` | 默认确认 Extension,传 `port` 时显式选择 CDP |
|
|
333
|
+
| `list` | 列出所有页面/Tab |
|
|
334
|
+
| `attach` | 附加到指定页面/Tab |
|
|
335
|
+
| `open` | 导航到 URL |
|
|
336
|
+
| `back` | 后退 |
|
|
337
|
+
| `forward` | 前进 |
|
|
338
|
+
| `refresh` | 刷新 |
|
|
339
|
+
| `close` | 关闭 `targetId` 指定的页面 |
|
|
340
|
+
|
|
341
|
+
默认 `launch` 使用已连接的 Extension;显式指定 `headless`、`incognito`、`userDataDir`、`executablePath` 或 `port`
|
|
342
|
+
时启动独立 CDP 浏览器并返回 `mode="cdp"`
|
|
343
|
+
已有 CDP 连接时,在创建或关闭浏览器前报告冲突,传入的启动设置会实际应用或明确拒绝
|
|
344
|
+
|
|
345
|
+
Extension 特有:`list` 返回 flat `targets` 数组和树状 `windows`,每个 target 含 `managed`(Tab 是否由 MCP
|
|
346
|
+
Chrome 受控)、`isActive`(该窗口中 Chrome 的活动 Tab)、`windowId`、`index`、`pinned`、`incognito`、`status`(`loading`/
|
|
347
|
+
`complete`),摘要模式返回 `windowCount` 和每个窗口按顺序排列的 `targetIds`,`details="full"`
|
|
348
|
+
返回完整的页面与窗口原生属性;Chrome 有聚焦窗口时,`focusedWindowId` 指向该窗口,`activeTargetId`
|
|
349
|
+
指向该窗口的活动页面;没有聚焦窗口时省略这两个字段,各窗口仍返回自己的 `activeTabId`;`defaultTargetId`
|
|
350
|
+
是默认操作目标,CDP 不用选中的操作目标推断浏览器前台页面,`open` 创建新页面时复用该窗口内的可信自动组,新组短标题为 MCP,初始颜色为 cyan
|
|
351
|
+
`open`、`back`、`forward`、`refresh` 支持 `diagnostics=true`,返回动作期间新增的 console
|
|
352
|
+
warning/error 和失败网络请求摘要,也覆盖首次 `open` 自动创建页面的场景,两个 driver 的 `open` 和 `refresh` 都支持
|
|
353
|
+
`wait="load"`、`wait="domcontentloaded"` 和
|
|
354
|
+
`wait="networkidle"`,等待器会在命令前建立,并绑定命令产生的新主文档,上一导航的迟到生命周期事件不会提前完成等待,CDP 模式的
|
|
355
|
+
`networkidle` 等待当前主 frame loader 的 `networkIdle`
|
|
356
|
+
事件;Extension 模式会等待当前文档完成、所有已跟踪响应 body 结束和 500
|
|
357
|
+
ms 静默窗口,请求跟踪发生丢失时返回超时,不会误报空闲,`close` 必须传 `targetId`,且只关闭该页面,不会关闭整个 CDP 连接
|
|
358
|
+
|
|
359
|
+
Extension 模式的 `back/forward` 在可访问的主文档中逐项访问相邻历史,之前通过 `open`
|
|
360
|
+
创建且没有用户交互的历史项也会保留;导航使用隔离环境中的浏览器 History API,页面保持后台,导航过程不附加 debugger
|
|
361
|
+
已知方向边界立即返回 `navigated=false`,仅在 Navigation API 的条目覆盖完整浏览器历史时使用其方向标记判断边界
|
|
362
|
+
待提交的导航、受限 URL、浏览器错误页和不存在的主 frame 保留浏览器原生界面的历史选择规则,保持零脚本注入;原生失败和注入失败保留原错误,每次最多派发一次导航
|
|
363
|
+
已派发遍历但未观察到导航信号时返回超时,动作状态保持 unknown
|
|
364
|
+
execution context 失效或浏览器拒绝向错误页注入时,操作返回失败,Extension 将其记录为预期操作警告;任意 debugger 命令保持不自动重放
|
|
365
|
+
|
|
366
|
+
CDP 历史导航命令明确拒绝时,返回原错误并立即结束本次等待,后续请求继续可用
|
|
367
|
+
|
|
368
|
+
`open`、`back`、`forward`、`refresh` 的 `timeout`
|
|
369
|
+
从请求入口开始计时,页面准备、排队、协议请求、加载、Challenge 检查与点击、诊断和目标恢复共用剩余预算,导航 RPC
|
|
370
|
+
使用原期限作为传输期限;队列中的动作到期后停止派发,后续请求仍等待原在途动作结束;显式
|
|
371
|
+
`timeout=0`
|
|
372
|
+
在导航派发前拒绝,页面创建保留独立的加载等待与传输余量合同;导航等待耗尽请求期限后,停止后续页面信息和诊断读取;较短子操作的等待超时保留请求剩余预算
|
|
373
|
+
|
|
374
|
+
MCP 取消会停止尚未派发的排队 browse 动作,并结束当前导航或 Challenge 等待,同一 signal 也会停止等待结束后的系统鼠标命令和 CDP 启动步骤,启动清理只终止本请求创建且尚未交付的进程
|
|
375
|
+
|
|
376
|
+
鼠标已经按下时,请求持有 tab 锁直到必要释放完成或独立的 5000
|
|
377
|
+
ms 清理预算结束,期间后续导航和输入继续排队,释放失败或超时返回 `releaseStatus="unknown"`
|
|
378
|
+
和明确错误,应检查并释放鼠标按键后再继续操作
|
|
379
|
+
|
|
380
|
+
导航已确认完成、随后状态读取失败时,保留 `actionExecuted=true`、`actionStatus="completed"`、`failureStage="metadata"` 和
|
|
381
|
+
`retryable=false`,页面验证保留自身结果
|
|
382
|
+
|
|
383
|
+
超时不会撤回已经派发的 Chrome 操作,结果未知时返回 `TIMEOUT`、`actionExecuted="unknown"`、`actionStatus="unknown"` 和
|
|
384
|
+
`retryable=false`,应读取实际页面状态后决定下一步;`pageContext.after` 使用实时快照,无法取得时为 null 并附
|
|
385
|
+
`contextError`;恢复预算耗尽时单独报告恢复失败,保留主动作结果;CDP 历史等待接受当前 session 主 frame 的 BFCache 恢复或同文档事件,普通 frame
|
|
386
|
+
commit、子 frame 和其他 session 的事件不作为完成信号
|
|
387
|
+
|
|
388
|
+
Challenge 点击、detach 和检查 RPC 携带剩余 deadline,排队或页面校验耗尽预算后不再派发;系统鼠标移动与 fallback 进程使用同一
|
|
389
|
+
deadline
|
|
390
|
+
CDP 已开始的按下始终尝试向原连接、原 session 释放,清理最多等待 1 秒,释放只发往原目标;只读 Challenge 检查到期返回
|
|
391
|
+
`CHALLENGE_TIMEOUT`,保留已知主动作状态;点击结果未知时返回 `TIMEOUT`、已知主动作状态、
|
|
392
|
+
`verificationStatus="unknown"`、`verificationActionExecuted` 和 `retryable=false`,不自动重放导航或点击
|
|
393
|
+
|
|
394
|
+
evaluate 在成功、动作失败、后置验证不匹配和输出失败时保留 Challenge 结果字段 `originResponsePending=true`
|
|
395
|
+
表示验证成功但源站尚未响应,不表示目标内容已加载
|
|
396
|
+
|
|
273
397
|
`browse` 仅 `open`、`back`、`forward`、`refresh`、`close` 接受这两个条件,`attach` 等其他动作在改变目标前返回
|
|
274
398
|
`INVALID_ARGUMENT`
|
|
275
399
|
|
|
@@ -278,61 +402,114 @@ epoch 与单页计数构成;Extension 跟踪主 frame 导航和 MCP 动作,C
|
|
|
278
402
|
撤销完整权限,保留页面、窗口归属和分组,清理 MCP 日志状态、debugger 和 console 采集资源;Chrome 阻止资源清理时返回
|
|
279
403
|
`warnings`,完整权限仍被撤销
|
|
280
404
|
|
|
281
|
-
受控权限在 Service
|
|
282
|
-
|
|
283
|
-
|
|
405
|
+
受控权限在 Service
|
|
406
|
+
Worker 重启后保留,重载 Extension 后,仍存活且原文档身份一致的受控页也会恢复权限,无需刷新页面或重新 adopt;文档身份不可取得的页面在重载
|
|
407
|
+
Extension 后需要显式
|
|
408
|
+
`adoptPage`;正常导航保留受控权限,`releasePage` 撤销的权限在重启或重载后仍保持撤销,仅复用 tab ID 不会授权另一份文档
|
|
284
409
|
|
|
285
410
|
受控页在 Service Worker 重启后可继续使用本 Extension 已有的调试连接,其他调试器占用仍返回 `DEBUGGER_BLOCKED`
|
|
286
411
|
|
|
287
412
|
通过 `manage(action="grantReadAccess", targetId=...)` 授予普通读取权限,用 `revokeReadAccess`
|
|
288
413
|
撤销,无需点击 popup;两个动作必须显式指定目标,可传
|
|
289
|
-
`expectedUrl`/`expectedRevision`;授权限定当前调用服务器实例、documentId、URL 和 revision,存储失败返回错误,不报告授权成功;popup
|
|
414
|
+
`expectedUrl`/`expectedRevision`;授权限定当前调用服务器实例、documentId、URL 和 revision,存储失败返回错误,不报告授权成功;popup
|
|
415
|
+
保留为可选入口,同一连接和文档未变化时,
|
|
416
|
+
Service
|
|
290
417
|
Worker 重启后仍可读取;导航、关闭页面或断开连接后授权失效,仅指定 `targetId`
|
|
291
|
-
不授予读取权限;普通只读授权覆盖定向文本、HTML、属性、计算样式及页面状态读取,任意脚本、debugger、截图、输入和 Cookie 访问不继承授权,现有
|
|
418
|
+
不授予读取权限;普通只读授权覆盖定向文本、HTML、属性、计算样式及页面状态读取,任意脚本、debugger、截图、输入和 Cookie 访问不继承授权,现有
|
|
419
|
+
Cookie 工具仍按独立的 URL/name 过滤规则执行
|
|
292
420
|
|
|
293
421
|
页面管理或导航因缺少受控权限而被拒绝时,不更新 revision,已有有效的普通只读授权保持不变
|
|
294
422
|
|
|
295
|
-
`manage(action="pageMetadata", targetId=...)`
|
|
296
|
-
`
|
|
297
|
-
`
|
|
423
|
+
`manage(action="pageMetadata", targetId=...)` 读取或更新 `taskHint`、`note`,支持
|
|
424
|
+
`expectedUrl`/`expectedRevision`,条件不符时返回 `ACTION_PRECONDITION_FAILED`,不读取或更新备注;Extension 持久保存来源
|
|
425
|
+
`origin=created/adopted/unknown`、创建时间和任务备注;旧 v1 记录迁移为 unknown,受控访问保持可用;Server 重启后以 Extension 返回的最新元数据为准,存储失败明确报错;
|
|
426
|
+
CDP 元数据保存在当前 Server 进程中;来源、文档身份及可信原生关系由 Extension 维护,备注不授予内容访问权限
|
|
427
|
+
|
|
428
|
+
执行任务先 `browse list`,按任务名称和备注选择已有页面,后台 `attach` 复用;确无合适页才 `newPage`,同时设置
|
|
429
|
+
`taskHint`
|
|
430
|
+
和说明临时、产物或可复用用途的 `note`,`newPage` 始终创建新页
|
|
431
|
+
|
|
432
|
+
`taskHint` 写具体对象+动作或目的,如“车道查询修复”“构建失败排查”“登录流程验证”,保留完整含义,用于识别和复用页面
|
|
433
|
+
任务名称保存在页面元数据中,与原生组名独立;同一任务跨页面、站点和阶段沿用同名,不同任务按目的区分;HIL/仿真、任务号、版本、进度和页面具体用途写入 `note`
|
|
434
|
+
|
|
435
|
+
`newPage` 默认在现有普通窗口后台创建,同一连接的持续工作跨步骤复用可信工作组,其他活动连接分别组织
|
|
436
|
+
重启后先 list、attach 原工作页,再创建的页面会恢复到对应工作组;归属恢复核对可信创建记录、实际成员和其他活动连接,用户自建组及混合用户组保持原状
|
|
437
|
+
为工作组自主选择简短用途名,如 MCP·发版,用已有 `updateGroup` 设置;内部子任务沿用原组,完整任务信息留在页面备注中
|
|
438
|
+
新组初始名称为 MCP 加上长度受限的 taskHint、URL 主机名或“浏览”,同名新组用序号区分;新组初始展开,后续创建及备注变化保留用户标题、颜色和折叠状态
|
|
439
|
+
操作冻结的可信工具组时自动展开并保持前台标签,用户组、混合组和其他活动连接的组保持原状;名称、颜色和折叠更新独立于页面脚本执行,展开可以恢复被冻结的页面
|
|
440
|
+
移动、关闭或原生成员变化会清理失效关系;无普通窗口时返回错误,缓存丢失不创建窗口
|
|
441
|
+
|
|
442
|
+
任务完成后通过已有 close/release 处理明确页面集合,默认只关闭本任务创建且备注明确临时的页面;保留 adopted/unknown、产物页、可复用测试页和混合用户组,按已有入口释放已不用的临时权限;
|
|
443
|
+
显式授权关闭继续使用原受控页合同,断线及闲置不关闭页面;原生分组仅支持 Extension,CDP 接受纯
|
|
444
|
+
`taskHint/note`
|
|
445
|
+
|
|
446
|
+
显式 `networkidle` 在导航前启用 Network 观测,新页也在观测准备就绪后才开始加载 URL,等待已跟踪请求完成后持续静默 500
|
|
447
|
+
ms;观测缺失或中断时返回错误,默认 `load` 路径不为网络空闲检查附加 debugger
|
|
298
448
|
|
|
299
449
|
### 访问验证
|
|
300
450
|
|
|
451
|
+
只读检查尚未完成时,保留
|
|
452
|
+
`challengeState="unverified"`,普通标题与普通 headers 继续等待可见内容检查,在原请求期限内重新读取;检查预算耗尽且未取得验证证据时,返回
|
|
453
|
+
`TIMEOUT`、`verificationStatus="unavailable"` 和 `autoRetry=false`;原生读取回执未知时,`verificationActionExecuted` 与
|
|
454
|
+
`verificationActionStatus` 保留 unknown;已观察到的验证继续返回 `CHALLENGE_TIMEOUT`
|
|
455
|
+
与实际类型,导航已完成时保留完成事实,只读重试不重放导航或业务动作
|
|
456
|
+
|
|
301
457
|
`open`、`back`、`forward`、`refresh`、`input` 和 `evaluate` 之后,MCP Chrome 会等待 Cloudflare JS Challenge 或 Turnstile
|
|
302
|
-
checkbox,Extension 模式下,导航先不启用 debugger 日志采集;Challenge 标题持续期间,前八秒只被动读取真实 tab 标题,interstitial
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
458
|
+
checkbox,Extension 模式下,导航先不启用 debugger 日志采集;Challenge 标题持续期间,前八秒只被动读取真实 tab 标题,interstitial
|
|
459
|
+
持续存在时,才检查可见 Turnstile 控件,
|
|
460
|
+
找到后才点击,Extension
|
|
461
|
+
inspect 走 isolated
|
|
462
|
+
world,Challenge 标题在检查前卸掉 debugger,普通页面检查保留已有调试连接,发现可见验证控件或仍需验证的正文后才卸除;同页测试按钮走页面点击,出现
|
|
463
|
+
Cloudflare
|
|
464
|
+
Turnstile iframe 时,把 inspect 的 CSS 坐标换成屏幕坐标,系统鼠标沿路径移动、悬停后再按下抬起:Linux 用 `xdotool`
|
|
465
|
+
读取活动 Chrome client 窗口几何,用 `xprop` 读取 GTK frame
|
|
466
|
+
extents,窗口标题必须对应该测试页;缺少工具、窗口数据无效或与页面视口不符时停止点击,不用 Chrome `screenX` 或
|
|
307
467
|
`outerHeight - innerHeight` 猜测内容原点;macOS 用 `cliclick` 或 System Events;Windows 用 PowerShell
|
|
308
468
|
`mouse_event`,widget 点 compact
|
|
309
469
|
Turnstile 卡片左侧 checkbox,宿主 wrapper 比卡片宽时也只点左侧卡片,不点文案,DOM 里已有 Cloudflare
|
|
310
470
|
iframe 时,即使 iframe 尺寸为 0,也走系统鼠标,不改用页面点击,后续宿主页 `Verify you are human` / `请验证您是真人`
|
|
311
471
|
按钮同样走系统鼠标,系统鼠标只在受控测试页已经是已聚焦窗口的活动 tab 时使用,混合窗口不会调用 `focusWindow`
|
|
312
472
|
|
|
313
|
-
系统点击前会卸掉 debugger
|
|
473
|
+
系统点击前会卸掉 debugger,路径移动和悬停结束后、按下前重新检查控件位置、视口与活动窗口;Linux 在悬停后以 1
|
|
474
|
+
px 原生往返校准提示条动画期间的内容原点;动画使指针经过不同元素时,在原 timeout 内重新采样,取得同一元素内的两条可信事件后才接受原点;控件位置变化时,重新移动、悬停并校准后点击;页面、验证阶段或焦点变化时停止点击,缺少系统鼠标工具或窗口未聚焦时返回可见错误
|
|
314
475
|
|
|
315
|
-
widget 要连续两次 inspect 到同一坐标才点,不以普通元素的尺寸认定 widget;系统鼠标从远处过来时从控件附近起步,同一类
|
|
476
|
+
widget 要连续两次 inspect 到同一坐标才点,不以普通元素的尺寸认定 widget;系统鼠标从远处过来时从控件附近起步,同一类
|
|
477
|
+
checkbox 或 compact
|
|
316
478
|
widget 在同一次等待里最多点一次;Cloudflare 随后换成可见的 `Verify you are human` 或 `请验证您是真人`
|
|
317
479
|
按钮时,inspect 判成 `verify` 后再点一次,访问受 Cloudflare 保护的页面默认保持
|
|
318
480
|
`diagnostics=false`,因为 diagnostics 会启用 debugger 的 console 和 network 采集
|
|
319
481
|
|
|
320
|
-
检测覆盖 `Just a moment...`、`请稍候…` 等标题、可见的 Challenge DOM、正文标记和 `Verify you are human` /
|
|
321
|
-
控件,包括精确匹配这两种文案的可见 `button`
|
|
482
|
+
检测覆盖 `Just a moment...`、`请稍候…` 等标题、可见的 Challenge DOM、正文标记和 `Verify you are human` /
|
|
483
|
+
`请验证您是真人` 控件,包括精确匹配这两种文案的可见 `button`
|
|
484
|
+
元素;普通标题也会进行有界的可见内容检查,可见的“正在进行安全验证”会阻止业务动作,隐藏标记不计入判定,无验证标记的页面不会固定等待八秒
|
|
322
485
|
|
|
323
486
|
没有 Cloudflare iframe 时,同页按钮使用页面点击,CDP 用 `Target.getTargetInfo` 读取实时标题
|
|
324
|
-
页面恢复后,仅残留 Cloudflare
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
487
|
+
页面恢复后,仅残留 Cloudflare
|
|
488
|
+
iframe 或旧 pending header 不算等待中,也不触发滚动或点击,缓存标题不参与判定
|
|
489
|
+
MCP Chrome 不调用 CAPTCHA
|
|
490
|
+
solver、自动重试导航或导出 `cf_clearance` 的值
|
|
491
|
+
CDP 超时后,先检查返回的 `mode`,再核实网站在用户真实 Chrome 中的状态
|
|
492
|
+
|
|
493
|
+
内嵌控件完成后可保留容器,与该控件关联的非空 response 标记完成状态,reset 或过期后恢复待验证状态
|
|
494
|
+
多个控件分别判断,其他表单中的 response 不会使当前控件完成,检测只返回完成状态,不返回 response 值
|
|
495
|
+
|
|
496
|
+
input 与 evaluate 在动作返回后使用剩余预算检查新验证,验证失败仍保留动作已完成状态,不重放动作
|
|
497
|
+
最终事件已确认完成且预算已用尽时,返回
|
|
498
|
+
`challengeVerificationStatus="unavailable"`,说明动作后的验证检查未执行
|
|
499
|
+
动作完成后的超时返回 `retryable=false` 和
|
|
500
|
+
`nextAction="wait_and_verify"`,等待验证结束后核验业务结果
|
|
501
|
+
|
|
502
|
+
验证完成时返回 `challengeResolved=true`、`challengeKind`、`waitedMs`、`clickedTurnstile` 和 `clearanceCookiePresent`
|
|
328
503
|
(只表示 cookie 名是否存在),页面可见文案显示验证成功、正在等待源站时,响应还会含
|
|
329
504
|
`originResponsePending=true`,表示已过盾但目标页面尚未加载,隐藏的成功文案(例如 `display:none`
|
|
330
|
-
的标题)不算过盾,可见 Turnstile 勾选框仍视为等待中,Challenge 成功和失败响应都含 `mode
|
|
331
|
-
|
|
505
|
+
的标题)不算过盾,可见 Turnstile 勾选框仍视为等待中,Challenge 成功和失败响应都含 `mode`,动作执行前超时返回
|
|
506
|
+
`CHALLENGE_TIMEOUT`
|
|
507
|
+
且 `retryable=true`,并带 `clickedTurnstile` 和实际观察到的
|
|
508
|
+
`challengeKind`(点过 Turnstile 时不会报成 `js`),Access
|
|
332
509
|
denied 返回 `CHALLENGE_DENIED`,交互式验证码、Bot Fight
|
|
333
510
|
Mode 和 IP 声誉检查无法靠等待或点击 checkbox 完成,之后的正常主文档响应才会清掉 header 标记,普通 iframe 文档响应和清空网络日志都不会清掉它
|
|
334
511
|
|
|
335
|
-
### input -
|
|
512
|
+
### input - 键鼠与文件输入
|
|
336
513
|
|
|
337
514
|
事件序列模型,支持任意组合:
|
|
338
515
|
|
|
@@ -345,6 +522,7 @@ Mode 和 IP 声誉检查无法靠等待或点击 checkbox 完成,之后的正
|
|
|
345
522
|
| `wheel` | 滚轮滚动 |
|
|
346
523
|
| `touchstart` / `touchmove` / `touchend` | 触摸事件 |
|
|
347
524
|
| `type` | 输入文本 |
|
|
525
|
+
| `upload` | 在文件控件中选择本地文件,`files:[]` 清空选择 |
|
|
348
526
|
| `wait` | 事件间暂停 |
|
|
349
527
|
| `select` | 按内容选中文本(鼠标模拟) |
|
|
350
528
|
| `replace` | 查找并替换文本 |
|
|
@@ -353,64 +531,208 @@ Mode 和 IP 声誉检查无法靠等待或点击 checkbox 完成,之后的正
|
|
|
353
531
|
| `editorInsert` | 在当前编辑器选区插入文本 |
|
|
354
532
|
| `editorCommand` | 执行 `bold`、`insertOrderedList` 等浏览器编辑命令 |
|
|
355
533
|
|
|
534
|
+
Extension 和 CDP 后台页的默认无修饰键元素左键单击使用经过可操作性检查的合成事件,返回 `warnings` 并说明
|
|
535
|
+
`isTrusted=false`,保持标签页在后台;活动且可渲染的页使用原生 precise 输入,humanize 单击保留鼠标移动,Extension
|
|
536
|
+
后台坐标点击、移动或带修饰键/多击的鼠标动作可显式使用 `manage(action="inputMode",inputMode="stealth")`,鼠标按键清理保持可用
|
|
537
|
+
|
|
356
538
|
`events` 至少需要一个事件,参数:`humanize` 启用贝塞尔曲线移动和随机延迟,`diagnostics=true` 返回动作后新增 console
|
|
357
539
|
warning/error 和失败网络请求, `postCondition`
|
|
358
540
|
会在事件发送后等待页面状态,便于区分输入事件已发送和页面业务状态已完成,`postCondition.timeout` 默认 3000 ms、最大 60000
|
|
359
541
|
ms,`postCondition.interval` 默认 100 ms、范围 50-5000 ms,`postCondition.script` 可传表达式、函数、async
|
|
360
542
|
function 或 Promise 表达式;函数会被调用,最终 Promise 值会被等待后再判定,抛错或 reject 会让检查失败,`targetId`(或旧版
|
|
361
543
|
`tabId`)在两种 backend 中指定页面;`frame`
|
|
362
|
-
|
|
544
|
+
在两种后端中指定子 iframe 或逐层选择器/索引路径,传入任一作用域时,动作、诊断和 post-condition 使用该目标作用域选定的同一个
|
|
545
|
+
backend
|
|
546
|
+
|
|
547
|
+
text、selector 和 URL 检查遇到临时 context 失效时,在 input 与验证的剩余期限内重新读取,持续不可用、原生连接关闭或读取预算耗尽时返回
|
|
548
|
+
`verificationStatus="unavailable"`,script 遇到原生 context 失效时立即返回 unavailable,
|
|
549
|
+
Extension 与 CDP 的原生执行终止及引擎执行超时在后置验证中同样归为 unavailable
|
|
550
|
+
selector 语法错误、页面抛错或 reject 返回
|
|
551
|
+
`error`,异常值转成字符串时再次抛错仍保留页面错误来源,文案中的 frame 或 timeout 不改变分类;已完成输入保留
|
|
552
|
+
`actionStatus="completed"`、`failureStage="verification"` 和顶层 `retryable=false`,`postCondition.retryable`
|
|
553
|
+
表示能否单独重试校验,验证同时受主动作总期限限制,总预算耗尽时不再发起检查
|
|
554
|
+
|
|
555
|
+
取消会中断验证读取和轮询等待,input 在后继排队动作开始前,有界尝试释放本请求新按下的键,保留请求开始前已按住的键,释放失败保留诊断
|
|
556
|
+
|
|
557
|
+
文本校验匹配页面渲染文字和可见的非密码表单值,`actual` 返回包含命中文字的有界片段,Shadow
|
|
558
|
+
host 的自身 shadow 子节点属于可点击范围,合成 click、key 和 input 事件会传到 host 与 document 监听器,mouseenter 和 change 保留各自的局部事件语义
|
|
559
|
+
|
|
560
|
+
坐标目标使用当前 frame 的 viewport 坐标,原生 precise 输入处理 frame 内容边界、缩放、旋转、倾斜及嵌套位置,无法可靠映射时在该事件派发前失败,保留前序已完成事件的进度,
|
|
561
|
+
stealth 事件保持 frame-local 坐标
|
|
562
|
+
|
|
563
|
+
按目标取点沿 assignedSlot 和 Shadow
|
|
564
|
+
host 找到实际滚动盒,可见页面在连续渲染间检查目标矩形与祖先滚动位置,包含页面监听器触发的级联及阻断 scroll 传播的情况,旁边无关容器的循环滚动保留稳定目标的可操作性;等待期间变为隐藏时按当前布局取点,不等待暂停的动画帧;
|
|
565
|
+
恢复可见时重新检查渲染,目标持续移动或祖先持续滚动耗尽本次请求期限时,该事件保持零次输入派发
|
|
363
566
|
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
567
|
+
wheel 省略 target 时沿用当前鼠标位置,Extension 的 helper 安装与输入固定到同一解析所得 documentId,派发前文档被替换或移除时返回 not_started,保持零次输入
|
|
568
|
+
|
|
569
|
+
wheel 和鼠标事件携带当前按住的 Ctrl、Shift、Alt、Meta 字段,包含组合修饰键及使用合成派发的 precise 右键,合成事件保留
|
|
570
|
+
`isTrusted=false`,应用监听器可以读取修饰字段并取消默认滚动
|
|
571
|
+
|
|
572
|
+
Extension 的坐标 wheel 按各轴实际滚动范围处理反向 Flex 和竖排布局,小数增量在同一滚动容器的连续输入间累计,命中后代更新或 wheel 监听器自身滚动仍保留余量,事件之间的独立位置变化重置该容器余量,
|
|
573
|
+
其他容器或文档建立各自序列;原生滚动进度识别 CSS
|
|
574
|
+
zoom 下的分数末端,无法取得进度时输出 console warning 并沿 CSSOM 尺寸范围兼容路径处理,元素滚动距离按有效 CSS
|
|
575
|
+
zoom 换算,普通 transform scale 保持原有滚轮距离语义,viewport 使用自身单位
|
|
576
|
+
|
|
577
|
+
滚动盒资格结合 namespace、实际主盒和文本编辑控件判断,MathML math 布局、flow-root list-item、inline flow-root
|
|
578
|
+
list-item、block ruby,以及 Chrome 支持的 `-webkit-box`/`-webkit-inline-box`
|
|
579
|
+
保留自身滚动与边界行为;文本 input 在 Chrome 将 computed overflow 显示为 clip 时仍可滚动内部文本,block SVG
|
|
580
|
+
viewport 的 hidden/contain 声明不形成 CSS 滚动边界,foreignObject 具备滚动盒时保留自身 auto 滚动及 hidden+contain/none 边界,嵌入的 HTML 保持自身滚动行为;
|
|
581
|
+
真实容器的
|
|
582
|
+
`overscroll-behavior-x/y: contain` 或 `none` 阻止该轴继续传播,包含零范围容器,auto 允许未消费的轴沿原链传播;嵌套
|
|
583
|
+
`overflow:hidden` 保留边界策略且自身不滚动,普通 clip/visible、非原子 inline 和 display:contents 节点不新增该边界
|
|
584
|
+
|
|
585
|
+
viewport 遵循 root/body 的 overflow 传播规则,无主盒的 body(包含 display:contents)不提供 viewport
|
|
586
|
+
overflow;html/body 的显式 containment,以及 content-visibility 或 container-type 施加的 containment,使 body 保留独立滚动行为,
|
|
587
|
+
真正传播 overflow 的 body 不作为独立边界,viewport 的 hidden/clip 轴不滚动;目标自身可滚动时优先处理自身,absolute/fixed 目标之后沿 composed
|
|
588
|
+
tree 中最近的有效定位包含块寻找后续对象,包含 slot 及 foreignObject 嵌入内容;transform、filter、containment、
|
|
589
|
+
3D/motion 条件及适用的 will-change 名称分别遵循各自的盒资格
|
|
590
|
+
|
|
591
|
+
事件可取消并能跨 ShadowRoot 到达 host 和 document 监听器,有效的 `preventDefault()` 停止模拟默认滚动,事件仍返回
|
|
592
|
+
`actionStatus="completed"`
|
|
593
|
+
并计为一次已执行输入;各轴按输入开始时的边界选择滚动路径,监听器改变容器尺寸或位置时保留其效果,默认动作在已选路径上使用改变后的位置;容器失去滚动范围后,未消费的输入按其 overscroll 策略沿原链继续传播;命中元素被移除或迁移时,
|
|
594
|
+
本次 wheel 不转向新插入的祖先或无关 viewport
|
|
595
|
+
|
|
596
|
+
Extension
|
|
597
|
+
wheel 的默认动作使用程序化滚动,吸附遵循程序化终点,原生 wheel 的滚动意图会产生不同终点;mandatory 和 proximity 保留各自吸附行为,原生终点差异属于已接受的兼容性行为
|
|
367
598
|
|
|
368
599
|
键盘 `type` 的 `timeout` 包含 Challenge 等待、焦点准备、字符输入和 `delay`/`humanize` 延迟,Extension
|
|
369
600
|
precise/stealth 与 CDP 使用本次剩余预算,显式预算如 `timeout=45000`
|
|
370
|
-
允许合法输入持续超过默认的
|
|
601
|
+
允许合法输入持续超过默认的 30000 ms,到期后停止后续字符与事件;已派发的输入不能撤回,超时可能留下部分输入,响应为
|
|
371
602
|
`actionExecuted=true`、`actionStatus="unknown"` 和 `retryable=false` 时,应独立读取页面确认实际值,不重放整个事件序列
|
|
372
603
|
|
|
373
604
|
鼠标目标查找、分步移动和 `humanize`
|
|
374
|
-
延迟也共用 input 剩余预算,每次移动和后续点击前检查截止时间,到期后停止后续移动和点击;已派发的原生事件不能撤回,结果为
|
|
605
|
+
延迟也共用 input 剩余预算,每次移动和后续点击前检查截止时间,到期后停止后续移动和点击;已派发的原生事件不能撤回,结果为
|
|
606
|
+
unknown 时独立读取页面,不重放操作
|
|
375
607
|
|
|
376
|
-
命令聚焦、文本选择和替换共用事件剩余预算,到期后停止后续动作;Shift 按下后仍尝试释放,释放失败不隐藏原动作错误,CDP
|
|
608
|
+
命令聚焦、文本选择和替换共用事件剩余预算,到期后停止后续动作;Shift 按下后仍尝试释放,释放失败不隐藏原动作错误,CDP
|
|
609
|
+
分步触摸移动到期后也停止后续触摸点与事件
|
|
377
610
|
|
|
378
611
|
Stealth 左键派发 `click`,中键派发 `auxclick`,右键派发 `contextmenu`,每次按下和释放携带对应的点击
|
|
379
612
|
`detail`;只有左键多击在 `detail=2` 时派发 `dblclick`,独立 stealth `mouseup` 使用相同的按键映射
|
|
380
613
|
|
|
381
614
|
Stealth 的 `delay` 只作用于字符之间,首字符不额外等待;后台页面受定时器节流时,后续间隔会延长,本次预算仍限制后续输入
|
|
382
615
|
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
`
|
|
616
|
+
默认 precise 键盘 `type`
|
|
617
|
+
在 Extension 与 CDP 模式中会为每个换行派发 Enter,CRLF 会规范化;编辑器将 Enter 绑定为提交时,多行输入中的部分文本会触发提交;在 Extension 模式替换多行文本时,使用
|
|
618
|
+
`mode="controlled"`(或 `dispatch=true`)并指定
|
|
619
|
+
`target`,它替换完整 value 或
|
|
620
|
+
contenteditable 文本,派发 input/change,不派发 Enter,表单控件继续使用原生 value setter
|
|
386
621
|
|
|
387
|
-
|
|
622
|
+
键盘输入和 `editorInsert` 使用当前光标与选区,键盘 `type` 指定 `target` 时会先点击并改变插入位置;`editorInsert`
|
|
623
|
+
聚焦目标但不点击,通过浏览器编辑 API 插入文本,不派发 Enter;追加多行文本时,将光标放到末尾,再发送不带 `target` 的
|
|
624
|
+
`editorInsert`,存在非空选区时会替换选区文本,完成后读取实际文本确认编辑器已接受输入
|
|
388
625
|
|
|
389
|
-
|
|
390
|
-
`target`,它会跳过可操作性检查(适用于测试隐藏元素等场景),但仍只分发标准 DOM 鼠标事件序列,不会直接调用框架私有 handler 中键、右键和多击采用同一检查规则,坐标型或省略 target 的点击不能使用 force,可操作性失败返回
|
|
391
|
-
`ACTIONABILITY_FAILED`,包含 `rect`、`clickPoint`、遮挡元素、候选遮挡物和修复建议, **`type`
|
|
392
|
-
专属参数**:`mode="controlled"` 或 `dispatch: true` 直接设置 `.value` 并触发 `input`/`change`
|
|
393
|
-
事件,兼容 React/Vue 等框架的受控组件(键盘事件无法触发状态更新时使用),需要非坐标型
|
|
394
|
-
`target`,仅限 Extension 模式,受控输入和目标查找失败时返回结构化 context,包含
|
|
395
|
-
`locator`、`matchCount`、`nth`、有数量上限的 `candidates` 和不含输入值的 `activeElement`
|
|
396
|
-
摘要,焦点不可取得时返回 null,DOM 查询失败时还返回 `diagnosticError` 选区相关错误另含编辑器与选区状态,password
|
|
397
|
-
input 的 value 不进入失败诊断,失败响应也会脱敏 input 事件传入的 `find` 和替换 `text`,`select` 和 `replace` 的事件级
|
|
398
|
-
`nth` 表示文本第 N 次出现,嵌套的 `target.nth` 表示第 N 个目标元素,两者都从 0 开始并可同时使用,CDP 模式的 locator
|
|
399
|
-
target 不依赖 Extension refId
|
|
626
|
+
后台 CDP 点击和键盘输入保持页面在后台,检查元素是否可见、可用且位置和尺寸稳定,必要时滚动到视口;点击还会检查遮挡;目标查找、可操作性检查和最终坐标读取共用事件剩余预算,任一阶段耗尽预算后停止派发鼠标或键盘事件
|
|
400
627
|
|
|
401
|
-
|
|
402
|
-
`
|
|
403
|
-
|
|
628
|
+
Extension precise 的键盘模式 `type` 和显式 `keydown`/`keyup` 使用原生按键,焦点准备与事件共用请求剩余预算;需要焦点模拟时,响应的
|
|
629
|
+
`warnings` 提示文档在输入期间临时报告 `visible`,实际标签页和窗口焦点保持原状,操作结束后恢复原设置,再执行
|
|
630
|
+
`postCondition`
|
|
631
|
+
|
|
632
|
+
复用调试会话的原模拟状态未知且页面在后台时,返回 `KEYBOARD_FOCUS_STATE_UNKNOWN` 和
|
|
633
|
+
`not_started`,保持原设置,可显式使用 stealth 或独立 CDP;恢复失败返回 `keyboardFocusCleanup`,已完成的事件仍保留
|
|
634
|
+
`completed`,派发回执未知时保留 `unknown`,请求失败、取消或到期会尝试释放本请求新增的按键,正常完成时保留有意按住的键
|
|
404
635
|
|
|
405
636
|
**`keydown` 专属参数**:
|
|
406
637
|
|
|
407
638
|
- `commands`:触发浏览器原生编辑命令(如 `["selectAll"]`、`["copy"]`、`["paste"]`、`["cut"]`、`["undo"]`、`["redo"]`
|
|
408
639
|
),成功表示浏览器已接受命令分发,页面结果需用 `postCondition` 或 `extract`
|
|
409
|
-
验证,仅 precise 模式可用,stealth 模式下抛错(CDP commands API 没有 JS
|
|
640
|
+
验证,仅 precise 模式可用,stealth 模式下抛错(CDP commands API 没有 JS 事件等价物);命令分发前只聚焦元素或坐标
|
|
410
641
|
`target`,不派发鼠标事件,坐标聚焦不会改变 checkbox、跟随链接或调用 click 监听器;目标缺失或无法聚焦时,在分发命令前返回错误,Extension 的
|
|
411
642
|
`frame` 坐标相对于所选 iframe
|
|
412
643
|
- 连续 `keydown` 同一 key 自动切换为 `rawKeyDown` + `autoRepeat`,模拟长按重复(与 Puppeteer 一致)
|
|
413
644
|
|
|
645
|
+
**`click` 专属参数**:`force:true` 必须提供 `forceReason` 与非坐标型元素
|
|
646
|
+
`target`,跳过可操作性检查后派发标准 DOM 鼠标事件;中键、右键和多击采用同一规则,坐标型或省略 target 时拒绝 force;失败返回
|
|
647
|
+
`ACTIONABILITY_FAILED`,包含 `rect`、`clickPoint`、遮挡元素、候选遮挡物与处理建议
|
|
648
|
+
|
|
649
|
+
**`type` 专属参数**:`mode="controlled"` 或 `dispatch:true` 替换完整 value 或 contenteditable 文本,派发
|
|
650
|
+
`input`/`change`,不派发 Enter;需要非坐标型 `target`,仅限 Extension;目标须为 HTML `input`、`textarea`、`select`
|
|
651
|
+
或 contenteditable,有效禁用、readonly、普通容器与 file input 在聚焦和输入事件前明确拒绝;disabled
|
|
652
|
+
fieldset 按 HTML 规则处理,保留首个 legend 的例外,文件控件使用 `upload`;普通控件、customized
|
|
653
|
+
built-in 及从同源文档 adopt 的控件按实际表单接口使用原生 value setter,setter 不可用时在聚焦前返回明确错误
|
|
654
|
+
|
|
655
|
+
受控输入与目标查找失败时返回 `locator`、`matchCount`、`nth`、有数量上限的 `candidates` 和不含输入值的 `activeElement`
|
|
656
|
+
摘要;焦点不可取得时为 `null`,DOM 查询失败时另含 `diagnosticError`
|
|
657
|
+
|
|
658
|
+
Extension
|
|
659
|
+
precise 输入在字符或 Enter 按键收到回执后取消或到期,保留已执行进度并使旧页面 revision 失效;首次派发前取消仍保留未执行状态,再次操作前读取当前值与 revision
|
|
660
|
+
|
|
661
|
+
标签输入框通过 Enter 创建标签时,输入文字后显式发送 Enter,再检查标签是否生成,以下 `input` 示例中,输入框为
|
|
662
|
+
`#tag-entry`,标签列表为 `#tags`,使用时替换为页面的实际选择器:
|
|
663
|
+
|
|
664
|
+
```json
|
|
665
|
+
{
|
|
666
|
+
"events": [
|
|
667
|
+
{ "type": "type", "target": { "css": "#tag-entry" }, "text": "12345" },
|
|
668
|
+
{ "type": "keydown", "key": "Enter" },
|
|
669
|
+
{ "type": "keyup", "key": "Enter" }
|
|
670
|
+
],
|
|
671
|
+
"postCondition": { "selector": "#tags [data-value=\"12345\"]" }
|
|
672
|
+
}
|
|
673
|
+
```
|
|
674
|
+
|
|
675
|
+
#### 文本选区与敏感输入
|
|
676
|
+
|
|
677
|
+
`replace` 对 `textarea` 与 `text`、`search`、`tel`、`url`、`password`
|
|
678
|
+
类型的 input 使用文本选区,其他 input 类型通过原生完整 value 更新,并返回请求值与浏览器规范化后的实际值;不支持选区的类型单独执行
|
|
679
|
+
`select` 时返回 `UNSUPPORTED_SELECTION`,CDP locator target 通过 CDP 聚焦
|
|
680
|
+
|
|
681
|
+
事件级 `nth` 选择文本第 N 次出现,嵌套 `target.nth`
|
|
682
|
+
选择第 N 个目标元素,两者从 0 开始,可同时使用,选区错误另含编辑器与选区状态
|
|
683
|
+
|
|
684
|
+
坐标 `select`/`replace`
|
|
685
|
+
使用该点实际命中的控件或文本范围,已有焦点不改变命中归属;替换写入前重新核对已选元素和选区归属,目标被移除、焦点转向其他控件或选区离开目标时停止写入;完整值路径的目标变化返回
|
|
686
|
+
`TARGET_FOCUS_FAILED`,文本选区变化返回 `TEXT_SELECTION_CHANGED`
|
|
687
|
+
只读、disabled 与不支持选区的控件继续按各自规则拒绝,其他控件中的同名文本和选区保持不变
|
|
688
|
+
|
|
689
|
+
password value 不进入失败 context 或 text post-condition 观测,失败响应及 `error.logs` 定位日志中的 `find` 与替换 `text`
|
|
690
|
+
采用同一脱敏规则;password `select`/`replace` 的成功与失败响应均隐藏 console 和 network 诊断正文,返回
|
|
691
|
+
`diagnostics.redacted=true`、`reason="sensitive_input_or_unresolved_target"`;无法安全确认选择目标时采用同一保护;普通输入保留诊断,
|
|
692
|
+
密码保护在当前 input 请求结束时清除
|
|
693
|
+
|
|
694
|
+
#### 上传本地文件
|
|
695
|
+
|
|
696
|
+
网页浏览、页面交互和文件上传优先使用 mcp-chrome,上传沿用当前页面与 Extension/CDP 连接
|
|
697
|
+
Chrome
|
|
698
|
+
DevTools 用于浏览器或扩展诊断,以及 mcp-chrome 未覆盖的明确任务
|
|
699
|
+
|
|
700
|
+
通过 `input` 的 `upload` 事件,从原路径选择文件,包括 Downloads 中的文件:
|
|
701
|
+
|
|
702
|
+
```json
|
|
703
|
+
{
|
|
704
|
+
"events": [
|
|
705
|
+
{
|
|
706
|
+
"type": "upload",
|
|
707
|
+
"target": { "css": "input[type=file]" },
|
|
708
|
+
"files": ["./review.zip"]
|
|
709
|
+
}
|
|
710
|
+
]
|
|
711
|
+
}
|
|
712
|
+
```
|
|
713
|
+
|
|
714
|
+
`files` 必填,路径指向 MCP Server 所在机器上可读的普通文件;相对路径按 Server 工作目录解析,支持绝对路径和 `~/`
|
|
715
|
+
路径;Server 传输文件字节,浏览器可位于另一台机器;本次选择的文件总大小须低于 50
|
|
716
|
+
MiB,达到或超过预算时,在修改文件控件前返回错误
|
|
717
|
+
|
|
718
|
+
带 `multiple` 属性的控件可传多个路径,`files:[]` 清空选择:
|
|
719
|
+
|
|
720
|
+
```json
|
|
721
|
+
{"events":[{"type":"upload","target":{"css":"#attachments"},"files":[]}]}
|
|
722
|
+
```
|
|
723
|
+
|
|
724
|
+
目标须为 `input[type=file]`,隐藏的文件控件也可使用,无需点击或打开系统文件选择框;现有元素定位器和 `target.nth`
|
|
725
|
+
选择控件,两种后端的 `frame`
|
|
726
|
+
均可选择子 iframe 或嵌套路径;上传复用当前 Extension 或 CDP 连接和所选 inputMode,默认 precise 模式支持严格 CSP 页面,stealth 遵守页面 CSP 限制;
|
|
727
|
+
Extension 上传需要受控页权限,在读取本地文件前完成检查
|
|
728
|
+
|
|
729
|
+
结果返回赋值时的文件名、大小、MIME 和事件摘要,控件依次收到合成的 `input`、`change` 事件;要求 trusted
|
|
730
|
+
event 的站点需按实际行为验证;页面在 `change` handler 中自动清空控件时,结果仍描述 handler 执行前的文件赋值
|
|
731
|
+
|
|
732
|
+
使用 `postCondition`
|
|
733
|
+
等待站点的附件就绪或上传完成状态,站点要求提交时另行执行提交;postCondition 失败时保留输入动作已完成的状态;文件读取、传输和赋值共用 input 超时与取消,赋值前失败时保留原选择;赋值结果未收到确认时返回
|
|
734
|
+
`actionStatus="unknown"`、`retryable=false`,独立读取页面后再决定下一步
|
|
735
|
+
|
|
414
736
|
### extract - 内容提取
|
|
415
737
|
|
|
416
738
|
| Type | 描述 |
|
|
@@ -427,35 +749,92 @@ CDP 查找失败保留 `ELEMENT_NOT_FOUND`,元素等待保留 `TIMEOUT`,原
|
|
|
427
749
|
源码或隐藏后代文本;显式选择不可渲染的 HTML 元素时遵循浏览器 `innerText` 规则,SVG/XML 节点使用
|
|
428
750
|
`textContent`,源码请使用 `html`
|
|
429
751
|
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
`
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
`
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
`
|
|
449
|
-
|
|
752
|
+
#### 文本窗口
|
|
753
|
+
|
|
754
|
+
`extract(type="text", maxChars=12000, offset=0)` 返回指定的 UTF-16 文本窗口,包含 `totalLength`、`nextOffset` 和
|
|
755
|
+
`truncated`,使用 `nextOffset` 继续读取
|
|
756
|
+
每次请求读取当前页面,页面文本变化会改变后续偏移,指定 `output`
|
|
757
|
+
时文件保存本次窗口,省略两个参数时保留完整文本响应与完整文件行为
|
|
758
|
+
|
|
759
|
+
#### HTML 与图片
|
|
760
|
+
|
|
761
|
+
`output` 将结果保存到文件,`images=data` 时使用目录;`images=info|data` 随 HTML 返回图片元信息或字节
|
|
762
|
+
图片数据单图限制 2
|
|
763
|
+
MiB,单次请求累计限制 8 MiB,目录导出逐张读取与写入,索引的 `omitted`
|
|
764
|
+
记录不可用或超额原因
|
|
765
|
+
内联输出保留前 20 张图片,采用相同的省略原因与字节预算,`frameHtml` 在 `frame`
|
|
766
|
+
路由后读取当前文档,HTML 与图片的最终选取使用完整语义定位、exact 和 nth 条件
|
|
767
|
+
|
|
768
|
+
#### 截图
|
|
769
|
+
|
|
770
|
+
`clip` 指定坐标区域,`compareWith` 指定 PNG 基准,`diffOutput` 指定 PNG 差异图;`diffOutput` 必须同时提供 `compareWith`
|
|
771
|
+
目标未匹配、`nth` 越界或尺寸为零时返回目标错误,响应包含
|
|
772
|
+
`metadata.format`、`width`、`height`、`dimensionSource`、`byteSize`、`fullPage`、`scale`、`clip` 与 `capabilities`
|
|
773
|
+
|
|
774
|
+
截图限制为单边 16,384 像素、总计 12,000,000 像素、预计 RGBA 内存 48 MiB 与编码数据 25 MiB,超限返回
|
|
775
|
+
`SCREENSHOT_BUDGET_EXCEEDED` 及对应上限;基准 PNG 在读取前检查文件大小,对比限制单个 PNG 为 25
|
|
776
|
+
MiB 与 12,000,000 像素;解压输出与 scanline 长度须匹配已校验尺寸,损坏或异常膨胀的 PNG 返回错误,较大截图使用 `clip` 或
|
|
777
|
+
`scale` 缩小
|
|
778
|
+
|
|
779
|
+
两种后端的截图和 diagnosticBundle 均报告 `hiddenTabScreenshot=false`,Extension 隐藏页返回
|
|
780
|
+
`HIDDEN_TAB_SCREENSHOT`,整页截图保留当前视口与设备模拟
|
|
781
|
+
其他 debugger 占用 precise 路径时,可视区域 fallback 在内联与文件输出中报告
|
|
782
|
+
`metadata.degraded`、`metadata.fallback` 和 `metadata.limitations`
|
|
783
|
+
窗口级捕获期间活动 tab 变化时丢弃图像,包括 A→B→A;不支持的 fallback 参数返回 `SCREENSHOT_FALLBACK_UNSUPPORTED`
|
|
784
|
+
|
|
785
|
+
元素截图按实际定位包含块计算 overflow 祖先的已绘制交集,包含直接 absolute 目标及 absolute/fixed 祖先中的普通流后代,保持滚动位置与视口大小;发生裁剪时返回
|
|
786
|
+
`clippedToVisibleArea=true`,完全不可见时返回 `ELEMENT_NOT_VISIBLE`,无法准确映射的 overflow 变换返回
|
|
787
|
+
`FRAME_GEOMETRY_UNAVAILABLE`
|
|
788
|
+
|
|
789
|
+
Extension 的自动 iframe 元素裁剪要求可用的仅平移偏移,iframe 或其 composed 祖先的 Motion Path 旋转返回
|
|
790
|
+
`FRAME_GEOMETRY_UNAVAILABLE`,显式零旋转的 Motion Path 保留平移映射
|
|
791
|
+
CDP 通过原生 frame 几何映射目标四角,几何不可用或存在非仿射变换时返回 `FRAME_GEOMETRY_UNAVAILABLE`
|
|
792
|
+
两种后端均将根视口矩形加上根页面滚动量,得到页面坐标的截图区域;操作后恢复原 frame,Extension 同时恢复 documentId,显式
|
|
793
|
+
`clip` 使用根页面坐标
|
|
794
|
+
|
|
795
|
+
#### 状态与元信息
|
|
796
|
+
|
|
797
|
+
`state` 返回 `interactiveElements`,两种后端的 metadata 均返回 `frames` 与实际文档 `url`,Extension `frame`
|
|
798
|
+
路由返回所选文档地址
|
|
799
|
+
CDP 无法取得的已声明帧字段保留为 `null`,包括 DOM selector 与所属元素 rect,帧树顺序和 ID 保持不变
|
|
800
|
+
|
|
801
|
+
元信息包含当前 `managed` 状态与 `createdBy`、`createdAt`、`lastUsedAt`、`taskHint`、`note`,与
|
|
802
|
+
`browse list`、`manage pageMetadata` 一致,内联与文件输出使用相同字段
|
|
803
|
+
`frame`
|
|
804
|
+
选择 iframe 文档时,备注仍属于页面;Extension 的创建来源、备注与可信分组关系跨 Server 和 Extension 重载保存,恢复时核对实际身份,另一 Extension Server 读取相同的已保存元数据
|
|
805
|
+
CDP 备注属于当前 Server 进程,新 CDP Server 的来源为未知,任务备注为空
|
|
806
|
+
未知来源保留
|
|
807
|
+
`unknown`,备注不授予访问权限或跨会话所有权;CDP 返回 `managed=false`,保留连接内的正常操作
|
|
808
|
+
|
|
809
|
+
两种后端均通过 `targetId` 或旧版 `tabId` 选择页面,通过 `frame` 选择子文档或嵌套路径
|
|
450
810
|
|
|
451
811
|
**`attribute` 特殊前缀**:`computed:<属性名>` 返回 computed CSS 样式值(如 `computed:color`、`computed:font-size`),
|
|
452
812
|
`computed:*` 返回全部计算样式(300+ 属性,建议配合 `output` 写文件)
|
|
453
813
|
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
814
|
+
`extract.timeout`
|
|
815
|
+
是浏览器操作总预算,单位毫秒,默认 30000,包含排队、页面/frame 准备、目标等待、内容读取和页面上下文元信息读取
|
|
816
|
+
每个 RPC 使用剩余预算,`state`
|
|
817
|
+
不另外开始 30 秒等待;已派发但未确认的请求保留 unknown,不自动重放
|
|
818
|
+
|
|
819
|
+
**`state` 专属参数**:`depth` 控制无障碍树遍历深度,默认 15,减小后可限制大页面的返回量
|
|
820
|
+
`mode` 选择
|
|
821
|
+
`accessibility`(默认,无障碍树)或 `domsnapshot`(原始
|
|
822
|
+
`DOMSnapshot.captureSnapshot`,支持 CDP 或受控 Extension 页面)
|
|
823
|
+
DOMSnapshot 返回整页快照,传入 `target`、`frame` 或
|
|
824
|
+
`depth`
|
|
825
|
+
限定时明确拒绝
|
|
826
|
+
普通只读授权允许 accessibility 状态读取,Extension 的 DOMSnapshot 需要完整受控权限以使用 debugger
|
|
827
|
+
无关 iframe 探测失败时,metadata 通过
|
|
828
|
+
`unavailableFrames` 与对应帧的 `unavailableReason` 标明原因,能够唯一验证的所选 iframe 继续可用
|
|
829
|
+
|
|
830
|
+
两种后端的 accessibility state 均通过 `target` 限定所选元素及其后代,`depth` 从该子树根部计算,CDP 后台文档的 role/name
|
|
831
|
+
定位读取所选 frame 的浏览器可访问性快照,保留子串、名称精确匹配与 `nth`,保持标签页在后台
|
|
832
|
+
|
|
833
|
+
accessibility state 生成元素名称与正文时不读取 hidden/password/file input 的 value getter,默认
|
|
834
|
+
`all`、指定子树和文件输出采用同一规则
|
|
835
|
+
隐藏控件保留名称与
|
|
836
|
+
`visible=false`;标签、placeholder 和 title 提供名称,普通 input 在 `value` 与 `pageContent`
|
|
837
|
+
中单独保留当前值,有名称时也保留,submit 标签保留完整文本,显式脚本、HTML 与属性读取保持原有行为
|
|
459
838
|
|
|
460
839
|
### wait - 等待条件
|
|
461
840
|
|
|
@@ -466,15 +845,18 @@ selector 和所属元素 rect,帧树顺序与 ID 保持不变;元信息还
|
|
|
466
845
|
| `time` | 固定延迟 |
|
|
467
846
|
| `idle` | 等待 DOM 或网络静默期 |
|
|
468
847
|
|
|
469
|
-
参数:`targetId`(或旧版 `tabId`)在两种 backend 中指定页面,`frame`
|
|
848
|
+
参数:`targetId`(或旧版 `tabId`)在两种 backend 中指定页面,`frame` 在两种后端中指定子 iframe 或嵌套路径
|
|
470
849
|
|
|
471
850
|
CDP 模式的 `visible` 要求 DOM 矩形宽高非零,且 CSS 不隐藏元素(`display:none` 或 `visibility:hidden/collapse`) `hidden`
|
|
472
851
|
接受这些隐藏状态或元素不存在,`attached` 和 `detached` 只检查元素是否存在
|
|
473
852
|
|
|
474
853
|
**`idle` 说明**:Extension 模式会在 `readyState === 'complete'` 后注入 `MutationObserver`,等待 `ms`
|
|
475
|
-
毫秒内无 DOM 变更;CDP 模式等待网络静默,两种模式的默认 `ms` 都是
|
|
854
|
+
毫秒内无 DOM 变更;CDP 模式等待网络静默,两种模式的默认 `ms` 都是 500 ms,响应返回 `idleKind` 和
|
|
476
855
|
`idlePeriodMs`,Extension 响应还返回 `domStable`
|
|
477
856
|
|
|
857
|
+
CDP idle 包含调用前已在途的页面请求,独立 idle 与同文档 `networkidle` 排除空 `loaderId`
|
|
858
|
+
的 Worker 请求,这类请求的终态事件可在页面 session 中缺失;页面 Fetch 与 Script 请求仍等待完成
|
|
859
|
+
|
|
478
860
|
### evaluate - JavaScript 执行
|
|
479
861
|
|
|
480
862
|
在页面上下文执行 JavaScript
|
|
@@ -488,7 +870,7 @@ CDP 模式的 `visible` 要求 DOM 矩形宽高非零,且 CSS 不隐藏元素
|
|
|
488
870
|
| `staleContextRetry` | iframe stale context 策略,`never`(默认)或 `readOnly` |
|
|
489
871
|
| `output` | 将结果保存到文件 |
|
|
490
872
|
| `targetId` / `tabId` | 在两种 backend 中指定页面(`tabId` 为兼容别名) |
|
|
491
|
-
| `frame` |
|
|
873
|
+
| `frame` | 指定子 iframe 或逐层选择器/索引路径,两种后端均支持 |
|
|
492
874
|
| `timeout` | 端到端超时预算(毫秒) |
|
|
493
875
|
| `diagnostics` | 执行后返回新增 console warning/error 和失败网络请求摘要 |
|
|
494
876
|
| `postCondition` | 执行后等待文本、selector、URL 片段或脚本结果匹配 |
|
|
@@ -502,16 +884,49 @@ CDP 模式的 `visible` 要求 DOM 矩形宽高非零,且 CSS 不隐藏元素
|
|
|
502
884
|
等简单字段,结果展开或序列化失败时返回 `actionExecuted=true`、`actionStatus="completed"` 和
|
|
503
885
|
`failureStage="output"`,因为页面脚本已经完成,evaluate 即使在全局 `inputMode=stealth` 时也默认使用 `precise`,其
|
|
504
886
|
`postCondition` 检查与主动作使用相同 evaluate mode,`postCondition` 不传时, `success=true`
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
`
|
|
508
|
-
|
|
509
|
-
|
|
887
|
+
只表示脚本完成执行并返回;传入后,`verificationStatus`
|
|
888
|
+
区分 matched、not_matched、unavailable 和 error,并返回最后一次检查结果,已完成脚本保留 `actionStatus="completed"`
|
|
889
|
+
和顶层 `retryable=false`,`postCondition.retryable` 仅适用于独立验证读取
|
|
890
|
+
iframe precise 执行默认不在 execution
|
|
891
|
+
context 失效后重放脚本,只有脚本无副作用时才应传
|
|
892
|
+
`staleContextRetry="readOnly"`,Extension 会在剩余 timeout 内重新解析 context,并最多重放一次,重试解析期间 Chrome 仍返回已移除的
|
|
893
|
+
document 时,
|
|
894
|
+
会在同一预算内等待当前 document,不增加脚本执行次数;权限拒绝立即结束
|
|
895
|
+
CDP
|
|
896
|
+
iframe 支持 `never`,请求 `readOnly` 时在脚本派发前返回 `DRIVER_CAPABILITY_ERROR`、`actionExecuted=false` 和
|
|
897
|
+
`actionStatus="not_started"`
|
|
898
|
+
两种 backend 的 `Runtime.evaluate` 发出后发生 stale context 时均返回
|
|
899
|
+
`actionExecuted=true`、`actionStatus="unknown"`
|
|
900
|
+
和
|
|
901
|
+
`retryable=false`,因为脚本可能已经产生部分副作用,但无法取得最终结果,CDP 保留原生 `CDP_ERROR`
|
|
902
|
+
|
|
903
|
+
evaluate 的总 timeout 同时限制后置验证,总期限已到时保持主动作 completed,并返回验证 unavailable
|
|
904
|
+
排队中超时且脚本未派发时,公开结果保留
|
|
905
|
+
`actionExecuted=false` 与 queue 阶段;已经派发且回执不明的脚本保持 unknown,按结果单独读取页面
|
|
510
906
|
|
|
511
907
|
Extension precise 主 frame 的对象结果,显式指定 `output` 时字符预算为 16
|
|
512
|
-
Mi(16777216),未指定时保留 1000000
|
|
513
|
-
|
|
514
|
-
|
|
908
|
+
Mi(16777216),未指定时保留 1000000,自动保存使用同一上限
|
|
909
|
+
显式输出支持深度 64、节点 100000,内联保留深度 8、节点 2000,两条路径均拒绝不可序列化结果
|
|
910
|
+
字符预算按 UTF-16
|
|
911
|
+
code units 计算,输出文件字节数按 UTF-8 计算
|
|
912
|
+
`tmp:`
|
|
913
|
+
文件另受临时输出配额约束,超限返回当前上限,并保留脚本已完成、输出失败的状态
|
|
914
|
+
|
|
915
|
+
内置后置验证在 CDP 使用 never、Extension 使用 readOnly,上下文失效后的轮询独立于已完成动作
|
|
916
|
+
|
|
917
|
+
绝对 `scriptFile` 与 `output`
|
|
918
|
+
路径须位于 Server 当前工作目录或本次 Server 会话的受控临时目录内,系统临时目录的其他位置与 Downloads 不自动列入允许根
|
|
919
|
+
`PATH_NOT_ALLOWED` 的 `error.context.allowedRoots` 给出实际范围,使用其中的 `cwd:` 或 `tmp:` 路径
|
|
920
|
+
|
|
921
|
+
响应包含 stale-context 策略、`retryAttempted`、限量的 `retryReason` 与最终 `frameContext`,其中记录 Extension
|
|
922
|
+
frame、parent frame、URL、CDP frame 与 execution context ID
|
|
923
|
+
同 URL frame 仅在所选 DOM
|
|
924
|
+
iframe 无法唯一确认目标时拒绝执行;Extension 重载后可继续访问原 iframe,探测上下文失效时输出 warning 并停止监听
|
|
925
|
+
|
|
926
|
+
已可用 iframe 的选择不等待兄弟 frame 加载完成,后台页面定时器限频不延长 frame 探测等待,脚本派发前取消或超时会释放探测资源,保持该脚本未执行
|
|
927
|
+
|
|
928
|
+
可信 Function 编译策略拒绝返回 `CSP_BLOCKED`,脚本未执行;页面 `throw` 或 Promise
|
|
929
|
+
rejection 保留原错误与已执行状态,错误文案中的 `CSP`、`Content Security Policy` 或 `unsafe-eval` 不改变来源
|
|
515
930
|
|
|
516
931
|
### manage - 页面与环境管理
|
|
517
932
|
|
|
@@ -519,7 +934,7 @@ code units 计,不等于输出文件的 UTF-8 字节数;`tmp:`
|
|
|
519
934
|
| ------------------ | ------------------------------------------------ |
|
|
520
935
|
| `newPage` | 新建受控页面/Tab |
|
|
521
936
|
| `pageMetadata` | 读取或设置页面的 `taskHint`、`note` |
|
|
522
|
-
| `closePage` |
|
|
937
|
+
| `closePage` | 两种模式关闭页面并返回 `affected.before/after` |
|
|
523
938
|
| `adoptPage` | 授予已有 Tab 完整受控能力,不改变前台 |
|
|
524
939
|
| `releasePage` | 将受控页移出管理,不关闭页面 |
|
|
525
940
|
| `grantReadAccess` | 为当前调用实例授予显式页面的普通只读权限 |
|
|
@@ -546,55 +961,115 @@ code units 计,不等于输出文件的 UTF-8 字节数;`tmp:`
|
|
|
546
961
|
| `inputMode` | 查询或设置输入模式(`precise` / `stealth`) |
|
|
547
962
|
| `stealth` | 注入反检测脚本 |
|
|
548
963
|
| `cdp` | 发送原始 CDP 命令(高级,如 `Runtime.evaluate`) |
|
|
549
|
-
|
|
550
|
-
|
|
964
|
+
| `dialog` | 观察或处理对话框 |
|
|
965
|
+
| `networkCapture` | 启停原请求、正文和流消息采集 |
|
|
966
|
+
| `route` | 匹配并处理暂停请求 |
|
|
967
|
+
| `httpAuth` | 设置或清除限定范围的 HTTP 挑战凭证 |
|
|
968
|
+
| `download` | 观察、等待和保存原下载文件 |
|
|
969
|
+
|
|
970
|
+
原生 tab/window/group 配置使用 Extension 模式,`activatePage` 同时支持 CDP
|
|
971
|
+
操作已有对象时,用
|
|
551
972
|
`targetId`、`targetIds`、`windowId` 或 `groupId` 明确指定目标,返回 `affected.before/after`,分组结果还返回
|
|
552
|
-
`tabsBefore/tabsAfter
|
|
553
|
-
由 Chrome
|
|
554
|
-
|
|
555
|
-
|
|
556
|
-
|
|
557
|
-
|
|
558
|
-
|
|
559
|
-
|
|
560
|
-
|
|
561
|
-
|
|
562
|
-
|
|
563
|
-
`
|
|
973
|
+
`tabsBefore/tabsAfter`
|
|
974
|
+
`ungroupPages` 由 Chrome 删除空组,成员的受控权限保持不变
|
|
975
|
+
|
|
976
|
+
窗口显示操作和分组名称、颜色、折叠更新按显式 `windowId` 或 `groupId`
|
|
977
|
+
执行,允许包含非托管成员,成员页面权限保持不变
|
|
978
|
+
整组移动和关闭整窗要求全部受影响成员受控,加入或解除指定页面分组只检查指定页面,无关成员变化不阻止有效选择
|
|
979
|
+
默认在现有普通窗口后台创建页面,窗口包含非托管 tab 时也沿用该路径
|
|
980
|
+
|
|
981
|
+
Extension 的 `clearCache` 返回 `UNSUPPORTED_MODE`,保留全部内容
|
|
982
|
+
清 Cookie 使用带 `url` 或 `domain` 过滤的
|
|
983
|
+
`cookies(action="clear")`,清 storage 或 cache 使用 CDP 模式
|
|
984
|
+
`focusWindow` 在观测到目标窗口已聚焦后返回成功,否则返回
|
|
985
|
+
`WINDOW_FOCUS_NOT_OBSERVED`
|
|
986
|
+
`closeWindow` 遇到混有非托管 tab 的窗口时返回 `WINDOW_HAS_UNMANAGED_TABS`
|
|
987
|
+
|
|
988
|
+
持久的 `adoptPage`、`releasePage`
|
|
989
|
+
目标变更与指定 tab 的操作串行执行,并发多事件 input 始终留在指定 tab,持久目标变更在该操作结束后生效
|
|
990
|
+
CDP 的
|
|
991
|
+
`activatePage` 保留默认操作目标,返回该 backend 能读取的字段,`active` 和系统窗口焦点状态保持不可用
|
|
992
|
+
|
|
993
|
+
Extension 的 `viewport`、`userAgent`、`emulate`、原始 `cdp` 和 precise `evaluate` 支持受控 `about:blank`
|
|
994
|
+
页面,Chrome 内部页和 Extension 页继续受原生访问限制
|
|
995
|
+
不带 `device` 的 `manage(action="emulate")`
|
|
564
996
|
直接查询本地设备目录,无需有效页面,携带页面条件时明确拒绝;实际设置设备继续校验目标页面和条件
|
|
565
997
|
|
|
566
|
-
|
|
567
|
-
|
|
568
|
-
|
|
569
|
-
|
|
570
|
-
|
|
571
|
-
|
|
572
|
-
|
|
573
|
-
|
|
574
|
-
|
|
575
|
-
|
|
998
|
+
#### `newPage`
|
|
999
|
+
|
|
1000
|
+
参数:`url`、 `windowId`、 `index`、 `active`、 `pinned`、 `openerTabId`、 `groupId`、 `timeout`、 `taskHint`、 `note`
|
|
1001
|
+
|
|
1002
|
+
`active` 默认 false,`groupId=-1` 不分组,显式位置不受默认显示分组改变
|
|
1003
|
+
|
|
1004
|
+
#### `updatePage`
|
|
1005
|
+
|
|
1006
|
+
参数:`url`、 `active`、 `pinned`、 `highlighted`、 `muted`、 `autoDiscardable`、 `openerTabId`
|
|
1007
|
+
|
|
1008
|
+
必须传 `targetId`,只支持 `active=true` 且不聚焦窗口,`active=false` 在任何更新前拒绝
|
|
1009
|
+
|
|
1010
|
+
#### `groupPages`
|
|
1011
|
+
|
|
1012
|
+
参数:`targetIds`、 `groupId`、 `windowId`、 `title`、 `color`、 `collapsed`
|
|
1013
|
+
|
|
1014
|
+
省略 `groupId` 时在成员原窗口创建分组,跨窗口成员须指定 `windowId`,加入已有组仅传 `targetIds/groupId`
|
|
1015
|
+
|
|
1016
|
+
#### `ungroupPages`
|
|
1017
|
+
|
|
1018
|
+
参数:`targetIds`
|
|
1019
|
+
|
|
1020
|
+
解除分组,保留受控能力
|
|
1021
|
+
|
|
1022
|
+
#### `updateGroup`
|
|
1023
|
+
|
|
1024
|
+
参数:`groupId`、 `title`、 `color`、 `collapsed`
|
|
1025
|
+
|
|
1026
|
+
空名称及 false 折叠值按原值设置
|
|
1027
|
+
|
|
1028
|
+
#### `moveGroup`
|
|
1029
|
+
|
|
1030
|
+
参数:`groupId`、 `windowId`、 `index`
|
|
1031
|
+
|
|
1032
|
+
移动全部成员,`index=-1` 表示窗口末尾
|
|
1033
|
+
|
|
1034
|
+
#### `newWindow`
|
|
1035
|
+
|
|
1036
|
+
参数:`url` 或 `urls`、 `targetId`、 `windowType`、 `focused`、 `incognito`、 `left`、 `top`、 `width`、 `height`、
|
|
1037
|
+
`windowState`、 `setSelfAsOpener`
|
|
1038
|
+
|
|
1039
|
+
normal 支持多 URL 及同时移入已有受控页,popup 只接受一个页面,所有新建页受控且分别记录创建来源
|
|
1040
|
+
|
|
1041
|
+
#### `updateWindow` / `resizeWindow`
|
|
1042
|
+
|
|
1043
|
+
参数:`windowId`、 `left`、 `top`、 `width`、 `height`、 `windowState`、 `focused`、 `drawAttention`
|
|
1044
|
+
|
|
1045
|
+
应用 Chrome 支持的窗口配置并返回观测状态
|
|
576
1046
|
|
|
577
1047
|
`updateWindow` 与 `resizeWindow` 修改状态或几何后等待浏览器观测稳定,非 normal 窗口同时请求 `windowState="normal"`
|
|
578
|
-
和 bounds 时,状态转换完成后才应用一次几何参数,OS
|
|
579
|
-
|
|
1048
|
+
和 bounds 时,状态转换完成后才应用一次几何参数,OS 调整后的几何按实际值返回;有界等待内仍未观测到稳定状态时,
|
|
1049
|
+
`WINDOW_UPDATE_NOT_OBSERVED`
|
|
1050
|
+
返回部分执行状态及最后观测的窗口信息,再次更新前用 `browse list`
|
|
1051
|
+
检查实际状态;Chrome 因窗口超出可见屏幕范围而拒绝 bounds 时,使用当前屏幕可用区域内的坐标和尺寸;响应保留原始几何错误,不附带页面激活提示
|
|
580
1052
|
|
|
581
1053
|
`browse list` 默认 `details="summary"`,返回页面标识、URL/标题、位置、managed/revision 和元数据;传 `details="full"`
|
|
582
|
-
获取选中、静音、自动丢弃、来源 tab ID 和可用原生只读属性,false
|
|
583
|
-
筛选页面及所属窗口、分组;`totalTargetCount`、`totalWindowCount` 和 `totalTabCount`
|
|
584
|
-
|
|
585
|
-
分组保留名称、颜色、折叠/共享、窗口、首个成员位置和成员 ID,颜色只属于分组,只读属性只回显,不作为写入参数,列表操作不读取页面正文,不导航或改变焦点
|
|
1054
|
+
获取选中、静音、自动丢弃、来源 tab ID 和可用原生只读属性,false 值保留;`targetIds` 与 `managedOnly=true`
|
|
1055
|
+
筛选页面及所属窗口、分组;`totalTargetCount`、`totalWindowCount` 和 `totalTabCount` 区分总量与选中数量;窗口通过
|
|
1056
|
+
`targetIds` 引用页面,完整结果以 `favIconInline=true` 标明未内联的 favicon data URL
|
|
586
1057
|
|
|
587
|
-
|
|
588
|
-
|
|
1058
|
+
分组保留名称、颜色、折叠/共享、窗口、首个成员位置和成员 ID,颜色属于分组;原生只读属性用于回显,写入仍按各动作支持的字段校验;列表操作只读取这些元数据,保持页面正文、导航和焦点不变;旧 Extension 只返回分组摘要、
|
|
1059
|
+
未提供成员数组时,按同次响应的窗口和 tab 归属恢复组成员及首个成员位置,summary/full 和筛选共用该结果;完全没有分组信息时,响应省略
|
|
1060
|
+
`groups` 并用 warning 说明原因;`groups: []` 表示没有分组,只提供一个成员数组等畸形分组数据返回错误
|
|
589
1061
|
|
|
590
1062
|
页面和分组移动接受
|
|
591
|
-
`index=-1`,新建页的 index 非负,来源 tab
|
|
592
|
-
UI
|
|
593
|
-
|
|
594
|
-
|
|
1063
|
+
`index=-1`,新建页的 index 非负,来源 tab 与显式分组、窗口必须位于同一窗口,固定页不能在分组中创建;窗口状态与位置/尺寸的冲突、动作不支持的字段在修改前拒绝,CDP 对不支持的 Chrome
|
|
1064
|
+
UI 配置明确报错;`newWindow` 的 `url` 与 `urls` 互斥,在 normal 窗口中可与 `targetId`
|
|
1065
|
+
同时使用;popup 只接受单个 URL 或一个已有页面
|
|
1066
|
+
|
|
1067
|
+
明确的创建前拒绝保留 `actionExecuted=false`、`actionStatus="not_started"` 和 `failureStage="preflight"`
|
|
1068
|
+
更新在执行前拒绝时保留原 revision,原生更新已派发后的失败仍使 revision 失效
|
|
595
1069
|
|
|
596
1070
|
`emulate` 在两个 backend 中设置设备视口、像素密度、触摸能力和 User-Agent,`viewport`
|
|
597
|
-
恢复桌面视口与页面缩放并关闭触摸模拟,User-Agent 通过 `userAgent`
|
|
1071
|
+
恢复桌面视口与页面缩放并关闭触摸模拟,User-Agent 通过 `userAgent` 单独恢复,`manage(action="userAgent", userAgent="")`
|
|
1072
|
+
清除页面 UA 覆盖
|
|
598
1073
|
|
|
599
1074
|
**Stealth 模式档位**(CDP launch 参数,通过 `browse action=launch stealth=...` 设置):
|
|
600
1075
|
|
|
@@ -602,31 +1077,149 @@ UI 配置,不静默忽略 `newWindow` 的 `url` 与 `urls` 是两种互斥输
|
|
|
602
1077
|
- `safe`(默认)— 最小改动(移除 `navigator.webdriver`、清理 CDP 痕迹)
|
|
603
1078
|
- `aggressive` — 增加少量 WebGL/插件/语言等指纹修补(不等于完整伪装)
|
|
604
1079
|
|
|
1080
|
+
页面管理使用 30000 ms 请求期限,`newPage` 传入 `timeout` 时采用该值,排队变更超期后在派发前返回错误;未附页面条件的
|
|
1081
|
+
`pageMetadata`
|
|
1082
|
+
使用显式 target 独立读取、更新或清空,同页或其他页面的长等待期间均可执行,每个请求保留自己的 URL/revision 条件;带条件的备注操作仍串行检查条件
|
|
1083
|
+
|
|
1084
|
+
分组操作与页面解除受控按涉及页面串行执行,持锁期间重新核对原生成员和权限;创建页面使用 `active`,`activate` 仅适用于
|
|
1085
|
+
`movePage`
|
|
1086
|
+
|
|
1087
|
+
### 浏览器事件与原文件
|
|
1088
|
+
|
|
1089
|
+
点击下载链接、打开对话框或发起请求前准备观察,随后按返回的 `ref` 读取或处理对应事件;这些操作使用 `targetId`
|
|
1090
|
+
指定的受控页面或当前默认页,默认目标改变后,引用仍指向原页面
|
|
1091
|
+
|
|
1092
|
+
| `manage` action | 嵌套命令 |
|
|
1093
|
+
| ---------------- | --------------------------------------------------------------- |
|
|
1094
|
+
| `dialog` | `dialog:{op:"watch"\|"stop"\|"accept"\|"dismiss",ref?,text?}` |
|
|
1095
|
+
| `networkCapture` | `capture:{op:"start"\|"stop",include?:["body","stream"]}` |
|
|
1096
|
+
| `route` | `route:{op:"add"\|"remove"\|"continue"\|"fulfill"\|"fail",...}` |
|
|
1097
|
+
| `httpAuth` | `auth:{op:"set"\|"clear",...}` |
|
|
1098
|
+
| `download` | `download:{op:"watch"\|"stop"\|"wait"\|"save",...}` |
|
|
1099
|
+
|
|
1100
|
+
- `dialog`:观察对话框,或处理一个已观察弹窗,`text` 为 prompt 答复
|
|
1101
|
+
- `networkCapture`:记录原请求,可选采集正文及 WebSocket/SSE 消息
|
|
1102
|
+
- `route`:匹配页面请求,或处理一个已观察的暂停请求
|
|
1103
|
+
- `httpAuth`:为明确的 Server/Proxy 挑战范围设置凭证
|
|
1104
|
+
- `download`:标识下载,等待原生状态,保存可取得的原始字节
|
|
1105
|
+
|
|
1106
|
+
#### 处理对话框
|
|
1107
|
+
|
|
1108
|
+
```text
|
|
1109
|
+
manage(action="dialog", targetId="PAGE_ID", dialog={op:"watch"})
|
|
1110
|
+
input(targetId="PAGE_ID", events=[{type:"click", target:{css:"#show-prompt"}}])
|
|
1111
|
+
logs(type="dialog", targetId="PAGE_ID")
|
|
1112
|
+
manage(action="dialog", dialog={op:"accept", ref:"DIALOG_REF", text:"答复"})
|
|
1113
|
+
```
|
|
1114
|
+
|
|
1115
|
+
阻塞操作的对话框返回 `DIALOG_OPEN` 和引用,处理后检查原操作结果;原请求被弹窗阻塞期间,事件读取与处理仍可使用,`dismiss`
|
|
1116
|
+
省略 `text`,`stop` 结束观察,读取日志保持弹窗原状
|
|
1117
|
+
|
|
1118
|
+
#### 读取原响应
|
|
1119
|
+
|
|
1120
|
+
```text
|
|
1121
|
+
manage(action="networkCapture", targetId="PAGE_ID", capture={op:"start", include:["body","stream"]})
|
|
1122
|
+
logs(type="network", targetId="PAGE_ID", view="details")
|
|
1123
|
+
logs(type="network", view="responseBody", ref="REQUEST_REF", output="tmp:response.bin")
|
|
1124
|
+
```
|
|
1125
|
+
|
|
1126
|
+
`details` 保留请求身份、重定向跳次、基础 headers、ExtraInfo headers 和完整性;`requestBody`
|
|
1127
|
+
读取原 POST 数据,`responseBody` 读取协议提供的实体正文,显式 `output` 保存解码后的原始字节;内联正文使用
|
|
1128
|
+
`{encoding:"utf8"|"base64",data}`,正文不可用或已被淘汰时返回错误,multipart 文件段和重定向正文受原生协议能力限制;单份正文须小于 16
|
|
1129
|
+
MiB,headers、`cookieLine` 等 Cookie metadata 副本和 URL 中的认证字段会脱敏;`Location`、`Content-Location`、`Referer`
|
|
1130
|
+
等 URL header 在结构化 metadata 和原始握手文本中均遮蔽用户信息与敏感查询值,显式请求的正文内容保持原始字节
|
|
1131
|
+
|
|
1132
|
+
`view="stream"` 按观察顺序返回 WebSocket 方向/opcode 和 SSE 消息,消费有界缓存时检查截断、`dropped` 和 `evicted`
|
|
1133
|
+
字段
|
|
1134
|
+
使用 `capture:{op:"stop"}` 结束采集
|
|
1135
|
+
|
|
1136
|
+
#### 继续或模拟匹配请求
|
|
1137
|
+
|
|
1138
|
+
添加路由时传 `urlPattern`,可选 `stage:"Request"|"Response"`;从 `logs(type="network",view="paused")`
|
|
1139
|
+
取得暂停请求引用,再处理该请求:
|
|
1140
|
+
|
|
1141
|
+
```text
|
|
1142
|
+
manage(action="route", targetId="PAGE_ID", route={op:"add", urlPattern:"https://example.com/api/*"})
|
|
1143
|
+
logs(type="network", targetId="PAGE_ID", view="paused")
|
|
1144
|
+
manage(action="route", route={
|
|
1145
|
+
op:"fulfill", ref:"PAUSED_REF", response:{status:200, body:{encoding:"utf8",data:"mock"}}
|
|
1146
|
+
})
|
|
1147
|
+
```
|
|
1148
|
+
|
|
1149
|
+
`continue` 接受可选的 `request:{url?,method?,headers?,body?}`,headers 使用 `{name,value}` 数组;`fulfill` 要求
|
|
1150
|
+
`response:{status,statusText?,headers?,body?}`,`fail` 接受原生 `errorReason`,默认 `Aborted`;使用 `op:"remove"`
|
|
1151
|
+
和规则引用删除规则,未匹配请求立即继续;匹配请求暂停超过 30 秒,或发生取消、导航、解除受控、所属连接断开时,中止未解决的请求;原生命令回执丢失时保留未知状态,不自动重发,`clear`
|
|
1152
|
+
清除读取缓存,活动暂停请求和弹窗保留处理引用;原始 `manage cdp` 的 Fetch 命令共用这些归属与清理规则
|
|
1153
|
+
|
|
1154
|
+
HTTP 认证使用 `auth:{op:"set",scope:{source:"Server"|"Proxy",origin,realm?},username,password}`
|
|
1155
|
+
凭证只在内存中用于该页面和精确的挑战范围,失败后重复挑战会取消;通过 `logs(type="network",view="auth")`
|
|
1156
|
+
读取脱敏状态,`auth:{op:"clear"}` 清除凭证
|
|
1157
|
+
|
|
1158
|
+
#### 保存下载文件
|
|
1159
|
+
|
|
1160
|
+
```text
|
|
1161
|
+
manage(action="download", targetId="PAGE_ID", download={op:"watch",urlPattern:"https://example.com/files/*"})
|
|
1162
|
+
input(targetId="PAGE_ID", events=[{type:"click",target:{css:"a.download"}}])
|
|
1163
|
+
logs(type="download", targetId="PAGE_ID")
|
|
1164
|
+
manage(action="download", download={op:"wait",ref:"DOWNLOAD_REF",timeout:30000})
|
|
1165
|
+
manage(action="download", download={op:"save",ref:"DOWNLOAD_REF",output:"tmp:attachment.bin"})
|
|
1166
|
+
```
|
|
1167
|
+
|
|
1168
|
+
原生下载 GUID 和状态区分“下载完成”与“原文件可交付”,`save` 要求下载已完成且 `artifact="available"`
|
|
1169
|
+
保存操作使用截获的原响应,不重新请求下载 URL,原生 Save
|
|
1170
|
+
As、blob 下载或浏览器安全限制可使文件不可用,结果会说明原因;共享浏览器的下载策略保持原值,这条收件路径同样要求正文小于 16
|
|
1171
|
+
MiB,`download:{op:"stop"}`
|
|
1172
|
+
结束观察并释放拦截;停止、暂停或文档变化后,迟到正文保持原观察归属,后续同 URL 下载的新 GUID 不继承该正文;原始正文仅在 frame、URL、原生 session、观察代次及文档版本一致且候选唯一时绑定 GUID;
|
|
1173
|
+
已可靠绑定的历史下载继续按原引用读取,直到缓存淘汰或 controller 释放
|
|
1174
|
+
|
|
1175
|
+
引用绑定 Server 实例、页面和连接代次,失效或其他实例的引用会被拒绝;默认目标事件配置等待临时选页恢复,带 ref 的弹窗和 Fetch 处理保持独立;同一 Server 重连后等待旧事件资源清理完成再配置新观察;
|
|
1176
|
+
已有页面迁入新窗口与解除受控共用成员页锁,临时选页期间继续记录原页面在途请求的终态;处理 Cloudflare 前结束当前 Fetch 控制并暂停这些观察,再解除 debugger 附加;查看返回的
|
|
1177
|
+
`browserEvents`
|
|
1178
|
+
状态,验证完成后按需显式重新开始观察;新增事件操作要求 Server 与 Extension 构建匹配,缺少原生能力时在启用拦截前报告限制;CDP 认证与响应捕获在连接请求结束后继续有效,后续每次工具调用使用各自的超时与取消信号
|
|
1179
|
+
|
|
1180
|
+
清理失败时保留原 controller、owner 和未确认资源,随后同一 Server 的事件操作先受控重试清理,成功后才建立新观察;未确认的暂停请求继续阻止新配置与 debugger 解除,返回清理错误及实际状态,处理引用保持有效;
|
|
1181
|
+
原生 session 或页面确已结束后释放对应阻挡
|
|
1182
|
+
|
|
1183
|
+
`cleanupFailures` 保留字符串数组,配套 `cleanupFailureDetails` 记录发生时间、阶段、已观测 ref 或 request
|
|
1184
|
+
ID、目标、owner 与 session
|
|
1185
|
+
generation
|
|
1186
|
+
每个 controller 最多保存 20 条,dispose 时清除;新 controller 从空记录开始,已经返回的详情保留原始归属;控制台 metadata 和错误消息遮蔽 URL 中的敏感查询值,
|
|
1187
|
+
显式请求的页面文本和正文文件保留原内容
|
|
1188
|
+
|
|
605
1189
|
### logs - 浏览器日志
|
|
606
1190
|
|
|
607
|
-
| Type
|
|
608
|
-
|
|
|
609
|
-
| `console`
|
|
610
|
-
| `network`
|
|
1191
|
+
| Type | 描述 |
|
|
1192
|
+
| ---------- | -------------------------------------------- |
|
|
1193
|
+
| `console` | 控制台日志(支持级别过滤) |
|
|
1194
|
+
| `network` | 请求摘要、详情、正文、暂停请求、认证及流消息 |
|
|
1195
|
+
| `dialog` | 对话框引用及待处理/关闭状态 |
|
|
1196
|
+
| `download` | 原生下载状态及原文件可用性 |
|
|
611
1197
|
|
|
612
1198
|
参数:`output` 将结果保存到文件,console 日志统一返回公开级别 `error`、`warning`、`info`、`debug`,浏览器原始的 `warn`、
|
|
613
1199
|
`log` 等级会在过滤和返回前转换,清空 fallback
|
|
614
1200
|
console 日志会保留 hook,debugger 采集恢复后,fallback 采集会停用;仍指向 MCP
|
|
615
|
-
wrapper 的 console 方法会恢复,页面之后安装的 wrapper
|
|
616
|
-
|
|
1201
|
+
wrapper 的 console 方法会恢复,页面之后安装的 wrapper 保持不变;独立的 fallback
|
|
1202
|
+
console 调用即使时间戳和文本相同,也会保留各自的级别和次数;重复读取已排空的批次不会再次追加,恢复 debugger 采集时,待排空调用各保留一次,对应 Runtime 历史回放不重复追加,
|
|
1203
|
+
已清除的 fallback 调用保持已清除,缓冲区保留最新 1000 条;network 日志在
|
|
1204
|
+
`loadingFinished` 或 `loadingFailed`
|
|
1205
|
+
时才完成记录,不会在收到 headers 时提前结束,因此 body 失败会同时保留 HTTP
|
|
1206
|
+
status 和
|
|
617
1207
|
`errorText`,传输中的 body 也会继续计入 `networkidle`,日志尽量返回 `method`、
|
|
618
1208
|
`url`、`status`、`timestamp`、`duration`,URL
|
|
619
1209
|
query 中常见的认证、签名、密码和 token 参数会在内联响应、diagnostics 和 显式 `output` 文件中替换为 `[REDACTED]`,并返回
|
|
620
1210
|
`urlRedacted`、`urlOriginalLength` 和
|
|
621
1211
|
`redactedQueryParameters`,内联 network 结果会把脱敏后的单条 URL 限制为 2048 字符,截断时返回 `urlLength` 和
|
|
622
1212
|
`urlTruncated: true`,`urlPattern` 支持 `*` 匹配任意长度字符、`?` 匹配单个字符,`tabId`
|
|
623
|
-
指定目标 Tab(Extension 模式),`frame`
|
|
1213
|
+
指定目标 Tab(Extension 模式),`frame` 不适用于日志;network 各视图中的 `urlPattern`
|
|
1214
|
+
按请求 URL 过滤,包含暂停请求和认证事件,过滤后再应用 `limit`;`clear` 保留仍需处理的请求
|
|
624
1215
|
|
|
625
1216
|
Extension debugger 不可用时,network 每次读取都会刷新 performance 记录并标记
|
|
626
1217
|
`source="performance"`;状态使用浏览器提供的 `responseStatus`,无法取得时为
|
|
627
1218
|
`0`,未知请求方法保留空值,重复读取保留记录序列号;`clear`
|
|
628
1219
|
清除 MCP 记录并推进当前文档的读取边界,不清除网页共享的 performance 数据,新文档重新建立边界,读取失败返回错误,不冒充空日志
|
|
629
1220
|
|
|
1221
|
+
CDP 网络日志在响应体传输失败时保留 HTTP 状态,每个请求只记录一次终态,临时选择其他页面时保留各目标独立的日志;清除日志只删除已缓冲记录,在途请求保留到最终事件,清除后完成的请求会出现在新日志中
|
|
1222
|
+
|
|
630
1223
|
### cookies - Cookie 管理
|
|
631
1224
|
|
|
632
1225
|
| Action | 描述 |
|
|
@@ -636,53 +1229,34 @@ Extension debugger 不可用时,network 每次读取都会刷新 performance
|
|
|
636
1229
|
| `delete` | 删除 Cookie |
|
|
637
1230
|
| `clear` | 在 URL 或域名范围内删除 Cookie,可用 `name` 进一步过滤 |
|
|
638
1231
|
|
|
639
|
-
|
|
640
|
-
`
|
|
641
|
-
|
|
642
|
-
|
|
643
|
-
|
|
644
|
-
所有工具使用统一的 `Target` 类型定位元素:
|
|
645
|
-
|
|
646
|
-
```typescript
|
|
647
|
-
// 按可访问性(推荐 - 最稳定)
|
|
648
|
-
const byRole = { role: 'button', name: '提交' }
|
|
649
|
-
|
|
650
|
-
// 按可访问性精确匹配名称
|
|
651
|
-
const byExactRole = { role: 'button', name: '提交', exact: true }
|
|
652
|
-
|
|
653
|
-
// 按文本内容
|
|
654
|
-
const byText = { text: '点击这里', exact: true }
|
|
655
|
-
|
|
656
|
-
// 按表单 label
|
|
657
|
-
const byLabel = { label: '邮箱' }
|
|
658
|
-
|
|
659
|
-
// 按 placeholder
|
|
660
|
-
const byPlaceholder = { placeholder: '请输入姓名' }
|
|
661
|
-
|
|
662
|
-
// 按 title 属性
|
|
663
|
-
const byTitle = { title: '关闭对话框' }
|
|
664
|
-
|
|
665
|
-
// 按 alt 文本(图片)
|
|
666
|
-
const byAlt = { alt: '头像' }
|
|
1232
|
+
所有 action 支持 `targetId`、`partitionKey:{topLevelSite?,hasCrossSiteAncestor?}` 和对应后端的存储范围:Extension 使用
|
|
1233
|
+
`storeId`,CDP 使用 `browserContextId`
|
|
1234
|
+
Extension 将目标页映射到原生 CookieStore,显式 store 与目标冲突时拒绝,不适用当前后端的范围字段返回错误;省略这些字段时沿用原 URL/domain 行为,`get`
|
|
1235
|
+
至少需要一个非空白 name、domain 或 url,存储上下文和其他条件只进一步限定这个读取范围,导出文件遵守相同校验
|
|
667
1236
|
|
|
668
|
-
|
|
669
|
-
|
|
1237
|
+
URL 过滤在 target 与 browser context 作用域下同样遵守 Cookie 路径边界,Path 为 `/app` 的 Cookie 匹配
|
|
1238
|
+
`/app/info`,`/apple/info` 会将其排除
|
|
670
1239
|
|
|
671
|
-
|
|
672
|
-
|
|
1240
|
+
`clear`
|
|
1241
|
+
必须指定 url 或 domain,name 仅进一步缩小范围,CDP 删除保留所选 Cookie 的完整 name、原始 domain、path、partition 与 browser
|
|
1242
|
+
context,省略 target 时在清除开始固定当前页的存储上下文,分区身份无法序列化时在删除前拒绝
|
|
673
1243
|
|
|
674
|
-
|
|
675
|
-
|
|
1244
|
+
CDP
|
|
1245
|
+
clear 的 count 统计紧邻删除前检查为存在、请求收到 ACK 后检查为消失的 Cookie 身份,`countSemantics="observed_present_then_absent"`
|
|
1246
|
+
标识该状态比较,acknowledged 统计原生 ACK,alreadyAbsent 统计预检查时已消失的身份,matched 与 attempted 分别表示候选总数和已开始删除的步骤数,网页并发修改可发生在两次观察之间,
|
|
1247
|
+
Extension 沿用原生移除确认计数
|
|
676
1248
|
|
|
677
|
-
|
|
678
|
-
|
|
1249
|
+
CDP 在首次删除、验证或连接清理失败时停止,返回 COOKIE_CLEAR_PARTIAL,保留已知 count、ACK 数、失败或未知步骤、未处理数量、阶段与原始原因,动作状态保留先前修改并返回 retryable=false,
|
|
1250
|
+
临时 session
|
|
1251
|
+
detach 失败也保留此前 ACK 和已经验证的消失状态
|
|
679
1252
|
|
|
680
|
-
|
|
681
|
-
|
|
1253
|
+
删除已经发送、ACK 尚未收到时,连接关闭、主动关闭、超时或取消均计为 unknown,首项未知返回
|
|
1254
|
+
`actionStatus="unknown"`,此前已有 ACK 时保留 partial,failed 统计明确拒绝、未派发的删除步骤,以及 ACK 后仍存在的身份,删除尝试后的未分类错误保持未知,后续删除停止
|
|
682
1255
|
|
|
683
|
-
|
|
684
|
-
|
|
685
|
-
|
|
1256
|
+
MCP 取消会停止排队的 Cookie 请求、连接等待及两个后端的后续删除,CDP 保留此前确认的进度和未收到 ACK 的删除未知结果,临时 attach 在取消或超时后继续负责接收原生响应,
|
|
1257
|
+
迟到成功获得的 session 使用独立 1000
|
|
1258
|
+
ms 预算分离,清理失败时日志保留命令及 session 身份,归属记录保持到连接关闭,删除不重放,Extension
|
|
1259
|
+
RPC 在回包前取消时返回该 RPC 结果未知,Extension 在当前原生调用结算后停止剩余移除
|
|
686
1260
|
|
|
687
1261
|
## 使用示例
|
|
688
1262
|
|
|
@@ -773,7 +1347,10 @@ MiB;启动时只清理超过 24 小时且所属进程已退出的带归属标
|
|
|
773
1347
|
extract(type="metadata")
|
|
774
1348
|
```
|
|
775
1349
|
|
|
776
|
-
###
|
|
1350
|
+
### 嵌套 frame 操作
|
|
1351
|
+
|
|
1352
|
+
两种后端的 iframe 选择器和索引均覆盖 open ShadowRoot,跨源 frame 和 OOPIF 的准备使用原请求期限,脚本派发前超时返回
|
|
1353
|
+
`actionExecuted=false`、`actionStatus="not_started"`,并尝试恢复原默认目标
|
|
777
1354
|
|
|
778
1355
|
```
|
|
779
1356
|
// 通过 CSS 选择器指定 iframe
|
|
@@ -782,6 +1359,9 @@ evaluate(script="document.title", frame="iframe#main")
|
|
|
782
1359
|
// 通过索引指定 iframe
|
|
783
1360
|
extract(type="text", frame=0)
|
|
784
1361
|
|
|
1362
|
+
// 每一步相对于当前父 frame 定位,CDP 同时支持 OOPIF
|
|
1363
|
+
evaluate(script="document.title", frame=["iframe#outer", "iframe#inner"])
|
|
1364
|
+
|
|
785
1365
|
// 在 iframe 内输入
|
|
786
1366
|
input(events=[
|
|
787
1367
|
{ type: "mousedown", target: { label: "用户名" } },
|
|
@@ -791,18 +1371,24 @@ input(events=[
|
|
|
791
1371
|
```
|
|
792
1372
|
|
|
793
1373
|
CSS 选择器和数字索引按父文档的 DOM
|
|
794
|
-
iframe 顺序定位,DOM 中不存在的子 frame(包括其他 Extension 加入的 frame)不会改变索引,也不会成为候选目标,所选元素无法对应到唯一
|
|
1374
|
+
iframe 顺序定位,DOM 中不存在的子 frame(包括其他 Extension 加入的 frame)不会改变索引,也不会成为候选目标,所选元素无法对应到唯一
|
|
1375
|
+
Chrome
|
|
795
1376
|
frame 时返回 `FRAME_IDENTITY_UNAVAILABLE`,不会选择其他 frame;precise
|
|
796
1377
|
evaluate 按含 query 和 fragment 的完整 URL 定位,并按所选 DOM iframe 区分 URL 相同的 frame,包括
|
|
797
1378
|
`about:srcdoc`,无法确认身份时拒绝执行
|
|
798
1379
|
|
|
799
1380
|
frame 定位失败分别返回 `INVALID_FRAME_SELECTOR`、`FRAME_NOT_IFRAME` 或 `FRAME_NOT_FOUND`,读取注入区分
|
|
800
1381
|
`INVALID_SELECTOR`、`FRAME_STALE_CONTEXT`、`FRAME_INJECTION_DENIED`、`FRAME_SCRIPT_FAILED`、 `FRAME_INJECTION_FAILED` 和
|
|
801
|
-
`FRAME_SCRIPT_NO_RESULT`,并报告注入或脚本结果阶段,无结果不等于 selector 非法,空文本、空元素数组、null 属性值和 void
|
|
1382
|
+
`FRAME_SCRIPT_NO_RESULT`,并报告注入或脚本结果阶段,无结果不等于 selector 非法,空文本、空元素数组、null 属性值和 void
|
|
1383
|
+
脚本调用保持原语义,错误不会重放脚本;成功定位后的读取失败在
|
|
802
1384
|
`pageContext.frameContext` 保留 DOM 索引、Chrome frame ID 和可取得的文档身份;frame
|
|
803
1385
|
URL 诊断去掉认证、query 和 fragment,长度限制为 500 字符,`data:` 与 `javascript:` 只返回协议;无法解析的 URL 返回
|
|
804
1386
|
`url=null` 和 `urlStatus="unavailable"`
|
|
805
1387
|
|
|
1388
|
+
Extension 的 text、attribute 与 accessibility state 使用 frame 内的元素身份和局部矩形,缩放、旋转及其嵌套路径中的只读查询无需为根坐标校准附加 debugger
|
|
1389
|
+
触摸、选区、编辑命令、上传与拖拽的目标定位也使用 frame 内的引用
|
|
1390
|
+
原生指针校准仍接受仅平移的 frame 偏移,frame owner 含缩放或旋转时,在使用推定原点前返回 `FRAME_GEOMETRY_UNAVAILABLE`
|
|
1391
|
+
|
|
806
1392
|
### 等待元素
|
|
807
1393
|
|
|
808
1394
|
```
|
|
@@ -840,6 +1426,19 @@ wait(for="element", target={ text: "加载完成" }, state="visible")
|
|
|
840
1426
|
└──────────┘
|
|
841
1427
|
```
|
|
842
1428
|
|
|
1429
|
+
### 连接状态与恢复
|
|
1430
|
+
|
|
1431
|
+
`browse(action="connect")` 和本地 `/api/info` 返回活动 Extension 后台 bundle 的 hash,并与 Server 附带的 bundle 比较
|
|
1432
|
+
`bundleStatus="stale"` 表示浏览器仍使用旧 bundle,在 `chrome://extensions/` 刷新该 Extension;旧版缺少
|
|
1433
|
+
`network_challenge_state` 时,使用 tab 标题和 DOM 检测,构建身份保持不阻断自动连接
|
|
1434
|
+
|
|
1435
|
+
Popup 的断开操作立即暂停当前 Extension 会话的本地连接,Service
|
|
1436
|
+
Worker 恢复后继续暂停,显式连接恢复发现,完整重载 Extension 或重启 Chrome 后恢复自动连接;单个 Server 重启后按既有退避持续重连,其他连接保持;显式断开取消这些重试;Popup 设置保存失败会显示错误,
|
|
1437
|
+
迟到旧值不覆盖新选择;暂停状态读取暂时失败时,同一 Worker 的后续连接尝试可重新读取,暂停写入失败保留可见错误
|
|
1438
|
+
|
|
1439
|
+
发现摘要在首次扫描与端口集合变化时输出,包括空集合,每次仍检查完整端口范围,相同集合的扫描与自动重连不重复报告,显式断开重新开始报告;普通 WebSocket
|
|
1440
|
+
open 前失败记录为 debug,已识别 MCP Server 的认证或协议拒绝在摘要变化时输出一条限量 warning
|
|
1441
|
+
|
|
843
1442
|
## 项目结构
|
|
844
1443
|
|
|
845
1444
|
```
|
|
@@ -901,7 +1500,23 @@ mcp-chrome/
|
|
|
901
1500
|
- `manage cdp` 操作可发送任意 CDP 命令
|
|
902
1501
|
- 网络 URL 中的常见认证参数默认会脱敏,但 console 文本和非标准参数名仍可能包含敏感信息
|
|
903
1502
|
|
|
904
|
-
###
|
|
1503
|
+
### 配对与本地访问
|
|
1504
|
+
|
|
1505
|
+
普通本地连接默认自动发现,在共享机器、CI runner 或不可信进程可访问 `127.0.0.1:19222-19299` 的容器环境中,在 Server 设置
|
|
1506
|
+
`MCP_CHROME_PAIRING_TOKEN`,并在 Extension popup 输入相同 token:
|
|
1507
|
+
|
|
1508
|
+
```bash
|
|
1509
|
+
MCP_CHROME_PAIRING_TOKEN="your-token" node /path/to/mcp-chrome/dist/index.js
|
|
1510
|
+
```
|
|
1511
|
+
|
|
1512
|
+
强制 token 时设置
|
|
1513
|
+
`MCP_CHROME_ALLOW_INSECURE_NO_TOKEN=0`,并在 popup 关闭“允许无 token 本地连接”;策略关闭会立即取消进行中的 health
|
|
1514
|
+
check、WebSocket 握手与重连,旧的无 token 尝试随之终止
|
|
1515
|
+
|
|
1516
|
+
带 token 的两端须支持认证协议 v2,命令、响应、取消和心跳使用方向分离的会话密钥及递增序号认证,health 证明绑定双方 nonce、Server 实例和端口;Extension 收到认证 ready 后报告可用,
|
|
1517
|
+
Server 收到认证 hello 后接受请求,旧版严格 token 对端返回协议诊断;默认无 token 的发现与自动重连保持可用
|
|
1518
|
+
|
|
1519
|
+
### 反检测(stealth):实际能力
|
|
905
1520
|
|
|
906
1521
|
`stealth` 模式(`safe` / `aggressive`)仅覆盖少量指纹面:
|
|
907
1522
|
|
|
@@ -916,7 +1531,17 @@ mcp-chrome/
|
|
|
916
1531
|
- **仅 Chrome**:仅支持 Chrome/Chromium 浏览器(不支持 Firefox/Safari)
|
|
917
1532
|
- **CDP 单会话**:CDP 模式仅支持一个浏览器会话
|
|
918
1533
|
- **Extension 需要 Chrome**:Extension 为 Manifest V3,仅限 Chrome
|
|
919
|
-
- **iframe
|
|
1534
|
+
- **iframe**:嵌套定位使用选择器/索引数组,XPath 保持原生文档作用域
|
|
1535
|
+
|
|
1536
|
+
## 兼容客户端
|
|
1537
|
+
|
|
1538
|
+
| 客户端 | 状态 |
|
|
1539
|
+
| ------------------- | ---- |
|
|
1540
|
+
| Claude Code | ✅ |
|
|
1541
|
+
| Claude Desktop | ✅ |
|
|
1542
|
+
| Cursor | ✅ |
|
|
1543
|
+
| Windsurf | ✅ |
|
|
1544
|
+
| 其他 MCP 兼容客户端 | ✅ |
|
|
920
1545
|
|
|
921
1546
|
## 许可证
|
|
922
1547
|
|
|
@@ -926,41 +1551,3 @@ MIT 许可证 - 详见 [LICENSE](LICENSE)
|
|
|
926
1551
|
|
|
927
1552
|
- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP 规范
|
|
928
1553
|
- [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/) - CDP 文档
|
|
929
|
-
|
|
930
|
-
## 操作状态与诊断
|
|
931
|
-
|
|
932
|
-
input 和 evaluate 返回值追加 `actionExecuted`、`actionStatus`、`verificationStatus`、`failureStage` 和
|
|
933
|
-
`retryable`,验证状态分为
|
|
934
|
-
`matched`、`not_matched`、`unavailable`、`error`;debugger 超时且无法证明脚本已停止时,动作状态为
|
|
935
|
-
`unknown`,页面脚本抛异常时返回 `actionExecuted=true` 和 `actionStatus="failed"`;原生执行已返回结果后,本地结果展开或序列化失败时返回
|
|
936
|
-
`actionStatus="completed"` 和 `failureStage="output"`,页面前置条件不符时,input 和 evaluate 返回
|
|
937
|
-
`actionExecuted=false`、`actionStatus="not_started"`,diagnostics 是附加能力,失败时返回
|
|
938
|
-
`diagnosticsStatus`,不会覆盖主动作结果,browse 和 wait 的主动作失败时,也会保留失败前已收集的 diagnostics,目标诊断会读取当前 tab 的实时状态,不依赖 attach 时缓存的 URL 和标题
|
|
939
|
-
|
|
940
|
-
原生脚本终止,以及 CDP `Runtime` 脚本命令返回 `Internal error`、`Object couldn't be returned by value` 或
|
|
941
|
-
`Object reference chain is too long` 时,evaluate 和 `manage cdp` 保留原错误码,返回 `actionExecuted=true`、`actionStatus="unknown"`、`retryable=false`,不重放命令;evaluate 的执行中
|
|
942
|
-
RPC 超时或过期 execution context 导致结果未知时也不可直接重试;执行开始前的超时仍可重试;页面主动抛出的同名异常按动作失败处理,重试标记为 false
|
|
943
|
-
|
|
944
|
-
Extension 中已识别的原生 CDP 拒绝返回 `CDP_ERROR`,保留 method、目标、原生消息和可用的协议 code,context 区分 Debugger
|
|
945
|
-
域未启用、scriptId 失效、浏览器级命令限制、方法不存在、命令权限拒绝(`Not allowed`)及原生结果序列化失败,资源或方法查找失败不会推断为整个域不支持
|
|
946
|
-
这些调用保持失败并输出 warning,未知异常继续按 error 报告,原生快照或权限检查发现的已关闭 tab 按目标失败处理,与页面主动抛出的同文案异常分开
|
|
947
|
-
|
|
948
|
-
Extension 的 accessibility state 在生成元素名称和状态正文时,均不访问 `input[type=hidden]` 与 `input[type=password]`
|
|
949
|
-
的 value getter,默认 `all`、目标子树和文件输出使用相同规则隐藏控件仍可返回
|
|
950
|
-
`visible=false`,标签、placeholder、title 和普通输入值保留;显式脚本、HTML 和属性读取保持原有行为
|
|
951
|
-
|
|
952
|
-
`replace` 仅对 `textarea` 以及 `text`、`search`、`tel`、`url`、`password`
|
|
953
|
-
类型的 input 使用文本选区,其他 input 类型通过原生完整 value 更新,并返回请求值与浏览器规范化后的实际值,对不支持选区的类型单独执行
|
|
954
|
-
`select` 会返回 `UNSUPPORTED_SELECTION`,CDP模式下,`select` 和 `replace` 的 locator target 通过 CDP
|
|
955
|
-
locator 聚焦,不调用 Extension refId,password value 不进入 input 失败 context 和 text
|
|
956
|
-
post-condition 观测值,失败响应还会脱敏传入的 `find` 和替换 `text`,password 的 `select`/`replace`
|
|
957
|
-
成功和失败响应均隐藏 console 与 network 诊断正文,返回 `diagnostics.redacted=true` 和
|
|
958
|
-
`reason="sensitive_input_or_unresolved_target"`;无法安全确认选择目标时也隐藏这些正文普通输入保留诊断,密码保护仅持续到当前 input 请求结束目标超时返回限量的locator、tab、frame、匹配数和候选上下文,显式
|
|
959
|
-
`tabId` 或 `frame`
|
|
960
|
-
作用域会在 input、wait、logs、extract 开始前确定活动 backend,动作和验证使用同一个目标 backend,precise iframe
|
|
961
|
-
evaluate 默认使用 `staleContextRetry="never"`,context 失效时不重放脚本; `readOnly` 允许 Extension 校验 frame
|
|
962
|
-
identity 并解析新 execution context 后重放一次,响应包含策略、`retryAttempted`、限量的 `retryReason`,以及最终 Extension
|
|
963
|
-
frame、parent frame、URL、CDP frame 和 execution context ID 组成的 `frameContext`,URL 相同的 frame 仅在所选 DOM
|
|
964
|
-
iframe 无法唯一确认目标时拒绝执行;Extension 重载后可继续访问原页面中的 iframe,无需刷新或重新导航,探测上下文失效时输出 warning 并停止监听,避免未捕获的消息调用异常
|
|
965
|
-
发现摘要在首次扫描和端口集合变化时输出,包含从有 Server 到空集合的变化,相同集合的扫描及自动重连不重复输出;每次仍检查完整端口范围,显式 disconnect 后重新开始报告
|
|
966
|
-
普通 WebSocket open 前失败仍聚合为 debug;已识别 MCP server 的认证或协议拒绝只在摘要变化时输出一条限量 warning
|