dsh-agent-team-ui-testing 0.1.1 → 0.1.3

package/select-control.js

@@ -0,0 +1,298 @@
+/**
+ * Panel-side surface for a *native* `<select>` (host half).
+ *
+ * The problem this module serves: a native `<select>` popup is painted by the browser UI layer, not
+ * by the page, so it never appears in the screencast/screenshot the panel renders
+ * (`select.matches(':open')` is true, the element is `document.activeElement`, and the frame still
+ * shows nothing). Keyboard `↑↓ + Enter` works because it goes through the page; the mouse path
+ * needs two things the panel can drive by itself:
+ *
+ *   1. **Read** the options of the hit `<select>` (read-only projection, no side effects) — done by
+ *      `POST /element`, which uses `normalizeSelectProjection` + `selectShapeSupport` from here.
+ *   2. **Write** one value back through the page (native setter + `input`/`change`) — done by
+ *      `POST /select`, which uses `selectWriteExpression` + `classifySelectWrite` from here.
+ *
+ * Everything in this file is pure and dependency-free so the contract suite can pin it without a
+ * browser, a Runtime or a Cordis context. It never touches `index.js` state, never allocates a
+ * runtime and never throws: refusals are *values* (`{ok:false, code, message, details}`) so the
+ * HTTP route decides the status code and the page's `lastError` projection stays untouched.
+ */
+
+/** Options are capped so one pathological `<select>` cannot bloat a panel response. */
+export const SELECT_OPTION_LIMIT = 200;
+
+/** Reasons a `<select>` cannot be driven by the panel popover (keyboard still works). */
+export const SELECT_UNSUPPORTED_REASON = Object.freeze({
+  MULTIPLE: 'multiple',
+  SIZE: 'size',
+  EMPTY: 'empty',
+  DETACHED: 'detached',
+});
+
+/** Human-facing hint the panel renders for an unsupported shape (one line, keyboard escape hatch). */
+export const SELECT_UNSUPPORTED_HINT = '该下拉不支持浮层，请用键盘 ↑↓ + Enter';
+
+/**
+ * Coerce the page-side probe into the public projection.
+ *
+ * The page function returns `{multiple, size, value, options[{value,label,disabled,selected}],
+ * truncated}`; every field is re-coerced here because the page is untrusted input from the Host's
+ * point of view (a page may hand back holes, huge arrays or non-strings).
+ *
+ * @returns {null|{multiple:boolean,size:number,value:string,
+ *   options:Array<{value:string,label:string,disabled:boolean,selected:boolean}>,truncated:boolean}}
+ *   `null` means "this is not a select projection" — the caller then leaves the /element reply
+ *   shape untouched.
+ */
+export function normalizeSelectProjection(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
+  const rawOptions = Array.isArray(raw.options) ? raw.options : null;
+  if (!rawOptions) return null;
+  const capped = rawOptions.slice(0, SELECT_OPTION_LIMIT);
+  const size = Number(raw.size);
+  return {
+    multiple: raw.multiple === true,
+    // `size` is the raw IDL value: 0 means "not set" (a closed single-line select), so both 0 and 1
+    // are the supported single-line shape.
+    size: Number.isFinite(size) && size >= 0 ? size : 0,
+    value: typeof raw.value === 'string' ? raw.value : String(raw.value === null || raw.value === undefined ? '' : raw.value),
+    options: capped.map((option) => {
+      const item = option && typeof option === 'object' ? option : {};
+      return {
+        value: typeof item.value === 'string' ? item.value : String(item.value === null || item.value === undefined ? '' : item.value),
+        label: typeof item.label === 'string' ? item.label : String(item.label === null || item.label === undefined ? '' : item.label),
+        disabled: item.disabled === true,
+        selected: item.selected === true,
+      };
+    }),
+    truncated: raw.truncated === true || rawOptions.length > SELECT_OPTION_LIMIT,
+  };
+}
+
+/**
+ * The page-side probe passed to `Runtime.callFunctionOn` (a function declaration, `this` = the
+ * node). Pure read: it never assigns, never dispatches, never awaits.
+ *
+ * `SELECT_OPTION_LIMIT` is inlined so the page never ships an unbounded list to the Host; the cap is
+ * reported through `truncated` instead of being silent.
+ */
+export function selectProbeDeclaration() {
+  return `function () {
+  if (!this || typeof this.tagName !== 'string' || this.tagName.toLowerCase() !== 'select') return null;
+  const all = Array.from(this.options || []);
+  const limit = ${SELECT_OPTION_LIMIT};
+  const capped = all.slice(0, limit);
+  return {
+    multiple: this.multiple === true,
+    size: Number(this.size) || 0,
+    value: String(this.value === null || this.value === undefined ? '' : this.value),
+    options: capped.map((option) => ({
+      value: String(option.value === null || option.value === undefined ? '' : option.value),
+      label: String(option.label === null || option.label === undefined ? (option.textContent || '') : option.label),
+      disabled: this.disabled === true || (typeof this.matches === 'function' && this.matches(':disabled')) ||
+        option.disabled === true || Boolean(option.parentElement && String(option.parentElement.tagName).toLowerCase() === 'optgroup' && option.parentElement.disabled === true),
+      selected: option.selected === true,
+    })),
+    truncated: all.length > limit,
+  };
+}`;
+}
+
+/**
+ * Can the panel popover drive this select?
+ *
+ * Only a single-line, non-multiple `<select>` with at least one option qualifies. Anything else
+ * keeps the keyboard path (`↑↓ + Enter`), which the panel already forwards to the page.
+ *
+ * @returns {{supported:boolean, reason:string|null}}
+ */
+export function selectShapeSupport(projection) {
+  if (!projection || typeof projection !== 'object') return { supported: false, reason: SELECT_UNSUPPORTED_REASON.DETACHED };
+  if (projection.multiple === true) return { supported: false, reason: SELECT_UNSUPPORTED_REASON.MULTIPLE };
+  const size = Number(projection.size);
+  if (Number.isFinite(size) && size > 1) return { supported: false, reason: SELECT_UNSUPPORTED_REASON.SIZE };
+  const options = Array.isArray(projection.options) ? projection.options : [];
+  if (options.length === 0) return { supported: false, reason: SELECT_UNSUPPORTED_REASON.EMPTY };
+  return { supported: true, reason: null };
+}
+
+/**
+ * Validate the `POST /select` body.
+ *
+ * `value` is mandatory and must be a string (a `<select>` value is always a string). `selector` is
+ * optional; when present it must be a non-empty string and address exactly one element. Optional
+ * `optionIndex` identifies an exact option even when several options share the same value. Optional
+ * `target` carries the Host's node/document identity; the Host verifies it before binding the write.
+ *
+ * @returns {{ok:true,value:string,selector:string|null,optionIndex:number|null,target:object|null}} | {{ok:false,code:string,message:string,details:object}}
+ */
+export function normalizeSelectWriteRequest(body) {
+  if (!body || typeof body !== 'object' || Array.isArray(body)) {
+    return { ok: false, code: 'INVALID_ARGUMENT', message: '/select 需要 body: {value, selector?, optionIndex?, target?}', details: { field: 'body' } };
+  }
+  if (typeof body.value !== 'string') {
+    return { ok: false, code: 'INVALID_ARGUMENT', message: '/select 的 value 必须是字符串', details: { field: 'value', type: typeof body.value } };
+  }
+  let selector = null;
+  if (body.selector !== undefined && body.selector !== null) {
+    if (typeof body.selector !== 'string' || body.selector.trim() === '') {
+      return { ok: false, code: 'INVALID_ARGUMENT', message: 'selector 必须是非空字符串', details: { field: 'selector' } };
+    }
+    selector = body.selector.trim();
+    if (selector.length > 4096) {
+      return { ok: false, code: 'INVALID_ARGUMENT', message: 'selector 过长', details: { field: 'selector', maxLength: 4096 } };
+    }
+  }
+  let optionIndex = null;
+  if (body.optionIndex !== undefined && body.optionIndex !== null) {
+    if (!Number.isSafeInteger(body.optionIndex) || body.optionIndex < 0) {
+      return { ok: false, code: 'INVALID_ARGUMENT', message: 'optionIndex 必须是非负安全整数', details: { field: 'optionIndex' } };
+    }
+    optionIndex = body.optionIndex;
+  }
+  let target = null;
+  if (body.target !== undefined && body.target !== null) {
+    const raw = body.target;
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+      return { ok: false, code: 'INVALID_ARGUMENT', message: 'target 必须是包含 backendNodeId 和 loaderId 的对象', details: { field: 'target' } };
+    }
+    if (!Number.isSafeInteger(raw.backendNodeId) || raw.backendNodeId <= 0) {
+      return { ok: false, code: 'INVALID_ARGUMENT', message: 'target.backendNodeId 必须是正安全整数', details: { field: 'target.backendNodeId' } };
+    }
+    if (typeof raw.loaderId !== 'string' || raw.loaderId.trim() === '' || raw.loaderId.length > 4096) {
+      return { ok: false, code: 'INVALID_ARGUMENT', message: 'target.loaderId 必须是非空字符串且不超过 4096 字符', details: { field: 'target.loaderId' } };
+    }
+    target = { backendNodeId: raw.backendNodeId, loaderId: raw.loaderId };
+  }
+  return { ok: true, value: body.value, selector, optionIndex, target };
+}
+
+/**
+ * The page-side write: one self-contained IIFE.
+ *
+ * Use the native `selectedIndex` setter to identify an exact option even when values repeat. Calling
+ * the prototype setter also bypasses instance accessors installed by frameworks. The prior selected
+ * state is captured before writing, then `input` and `change` are dispatched in that order.
+ *
+ * With `objectBound:true`, the IIFE inherits `this` from the Host's `Runtime.callFunctionOn` wrapper.
+ * That exact node takes precedence over both selector and focus; a detached node is never replaced
+ * by another target.
+ *
+ * The function is pure with respect to the Host: it reads, writes one element and dispatches two
+ * events, and it answers a JSON-serialisable object in every branch.
+ */
+export function selectWriteExpression({ value, selector = null, optionIndex = null } = {}, { objectBound = false } = {}) {
+  const wanted = JSON.stringify(typeof value === 'string' ? value : String(value ?? ''));
+  const sel = selector === null || selector === undefined ? 'null' : JSON.stringify(String(selector));
+  const index = optionIndex === null || optionIndex === undefined ? 'null' : JSON.stringify(optionIndex);
+  return `(() => {
+  const wantedValue = ${wanted};
+  const selector = ${sel};
+  const requestedIndex = ${index};
+  const objectBound = ${objectBound === true};
+  let target = null;
+  if (objectBound) {
+    target = this;
+    if (!target || target.isConnected === false) return { ok: false, reason: 'target-detached' };
+  } else if (selector !== null) {
+    let matches;
+    try { matches = document.querySelectorAll(selector); } catch (error) {
+      return { ok: false, reason: 'selector-invalid', message: String(error && error.message || error) };
+    }
+    if (!matches || matches.length === 0) return { ok: false, reason: 'selector-not-found', selector };
+    if (matches.length > 1) return { ok: false, reason: 'selector-not-unique', selector, count: matches.length };
+    target = matches[0];
+  } else {
+    target = document.activeElement;
+    if (!target || target === document.body || target === document.documentElement) {
+      return { ok: false, reason: 'no-focused-element' };
+    }
+  }
+  const tag = String(target.tagName || '').toLowerCase();
+  if (tag !== 'select') return { ok: false, reason: 'not-a-select', tag, focused: !objectBound && selector === null };
+  if (target.disabled || (typeof target.matches === 'function' && target.matches(':disabled'))) {
+    return { ok: false, reason: 'select-disabled' };
+  }
+  const multiple = target.multiple === true;
+  const size = Number(target.size) || 0;
+  if (multiple || size > 1) return { ok: false, reason: 'unsupported-shape', multiple, size };
+  const options = Array.from(target.options || []);
+  if (options.length === 0) return { ok: false, reason: 'no-options' };
+  if (requestedIndex !== null && (!Number.isInteger(requestedIndex) || requestedIndex < 0 || requestedIndex >= options.length)) {
+    return { ok: false, reason: 'option-index-out-of-range', optionIndex: requestedIndex, optionCount: options.length };
+  }
+  const index = requestedIndex === null ? options.findIndex((item) => String(item.value) === wantedValue) : requestedIndex;
+  const option = options[index];
+  if (!option) {
+    return { ok: false, reason: 'value-not-in-options', value: wantedValue, optionCount: options.length,
+      values: options.slice(0, 50).map((item) => String(item.value)) };
+  }
+  if (String(option.value) !== wantedValue) {
+    return { ok: false, reason: 'option-value-mismatch', value: wantedValue, optionIndex: index };
+  }
+  if (option.disabled === true || (option.parentElement && String(option.parentElement.tagName).toLowerCase() === 'optgroup' && option.parentElement.disabled === true)) {
+    return { ok: false, reason: 'option-disabled', optionIndex: index, value: wantedValue };
+  }
+  const wasSelected = option.selected === true;
+  let setter = null;
+  try {
+    setter = Object.getOwnPropertyDescriptor(HTMLSelectElement.prototype, 'selectedIndex');
+  } catch (error) { setter = null; }
+  if (setter && typeof setter.set === 'function') setter.set.call(target, index);
+  else target.selectedIndex = index;
+  target.dispatchEvent(new Event('input', { bubbles: true }));
+  target.dispatchEvent(new Event('change', { bubbles: true }));
+  return {
+    ok: true,
+    value: String(target.value),
+    selectedIndex: Number(target.selectedIndex),
+    optionIndex: index,
+    wasSelected,
+  };
+})()`;
+}
+
+/**
+ * Classify the page answer into the route's contract.
+ *
+ * Every refusal keeps a stable `reason` in `details` (the panel and the tests branch on that, not on
+ * message text) and uses `INVALID_ARGUMENT` — the request named something this page cannot honour,
+ * which is an input answer rather than a Host failure. `INTERNAL` is reserved for an answer the
+ * function itself could not produce.
+ */
+export function classifySelectWrite(raw) {
+  if (!raw || typeof raw !== 'object') {
+    return { ok: false, code: 'INTERNAL', message: '/select 的页面结果不可读', details: { reason: 'unreadable-result' } };
+  }
+  if (raw.ok === true) {
+    return { ok: true, value: String(raw.value ?? ''), selectedIndex: Number.isFinite(Number(raw.selectedIndex)) ? Number(raw.selectedIndex) : null };
+  }
+  const reason = typeof raw.reason === 'string' && raw.reason ? raw.reason : 'unknown';
+  const details = { reason };
+  if (typeof raw.selector === 'string') details.selector = raw.selector;
+  if (Number.isFinite(Number(raw.count))) details.count = Number(raw.count);
+  if (Number.isFinite(Number(raw.size))) details.size = Number(raw.size);
+  if (typeof raw.multiple === 'boolean') details.multiple = raw.multiple;
+  if (typeof raw.tag === 'string') details.tag = raw.tag;
+  if (typeof raw.focused === 'boolean') details.focused = raw.focused;
+  if (typeof raw.value === 'string') details.value = raw.value;
+  if (Number.isSafeInteger(raw.optionIndex) && raw.optionIndex >= 0) details.optionIndex = raw.optionIndex;
+  if (Number.isFinite(Number(raw.optionCount))) details.optionCount = Number(raw.optionCount);
+  if (Array.isArray(raw.values)) details.values = raw.values.slice(0, 50).map((item) => String(item));
+  const message = {
+    'selector-invalid': 'selector 不是合法的 CSS 选择器',
+    'selector-not-found': 'selector 没有命中任何元素',
+    'selector-not-unique': 'selector 命中了多个元素（必须唯一）',
+    'no-focused-element': '页面没有聚焦的元素：先点一下 <select>，或显式给 selector',
+    'not-a-select': '目标元素不是 <select>',
+    'select-disabled': '<select> 处于 disabled 状态',
+    'target-detached': '绑定的 <select> 已脱离文档',
+    'option-index-out-of-range': 'optionIndex 不在 <select> 的 options 范围内',
+    'option-value-mismatch': 'optionIndex 对应选项的 value 已变化',
+    'option-disabled': '目标 option 或所属 optgroup 处于 disabled 状态',
+    'unsupported-shape': '只支持单选 <select>（multiple/size>1 请用键盘 ↑↓ + Enter）',
+    'no-options': '<select> 没有可选项',
+    'value-not-in-options': '目标值不在 <select> 的 options 里',
+  }[reason] || '下拉写入失败';
+  return { ok: false, code: 'INVALID_ARGUMENT', message, details };
+}

