#故障排查

A3S Test 把测试规范、界面驱动、产品断言、会话生命周期和修复队列分开记录。排查时先确定失败归谁，再决定是否修改业务代码。一个红色结果只说明某条边界没有成立，不能直接证明产品有缺陷。

#先保存这五项信息

1. 完整命令与进程退出码。
2. JSON 结果中的稳定错误码和 message。
3. 当前 session 或 run 标识。
4. 最新 observation_id、页面 URL 和 Test Kit revision。
5. 能证明问题的最小截图、可访问树、console 与 page errors。

不要复制 Cookie、Authorization、页面存储、生产数据或 provider 凭据。证据里可能含有用户输入，提交前先检查脱敏结果。

#根据错误范围选择负责人

如果 JSON 输出同时包含根错误与 cleanup 错误，两者都要保留。原始产品失败不会因为清理也失败而消失，清理失败也不能被产品断言覆盖。

#会话无法启动

先读取安装版本与协议。

a3s-test --version
a3s-test agent schema
a3s-test capabilities --json

agent schema 成功但 capabilities 返回 test.driver.web.version_unsupported 时，CLI 本身可以运行，当前 Web adapter 的协议范围不兼容。升级或切换到与该 CLI 版本匹配的 adapter。不要绕过版本门禁，也不要把 adapter 的帮助输出当成成功探测。

使用兼容 standalone adapter 时显式声明驱动与可执行文件。

A3S_TEST_AGENT_BROWSER="$(command -v agent-browser)" \
  a3s-test agent start http://127.0.0.1:3000 \
  --session smoke \
  --goal "Open the page" \
  --success "The main heading is visible" \
  --browser-driver standalone \
  --json

如果仍然失败，检查 URL 是否已经监听、adapter 是否可执行、headless 浏览器依赖是否齐全。不要按进程名关闭机器上的所有 Chrome 或浏览器会话。

#观察为空或页面没有 ready

先查看持久状态，再读取一份完整观察。

a3s-test agent show --session smoke --json
a3s-test agent observe --session smoke --json

依次核对以下事实。

• 当前 URL 仍属于 session 的精确 origin 集合。
• 页面没有停在认证跳转、错误页或未授权的新端口。
• 目标位于主文档或驱动能够访问的 frame。
• 宿主页面确实渲染了原生语义或 ARIA 名称。
• Test Kit 的 page.ready 与相关组件 ready 已经变为 true。

等待要绑定可观察条件。

{
  "type": "wait",
  "condition": {
    "type": "text",
    "value": "订单确认"
  }
}

不要添加无限轮询或任意长 sleep。页面始终不 ready 时，应修复宿主应用的 ready 信号或成功条件。

#隐藏断言或消失等待失败

修改定位器前，先读取准确错误码。

expect hidden 表示“现在没有可见匹配”。产品过渡本身必须移除或隐藏目标时，使用 wait hidden。它的 output.data.wait 会记录 matched、timed_out、cancelled、probe_limit 或 inconclusive，以及探测次数和耗时。只有产品要求在第一次隐藏探测通过后继续保持隐藏时，才使用 stable_for_ms。

不要把语义定位器换成快照 ref。ref 缺失可能表示观察已经过期，因此不会被接受为产品元素已消失的证据。不要吞掉 test.driver.*。非法选择器、GUI 歧义匹配、浏览器输出异常或 surface 丢失都会让可见性处于未知状态。

#稳定断言失败或超时

先看步骤错误码，在明确责任边界之前不要先调大采样间隔。

遇到 test.assert.unstable 时，读取 output.data.stability，比较 observed_ms 与 required_ms。samples 统计已经完成的观察点；步骤 attempts 统计全部驱动调用，启用基础设施重试时可以更大。失败的驱动命令只返回错误、不返回数据时，assertion.last 可以是 null。

按下面顺序校准。

