#人工评审与自动修复

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。

#评审者可以标记什么

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

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

#一条 finding 包含什么

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

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

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

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

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

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

隐藏 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

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

#编码 Agent 如何领取

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

默认 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 或改变页面布局。

#失败恢复

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