#Web、GUI、TUI 与 MCP

A3S Test 把被测界面抽象成 SurfaceDriver。Core 只认识类型化观察、动作、证据和关闭结果，不依赖浏览器 DOM、操作系统辅助功能 API 或终端模拟器。Web、GUI 和 TUI 驱动分别把自己的真实感知投影到这套公共协议。

相同的 click 或 expect 名称不代表三个 surface 拥有相同证据。每个驱动只能报告底层平台实际暴露的状态，缺少等价证据时必须关闭失败。

#选择哪一种 Surface

#Web Surface

Web 同时拥有最丰富的结构证据和最严格的浏览器策略。它适合业务回归、响应式布局、可访问性、网络替身、文件上传下载和 Test Kit 上下文。

#确定性 ACL

suite "checkout" {
    version = 1

    scenario "complete-order" {
        name = "Complete checkout"
        surface = "web"
        timeout_ms = 30000

        navigate "open" {
            url = "http://127.0.0.1:3000/checkout"
        }

        fill "email" {
            target = label("Email")
            value = "tester@example.test"
        }

        click "continue" {
            target = role("button", "Continue")
        }

        expect "confirmed" {
            visible = role("heading", "Order confirmed")
        }
    }
}

a3s-test check tests/checkout.acl --json
a3s-test run tests/checkout.acl --json

check 只解析和准入，不打开浏览器。run 在准入通过后为每个 Web scenario 创建自有浏览器会话，按源顺序执行步骤，保存报告和证据，最后清理自己创建的进程树。

#浏览器 adapter 与能力发现

a3s-test capabilities --json

a3s-test run tests/checkout.acl \
  --browser-driver standalone \
  --browser-executable /path/to/agent-browser \
  --json

当前协议准入 A3S Browser >= 0.4.0, < 0.5.0 和 standalone adapter >= 0.26.0, < 0.27.0。能力发现会实际探测 executable。文件存在但版本、Schema 或启动行为不兼容时仍会返回 test.driver.web.*。

默认运行强制 headless。只有显式 --headed 才显示窗口。--browser-microphone synthetic 使用确定性假设备，不读取真实麦克风；默认 disabled。

#Origin 与 network domain 是两种权限

持久 Agent 会话从初始 URL 和每个 --allow-origin 建立 exact-origin 集合。它同时约束显式导航和成功观察。

a3s-test agent start http://127.0.0.1:3000/checkout \
  --session checkout \
  --goal "Complete checkout" \
  --success "The confirmation heading is visible" \
  --allow-origin https://auth.example.test \
  --allow-domain cdn.example.test \
  --json

--allow-origin 包含 scheme、hostname 和有效 port，可以扩大动作导航范围。--allow-domain 只向浏览器网络层增加 hostname 或前导 *. wildcard，不允许 Agent 导航或接受来自该 origin 的新页面观察。两者不能互相替代。

A3S Browser 直接执行 exact-origin policy。standalone 协议只能表达 hostname，因此会收到保守投影，session metadata 会记录实际使用的 containment mode。恢复持久会话时，策略或 adapter 模式不匹配会关闭失败。

#DOM 渲染时如何附加 Test Kit 上下文

浏览器首先生成自己的交互语义。页面引入 Test Kit 后，运行时在组件注册、DOM commit、viewport 变化和页面稳定信号上增量维护 Page Context。

React 或页面组件
    -> Test Kit 注册组件身份、意图与稳定定位器
    -> 读取 DOM 几何、可访问名称、状态和样式事实
    -> 生成带 revision 的 Page Context snapshot
    -> Web driver 按当前 observation 合并浏览器语义
    -> Agent 得到 @eN、@cN 和只读 @uN

Test Kit 不篡改业务可访问树，也不向每个 DOM 节点永久写入大块属性。它维护独立、可撤销、有界的元数据层。坐标由实际渲染后的 DOM geometry 产生，只有当前 revision 有效。MutationObserver、ResizeObserver、scroll、viewport 和显式 ready 状态只负责失效与重新采样，不赋予页面新的动作权限。