1. 如果测试需要先到达 ready 状态，在断言前加入类型化 wait。
2. 让 stable_for_ms 对应产品真正需要的收敛时间，不要直接取 CI 能容忍的最长时间。
3. 让 sample_interval_ms 不大于测试希望有合理概率观察到的最短瞬态。
4. 场景 deadline 要覆盖前置工作、完整窗口、命令耗时和重试退避。
5. 优先使用每次渲染都能重新解析的语义目标，不要让旧 observation ref 穿过 DOM 替换。

不要仅为了让闪烁避开采样而调大间隔，这会降低时间分辨率并隐藏缺陷。不要在断言后补 sleep，sleep 不会产生任何断言证据。采样始终是离散的，无法证明两个观察点之间的状态。

#引用过期或动作目标被拒绝

@eN 与 @cN 只在产生它们的最新观察中有效。导航、DOM 更新、滚动、视口、焦点和浏览器上下文变化都可能推进修订。此时 @eN、UI、截图和坐标证据会失效。只有 Test Kit 0.6.0 返回 complete delta 且没有失效对应私有节点 ID 时，@cN 背后的稳定定位器才会保留；节点变化或消失、reset_required、元数据缺失或旧版 Test Kit 都会清除它。

a3s-test agent observe --session smoke --interactive --json
a3s-test agent click @e3 \
  --session smoke \
  --observation 8 \
  --json

动作报告 stale ref 时重新观察并重新选择目标。自定义集成收到 delta.status = "reset_required" 时，应丢弃旧 baseline 并先获取普通快照。不要重写旧 observation ID，也不要把旧坐标塞进 CSS 目标。

@uN 永远只读。它出现在 UI 理解关系里时，可以帮助定位样式、布局或动效证据，不能用于 click、fill、drag 或 ACL action。需要操作同一节点时，寻找当前观察里的 @eN、可唯一操作的 @cN 或稳定语义定位器。

#页面跳离允许来源

--allow-origin 控制可导航和可观察的精确 scheme、host 与 port。--allow-domain 只允许浏览器网络访问 hostname，不扩大动作 origin。

页面自己跳到未授权 origin 后，A3S Test 会停止签发引用。确认跳转是否属于测试目标。属于目标时，用精确 --allow-origin 重新创建 session。不属于目标时，保留 origin-loss 证据并结束当前 session。

不要在未知页面上继续动作，也不要把 http://127.0.0.1:3000 与 http://localhost:3000 当作同一个 origin。

#Test Kit bridge 不可用

无 bridge 时，Web 可访问快照仍可工作，组件归属、源码提示和 @cN 不会出现。按下面顺序检查。

1. enabled 是否严格等于 true。
2. React 应用是否在客户端挂载 A3STestKit。
3. 页面是否只加载了 A3SReviewOverlay，却没有外层 Context Runtime。
4. 当前 frame 是否与 bridge 同源且可访问。
5. 热更新后是否有多个 provider 互相覆盖。

浏览器控制台里可以只读探测 bridge。

import { getPageContextBridge } from '@a3s-lab/testkit';

const bridge = getPageContextBridge();
console.log({ handshake: bridge?.handshake(), pageContext: bridge?.probe() });

生产环境默认关闭 overlay 属于正常配置。CI 需要 Page Context 时，可以保留 A3STestKit 并省略可见界面。

本地评审循环使用 a3s-test dev --json。doctor 只证明已安装版本处于静态 范围，dev 会报告精确的实时失败边界。必需 bridge 缺失对应 test.driver.web.testkit_bridge_missing，旧 runtime 没有 handshake() 对应 test.driver.web.testkit_handshake_missing，provider 兼容但没有可见评审界面 对应 test.driver.web.testkit_review_overlay_missing。按照错误中的安装或挂载 命令修复，不要通过修改项目 profile 隐藏问题。

#Page Context 被截断

