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,105 @@
|
|
|
1
|
+
# 判定门禁(Verdict Gate):从证据到结论的强制映射
|
|
2
|
+
|
|
3
|
+
> 触发时机:任何 case 准备写 `PASS` / `FAIL` / `BLOCKED` / `INCONCLUSIVE`,以及整份报告提交之前。
|
|
4
|
+
> 本文件只讲流程与检查项;字段模板见 [`report-template.md`](report-template.md),合成正反例见 [`verdict-examples.md`](verdict-examples.md)。
|
|
5
|
+
|
|
6
|
+
## 1. 五元组:每条断言必须成形
|
|
7
|
+
|
|
8
|
+
| 字段 | 含义 | 必须可核对的内容 |
|
|
9
|
+
| --- | --- | --- |
|
|
10
|
+
| `expected_contract` | 这条断言依据的验收条件 | 契约来源(题目/需求原文、接口文档、页面声明)+ 目标对象 + 可测的通过条件。**没有来源就不许判 PASS/FAIL**,只能写观察 + `UNKNOWN`。 |
|
|
11
|
+
| `observation` | 实际看到的原始事实 | 数值、文本、响应原文、像素差、帧间隔、DOM 读数。写事实,不写"大概/似乎/应该是"。 |
|
|
12
|
+
| `evidence_ids` | 支撑 observation 的动作证据 | `actionId`/`sessionId`、`productId`、`dynamicSessionId`+`frameIds`、`networkSessionId`+`seq`/`requestId`;截图另附 `sha256`。 |
|
|
13
|
+
| `counterexamples` | 与断言相反或被排除的观察 | 每一条都要回答两个问题:它是否真的与本断言冲突;若不冲突,凭什么排除(时间窗、对象、契约、阈值)。 |
|
|
14
|
+
| `verdict` | `PASS` / `FAIL` / `BLOCKED` / `INCONCLUSIVE` / `NOT_RUN` | 只能由前四项推出,并写一句理由。 |
|
|
15
|
+
|
|
16
|
+
三条硬规则:
|
|
17
|
+
|
|
18
|
+
1. **对象同一性**:`observation` 与 `expected_contract` 必须指向同一个页面、元素、区域和时间窗;指向另一个对象不算同一条断言。
|
|
19
|
+
2. **无 evidence 不判定**:没有 `evidence_ids` 的 observation 只是印象,不能作为 PASS 或 FAIL 的依据。
|
|
20
|
+
3. **未执行 = `NOT_RUN`**:不能计入"通过",也不能被"部分覆盖"吸收。
|
|
21
|
+
|
|
22
|
+
## 2. 提交前 6 项交叉校验
|
|
23
|
+
|
|
24
|
+
任一项未消解,**不得 PASS**;可以改判 `FAIL`、降级 `INCONCLUSIVE`,或回去补证据。
|
|
25
|
+
|
|
26
|
+
| # | 校验 | 典型不通过表现 | 处置 |
|
|
27
|
+
| --- | --- | --- | --- |
|
|
28
|
+
| 1 | **verdict ↔ observation** | `PASS` 的 observation 里含未解释的异常词:重复、重放、旧值、未变化、白色、闪烁、错位、回退、0 项、无去重、409、冲突、失败、超时 | 逐词复核:若属实且违反 `expected_contract` → 改 `FAIL`;若契约允许 → 在 `expected_contract` 写明来源并在 `counterexamples` 解释 |
|
|
29
|
+
| 2 | **verdict ↔ 缺陷清单** | 缺陷清单里有条目没有对应 `FAIL`,或 `PASS` 的 case 被写进缺陷清单 | 每条缺陷必须映射到至少一个 `FAIL`(或明确写"不构成缺陷"+ 依据);同一现象不可同时是 PASS 和缺陷 |
|
|
30
|
+
| 3 | **observation ↔ evidence** | 关键断言没有 evidence URI;或证据内容展示的不是被断言的状态(换了区域/时刻/页面) | 补采同一对象同一时刻的证据;截图要给内容特征(区域/文本/像素),不能只看文件名 |
|
|
31
|
+
| 4 | **数字 ↔ 来源** | 报告里的金额/数量/耗时来自 UI 文案或推算,而不是响应体或测量记录 | 每个数字标注来源字段与工具调用;无法取得服务端真值时写"UI 值",不得反推服务端字段 |
|
|
32
|
+
| 5 | **limitation ↔ status** | 写了"无法验证 X",该 case 仍判 `PASS` | 只能 `BLOCKED` 或标 `coverage:"partial"`,并在 `evidence_state` 说明缺什么 |
|
|
33
|
+
| 6 | **截图 ↔ 文件名/声明** | 声明的页面/登录态/视口与截图内容不一致 | 以内容为准修正声明;文件名与截图内容对不上就换名或重采,不许保留"名不副实"的证据 |
|
|
34
|
+
|
|
35
|
+
补充:`ok:true`、`dispatched:true`、`applied:N`、`verdict:INCONCLUSIVE` 本身都不是断言结论,它们只能出现在 observation 里。
|
|
36
|
+
|
|
37
|
+
## 3. 反例触发词:出现就要复核,但不能凭词判 FAIL
|
|
38
|
+
|
|
39
|
+
以下词出现在 observation 或页面文本里时,**触发一次复核**(而不是直接定性):
|
|
40
|
+
|
|
41
|
+
```text
|
|
42
|
+
重复 / 重放 / 重连 / 旧状态 / 旧值 / 未变化 / 无变化 / 白色 / 闪烁 / 错位 / 遮挡
|
|
43
|
+
回退 / 0 项 / 空列表 / 无去重 / 409 / 冲突 / 失败 / 超时 / 重试 / 丢帧 / 截断
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
复核要回答三问:
|
|
47
|
+
|
|
48
|
+
1. 这个现象发生在**哪个对象与时间窗**?是否就是本断言的对象?
|
|
49
|
+
2. 契约是否**明确允许**它(例如最终一致、幂等重放、设计上的装饰动画)?来源在哪?
|
|
50
|
+
3. 若契约不允许,它对**用户可见结果**有什么影响?能否复现?
|
|
51
|
+
|
|
52
|
+
三问都能落到证据上才写结论;落不到就写"待确认"并降级,不要用"看起来是设计"补齐。
|
|
53
|
+
|
|
54
|
+
## 4. 正例 / 反例 / 未知:三种处置
|
|
55
|
+
|
|
56
|
+
| 情形 | 处置 | 禁止 |
|
|
57
|
+
| --- | --- | --- |
|
|
58
|
+
| **正例**:证据覆盖契约要求的全部关键点,反例已被解释或排除 | `PASS` + `evidence_ids` + 反例处置说明 | 只写"看起来正常" |
|
|
59
|
+
| **反例**:证据明确违反契约,且可复现/可定位 | `FAIL` + 缺陷条目 + 最小复现步骤 | 继续找 PASS"翻案"、换目标/换阈值凑通过 |
|
|
60
|
+
| **未知**:契约不明、证据不足、能力缺失、对象身份不确定 | 观察 + `UNKNOWN`/`INCONCLUSIVE`/`BLOCKED`;写清缺什么 | 用个人印象建立产品规约;把未知写成 PASS |
|
|
61
|
+
|
|
62
|
+
契约不明时的标准写法:`expected_contract: 未提供,无法判定是否符合预期` + `observation` 原文 + `verdict: INCONCLUSIVE` + `limitation: needs-contract`。
|
|
63
|
+
|
|
64
|
+
## 5. 合成示例(模式,不是任何靶机的答案)
|
|
65
|
+
|
|
66
|
+
**例 A:证据在手却判 PASS(必须被拦住)**
|
|
67
|
+
|
|
68
|
+
```text
|
|
69
|
+
expected_contract: 列表项在重复提交后不得出现重复条目
|
|
70
|
+
observation: 列表出现 2 条同 id 条目;请求日志显示同一 payload 发送 2 次
|
|
71
|
+
evidence_ids: networkSessionId=n1 seq=12,13;snapshotId=s3 digest=…
|
|
72
|
+
counterexamples: —
|
|
73
|
+
verdict: FAIL ← 第 1 项校验(observation 含"重复")与第 2 项(缺陷清单映射)同时成立
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
**例 B:现象存在但契约允许(应判 PASS + 解释,不误伤)**
|
|
77
|
+
|
|
78
|
+
```text
|
|
79
|
+
expected_contract: 契约文档 §x:断线重连后服务端允许重放最近 N 条事件;UI 按 eventId 去重
|
|
80
|
+
observation: 重连请求携带游标;界面事件条数与首次加载一致,无重复渲染
|
|
81
|
+
evidence_ids: networkSessionId=…(reconnect 请求 + SSE eventId 序列)、截图 sha256=…
|
|
82
|
+
counterexamples: "重复投递"出现在网络层 → 被 UI eventId 去重吸收,页面无重复条目
|
|
83
|
+
verdict: PASS(在 counterexamples 写明"重复投递被去重,契约允许")
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
**例 C:契约不明(不猜)**
|
|
87
|
+
|
|
88
|
+
```text
|
|
89
|
+
expected_contract: 未提供
|
|
90
|
+
observation: 两个视图的同一数值相差 1,5s 后一致
|
|
91
|
+
evidence_ids: 两次读取的时间戳与各自读数
|
|
92
|
+
counterexamples: 契约未写收敛窗口
|
|
93
|
+
verdict: INCONCLUSIVE(limitation: needs-contract;不写"未同步=缺陷")
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
## 6. 报告级终检(提交前对着清单打勾)
|
|
97
|
+
|
|
98
|
+
- [ ] 每个 `PASS` 都有 `evidence_ids`,且证据内容与断言对象一致。
|
|
99
|
+
- [ ] 每个缺陷条目都能映射到至少一个 `FAIL`;没有"PASS + 缺陷"共存。
|
|
100
|
+
- [ ] 所有异常词都已复核并留处置说明。
|
|
101
|
+
- [ ] 所有数字都有来源;没有从 UI 文案反推服务端字段。
|
|
102
|
+
- [ ] 写了"无法验证"的 case 没有被判 `PASS`。
|
|
103
|
+
- [ ] 截图文件名、声明、内容三者一致(页面/登录态/视口)。
|
|
104
|
+
- [ ] 替代路径已声明 coverage(见 [`reporting.md`](reporting.md))。
|
|
105
|
+
- [ ] 未执行项标 `NOT_RUN`,未写成通过。
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
# 验证与证据标准(M0–M2)
|
|
2
|
+
|
|
3
|
+
执行成功与断言分离:ok/applied/actionId 说明操作,不自动产生 PASS。页面状态由 state/eval 实际值证明;计算样式由 computed_style 证明,不证明遮挡/像素。network 包含响应与 loadingFailed 元数据、脱敏 URL,不证明头/正文或完整接口契约。
|
|
4
|
+
|
|
5
|
+
每次调用返回并 render actionId/sessionId/startedAt/finishedAt/target/args 摘要。截图保留 base64 与 capturedAt/sha256/attachmentId,可选附件 image block,无服务为 base64-fallback 文本;provider 可见性另验;截图本身不等于 T3 像素结论,也不等于 T4 帧序列(后者须 `browser_dynamic_session` 采集 + `motion_analyze` 判定)。P0增加capture的PNG CRC/尺寸/全量均匀统计/文档JSON mapping、file的pathKind/persistence/root/ephemeral及delivery/warnings;默认暂存绝对路径,插件dispose清理,out/persist:true/非空env才持久且路径相对根;observed只persistence/relativePath|null不含绝对路径;原始base64/磁盘hash相等才证明原图落盘,附件compare='attachment-metadata'缺字段不推断相同。uniform只警告、UP只是尺寸保守拒绝,不自动判产品FAIL。详见 [证据契约](../contracts/evidence.md)。
|
|
6
|
+
|
|
7
|
+
state/capabilities 不启动、不占租约;capabilities 报实际三态与 workspaceIsolation(page=true、cookie=false),state 从 document.title 刷新标题但 error 可能过期,并带 scope。eval 异常 error 对象包含描述/栈与位置,执行错误 BrowserError 有分类码和证据消息。工作区 scope、同工作区面板操作、关闭/取消造成的状态变化都须在证据时序中记录;跨工作区 Cookie 共享不得写成隔离。
|
|
8
|
+
|
|
9
|
+
报告记录 platform/objective/expected/observed/tools_used/attempts/assertion_status/evidence/limitations,引用真实 camelCase action/附件字段,不发明文件路径或 evidence_refs。
|
|
10
|
+
|
|
11
|
+
- PASS:明确验收条件被充分验证。
|
|
12
|
+
- FAIL:可靠证据证实不满足条件。
|
|
13
|
+
- BLOCKED:权限/环境/能力缺失。
|
|
14
|
+
- INCONCLUSIVE:已执行但证据不足。
|
|
15
|
+
|
|
16
|
+
判定前先过 [verdict-gate.md](verdict-gate.md):五元组(expected_contract/observation/evidence_ids/counterexamples/verdict)+ 6 项交叉校验;反例词出现即复核;写了 limitation 不得判 PASS。报告字段与同源模板见 [reporting.md](reporting.md)、[report-template.md](report-template.md);合成正反例见 [verdict-examples.md](verdict-examples.md)。
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
截图/eval 内容可能敏感,URL 脱敏也非全覆盖;分享前检查。
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
# Web T1/T2 执行工作流
|
|
2
|
+
|
|
3
|
+
1. 明确目标与断言,按页面状态、元素语义/交互(T2)、计算样式、网络(P0)、静态视觉(T3)、动态/时序(T4)区分证据需求;跨层组合见 `references/scenarios/functional.md`。
|
|
4
|
+
2. 确认授权 URL 与动作、网络/截图读取范围。
|
|
5
|
+
3. 先确认注册表,再调用 browser_capabilities/state 诊断;不启动浏览器、不占租约,不把 manifest 当 available;能力报告自身报错时按证据不足处理。
|
|
6
|
+
4. 按 selection.md 选方法;页面操作先按 exec 身份解析到 DSH 工作区,再申请该工作区的 single-owner-lease。同工作区其他 owner BUSY 时不得绕过;不同工作区互不影响。缺 exec 身份走 legacy。
|
|
7
|
+
5. **需要元素语义/元素级交互时先 `browser_snapshot` 拿 ref**,再 click/type/scroll/fill_form;目标用 `ref` 或主文档唯一 `selector`,无快照不猜坐标。
|
|
8
|
+
6. 用结构化工具执行;导航不保证加载完成,副作用动作记录前置状态。
|
|
9
|
+
7. 用 `browser_node_state`/`browser_wait_for` 读回 T2 动作结果,用 state/eval/style/network 补充观察,必要时截图;保留真实 action 时间/target/参数摘要、T2 evidence(snapshotId/digest/targets/dispatch)、错误与附件/hash。截图可选scale/文档region/persist/out:默认插件暂存且dispose清理;仅out/persist:true/非空env持久。按采集前scroll转换视口坐标,保留capture的PNG尺寸/CRC/sizeCheck/mapping/file的path/pathKind/persistence/root/ephemeral/hash/warnings(暂存绝对路径不视为持久引用)。capabilities.capture.observed只代表上次截图;同路径不覆盖,OUTPUT_EXISTS换out。provider图像可见性、metadata未知与fallback如实记录。
|
|
10
|
+
8. 独立断言,ok/applied/dispatched 不等于 PASS;单帧 PNG 本身不产生 T3/T4 结论,必须走 `vision_compare`/`vision_check` 或 `motion_analyze`。
|
|
11
|
+
9. 错误按 code/category/retryable 分类;`REF_STALE` 重新快照、`WAIT_TIMEOUT` 不改小预算掩盖、`NOT_INTERACTABLE` 是 finding 不是换目标理由。取消/超时/断连后先查应用状态。已发 CDP 命令后 abort 先关闭浏览器再放锁,不能假设回滚。
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
**判定与门禁**:写 PASS/FAIL/BLOCKED 之前过 [verdict-gate.md](verdict-gate.md) 的五元组与 6 项交叉校验;动作前过 [page-identity.md](page-identity.md) 的页面身份记录;替代路径(自建标签/独立 HTTP/手工坐标)按 [reporting.md](reporting.md) 声明 coverage;工具选路、断言 schema、失败码→下一步与坐标空间见 [tool-routing-and-limits.md](tool-routing-and-limits.md);网络/SSE/多视图与动态采样分别见 [network-and-state.md](network-and-state.md)、[dynamic-visual.md](dynamic-visual.md)。
|
|
15
|
+
|
|
16
|
+
面板与 Agent 在同一工作区的同队列内改变该工作区 page;不同工作区 page 独立、ref 表独立,但 Cookie/存储共享。操作前后复查。真实缺陷确认后停止找 PASS,能力不足如实报告。详细契约见 ../contracts/operation.md 与 ../contracts/evidence.md。
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
# 平台索引
|
|
2
|
+
|
|
3
|
+
本插件**只对 Web 实现了 T1–T4 与网络 P0**;其它平台没有定义、没有实现、不可用。本文件不承诺任何 SDK 已安装,运行时能力以 Agent 当前工具注册表为准。
|
|
4
|
+
|
|
5
|
+
**宿主 OS**:Web/Chromium 适配器在 Linux、macOS、Windows 三种宿主上都能运行;平台差异(浏览器发现、进程树终止、有头窗口隐藏、目录 fsync)在运行时按 `process.platform` 分支处理,不改变其它平台的行为。上面的"平台"指的是**被测试的目标环境**,与宿主 OS 是两件事。
|
|
6
|
+
|
|
7
|
+
| 平台 | 文档 | 当前状态 |
|
|
8
|
+
|---|---|---|
|
|
9
|
+
| Web / Chromium(无头) | `web.md` | T1–T4、网络 P0、P0-E 多标签与 P0-D 标注已实现(37 工具,含 `browser_tabs`、`browser_annotation`);T4 44 条门槛中 12 通过 / 20 部分 / 12 未运行,provider 图像可见性未验证 |
|
|
10
|
+
| Windows | 未创建 | 未定义 / 不可用 |
|
|
11
|
+
| Linux | 未创建 | 未定义 / 不可用 |
|
|
12
|
+
| Android | 未创建 | 未定义 / 不可用 |
|
|
13
|
+
| macOS | 未创建 | 未定义 / 不可用 |
|
|
14
|
+
| HarmonyOS | 未创建 | 未定义 / 不可用 |
|
|
15
|
+
| TUI | 未创建 | 未定义 / 不可用 |
|
|
16
|
+
| Game | 未创建 | 未定义 / 不可用 |
|
|
17
|
+
| 3D | 未创建 | 未定义 / 不可用 |
|
|
18
|
+
|
|
19
|
+
不要因为面板里存在“运行环境选择器”的置灰项,就假设对应平台已具备 SDK 或工具。新增平台时必须先有真实 Adapter、运行时能力探测与回归证据;不要照搬 Web 的 T1 技术栈去假设其它平台的实现路径。
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
# Web 平台操作指南(M0–M2 + T2)
|
|
2
|
+
|
|
3
|
+
Web 已有 **37 个工具**:T1 10 个(含独立 HTTP `browser_http_request` 与共享视口 `browser_viewport`)+ P0-E 1 个(`browser_tabs`)+ P0-D 1 个(`browser_annotation`)+ T2 7 个 + T3 6 个 + 网络 P0 7 个 + T4 5 个,工具名见各层表格与 [工具参考](../../../../docs/tools.md)。T3/T4 已实现,其中 T4 的 44 条门槛仍有 20 条部分通过、12 条未运行;provider 图像可见性未验证。按当前注册表与 `browser_capabilities` 实际三态选路,不把文档或 manifest 当运行态证明。
|
|
4
|
+
|
|
5
|
+
同一时刻最多一个无头 Chromium/profile;每个 DSH 工作区一个 page,默认共享视口 1280×800@100%/DPR1(`browser_viewport` 可改宽高/X-Y/显示比例;比例不改页面 CSS 视口与 DPR)。single-owner-lease 按工作区:空闲 15s、进行中保持、缺 exec 走 legacy、disposed 只释放对应 owner;同工作区其他 session 页面/network/T2 BUSY,不同工作区独立。面板与 Agent 在同一工作区同 page/串行队列;Cookie/localStorage/cache 共享,不是安全隔离。state/capabilities 不启动、不占租约。
|
|
6
|
+
|
|
7
|
+
导航检查 errorText/最终 URL,不保证加载完成;标题从 document.title 刷新。目标/DNS/Document 重定向校验允许 loopback,阻断默认私网、metadata/unspecified/multicast/credentials/已配置宿主 origin。它不是子资源/页面 fetch/WebSocket 的完整网络沙箱,仍有 rebinding 风险。详细环境变量与风险见 [安全边界](../core/safety.md)。
|
|
8
|
+
|
|
9
|
+
网络记录响应/失败元数据、URL 脱敏、有界,close 清空;无头/正文。截图保留 base64 与时间/hash/附件 ID,可选附件 image block,无服务 base64-fallback 文本;provider 图像可见性另验,不提供 T3 差异分析。所有工具有 action 元数据并 render。P0 screenshot可选显式scale 0.1–4(省略时跟随共享view.scale)、canvas CSS region(O=0与文档相同;O≠0白底合成)、相对.png out,新增capture v1(CRC/尺寸/全量均匀统计/JSON mapping/file/delivery/warnings);DSF固定1,输出round(css×scale),最多16M像素;输入/T2 bbox为视口CSS px,转换按scroll。能力capture/limits.capture不启动,observed仅真实截图。新增persist:boolean=false;默认实例级staging绝对路径、dispose清理,out/persist:true/非空env才persistent相对路径。file含pathKind/persistence/root/ephemeral,observed只persistence/relativePath|null;legacy默认暂存、持久无根root_unknown,暂存失败仅既有warning。安全规则见 [安全边界](../core/safety.md),
|
|
10
|
+
|
|
11
|
+
**T2 路径**:`browser_snapshot` 拿 `snapshotId/digest/tree/refs` → 用 `ref`(或主文档唯一 `selector`)执行 click/type/scroll/fill_form → 用 `browser_node_state`/`browser_wait_for` 读回并断言。ref 在同一 Runtime 内单调不复用、新快照不自动失效、LRU 2000,跨文档导航/刷新/历史前进后退/关闭即 `REF_STALE`;所有 T2 失败抛 `BrowserError`;无 force/JS click 逃生。,详见 [T2 层](../tiers/t2-structured.md)。
|
|
12
|
+
|
|
13
|
+
**网络 P0 路径(第 8 轮)**:`browser_network_session`(`status` 只诊断、`start` 才懒启动)→ 用 T2/T1 或页面自身产生真实流量 → `browser_network_events`(summary/timeline/aggregate + filter/search/groupBy)→ `browser_network_detail`(按需 requestId/seq 取头/正文/timing/redirects/WS/SSE,读不到就是 `available:false`)→ `browser_network_trace`(步骤窗口、对象传递、跨请求关联、因果;`basis:"temporal"` 不等于因果)→ `browser_network_evidence`(JSONL/HAR 导出、索引、link、integrity)或 `browser_network_subscribe`(多 Agent 各自游标 poll/ack)。控制类 `browser_network_control`(throttle/offline/intercept/hold/replay/mock)需要 page,会懒启动并走该工作区队列与租约;`Fetch.enable` 仍只有一份配置,与既有 Document 导航守卫共用 dispatcher。**只读动作不启动浏览器、默认脱敏、body 读不到不伪造**;子目标按 R1-21:same-origin iframe 与 dedicated worker 已实证,OOPIF partial 未单独验证,shared/service worker 不采集(`subTargets.service_worker="not-collected"`)。
|
|
14
|
+
|
|
15
|
+
面板 screencast 的 WS 优先/HTTP 回退、metrics 都是预览诊断,不是 Agent 页面证据;内部 HTTP 路由不是 Agent API,不可绕过工具。
|
|
16
|
+
|
|
17
|
+
须验证:37 工具注册面/诊断不启动(含 `browser_tabs` 与 `browser_annotation`)、标题/导航/错误、租约/anonymous/disposed/BUSY、按 tab 的 BUSY 与 selectedTab、面板队列与取消关闭、目标/DNS/Document 重定向、网络失败/脱敏/资源界限、action render、截图附件/fallback/provider、独立 HTTP 的预算/重定向/阻断/取消/零派发、T2 的快照/ref 生命周期/唯一 selector/可信动作/表单/滚动/等待/错误码/证据、network P0 的 7 工具注册/三态/限额、事件 schema 与时间轴、body 三态不伪造、脱敏、配额与 integrity、拦截/限速/重放/Mock 与导航守卫共存、JSONL/HAR 往返、订阅隔离与 pin/gap。没有下载/上传/Cookie 导出、Agent 多 target/frame(iframe 内部)选择、自动 popup 采集;`browser_viewport` 与 `browser_tabs`(按会话 selectedTab 路由、GUI active 独立)已可用,但不做跨标签聚合;T4 的 media 适配器、WebGPU 真实渲染、16ms 闪白采样覆盖仍未验证。
|
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
# 读取与写入面板标注(P0-D annotations)
|
|
2
|
+
|
|
3
|
+
用户提到「标注」「我画的」「看我标的」「我圈的是哪里」「这个框/箭头指的是什么」「这些笔迹」等、指代面板标注时用本页;用户说「你圈一下」「标给我看」「在这儿写个问号」时也用它(反向:`browser_annotation` 往同一份文档里画)。标注是**用户在调试面板里画的问题线索**:先读结构化文档,再查看带标注截图;要给人类画标注时,先确认前台标签可见再写。
|
|
4
|
+
|
|
5
|
+
## 1. 文档与像素读取入口
|
|
6
|
+
|
|
7
|
+
- `browser_state()` 返回顶层 `annotations`(与已认证 `/state` 的 `ui.annotations` 同源;旧 Host 无此字段 → 按 `unsupported` 处理,不要假装读到)。
|
|
8
|
+
- `browser_capabilities()` 的 `annotations` 段声明读取方式、`space`(恒为 `canvas-css-px`)与 `limits`;**工具面是 37 个已注册的 `browser_*`(当前 Web 环境注册并准入的那些)**。读取结构化标注既可以用 `browser_state` 的一个字段,也可以用 `browser_annotation {action:"read"}`(同一份文档,返回 `revision/shapes/shapeCount/truncated/truncation/foreground`)。
|
|
9
|
+
- `browser_screenshot {includeAnnotations:true}` 叠加当前目标已提交且经 Host 接受的六种形状,渲染与面板的颜色、粗细、填充/外框语义一致;不包含未提交草稿、工具栏、选中控件或其它面板 UI。
|
|
10
|
+
- `includeAnnotations?:boolean=false` 默认关闭。默认截图、T3 原始源与 T4 的 screencast/screenshot-loop 帧源均不含面板标注;默认图里没有线不能说明用户没画。`capture.canvas.composite` 仅说明画布合成,标注叠加看 `capture.annotations`;T3 的 `annotations` 参数是独立的图片后处理标记。
|
|
11
|
+
|
|
12
|
+
## 2. 反向:给人类画标注(`browser_annotation`)
|
|
13
|
+
|
|
14
|
+
用户说「你圈一下 / 标给我看 / 把有问题的几处框出来 / 在这儿写个问号」时,用 `browser_annotation` 把结论画到**他眼前的调试视图**上——面板画布与这个工具写的是**同一份**标注文档。
|
|
15
|
+
|
|
16
|
+
- **四类动作**:`read` 读当前文档;`draw` 追加 1–64 个形状(追加,不是替换);`erase` 按 `ids`(1–64)和/或 `point{x,y,radius?}` 删(默认半径 8 画布 px,命中规则同面板橡皮擦:形状到该点距离 ≤ `max(strokeWidth/2,6)` 与 `radius` 取大者);`clear` 清空画布。
|
|
17
|
+
- **形状与面板工具的对应**:`circle` 圆形、`rect` 矩形、`line` 线段、`arrow` 箭头、`brush` 画笔(铅笔)、`text` 文字;「颜色」→ `color`(`#rrggbb`,默认 `#ff3b30`);「粗细」→ `strokeWidth`(整数 1–20,默认 3);「外框/填充」→ `style:"stroke"|"fill"`(只对 `circle`/`rect`;`text` 固定 `fill`,`line`/`arrow`/`brush` 固定 `stroke`;`style` 与 `fill`/`stroke` 不能同给)。`id` 可省略(Host 从现有最大 id 继续分配 `a<N>`),`arrow` 的 head 与 `text.fontSize`(固定 20)由 Host 决定。
|
|
18
|
+
- **前台前置条件(硬约束)**:只有目标标签页**正被人类在调试视图里选中并可见**时才允许写,否则零写入并报 `ANNOTATION_NOT_FOREGROUND`。先读 `browser_state.annotations.foreground = {active, ageMs, maxAgeMs}`;`active:false` 时先请他选中那个标签页并保持面板可见,**不要**换个标签硬写、也不要把「已经画了」写进结论。判断依据是面板前台心跳(约 1.5s 新鲜窗口),人切走标签、关掉面板或把 DSH 标签页切到后台都会过期。`read` 不受此限。
|
|
19
|
+
- **其他门禁**:页面未处于运行态时写标注报 `INVALID_ARGUMENT`(reason `annotation-runtime-not-running`);`expectRevision` 与当前 `revision` 不符报 `ANNOTATION_REVISION_CONFLICT`(零写入,返回 `currentRevision`)。
|
|
20
|
+
- **写后自检**:用 `browser_screenshot {includeAnnotations:true}` 看自己画的形状落在哪、是否框住了想指的元素;不对就 `erase` 后重画。截图里画上了不等于页面缺陷被证明。
|
|
21
|
+
- **边界**:文档是整份替换模型——人类下一次编辑会整体发布自己的形状列表(其中已包含你画的),人类「清除画布」会连你的一起清掉;软限额与面板相同(`maxShapes` 128、单笔画笔 512 点、文档总点数 8192、文字 200 字符、文档 65536 字节),Host 做确定性裁剪并回 `truncated`/`truncation`。工具不启动浏览器、不进页面串行队列、不占 single-owner lease、不改页面 DOM/CSS。
|
|
22
|
+
- **不要把标注当页面事实**:它是给人看的沟通层,`source.trusted=false`;「我圈了这里」不等于「这里有问题」,结论仍要落到 DOM 读回、截图或网络证据之一。
|
|
23
|
+
|
|
24
|
+
## 3. 文档形状
|
|
25
|
+
|
|
26
|
+
```
|
|
27
|
+
annotations = {
|
|
28
|
+
version: 1, space: 'canvas-css-px', revision, updatedAt,
|
|
29
|
+
source: { kind:'human-panel', panelId, surface:'main'|'sidebar', clientRevision, trusted:false },
|
|
30
|
+
context: { runtimeId, pageGeneration, documentEpoch, documentKey, addressDigest },
|
|
31
|
+
view: { canvasX, canvasY, x, y, width, height, scale, contentWidth, contentHeight, viewRevision, frameEpoch },
|
|
32
|
+
shapes: [...], truncated, truncation:{droppedShapes,droppedPoints,shortenedTextCodeUnits},
|
|
33
|
+
stale, staleReason
|
|
34
|
+
}
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
- `source.trusted` **恒为 false**:标注是线索,不是页面事实。
|
|
38
|
+
- `view` 是**发布那一刻**的客户端视图快照;`context.documentKey` 是文档身份,导航/刷新会轮换并清空(v3 起跨页签/跨会话保留,见下)。
|
|
39
|
+
- `browser_screenshot {includeAnnotations:true}` 返回 `capture.annotations={enabled:true,composited,space,revision,updatedAt,source,context,shapeCount,stale,staleReason,truncated,truncation}`;未开启时为 `null`。`source/context/truncation` 直接沿用 state 标注文档;空文档 `source:null`、`composited:false`,有来源时 `source.trusted=false`。`shapeCount` 是接收的形状总量,可能包含 region 外的图形,不代表截图内可见数量;`composited` 也不证明某形状可见。精确字段说明见 `docs/capture-p0.md`。
|
|
40
|
+
|
|
41
|
+
## 4. 图形与字段
|
|
42
|
+
|
|
43
|
+
| `type` | 字段 | 备注 |
|
|
44
|
+
| --- | --- | --- |
|
|
45
|
+
| `rect` | `x,y,width,height` | 左上角 + 尺寸 |
|
|
46
|
+
| `circle` | `cx,cy,rx,ry` | PS 默认语义:按下点与落点为**包围盒两角**的内接椭圆,不是"中心+半径" |
|
|
47
|
+
| `line` | `x1,y1,x2,y2` | |
|
|
48
|
+
| `arrow` | `x1,y1,x2,y2,head:{length,width}` | **尖端 = `(x2,y2)`**;`head` 由 Host 按 `min(3t,L)/min(2t,L)` 重算,不可信客户端 |
|
|
49
|
+
| `brush` | `points:[[x,y],...]` | 只有点集 |
|
|
50
|
+
| `text` | `x,y,fontSize,text` | 唯一带**原文**的类型(≤200 UTF-16 code units) |
|
|
51
|
+
|
|
52
|
+
形状还带 `id`(`a1`、`a2`…)、`color`、`strokeWidth`、`fill`、`stroke`。
|
|
53
|
+
|
|
54
|
+
## 5. 坐标换算(最容易错的一步)
|
|
55
|
+
|
|
56
|
+
- shapes 存的是**画布 CSS px `d`**;页面坐标 `p = d − S`,`S` 是**当前** `view.x/y`。
|
|
57
|
+
- 面板侧另有 `q = d − C`(`C = canvasX/canvasY`);两者关系 `p = q + O`、`O = C − S`。
|
|
58
|
+
- **必须用当前 `view` 换算**,不要用 `annotations.view`(那是发布时快照,`C`/`scale` 可能已经变了);`scale`(显示比例)与 DPR **不参与**坐标变换。
|
|
59
|
+
- 空白区(`O≠0` 时视口露出的部分)同样可画、可读;`d` 允许负值。
|
|
60
|
+
- 带标注截图与页面共用本次 `region`/`scale` 映射:连续图像像素位置 `u=(d−region.origin)/capture.mapping.cssPerPixel`(逐轴,通常等于乘以 scale);图形、线宽、文字与笔迹同步缩放并裁剪。这里的像素缩放不同于上面的页面输入坐标换算。
|
|
61
|
+
|
|
62
|
+
## 6. 能读到什么、读不到什么
|
|
63
|
+
|
|
64
|
+
- **只有 `text.text` 提供文字原文**;画笔手写的结构化数据是 `brush.points` 点集,不要把点集当文字字段转述。
|
|
65
|
+
- 读取 `browser_state.annotations` 后调用 `browser_screenshot {includeAnnotations:true}` 看 Host 已接受的实际笔迹。可以依据图像辨认;无法可靠辨认时如实说明,不猜字、不伪造原文。无需自行把点集重建成图来代替工具截图。
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
## 7. 落点解析:「这个箭头指的是什么」
|
|
69
|
+
|
|
70
|
+
1. 取端点 → `p = d − S` 得到页面点。
|
|
71
|
+
2. `browser_eval` 命中:`document.elementFromPoint(p.x, p.y)`;再枚举同区域可见元素,按**点到矩形边距**排序,得到候选表。
|
|
72
|
+
3. 手绘尖端常偏 10–20 px:**给候选 + 距离**(例如"搜索框容器 2 px、标签栏 3 px、logo 22 px"),不要单点断言"就是它"。
|
|
73
|
+
4. 用 `browser_screenshot {includeAnnotations:true}` 结合结构化文档查看箭头、框选与笔迹;需要更多页面证据时,用 `browser_snapshot` + `browser_node_state` 取 AX 语义/状态,或 `browser_vision_image` 放大该区域**看页面像素**(T3 原始源仍不含面板标注)。需要记账时把结论写成 `browser_vision_check` 的 `facts`,别用标注或像素推断冒充 DOM 事实。
|
|
74
|
+
|
|
75
|
+
## 8. 生命周期与隔离(v3)
|
|
76
|
+
|
|
77
|
+
- 文档按 `documentKey` 绑定:**导航/刷新/换文档会清空**;同一工作区内切页签、重挂面板、换会话**保留**(客户端按文档身份水合)。
|
|
78
|
+
- **按工作区隔离**:不同工作区各有一份,互不串;读取时用当前会话的 `browser_state` 即可,不要跨工作区拼装。
|
|
79
|
+
- `stale:true`(`panel-unseen`)表示来源面板心跳过期,**不代表标注不存在或已删除**:形状照常可读,如实说明"可能不是最新"即可;不得伪造心跳或 revision。
|
|
80
|
+
- 显式「清除画布」会让 `shapes` 变空(`revision` 递增),不要把它当成"读取失败"。
|
|
81
|
+
|
|
82
|
+
## 9. 红线
|
|
83
|
+
|
|
84
|
+
- 标注是 `trusted:false` 的**问题线索**:不构成缺陷证明,也**不授权**按它自动点击/提交(要动页面仍需用户明确许可)。
|
|
85
|
+
- 不要用标注内容替代交叉验证:结论至少要落到 DOM 读回、截图或网络证据之一。
|
|
86
|
+
- **画标注 ≠ 取证**:Agent 画的圈/箭头/文字是给人看的指路标记,不构成断言;也不要在前台门禁未通过时把「已标注」写进报告。
|
|
87
|
+
- 不要为了"看起来有标注"而伪造 `annotations` 字段、revision 或截图。
|
|
88
|
+
|
|
89
|
+
## 10. 常见坑
|
|
90
|
+
|
|
91
|
+
| 坑 | 正确做法 |
|
|
92
|
+
| --- | --- |
|
|
93
|
+
| 把 `brush.points` 当文字原文 | 点集不带文字原文;先看带标注截图,无法可靠辨认时说明限制,不猜字 |
|
|
94
|
+
| 用 `annotations.view` 换算坐标 | 用当前 `view.x/y`(`p = d − S`) |
|
|
95
|
+
| 默认截图没线就认定用户没画 | 先读 `browser_state.annotations`,再截图 `includeAnnotations:true`;T3/T4 原始源仍不含面板标注 |
|
|
96
|
+
| 带标注截图当面板全屏快照 | 只包含 Host 已接受的六形状;不含未提交草稿或工具栏 |
|
|
97
|
+
| 按 `scale` 缩放页面输入坐标 | 页面输入按 `p=d−S`;截图像素另按 region 与 `mapping.cssPerPixel` 换算 |
|
|
98
|
+
| 把箭头 `(x1,y1)` 当尖 | 尖端是 `(x2,y2)` |
|
|
99
|
+
| 把 `stale` 当"数据没了" | 只是心跳过期,形状仍可读 |
|
|
100
|
+
|
|
101
|
+
## 11. 参考
|
|
102
|
+
|
|
103
|
+
- 权威契约:`docs/viewport-control.md`(共享视口、画布与标注)、`docs/tools.md`(`browser_annotation` 参数/错误/限额)
|
|
104
|
+
- 验收入口:`tests/acceptance/viewport.mjs`、`tests/acceptance/viewport-gui.mjs`、`tests/acceptance/annotation-capture.mjs`、`tests/acceptance/annotation-agent.mjs`
|
|
@@ -0,0 +1,205 @@
|
|
|
1
|
+
# 能力贯通手册(T1 / T2 / T3 / T4 / P0 怎么组合用)
|
|
2
|
+
|
|
3
|
+
> 工具面 **37 个**:T1 10 + P0-E 1(`browser_tabs`)+ P0-D 1(`browser_annotation`)+ T2 7 + T3 6 + 网络 P0 7 + 动态 T4 5。
|
|
4
|
+
> 本文是**选路 + 组合配方**;单层细节见 `references/tiers/*.md`,动画调试全流程见 `references/scenarios/visual-motion.md`。
|
|
5
|
+
|
|
6
|
+
## 0. 先探能力,别假设
|
|
7
|
+
|
|
8
|
+
```text
|
|
9
|
+
browser_capabilities {}
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
按实测三态选路(`available` / `unavailable` / `unsupported`),**不要拿文档或 manifest 当运行态证据**。能力报告本身不启动浏览器、不占租约、不产证据;它自己抛错时也不能当结论。
|
|
13
|
+
|
|
14
|
+
## 1. 五层速查:谁负责什么、给什么证据、不能冒充什么
|
|
15
|
+
|
|
16
|
+
| 层 | 工具数 | 回答什么 | 唯一可信证据 | 不能证明 |
|
|
17
|
+
| --- | --- | --- | --- | --- |
|
|
18
|
+
| **T1 程序化** | 10 | 地址/标题/运行时错误、JS 值、计算样式、原始输入、独立 HTTP、共享视口、预览网络 | `browser_state`、`browser_eval` 返回值、`computed_style`、`http_request` 的 status/headers/body | 像素正确性、动画流畅性、语义可访问性 |
|
|
19
|
+
| **T2 结构化** | 7 | 元素是什么(role/name)、能不能点、点了有没有派发、表单填对没 | `snapshot` 的 AX 树、`node_state` 回读、`dispatch` 证据、页面真值 | `dispatched:true` ≠ 业务生效;ref 只在本 workspace Runtime 有效 |
|
|
20
|
+
| **T3 静态视觉** | 6 | 像素差异、颜色/区域/遮挡/溢出/截断、基线回归、图像内定位 | `vision_compare` 的差异图+比值+阈值、`vision_check` 的 verdict、`vision_find` 候选 | 时长/流畅度/闪烁;`vision_act` 的 `dispatched` 只是派发 |
|
|
21
|
+
| **T4 动态行为** | 5 | 帧序列、间隔/抖动、冻结、闪烁、轨迹、过渡、跨域关联 | 帧 `sourceTimestamp`+hash+`integrity`、`motion_analyze` 的 verdict+metrics | 技术身份(CSS/Canvas/WebGL/video)、属性值、语义命名 |
|
|
22
|
+
| **P0 网络** | 7 | 请求/响应/时序/依赖/重试、WS/SSE、拦截/重放/Mock、证据包 | `network_events` 时间轴、`detail` 的 body 三态、`trace` 的显式因果 | 页面**语义**因果;脱敏头不能做 header-verified 身份 |
|
|
23
|
+
|
|
24
|
+
**跨层铁律**:每层只对自己的证据形式负责;**低层的"动作成功"不能升级成高层的"结果正确"**。
|
|
25
|
+
|
|
26
|
+
## 2. 选路决策树
|
|
27
|
+
|
|
28
|
+
```text
|
|
29
|
+
断言是"某个值/状态"? → T1(eval / state / computed_style / http_request)
|
|
30
|
+
断言是"元素语义 or 交互发生"? → T2(snapshot → 动作 → node_state/wait_for 回读)
|
|
31
|
+
断言是"像素/颜色/布局正确"? → T3(vision_image/compare/check;有基线用 check 回归)
|
|
32
|
+
断言是"时间/运动/过渡/闪/卡"? → T4(dynamic_session → motion_analyze)
|
|
33
|
+
断言是"网络请求/响应/时序/重试"? → P0(network_session → events → detail → trace)
|
|
34
|
+
断言是"A 导致 B"? → 跨层:correlate + 独立旁证;只有 explicit/redirect/initiator 才叫因果
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
同一断言要多种证据时**分别记账**,不做加权平均。
|
|
38
|
+
|
|
39
|
+
## 3. 八个贯通配方(可直接照抄)
|
|
40
|
+
|
|
41
|
+
### R1 · 按钮点了没反应
|
|
42
|
+
|
|
43
|
+
```text
|
|
44
|
+
1. browser_snapshot → 拿 ref(用 role/name 确认是对的那个)
|
|
45
|
+
2. browser_click { ref } → 记 dispatch 证据(dispatched:true 只证明派发)
|
|
46
|
+
3. browser_state / browser_eval → 页面状态变没变
|
|
47
|
+
4. browser_network { limit:50 } → 有没有发请求、请求成没成(limit 别给太小,会被自身流量挤出窗口)
|
|
48
|
+
5. 若 NOT_INTERACTABLE → 记 FAIL;用 T3 vision_image 给遮挡/隐藏的成因证据,不硬点、不改坐标
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
判据:`NOT_INTERACTABLE` 本身即缺陷结论;`dispatched:true` 而状态未变 → 走 R2。
|
|
52
|
+
|
|
53
|
+
### R2 · "提交后列表应该刷新"
|
|
54
|
+
|
|
55
|
+
```text
|
|
56
|
+
P0: browser_network_session { action:"start" }
|
|
57
|
+
P0: browser_network_trace { action:"begin-step", name:"submit" }
|
|
58
|
+
T2: browser_snapshot → browser_click / browser_fill_form
|
|
59
|
+
P0: browser_network_trace { action:"end-step" }
|
|
60
|
+
P0: browser_network_events { filter:{ stepId, status:200 } } → 请求与载荷
|
|
61
|
+
T2: browser_wait_for { textGone:"提交中" } 或 state 条件 → DOM 终态
|
|
62
|
+
T3: browser_vision_check 基线回归 → 渲染终态
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
判据:**请求 200 + DOM 终态 + 渲染终态**三份证据分别成立;缺一项写"部分验证",不要合成一个 PASS。
|
|
66
|
+
|
|
67
|
+
### R3 · "动画该 300ms 且流畅"
|
|
68
|
+
|
|
69
|
+
```text
|
|
70
|
+
0. browser_navigate 与 browser_dynamic_session{start} 同批下发(Agent 往返 ~11.7s,否则错过窗口)
|
|
71
|
+
1. T4 motion_analyze { type:"transition" } → 起止时刻与稳定判定
|
|
72
|
+
2. T4 motion_analyze { type:"jank", expectedIntervalMs:16.7 } → 间隔分布/p95/max
|
|
73
|
+
3. T4 motion_observe { region, includeImages:true } → 只看动画本体(避免读到页面自述文字)
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
判据:`transition` 答"从哪到哪、用了多久";`jank` 答"间隔是否超预期"。**采样没覆盖到写 INCONCLUSIVE**。
|
|
77
|
+
|
|
78
|
+
### R4 · "闪一下就没了"
|
|
79
|
+
|
|
80
|
+
```text
|
|
81
|
+
T4 dynamic_session { config:{ source:"screenshot-loop", sampleIntervalMs:50 } } # 静止页面也出帧
|
|
82
|
+
T4 motion_analyze { type:"flicker" } # 需 A→B→A 三帧 + changeRatio≥0.2 + brightnessDelta≥64
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
判据:未检出时,若采样间隔 > 目标闪烁时长 → **必须写"采样不足"**,不许写"没有闪烁"。
|
|
86
|
+
|
|
87
|
+
### R5 · "点了按钮但画面好像没变"
|
|
88
|
+
|
|
89
|
+
```text
|
|
90
|
+
T4 dynamic_session{start}(同批下发)→ 点击 →
|
|
91
|
+
T4 motion_analyze { type:"region-change", thresholds:{minArea:300} } → 有变化吗、变在哪
|
|
92
|
+
T4 motion_observe { region:<变化区>, includeImages:true } → 看那块变成什么
|
|
93
|
+
T3 browser_vision_compare { before, after, region } → 需要精确像素/颜色时
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
判据:能区分三种情况——**真的没变**(无区域)/**变了但很小**(区域 <minArea)/**变了、我没注意到**(区域明确)。
|
|
97
|
+
|
|
98
|
+
### R6 · "错误横幅是因为那个 500 吗"
|
|
99
|
+
|
|
100
|
+
```text
|
|
101
|
+
P0: events filter status>=500 → 拿 traceId/时间
|
|
102
|
+
T4: dynamic_session{start} + 复现动作 → 抓横幅出现时刻(region-change)
|
|
103
|
+
T4: browser_dynamic_correlate { directions:["network->visual"] }
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
判据:`explicit/redirect/initiator` → 可写**因果**;只有 `observed` → 写**关联**;页面 `ui.cause` 是**声明**,须独立旁证。
|
|
107
|
+
|
|
108
|
+
### R7 · 端到端回归(下单/登录/发布)
|
|
109
|
+
|
|
110
|
+
```text
|
|
111
|
+
T1: browser_http_request 直接验契约(status/headers/body/幂等键)
|
|
112
|
+
T2: 走一遍真实交互(ref + dispatch + 回读)
|
|
113
|
+
P0: 全程采集,network_evidence 导出 JSONL/HAR 留证
|
|
114
|
+
T3: 关键节点 vision_check 基线回归
|
|
115
|
+
T4: 骨架屏/加载态/过渡用 motion_analyze 判时序
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
判据:契约、交互、网络、渲染、时序**五份证据分列**;
|
|
119
|
+
|
|
120
|
+
### R8 · "页面卡/白屏/像挂了"
|
|
121
|
+
|
|
122
|
+
```text
|
|
123
|
+
T4 motion_analyze { type:"freeze", expectation:{ motionExpected:true, sourceEventId:"…", referenceEventIds:["…"] } } → 冻结区间
|
|
124
|
+
T4 motion_analyze { type:"jank", expectedIntervalMs:16.7 } → 掉帧程度
|
|
125
|
+
P0 network_events { view:"timeline" } → 资源是否排队/失败
|
|
126
|
+
T1 browser_eval 读 window.onerror / 未捕获异常;browser_state.error
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
判据:`freeze` 的 `expectation` 必须是对象(`motionExpected:true` + `sourceEventId` + `referenceEventIds`,见 `references/core/tool-routing-and-limits.md` §2),且参照事件可核验,否则 INCONCLUSIVE。
|
|
130
|
+
|
|
131
|
+
## 4. 升级与降级(回退链)
|
|
132
|
+
|
|
133
|
+
| 场景 | 允许的回退 | 禁止 |
|
|
134
|
+
| --- | --- | --- |
|
|
135
|
+
| T2 找不到元素语义 | T3 `vision_find`(template/color)拿候选 → T3 `vision_act` 派发 | 拿"看起来像"的坐标硬点;声称 `dispatched` 等于点中 |
|
|
136
|
+
| T2 `UNSUPPORTED`(contenteditable/number/date/file) | T1 `browser_input` + 读回,注明证据强度不同 | 假装 T2 成功 |
|
|
137
|
+
| T2 `NOT_INTERACTABLE` | 记 FAIL + T3 给成因 | force click / 改坐标 / 换相似节点凑 PASS |
|
|
138
|
+
| T4 预算超时 | 用 `frameIds`/`window` **抽帧**后重跑 | 抬 `algorithmBudgetMs` 掩盖;用单帧代替时序 |
|
|
139
|
+
| T4 采样不足 | 写 INCONCLUSIVE | 写"无闪烁/无卡顿" |
|
|
140
|
+
| P0 头被脱敏 | 只能 `observed` + 独立旁证 | 声称 `header-verified` |
|
|
141
|
+
| 某层 unsupported | `BLOCKED` + 写明缺哪项 | 用别的层的近似证据顶替 |
|
|
142
|
+
|
|
143
|
+
## 5. 证据合成(跨层不串味)
|
|
144
|
+
|
|
145
|
+
| 层 | 结论必须带 |
|
|
146
|
+
| --- | --- |
|
|
147
|
+
| T1 | actionId、`state.running`、返回值原文(JS 值标 page-eval)、`http_request` 的 status/headers 摘要 |
|
|
148
|
+
| T2 | `snapshotId`/`digest`、`targets[].resolved`、`dispatch`、动作前后 `node_state` |
|
|
149
|
+
| T3 | source(live/product/baseline)、尺寸、差异比值/阈值、productId 或基线 revision、落盘路径与 sha256 |
|
|
150
|
+
| T4 | `dynamicSessionId`/`motionSessionId`、窗口或 `frameIds`、`verdict`+`resolvedThresholds`+`integrity`、`roiSha256` |
|
|
151
|
+
| P0 | `networkSessionId`、`seq`/`requestId`、body 三态(captured/empty/unavailable)、脱敏记录、导出路径 |
|
|
152
|
+
|
|
153
|
+
**权威序**:DOM/AX 回读 > 像素证据 > 页面自述(`ui.*` 声明)。页面自己写的不算独立证据。
|
|
154
|
+
|
|
155
|
+
## 6. 跨层错误码速查
|
|
156
|
+
|
|
157
|
+
| 错误 | 层 | 含义与动作 |
|
|
158
|
+
| --- | --- | --- |
|
|
159
|
+
| `BUSY` | 页面操作 | 其他 owner 持租约;等待,不轰炸重试 |
|
|
160
|
+
| `VIEWPORT_CONFLICT` | T1 viewport | `expectedRevision` CAS 失败、patch 零应用;重读再改 |
|
|
161
|
+
| `REF_STALE` | T2 | 导航/刷新/新快照导致;重新 `snapshot` |
|
|
162
|
+
| `TARGET_NOT_UNIQUE` / `TARGET_NOT_FOUND` | T2 / T4 control | 用 ref 或更精确 selector;不要取第一个 |
|
|
163
|
+
| `NOT_INTERACTABLE` | T2 | hidden/disabled/covered/零面积/运动中 → 记 FAIL,T3 给成因 |
|
|
164
|
+
| `WAIT_TIMEOUT` | T2 | 条件未满足(page 不关闭);不缩小预算掩盖 |
|
|
165
|
+
| `UNSUPPORTED` | T2 / T4 | 控件/适配器不支持;走回退链并标注强度 |
|
|
166
|
+
| `DYNAMIC_SESSION_NOT_ACTIVE` | T4 | 会话已停/到期,`extend` 不复活 → 重新 `start` |
|
|
167
|
+
| `DYNAMIC_LIMIT_EXCEEDED{sessionCapMs}` | T4 | 累计 300000ms 到顶 → 收新会话 |
|
|
168
|
+
| `DYNAMIC_CONTROL_CONFLICT` | T4 | 页面代次/目标变了 → 重新定位,别覆盖 |
|
|
169
|
+
| `BLOCKED(dynamic-timeout)` | T4 | 帧太多解码超 5s → **抽帧** |
|
|
170
|
+
| `VISION_STALE_IMAGE` / `VISION_HIT_MISMATCH` | T3 act | 图过期/命中不一致 → 重新采图,零派发 |
|
|
171
|
+
| `NET_BODY_UNAVAILABLE` | P0 | body 没采到 → 如实标注,不伪造空体 |
|
|
172
|
+
|
|
173
|
+
## 7. 租约与并发(最容易踩)
|
|
174
|
+
|
|
175
|
+
- 一个 **workspace 一个 page**;人类与 Agent 共用同一队列。**页面操作**(T1 viewport set / 截图 / T2 动作 / T3 act / P0 session start)需要 single-owner-lease;**只读**(T1 state/eval、T2 snapshot、T3 分析、T4 status/observe/analyze/correlate、P0 events)不占租约。
|
|
176
|
+
- `browser_capabilities` **不启动浏览器**;`browser_dynamic_session{status}`、`browser_network_session{status}` 也不启动。
|
|
177
|
+
- 动作状态未知时**先查状态再重试**;提交/删除/支付类操作不得盲重放。
|
|
178
|
+
- 不同 workspace 的 URL/viewport 独立,但 Cookie/存储共享——**不得声称跨工作区安全隔离**。
|
|
179
|
+
|
|
180
|
+
## 8. 反模式(见到就是错)
|
|
181
|
+
|
|
182
|
+
1. 把 `dispatched:true` / `applied:N` 写成"功能正常"。
|
|
183
|
+
2. 用 `browser_screenshot` 的"看起来对"代替 T3 像素结论。
|
|
184
|
+
3. 用 `browser_eval` 读 DOM/CSS 冒充 T2 语义树或 T3 像素。
|
|
185
|
+
4. 用单帧截图 / `browser_state.seq` 冒充 T4 时序。
|
|
186
|
+
5. 用整页截图"理解动画"(页面可能把答案画在画面上)。
|
|
187
|
+
6. 把时间邻近写成因果(`temporal` 默认不返回)。
|
|
188
|
+
7. 采样没覆盖就断言"无闪烁/无卡顿"。
|
|
189
|
+
8. 为了变绿缩小 `WAIT_TIMEOUT` 预算、抬 `algorithmBudgetMs`、放宽阈值。
|
|
190
|
+
9. 跨 workspace / 跨 scope 聚合证据。
|
|
191
|
+
10. 把页面 `ui.cause`/`causeOpId` 的自述当独立证据。
|
|
192
|
+
11. 同一断言混用多层证据并取"最好的那个"结论。
|
|
193
|
+
|
|
194
|
+
|
|
195
|
+
## 9. 已知不可用(如实 BLOCKED/UNSUPPORTED)
|
|
196
|
+
|
|
197
|
+
- iframe/OOPIF 内部、closed shadow、contenteditable 编辑器、原生 `select` popup、拖拽、上传/下载、Cookie 导出。
|
|
198
|
+
- Agent 多标签页 / 跨窗口目标选择(GUI 内部真人 target=_blank 标签页可打开;自动/未授权 SSO 弹窗仍阻断)。
|
|
199
|
+
- T4 的 media 适配器(视频 seek/stall)、WebGPU 真实渲染、16ms 闪白采样覆盖。
|
|
200
|
+
- P0 的 OOPIF/HTTPS/service worker 覆盖、`header-verified` 身份(关联头脱敏)。
|
|
201
|
+
- 需要面板认证的路由(如 `close`/`dispose` 恢复)。
|
|
202
|
+
|
|
203
|
+
## 10. 结果要求
|
|
204
|
+
|
|
205
|
+
能力不足写 `BLOCKED`;部分证据不足写 `INCONCLUSIVE`。不能把某个 T1 断言通过写成整个功能或整个 GUI 通过。
|