# Visual Evidence Conventions（截图 / 视觉证据交付约定）

> **作用域**：任何 AI 工具（Codex / Claude Code / Cursor / Cline / Gemini / 其它）在本仓库收发截图、视觉验收图、UI 对比图时遵循的工程约定。
> **不**作用于：用户与 AI 之间纯人类沟通的随手截图（用户 review 体感图无所谓）。

---

## 背景：为什么这条规则存在

主流 AI 工具对**单次会话内图片**有硬上限（典型为单图长边 ≤ 2000px，多图会话同时生效）。撞限会强制中断会话、丢失 in-flight context，必须新开 session。

- macOS Retina 屏全屏截图原始分辨率天然 2400px+（DPR=2）
- VS Code / Browser 全窗口截图通常 1800–2800px
- 多图会话（同一 thread 多张视觉验收图）累积撞限概率 ~100%

**已实证**：2026-05-08 F19 视觉验收阶段连续撞限两次，迫使 executor 中断重启 session。

---

## Hard Rules

### V1 — 视觉验收**默认走脚本文本输出**，截图是兜底

UI 对比 / 视觉验收任务的 ground truth **必须**是机器可读的文本输出（pass/fail + 具体差异），**不**是截图。

✅ 范式参考：[`.f19-visual-audit.mjs`](../../.f19-visual-audit.mjs)

```
=== summary ===
topbar       dark=0 light=0 same
badge        dark=0 light=0 same
notification dark=0 light=2 different  ← 这种行才需要补截图
```

只有当脚本报"差异 > 0"时才补充对应截图作为定位证据。**禁止**让 executor 一次性贴 18 张全页截图给 reviewer 肉眼对比。

**Why:** 肉眼对比不可重现、不可 grep、累积撞 2000px 限制。脚本输出 = 单一真源 + 可 diff + 不污染会话 context。

### V2 — 截图长边 ≤ 1800px

任何要进入 AI 会话的截图（剪贴板粘贴 / 工具自动截屏 / 文件上传）**必须**先 resize 到长边 ≤ 1800px。1800 是 2000 的安全 margin。

macOS 批量缩：

```bash
sips -Z 1800 path/to/*.png
```

单图：Preview 打开 → `⌘K` 调整尺寸。

**Why:** 留 margin 防止下游工具（Codex / Claude Code / Cursor）任何一家把限制收紧到 < 2000 时全盘失效。

### V3 — 大图必须落盘走 `Read`，不走剪贴板

需要让 executor 看大尺寸图（如设计稿全图 / 长截图）时：

1. 存到磁盘任意位置（推荐 `/tmp/` 或 `docs/internal/_audit-snapshots/`，后者会进 git 慎用）
2. 在 prompt / 对话里写**绝对路径**
3. 让 executor 用 `Read` tool 读

**禁止**：把 3000px+ 大图直接粘贴进对话。剪贴板粘贴走的是"many-image"通道，会撞 2000px 限制；`Read` tool 走的是文件读取通道，限制更宽松（取决于具体工具）。

### V4 — 撞限后该 session 不可恢复

一旦工具报错"image exceeds dimension limit"或类似消息：

- ❌ 不要重试同样操作
- ❌ 不要清理对话内某张图试图"瘦身"——上下文已污染
- ✅ STOP 当前任务，把进度落盘（commit / 写报告 / 更新 plan）
- ✅ 新开 session，按 V1–V3 重新进入

---

## Process Rules

### V5 — 视觉验收脚本的产出契约

新写视觉验收脚本（参考 `.f19-visual-audit.mjs`）时，输出**必须**至少包含：

| 字段 | 用途 |
|---|---|
| 页面 / 单元名 | 定位 |
| 差异计数（`different=N`） | 机器判定 pass/fail |
| `same` / `different` 二元结论 | reviewer 一眼可读 |
| 差异截图绝对路径 | 仅当 `different > 0` 时输出 |

输出格式参考 `=== summary ===` block。reviewer / plan owner 应能直接 grep `different=[1-9]` 找到所有 fail 项。

### V6 — Executor prompt 里**不要**期望"对话内多图对比"

写 executor prompt 时（`docs/internal/_prompts/<name>.prompt.md`）：

- ❌ "请对比下面这 18 张截图…"
- ❌ "看一下我贴的设计稿…"
- ✅ "跑 `node .f19-visual-audit.mjs` 拿文本结论；如有 different，读 `/tmp/f19-screenshots/<name>.png` 定位"
- ✅ "设计稿落在 `docs/internal/_audit-snapshots/<name>.png`，用 Read 读"

**Why:** executor 是无状态的——每次 fresh session 收到 prompt，对话内的图都是新粘的，立刻进入累积撞限轨道。把视觉证据接入"脚本 + 文件"通道，executor 的 session 永远不会因为图片大小中断。

---

## 已知会触发撞限的反模式

| 反模式 | 替代 |
|---|---|
| 直接粘贴 macOS 全屏截图 | `sips -Z 1800` 后再贴；或落盘让 `Read` |
| reviewer 让 executor "把每个 page 都截图发给我看" | 跑视觉验收脚本，发 summary 文本 |
| 在同一 session 里反复贴新 round 的对比图 | 每 round 新开 session 或走脚本输出 |
| 设计稿原图（5000px+）粘进对话 | 落盘 + `Read` 路径 |

---

## 历史背景

- **2026-05-08** — F19 docs site 主题统一阶段，executor (Codex) 视觉验收时连续撞 2000px 限制两次，被迫中断 session。复盘发现：脚本 `.f19-visual-audit.mjs` 已经能给出文本结论，但流程未约定优先信脚本，导致 reviewer 习惯性要求贴大图。本文档由该 incident 产生。