#CLI 命令与稳定契约

这页按任务整理 A3S Test 的稳定命令与返回约定。第一次使用先运行能力发现命令，再根据当前任务进入 Agent 会话、ACL 套件或分布式执行。

#发现能力

这些命令直接输出已安装协议和调度边界，不根据文档猜测本机能力。

a3s-test capabilities --json
a3s-test agent schema
a3s-test provider schema contract-generation
a3s-test provider schema design-audit
a3s-test provider schema llm
a3s-test provider schema visual-grounding
a3s-test worker schema
a3s-test worker inventory
a3s-test worker remote schema
a3s-test worker artifacts schema
a3s-test distributed schema

Provider schema 描述请求、响应、来源和权限字段，不代表仓库捆绑了某个推理后端。

#项目 Vibe Loop

这些命令已包含在已发布的 v1.0.2 二进制中。

a3s-test init --root . --json
a3s-test doctor --root . --json
a3s-test dev --root . --json

init 默认要求 Test Kit，只做发现与配置，不会安装依赖或启动进程。doctor --connect 会额外探测 URL；--strict 会把 warning 视为失败。

dev 先执行静态检查。配置 URL 已可访问时标记为 server: "existing"，退出时不会终止它；否则直接启动配置中的命令并拥有其进程树。开发服务器日志只写入 stderr，stdout 保持为紧凑 JSONL：

{"protocol":"a3s.test.dev/1","event":"ready","project":"checkout","url":"http://127.0.0.1:5173/","server":"started","session":"dev","repair_bridge":{"protocol":"a3s.test.local-repair-bridge/1","state":"watching","event":"repair_batch"}}
{"protocol":"a3s.test.local-repair-bridge/1","event":"repair_batch","project":"checkout","protocol_revision":15,"session":"dev","repairs":["..."],"batches":["..."],"ledger_path":".../repairs.jsonl"}
{"protocol":"a3s.test.dev/1","event":"stopped","project":"checkout","url":"http://127.0.0.1:5173/","server":"started","session":"dev","reason":"interrupt","cleanup":"complete"}

实时 Test Kit 握手通过后，页面评审侧栏明确发送的 finding 会先写入权威 repairs.jsonl 并捕获 A3S Test 自有的修改前证据，再按 finding ID 与 ledger sequence 去重后发出 repair_batch。事件已经包含生成的 session ID，coding agent 不需要再手工协调一个 repair-watch --session ... 进程。Test Kit 可选且页面中完全不存在时，repair_bridge 为 null，不会启动轮询。

按 Ctrl+C 会在精确关闭浏览器和自有开发服务器后返回 130。自有服务器异常退出会返回 1。启动、配置或 bridge 失败会返回 2；bridge 失败的停止原因为 repair_bridge_error，同样先完成精确清理。

#Agent 会话

agent open 是 agent start 的别名，agent snapshot 是 agent observe 的别名。

#创建会话时的关键选项

a3s-test agent start http://127.0.0.1:3000/checkout \
  --session checkout \
  --goal "Complete checkout" \
  --success "The confirmation heading is visible" \
  --allow-origin http://127.0.0.1:3001 \
  --browser-driver standalone \
  --json

自动解决是 session 级选择。验证失败、缺少新 ready 修订或证据不完整时不会自动进入 resolved。

#紧凑动作命令

紧凑命令适合常见的一步操作。

a3s-test agent click @e3 \
  --session checkout \
  --observation 7 \
  --json

a3s-test agent fill @e4 "tester@example.test" \
  --session checkout \
  --observation 8 \
  --json

a3s-test agent press Enter --session checkout --json
a3s-test agent viewport 390 844 --session checkout --json
a3s-test agent screenshot screenshots/confirmation.png \
  --session checkout \
  --json

可用紧凑命令包括 click、hover、focus、double-click、context-click、fill、type、insert-text、check、uncheck、select、drag、press、wheel、viewport 和 screenshot。动作需要 ref 时，必须同时传入生成该 ref 的最新 observation ID。

#完整 Action JSON

标签页、frame、dialog、网络、等待、断言和高级证据使用 agent act。

a3s-test agent act \
  --session checkout \
  --action-json '{"type":"wait","condition":{"type":"text","value":"Order confirmed"}}' \
  --json

