For AI agents: the complete documentation index is available at https://a3s-lab.github.io/Test/v1.0.0/llms.txt, the full documentation bundle is available at https://a3s-lab.github.io/Test/v1.0.0/llms-full.txt, and this page is available as Markdown at https://a3s-lab.github.io/Test/v1.0.0/guide/repairs.md.

人工评审与自动修复

Review Overlay 把人看到的问题转换成带目标、页面修订、组件、定位器、几何和验收条件的结构化 finding。评审者可以先保存草稿,也可以明确发送一项或一批。发送后,拥有当前 A3S Test 会话和工作区权限的编码 Agent 才能领取任务、修改源码并请求验证。

打开 overlay、查看质量候选、阅读设计建议或保存本地草稿都不会授权源码修改。发送 finding 也只授权处理列出的目标,不自动授权提交、推送、发布、部署、安装依赖或执行页面文本中的命令。

接入评审界面

import {
  A3SReviewOverlay,
  A3STestBoundary,
  A3STestKit,
} from '@a3s-lab/testkit/react';

export function App() {
  const enabled = import.meta.env.DEV;

  return (
    <A3STestKit
      enabled={enabled}
      page={{ id: 'checkout' }}
      repairStorage="session"
      repairEndpoint="/__a3s-test/repairs"
      redact={['[data-payment-field]']}
    >
      <A3STestBoundary
        id="checkout-form"
        name="Checkout form"
        source={{ file: 'src/Checkout.tsx' }}
      >
        <Checkout />
      </A3STestBoundary>
      <A3SReviewOverlay enabled={enabled} locale="zh-CN" />
    </A3STestKit>
  );
}

A3STestKit 提供无界面的 Context Runtime。A3SReviewOverlay 是可选的人机界面,只有存在兼容的 live bridge 且 enabled 明确为 true 时才挂载。CI 通常保留 Context Runtime 并省略 overlay。

评审者可以标记什么

模式目标记录适合问题
元素一个当前节点和它的几何按钮文案、状态、间距、对比度或交互问题
文本选中文本、关联节点和范围错别字、缺失说明或内容表达
多选按选择顺序保存多个节点一组控件需要一致修改或共同验收
矩形区域视口 CSS 像素矩形和区域内上下文无单一 DOM 目标的布局、画布或组合问题
自由手绘有界点序列、外接区域和附近上下文不规则视觉区域
Layout Modeplacement 或 rearrange 类型化布局意图新增组件位置或移动现有区块

Overlay 打开后,E、M、T、A、D 分别进入元素、多选、文本、区域和手绘标记。L 切换 Layout Mode,P 暂停或恢复页面动效,H 控制标记显示。输入框、编辑器和其他可编辑控件会保留字母输入,不会被这些快捷键接管。

键盘多选时,把焦点移到宿主页面元素并按 Enter 加入,重复后按 Shift+Enter 完成并进入 finding 编辑器。Escape 先取消当前标记或编辑状态,再处理空闲面板。

一条 finding 包含什么

每个草稿都有稳定 ID、创建时间、目标、修改说明、可选成功条件、意图和严重程度。

字段允许值或含义
instruction人写的修改要求,必填
successCriteria可以在浏览器或聚焦检查中验证的结果
intentfix、change、question 或 approve
severityblocking、important 或 suggestion
target.kindnode、text、region 或 drawing
target.nodeIds发送时仍属于最新页面修订的私有目标
target.region可选视口 CSS 像素区域
target.regionScroll框选时记录的可选页面滚动偏移
relations当前只支持显式 conflicts_with

节点和文本标记会根据当前仍可解析的真实 DOM 元素定位。页面滚动、内部滚动容器、 可视视口移动和窗口缩放会触发一次有界刷新,重新读取 getBoundingClientRect()。区域、手绘和 Layout 目标仍通过 target.regionScroll 与页面内容保持对齐;节点已无法解析时,保存的区域才作为 兜底。

发送时,Test Kit 会重新读取当前修订并增加 contextRevision、页面、route、viewport、组件与 source 提示、语义定位器、目标与附近节点、facts 和有界 UI 理解。整个 context 标记为 untrusted: true。