普通观察应保持紧凑。需要组件、私有 node 或局部区域的完整细节时，使用 agent inspect。Page Context 协议、坐标空间和分页规则见Page Context 详解。

#Web 生命周期

每个确定性 scenario、Agent session 或 MCP session 都拥有独立 runtime namespace、artifact 根和浏览器进程边界。Unix 使用专用 process group 与 EOF watchdog，Windows 使用 kill-on-close Job Object。timeout、取消、Drop 和第二次中断只清理本次运行注册的进程树，不按进程名终止其他浏览器。

#GUI Surface

GUI 通过 A3S CUA adapter 使用操作系统辅助功能和窗口捕获。A3S Test 仍然拥有会话、动作策略、预算、报告和清理，CUA 负责平台感知与输入。CUA 私有 element token 不会进入 Core 或返回给 Agent。

#先核对平台和真实 host

a3s-test gui-certification --json

当前锁定的 CUA 0.10.0 配置只准入 macOS installed-daemon 与 embedded-socket profile。Windows 和 Linux 在 transport 启动前明确失败。contract_tested 说明检入协议测试通过，不代表当前机器已经授予 Accessibility 和 Screen Recording 权限。

真实 worker 启用前应运行认证。

a3s-test gui-certify \
  --gui-policy-file config/gui-policy.yaml \
  --cua-proxy-executable /Applications/CuaDriver.app/Contents/MacOS/cua-proxy \
  --gui-macos-bundle-id com.example.Editor \
  --gui-target-mode launch \
  --gui-profile window-vision \
  --json

认证会执行真实 observation 和 ownership-safe cleanup。正式 release 还要求 CI 生成绑定源码修订、binary 与 policy digest、host 权限、语义与视觉观察、零残留进程的签名记录。一次本地成功 JSON 不能替代 release certification。

#Host 固定应用身份和捕获范围

GUI 的以下选择都是 host 配置，Agent action 无权修改。

• CUA policy 与 endpoint
• macOS bundle ID
• launch 或 attach 模式
• attach PID 或 launch arguments
• 精确窗口 title、automation ID 或 primary window
• semantic 或 window-vision perception profile

launch 创建一个新应用实例，session 只有在证明它启动前不存在且 PID 身份仍匹配时才会终止它。attach 连接已有应用，任何终态都不会杀掉该应用。当前捕获范围严格限制为绑定的顶层窗口，不支持任意桌面截图。

#Semantic 与 window-vision

semantic observation 返回有界辅助功能元素、role、label、value、automation ID、parent 和 frame，并投影成 A3S Test 自有 @gN.M ref。每个状态改变动作后，整代 ref 失效。

window-vision 还为每次观察生成一个窗口范围 PNG、尺寸、SHA-256 和 @vN。只有语义无法识别目标时才使用视觉点。

{
  "type": "click",
  "target": {
    "type": "visual_point",
    "snapshot": "@v2",
    "x": 420,
    "y": 96
  }
}

输入前会再次校验最新 observation、坐标边界、截图 digest、artifact containment、应用 PID 和窗口 identity。任一项漂移都会阻止 CUA input。成功的视觉动作会把 grounding 图片和 digest 作为证据返回。

#GUI 支持边界

GUI 语义定位器只接受当前 ref、role、text、label 和 automation_id。CSS、test ID 与 placeholder 属于浏览器语义，GUI 不会根据字符串猜测等价元素。一个语义定位器匹配多个元素时会返回歧义错误，不会任选第一个。

GUI wheel 把 delta 的绝对值按每 100 单位换算成一行，向上取整并限制在 1 到 50 行。它不等价于 Web 的带 modifier 缩放手势。

in_viewport、viewport coverage、pointer reachability、URL、rendered text collection、visible count、boolean state 和 selected values 当前没有等价 CUA 证据，会以 test.driver.gui.assertion_unsupported 关闭失败。浏览器网络、tab、frame、DOM 集合状态和终端动作也不会被猜测映射到 GUI。

#TUI Surface