先用 a3s-test agent schema 获取修订 15 的完整 JSON Schema。当前动作类型如下。

insert_text 复用已建立的编辑上下文，不接收新目标。terminal_* 只在 TUI surface 合法。未知字段和当前 surface 不支持的动作会在派发前拒绝。

#Test Kit inspection

a3s-test agent inspect \
  --session checkout \
  --component checkout-form \
  --detail forensic \
  --limit 100 \
  --json

--detail 接受 summary、scoped、diff 与 forensic。范围可以是 page、一个当前私有 node、component，或 viewport,x,y,width,height 与 document,x,y,width,height 形式的 region。响应带 cursor 时，下一次 inspection 必须保持相同 session、scope 与页面修订。

需要修订级差异时，提供正整数 baseline 和可选有界等待。

a3s-test agent inspect \
  --session checkout \
  --detail diff \
  --since-revision 42 \
  --wait-timeout-ms 5000 \
  --json

diff 必须带 --since-revision，其它 detail 会拒绝这个参数。--wait-timeout-ms 必须是 0 到 300,000 的整数。后续 cursor 还会绑定 detail、scope、baseline、UI 选择、标准化 limit 与当前修订，任一变化都会失败，不会重新从第一页开始。

#Repair Ledger 命令

每次状态变化都需要新的幂等 request ID。claim 返回的 attempt ID 要沿用到 progress、reply、complete 和 fail。repair-complete 会保存精确且有顺序的 --changed-file 列表，包括空报告。repair-verify 必须重复同一列表并针对更新后的 ready 页面修订；列表不同会在连接浏览器前失败。

忘记 session 或 finding ID 时，先在当前工作区发现可恢复任务：

a3s-test agent repair-inbox --json

a3s.test.repair-inbox/1 无需连接浏览器即可扫描活动和已关闭会话，并依次排列过期 lease、正在修改的任务、最早 queued finding、等待人工处理的任务和只能检查的记录。终态历史默认不返回。需要时可以添加 --session dev、--limit 20 或 --include-terminal。total 是应用 limit 前的有效匹配数，truncated 表示返回前缀是否不完整。

选定任务后再检查完整循环，会话浏览器已经关闭也可以读取：

a3s-test agent repair-inspect finding-checkout \
  --session dev \
  --json

版本化的 a3s.test.repair-loop-record/1 结果包含有界意图、经过校验的源码映射、完成修改时的变更、紧凑证据摘要、验证、ACL 证明、attempt 历史和类型化下一步。它从 repairs.jsonl 派生，不连接浏览器，也不会把不可信 Page Context 变成恢复命令。

claimed、repairing 或 verifying 的 lease 过期时，只返回类型化对账动作，不会返回旧编辑或验证命令。继续该 attempt 或领取下一项前，先执行投影给出的有界 repair-watch。

省略 --checks-json 即可从 .a3s-test/project.acl 规划并运行最小配置切片：

a3s-test agent repair-verify finding-checkout \
  --session dev \
  --request-id verify-checkout-1 \
  --success-criteria-passed true \
  --changed-file src/Checkout.tsx \
  --summary "已在新页面上验证 checkout 修复" \
  --json

--config 可以更换项目 ACL 路径，默认值为 .a3s-test/project.acl。Focused 检查声明工程内相对 file_prefixes，regression 检查不声明前缀。结果会在 verification.verificationSlice 中保存协议、focused 或 expanded 范围、映射源码、定位器与既有证明状态、选中检查 ID 和扩大原因。选中的命令会在自有进程树中直接运行，执行与清理都有明确上限。

只有外部 orchestrator 已经运行检查时，才传入 --checks-json '[{"command":"npm test","status":"passed","summary":"检查通过"}]'。传入后，本次调用不会自动执行项目检查，但浏览器证明和 ACL 证明门槛仍然保留。

repair-watch 仍用于直接启动的 Agent session 做一次提取。dev --json session 已经运行本地 repair bridge，并会发出带修改前证据的 repair_batch， 不要再为它附加第二个 watch loop。

#会话终态与文件

a3s-test agent finish \
  --session checkout \
  --status passed \
  --summary "Checkout completed and confirmation was observed" \
  --json