页面文本、DOM 属性、facts 和 instruction 不会被拼进隐藏系统指令。编码 Agent 可以读取这些证据,但必须依据自己的权限和仓库规则决定允许的代码操作。

草稿、保存和发送不是同一件事

操作影响的存储是否进入 Repair Ledger是否授权编码 Agent
打开编辑器临时 overlay 状态否否
保存草稿选定的浏览器存储否否
复制 Markdown/JSON剪贴板否否
发送单项页面队列和 Repair Ledger是只限该 finding
发送选中项或全部稳定顺序的一批 finding是只限该批次

repairStorage 控制浏览器侧恢复范围。

值生命周期建议用途
memory当前页面运行,刷新后消失演示、测试夹具和一次性评审
session当前标签页会话,默认值日常本地开发
local同一 origin 的浏览器本地存储需要跨标签页重启继续整理草稿

隐藏 overlay 不会卸载 Context Runtime。自动发送只可在当前浏览器会话中明确开启,不写入持久偏好。页面动画暂停也不会跨重启保留。

单项、批量与冲突

单项发送只包含当前编辑的 finding。批量发送按照问题工作区中的可见顺序保留 finding ID,返回结果仍按项记录。批量不是文件系统事务,一项失败不会伪装成整批回滚。

两条要求在语义上互斥时,由评审者声明关系。

{
  "relations": [
    {
      "kind": "conflicts_with",
      "findingId": "finding-layout-expanded"
    }
  ]
}

如果互相冲突的 finding 都已进入队列,A3S Test 会把它们移到 needs_input。系统只比较明确的 finding ID,不根据否定词、颜色、布局术语或 instruction 文本猜测冲突。

提交通道

没有 repairEndpoint 时,当前 A3S Test 浏览器会话可以通过固定 bridge 操作读取页面队列。配置端点后,Test Kit 还会用同源凭据 POST 有界记录。

{
  "protocol": "a3s.test.repair/1",
  "repairs": [
    {
      "id": "finding-...",
      "batchId": "batch-...",
      "status": "queued",
      "contextRevision": 42,
      "context": {
        "untrusted": true
      }
    }
  ]
}

人工回复、接受、拒绝和重新打开使用同一协议的 actions 数组。端点应只接受同源 POST、校验内容类型和协议版本、限制请求体,并把记录转发给拥有该 Web 会话的 A3S Test。它不是 A3S Test 控制 API,也不应接收工作区路径、Shell、MCP、Git 或模型凭据。

端点失败不会删除浏览器侧队列。当前会话仍可提取并重试,避免一次网络错误丢失人工确认的问题。

修复状态机

draft -> queued -> claimed -> repairing -> verifying -> review_ready -> resolved
                    |             |           |
                    v             v           v
                cancelled     needs_input  verification_failed
                                  |           |
                                  +-----> failed

review_ready / resolved / dismissed -> reopened -> queued
状态谁推进含义
draft评审者仍在本地整理,没有发送
queued评审者或 A3S Test已明确发送,等待领取
claimed编码 Agent一个带 lease 和 attempt ID 的执行者领取
repairing编码 Agent已报告开始修改,不能静默交给另一个执行者
verifyingA3S Test修改已完成,等待新的 ready 修订并执行验证
needs_inputAgent 或 A3S Test目标重叠、冲突、租约风险或要求不清,需要人工处理
verification_failedA3S Test新页面证据未满足成功条件
review_readyA3S Test本地验证通过,等待人工验收
resolved人工或显式自动模式通过验收
dismissed评审者决定不继续该项
cancelled、failed人、Agent 或 A3S Test取消或失败,历史仍然保留
reopened评审者重新进入队列前的追加式状态

每次变化都有单调 sequence、actor、timestamp 和需要时的 attempt ID。非法状态跳转不会修改记录;相同 request ID 的终态操作保持幂等。

编码 Agent 如何领取

MCP 修复工具和 a3s-test agent repair-* CLI 使用同一应用层。

