# Reasonix Browser Test Contract v1

## 状态

- 状态：reference
- Owner：AI runtime / browser verification
- 背景：Reasonix 已能作为独立辅助 agent 执行只读审计，但浏览器验收若只输出自然语言结论，主控仍需重测，无法稳定节省 token。

## 目标

把 Reasonix 浏览器测试从“描述性结论”收口为“可审计证据包”。Codex/Hermes 主控只接受带截图、日志、网络、断言和环境前置条件的 Reasonix 浏览器结论。

## 非目标

- 不让 Reasonix 直接裁决业务 bug 是否完成。
- 不让 Reasonix 修改源码、提交 git、回滚文件。
- 不把浏览器测试结论写成长期产品事实源；长期事实仍以 bug/design/checklist 和真实验证日志为准。

## 合同

每个 Reasonix 浏览器测试任务必须产出以下文件：

```text
result.json
final.md
process-handoff.md
process-handoff.json
artifacts/
  screenshots/
  console.json
  network.json
  trace-or-steps.md
```

`result.json` 至少包含：

```json
{
  "status": "passed | failed | blocked",
  "run_id": "reasonix-...",
  "target_url": "http://127.0.0.1:3000",
  "environment": {
    "dev_server_restarted": true,
    "cache_cleared": true,
    "browser_context": "isolated",
    "auth_mode": "test-account",
    "workspace_root": "/tmp/..."
  },
  "steps": [
    {
      "name": "upload first attachment",
      "action": "drag file into editor",
      "screenshot": "artifacts/screenshots/01-upload-first.png"
    }
  ],
  "assertions": [
    {
      "name": "attachment opens in tab after second upload",
      "expected": "tab count increases and active tab kind is resource",
      "actual": "click produced no tab change",
      "passed": false,
      "evidence": "artifacts/screenshots/04-click-after-second-upload.png"
    }
  ],
  "console_errors": [],
  "network_failures": [],
  "screenshots": [],
  "modified_files": []
}
```

## 浏览器前置条件

- 测试前重启 `npm run dev:hot` 或复用主控明确提供的已重启服务。
- 使用全新 isolated browser context；清空 cookies、localStorage、sessionStorage、IndexedDB、Cache Storage。
- 默认使用 `http://127.0.0.1:3000/auth` 的测试账号快速登录。
- local-first 测试必须创建临时页面或临时 workspace，并记录路径。
- 所有上传文件路径必须记录，不能只写“上传文件”。

## 截图要求

用户可见 bug 至少保留：

- 初始状态截图。
- 关键动作后截图。
- 失败状态截图。
- 修复验证时的通过状态截图。

如果 bug 涉及 “点击无反应”，必须同时记录：

- 点击前 tab 列表。
- 点击后 tab 列表。
- 点击目标节点截图。
- console/network。

## 0524 试验集映射

`bugs/0524.md` 可作为第一批协同测试样本：

1. 我的空间拖入附件路径错误：
   - 验收：上传后文件实际路径应在当前页面 bundle/下级，而不是与主文件夹同级。
   - Reasonix 输出：文件树截图、实际磁盘路径、上传请求、编辑区附件截图。
2. 上传后文件冲突：
   - 验收：本页面不误报自写冲突；新建页面不继承旧冲突状态。
   - Reasonix 输出：冲突弹窗截图、页面切换后截图、console/network。
3. 隐藏本地 Markdown 标题设置：
   - 验收：不同 workspace/source 的默认值区分，用户选择刷新后保持。
   - Reasonix 输出：设置变更前后截图、刷新后截图、local/session storage 或后端请求证据。
4. Ctrl+Z/Ctrl+Y 删除链接：
   - 验收：删除附件链接后 undo/redo 可恢复/再次删除。
   - Reasonix 输出：键盘动作步骤、编辑区 DOM/截图、断言结果。
5. md 文件上传后黑色方块刷新变灰：
   - 验收：上传前后和刷新后附件 icon 状态一致，或有明确缺失状态样式。
   - Reasonix 输出：刷新前后截图、附件节点属性。

## 主控接受条件

Codex/Hermes 只有在以下条件满足时，才能把 Reasonix 浏览器结果作为验收证据：

- `result.json` 存在且能解析。
- 至少一张截图能直接显示用户可见状态。
- console/network 不为空时已被解释；为空时明确记录为空。
- `modified_files` 为 `[]` 或 `none`，确认 Reasonix 没有改源码。
- `process-handoff` 已 retain 到 Hindsight，主控可 recall。

## 失败处理

- 缺截图：结果降级为线索，不作为验收。
- 缺 console/network：UI 失败只可作为复现证据，不可作为根因证据。
- 没清缓存或没隔离 browser context：结果标记 `blocked` 或 `needs_rerun`。
- Reasonix 修改源码：本次测试作废，主控检查 diff 后决定是否保留建议。

## 评价指标

- accepted_browser_findings：Reasonix 浏览器发现最终被主控采纳的数量。
- false_browser_leads：Reasonix 浏览器结论导致主控走错方向的数量。
- retest_required_ratio：主控必须完全重测的比例。
- artifact_read_time：主控读取证据包并形成判断所需时间。
- missing_artifact_count：缺失截图、console、network、断言的数量。

## Done Gate

- [ ] `reasonix-browser-tester` skill 已补入本合同的最小 artifact 要求。
- [ ] 使用 `bugs/0524.md` 中至少 1 个 bug 进行 Reasonix 浏览器试跑。
- [ ] 试跑后记录 accepted findings / false leads / retest required。
- [ ] 根据试跑结果更新本合同或 Reasonix skill。

## 2026-06-01 降级说明

本合同对应的全局 `reasonix-browser-tester` skill 已存在，并已包含 `result.json`、截图、console/network、isolated context、`modified_files` 等 artifact 要求。本文不再作为 MNote 产品 runtime 的 active process 项，降级为协作参考；后续若要继续试跑 `bugs/0524.md`，应在 Reasonix skill 维护流程或独立复盘文档中跟踪。