Oil Frontend

从用户任务和完成结果出发，修复真正出错的信息、交互、数据流、布局或共享实现。

核心原则

• 沿用用户对浏览、选择、编辑和提交的已有认知；可见内容服务于识别、判断、操作和结果反馈。
• 同一业务数据有明确的权威来源，一个用户意图只执行一次；失败时保留对象、位置和已输入内容。
• 优先使用项目已有的设计变量、组件和成熟能力；既有模式错误时修复源头。简单逻辑直接实现，不为少量代码引入依赖。
• 把用户时间、工具调用和上下文 Token 作为执行成本；在覆盖目标风险和必需门禁的前提下，按需取证、合并改动与验证，证据充分即停止。

按需读取

1. 先读本文件作为入口，再看用户提供的证据和相关实现，定位要改变的结果与影响范围；不先通读参考规范再找问题。仅修导入路径等机械错误时停止，不读取参考文件。
2. 在确定方案和修改前，按目标或初步证据选择一个主要规则；不必先证明完整根因，也不按文件扩展名、CSS、动画关键词或参考文件中的链接追加读取。
3. 出现当前规则无法处理的独立问题时，才补充对应规则；复杂任务按阶段读取，不预先加载全套，也不因固定数量上限遗漏必要规则。当前上下文已有完整且未变化的规则时直接复用，不重复读取。

优先按要改变的行为或已知故障选规则；列表、表单等承载形式只在其结构本身需要调整时作为主要路由。表中“涉及”指本次要改变或存在待解决问题，不是代码里恰好出现该元素。

当前任务	主要规则	仅在这些情况补充
“看起来不对”、视觉精修、层级、间距、排版、颜色、圆角、边框、阴影或图标的尺寸、颜色与对齐	视觉工程	需要修改共享 Token、组件默认样式或变体时读 组件与代码组织；改变分栏、滚动或响应式结构时改读 视口与弹窗 为主要规则；同时改变图标或动作含义时读 信息与动作
动画、过渡、微交互、展开收起、拖拽反馈、滚动动效或卡顿	动效与性能	动效承担动作反馈或视觉层级时读 视觉工程；根因是异步状态时改读 状态与加载 为主要规则
前端测试策略、端到端方案设计、测试清理或检查规则调整	自动化	只有检查确实发现需要修复的业务问题时，才补充对应规则；仅运行已有检查不额外读取
模块边界、组件、Hook、函数、类型、样式归属、共享样式、CSS 组织或共享实现	组件与代码组织	需要为未覆盖风险设计检查，或清理脆弱、重复、失效检查时读 自动化
文案、动作层级、图标含义与必要性、点击反馈或强调含义	信息与动作	涉及对象身份、图片或选择器时读 资源识别；同时改变颜色、尺寸或对齐时读 视觉工程

数据、交互与空间：

当前任务	主要规则	仅在这些情况补充
列表、卡片、详情、表格或批量操作	集合与详情	涉及资源身份时读 资源识别；涉及编辑时读 交互与编辑
表单、选择、编辑或多步工作流	交互与编辑	涉及保存范围和流程连续性时读 数据与操作范围
查询结果、分页、候选集合、保存范围、批量范围或请求结果归属	数据与操作范围	同时改变 loading、refreshing、empty、error 或 processing 呈现时读 状态与加载
loading、refreshing、empty、filtered-empty、error、queued、processing 或骨架	状态与加载	同时涉及查询快照、操作范围或保存结果归属时读 数据与操作范围
改变页面尺寸、分栏、滚动、弹窗结构或响应式行为	视口与弹窗	涉及下拉、菜单、提示等依附触发器的浮层时读 弹层
对象身份、图片或相邻资源区分	资源识别	需要改变集合结构或编辑流程时，补充对应规则
下拉、菜单、日期面板、提示或依附触发器的浮层	弹层	需要改变承载方式时读 视口与弹窗

执行流程

只处理与当前目标有关的步骤，不为局部改动补齐全套问题。评审请求只给证据和建议；要求实现或修复时才修改。

1. 还原任务与范围