TUI 驱动拥有 executable、PTY 或 ConPTY、完整进程树、VT 状态、证据和清理。它适合已经知道命令、按键和文本成功条件的流程。

suite "editor" {
    version = 1

    scenario "open-document" {
        surface = "tui"
        timeout_ms = 30000

        wait "ready" {
            text = "Ready"
        }

        terminal_resize "size" {
            columns = 120
            rows = 40
        }

        terminal_paste "open" {
            text = "open fixtures/report.txt"
        }

        press "submit" {
            key = "Enter"
        }

        expect "visible" {
            text = "Quarterly report"
        }
    }
}

a3s-test run tests/editor.acl \
  --tui-executable ./target/debug/editor \
  --tui-arg --fixture-mode \
  --tui-columns 120 \
  --tui-rows 40 \
  --json

--tui-working-directory 必须是绝对路径。scrollback row 和 raw output byte 上限只控制有界保留，不会把观察变成无限。TUI snapshot 返回 viewport、scrollback、cursor、alternate-screen、application-cursor、bracketed-paste、process exit 和 truncation 元数据。

Unix 为每个 scenario 创建专用 PTY session、process group 和 EOF watchdog。Windows 使用 ConPTY 与 kill-on-close Job。根进程退出后仍有后代时，清理继续作用于完整 owned tree。

TUI 当前只运行确定性 ACL。外部 Agent 不能通过 agent start 或 MCP 启动 TUI session。

#MCP 给外部 Agent 的统一会话接口

MCP 把同一 session application layer 投影到 stdio。确定性测试仍由原有 runner 执行，host 可以注册 Web、GUI 或两者。

#启动 Web host

a3s-test mcp \
  --web-url http://127.0.0.1:3000 \
  --web-allow-domain cdn.example.test \
  --max-sessions 4 \
  --artifacts-root .a3s-test/mcp-sessions

#启动 GUI host

a3s-test mcp \
  --gui-policy-file config/gui-policy.yaml \
  --cua-proxy-executable /Applications/CuaDriver.app/Contents/MacOS/cua-proxy \
  --gui-macos-bundle-id com.example.Editor \
  --gui-target-mode attach \
  --gui-attach-pid 4242 \
  --gui-profile window-vision

MCP tool 参数中没有 executable、bundle ID、window selector、捕获范围或 policy。调用方只能选择 host 已注册的 surface。

#协议生命周期

客户端必须使用 MCP 2025-06-18，并完成下面的顺序。

initialize
    -> notifications/initialized
    -> tools/list
    -> test_session_start
    -> test_observe
    -> test_act
    -> test_observe
    -> test_finish 或 test_abort

服务器按 session 串行化 turn，同时允许不同 session 在配置上限内独立运行。失败的 observation 也会使上一轮 ref 失效。EOF 会并发关闭所有独立 surface，每个 surface 仍受 cleanup deadline 限制。

#MCP tools

test_schema 返回当前 interactive Action JSON Schema 和实际注册 surface。Runner 专用 verify_contract 不会出现在 interactive Schema 中。test_repair_inbox 不连接浏览器，只读取当前活动 owner 的 ledger；修改 lease 过期时会返回类型化对账动作，不会重放旧编辑命令。工作区级 CLI 发现、Repair Ledger 的 attempt、lease 和验证规则见人工评审与自动修复。

#Cleanup 是可观察状态

test_finish 或 test_abort 达到调用方 deadline 后，已经派发的 driver close 仍在 owned task 中继续。此时其他 turn 返回 retryable test.session.cleanup_in_progress。如果 close 最终返回可重试错误，session 进入 cleanup_required，只能用同一 session ID 再次调用 finish 或 abort，不能继续 observe 或 act。

这条规则避免调用方超时后丢失 surface ownership，也避免重用仍绑定旧浏览器或应用的 session 名称。

#三种执行入口如何配合

探索阶段用持久会话理解未知路径。动作和成功条件稳定后，把它们迁移到 ACL。分布式执行只调度已经确定性的 Web、GUI 与 TUI suite，见Worker 与分布式执行。