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