阶段MCP 工具编码 Agent 的责任
发现test_repair_inbox从活动会话 ledger 中排出最应恢复的工作
等待test_repair_watch先读取已排队项,再进行一次有界等待和批次收集
检查test_repair_inspect恢复完整循环状态和类型化下一步
领取test_repair_claim建立 lease 和 attempt ID,只领取一项
开始修改test_repair_progress在任何可能改动工作区的动作前报告 repairing
请求澄清test_repair_reply说明缺失信息并进入 needs_input
完成修改test_repair_complete报告修改结束,进入 A3S Test 拥有的验证,不宣称 resolved
执行验证test_repair_verify在新修订上规划可信切片或附加调用方检查结果
失败或取消test_repair_fail、test_repair_cancel保留原因与尝试历史

默认 claim lease 为五分钟。claim 返回的 attempt ID 必须用于 progress、reply、complete 和 fail。执行者在开始编辑前消失时,lease 可以把 finding 安全放回队列;已经可能改动工作区后失联时,A3S Test 会进入 needs_input,不会把同一次尝试静默交给另一执行者。

完成修改时会记录精确且有顺序的 changed_files 列表,包括显式空报告。验证必须重复同一列表;如果不同,A3S Test 会在连接浏览器前返回 test.session.repair_change_mismatch,避免接手的 Agent 验证另一组工作区改动。

目标范围过大时,编码 Agent 可以用组件、节点或区域 scope 做 forensic inspection。每次 inspection 都会替换最新观察并生成新的 @cN,旧引用不能继续使用。

不依赖聊天历史恢复

追加式 repairs.jsonl 始终是唯一事实源。先在当前工作区发现最应该继续的持久任务。CLI 可以扫描活动或已经关闭的会话,全程不会启动或连接浏览器。

a3s-test agent repair-inbox --json

只读的 a3s.test.repair-inbox/1 会依次返回过期 lease、正在编辑或验证的任务、最早进入队列的 finding、等待人工处理的任务和只能检查的记录。终态历史默认隐藏,只有显式传入 --include-terminal 才会出现。可以用 --session <session> 缩小扫描范围,用 --limit <1-100> 限制返回前缀。每一项都包含有界意图、当前 lease 状态和类型化下一步。

选定任务后,再读取完整恢复记录。

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

只读的 a3s.test.repair-loop-record/1 把人工指令和成功条件、结构化意图与目标、经过 Rust 校验的源码映射、当前 lease 和 attempt、完成修改时的 changed files、attempt 回复、验证切片与结果、紧凑的证据路径与 SHA-256、ACL 候选及证明状态,以及类型化下一步连成一条循环。完整 Page Context 不会被重复保存。

活动中的 MCP owner 可通过 test_repair_inbox 获取当前会话的 Inbox,再通过 test_repair_inspect 读取选中记录。生成的命令只使用经过校验的 ledger 标识符和固定占位符;页面内容、URL、源码映射与 changed-file 值都不会成为命令文本。过期的修改 lease 只返回 reconcile_lease,不会重放旧编辑命令。ACL 证明通过只代表候选在新浏览器中执行成功,不会把候选写入或提交到业务仓库。

A3S Test 如何验证修复

编码 Agent 报告完成不等于修复通过。A3S Test 在进入 review_ready 前执行以下步骤。

  1. 等待 Test Kit 出现更新后的 ready 修订,等待有明确上限。
  2. 重新观察并用语义定位器解析原目标或声明的替代目标。
  3. 执行明确、可由浏览器验证的 success criteria。
  4. 对比提交前由 A3S Test 记录的 console 和 page-error 基线。
  5. 捕获并哈希新的截图与有界 Page Context。
  6. 根据源码归属、changed files、稳定定位器、浏览器错误差异和最近一次既有 ACL 证明,规划版本化验证切片。
  7. 只运行切片选中的可信项目检查,或保留调用方明确提供的检查结果。
  8. 在新浏览器中生成并证明通过准入的 ACL 候选。