package/skills/ui-testing-common/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: ui-testing-common
+description: UI 测试的跨环境中立操作规则，凡是「让你在某个已接入的目标上看一眼/操作一下并给结论」的常规表述都算命中：「帮我看看这个界面/这个页面/这个窗口」「点一下试试、填一下、走一遍这个流程」「为什么点了没反应/报错了」「这个环境能用吗/为什么工具不可用」「你看我标的这里/我圈的是这块」（人类在调试视图上的标注＝通用输入通道，先读标注别让他口述）「给我证据/复现一下/能不能测」。规则：先锁目标与契约、再探能力、观测优先于动作、用独立证据判定、区分未检测/不可用/不支持；具体环境的工具名、协议与限制以该环境扩展 Skill 与运行态能力发现为准。
+---
+
+# UI Testing · 跨环境公共规则
+
+## 何时使用
+
+当你需要通过已接入的调试环境观察或操作一个目标（网页、桌面应用、设备等）并给出可复核结论时使用。本 Skill 只写环境中立规则；具体工具面、坐标空间、协议与限制由当前环境的扩展 Skill 与运行态能力发现提供。
+
+命中示例（环境无关，换成任何目标都成立）：「帮我看看这个界面现在什么状态」「点一下这个按钮试试」「走一遍登录流程」「为什么点了没反应/为什么会报错」「这个环境能用吗、为什么工具不可用」「你看我标的这里、我圈的是这块」「给我证据、复现一下」。不命中：纯文案写作、后端接口设计、与被测目标无关的通用编程问题。
+
+## 事实来源与边界
+
+- **工程支持、用户启用、依赖可用、连接可信、目标已绑定、能力就绪是六个独立问题**，不得合并成一个“有效”布尔值。
+- 静态文档、清单与历史记录只说明工程状态，不构成运行态可用性证明；以能力发现与真实调用结果为准。
+- 「本环境的工具面」= 该环境**注册并准入**的工具集合（本插件 Web 环境当前是 37 个 `browser_*`）；环境未启用时这些工具不注册，调用报 `ADAPTER_DISABLED`，不是工具缺陷。
+- 缺失能力要如实写 `unsupported`；暂时不可用写 `unavailable`；尚未检测写 `not-probed`。不得用推断代替观测。
+- 不同目标、不同 generation、不可兼容的坐标/几何版本不得直接比较；切换目标后旧引用、旧帧、旧网络记录与旧标注按身份边界作废。
+
+## 最短流程
+
+1. **锁目标与契约**：写下验收原文与来源、目标身份、需要的坐标空间/视口/环境版本、前置条件。契约不明只能观察并记 `UNKNOWN`。
+2. **探能力**：先调用能力发现，记录支持与现场可用性；缺能力就停在该步。
+3. **页面/目标身份门禁**：动作前记录期望身份，动作后用独立读取核对；不一致不得用另一个目标的通过覆盖本题。
+4. **先观测再动作**：记录初始状态与基线，再做最小必要动作。
+5. **独立证据**：回读目标真值、结构/像素/网络/帧证据；`ok:true`、`dispatched:true`、`applied:N` 都不是断言结果。
+6. **判定五元组**：`expected_contract` / `observation` / `evidence_ids` / `counterexamples` / `verdict`。
+7. **覆盖声明**：任何替代路径都要写清替代了什么、仍缺哪条原始断言、`coverage=full|partial|blocked`。
+8. **提交前交叉校验**：verdict↔observation 异常词、verdict↔缺陷清单、observation↔证据、数字↔来源、limitation↔status、截图↔文件名与声明；任一项未消解不得 PASS。
+
+## 人类标注：环境无关的输入通道
+
+- 人类在调试视图（面板画布）上画图是**指路信号**：他说「看我框的」「这个箭头指哪」时，先按当前环境的能力发现找读取入口（本插件 Web 环境是 `browser_state()` 顶层的 `annotations`，`browser_capabilities().annotations` 声明坐标空间与限额），再去定位元素；**不要让用户改用文字描述或给候选编号**。
+- 标注是**画布坐标**，不是页面坐标：换算成页面坐标要减去**当前**的视图偏移，不能用发布那一刻的视图快照。
+- `source.trusted` 恒为 false：标注是线索，不是页面事实，也不授权自动点击；结论仍要被结构化/像素/网络/帧证据支撑。
+- 用户提到标注、画、圈、框、箭头或笔迹等指代面板标注时，读取结构化文档后还应查看当前环境提供的带标注截图（Web：`browser_screenshot {includeAnnotations:true}`）。Web 的 `includeAnnotations?:boolean=false` 默认关闭，默认截图、T3 原始源与 T4 帧源不含面板标注；默认图里没有线不能证明用户没画。
+- Web 带标注截图只叠加已提交且经 Host 接受的六种形状，遵循面板渲染语义与本次截图的 region/scale 映射，不含未提交草稿、工具栏或其它面板 UI。用 `capture.annotations` 核对 revision、context、新鲜度、截断与 `source.trusted=false`；写标注走该环境的写入口（Web 为 `browser_annotation`），不是页面动作。
+- `brush.points` 是几何点集，`text.text` 才有文字原文；可从带标注截图观察手写笔迹，无法可靠辨认时如实说明，不猜字。
+- 标注按工作区隔离，导航/刷新会清空、跨页签或跨会话可能保留；引用时要带上 `revision` 与 `context.documentKey` 这类身份字段，过期就重读。
+
+## 判定门禁
+
+- 证据不足、采样不足、目标身份不明、坐标空间不兼容：`BLOCKED` 或 `INCONCLUSIVE`，不得写 PASS。
+- 读取型探测不证明输入已生效；输入闭环必须在受控目标上验证。
+- 配置帧率/请求参数不能冒充实测采样；报告实测值、时钟与空档。
+- 历史已注入的上下文不会被开关自动撤回；隔离只对后续轮次生效。
+
+## 安全
+
+- 只操作被授权的目标；不读写被禁止的目录，不索取或回显明文秘密。
+- 高风险操作先确认前置条件与回滚/清理路径；失败后复验。
+- 不把密钥、token 写进命令、脚本或仓库文件；证据只保留必要元数据。

