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.
Files changed (92) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +327 -2
  3. package/annotation-capture.js +111 -0
  4. package/banner.png +0 -0
  5. package/banner_zh.png +0 -0
  6. package/browser-safety.js +293 -0
  7. package/capture-p0.js +910 -0
  8. package/client.js +11302 -0
  9. package/context-menu.js +134 -0
  10. package/cordis.patch.yml +3 -0
  11. package/core/clock.js +88 -0
  12. package/core/config-store.js +566 -0
  13. package/core/config.js +892 -0
  14. package/core/contracts.js +240 -0
  15. package/core/errors.js +156 -0
  16. package/core/evidence.js +141 -0
  17. package/core/geometry.js +217 -0
  18. package/core/identity.js +180 -0
  19. package/core/index.js +24 -0
  20. package/core/p0.js +1101 -0
  21. package/core/readiness.js +175 -0
  22. package/core/registry.js +239 -0
  23. package/core/tab-access.js +1350 -0
  24. package/docs/adapters.md +160 -0
  25. package/docs/architecture.md +146 -0
  26. package/docs/capability-tiers.md +80 -0
  27. package/docs/capture-p0.md +90 -0
  28. package/docs/diagnose-reason-codes.md +157 -0
  29. package/docs/element-picker.md +143 -0
  30. package/docs/getting-started.md +136 -0
  31. package/docs/index.md +36 -0
  32. package/docs/multi-tab.md +162 -0
  33. package/docs/network-p0.md +117 -0
  34. package/docs/panel-context-menu.md +41 -0
  35. package/docs/t2-structured-gui.md +68 -0
  36. package/docs/t3-vision.md +84 -0
  37. package/docs/t4-dynamic-behavior.md +135 -0
  38. package/docs/tools.md +174 -0
  39. package/docs/verification.md +131 -0
  40. package/docs/viewport-control.md +94 -0
  41. package/dynamic-t4.js +5699 -0
  42. package/frame-push.js +508 -0
  43. package/frame-source.js +162 -0
  44. package/icon.png +0 -0
  45. package/index.js +23028 -0
  46. package/integration/cross-environment.js +1535 -0
  47. package/integration/diagnose.js +945 -0
  48. package/integration/tab-principal.js +493 -0
  49. package/locale/en.json +6 -0
  50. package/locale/zh.json +6 -0
  51. package/network-p0.js +4264 -0
  52. package/package.json +19 -4
  53. package/select-control.js +298 -0
  54. package/skills/ui-testing-common/SKILL.md +54 -0
  55. package/skills/ui-testing-fake/SKILL.md +43 -0
  56. package/skills/ui-testing-web/SKILL.md +520 -0
  57. package/skills/ui-testing-web/manifests/declared-capabilities.json +903 -0
  58. package/skills/ui-testing-web/references/contracts/capability.md +68 -0
  59. package/skills/ui-testing-web/references/contracts/evidence.md +41 -0
  60. package/skills/ui-testing-web/references/contracts/operation.md +44 -0
  61. package/skills/ui-testing-web/references/core/dynamic-visual.md +123 -0
  62. package/skills/ui-testing-web/references/core/fallback.md +83 -0
  63. package/skills/ui-testing-web/references/core/network-and-state.md +114 -0
  64. package/skills/ui-testing-web/references/core/page-identity.md +91 -0
  65. package/skills/ui-testing-web/references/core/report-template.md +144 -0
  66. package/skills/ui-testing-web/references/core/reporting.md +92 -0
  67. package/skills/ui-testing-web/references/core/safety.md +12 -0
  68. package/skills/ui-testing-web/references/core/selection.md +26 -0
  69. package/skills/ui-testing-web/references/core/tool-routing-and-limits.md +198 -0
  70. package/skills/ui-testing-web/references/core/verdict-examples.md +96 -0
  71. package/skills/ui-testing-web/references/core/verdict-gate.md +105 -0
  72. package/skills/ui-testing-web/references/core/verification.md +19 -0
  73. package/skills/ui-testing-web/references/core/workflow.md +16 -0
  74. package/skills/ui-testing-web/references/platforms/index.md +19 -0
  75. package/skills/ui-testing-web/references/platforms/web.md +17 -0
  76. package/skills/ui-testing-web/references/scenarios/annotations.md +104 -0
  77. package/skills/ui-testing-web/references/scenarios/functional.md +205 -0
  78. package/skills/ui-testing-web/references/scenarios/visual-motion.md +170 -0
  79. package/skills/ui-testing-web/references/tiers/t1-programmatic.md +25 -0
  80. package/skills/ui-testing-web/references/tiers/t2-structured.md +61 -0
  81. package/skills/ui-testing-web/references/tiers/t3-static-visual.md +45 -0
  82. package/skills/ui-testing-web/references/tiers/t4-dynamic-visual.md +58 -0
  83. package/skills/ui-testing-web/templates/capability-note.md +23 -0
  84. package/skills/ui-testing-web/templates/platform.md +30 -0
  85. package/skills/ui-testing-web/templates/regression-case.md +15 -0
  86. package/skills/ui-testing-web/templates/scenario.md +13 -0
  87. package/targets/fake/adapter.js +1163 -0
  88. package/targets/fake/fixtures.js +177 -0
  89. package/targets/web/adapter.js +1231 -0
  90. package/targets/web/provider.js +415 -0
  91. package/vision-baseline.js +1254 -0
  92. package/vision-t3.js +2657 -0