持久会话默认保存在当前工作区的 .a3s-test/agent-sessions/<session>/。events.jsonl 是追加式事件记录，report.json 是终态结果，artifacts/ 只允许相对证据路径。finish 用于已经得到 passed 或 failed 结论的会话；无法安全继续时使用精确 abort。

#契约与 provider

a3s-test contract generate \
  --config tests/contracts/checkout.generate.acl \
  --output tests/contracts/checkout.draft.json

a3s-test contract review \
  --draft tests/contracts/checkout.draft.json \
  --review tests/contracts/checkout.review.acl \
  --output tests/contracts/checkout.acl \
  --audit tests/contracts/checkout.reviewed.json

contract generate 只写 candidate draft。contract review 重新校验来源、评审动作和冲突后才发布规范 ACL。视觉定位与设计审查分别通过 agent ground 和 agent audit 调用部署方 provider，返回建议而不执行页面动作。

#ACL 与分布式运行

a3s-test check <suite.acl> --json
a3s-test run <suite.acl> --json
a3s-test distributed plan <distributed.acl> --compact
a3s-test distributed run <distributed.acl> --json

远程 worker 使用独立的 a3s.test.remote-worker/3 执行协议和 a3s.test.remote-artifacts/1 artifact 协议。请求不能选择 executable、应用、后端、凭据或网络策略，这些必须由部署启动参数固定。

check 只做准入，不启动界面。run 在准入后执行 suite，并把产品失败、测试规范错误、基础设施错误和清理错误分开写入机器结果。distributed plan 先匹配 worker 能力，distributed run 才发送鉴权 shard。

#ACL 控件状态断言

Action 协议修订 8 新增以下 expect 条件。

expect "name" {
    target = label("Display name")
    value = "Ada"
}

expect "submit" { disabled = role("button", "Submit") }
expect "terms" { checked = label("Accept terms") }
expect "review" { selected = role("option", "Review") }

expect "status" {
    target = role("listbox", "Publication status")
    selected_values = ["review", "published"]
}

value 与 selected_values 需要单独配置 target。布尔状态包括 enabled/disabled、checked/unchecked 和 selected/unselected 三组。预期选项不得重复；期望值与实际值都会排序后按精确集合比较。[] 可以通过准入，含义是观察到真实的空选择。

布尔状态通过时会在 output.data 下返回以下结构。

{
  "target": { "type": "role", "role": "button", "name": "Submit" },
  "state": "enabled",
  "expected": false,
  "actual": false
}

值和已选值集合也会返回 target、expected 与 actual，其中选项数组使用规范顺序。配置 stable_for_ms 后，Runner 会重复同一个类型化断言，并增加常规的 assertion 与 stability 证据。

Web 读取实时 DOM 状态，原生 checkbox/radio 属性优先于 ARIA。GUI 只有在 CUA 确实返回 value 时支持精确值；布尔状态和多选状态会以 test.driver.gui.assertion_unsupported 拒绝。TUI 仍然只支持可见终端文本。Page Context ref 会在派发前解析；直接 standalone ref 还不能暴露原生 option 选择或多选数组。

#焦点归属 ACL 断言

Action 协议修订 13 新增四种稳定目标条件。

expect "checkout-focused" { focused = role("button", "Checkout") }
expect "cancel-unfocused" { unfocused = testid("cancel") }
expect "dialog-owns-focus" { focus_within = role("dialog", "Checkout") }
expect "page-does-not-own-focus" { focus_outside = testid("page-shell") }

focused 把目标与当前 document 和嵌套开放 Shadow DOM 中可观察到的最深 active element 比较。focus_within 还会沿 assigned slot、DOM 父级与 Shadow host 检查渲染扁平树祖先。两种负向形式只在目标解析成功后比较同一份实时证据。元素缺失绝不能证明 unfocused 或 focus_outside。

语义定位器穿透开放 Shadow DOM，并排除可访问性隐藏的 composed ancestry，包括隐藏的 slot wrapper。CSS 保持当前 document 查询语义。GUI 与 TUI 没有等价归属证据时明确关闭失败。当前检入覆盖 600/600 个确定性 Web 分类、200/200 个持续窗口、200/200 个瞬态窗口，以及 standalone Chromium 中 17 个正向断言和 11 个负向或驱动错误分类。

#实时语义状态 ACL 断言

Action 协议修订 14 新增五组彼此独立的正向与负向状态。