package/skills/ui-testing-fake/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: ui-testing-fake
+description: 仅用于契约测试的假调试环境（test-only）：验证跨环境适配器、配置准入、证据与生命周期。它不是真实平台实现，不得据此声称任何真实桌面/Android/小程序环境已支持。
+---
+
+# UI Testing · 假环境（test-only）
+
+## 边界
+
+- 本 Skill 只在 `DSH_UI_TESTING_TEST_HOOKS=1` 或 `DSH_UI_TESTING_ALLOW_TEST_ENV=1` 的测试配置中可发现；生产默认不可见、不可加载。
+- 假环境只提供确定性夹具：目标列表、帧/图像、网络事件、显示空间、标注与租约；不启动真实浏览器、不连接真实设备。
+- 不得把假环境的通过写成真实平台可用；真实平台仍需独立适配器、独立探针与独立验收。
+
+## 用途
+
+用于验证三类 adapter 的公共契约：配置 revision 一致性、目标 generation、证据 envelope、P0 可选能力、取消/清理与跨环境隔离。测试记录必须区分“假适配器契约通过”与“真实平台未验证”。
+
+## 怎么用（Agent 操作口径）
+
+1. **先确认发现条件**：`browser_capabilities` 的 `readiness.environments` 里能看到 `fake`，且 `enabled=false` 时不要直接调工具——它还没被启用。
+2. **启用并选择**：让用户（或测试脚本）在设置页面板启用 `fake` 环境；本会话选择用 `POST /plugins/ui-testing/config/select`（`scope:"session"`）。工具面会在下一步按新的启用集合重建。
+3. **确认注册面**：启用 fake 后 `browser_capabilities.adapter.declaration.registeredTools` 应包含 `browser_fake_probe` + 两个环境无关诊断；Web 未启用时应**不含**任何 `browser_*` Web 工具。
+4. **跑探针**：调 `browser_fake_probe`（可带 `payload`），确认返回 `environment:"fake"` 且结果 envelope 带 `configRevision`；这证明执行入口用的是当前配置。
+5. **做对照**：Web 与 fake 的差异要落在"注册面 / Skill 目录 / 执行准入"三处，任一处不符就记 FAIL，别只截图。
+
+## 断言清单（缺一条就不算契约通过）
+
+| 检查 | 期望 |
+| --- | --- |
+| 配置 revision | 工具结果里的 `configRevision` 与 `GET /config` 的 `revision` 一致；旧 revision 的调用被判 `CONFIG_STALE` 或重新解析 |
+| 目标 generation | `listTargets`→`bind` 后 `generation` 递增；重绑后旧帧/旧标注/旧租约按 `targetId + generation` 被拒（`GENERATION_MISMATCH`），不串目标 |
+| 证据 envelope | P0 每次成功调用带 `version/scope/session/target/generation/configRevision/operation/source/capturedAt`，缺字段即 `EVIDENCE_INCOMPLETE` |
+| 可选能力 | 去掉某个 P0 家族时该家族报 `unsupported`，其余家族仍可用；不得伪造空数据 |
+| 取消/清理 | 取消后连接/帧源/网络/租约都被释放，不遗留后台任务 |
+| 跨环境隔离 | 禁用某环境后其工具不进注册面、其 Skill 不在目录里（`ui-testing-web` 与 `ui-testing-common` 的差别就是判据） |
+
+## 常见误判
+
+- 用 fake 的结果去宣称 Android/桌面/小程序"已支持"——不行，那是另一套适配器与另一套验收。
+- 把"工具被拒"当成隔离证据：要看**注册面/请求声明**，而不是 handler 返回 `ADAPTER_DISABLED`。
+- 把"页面工具 available"当成"浏览器已经连上"：连接状态看 `connection` 轴，未启动是 `not-probed`。
+
+三类 adapter 的接口形状与完整坑点清单是**贡献者文档**：`docs/adapters.md`（Agent 日常操作不需要读它，按上面的断言清单用工具即可）。