• 明确原问题、操作入口和预期结果；检查相关实现、数据来源与项目既有约定。
• 先查相关入口、符号和局部实现，证据不足再沿调用关系扩大；复用已有截图、日志和定位结果，不为了解全貌先扫描整个项目。现有证据不足以决定方向时，做有明确问题的最小运行复现；追加取证必须针对尚未解决的疑点。
• 涉及数据或交互时，确认对象、字段归属、查询集合、操作范围和提交边界；涉及布局时，确认父容器、滚动与视口边界。
• 修改共享实现前查找受影响的使用位置。只有缺失信息会改变实施方向且无法从项目确认时才提问，不为无关信息中断任务。

2. 确定结构与修改落点

• 根据识别、比较、选择或编辑任务确定必要内容和承载方式；删除重复信息与操作，不为完整感增加字段、步骤或装饰。
• 沿用项目已有的 Token、组件和相邻同类模式；视觉差异须能落实到具体元素、属性和依据，缺少标准时按视觉规则采用有限兜底。
• 区分数据流、父布局、共享组件与调用方式的责任，修改真正出错的位置；按业务归属组织代码，只有职责和行为稳定复用时才抽象。
• 必要动作缺少真实结果时补齐行为；无法提供的动作不伪装成可用。新实现接管后清理失效代码和引用，仍有真实兼容对象时明确保留原因与删除条件。
• 完成受影响使用位置的迁移；超出当前授权范围时说明剩余项，不扩大旧模式或修改无关区域。

3. 验证实际结果

• 开始修改时确定要验证的行为和最小检查集；同一目标下可一起验证的改动先完成，再集中检查。不每改一个文件或样式就启动浏览器、截图或重跑整套检查；大任务按可独立验收的阶段合并，不把所有验证拖到最后。
• 相关的类型、导入等低成本检查可以随实现需要运行，不强制每批先跑全套。浏览器等高成本检查默认集中执行；运行证据会改变后续方案、需要捕获偶发故障或验证高返工成本的假设时提前取证，必需门禁照常执行。
• 优先从真实入口完成受影响的操作链，检查必要中间反馈与最终结果；保存类修改要重新读取，不能只确认回调或请求发出。
• 复用项目现有且相关的检查与必需门禁；简单样式、文案或排列直接检查实际结果，不默认新增测试、快照或完整状态矩阵。
• 浏览器检查复用可用会话、页面和登录状态，一次会话覆盖本批相关检查点；只获取判断结果所需的截图、DOM 或日志，不反复输出整页内容。只在隔离状态确有必要时重建环境。
• 视觉与动效使用真实内容、受影响状态和代表性视口验证；静态检查与截图生成本身不能证明实际表现正确。
• 需要设计、补充或清理长期检查时，按路由读取自动化规则；只保留能发现独立行为错误的验证。目标风险已有充分证据时停止；后续修复只重跑受影响的检查，影响范围不明或门禁要求时才扩大。相关实现或环境变化后，不能沿用已失效的通过结果。

独立自检

共享行为有多种不同使用场景、跨模块状态流或大范围规则调整存在较高遗漏风险时，派发无历史上下文的独立自检；不因文件或页面多就自动派发。局部差异、行为不变的重复迁移由主 Agent 检查。自检在本批改动稳定后集中执行，后续只复查受修复影响的部分。没有隔离执行能力时直接自检并说明限制。

独立自检只接收检查对象、范围、用户要求与验收约束和 oil-frontend，不接收对话历史、既有结论、问题猜测或修复方案；按问题读取规则，不重复完整实施流程。

输出

按当前任务报告具体问题或已完成改动、依据、实际验证结果与未验证项。只在确有删除、迁移或遗留工作时说明，不强制填满固定栏目，不用测试数量或“更现代”等空泛评价代替证据。区分源码检查、本地运行和目标环境生效。

不主动扩展为无障碍专项审计；实现时使用原生交互元素，保留项目已有的焦点、键盘、标签和 ARIA 行为。当前改动直接造成任务不可完成时检查相应问题。