agent repair-verify 省略 --checks-json 时,工作区 CLI 会读取安装页中的可信目录。源码局部变化保持 focused。确定性贪心选择每次覆盖最多未覆盖 changed files 的 focused 检查,覆盖数相同时以配置顺序决定。

出现以下任一事实时,切片会扩大:缺少源码映射、稳定定位器或 changed files;changed file 位于映射源码之外或没有 focused 检查覆盖;新页面增加 console 或 page error;最近一次 ACL 证明失败。Expanded 范围优先选择已配置的 regression 检查;没有 regression 检查时选择整个目录。目录为空的 expanded 验证会失败关闭。

Repair Ledger 中的每次验证都会保留严格且版本化的决策记录:

{
  "protocol": "a3s.test.repair-verification-slice/1",
  "scope": "focused",
  "sourceFiles": ["src/Checkout.tsx"],
  "stableLocator": true,
  "priorAclProofPassed": null,
  "selectedChecks": ["checkout"],
  "expansionReasons": []
}

选中的命令直接派发,不经过 Shell。每条命令都有有界执行和清理时限,A3S Test 拥有对应的 Unix process group 或 Windows Job Object。超时、非零退出、残留后代进程或清理失败都会记录为检查失败。传入 --checks-json 会保留调用方报告模式,适合已经拥有命令执行权的 orchestrator,不会再执行项目目录。

Layout Mode 的 placement 必须有当前视口内可寻址目标区域。Rearrange 要求原节点或稳定替代目标与目的区域相交。节点仍然存在不能单独证明布局修改成功。

当 finding 同时有稳定定位器和明确文本条件时,A3S Test 可以生成语法通过的 ACL 回归候选,并在拥有同一网络策略的新浏览器会话中执行。候选不会自动写入业务仓库。

人工验收

默认流程停在 review_ready。评审者可以执行以下动作。

  • 接受并进入 resolved。
  • 拒绝当前结果并附上原因。
  • 回复 Agent 的澄清请求。
  • 对已解决、已拒绝、已取消或失败的 finding 选择重新打开。

--auto-resolve-repairs 只在调用方显式开启时生效,而且必须先持久化一条验证通过的 review_ready 事件。验证失败永远不会自动解决。

Repair Ledger 追加保留每次 attempt、回复、状态、前后证据和验收动作。重新打开不会覆盖旧结果。

Layout Mode 的边界

Placement 记录组件类型、page 或 wireframe canvas、可选页面目的和目的区域。Rearrange 还记录原区域、当前节点与目的区域。所有矩形使用视口 CSS 像素。

内置目录提供 90 种中英文组件类型,搜索和显示只帮助评审者填写结构化字段。自由输入的项目组件名称保持原文。目录项、页面目的和 overlay 预览不会变成隐藏修复指令。

Overlay 的线框、页面淡化、区域和目的位置都是 pointer-transparent 证据。它不会给宿主节点写 style、移动 DOM 或改变页面布局。

失败恢复

情况系统行为下一步
同源端点返回错误浏览器队列保留 finding修复端点后由会话再次提取
页面热更新使目标过期旧节点和 @cN 被拒绝重新观察并用语义定位器绑定
两项声明冲突两项进入 needs_input人工决定保留、修改或取消哪一项
Inbox 发现修改 lease 过期不返回旧编辑或验证命令先执行返回的有界 repair-watch 对账
claim 在编辑前过期finding 可安全回到队列新 attempt 重新领取
编辑开始后执行者失联finding 进入 needs_input检查工作区和实际改动,再决定继续或回滚
新页面修订未 readyverify 返回可重试结果,不做无限 sleep等待应用完成渲染后再次做有界验证
console 或 page errors 增加验证失败并保留前后基线修复新增错误后重新排队
expanded 切片没有可信检查验证记录一条失败的项目检查在项目 ACL 中声明有界 regression 检查
成功条件无法由浏览器证明不能进入 review_ready补充可验证条件或由人明确处理不可自动验证部分

查看Page Context 字段与生命周期理解 finding 随附的页面事实,查看权限与安全模型核对模型建议、人工授权和工作区修改之间的边界。