expect "filters-open" { expanded = testid("filters") }
expect "pin-off" { unpressed = role("button", "Pin") }
expect "name-locked" { readonly = label("Display name") }
expect "email-required" { required = placeholder("Email") }
expect "email-invalid" { invalid = css("#email") }

完整配对为 expanded/collapsed、pressed/unpressed、readonly/writable、required/optional 和 invalid/valid。状态适用时以原生属性为准，包括 <details>.open、原生只读与必填属性，以及 willValidate 为 true 时的 Constraint Validation。ARIA 回退只接受精确布尔值；aria-invalid 还会把 grammar 和 spelling 映射为 invalid。混合按压状态、未知 token 和缺失状态属于 unsupported，不会被当成 false。

writable 不蕴含 enabled，产品要求真正可编辑时应组合两者。当前 Page Context ref 可以在派发前解析为稳定定位器。语义定位器穿透开放 Shadow DOM，并排除可访问性隐藏祖先；CSS 保持当前 document 语义。GUI 与 TUI 明确关闭失败。当前检入证据覆盖 1,000/1,000 个确定性 Web 分类、100/100 个持续窗口、100/100 个瞬态窗口，以及 standalone Chromium 中 27 个正向断言和 17 个负向或驱动错误分类。

#渲染文本、有序序列与可见数量 ACL 断言

Action 协议修订 9 把预期文案绑定到唯一目标，并观察稳定定位器产生的完整可见数量。修订 10 新增精确的有序渲染文本向量。

expect "total-copy" {
    target = testid("total")
    rendered_text = "Total $42.00"
}

expect "visible-rows" {
    target = css("[data-row]")
    visible_count = 3
}

expect "line-items" {
    target = css("[data-line-item]")
    rendered_texts = ["Keyboard × 1", "Mouse × 2", "Shipping", "Shipping"]
}

expect "no-line-items" {
    target = css("[data-missing-line-item]")
    rendered_texts = []
}

expect "no-errors" {
    target = role("alert", "Checkout error")
    visible_count = 0
}

rendered_text 必须解析到唯一可见目标。比较前会去掉两端空白，并把连续空白折叠成一个空格。目标缺失或歧义仍是驱动错误；只有已经观察到的文案不同才返回 test.assert.rendered_text。

visible_count 接受语义或 CSS 定位器，并把完整可见匹配集合与非负整数比较。空集合是有证据的零。ACL 会以 test.spec.visible_count_target_unstable 拒绝 ref() 与 visual_point()，因为它们都不能表示可重复解析的集合。非法 CSS selector 仍是 test.driver.web.target_invalid；已观察数量不同才是 test.assert.visible_count。

rendered_texts 接受稳定语义或 CSS 定位器，对每个可见匹配独立规范化，并在不排序、不去重的前提下比较完整向量。空匹配集合会被观察成 []，顺序与重复字符串都有意义。ACL 会以 test.spec.rendered_texts_target_unstable 拒绝 ref 与 visual point。预期和实际向量在 ACL 与 Web 驱动两端都限制为最多 256 项。非法 selector 与超限仍是驱动错误；已观察向量不同时才是 test.assert.rendered_texts。

两种平面都排除零几何元素，但都不声称目标处于 viewport 内或没有被其他像素遮挡。当前浏览器 ref 可以标识唯一 rendered_text 元素，却不能表示 visible_count 或 rendered_texts 集合。GUI 支持单目标 rendered_text（优先 CUA value，否则 label）。GUI 与 TUI 对 rendered_texts 与 visible_count 明确关闭失败。

三种条件都支持 stable_for_ms。后续标量文案、有序向量或数量不匹配变为 test.assert.unstable；驱动失败保留原错误码。修订 9 覆盖 600/600 个确定性标量文案与数量分类，修订 10 新增 600/600 个有序向量分类。组合稳定性证据覆盖 300/300 个持续一致窗口与 300/300 个瞬态窗口，以及真实 Chromium CLI 中 12 个正向观察、12 个负向分类、三个通过与三个被拒绝的 100 ms 窗口和零私有 runtime 泄漏。

#渲染布局 ACL 断言

Action 协议修订 11 比较两个稳定目标的渲染几何。

