dsh-agent-team-ui-testing 0.0.0-stage → 0.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/LICENSE +21 -0
- package/README.md +327 -2
- package/annotation-capture.js +111 -0
- package/banner.png +0 -0
- package/banner_zh.png +0 -0
- package/browser-safety.js +293 -0
- package/capture-p0.js +910 -0
- package/client.js +11302 -0
- package/context-menu.js +134 -0
- package/cordis.patch.yml +3 -0
- package/core/clock.js +88 -0
- package/core/config-store.js +566 -0
- package/core/config.js +892 -0
- package/core/contracts.js +240 -0
- package/core/errors.js +156 -0
- package/core/evidence.js +141 -0
- package/core/geometry.js +217 -0
- package/core/identity.js +180 -0
- package/core/index.js +24 -0
- package/core/p0.js +1101 -0
- package/core/readiness.js +175 -0
- package/core/registry.js +239 -0
- package/core/tab-access.js +1350 -0
- package/docs/adapters.md +160 -0
- package/docs/architecture.md +146 -0
- package/docs/capability-tiers.md +80 -0
- package/docs/capture-p0.md +90 -0
- package/docs/diagnose-reason-codes.md +157 -0
- package/docs/element-picker.md +143 -0
- package/docs/getting-started.md +136 -0
- package/docs/index.md +36 -0
- package/docs/multi-tab.md +162 -0
- package/docs/network-p0.md +117 -0
- package/docs/panel-context-menu.md +41 -0
- package/docs/t2-structured-gui.md +68 -0
- package/docs/t3-vision.md +84 -0
- package/docs/t4-dynamic-behavior.md +135 -0
- package/docs/tools.md +174 -0
- package/docs/verification.md +131 -0
- package/docs/viewport-control.md +94 -0
- package/dynamic-t4.js +5699 -0
- package/frame-push.js +508 -0
- package/frame-source.js +162 -0
- package/icon.png +0 -0
- package/index.js +23028 -0
- package/integration/cross-environment.js +1535 -0
- package/integration/diagnose.js +945 -0
- package/integration/tab-principal.js +493 -0
- package/locale/en.json +6 -0
- package/locale/zh.json +6 -0
- package/network-p0.js +4264 -0
- package/package.json +19 -4
- package/select-control.js +298 -0
- package/skills/ui-testing-common/SKILL.md +54 -0
- package/skills/ui-testing-fake/SKILL.md +43 -0
- package/skills/ui-testing-web/SKILL.md +520 -0
- package/skills/ui-testing-web/manifests/declared-capabilities.json +903 -0
- package/skills/ui-testing-web/references/contracts/capability.md +68 -0
- package/skills/ui-testing-web/references/contracts/evidence.md +41 -0
- package/skills/ui-testing-web/references/contracts/operation.md +44 -0
- package/skills/ui-testing-web/references/core/dynamic-visual.md +123 -0
- package/skills/ui-testing-web/references/core/fallback.md +83 -0
- package/skills/ui-testing-web/references/core/network-and-state.md +114 -0
- package/skills/ui-testing-web/references/core/page-identity.md +91 -0
- package/skills/ui-testing-web/references/core/report-template.md +144 -0
- package/skills/ui-testing-web/references/core/reporting.md +92 -0
- package/skills/ui-testing-web/references/core/safety.md +12 -0
- package/skills/ui-testing-web/references/core/selection.md +26 -0
- package/skills/ui-testing-web/references/core/tool-routing-and-limits.md +198 -0
- package/skills/ui-testing-web/references/core/verdict-examples.md +96 -0
- package/skills/ui-testing-web/references/core/verdict-gate.md +105 -0
- package/skills/ui-testing-web/references/core/verification.md +19 -0
- package/skills/ui-testing-web/references/core/workflow.md +16 -0
- package/skills/ui-testing-web/references/platforms/index.md +19 -0
- package/skills/ui-testing-web/references/platforms/web.md +17 -0
- package/skills/ui-testing-web/references/scenarios/annotations.md +104 -0
- package/skills/ui-testing-web/references/scenarios/functional.md +205 -0
- package/skills/ui-testing-web/references/scenarios/visual-motion.md +170 -0
- package/skills/ui-testing-web/references/tiers/t1-programmatic.md +25 -0
- package/skills/ui-testing-web/references/tiers/t2-structured.md +61 -0
- package/skills/ui-testing-web/references/tiers/t3-static-visual.md +45 -0
- package/skills/ui-testing-web/references/tiers/t4-dynamic-visual.md +58 -0
- package/skills/ui-testing-web/templates/capability-note.md +23 -0
- package/skills/ui-testing-web/templates/platform.md +30 -0
- package/skills/ui-testing-web/templates/regression-case.md +15 -0
- package/skills/ui-testing-web/templates/scenario.md +13 -0
- package/targets/fake/adapter.js +1163 -0
- package/targets/fake/fixtures.js +177 -0
- package/targets/web/adapter.js +1231 -0
- package/targets/web/provider.js +415 -0
- package/vision-baseline.js +1254 -0
- package/vision-t3.js +2657 -0
|
@@ -0,0 +1,170 @@
|
|
|
1
|
+
# 视觉与动态场景调试手册(T3 静态 / T4 时序)
|
|
2
|
+
|
|
3
|
+
> 面向**没有上下文**的 Agent:照本文管线走就能调动画,不必先读源码。
|
|
4
|
+
> 权威契约 [docs/t4-dynamic-behavior.md](../../../../docs/t4-dynamic-behavior.md)、实现冻结 [docs/t4-dynamic-behavior.md](../../../../docs/t4-dynamic-behavior.md)。
|
|
5
|
+
|
|
6
|
+
## 0. 先选层,别用错工具
|
|
7
|
+
|
|
8
|
+
| 你要回答的问题 | 用哪层 |
|
|
9
|
+
| --- | --- |
|
|
10
|
+
| 元素在哪、能不能点、点了没反应 | T2(`browser_snapshot` / `node_state` / `click`) |
|
|
11
|
+
| 改前改后两张图差在哪、颜色对不对、有没有被遮挡 | T3(`browser_vision_image` / `compare`) |
|
|
12
|
+
| **动画顺不顺、闪不闪、卡不卡、冻结多久、过渡多长、动的是哪块** | **T4** |
|
|
13
|
+
| **这次点击/请求是不是导致了画面变化** | **T4 `dynamic_correlate`** + P0 网络 |
|
|
14
|
+
|
|
15
|
+
单张截图、`browser_state.seq`、面板 `/metrics` **都不是** T4 帧证据。
|
|
16
|
+
|
|
17
|
+
## 1. 三条铁律(都是踩过的坑)
|
|
18
|
+
|
|
19
|
+
**① 不要用整页截图"理解动画"。**
|
|
20
|
+
|
|
21
|
+
页面经常把答案直接画在画面上——例如把 `t=…ms tx=… opacity=…`、`rgb=…,…,…` 这类状态行写进面板。拿整页图去"看动画",等于**读答案**而不是看运动,结论不可信;而且浪费:整帧 JPEG 体积通常是裁剪区域 PNG 的十倍以上。
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
**② 算力靠抽帧,不靠 `region`。**
|
|
26
|
+
|
|
27
|
+
JPEG 必须**整帧解码**,`region` 只缩小比较范围与输出噪声,**不降低解码成本**。实测:同一批帧 176 帧全帧分析 **20.5s → `BLOCKED(dynamic-timeout)`**;抽 6 帧只要 **883ms**(快 23×)。所以:
|
|
28
|
+
|
|
29
|
+
- 耗时不够 → 减 `frameIds` / 收窄 `window`;
|
|
30
|
+
- token / 带宽不够 → 用 `region` 裁剪。
|
|
31
|
+
|
|
32
|
+
**③ 采样没覆盖 ≠ 没有异常。**
|
|
33
|
+
|
|
34
|
+
16ms 级闪白在 damage 驱动的 screencast 里可能一帧都抓不到。这时只能报 **`INCONCLUSIVE`(采样不足)**,**绝不许写"无闪烁/无卡顿"**。
|
|
35
|
+
|
|
36
|
+
## 2. 标准管线(6 步)
|
|
37
|
+
|
|
38
|
+
### Step 0 · 打开页面并立刻开始采集
|
|
39
|
+
|
|
40
|
+
Agent 一次工具往返实测约 **11.7s**。若先 `navigate`、下一轮再 `start`,观察窗口可能已经过去(很多动画 3s 就停)。**把 `browser_navigate` 与 `browser_dynamic_session{action:"start"}` 放在同一批下发**——实测可压到导航完成后 **6–21ms** 即开始采集。
|
|
41
|
+
|
|
42
|
+
```text
|
|
43
|
+
browser_navigate { url }
|
|
44
|
+
browser_dynamic_session { action:"start",
|
|
45
|
+
config:{ captureVisual:true, source:"screencast", durationMs:60000 } }
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
- `screencast`:共享预览流、JPEG、**damage 驱动**(页面不动就没帧),适合"看动的东西"。
|
|
49
|
+
- `screenshot-loop`:PNG、`precise:true`、**按间隔采样**(50–1000ms),页面静止也能出帧,适合"精确像素/颜色等值"。
|
|
50
|
+
- 不够长用 `action:"extend", durationMs`(单次 ≤60000、累计 ≤300000ms,仅 `running` 有效)。
|
|
51
|
+
|
|
52
|
+
### Step 1 · 定位动画区域(两种来源,任选)
|
|
53
|
+
|
|
54
|
+
**A. 纯像素(推荐,不需要 DOM)**
|
|
55
|
+
|
|
56
|
+
```text
|
|
57
|
+
browser_motion_analyze { motionSessionId, frameIds:[<少量帧>],
|
|
58
|
+
assertions:[{ id:"where", type:"region-change",
|
|
59
|
+
thresholds:{ pixelThreshold:0.1, changeRatio:0.005, minArea:300 } }] }
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
返回 `regions[]`:`{region:{x,y,width,height}, area}` —— "哪块在动",坐标是**帧图像像素**。
|
|
63
|
+
|
|
64
|
+
**B. DOM 辅助(需要精确到元素时)**
|
|
65
|
+
|
|
66
|
+
```text
|
|
67
|
+
browser_snapshot / browser_node_state → 元素 bbox(CSS px)
|
|
68
|
+
换算:imagePx = (cssPx − originCss) × cssPerPixel # 见帧的 mapping
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
### Step 2 · 收窄 + 抽帧(把成本压下来)
|
|
72
|
+
|
|
73
|
+
```text
|
|
74
|
+
browser_motion_analyze { motionSessionId,
|
|
75
|
+
frameIds:[<6–10 个跨时间点的 frameId>], // 关键:别用全序列
|
|
76
|
+
assertions:[{ id:"in-panel", type:"frame-diff", region:{x,y,width,height} }] }
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
- 帧要**跨时间分布**(如 t≈250 / 1500 / 2700ms),否则看不出运动方向。
|
|
80
|
+
- 每个断言都回 `resolvedThresholds` / `sampleCount` / `limitations` —— 判读要看这些,不要只看 `verdict`。
|
|
81
|
+
|
|
82
|
+
### Step 3 · 判定(七类断言,按问题选)
|
|
83
|
+
|
|
84
|
+
| 你的问题 | 断言 | 必给参数 | 通过条件 |
|
|
85
|
+
| --- | --- | --- | --- |
|
|
86
|
+
| 两块/两帧差多少 | `frame-diff` | — | 未达 `changeRatio` → PASS |
|
|
87
|
+
| 哪里变了、面积多大 | `region-change` | — | 未检出区域 → PASS |
|
|
88
|
+
| 闪一下又回来 | `flicker` | — | A→B→A 三帧 + `changeRatio≥0.2` + `brightnessDelta≥64` 才算检出 |
|
|
89
|
+
| 卡住/冻结 | `freeze` | **`expectation`** | 必须给可核验"预期应动"声明 + 独立推进旁证 + ≥3 次复核 |
|
|
90
|
+
| 掉帧/卡顿 | `jank` | **`expectedIntervalMs`** | 间隔 > `expectedIntervalMs × intervalFactor` 为怀疑 |
|
|
91
|
+
| 目标往哪走、是否连续 | `trajectory` | **`query`**(color/template) | 唯一且连续 → PASS;歧义 → INCONCLUSIVE |
|
|
92
|
+
| 过渡从哪开始、多长 | `transition` | — | 首次越阈值 + 连续 `stableSamples` 次稳定 → PASS |
|
|
93
|
+
|
|
94
|
+
### Step 4 · 只看那一块(crop-on-delivery)
|
|
95
|
+
|
|
96
|
+
```text
|
|
97
|
+
browser_motion_observe { motionSessionId, frameIds:[...], includeImages:true,
|
|
98
|
+
region:{x,y,width,height} } // 只交付这块;不带 region 则整帧 JPEG
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
- 带 `region` → 返回**裁剪后 PNG**(`mediaType:"image/png"`、尺寸=region),并附 `crop:{region, sourceSha256, sourceDimensions, sourceEncoding, roiSha256, outputBytes}`。
|
|
102
|
+
- `roiSha256` 是**裁剪后像素**的 hash,与整帧 `encodedSha256` **不是一回事**,别互相冒充。
|
|
103
|
+
- 越界 / 只给 `region` 不给 `includeImages` → `DYNAMIC_INVALID_ARGUMENT`(不静默 clamp)。
|
|
104
|
+
- 解码失败不抛错:该帧不给图 + `crop.failed:true` + `incomplete:["crop-unavailable"]`。
|
|
105
|
+
- 需要遮挡(游标/水印)才用 `analyze` 的 `masks`;`observe` 不带 masks。
|
|
106
|
+
|
|
107
|
+
### Step 5 · 消融实验(把"相关"变成"因果")
|
|
108
|
+
|
|
109
|
+
```text
|
|
110
|
+
browser_motion_control { motionSessionId, action:"pause",
|
|
111
|
+
adapterId:"waapi", targetIds:["<selector 或 animation.id>"] }
|
|
112
|
+
→ observe { region } 看哪块停了 / 哪块还在动
|
|
113
|
+
→ browser_motion_control { action:"restore", restoreToken }
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
- `targetIds` 来自 **T2**(DOM selector / animation id)——T4 只做像素观测,不做 DOM 定位。
|
|
117
|
+
- 会话到期或 `reset` 会尽力恢复(`restoreStatus` / `restores[]`),但**显式 `restore` 才可预期**。
|
|
118
|
+
- 只有 `pause/seek` 后**画面区域真的变化/停止**,才能说"这块由这个适配器驱动"。
|
|
119
|
+
|
|
120
|
+
### Step 6 · 跨域关联
|
|
121
|
+
|
|
122
|
+
```text
|
|
123
|
+
browser_network_session { action:"start" } # 需要网络侧时
|
|
124
|
+
browser_dynamic_correlate { dynamicSessionId, motionSessionId, networkSessionId,
|
|
125
|
+
directions:["operation->visual","network->visual"] }
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
- `explicit` / `redirect` / `initiator` 才是 **confirmed-causal**;`observed` 只是关联;`temporal` 默认**不返回**。
|
|
129
|
+
- 页面 `ui.cause` / `causeOpId` 是**声明证据**,须另有独立旁证(真实 response/WS 事件、DOM 回读、帧像素)才能升级。
|
|
130
|
+
- 没有共同 ID 或协议父端点 → 只能 `unresolved`。别把"时间挨得近"写成因果。
|
|
131
|
+
|
|
132
|
+
## 3. 判读红线
|
|
133
|
+
|
|
134
|
+
| 情况 | 必须报 |
|
|
135
|
+
| --- | --- |
|
|
136
|
+
| 缺帧、解码失败、时钟不可比、几何不兼容 | `INCONCLUSIVE` / `BLOCKED` + `reasons` / `incomplete` |
|
|
137
|
+
| 采样窗口内没出现异常 | "采样不足",**不是** "无异常" |
|
|
138
|
+
| 帧被淘汰/丢帧/截断 | 看 `dropped/evicted/truncated/gaps/ackFailures` 并写进结论 |
|
|
139
|
+
| 只有 JPEG 帧 | `precise:false` + `limitations:["jpeg-compression-noise"]`;精确等值改用 `screenshot-loop` |
|
|
140
|
+
| 关联只有 `observed` | 写"关联",**不写"因果"** |
|
|
141
|
+
|
|
142
|
+
## 4. 常见失败与恢复
|
|
143
|
+
|
|
144
|
+
| 现象 | 原因 | 怎么做 |
|
|
145
|
+
| --- | --- | --- |
|
|
146
|
+
| `BLOCKED(dynamic-timeout)` + `budget-exhausted` | 帧太多,纯 JS 解码超 5s | 用 `frameIds` 抽 6–10 帧,或收窄 `window` |
|
|
147
|
+
| `regionsTruncated:true` | JPEG 噪声碎出上百小区 | 提高 `minArea`(≥300),或先用 `region` 收窄 |
|
|
148
|
+
| `issues:["no-damage-frames"]`、`captured:0` | 页面静止(damage 驱动) | 换 `source:"screenshot-loop"`,或先让页面动起来 |
|
|
149
|
+
| `DYNAMIC_SESSION_NOT_ACTIVE` | 会话已到期/已停,`extend` 不复活 | 重新 `start`(`durationMs` 给足) |
|
|
150
|
+
| `DYNAMIC_CONTROL_CONFLICT` | 页面代次/目标变了,或外部改了同一字段 | 重新定位目标,别强行覆盖 |
|
|
151
|
+
| `DYNAMIC_LIMIT_EXCEEDED{sessionCapMs}` | 累计会话时长到 300000ms | 收新会话 |
|
|
152
|
+
| `crop.failed` / `crop-unavailable` | 该帧解码失败 | 跳过该帧;结论用其它帧,否则 `INCONCLUSIVE` |
|
|
153
|
+
|
|
154
|
+
## 5. 成本参考(实测,1024×768)
|
|
155
|
+
|
|
156
|
+
| 操作 | 耗时 / 体积 |
|
|
157
|
+
| --- | --- |
|
|
158
|
+
| 6 帧 `region-change` | **883ms** |
|
|
159
|
+
| 176 帧 `frame-diff` 全序列 | **20.5s → BLOCKED** |
|
|
160
|
+
| 整帧 JPEG 交付 | **61,824 B/帧** |
|
|
161
|
+
| 裁 243×139 交付 PNG | **4,198 B/帧(14.7× 缩小)** |
|
|
162
|
+
| screencast 采集密度 | 实测相邻帧 ~16ms;60s 会话 3517 帧、`ackFailures:0` |
|
|
163
|
+
|
|
164
|
+
## 6. 交付要求
|
|
165
|
+
|
|
166
|
+
每次 T4 结论至少带:`dynamicSessionId` / `motionSessionId`、时间窗口或 `frameIds`、`verdict` 与 `resolvedThresholds`、`integrity`(含 dropped/evicted/truncated)、证据引用(frameId / `roiSha256` / 图片路径或交付方式)。**
|
|
167
|
+
|
|
168
|
+
## 7. T3 静态侧的边界(本节保留)
|
|
169
|
+
|
|
170
|
+
`browser_screenshot` 可保留 PNG base64 并经可选附件服务 render image block;缺服务为 base64-fallback 文本,provider 可见性需另验。P0 截图支持显式 `scale` 0.1–4(省略跟随共享 `view.scale`)/ 画布 CSS `region` / PNG 校验;`includeAnnotations?:boolean=false` 为 true 时按相同 region/scale 叠加 Host 已接受的六种面板形状,不含未提交草稿/工具栏,证据见 `capture.annotations`。默认截图、T3 原始源及 T4 两种帧源不含面板标注;`persist` 默认 false(暂存,dispose 清理),`out`/`persist:true`/非空 env 才持久。`file.pathKind`/`persistence`/`root`/`ephemeral` 必须随证据记录,`observed` 不含绝对路径;**暂存不能当持久引用**。原始图像可见性不等于像素差异/基线阈值/VLM 管线;不能把"截图动作成功"判成视觉 PASS。定量视觉条件缺证据时一律 `BLOCKED`/`INCONCLUSIVE`。
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
# T1 · 程序化接口(M0–M2)
|
|
2
|
+
|
|
3
|
+
T1 共 10 个工具(含独立 HTTP `browser_http_request` 与共享视口 `browser_viewport`)。注册表决定可调用名字,`browser_capabilities` 报真实运行态三态;静态工程状态不能当 available。详细返回见 [操作契约](../contracts/operation.md)。
|
|
4
|
+
|
|
5
|
+
| 操作 | 工具 | 关键边界 |
|
|
6
|
+
| --- | --- | --- |
|
|
7
|
+
| 导航 | browser_navigate | errorText/最终 URL/目标与 DNS/Document 重定向校验,不保证 load complete |
|
|
8
|
+
| JS | browser_eval | 顶层主世界,可序列化值;页面异常 error 对象含描述/栈/位置 |
|
|
9
|
+
| 截图 | browser_screenshot | P0:显式 scale 0.1–4(省略时跟随共享 view.scale,cold 1)、region画布CSS px、includeAnnotations?:boolean=false、out相对.png;true 按同一 region/scale 叠加 Host 已接受的六形状,不含草稿/工具栏,证据 capture.annotations;默认截图与 T3/T4 原始源不含面板标注;PNG CRC/尺寸/全量均匀统计、JSON mapping、安全落盘与附件metadata证据;保留base64/附件fallback;provider另验,无T3分析 |
|
|
10
|
+
| 共享视口 | browser_viewport | `action:"get"`=只读缓存诊断(不启动/不发 CDP/不占租约,`stale` 明示);`action:"set"`=页面操作(宽高才发 metrics override,scale-only 不改页面几何);`x/y` 为文档 CSS 滚动位置实测,宽高 200–4096 整数,scale 0.1–2(也是省略 scale 的截图默认密度),`expectedRevision` → `VIEWPORT_CONFLICT` 零应用 |
|
|
11
|
+
| 输入 | browser_input | applied 是数量,不证明生效;支持 modifiers(数组或 CDP 位掩码)、key 的 virtualKeyCode/autoRepeat 等、mouse 的 buttons/pointerType。**有按键状态机**:`keyDown` 记位、`keyUp` 清位,按住 Shift 后其它事件自动带位(要复现"没带位"的坏行为用 `synthesizeModifiers:false`);`mouse` 给 `deltaX/deltaY` 就是相对移动(虚拟光标,clamp 在视口内);返回 `held` 可核对残留按键,导航会清空。无焦点管理工具与高层动作 |
|
|
12
|
+
| 网络(旧工具) | browser_network | 响应与 loadingFailed 元数据、URL 脱敏、有界 300 条;**无头/正文**;其他 owner BUSY。深度采集/控制看下一条 |
|
|
13
|
+
| 网络(P0 七工具) | browser_network_session · events · detail · trace · control · evidence · subscribe | `action` 必填;HTTP/HTTPS 请求响应与头/体(按需、配额截断、读不到 `available:false`)、WebSocket 双向帧、SSE、same-origin iframe/OOPIF/Worker、统一时间轴与分析聚合、业务步骤链路、拦截/限速/断连/重放/Mock、JSONL+HAR 与多 Agent 独立订阅;只读/诊断不启动浏览器,`session.start` 与需 page 的 `control` 才懒启动;`G1.5` partial(same-origin iframe + dedicated worker 已实证;OOPIF partial;shared/service worker 不采集)、HTTPS 未独立验收(`limits.network.https="mechanism-identical"`)、`responseModification` 条件支持、真实宿主上的行为需单独证据|
|
|
14
|
+
| CSSOM | browser_computed_style | 首匹配,未命中 error 对象;无伪元素/iframe/Shadow DOM 内部定位 |
|
|
15
|
+
| 状态 | browser_state | document.title 刷新与 owner 诊断,不启动/不占租约;error/errorAt/errorActionId/errorTarget 由成功页面操作清空 |
|
|
16
|
+
| 独立 HTTP | browser_http_request | Host HTTP(S) 客户端:不启动浏览器/不占租约;默认 GET、5s 总超时、64KiB 保留上限、不跟随重定向;每跳复验目标、无 cookie jar、新错误码 HTTP_TIMEOUT/HTTP_FAILED/HTTP_REDIRECT_LIMIT;`ok:true` 非 2xx |
|
|
17
|
+
| 能力 | browser_capabilities | 实际 available/unavailable/unsupported 与原因限制,不启动/不占租约;按段报 T1/T2(7+1)/T3(6+1)/network(7+1,聚合 `web.network.p0`,含必报标量 `limits.network.https:"mechanism-identical"` 与并列的 `responseModification` 实测值),并报 `limits.structuredGui`、`vision`/`limits.vision`、`network`/`limits.network`、`dynamic`/`limits.dynamic` |
|
|
18
|
+
|
|
19
|
+
同一时刻一个无头 Chromium/profile;每个 DSH 工作区一个 page。single-owner-lease 按工作区,15s idle、进行中保持、缺 exec 走 legacy、disposed 只释放对应 owner。页面操作与 network(含 network P0 的 session/control 变更)受同工作区租约,network P0 只读/离线动作不加租约;state/capabilities 可诊断。同工作区页面工具与面板同串行队列;已发 CDP 命令后 abort 先关闭该 page 再放锁,后续可懒启动。Cookie/存储共享,非安全隔离。
|
|
20
|
+
|
|
21
|
+
默认视口1280×800/受控DSF1,共享视口由 `browser_viewport` 读写;P0 scale不改viewport/DSF,输出round(css×scale)且≤16M像素。region为画布坐标(O=0时同文档),T2 bbox/输入为视口坐标,按scroll转换。页面DPR读取失败null、headlessSource依据product/userAgent;capture JSON mapping不返回函数。persist:boolean默认false;默认staging(包括legacy无cwd)绝对路径/0600/no-clobber/dispose清理,out/persist:true/非空env才persistent相对路径;file含pathKind/persistence/root/ephemeral,observed不含绝对路径;持久无根报root_unknown、tmp失败仅warning。安全规则见 [安全边界](../core/safety.md);observed不启动、只代表上次真实截图。页面工具可懒启动,network/state/capabilities 不启动。CDP 超时、断连和取消有分类错误,pending timers 清理;close 清空网络/请求/URL/标题/帧并清进程/profile。
|
|
22
|
+
|
|
23
|
+
安全策略见 [安全边界](../core/safety.md):loopback 允许,RFC1918 默认阻断,可显式环境变量开放;Document/DNS/最终 URL 校验不等于对子资源/页面 fetch/WebSocket 的完整网络沙箱,仍有 rebinding 风险。
|
|
24
|
+
|
|
25
|
+
所有工具 action 元数据进入 render;操作成功与断言分离。网络元数据不证明完整接口契约(接口契约用 `browser_http_request`),CSSOM 不证明视觉,原始截图可见不等于已得到 T3/T4 结论。元素语义与元素级交互优先走 T2(`browser_snapshot`/`browser_click`/`browser_type`/`browser_fill_form`/`browser_wait_for`,见 [T2 表](t2-structured.md));下载/上传/Cookie 导出、多 target/frame(iframe 内部)选择仍不支持;运行态以 `browser_capabilities` 与实际调用为准。
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
# T2 · 结构化 GUI
|
|
2
|
+
|
|
3
|
+
**实现状态:已实现(7 个工具)。** 权威契约是 `docs/t2-structured-gui.md`;能力 id 为 `web.t2.snapshot/click/type/scroll/fill_form/node_state/wait_for`,聚合项 `web.t2.structured-dom`。运行态以 `browser_capabilities` 与真实调用结果为准,本文与 manifest 都不是可用性证明。
|
|
4
|
+
|
|
5
|
+
## 能力(已实现)
|
|
6
|
+
|
|
7
|
+
| 能力 | 工具 | 说明 |
|
|
8
|
+
| --- | --- | --- |
|
|
9
|
+
| 语义快照 | `browser_snapshot` | 主 frame AX 树 → 缩进文本树 + `refs` 表;`maxNodes`/`depth`/`boxes` 可控;`snapshotId`(`s1`、`s2`…)、`digest=sha256(tree)` 前 16 位、`truncationReasons`、`coverage{frame:'main',shadow:'ax-backed'}` |
|
|
10
|
+
| 定位与点击 | `browser_click` | `ref`/`selector` 恰一;滚动进视口 + 两帧稳定 + 命中校验后派发 CDP 真实鼠标事件;支持 button/clickCount/modifiers |
|
|
11
|
+
| 文本输入 | `browser_type` | 原生 `input[type=text|search|email|url|tel|password]` 与 `textarea`;replace/append、可选 Enter 提交;焦点与值双重校验 |
|
|
12
|
+
| 滚动 | `browser_scroll` | `direction`(wheel,`cdp-input`)或 `to:top|bottom`(精确 `scrollTo`,`dom-scroll`);返回 before/after/moved |
|
|
13
|
+
| 表单批处理 | `browser_fill_form` | 1–20 项,`type` = textbox/checkbox/radio/combobox/slider;整批预检后再执行,部分生效不回滚 |
|
|
14
|
+
| 节点状态 | `browser_node_state` | 现场读 NodeState(可见/启用/只读/勾选/焦点/bbox/hitTarget/滚动…),可编辑值脱敏 |
|
|
15
|
+
| 条件等待 | `browser_wait_for` | text / textGone / 目标 state(visible、enabled、checked、valueEquals,多 key 为 AND);超时抛 `WAIT_TIMEOUT` |
|
|
16
|
+
|
|
17
|
+
组合出的交互流程:`snapshot → ref/selector → 动作 → before/after 证据 → wait_for/node_state → 页面真值断言`。派发成功与业务断言分开记录,没有自动 PASS 字段。
|
|
18
|
+
|
|
19
|
+
## 交付条件
|
|
20
|
+
|
|
21
|
+
- **注册面**:7 个工具经既有 `register()` 注册,目标用字符串 `ref`/`selector`(无 Target 对象),共用 action envelope 与 lossless JSON 投影。
|
|
22
|
+
- **语义来源**:`Accessibility.getFullAXTree`(主 frame)+ `DOM.describeNode/resolveNode` + `Runtime.callFunctionOn` 做身份校验;几何用 rect/quads/命中测试;输入用 `Input.dispatchMouseEvent/dispatchKeyEvent/insertText`。
|
|
23
|
+
- **可信输入**:click/type/textbox/checkbox/radio 走 CDP 输入事件;只有 combobox/slider 用原生 setter(`eventSource=dom-control`,不声称 isTrusted)。
|
|
24
|
+
- **证据**:version=1 evidence(provenance/targets/before/after/dispatch/networkDelta/escalation/incomplete),成功在 `result.evidence`,失败在 `BrowserError.details.evidence`。
|
|
25
|
+
- **错误**:`REF_STALE`/`TARGET_NOT_FOUND`/`TARGET_NOT_UNIQUE`/`NOT_INTERACTABLE`/`WAIT_TIMEOUT`/`INVALID_ARGUMENT` 全部抛错(不再走 T1 legacy `{ok:false,error}`)。
|
|
26
|
+
- **零依赖**:只用现有 CDP 与 Node 内建库,不引入 Playwright/Puppeteer;不改面板视觉。
|
|
27
|
+
`declared-capabilities.json` tier 为 `T1+T2+T3+T4`,`unsupported_tiers` 为空。
|
|
28
|
+
|
|
29
|
+
## 压缩与滚动行为(契约 §3.1/§4.3)
|
|
30
|
+
|
|
31
|
+
**快照压缩(§3.1 第 1 条)**:内容命名 owner(heading/button/link,且 name 确实来自其 contents)的纯文本重复链只保留一份;`aria-label`/`aria-labelledby`/外部 `label` 命名的 owner 不吞子文本;`StaticText → InlineTextBox` 单链只留一份,多片 InlineTextBox 不逐片全局去重;换行/空格不做有损 normalize。压缩在 emit / `nodeCount` / 字节预算**之前**完成,被合并的表示不计入 truncation。同名 sibling、不同 role 父子、`listitem`/`tablecell`/`iframe`/`image`/`canvas`、任何 frame/shadow 边界一律保留。
|
|
32
|
+
|
|
33
|
+
内联片段分隔符投影为单行 `- text " "`;不可交互的非语义 `generic` 包装不分配 ref(含 `contenteditable` generic → 用显式 selector 查状态;`role=textbox` 的自定义控件不受影响)。
|
|
34
|
+
|
|
35
|
+
**实测(同 `/web-t2.html`、默认参数)**:`nodeCount` 421→275(−34.7%)、tree UTF-8 14432→9254(−35.9%)、`- text` 行 232→91;两次连续捕获 `tree/digest` 一致。`nodeCount`/`digest` 是构建相关读数,跨构建变化不算回归。
|
|
36
|
+
|
|
37
|
+
**滚动硬门禁(§4.3)**:`direction` 与 `to` 都**不自动滚入视口**;派发前校验 visible / 两帧稳定(bbox 四项差 ≤1 CSS px)/ 视口交集 / 中心命中 / 轴有滚动范围,不满足零派发 `NOT_INTERACTABLE`(`outside-viewport`|`unstable`)+ 固定无 selector 的 `details.hint`;失败前后页面与元素 scroll 读数进 evidence。恢复:先无目标滚文档 → `browser_node_state` 确认 `inViewport` → 带目标重试;持续运动属 T4,不换点、不 force。
|
|
38
|
+
|
|
39
|
+
## 仍然存在的限制
|
|
40
|
+
|
|
41
|
+
- **主 frame only**:same-origin iframe 也只显示边界叶子,cross-origin/OOPIF 不遍历、不查内部 selector、不产生内部 ref;动作不能送入 iframe 内部。跨帧需要 renderer `sessionId`+`frameId`+`documentEpoch` 联合身份;当前不支持跨帧操作。
|
|
42
|
+
- **shadow**:只支持 open shadow 的 AX-backed ref;CSS 不穿透 shadow root;closed shadow 或无 backend 身份时拒绝,不落到相似节点。
|
|
43
|
+
- **定位**:selector 仅原生 CSS、仅主文档、必须唯一;无 XPath/文本 DSL/`getByRole`/`getByText`/Locator;不自动推导 CSS locator。
|
|
44
|
+
- **无 force / 无 JS click / 无 hover 工具**;overlay 命中失败即动作失败,不搜索其它点击点。
|
|
45
|
+
- **表单**:`combobox` 按 `option.value` 精确匹配、**不打开原生 select popup**;`slider` 用原生 setter、**不模拟拖拽**;自定义 ARIA combobox/slider 不接受。结构赋值不能替代 popup / 拖拽手势测试。
|
|
46
|
+
- **输入**:不承诺 IME/composition 与逐字符 keydown;contenteditable/富文本编辑器、`number`/`date`/`file`/`hidden` 抛 `UNSUPPORTED`。
|
|
47
|
+
- **不做**:上传/下载、drag/drop、文件选择器、JSDialog 管理、Agent 多标签/popup 目标选择(GUI 内部标签页已支持)、触摸、截图 diff、独立证据文件包。
|
|
48
|
+
- **视觉归类**:hit-test 只证明当前坐标命中;颜色、可读性、遮挡成因、canvas/WebGL 文字等属 T3(`browser_vision_image`/`compare`);动画/时序属 T4(`browser_dynamic_session` + `motion_analyze`)。两者均已实现。
|
|
49
|
+
|
|
50
|
+
## 不要用旧层级冒充 T2
|
|
51
|
+
|
|
52
|
+
`browser_eval` 里的 `document.querySelector(...)`、读 DOM 属性、`element.click()` 仍然只是**页面 JS 状态/页面内合成事件**:没有节点身份、没有可信派发、没有 before/after 证据,也不能证明 ARIA role/name 或命中正确。T2 工具缺失或抛 `UNSUPPORTED` 时才回落到 T1,并如实说明回落理由与证据强度差异——**不得**用 T1 结果声称结构化语义已通过。
|
|
53
|
+
|
|
54
|
+
## 验收门槛
|
|
55
|
+
|
|
56
|
+
覆盖注册面、冷启动能力、工作区隔离、快照、ref 生命周期(含 LRU 与跨快照保留)、唯一 selector、可信动作、表单、滚动、等待、错误码、证据、租约、取消。
|
|
57
|
+
2. 能力状态声明见 `manifests/declared-capabilities.json`。
|
|
58
|
+
|
|
59
|
+
4. ✅ `browser_capabilities` 按 §5.3 报 `limits.structuredGui`(C2 required 检查通过)。
|
|
60
|
+
|
|
61
|
+
因此 7 个 T2 工具与聚合项记 `verified`;真实宿主会话已补齐,**仅剩 provider 图像可见性(T1 遗留)与仅 advisory 覆盖的 closed-shadow「不产生 ref」细分未验证**。不要把 verified 外推到跨帧、视觉(T3/T4)或 provider 图像可见性。
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
# T3 · 静态视觉
|
|
2
|
+
|
|
3
|
+
> 权威契约:[`docs/t3-vision.md`](../../../../docs/t3-vision.md)。本文件是已实现能力的操作摘要,字段、边界与验收口径以契约为准。
|
|
4
|
+
|
|
5
|
+
## 已实现的六个工具(当前工具面 37 = 10 T1 + 1 P0-E + 1 P0-D + 7 T2 + 6 T3 + 7 network + 5 T4)
|
|
6
|
+
|
|
7
|
+
| 工具 | 用途 | 关键边界 |
|
|
8
|
+
| --- | --- | --- |
|
|
9
|
+
| `browser_vision_image` | 采集/裁剪/缩放/预处理/统计/可选识别/像素标注,交付一张 PNG | 顺序固定 source→region→resize→preprocess→统计/识别→标注→编码/交付;分析与识别在标注前;无断言 `INCONCLUSIVE(no-assertion)` |
|
|
10
|
+
| `browser_vision_find` | 确定性识别与定位(color/components/edges/template) | 坐标相对完整源图(ROI 原点已回加),`semanticName` 恒 null;无匹配是成功空列表 |
|
|
11
|
+
| `browser_vision_compare` | 两图 YIQ 像素差异 + 标注差异 PNG | 两图必须同尺寸;mask/options/thresholds 继承 before 基线并可覆盖;全屏蔽 `VISION_EMPTY_COMPARISON` |
|
|
12
|
+
| `browser_vision_act` | 用截图坐标派发真实 CDP 鼠标输入 | 六步安全校验(现场几何/重采样 RGBA hash/视口/命中+两帧稳定/CDP 派发/finally 释放),失败零派发;verdict 恒 `INCONCLUSIVE(dispatch-only)` |
|
|
13
|
+
| `browser_vision_baseline` | 受管基线 list/get/create/update/delete | 可信持久根 + scopeHash 隔离;不可变 revision + HEAD CAS;delete 为墓碑;离线操作不启动浏览器 |
|
|
14
|
+
| `browser_vision_check` | 回归 + 六类缺陷用例集 | cases 1–20 / assertions 1–32 / facts 0–64;required 缺事实=INCONCLUSIVE、advisory 最多 WARN;不发布文件、不读 DOM、不建基线 |
|
|
15
|
+
|
|
16
|
+
## 证据口径(`evidence.vision.version=1`)
|
|
17
|
+
|
|
18
|
+
- 成功业务体 `{ok:true,...,evidence:{vision:…}}`;失败抛 `BrowserError`,完整证据在 `details.evidence.vision`。
|
|
19
|
+
- 字段:`version/operation/provenance(algorithmVersion=t3-v1)/source/coordinateSpace/regions/metrics/baseline/facts/verdict/dispatch/output/escalation/incomplete/truncated`(全部必填,未观察项 null,非适用列表 [])。
|
|
20
|
+
- `evidence` JSON ≤262144 字节、`regions`≤100;超限标 `truncated` 并只丢可选细节;截断会丢失 required 判断依据时 PASS 降 INCONCLUSIVE。
|
|
21
|
+
- `ok:true` 只表示工具完成,`verdict` 才是断言结论;截图成功、识别到候选、坐标已派发都不等于视觉验收通过。
|
|
22
|
+
- `facts` 一律 `trusted:false`:T3 不重新查询 DOM,只融合调用方显式提供的、带 provenance 的几何/样式事实。
|
|
23
|
+
|
|
24
|
+
## 三个坐标空间
|
|
25
|
+
|
|
26
|
+
`image-px`(PNG 实际像素,T3 region/mask/annotation/find/act 默认)→ `document-css-px`(live source.region、外部 facts、基线 mapping)→ `viewport-css-px`(CDP Input,document 减现场 scroll)。`act.point` 是连续图像坐标:像素中心请传 `i+0.5`,不自动取整、不加 0.5。
|
|
27
|
+
|
|
28
|
+
## 新增错误(§3.3,分类固定)
|
|
29
|
+
|
|
30
|
+
`VISION_SOURCE_NOT_FOUND` / `VISION_FORMAT_UNSUPPORTED` / `VISION_SIZE_MISMATCH` / `VISION_EMPTY_COMPARISON` / `VISION_BASELINE_NOT_FOUND`(vision);`VISION_LIMIT_EXCEEDED`(resource);`VISION_TIMEOUT`(timeout/retryable);`VISION_STALE_IMAGE` / `VISION_HIT_MISMATCH`(action);`VISION_BASELINE_ROOT_UNAVAILABLE` / `VISION_BASELINE_EXISTS` / `VISION_BASELINE_READ_FAILED` / `VISION_BASELINE_WRITE_FAILED`(output);`VISION_BASELINE_NAME_INVALID`(input);`VISION_BASELINE_CONFLICT`(concurrency)。原有 `ABORTED/CDP_TIMEOUT/CDP_DISCONNECTED/BUSY/scope/INVALID_ARGUMENT/INVALID_PNG/CAPTURE_*/OUTPUT_*` 分类不变。
|
|
31
|
+
|
|
32
|
+
## 不被支持 / 不可外推的保证
|
|
33
|
+
|
|
34
|
+
无 VLM/OCR/语义命名;不接受任意图片路径/URL/附件 ID/调用方 base64;不跨 frame 坐标输入;不跨重启恢复 product;无自动基线接受/更新、无自动阈值学习、无自动动态 mask;无图像配准/透视/旋转/模板缩放;无 SSIM/感知模型;无动画时序与「无中间闪烁」保证。canvas/WebGL 只对最终像素可识别,不能推断内部对象或语义。像素相等只支持指定区域/分辨率/时间/阈值下的相等。
|
|
35
|
+
|
|
36
|
+
## 与 T1/T2 的关系
|
|
37
|
+
|
|
38
|
+
`browser_screenshot` 是 PNG 采集(P0),不隐式产生 productId;它的 `includeAnnotations?:boolean=false` 仅控制本次截图叠加 Host 已接受的面板标注,T3 原始源不含面板标注,T3 `annotations` 是独立的图片后处理标记;要用同一画面做视觉分析,先 `browser_vision_image` 取得 product。T2 负责语义元素与可交互目标;T3 的 `act` 用当前截图里的顶层命中点,不是“知道调用者想要哪个 DOM 对象”,也不是 T2 `NOT_INTERACTABLE` 的 force 逃生口。`escalation:"T3"` 只提示需要视觉分析;`escalation:"T4"` 提示需要连续帧证据(持续运动)。
|
|
39
|
+
|
|
40
|
+
## 结论边界
|
|
41
|
+
|
|
42
|
+
- 结论只对指定源图、区域、分辨率与阈值负责;`ok:true`、截图成功、识别到候选、坐标已派发都不等于视觉验收通过。
|
|
43
|
+
- `INCONCLUSIVE`/`BLOCKED` 必须原样报告,不能降级成 PASS;`advisory` 事实最多给 `WARN`。
|
|
44
|
+
- 3 条 N/A 子项(DOM 小数/Blink 截断、inert 命中、页面级 downs/ups)以 reason 说明,不计入 PASS。
|
|
45
|
+
- 真实宿主加载与 provider 图像可见性需要单独证据。
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
# T4 · 动态行为
|
|
2
|
+
|
|
3
|
+
**实现状态:已实现并注册 5 个工具。** 44 条门槛中 12 条通过、20 条部分通过、12 条未运行,未运行项不得写成通过。权威契约:[T4 契约](../../../../docs/t4-dynamic-behavior.md)。
|
|
4
|
+
|
|
5
|
+
## 能用什么
|
|
6
|
+
|
|
7
|
+
| 能力 | 工具 | 说明 |
|
|
8
|
+
| --- | --- | --- |
|
|
9
|
+
| 连续帧采集 / 续约 | `browser_dynamic_session` | `source:"screencast"` 共享预览 JPEG 流(唯一协调器、唯一 ACK、有界存储、dropped/evicted 计数);`source:"screenshot-loop"` PNG 精确采样(50–1000ms,单飞,真实采样区间) |
|
|
10
|
+
| 时间轴查询 | `browser_motion_observe` | 帧/事件只读查询、`fresh` 显式采样、**`region` crop-on-delivery(只看动画那一块)**;只读不 ensure、不续租 |
|
|
11
|
+
| 运动分析 | `browser_motion_analyze` | `frame-diff` / `region-change` / `flicker` / `freeze` / `jank` / `trajectory` / `transition`,确定性阈值 + `resolvedThresholds` + limitations |
|
|
12
|
+
| 时间控制 | `browser_motion_control` | WAAPI `pause/resume/seek/rate/restore`,逐目标回读,`restoreToken`,部分应用与恢复状态如实报告 |
|
|
13
|
+
| 事件关联 | `browser_dynamic_correlate` | 六向关联,`explicit/redirect/initiator`=confirmed-causal,`observed`=关联,`temporal` 默认过滤,输出 pairs/unresolved/suppressedTemporal/integrity |
|
|
14
|
+
|
|
15
|
+
动态网络(DN)继续复用 7 个 `browser_network_*`(HTTP/WS/SSE/轮询/重放/证据/订阅),**没有第二套抓包 API**。
|
|
16
|
+
|
|
17
|
+
## 怎么用(最短路径)
|
|
18
|
+
|
|
19
|
+
```text
|
|
20
|
+
1) browser_dynamic_session { action:"start", config:{ captureVisual:true, source:"screencast", durationMs:3000 } }
|
|
21
|
+
→ { dynamicSessionId, motionSessionId }
|
|
22
|
+
2) 执行被测动作(browser_click / 页面 __t4 方法 / 导航)
|
|
23
|
+
3) browser_motion_observe { motionSessionId, sinceSeq:0, limit:50 } # 帧元数据 + 事件
|
|
24
|
+
4) browser_motion_analyze { motionSessionId, window:{fromMs,toMs},
|
|
25
|
+
assertions:[{ id:"a1", type:"jank", expectedIntervalMs:16, thresholds:{ intervalFactor:2 } }] }
|
|
26
|
+
→ verdict/exitCode/summary;证据不足是 INCONCLUSIVE/BLOCKED,不是 PASS
|
|
27
|
+
5) 需要精确像素:另起 source:"screenshot-loop"(PNG,precise=true)再 analyze
|
|
28
|
+
6) 需要控制:browser_motion_control { motionSessionId, action:"pause", adapterId:"waapi", targetIds:["#t4v-css-orb"] }
|
|
29
|
+
然后 action:"restore" + restoreToken 复原
|
|
30
|
+
7) 需要关联:先 browser_network_session start,再
|
|
31
|
+
browser_dynamic_correlate { dynamicSessionId, motionSessionId, networkSessionId, directions:["network-visual"] }
|
|
32
|
+
8) 分析耗时较长:browser_dynamic_session { action:"extend", durationMs:30000 } # 续约(单次≤60000、累计≤300000ms,仅 running 有效)
|
|
33
|
+
9) browser_dynamic_session { action:"stop" } # 尽力恢复本会话控制字段
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
## 三条铁律(详版方法论见 `references/scenarios/visual-motion.md`)
|
|
37
|
+
|
|
38
|
+
1. **不要用整页截图"理解动画"**:页面常把状态行(形如 `t=…ms tx=… opacity=…` 的读数)画在画面上,整页图等于泄漏答案;且整帧 JPEG 体积通常是裁剪区域 PNG 的十倍以上。先 `region-change` 定位 bbox → 再 `observe {region}` 只看这块。
|
|
39
|
+
2. **算力靠抽帧不靠 region**:JPEG 必须整帧解码;176 帧全序列 **20.5s→BLOCKED**,抽 6 帧 **883ms**。
|
|
40
|
+
3. **采样没覆盖 ≠ 没有异常**:16ms 闪白抓不到即报"采样不足",不写"无闪烁"。
|
|
41
|
+
|
|
42
|
+
## 判读规则(必须遵守)
|
|
43
|
+
|
|
44
|
+
- 帧证据:`sourceTimestamp` 是原始 CDP 秒(缺失为 `null`,**不得**用接收时刻填充);`encodedSha256` 与 `rgbaSha256` 分列,编码字节不同 ≠ 画面变化;`dropped/evicted/ackFailures/gaps/truncated` 必须计数并看。
|
|
45
|
+
- 精度:`screencast` 是 JPEG(`precise=false`,`limitations` 含 `jpeg-compression-noise`),只做粗粒度亮度/变化率判定;精确像素/颜色等值只用 `screenshot-loop` 的 PNG。解码失败 → `INCONCLUSIVE(decoder-unavailable)`。
|
|
46
|
+
- 负结论门槛:`flicker` 需要 A→B→A 三帧;`freeze` 需要可核验的「预期应动」声明 + 独立推进旁证 + ≥3 次像素复核;`jank` 的 `expectedIntervalMs` 必须显式给(不是面板 40ms 预览间隔)。**采样没覆盖到 ≠ 没有异常**。
|
|
47
|
+
- 会话生命周期:`durationMs` 默认 3000、硬上限 60000。Agent 一次工具往返约 11.7s,**多步取证必须显式给 `durationMs` 或用 `extend` 续约**;`extend` 仅对 `running` 有效(已停会话返回 `DYNAMIC_SESSION_NOT_ACTIVE`,不复活),累计 ≤300000ms,不放大帧/字节/算法预算。用 `deadlineMs`/`cumulativeMs` 判断剩余时间。
|
|
48
|
+
- 控制:只对已声明目标;`restore` 只还原本会话改过的字段;页面代次/目标变化 → `DYNAMIC_CONTROL_CONFLICT`,不覆盖外部新状态;不擅自暂停被测应用。
|
|
49
|
+
- 关联:无共同 ID 或协议父端点不得判因果;同 trace/幂等键只证明同组;页面 `ui.cause`/`causeOpId` 是声明证据,需独立旁证(真实 response/WS 事件、DOM 回读、帧像素)才可升级;跨 scope / documentEpoch 不合并。
|
|
50
|
+
|
|
51
|
+
## 未验证(不得写成可用)
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
## 不要再用旧说法
|
|
56
|
+
|
|
57
|
+
- T4 的 screencast/screenshot-loop 两种帧源均不含面板标注;`browser_screenshot {includeAnnotations:true}` 只生成带 Host 已接受标注文档的静态截图,不影响 T4 采帧。
|
|
58
|
+
- 单张 `browser_screenshot`(含带标注截图)、T3 的 before/after 两帧、面板 `/metrics` 与 `browser_eval` 读页面状态都**不是** T4 帧序列证据。
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
# 能力沉淀卡片模板
|
|
2
|
+
|
|
3
|
+
> 从本文件复制填写,不要把占位符改成未经验证的结论。状态限定为 `implemented-not-verified` / `partial` / `unsupported`;未经验收步骤回填证据前不要写 `verified`。
|
|
4
|
+
|
|
5
|
+
- ID:`<platform>.<tier>.<operation>`
|
|
6
|
+
- 名称:
|
|
7
|
+
- 状态:`implemented-not-verified` / `partial` / `unsupported`
|
|
8
|
+
- 实现代码位置(文件与行号):
|
|
9
|
+
- Agent 工具及参数(必须与注册表一致):
|
|
10
|
+
- 返回形态与失败形态:
|
|
11
|
+
- 目标平台与运行环境:
|
|
12
|
+
- 前置权限/依赖:
|
|
13
|
+
- 执行步骤:
|
|
14
|
+
- 支持能力边界:
|
|
15
|
+
- 错误分类及回退/停止条件:
|
|
16
|
+
- 副作用与幂等性:
|
|
17
|
+
- 独立验证方式:
|
|
18
|
+
- 正例测试:
|
|
19
|
+
- 负例测试:
|
|
20
|
+
- 证据(实际返回值摘要;脱敏):
|
|
21
|
+
- 最后核对日期:
|
|
22
|
+
- 已知限制:
|
|
23
|
+
- 待解决问题:
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
# <平台名> 操作手册(模板)
|
|
2
|
+
|
|
3
|
+
> 新建平台前先确认该平台有真实 Adapter、运行时能力探测与回归证据;不要照搬 Web 的 T1 技术栈假设可用性。
|
|
4
|
+
|
|
5
|
+
- 当前支持状态:未定义 / 不可用(除非已注册真实工具并有证据)
|
|
6
|
+
- Adapter/SDK:
|
|
7
|
+
- 目标会话连接与授权:
|
|
8
|
+
- 运行时能力发现方式(必须是真实接口或工具注册表):
|
|
9
|
+
|
|
10
|
+
## T1 程序化接口
|
|
11
|
+
- 能力、工具、限制、证据:
|
|
12
|
+
|
|
13
|
+
## T2 结构化 GUI
|
|
14
|
+
- 未实现时明确写“不可用”,不要保留未验证占位当作可用。
|
|
15
|
+
|
|
16
|
+
## T3 静态视觉
|
|
17
|
+
- 未实现时明确写“不可用”。
|
|
18
|
+
|
|
19
|
+
## T4 动态视觉
|
|
20
|
+
- 未实现时明确写“不可用”。
|
|
21
|
+
|
|
22
|
+
## 实际注册的工具
|
|
23
|
+
只填写当前源码真实注册、且与 Agent 工具注册表一致的工具;不要凭 SDK 文档推定。
|
|
24
|
+
|
|
25
|
+
## 验收
|
|
26
|
+
- 正例:
|
|
27
|
+
- 反例:
|
|
28
|
+
- 权限拒绝:
|
|
29
|
+
- 异常/恢复:
|
|
30
|
+
- 结果状态:NOT_RUN
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
# <测试场景名>(模板)
|
|
2
|
+
|
|
3
|
+
- 目标:
|
|
4
|
+
- 权限与测试环境:
|
|
5
|
+
- 前置状态(`browser_state` 探测结果):
|
|
6
|
+
- 可观测的验收条件:
|
|
7
|
+
- 每个断言使用的工具与参数:
|
|
8
|
+
- 同层替代与限制:
|
|
9
|
+
- 未实现能力(iframe/OOPIF 内部、closed shadow、contenteditable、原生 select popup、下载/上传等)的处理:BLOCKED / INCONCLUSIVE
|
|
10
|
+
- 副作用/清理:
|
|
11
|
+
- 证据要求(实际返回值、脱敏):
|
|
12
|
+
- 正例与负例:
|
|
13
|
+
- 结果状态:NOT_RUN
|