@@ -0,0 +1,144 @@
1
+ # 报告模板:机器可读 JSON 与 Markdown 同源
2
+
3
+ > 同一份结果输出两个视图:`report.json`(机器可读、可 diff)与 `REPORT.md`(人读)。
4
+ > 字段语义见 [`reporting.md`](reporting.md);判定规则见 [`verdict-gate.md`](verdict-gate.md)。**两处字段名必须完全一致**,Markdown 只是同一对象的表格化投影。
5
+
6
+ ## 1. JSON 骨架
7
+
8
+ ```json
9
+ {
10
+ "schema": "dsh-ui-testing/report-v1",
11
+ "task": {
12
+ "task_ref": "任务/题目来源的稳定引用(不含答案)",
13
+ "objective": "被测目标与授权范围",
14
+ "target": { "url": "…", "title": "…", "heading": "…" },
15
+ "environment": {
16
+ "runtime": "headless-chromium | headed",
17
+ "gpu": "hardware | software(SwiftShader) | unknown",
18
+ "viewport": { "width": 1280, "height": 800, "scale": 1, "dpr": 1 },
19
+ "tab": "primary",
20
+ "notes": []
21
+ }
22
+ },
23
+ "summary": {
24
+ "cases": 0,
25
+ "pass": 0, "fail": 0, "blocked": 0, "inconclusive": 0, "not_run": 0,
26
+ "coverage": { "full": 0, "partial": 0, "blocked": 0 }
27
+ },
28
+ "cases": [
29
+ {
30
+ "case_id": "case-01",
31
+ "assertion": "这条断言问什么(一句话)",
32
+ "expected_contract": { "text": "验收条件", "source": "契约来源或 \"未提供\"" },
33
+ "observation": "实际事实(含对象/时间/数值)",
34
+ "evidence_ids": ["actionId 或 sessionId 等"],
35
+ "evidence_state": "complete | partial | missing",
36
+ "counterexamples": [ { "observation": "反例现象", "disposition": "为何不影响本判定" } ],
37
+ "coverage": "full | partial | blocked",
38
+ "coverage_gaps": ["替代路径仍缺的原始断言"],
39
+ "verdict": "PASS | FAIL | BLOCKED | INCONCLUSIVE | NOT_RUN",
40
+ "reason": "判定理由(一段话)",
41
+ "attribution": {
42
+ "layer": "T1 | T2 | T3 | T4 | P0 | ENV",
43
+ "kind": "MODEL_REASONING | SKILL_GUIDANCE | TOOL_CAPABILITY | ENVIRONMENT | TEST_DESIGN_OR_SPEC | UNKNOWN",
44
+ "confidence": "CONFIRMED | PROBABLE | HYPOTHESIS | UNKNOWN"
45
+ },
46
+ "limitations": []
47
+ }
48
+ ],
49
+ "findings": [
50
+ { "finding_id": "F-01", "case_id": "case-01", "summary": "缺陷一句话", "severity": "high | medium | low", "duplicate_of": null }
51
+ ],
52
+ "alternative_paths": [
53
+ { "case_id": "case-01", "path": "browser_tabs.open 自建标签", "replaces": "原生 target=_blank 流程", "missing_assertions": ["opener 关系", "焦点归属"] }
54
+ ],
55
+ "blocked": [
56
+ { "case_id": "case-01", "attempts": [], "error": "[CODE] 摘要", "minimal_repro": "可复跑输入", "alternative_verified": [] }
57
+ ],
58
+ "evidence_index": [
59
+ { "kind": "screenshot | frame | network-jsonl | network-har | product", "path": "相对路径", "sha256": "…", "captured_at": "ISO8601", "page": { "url": "…", "title": "…" } }
60
+ ]
61
+ }
62
+ ```
63
+
64
+ ## 2. 字段规则(两视图都要满足)
65
+
66
+ | 字段 | 规则 |
67
+ | --- | --- |
68
+ | `expected_contract.source` | 必须有来源;没有就写 `"未提供"`,此时 `verdict` 只能是 `INCONCLUSIVE`/`UNKNOWN`,不得 PASS/FAIL |
69
+ | `evidence_ids` | PASS/FAIL 至少 1 条;`observation` 每个关键数字都要能在证据里找到出处 |
70
+ | `counterexamples` | 出现异常词(重复/旧值/未变化/白色/闪烁/409/冲突/超时/0 项…)就必须有处置条目 |
71
+ | `coverage` | `partial` 必须有非空 `coverage_gaps`;`blocked` 还要有 `blocked` 段四件套 |
72
+ | `coverage ↔ verdict` | 写了 `limitation`(无法验证 X)就不能 PASS |
73
+ | `findings` ↔ `cases` | 每条 finding 至少映射一个 `FAIL`;重复现象用 `duplicate_of` 指向首条,不重复计数 |
74
+ | `summary` | 由 `cases` 自动汇总,手写数字必须与逐项一致 |
75
+ | `evidence_index.path` | 只写持久根内的**相对**路径;暂存绝对路径不得入索引(会被当持久引用) |
76
+ | `environment` | 单列,不写进 `observation`;软件 GPU/headless 只作环境说明,不单独构成缺陷理由 |
77
+
78
+ ## 3. Markdown 投影(同源,不另写结论)
79
+
80
+ ````markdown
81
+ # UI 测试报告
82
+
83
+ 环境:headless-chromium / software(SwiftShader) / 1280×800 @1 / primary
84
+ 目标:<url> — <title>
85
+
86
+ ## 概览
87
+ | cases | pass | fail | blocked | inconclusive | not_run | coverage(full/partial/blocked) |
88
+ |---|---|---|---|---|---|---|
89
+ | 3 | 1 | 1 | 0 | 1 | 0 | 1/2/0 |
90
+
91
+ ## case-01 · <断言>
92
+ - 预期契约:<text>(来源:<source>)
93
+ - 观察:<observation>
94
+ - 证据:<evidence_ids>(evidence_state=complete)
95
+ - 反例处置:<counterexamples>
96
+ - 覆盖:full
97
+ - 判定:**PASS** — <reason>
98
+ - 归因:T2 / MODEL_REASONING / CONFIRMED
99
+ - 限制:<limitations 或 —>
100
+ ````
101
+
102
+ 要点:Markdown 的每一行都必须来自 JSON 的对应字段,**不得在 Markdown 里新增未入 JSON 的结论**;反过来 JSON 里也不要放 Markdown 独有的"备注"。
103
+
104
+ ## 4. 最小示例(合成)
105
+
106
+ ```json
107
+ {
108
+ "schema": "dsh-ui-testing/report-v1",
109
+ "task": {
110
+ "task_ref": "synthetic-example",
111
+ "objective": "检查表单提交后的状态反馈",
112
+ "target": { "url": "http://127.0.0.1:3000/form", "title": "示例表单", "heading": "示例表单" },
113
+ "environment": { "runtime": "headless-chromium", "gpu": "software(SwiftShader)", "viewport": { "width": 1024, "height": 768, "scale": 1, "dpr": 1 }, "tab": "primary", "notes": [] }
114
+ },
115
+ "summary": { "cases": 1, "pass": 0, "fail": 1, "blocked": 0, "inconclusive": 0, "not_run": 0, "coverage": { "full": 1, "partial": 0, "blocked": 0 } },
116
+ "cases": [
117
+ {
118
+ "case_id": "case-01",
119
+ "assertion": "必填项为空时提交应被拒绝并给出提示",
120
+ "expected_contract": { "text": "空必填项提交返回错误提示,且不产生后端写入", "source": "接口文档 §x + 题目原文" },
121
+ "observation": "点击提交后出现错误提示;网络无写请求;字段保持空值",
122
+ "evidence_ids": ["act_…", "session_…", "networkSessionId=… seq=7"],
123
+ "evidence_state": "complete",
124
+ "counterexamples": [{ "observation": "提交按钮短暂 disabled", "disposition": "属于提交中的正常交互反馈,未产生写入,不构成缺陷" }],
125
+ "coverage": "full",
126
+ "coverage_gaps": [],
127
+ "verdict": "FAIL",
128
+ "reason": "提示出现方向与契约相反:契约要求拒绝并保持原值,实测页面把空值写入本地草稿并显示“已保存”",
129
+ "attribution": { "layer": "T2", "kind": "MODEL_REASONING", "confidence": "CONFIRMED" },
130
+ "limitations": []
131
+ }
132
+ ],
133
+ "findings": [{ "finding_id": "F-01", "case_id": "case-01", "summary": "空必填项被当作已保存", "severity": "high", "duplicate_of": null }],
134
+ "alternative_paths": [],
135
+ "blocked": [],
136
+ "evidence_index": [{ "kind": "screenshot", "path": "output/capture/case-01.png", "sha256": "…", "captured_at": "2026-01-01T00:00:00Z", "page": { "url": "http://127.0.0.1:3000/form", "title": "示例表单" } }]
137
+ }
138
+ ```
139
+
140
+ ## 5. 生成顺序(避免自相矛盾)
141
+
142
+ 1. 先落 JSON(逐 case 填五元组),用脚本/人工跑 6 项交叉校验;
143
+ 2. 校验通过后再生成 Markdown 投影(只搬字段);
144
+ 3. 最后汇总 `summary`/`findings` 并与逐 case 对账;对不上就回去改 JSON,不在 Markdown 里打补丁。
@@ -0,0 +1,92 @@
1
+ # 报告与覆盖声明:让每条结论可复核
2
+
3
+ > 目标:任何人只看报告就能复现证据链,并知道**哪些断言真的验证过、哪些只是替代路径**。
4
+ > 字段模板(JSON 与 Markdown 同源)见 [`report-template.md`](report-template.md);判定门禁见 [`verdict-gate.md`](verdict-gate.md)。
5
+
6
+ ## 1. 每个 case 必备字段
7
+
8
+ | 字段 | 取值 | 含义与要求 |
9
+ | --- | --- | --- |
10
+ | `case_id` | 稳定短 id | 与题目/任务编号可对应;额外发现另起 id,不与必考项复用 |
11
+ | `expected_contract` | 文本 + `source` | 验收条件 + **契约来源**(题目原文/接口文档/页面声明);没有来源就写"未提供",此时不判 PASS/FAIL |
12
+ | `observation` | 事实文本/数值/读数 | 只写实际看到的;时间戳、对象、区域都要能定位 |
13
+ | `counterexamples` | 数组 | 每条写"现象 + 为何不影响本判定(或改判依据)";空数组要显式写 `[]` |
14
+ | `verdict` | `PASS` / `FAIL` / `BLOCKED` / `INCONCLUSIVE` / `NOT_RUN` | 只能由证据推出;`NOT_RUN` 不计入通过 |
15
+ | `coverage` | `full` / `partial` / `blocked` | 本 case 的**验证范围**完成度(见 §2);与 verdict 独立 |
16
+ | `evidence_state` | `complete` / `partial` / `missing` | 证据**是否取得并可复核**(见 §3) |
17
+ | `evidence_ids` | 数组 | 动作级 id:`actionId`/`sessionId`/`productId`/`dynamicSessionId`+`frameIds`/`networkSessionId`+`seq`;截图另附 `sha256` |
18
+ | `attribution` | `{layer, kind, confidence}` | 归因:层(T1/T2/T3/T4/P0/ENV)+ 类别 + 置信度(`CONFIRMED`/`PROBABLE`/`HYPOTHESIS`/`UNKNOWN`) |
19
+ | `limitations` | 数组 | 明确写出"无法验证 X";写了就**不能**该 case 判 PASS |
20
+
21
+ 常见 `attribution.kind`:`MODEL_REASONING`(读题/对象选择/证据到结论映射)、`SKILL_GUIDANCE`(流程缺失导致可复发)、`TOOL_CAPABILITY`(缺接口/生命周期/证据)、`ENVIRONMENT`(headless/软件渲染/无设备)、`TEST_DESIGN_OR_SPEC`(契约未明)、`UNKNOWN`。
22
+
23
+ ## 2. `coverage` 三态(覆盖范围,不是结论)
24
+
25
+ | 值 | 判定条件 | 报告写法 |
26
+ | --- | --- | --- |
27
+ | `full` | 契约要求的**每一项**断言都由**原生路径**证据覆盖 | 逐项列 evidence_id;可给 PASS/FAIL |
28
+ | `partial` | 有替代路径、或某子项缺证据、或只覆盖部分视图/尺寸/时序 | 必须写"替代了什么、仍缺哪条原始断言"(见 §4);verdict 最多 `PASS(partial)` 并在 limitation 注明,或 `INCONCLUSIVE` |
29
+ | `blocked` | 关键路径完全不可用(能力/权限/环境) | verdict=`BLOCKED` + 阻断证据(见 §5) |
30
+
31
+ `coverage=full` 与 `verdict=PASS` 同时成立才算"完整通过";`partial` 的 PASS 必须显式降级表述。
32
+
33
+ ## 3. `evidence_state` 三态(证据是否到手)
34
+
35
+ - `complete`:关键断言都有可复核证据(内容/字段/像素/帧),且未截断。
36
+ - `partial`:有证据但缺项(例如只有 UI 文本没有响应体、只有单帧没有时序、截图被截断/掉帧)。
37
+ - `missing`:关键证据未取得(工具失败、配额、能力缺失)。此时结论必须是 `BLOCKED`/`INCONCLUSIVE`,并写缺什么。
38
+
39
+ ## 4. 替代路径:必须声明"替代了什么、还缺什么"
40
+
41
+ | 替代路径 | 可以证明 | 仍缺的原始断言 | 写法 |
42
+ | --- | --- | --- | --- |
43
+ | `browser_tabs open` 自建标签 | 目标页面在新标签里的渲染/交互 | 原生的 `target=_blank`/`opener` 关系、焦点归属、postMessage 时序、触发动作与源页面 | `coverage:"partial"`,`limitation:["native-popup-not-observed"]` |
44
+ | `browser_http_request` 独立请求 | 接口契约(status/headers/body) | 页面是否真的发了同一请求(Cookie/凭据/时序/CORS 差异) | 写"接口契约已验证;页面链路未验证" |
45
+ | T3 `vision_act` 手工坐标 | 该坐标命中的顶层元素被点击 | 业务控件身份、可信派发语义 | `INCONCLUSIVE` 依赖;不能写"T2 交互已覆盖" |
46
+ | `browser_eval` 读/写页面值 | 页面内存状态 | 用户可见渲染、真实输入事件、网络副作用 | 不得写成"交互验证通过" |
47
+ | 手工构造 DOM/类名 | 布局假设 | 真实用户路径 | 只作成因线索,不作断言证据 |
48
+
49
+ 规则:替代路径**不能**把 `coverage` 抬高到 `full`;写了替代就必须写缺项,缺项与 verdict 一致(`verdict-gate.md` 第 5 项校验)。
50
+
51
+ ## 5. `BLOCKED` 的必附四件套
52
+
53
+ 1. **尝试过的动作**(工具名 + 关键参数 + 时间);
54
+ 2. **错误码/错误摘要**(`[CODE]` + `details` 关键字段);
55
+ 3. **最小复现输入**(URL/选择器/帧窗口/请求,能让人再跑一次);
56
+ 4. **已完成的替代验证范围**(做了什么、覆盖到哪、为什么仍不构成原断言证据)。
57
+
58
+ 缺任一项的 `BLOCKED` 视为证据不足,不能计入"受限通过"。
59
+
60
+ ## 6. 额外发现:先与必考/缺陷清单去重
61
+
62
+ - 新发现的 id 不得复用必考项 id;内容与已有条目**同一现象/同一根因**时,写"已计入 case X",不单列新发现(重复计数会稀释可信度)。
63
+ - 去重判据:同一页面对象 + 同一现象 + 同一时间窗 = 同一条;不同对象/不同契约 = 可以单列。
64
+ - 额外发现也要走五元组与 6 项校验,不能因为是"额外"就跳过证据。
65
+
66
+ ## 7. 数字与截图的一致性
67
+
68
+ - **数字**:金额/数量/耗时/比例必须来自响应体、帧 `sourceTimestamp`、`comparison.metrics`、DOM 读数等可指认来源;UI 文案只能标为"UI 显示值",不能反推服务端字段。
69
+ - **截图**:文件名/声明/内容三者一致。报告里写清 `sha256`、`capturedAt`、页面身份(url/title)、视口与 `scale`(`scaleSource:"view"` 还是 `"explicit"`)、`persist/out` 与否。暂存路径不能当持久引用。
70
+ - **帧**:写 `dynamicSessionId`/`motionSessionId`、`window` 或 `frameIds`、`verdict`+`resolvedThresholds`、`integrity`(dropped/evicted/truncated)、`roiSha256` 或交付方式。
71
+ - **网络**:写 `networkSessionId`、`seq`/`requestId`、body 三态、脱敏说明、导出相对路径。
72
+ - **T2**:写 `snapshotId`/`digest`(minted provenance)、`targets[].resolved`、`dispatch`、动作前后 `node_state`。
73
+
74
+ ## 8. 报告结构(与模板同源)
75
+
76
+ ```text
77
+ 1. 任务与目标(task_ref / target / 授权范围 / 环境:headless-无头、GPU、视口、DPR)
78
+ 2. 结果概览(pass/fail/blocked/inconclusive/not_run 计数;coverage 分布)
79
+ 3. 逐 case(§1 字段 + 证据引用 + 判定理由)
80
+ 4. 缺陷清单(每条映射到 case;同现象去重)
81
+ 5. 覆盖与限制(替代路径、未覆盖断言、环境限制)
82
+ 6. 附件索引(截图/帧/JSONL/HAR 的相对路径 + hash)
83
+ ```
84
+
85
+ ## 9. 提交前自检
86
+
87
+ - [ ] 每个 PASS/FAIL 都有 `evidence_ids` 与判定理由。
88
+ - [ ] 每个 `partial`/`blocked` 都写了缺项,且 verdict 与 limitation 一致。
89
+ - [ ] 缺陷清单与 case 一一对应,没有重复计分的同现象条目。
90
+ - [ ] 所有数字有来源;所有截图名与内容一致。
91
+ - [ ] 未执行项标 `NOT_RUN`;`INCONCLUSIVE`/`BLOCKED` 原样保留,没有为了好看降级成 PASS。
92
+ - [ ] 环境信息单列,没有把环境差异写成产品缺陷。
@@ -0,0 +1,12 @@
1
+ # 授权、所有权与安全(M0–M2 + T2)
2
+
3
+ 1. 只操作用户授权目标;URL 放行不构成授权,不绕过登录、CAPTCHA、访问控制或反滥用机制。
4
+ 2. single-owner-lease 只防同工作区并发写:page/URL/viewport/网络缓冲按 DSH 工作区隔离;Cookie/localStorage/cache 在同一 Chromium/profile 内共享,不是安全边界。空闲租约 15s、进行中保持;同工作区其他 session 返回 BUSY,不同工作区互不影响;state/capabilities 可诊断。无 exec 身份走 legacy,disposed 只释放对应 owner。
5
+ 3. 同一工作区的面板和 Agent 页面操作进入该工作区的串行队列;面板可改变该 page,操作前后复查。不要通过面板 HTTP/CDP 绕过敏捷 scope/owner;不同工作区不得互相读取或写入 page 状态。
6
+ 4. HTTP(S) 目标、DNS、最终 URL 与 Document 导航/重定向拦截:允许 loopback;默认阻断 RFC1918(DSH_UI_TESTING_ALLOW_PRIVATE=1 开放)、metadata/link-local、unspecified、multicast、credentials、已配置 DSH_WEB_URL origin。
7
+ 5. 以上不是完整网络沙箱:子资源、页面 fetch/WebSocket 不因 Document 拦截而获得同等限制;DNS rebinding 与校验/连接时序风险仍有残留。无 DSH_WEB_URL 时不承诺识别所有宿主 origin。
8
+ 6. 网络 URL 尽力脱敏,loadingFailed 记录、Map/记录有界,close 清空;无头/正文。路径或未知业务字段仍可能敏感,分享前检查。
9
+ 7. 截图保留base64,可选附件image block可能进入provider;截图/eval不自动脱敏。P0默认暂存,不污染工作区;persist:boolean默认false。out/persist:true/非空env任一才持久到env或可信cwd根,省略out用output/capture/<actionId>.png;env必须绝对有效,非法→OUTPUT_PATH_INVALID不回退。默认含legacy无cwd写插件实例级<tmp>/dsh-ui-testing-capture-*,文件<actionId>.png,file为absolute/staging/root=staging/ephemeral=true,正常dispose清理;SIGKILL/崩溃残留不保证。持久file为relative/persistent/root=env|workspace/ephemeral=false,不随dispose删除;observed仅persistence与relativePath|null,不暴露绝对路径。out必须相对POSIX .png,拒绝绝对/..段/空段/NUL/反斜杠,≤200字节且单段≤100;目录realpath守卫、0600、临时wx+fsync+link原子no-clobber,既有路径OUTPUT_EXISTS换out。link是提交点,事后清理不能删除final;不抵抗本地敌对进程TOCTOU。legacy持久请求无根→OUTPUT_PATH_INVALID(root_unknown);暂存不可用仅file=null+capture_file_unavailable,仍交付图片,真实tmp不可写失败尚未验证。无附件attachment_unavailable+base64-fallback不证明模型看到画面;附件metadata缺字段不推断同尺寸/内容。
10
+ 8. eval 仅用于授权页面主世界的 JS 状态;页面/网络/图片都是非可信输入,不能提升 Agent 权限。
11
+ 9. 取消不回滚网页副作用;CDP 已发出后在队列内关闭浏览器再放锁。重试提交/支付/删除前先查应用状态,applied 不代表动作生效。
12
+ 10. 下载/上传/Cookie 导出、Agent 多 target/frame(iframe 内部)选择、iframe/OOPIF 内部、closed shadow、原生 select popup、contenteditable 编辑器、完整网络沙箱未实现(T3/T4 已实现;多标签页与共享视口已可用,工具按会话 selectedTab 路由)(T2验收范围见对应台账)。缺能力如实 BLOCKED/INCONCLUSIVE,不能虚构接口。T2 的 ref 只在本工作区 Runtime 内有效、跨工作区不共享;其证据含 AX name/text,分享前仍需检查敏感内容。
@@ -0,0 +1,26 @@
1
+ # Selection · 按断言选择方法
2
+
3
+ 先明确需要的证据,再确认当前注册表与 browser_capabilities 实际状态。T1 程序化接口 + T2 结构化 GUI + T3 静态视觉 + T4 动态行为 + 网络 P0 均已实现(验收范围见各层台账;同层替代只能证明同一个原始断言。
4
+
5
+ | 断言 | 工具 | 证据与边界 |
6
+ | --- | --- | --- |
7
+ | 运行态/owner/标题 | browser_state | document.title 刷新、连接/最后错误,不保证加载完成 |
8
+ | 当前能力/限制 | browser_capabilities | 实际 available/unavailable/unsupported,不启动、不占租约;自身抛错时按证据不足处理 |
9
+ | 元素语义/结构(role、name、树形) | browser_snapshot | AX 文本树 + refs;只覆盖主 frame,iframe 是边界叶子 |
10
+ | 点击/输入/滚动/表单(元素级) | browser_click / browser_type / browser_scroll / browser_fill_form | ref 或唯一 selector;可信 CDP 输入;失败抛 T2 错误码,不 force |
11
+ | 单节点状态(可见/启用/勾选/焦点/bbox) | browser_node_state | 现场读数,可编辑值脱敏 |
12
+ | 异步条件(出现/消失/文本/值) | browser_wait_for | 三类互斥条件;超时抛 WAIT_TIMEOUT,page 不关闭 |
13
+ | 页面 JS 状态 | browser_eval | 可序列化值,不冒充点击/网络/CSSOM/动画;不冒充 T2 结构化协议 |
14
+ | 页面请求成功或失败 | browser_network | 响应及 loadingFailed、脱敏 URL,无头/正文;其他 owner BUSY |
15
+ | 元素计算样式 | browser_computed_style | 首匹配值,不证明像素/遮挡 |
16
+ | PNG采集/局部高密度证据 | browser_screenshot | 显式scale 0.1–4(省略跟随共享view.scale)/region画布CSS(O=0时同文档)/out相对.png;includeAnnotations?:boolean=false,true 叠加 Host 已接受的六形状(不含草稿/工具栏);用户指代标注时先 state.annotations 再带标注截图,默认截图与 T3/T4 原始源不含面板标注;PNG校验、capture.annotations/映射/文件/附件metadata/warnings;observed不等于本次图,provider另验;无T3/T4分析 |
17
+ | 原始事件序列(多点/组合键/滚轮) | browser_input | 事件数量,不证明生效;另查状态 |
18
+ | 颜色/遮挡成因/可读性/像素差异 | **T3**(`browser_vision_*`) | 用确定性算法取像素证据;T2 的 hit-test 只证明坐标命中 |
19
+ | 动画/时序/帧连续性 | **无 T4** | BLOCKED;单帧截图与 JS 读值不能冒充 |
20
+
21
+ 1. 拆分状态、样式、网络、副作用、视觉与动画断言。
22
+ 2. 查注册表、capabilities/state;静态台账不代表可用性,不绕过 BUSY/缺工具。
23
+ 3. 选择能提供足够证据的工具,记录参数、预期、限制。**元素级交互优先 T2**(元素语义、可信点击/输入、表单、等待),只有在 T2 工具缺失/抛 `UNSUPPORTED`/需要原始事件序列时才回落 T1,并说明回落理由。
24
+ 4. 执行并另行观察;失败按 fallback.md 分类,不因 ok/applied/dispatched 判 PASS。
25
+
26
+ 导航检查 errorText/最终 URL 仍不等待 load complete;另读 readyState/应用状态。点击成对派发,核对结果后再重试。T2 的 `dispatched:true` 只代表事件已发出,必须用 `browser_node_state`/`browser_wait_for`/页面真值断言。network 失败记录不代表完整接口报文;可见原始图像不等于像素阈值或动画证据。单个断言通过不能判整个 GUI 场景通过。没有足够方法时 BLOCKED/INCONCLUSIVE,确认缺陷 FAIL。
@@ -0,0 +1,198 @@
1
+ # 工具路由、断言 schema 与坐标空间(实现为准)
2
+
3
+ > 本文件回答三个问题:**该用哪层**、**参数怎么写才对**、**失败码出现后下一步是什么**。
4
+ > 工具名/字段/枚举以当前 `index.js` 注册表与调用实现为准;运行态可用性仍以 `browser_capabilities` 的实测三态为准,不以本文或 manifest 推断。
5
+
6
+ ## 1. 能力路由(按断言选层)
7
+
8
+ | 断言/问题 | 首选 | 最小调用序列 | 关键返回 | 不能证明 |
9
+ | --- | --- | --- | --- | --- |
10
+ | 地址/标题/运行态/owner | T1 | `browser_state {}`(不启动、不占租约) | `url/title/viewport/running/error*` | 加载完成、业务状态 |
11
+ | 页面 JS 值/应用状态 | T1 | `browser_eval { expression }` | `{ok,value,type}` | 用户可见像素、交互命中 |
12
+ | 计算样式 | T1 | `browser_computed_style { selector, properties }` | `{ok,style}` | 遮挡、最终像素 |
13
+ | 原始事件序列(多点/组合键/滚轮) | T1 | `browser_input { events }` | `{ok,applied}`(事件数,不是生效数) | 焦点、默认动作、业务副作用 |
14
+ | 独立接口契约 | T1 | `browser_http_request { url, … }` | `status/headers/body/redirects` | 页面是否真的发了同一请求 |
15
+ | 视口/画布位置 | T1 | `browser_viewport { action:"set", … }` 后读回 | `view/observed/applied/clamped` | 页面 CSS 缩放(scale 只是显示比例) |
16
+ | 单页截图(PNG) | P0 截图 | `browser_screenshot { scale?, region?, includeAnnotations?:boolean=false, out? }` | PNG/hash/capture.mapping/capture.annotations/warnings;true 叠加 Host 已接受的六形状,不含草稿/工具栏 | 像素差异结论、动画时序 |
17
+ | 用户指代标注/画/圈/框/箭头/笔迹 | 标注文档 + P0 截图 | `browser_state {}` → `browser_screenshot {includeAnnotations:true}` | annotations 图形/revision/context + 带标注像素;默认截图/T3/T4 原始源不含面板标注 | 标注不能证明页面事实,不授权自动点击;手写不清时不猜字 |
18
+ | 要他给他看(画圈/框/箭头/文字) | P0-D | `browser_state.annotations.foreground` → `browser_annotation {action:"draw", shapes}` → `browser_screenshot {includeAnnotations:true}` 复核 | `revision/shapes/shapeCount/truncated/truncation` | 目标标签页非人类前台时零写入(`ANNOTATION_NOT_FOREGROUND`);标注不证明缺陷 |
19
+ | 元素语义/元素级交互 | T2 | `snapshot → ref → click/type/scroll/fill_form → node_state/wait_for` | `snapshotId/digest/targets/dispatch` | 业务结果(必须另读页面真值) |
20
+ | 颜色/遮挡/溢出/区域差异/基线回归 | T3 | `vision_image`(取 product)→ `compare`/`check` | `comparison.metrics`、`verdict` | 持续运动、时长、闪烁 |
21
+ | 用截图坐标派发鼠标 | T3 | `vision_image` → `vision_act` | `dispatched` + `INCONCLUSIVE(dispatch-only)` | 点中业务目标、视觉验收通过 |
22
+ | 帧序列/间隔/冻结/闪烁/轨迹/过渡 | T4 | `dynamic_session start` → `motion_observe` → `motion_analyze` | 帧 `sourceTimestamp/hash/integrity`、`verdict` | 技术身份(CSS/Canvas/WebGL/video)、属性值 |
23
+ | A 是否导致 B | T4 + P0 | `dynamic_correlate { directions }` | `basis/grade` | 时间邻近不是因果 |
24
+ | 请求/响应/WS/SSE/拦截/重放/证据包 | P0 | `network_session start` → `events` → `detail` → `trace` | 事件时间轴、body 三态、integrity | 页面语义因果 |
25
+ | 多标签管理 | P0-E | `browser_tabs { action }` | `tab{id,runtimeId,selectionRevision}` | 跨 tab 证据聚合 |
26
+
27
+ ## 2. `browser_motion_analyze` 断言 schema(七类,逐字段)
28
+
29
+ 顶层参数(注册 schema):`motionSessionId`(必填)、`assertions`(必填,1–20 条)、`window` 与 `frameIds` **二选一**(同给 → `DYNAMIC_INVALID_ARGUMENT(window-and-frameIds-exclusive)`)。离线执行,不采帧、不 ensure、不续租。
30
+
31
+ 每条断言允许的键固定为:`id / type / region / masks / thresholds / expectedIntervalMs / query / expectation`(未知键拒绝;`id` 必填、同批唯一、≤64 字节)。
32
+
33
+ | type | 必填专属字段 | 专属字段的精确要求 | `thresholds` 允许键(默认值) |
34
+ | --- | --- | --- | --- |
35
+ | `frame-diff` | — | — | `pixelThreshold`(0–1, 0.1)、`changeRatio`(0–1, 0.01) |
36
+ | `region-change` | — | — | 同上 + `minArea`(1–16000000 整数, 4) |
37
+ | `flicker` | — | — | `pixelThreshold`(0.1)、`changeRatio`(0.2)、`stableRatio`(0.01)、`brightnessDelta`(0–255, 64)、`maxDurationMs`(0–10000, 100) |
38
+ | `freeze` | **`expectation`(对象)** | 见下 | `pixelThreshold`(0.1)、`stableRatio`(0.001)、`minDurationMs`(0–10000, 500) |
39
+ | `jank` | **`expectedIntervalMs`** | 有限数且 `> 0`;传 `null` 或非 jank 类型携带 → `DYNAMIC_INVALID_ARGUMENT` | `intervalFactor`(1–10, 2) |
40
+ | `trajectory` | **`query`(对象)** | 见下 | `maxStep`(1–1000000, 80) |
41
+ | `transition` | — | — | `pixelThreshold`(0.1)、`changeRatio`(0.01)、`stableRatio`(0.001)、`stableSamples`(2–20 整数, 3) |
42
+
43
+ `freeze.expectation` 的封闭形状(不是字符串!写成字符串必失败):
44
+
45
+ ```json
46
+ { "motionExpected": true,
47
+ "sourceEventId": "≤128 字节的事件 id",
48
+ "referenceEventIds": ["1–16 个、≤128 字节、不重复的参照事件 id"] }
49
+ ```
50
+
51
+ - `motionExpected` 必须**字面为 `true`**;`sourceEventId`、`referenceEventIds` 均必填。
52
+ - 语义:用可核验的"此处本应继续推进"的事件作参照;没有可核验参照就不要写 freeze 断言。
53
+
54
+ `trajectory.query` 两种形状:
55
+
56
+ ```json
57
+ { "method": "color", "color": [r,g,b], "tolerance": 0–255, "minArea": 1–16000000, "maxResults": 1–20 }
58
+ { "method": "template", "productId": "v1_<32hex>", "minScore": 0–1, "stride": 1–16, "maxResults": 1–20 }
59
+ ```
60
+
61
+ - `color`:三通道 0–255 整数;`tolerance` 默认 16、`minArea` 默认 4、`maxResults` 默认 20。
62
+ - `template`:`productId` 必须来自本工作区 product;`minScore` 默认 0.95、`stride` 默认 1。
63
+ - `region` / `masks` 对全部类型都可给,但**坐标是帧图像像素**(整数、x/y ≥0、宽高 ≥1、像素数 ≤4,000,000);`masks` ≤64 个 `{id, region}`。
64
+ - 单次分析共用 5000ms 算法预算:超时 → 结果 `BLOCKED(reason:dynamic-timeout)` + `remaining-assertions-not-run`。用 `frameIds`/`window` 抽帧降成本,不要抬阈值凑通过。
65
+ - `verdict` 严重度顺序 `FAIL > BLOCKED > INCONCLUSIVE > WARN > PASS`;`exitCode`:PASS/WARN=0、FAIL=1、INCONCLUSIVE/BLOCKED=2。
66
+
67
+ ## 3. `browser_dynamic_session` 配置(start 时唯一生效)
68
+
69
+ `action` ∈ `start|stop|status|reset|extend`。`config` 只接受这 10 个键:
70
+ `captureVisual / networkSessionId / source / encoding / durationMs / maxFrames / maxBytes / region / scale / sampleIntervalMs`。
71
+
72
+ | 键 | 视觉采集(`captureVisual:true`,默认) | 纯网络关联视图(`captureVisual:false`) |
73
+ | --- | --- | --- |
74
+ | `source` | **必填**,`screencast` 或 `screenshot-loop` | 禁止 |
75
+ | `encoding` | `screencast` 只允许 jpeg(显式要 png → `DYNAMIC_SOURCE_UNAVAILABLE`);`screenshot-loop` 只允许 png(显式要 jpeg 同上) | 禁止 |
76
+ | `region` | **canvas CSS px** 矩形;`screencast` 不支持(`DYNAMIC_SOURCE_UNAVAILABLE(screencast-mode-conflict)`) | 禁止 |
77
+ | `scale` | 0.1–2,默认 1;`screencast` 只接受 1 | 禁止 |
78
+ | `sampleIntervalMs` | 仅 `screenshot-loop` 必填,50–1000 整数;`screencast` 携带即 `DYNAMIC_INVALID_ARGUMENT` | 禁止 |
79
+ | `durationMs` | 1–60000 整数,默认 3000 | 禁止(视图无采集) |
80
+ | `maxFrames` | 1–300,默认 180 | 禁止 |
81
+ | `maxBytes` | 1–64 MiB,默认 32 MiB | 禁止 |
82
+ | `networkSessionId` | 可选;用于关联已有 P0 会话 | **必填**,且必须是本 scope 已存在的 P0 会话(否则 `DYNAMIC_SESSION_NOT_FOUND`) |
83
+
84
+ - `captureVisual:false` 是"纯关联视图":不启动浏览器、不采帧、不建 page、不占 page 租约,也不启动/停止 P0;同时给其它采集字段会被拒绝。
85
+ - 同 scope 只允许 1 个活动会话(`DYNAMIC_SESSION_ACTIVE`);`status`/`stop`/`reset` 不启动浏览器。
86
+ - `extend`:`durationMs` 1–60000/次,自 `startedAt` 起累计 ≤300000ms(超了 `DYNAMIC_LIMIT_EXCEEDED`),**仅 running 有效**;已停会话返回 `DYNAMIC_SESSION_NOT_ACTIVE` 且不复活。
87
+ - Agent 一次工具往返约 11.7s:多步取证要显式给足 `durationMs` 或中途 `extend`,否则观察窗口可能已结束(结论只能写采样不足)。
88
+
89
+ ## 4. `browser_motion_observe`(只读)
90
+
91
+ - 必填 `motionSessionId`;`limit` 1–200(默认 50)。查询组合按实现:`cursor` 与 `sinceSeq` 互斥;`frameIds` 与 `window`/`cursor`/`sinceSeq` 互斥;`fresh:true` 不能与 `sinceSeq`/`cursor`/`window`/`frameIds` 同用;`window` 可与 `sinceSeq` 同时给出(取交集,以返回的 `fromSeq/toSeq` 为准)。
92
+ - `includeImages:true` 最多命中 **3 帧**;`fresh:true` 是唯一显式采样动作,只允许当前活动的视觉会话。
93
+ - `region`:只交付该矩形(crop-on-delivery,需同时 `includeImages:true`),**坐标是帧图像像素(整数)**,越界/缺 `includeImages` → `DYNAMIC_INVALID_ARGUMENT`;裁剪结果附 `crop{region,sourceSha256,sourceDimensions,sourceEncoding,roiSha256,outputBytes}`,`roiSha256` 与整帧 `encodedSha256` **不是一回事**。
94
+ - 只读查询不 ensure、不续租、不启动浏览器;帧被淘汰/丢弃/截断要写在结论里,不能静默忽略。
95
+ - `region` 已在 `browser_motion_observe` 的注册 schema 中声明,按上述规则使用即可,不需要假设宿主会拒绝该字段。
96
+
97
+ ## 5. `browser_dynamic_correlate`
98
+
99
+ - 必填 `dynamicSessionId`;首次调用至少再给 `motionSessionId` 或 `networkSessionId` 之一,且必须属于该动态会话。
100
+ - `directions` ∈ 六向:`operation->visual`、`operation->network`、`network->visual`、`visual->network`、`network->network`、`visual->visual`(不得重复)。
101
+ - `beforeMs` 0–5000(默认 250)、`afterMs` 0–5000(默认 1000);`limit` 1–200(默认 50);`includeTemporal` 默认 `false`(只回时间邻近、不混入因果)。
102
+ - `basis` → `grade`:`explicit`/`redirect`/`initiator` = `confirmed-causal`;`observed` = `observed-association`;`temporal` = `temporal-proximity`(默认过滤)。
103
+ - 固定 `verdict=INCONCLUSIVE(no-assertion)`:本工具给关联,不给"因果成立"的产品结论;无共同 ID/协议父端点只能进 `unresolved`。
104
+
105
+ ## 6. 网络 P0 参数要点
106
+
107
+ - `browser_network_session`:`start` 是唯一懒启动动作;`config` 只接受 `captureBodies/captureWebSocket/captureSse/captureWorkers/maxEvents/maxBodyBytes/maxTotalBytes/maxWsFrames/businessStatusPath/maskRules`;上限 `maxEvents ≤ 20000`、`maxBodyBytes ≤ 1 MiB`、`maxTotalBytes ≤ 32 MiB`、`maxWsFrames ≤ 20000`;同名 `start` 幂等(`changed:false`),不同名运行中 → `NET_SESSION_ACTIVE`。
108
+ - `browser_network_events`:`view` ∈ `summary|full|timeline|aggregate`;`groupBy` 仅 `aggregate` 需要;`limit` 1–200(默认 50);`filter.phase` 取值见下表;`cursor` 与 `sinceSeq` 二选一,指向已淘汰 seq → `gap`。
109
+ - 事件 `kind` ∈ `http|ws|sse|marker`;`phase` ∈
110
+ `request|redirect|response|data|finished|failed|extra-info`、
111
+ `ws-created|ws-handshake|ws-send|ws-receive|ws-error|ws-closed`、
112
+ `sse-message|mark|step-begin|step-end|evidence-link|control|session-meta`。
113
+ - `browser_network_detail`:`requestId`/`seq` 恰一;`include` 缺省除 body 外全部;body 三态 `captured|empty|unavailable`,读不到就 `available:false`(`NET_BODY_UNAVAILABLE`),纯只读、不为此启动 CDP。
114
+ - `browser_network_trace`:`action` ∈ `begin-step|end-step|mark|link|window|query|reset`,全部 Host 内存操作、不启动浏览器;窗口归属是 `basis:"temporal"` 派生,不改写事件。
115
+ - `browser_network_control`:`action` ∈ `throttle|offline|intercept-add|intercept-remove|intercept-clear|intercept-list|hold|resume|replay|mock|reset`;规则 ≤32、同 id `NET_RULE_CONFLICT`;`hold` ≤64 且超时自动放行并计数(`NET_CONTROL_TIMEOUT` 不抛错);`reset` 不得 `Fetch.disable`(导航守卫保留)。
116
+ - `browser_network_evidence`:`action` ∈ `export|import|index|search|link|integrity|clear|list`;`format` ∈ `jsonl|har|auto`;`out` 必须是持久根内相对路径(否则 `NET_OUTPUT_ROOT_UNKNOWN`/`NET_OUTPUT_PATH_INVALID`);导入会话为 `state:"snapshot"`,不可 control/replay(`NET_CONTROL_UNAVAILABLE`)。
117
+ - `browser_network_subscribe`:`action` ∈ `create|poll|ack|close|list`;每 scope 订阅 ≤16、pin 1000 条;超出给 `gap/dropped` 不许静默。
118
+
119
+ ## 7. 失败码 → 下一步(只列允许动作)
120
+
121
+ | 错误码(层) | 含义 | 允许的下一步 | 禁止 |
122
+ | --- | --- | --- | --- |
123
+ | `REF_STALE`(T2) | ref 未知/LRU 淘汰/文档代次变化/节点替换 | 重新 `browser_snapshot` 取新 ref | 猜编号、复用旧 ref、改坐标硬点 |
124
+ | `TARGET_NOT_FOUND`(T2) | selector 0 命中;或多标签 selection 指向已关闭 child(`reason:selected-tab-closed`,`fallbackTabId:primary`) | 检查 selector;后者用 `browser_tabs current/select` 确认 | 取"看起来像"的节点;忽略 reason |
125
+ | `TARGET_NOT_UNIQUE`(T2) | selector 多命中(含隐藏副本) | 改 ref 或更具体 selector | 取首个匹配 |
126
+ | `NOT_INTERACTABLE`(T2) | hidden/disabled/covered/零面积/离视口/运动/不可编辑/焦点或值不匹配 | 记 `FAIL`(或按断言判 `BLOCKED`);hidden/covered 可用 T3 给成因;`unstable` 走 T4 | force/JS click、改坐标、换相似节点、抖动等待 |
127
+ | `WAIT_TIMEOUT`(T2) | 条件未在预算内成立(page 不关闭) | 复核条件写法;记 `FAIL`/`INCONCLUSIVE` | 缩小 `timeoutMs` 掩盖、把超时当"不存在" |
128
+ | `UNSUPPORTED`(T2/T4) | 控件/适配器不支持(contenteditable、number/date/file、closed shadow、iframe 内部、非 WAAPI 适配器) | 写 `BLOCKED`;或 T1 替代并在报告声明强度不同 | 假装 T2 已完成;虚构接口 |
129
+ | `BUSY`(全层) | 同 tab 有其它 owner(idle 15s) | 等释放后用 `state/capabilities` 诊断,再重试 | 绕面板 HTTP/CDP |
130
+ | `VIEWPORT_CONFLICT`(T1) | `expectedRevision` CAS 失败,patch 零应用 | 读最新 `view` 再决定是否重新提交 | 自动重放旧 patch |
131
+ | `VISION_STALE_IMAGE` / `VISION_HIT_MISMATCH`(T3 act) | 图过期(>30s/代次/滚动/视口变化/重采样 hash 不符)或命中不一致 | 重新 `vision_image` 取新 product 再派发 | 回退点、换坐标凑命中 |
132
+ | `VISION_SIZE_MISMATCH`(T3 compare) | 两图尺寸不同 | 同视口/同 scale 重采同一区域 | 强制比较/缩放后比 |
133
+ | `VISION_EMPTY_COMPARISON`(T3 compare) | ROI 被 mask 全排除(无分母) | 扩 ROI 或减 mask | 写 `similarity=1` |
134
+ | `VISION_SOURCE_NOT_FOUND`(T3) | product 不存在/LRU/跨 scope/重启丢失 | 重新采 `vision_image` | 换 scope 读取 |
135
+ | `VISION_BASELINE_*`(T3 基线) | 根不可用 / 名字非法 / 已存在 / 无此基线 / CAS 冲突 / 读失败 / 写失败 | 配可信持久根;换 name;读 HEAD revision 后重提交;`READ/WRITE_FAILED` 按 reason 处理 | 静默回退暂存、覆盖已有基线 |
136
+ | `CAPTURE_FAILED` / `INVALID_PNG` / `CAPTURE_SIZE_MISMATCH` / `CAPTURE_UPSCALED` / `CAPTURE_TOO_LARGE` | 截图采集/校验失败 | 保留 expected/actual;降 scale/缩 region 重采 | 交付坏图/尺寸异常图 |
137
+ | `OUTPUT_PATH_INVALID` / `OUTPUT_EXISTS` / `OUTPUT_WRITE_FAILED` | 持久路径问题 | 修相对 `.png`/env 根;换 out 名;核对发布事实 | 覆盖已有路径 |
138
+ | `HTTP_TIMEOUT` / `HTTP_FAILED` / `HTTP_REDIRECT_LIMIT`(独立 HTTP) | 超时/网络失败/重定向超限 | 缩短任务、核对 URL;副作用未知先查状态 | 自动重试写操作 |
139
+ | `NET_SESSION_ACTIVE` | 不同名会话运行中 | 复用现有 `sessionId` 或先 `stop` | 强开第二个会话 |
140
+ | `NET_SESSION_NOT_FOUND` | 无会话 | `session start`(懒启动) | 用 `snapshot` 会话做 control |
141
+ | `NET_BODY_UNAVAILABLE` | body 未采到/被淘汰/配额不足 | 报告写原因码;必要时提高 `captureBodies`/配额后重放 | 伪造空体、用 UI 文本反推报文 |
142
+ | `NET_EVENT_NOT_FOUND` / `NET_QUOTA_EXCEEDED` / `NET_RULE_INVALID` / `NET_RULE_CONFLICT` | 事件已淘汰 / 超配额 / 规则非法或冲突 | 用 `cursor`/`gap` 重查;调小采集面;改规则 id | 假装事件存在 |
143
+ | `NET_OUTPUT_ROOT_UNKNOWN` / `NET_OUTPUT_PATH_INVALID` | 持久根缺失/路径非法 | 用持久根内相对路径 | 写暂存绝对路径 |
144
+ | `DYNAMIC_INVALID_ARGUMENT` | 断言/配置 schema 错(必填、互斥、枚举、未知键) | 按 §2–§3 修正后零成本重试 | 猜字段名、把失败当"没有异常" |
145
+ | `DYNAMIC_LIMIT_EXCEEDED` | 断言/会话/帧/字节/ID 数量超上限 | 缩规模或新会话 | 抬内部预算掩盖 |
146
+ | `DYNAMIC_SESSION_NOT_FOUND` / `NOT_ACTIVE` / `ACTIVE` | 会话不存在/已停(`extend` 不复活)/已有活动会话 | 重新 `start`(给足 `durationMs`);先 `stop` 旧会话 | 复用已停 motionSessionId |
147
+ | `DYNAMIC_SOURCE_UNAVAILABLE` | screencast 不支持 png/region/scale≠1,或核心不可用 | 换 `screenshot-loop`(PNG 精确)或去掉不支持字段 | 静默降级后宣称精确 |
148
+ | `DYNAMIC_CONTROL_CONFLICT` / `DYNAMIC_RESTORE_FAILED` | 目标/字段被外部改动,恢复冲突 | 重新定位目标;如实报告 `restoreStatus` | 覆盖外部新状态 |
149
+ | `DYNAMIC_EVENT_NOT_FOUND` | frame/event id 不属于本会话 | 用 `motion_observe` 重新取 id | 跨会话使用 id |
150
+ | `TAB_NOT_FOUND` / `TAB_LIMIT` / `TAB_FORBIDDEN` / `TAB_CONTROL_CHANGED` / `TAB_OWNERSHIP_STALE` / `TAB_IDENTITY_UNAVAILABLE`(P0-E) | 标签不存在或跨 root(统一 not-found)/超 child 或全局 8/同 root 但角色或归属不允许/控制权或 CAS 版本不匹配/身份无法证明 | 重新 `list` 选 tab;关掉不需要的 child;读 `control` 的最新版本再决策(`TAB_CONTROL_CHANGED` 不自动重放) | 用"能看见"推断"能写";把 BUSY 当权限结论 |
151
+
152
+ ## 8. 坐标空间对照表(最容易错的地方)
153
+
154
+ | 参数 / 字段 | 所属空间 | 说明 |
155
+ | --- | --- | --- |
156
+ | `browser_screenshot.region` | **canvas CSS px** | `O=0` 时与文档 CSS 相同;`O≠0` 时先截真实帧再白底合成(`capture.canvas.composite=true`,blank 为纯白 `#ffffff`);`mapping.cssPerPixel/scrollAtCapture` 是换算依据 |
157
+ | `browser_input` 的 `x/y` | **viewport CSS px** | CDP Input 坐标;元素级操作优先 T2,不要用它猜元素位置 |
158
+ | T2 `bbox` / `hitTarget` / 动作 `point` | **viewport CSS px** | 来自 `getBoundingClientRect()`;滚动后变化,动作前现读 |
159
+ | `browser_viewport` 的 `x/y` | **文档 CSS px** | 页面顶层滚动位置(实测回读、可能被 clamp) |
160
+ | `browser_viewport` 的 `canvasX/canvasY` | **画布坐标** | 视口左上角在文档画布上的位置(±1e7,可为负) |
161
+ | T3 `Source.live.region` | **文档 CSS px** | 采集前的 live 裁剪区域 |
162
+ | T3 `vision_image.region` / `vision_find.region` / `vision_compare.region` / `vision_check` 的 assertion region、`masks`、`annotations` | **图像像素(整数)** | 相对完整源图;`vision_act.point/to` 是连续图像坐标(像素中心传 `i+0.5`);`vision_check` 的 case `source.live.region` 仍按文档 CSS 解释 |
163
+ | T4 `dynamic_session.config.region` | **canvas CSS px** | 截图区域;`screencast` 不支持 |
164
+ | T4 `motion_observe.region`、`assertions[].region/masks` | **帧图像像素(整数)** | 帧证据里以 `frame.dimensions` 为准,不是视口 CSS |
165
+ | T4 帧 `mapping` | 混合 | `space:"canvas-css-px"`、`viewport`(=画布位置)、`scroll`、`canvasOffset{O=C−S}`、`coordinateSpace:"document-css-px"`、`originCss`、`cssPerPixel{x,y}`、`imagePixels` |
166
+ | 面板标注 `shapes` | **画布 CSS px** | 页面坐标 `p = d − S`(`S` = 当前 `view.x/y`,不是发布时的 view) |
167
+
168
+ 换算公式(`C` = `view.canvasX/Y`,`S` = `view.x/y`,`O = C − S`;`d` = 画布坐标,`q` = 视口内偏移,`p` = 文档滚动坐标):
169
+
170
+ ```text
171
+ O = C - S # 画布偏移;O=0 时画布坐标 = 文档坐标
172
+ q = d - C # 画布点 → 视口内偏移(browser_input 用)
173
+ p = q + O = d - S # 视口偏移 → 文档滚动坐标(也用于标注 shapes)
174
+ d = v + C # 视口坐标 v(T2 bbox)→ 画布坐标(screenshot region 用)
175
+ imagePx = (docCss - originCss) * cssPerPixel # 文档 CSS → 帧图像像素(用该帧 mapping)
176
+ ```
177
+
178
+ 例(`v` = T2 `bbox` 的视口坐标,`S`/`C` 取自 `browser_viewport` 的 `view`):
179
+
180
+ ```text
181
+ 情况 1:C=S=(0,0) → O=0,d=p;screenshot region 起点 = v
182
+ 情况 2:C=(300,200), S=(0,0), v=(120,80)
183
+ → O=(300,200);画布 d=(420,280)(screenshot region 起点);p=v=(120,80);q=d−C=(120,80)
184
+ 情况 3:C=(300,200), S=(40,10), v=(120,80)
185
+ → O=(260,190);画布 d=(420,280);文档 p=v+S=(160,90);q=d−C=(120,80)=p−O
186
+ ```
187
+
188
+ ## 9. 其它硬限额速查(写报告时直接引用)
189
+
190
+ - 截图:`scale` 0.1–4(省略跟随 `view.scale`);输出 ≤16,000,000 像素;`region` 宽高 ≥1 CSS px;`out` 必须是工作区相对 `.png`;`persist` 非布尔 → `INVALID_ARGUMENT`。
191
+ - 视口:宽高 200–4096 整数;`scale` 0.1–2;`canvasX/canvasY` ±10,000,000;`expectedRevision` CAS。
192
+ - T3:product 每 scope 16 张 / 单张 32 MiB / 16M 像素 / 每 scope 合计 128 MiB;evidence JSON ≤262144 字节、`regions` ≤100;`vision_act` 只接受 ≤30s 的 capture。
193
+ - T4:断言 ≤20;`masks` ≤64;`region` 像素 ≤4,000,000;帧 ≤180(硬 300)、字节 32/64 MiB;`includeImages` ≤3;算法预算 5000ms;`correlate limit` ≤200。
194
+ - T2:ref 表 2000 项 LRU;`snapshot maxNodes` 1–2000、`depth` 0–32;`wait_for timeoutMs` 0–30000;`fill_form` 1–20 项、文本合计 ≤65536 字节。
195
+ - 网络:`events limit` ≤200;会话 `maxEvents` ≤20000、`maxBodyBytes` ≤1 MiB、`maxTotalBytes` ≤32 MiB、`maxWsFrames` ≤20000;规则 ≤32、`hold` ≤64、订阅 ≤16。
196
+ - 独立 HTTP:总超时 1–20000ms(默认 5000)、保留正文 1–1048576 字节(默认 65536)、重定向 ≤5 跳、body ≤64 KiB。
197
+ - 标注(P0-D):`draw.shapes` 每次 1–64;`erase.ids` 1–64、`point.radius` 默认 8 画布 px;文档 `maxShapes` 128、单笔画笔 512 点、文档总点数 8192、文字 200 字符、文档 65536 字节(Host 确定性裁剪并回 `truncated`/`truncation`);`expectRevision` CAS → `ANNOTATION_REVISION_CONFLICT`;前台心跳窗口约 1.5s。
198
+ - 多标签:页面组按 (workspace, provider, 团队根) 分组,每组一个 primary 槽;child 最多 3 个按 (workspace, provider) 跨 root 合计,全局 live 8;短租约 idle 15s 只表示"短暂忙"(观察不占写租约),写权限由 root/角色/控制权决定。
@@ -0,0 +1,96 @@
1
+ # 判定范例与反例集(合成场景,非任何靶机答案)
2
+
3
+ > 目的:训练"**差异 ≠ 缺陷**"的分界,避免把所有异常现象都判成 FAIL,也避免把真实缺陷解释成设计。
4
+ > 范例全部是**合成的一般场景**;不引用任何具体被测站点、用例编号、组件名或产品文案。判定终检见 [`verdict-gate.md`](verdict-gate.md)。
5
+
6
+ ## 0. 先问三个问题
7
+
8
+ 任何"看起来不对"的现象,按顺序问:
9
+
10
+ 1. **契约怎么说?** 需求/接口文档/页面声明是否明确允许这种表现(最终一致、幂等重放、装饰动画、静态内容、冲突提示)?
11
+ 2. **用户可见结果受影响吗?** 影响可读性/金额/状态/可操作性,还是只是实现细节的差异?
12
+ 3. **证据够吗?** 是否覆盖了对象、时间窗、采样规格;能否复现?
13
+
14
+ 三问答完再给 verdict:**契约允许 + 无可见影响 → 不构成缺陷**;**契约不允许 + 有可见影响 + 证据充分 → 缺陷**;**契约不明/证据不足 → `INCONCLUSIVE`**。
15
+
16
+ ## 1. 正常 SSE 重放 vs 重复渲染缺陷
17
+
18
+ | | 正常(不判缺陷) | 缺陷(判 FAIL) |
19
+ | --- | --- | --- |
20
+ | 场景 | 断线重连后,服务端按契约重放最近若干条事件;客户端按 `eventId` 幂等/去重 | 重连后 UI 把重放事件当新事件追加 |
21
+ | 观察 | 网络层出现重复 `eventId`;UI 条目数不变、无重复条目、计数不翻倍 | UI 条目重复/计数翻倍;或同一操作触发两次副作用(重复提交) |
22
+ | 需要的契约 | "允许重放 + 客户端去重/幂等"的来源 | 契约要求唯一/幂等,且未实现 |
23
+ | verdict | `PASS`;`counterexamples` 写"网络层重复投递被 UI 去重吸收(契约允许)" | `FAIL`;附 eventId 序列 + UI 条数前后对比快照 |
24
+ | 判相反需要 | 证明 UI 真的去重(快照/节点读数),并把"允许重放"的来源写进 `expected_contract` | 证明重复来自重放而非用户重复操作(动作记录 + 请求次数) |
25
+
26
+ 常见误判:只数网络事件条数就写"重复投递=缺陷"。**网络层重复与用户可见重复是两件事。**
27
+
28
+ ## 2. 允许的延迟同步 vs 未收敛缺陷
29
+
30
+ | | 正常(不判缺陷) | 缺陷(判 FAIL) |
31
+ | --- | --- | --- |
32
+ | 场景 | 契约写明"最终一致,收敛窗口 ≤N 秒";多视图在窗口内先后更新 | 契约要求实时/窗口内收敛,但某视图长期不更新或永远不更新 |
33
+ | 观察 | t0 视图 A 旧值,t0+2s 更新;视图 B 在窗口内跟上;无报错 | 超出契约窗口仍旧值;或某一视图永不更新;或刷新后才更新(说明未推送) |
34
+ | 需要的契约 | 收敛窗口/最终一致的来源 | 实时性要求或收敛窗口的来源 |
35
+ | verdict | `PASS`(在 `observation` 记录各视图读取时间与数值) | `FAIL`;附多次读取时间戳 + 网络/事件证据(是否有推送) |
36
+ | 判相反需要 | 契约未写窗口 → `INCONCLUSIVE(needs-contract)`,不写"未同步=缺陷" | 排除缓存/读取时间差:至少两次独立读取且间隔超过窗口 |
37
+
38
+ 常见误判:拿"两个视图数字不同"直接判缺陷——先看读取是否同一时刻、契约是否允许延迟。**多视图同步要求由契约决定,不能靠个人印象设定规约。**
39
+
40
+ ## 3. 装饰性闪烁 vs 非预期瞬时变化
41
+
42
+ | | 正常(不判缺陷) | 缺陷(判 FAIL) |
43
+ | --- | --- | --- |
44
+ | 场景 | 设计上就有周期性装饰动画(呼吸灯/加载脉冲/强调动效),声明层与实现一致 | 关键内容区出现非预期瞬时变化;或与声明层不一致 |
45
+ | 观察 | 变化周期性、幅度/颜色与设计声明一致、不影响文字可读性 | 关键文本/金额/操作按钮区域短时不可读或明显错位;变化不在声明里 |
46
+ | 需要的契约 | 设计声明/动画规格(关键帧、时长、循环方式) | 一致的"不应出现该变化"的验收条件 |
47
+ | verdict | `PASS` 或"不构成缺陷"(写清依据:声明一致 + 无可见影响) | `FAIL`;必须给出能覆盖该瞬时变化的采样证据(帧 id + 时间窗),或声明层证据 |
48
+ | 判相反需要 | 采样覆盖到变化窗口(采样间隔 < 变化时长),否则不能断言"没发生" | 单帧截图不足以证明瞬时变化;需连续帧 + `region` 裁剪 |
49
+
50
+ 红线:**采样没覆盖到,只能写 `INCONCLUSIVE`(INSUFFICIENT_TEMPORAL_RESOLUTION)**;也不能因为"设计上通常有闪烁"就一概不判。
51
+
52
+ ## 4. 静态 WebGL/Canvas 内容 vs 应当变化的渲染故障
53
+
54
+ | | 正常(不判缺陷) | 缺陷(判 FAIL) |
55
+ | --- | --- | --- |
56
+ | 场景 | canvas 内容本来就是静态图/一次性绘制;无动画声明 | 声明/契约要求内容随时间变化,但像素恒定 |
57
+ | 观察 | 帧间像素稳定、无丢帧;上下文正常;rAF 活跃或空闲都合理 | 声明要求变化,帧间像素恒定;或上下文丢失/报错 |
58
+ | 需要的契约 | "静态内容"是设计(无动画声明、验收只要求绘制正确) | "应变化/应重绘"的来源 |
59
+ | verdict | `PASS`(静态即正确);不写"未渲染",也不写"缺 clear" | `FAIL` 只在"应变化而未变化"且采样足够时成立;机制列为候选,不写死 |
60
+ | 判相反需要 | 用 T3 验证某一帧绘制正确(颜色/区域/几何) | 需排除:上下文丢失、采集未覆盖、绘制被遮挡、软件渲染差异 |
61
+
62
+ 反例(错误推理):像素 3s 不变 + 页面有 canvas → "WebGL 未渲染/缺少清屏"。这是把**观察**直接升级成**机制**;机制必须列候选并用对照实验排除。
63
+
64
+ ## 5. 正常 409 冲突提示 vs 冲突处理缺陷
65
+
66
+ | | 正常(不判缺陷) | 缺陷(判 FAIL) |
67
+ | --- | --- | --- |
68
+ | 场景 | 并发修改触发 409;UI 明确提示冲突;资源保持原值 | 409 后 UI 显示成功、资源被部分写入、或没有任何提示 |
69
+ | 观察 | 响应 409 + 冲突原因;提示文案出现;重新读取资源仍是旧值 | 响应 409 但提示为成功样式/无提示;或资源出现半更新状态 |
70
+ | 需要的契约 | 冲突提示与"不写入"的约定 | 成功/失败反馈与原子性的约定 |
71
+ | verdict | `PASS`(三方核对:状态码 + 提示 + 资源终态) | `FAIL`;三方证据缺一不可 |
72
+ | 判相反需要 | 用 `network_detail` 看响应体原因、T2 读提示文本、独立读取资源终态 | 只看 toast 或只看状态码都不够 |
73
+
74
+ ## 6. 差异 vs 缺陷:快速判据表
75
+
76
+ | 现象 | 先查 | 大概率结论 |
77
+ | --- | --- | --- |
78
+ | 网络层重复 | 契约是否允许重放;UI 是否去重 | 正常(若去重生效) |
79
+ | 多视图数值暂时不同 | 读取时间差;契约收敛窗口 | 正常/待确认 |
80
+ | 周期性动效 | 设计声明是否包含 | 正常 |
81
+ | 静态画面 | 验收是否要求动画 | 正常 |
82
+ | 409/冲突提示 | 资源终态是否被改 | 正常(若未写入) |
83
+ | 关键内容瞬时不可读 | 采样是否覆盖 + 声明层证据 | 缺陷(证据充分时) |
84
+ | 应变化却恒定 | 采样覆盖 + 上下文状态 + 遮挡 | 缺陷或 INCONCLUSIVE |
85
+ | 金额/数量与响应字段不符 | 数字来源与字段口径 | 缺陷(有服务端真值时) |
86
+
87
+ ## 7. 反例集:这些写法会被门禁拦下
88
+
89
+ 1. `PASS` + observation 里写"偶尔闪一下但不影响"(第 1 项校验:异常词未解释)。
90
+ 2. 缺陷清单有 3 条,但只有 1 个 case 判 `FAIL`(第 2 项校验:清单未映射)。
91
+ 3. 报告写"接口无问题",证据只有一张 UI 截图(第 3/4 项校验)。
92
+ 4. 写了"无法观察 opener 关系",该 case 仍 `PASS`(第 5 项校验)。
93
+ 5. 截图文件名是订单页,内容却是列表页(第 6 项校验)。
94
+ 6. 低采样率下写"无闪烁"(应 `INCONCLUSIVE` + 采样不足)。
95
+ 7. 把"网络层重复投递"直接写成缺陷(未查契约/未看 UI 去重)。
96
+ 8. 把"像素恒定"直接写成"未渲染"(观察升级成机制)。