expect "checkout-below-summary" {
    target = testid("checkout")
    relative_to = role("region", "Order summary")
    layout = "below"
    tolerance_px = 1
    stable_for_ms = 300
    sample_interval_ms = 25
}

target、relative_to 与 layout 都是必填项。两个目标都接受 role、text、test ID、label、placeholder 或 CSS 定位器。ACL 会以 test.spec.layout_target_unstable 拒绝 ref() 与 visual_point()；两者绑定一次观察，不能在稳定窗口中重新解析。当前 Page Context ref 在两个目标都解析为稳定定位器后仍可使用。tolerance_px 默认为零，只接受不超过 1,024 的整数。

Web 在一次页面求值中解析两个目标并采集两个矩形。CSS 使用视觉渲染可见性，因此仅设置 aria-hidden 但仍有像素的元素仍可测量；语义定位器还会排除可访问性隐藏祖先，并穿透开放 Shadow DOM。通过载荷返回两个目标、两个矩形、关系、容差与 matched = true。

GUI 要求两个 frame 来自同一份新鲜 CUA snapshot。TUI 返回明确的不支持错误。稳定性输出保留首次与末次完整双矩形载荷；后续解析或几何失败仍由驱动负责。当前检入证据覆盖 3,400/3,400 个确定性案例、100/100 个持续窗口通过、100/100 个瞬态窗口拒绝、全部 17 种关系，以及 standalone Chromium 中 25 个正向断言和 15 个负向或错误分类，同时完成精确清理。

#visual viewport 覆盖率与指针命中 ACL 断言

Action 协议修订 12 区分目标与 visual viewport 相交，以及指针命中测试能否到达目标。修订 15 新增有界覆盖率阈值。

expect "checkout-in-view" {
    in_viewport = testid("checkout")
}

expect "checkout-mostly-visible" {
    target = testid("checkout")
    viewport_coverage_at_least = 80
}

expect "drawer-mostly-outside" {
    target = css("#drawer")
    viewport_coverage_at_most = 10
}

expect "checkout-pointer-hit" {
    pointer_reachable = role("button", "Checkout")
    stable_for_ms = 300
    sample_interval_ms = 25
}

in_viewport 要求正面积相交。部分进入视口的目标会通过，并返回零到一之间的 intersection_ratio；完全离屏或只有边界接触会失败。覆盖率等于相交面积除以完整目标面积。viewport_coverage_at_least 接受 1 到 100，viewport_coverage_at_most 接受 0 到 99，两个被排除的端点会导致恒真断言。pointer_reachable 在裁剪后的目标矩形上使用确定性 3×3 网格，至少一个深层命中到达目标或其 composed-tree 后代时通过。覆盖率不证明无遮挡，所有写法都不证明 enabled 状态、键盘可达性、事件处理或产品意图。

所有写法都接受稳定的 role、text、test ID、label、placeholder 或 CSS 定位器。ACL 拒绝 ref 和 visual point；当前 Page Context ref 可以在派发前解析为稳定定位器。语义目标穿透开放 Shadow DOM，并排除可访问性隐藏祖先。CSS 保留仍有视觉像素的 aria-hidden 目标。原生命中测试会让接收指针事件的透明覆盖层形成阻挡，也会让 pointer-events: none 覆盖层穿透。

通过的 viewport 载荷包含两个矩形和独立重算的比例。覆盖率载荷还包含 actual_percent、comparison、threshold_percent 与 matched。通过的 pointer 载荷还包含全部九个有序样本坐标与布尔值，以及 sample_count 和 reachable_samples。GUI 与 TUI 的当前协议没有等价证据，因此明确关闭失败。当前检入证据覆盖 1,000/1,000 个基础 Core 几何案例与 2,000/2,000 个阈值案例、4,000/4,000 个 Web 协议分类、300/300 个持续窗口与 300/300 个瞬态窗口，以及 standalone Chromium 中 37 个通过断言和 25 个负向或驱动错误分类，并完成精确清理。

#ACL 隐藏断言

hidden 断言稳定目标定位器在当前观察中没有可见匹配。目标不存在，或匹配元素没有渲染出的可见边界，都满足条件。

expect "dialog-closed" {
    hidden = role("dialog", "Checkout")
}

