视觉修复 是做什么的？
将单个可见的UI问题转化为一个本地化、已批准、已验证的代码更改。
支持的证据
接受任何有用的组合：
- 当前UI的屏幕截图
- 屏幕截图中带注释或描述的区域
- 当前与目标屏幕截图，并标识其角色
- 路由、视口、组件名称、可见字符串、选择器或测试ID
- 通俗语言的症状描述，如"此卡片被裁剪"或"这些控件未对齐"
仅询问那些会阻止可靠定位的证据。一条路由加上唯一的可见字符串可能足以完成定位，无需屏幕截图。即使有屏幕截图，如果包含重复组件，可能仍需要路由、标签或状态信息。
一次只处理一个视觉问题。将无关的症状拆分到单独的修复中。
工作流程
1. 确立目标
用具体术语重新表述有明确范围的结果：
- 现在看起来有什么问题
- 用户期望看到什么
- 相关的路由、组件、状态和视口（如已知）
- 标识目标的可见锚点
如果请求的结果带有主观性，或者可能影响不同元素，提出能区分它们的最小问题。
2. 建立只读基线
在编辑之前：
- 找到仓库的说明和真实来源。
- 检查工作树状态，保留现有的用户更改。
- 识别框架、路由入口、组件树、样式系统和可用的运行或测试命令。
- 在环境允许时重现目标路由和视口。
- 在更改之前捕获或记录当前状态。
不要编辑生成的输出文件，如果存在受维护的源文件。不要清理或覆盖无关的工作树更改。
简要报告基线：
上下文
- 路由/状态：/catalog，筛选器已打开
- 视口：390 x 844
- 真实来源：src/routes/catalog.tsx + src/styles/catalog.css
- 现有用户更改：无
- 重现：可用
3. 定位渲染源
将证据从渲染元素追溯到受维护的代码。使用路由、可访问名称、可见文本、DOM选择器、组件名称、测试ID、类、样式令牌或截图几何信息。当涉及多个文件或样式层时，阅读 references/locating.md。
确定一个主源位置和最多两个必需的关联位置。文件及行号证据必须来自当前工作树。
定位结果
- 主源：src/components/ProductGrid.tsx:42，ProductGrid
- 关联：src/styles/products.css:18
- 证据：`.grid` 控制了卡片之间可见的重复水平间距
- 置信度：高
如果仍有两个相似元素看似合理，解释区分它们的证据并停下来请求澄清。
4. 从证据进行诊断
将可见症状与实际代码联系起来。优先支持一个根本原因。只有当证据仍然模棱两可时，才提出两到三个假设。
对于每个假设，包括：
- 涉及的属性、选择器、令牌或组件
- 支持它的代码或呈现证据
- 预期的修复方向
- 一个可以反驳它的观察
不要根据屏幕截图臆测CSS值。首先检查当前值和周围的设计系统。
5. 展示精确的变更计划
在编辑之前展示提议的补丁：
变更计划
- 文件：src/components/ProductGrid.tsx:42
- 当前值：gap: 8px
- 提议值：使用现有的 space-4 令牌（16px）
- 范围：/catalog 和 /search 上的 ProductGrid
- 保持不变：卡片内边距、移动端列数、不相关的路由
- 验证：针对性测试、lint、在 390 x 844 和 1280 x 800 视口的屏幕截图
- 风险：中等；该组件被两个路由共享
等待此计划的明确批准。选择一个诊断结果并不等同于批准代码更改。如果计划后来扩展到其他文件、依赖项、锁定文件、生成的工件或路由，则展示修订后的计划并再次获得批准。
6. 应用批准的补丁
进行实现计划所需的最小更改。保持编辑在已批准的文件和范围内。然后立即检查差异：
- 当项目使用Git时，运行
git diff --check。 - 确认差异仅包含计划中的更改。
- 保留预先存在的更改，避免无关的格式混乱。
- 除非另有授权，否则不要提交、推送、安装依赖项或修改外部服务。
7. 验证结果
在声称成功之前，阅读 references/verification.md。
使用最强的可用证据：
- 运行与被更改代码相关的针对性测试、格式化、类型检查或构建。
- 重新渲染用于基线的相同路由、状态和视口。
- 在视觉上比较修改前后。
- 当更改的源具有更广泛的范围时，检查一个附近的视口或共享路由。
精确报告一个验证状态：
已验证视觉当存在可比较的修改前后渲染证据时已验证静态当代码检查通过但UI无法渲染时无法验证视觉当环境缺少路由、浏览器、夹具或启动路径时验证失败附带失败的命令或观察到的回归
如果验证失败，返回诊断阶段。不要在第一个修复之上堆叠未获批准的第二个修复。
完成报告
保持交接紧凑且基于证据：
已修复
- 目标：移动宽度下的目录卡片间距
- 源：src/components/ProductGrid.tsx:42
- 更改：gap 现在使用 space-4
- 验证：在 390 x 844 已验证视觉；单元测试和 lint 通过
- 更广泛的检查：/search 在 390 x 844 和 /catalog 在 1280 x 800
提及任何剩余的视觉不确定性。绝不要将代码差异描述为视觉证据。