响应中的 truncated、nextCursor 和 ui.budget 说明哪类预算先耗尽。处理顺序如下。

1. 把 scope 缩小到 component、node 或 region。
2. 常规定位使用 summary 或 scoped。
3. 只在修复验证和设计审查使用 forensic。
4. 用返回的 opaque cursor 读取下一页。
5. 确认请求没有试图提高 provider 安装上限。

UI 记录因图不完整而被整体省略时，外层 Page Context 仍可能有效。调用方要把缺失 UI 证据标为不确定，不能补造布局节点或关系。

#Review Overlay 没有出现

检查 A3SReviewOverlay 的 enabled、外层 provider、页面 <html lang> 和 Shadow DOM host。Overlay 只有在 live bridge 存在时挂载。默认界面是一个侧栏，其中“新反馈”“问题”“偏好设置”是并列视图；选中目标后，编辑器会在同一侧栏内替换标记工具。

键盘操作无响应时，先确认焦点没有停在输入框或编辑器。字母快捷键在可编辑控件中会主动让路。移动端还要检查宿主页面是否使用了 z-index 高于 Test Kit 侧栏的全屏层。

#Finding 没有进入修复队列

先区分草稿和发送。保存本地草稿、复制 Markdown 或打开建议都不会进入 Repair Ledger。

工程已经通过 a3s-test dev --json 启动时，不要并行执行下面的命令。先确认 ready.repair_bridge.state 为 watching，再从现有 dev stdout 流读取 repair_batch。手工 watch 只用于直接启动的 Agent session 或一次明确的有界回放。

a3s-test agent repair-watch \
  --session smoke \
  --limit 20 \
  --timeout-ms 30000 \
  --json

没有 repairEndpoint 时，活动浏览器会话从 bridge 队列提取。配置端点后，同源 POST 失败不会删除浏览器队列。检查请求协议、内容类型、body 上限和路由归属，再从同一 session 重试提取。

互相冲突或目标重叠的 finding 可能进入 needs_input。读取 Repair Ledger 和线程消息，人工澄清后再重新排队。不要绕过冲突直接让第二个 Agent 修改同一工作区。

#修复完成但验证不能通过

repair-complete 只结束编辑阶段。repair-verify 还需要更新后的 ready 页面修订、可重新定位目标、成功条件、前后浏览器错误基线和聚焦检查。

常见处理如下。

验证失败不会触发自动解决。显式 --auto-resolve-repairs 也必须先写入通过的 review_ready 事件。

#Provider 请求失败

视觉定位、设计审查和契约生成分别使用独立协议。核对 provider 与 model 身份、endpoint、authorization 环境变量、deadline、费用、请求字节、候选数和响应 Schema。

来源文件或截图在请求期间发生变化时，A3S Test 会拒绝响应。重新生成观察或 draft，不能复用旧摘要。Provider 返回坐标但页面修订已经变化时，也要重新观察和请求，不能把坐标转换成当前点击。

#清理没有完成

先停止派发新动作，再对精确 session 执行 finish 或 abort。

a3s-test agent abort --session smoke --json

第一次 Ctrl+C 请求有界取消和清理。第二次只终止当前 run 拥有的进程组。清理失败会保留 session 供同一调用方重试，观察与动作保持阻断。

不要运行按浏览器或应用名称匹配的全局 kill。它可能关闭用户已有会话，也会丢失 A3S Test 需要写入的终态和证据。

#提交最小诊断包

一个可复查的诊断包通常只需要以下内容。

command.txt
result.json
session.json
events.jsonl
report.json
artifacts/
├── screenshots/failure.png
├── evidence/accessibility.json
├── evidence/console.json
└── evidence/page-errors.json

只有网络或时间问题确实需要时才增加 HAR、trace 或视频。提交前删除凭据、生产数据和与失败无关的大型工件。

需要核对完整入口时，查看能力参考。需要理解权限分层时，查看权限与安全模型。