ACL 编译器保存现有的 Action::Assert(Expectation::Visible(target))，并增加由 Runner 负责的隐藏模式。这个策略不会增加 Action 变体；当前协议已推进到修订 15，是因为上面的类型化 expectation。Runner 派发正向可见性探测，再按以下契约分类。

通过步骤会在 output.data 下给出以下稳定结构。

{
  "expected": "hidden",
  "visible": false,
  "target": {
    "type": "role",
    "role": "dialog",
    "name": "Checkout"
  },
  "probe_error": {
    "code": "test.assert.visible",
    "message": "target is not visible"
  }
}

请使用所选 surface 支持的语义或 CSS 定位器。ref() 与 visual_point() 会在准入时失败，因为两者绑定某次观察，解析失败可能只是数据过期，不能证明界面隐藏。Web 支持其语义与 CSS 可见性目标。GUI 支持已准入的语义目标，并把过期或歧义匹配保留为驱动错误。TUI 当前不支持目标可见性断言。

expect hidden 是立即断言。产品要求持续隐藏时，可组合 stable_for_ms。后续采样又发现目标可见时返回 test.assert.unstable，同时保留第一次隐藏观察和可见反例。目标消失本身就是同步条件时，使用下面的等待形式。

#ACL 隐藏等待

wait "dialog-closed" {
    hidden = role("dialog", "Checkout")
}

编译器保存现有的可见目标等待条件，并增加 wait_mode = hidden；在当前修订 15 下，它仍然复用早先的可见性 Action 变体。只要正向探测仍返回可见证据，Runner 就先立即执行一次只读可见性断言，再每 50 ms 探测一次。

延迟后匹配的等待会在 output.data 中给出以下稳定结构：

{
  "expected": "hidden",
  "visible": false,
  "first_visible": { "visible": true },
  "last_visible": { "visible": true },
  "probe_error": {
    "code": "test.assert.visible",
    "message": "target is not visible"
  },
  "wait": {
    "condition": "hidden",
    "outcome": "matched",
    "poll_interval_ms": 50,
    "max_probes": 1201,
    "probes": 3,
    "observed_ms": 101
  }
}

probes 统计逻辑观察次数。步骤 attempts 统计驱动派发次数，只有已准入的可重试基础设施故障才可能让后者更大。普通 suite 与 agent run 的确定性验证使用同一套 Runner 策略。

#ACL 稳定窗口断言

stable_for_ms 为 ACL 的 expect 增加有界采样策略。文本、精确 URL、目标可见性和目标隐藏断言都能使用；前提是所选 surface 驱动支持底层 expectation。它不会增加新的动作类型，也不会改变驱动契约。

expect "settled-total" {
    visible = testid("order-total")
    stable_for_ms = 300
    sample_interval_ms = 25
}

计划工作量按 ceil(stable_for_ms / sample_interval_ms) + 1 计算，包含第一次观察。超过 1,001 个计划样本会在准入时被拒绝。Runner 只在第一次采样通过后启动计时，并在请求窗口的末端一定执行一次采样。

稳定步骤保留常规步骤字段，并在 output.data 下增加以下数据。

第一次采样为假时保留原始断言错误码。后续采样为假时使用 test.assert.unstable。超时和取消仍是终止性的 test.run.* 结果；采样没有完成时可以不带 stability payload。

#JSON 与错误契约

自动化调用应统一传入 --json，读取稳定错误码、状态和结构化字段，避免解析面向人的帮助文本。常见错误范围如下。

完整处理方法见故障排查。全部功能与权限边界见能力参考。

#退出码

第一次 Ctrl+C 请求取消并清理自有界面。第二次只终止当前进程拥有的浏览器、CUA 进程边界和 TUI 进程树。

#Web 能力摘要

Web 驱动支持导航、语义快照、点击、悬停、聚焦、填写与输入、选择范围文本插入、勾选、选择、双击、右键、拖动、按键、修饰键滚轮与视口设置。同步操作包括 load、文本、URL、正向可见性、有界消失等待、精确或范围焦点归属、实时展开/按压/只读/必填/有效性状态，以及正向或隐藏断言。证据包括截图、可访问树、console、页面错误、HAR、Chrome trace、WebM 视频和受约束下载。

浏览器默认 headless，--headed 是明确的调试选项。网络和导航范围分别受初始 origin、--allow-origin 与显式 hostname 例外约束。