oil-frontend

name	oil-frontend
description	用于实现、修改、重构或评审产品前端。当前任务涉及页面、组件、交互、表单、状态、数据流、Hook、类型、视觉层级、排版、颜色、圆角、阴影、图标、响应式、动效、改变可见结果的 CSS 或前端代码组织时自动触发。触发后先阅读 SKILL.md，按任务的主要决策只加载最小规则集。纯 CSS 语法、导入或类名修复且不改变界面结果时不触发；纯构建、部署、依赖升级、安全、后端任务，以及只解释前端概念而不处理项目实现的请求也不触发。

Oil Frontend

先识别用户任务、业务对象和数据来源，再删除无效内容，建立正确的信息、状态、代码归属和共享实现。

始终遵守

• 从真实用户任务、业务对象和完成结果出发；可见内容只保留能够帮助识别、比较、判断、操作或理解结果的信息。
• 一个用户意图只执行一次，动作必须产生真实结果；数据、操作、忙碌和提交边界保持一致，失败时保留当前对象、位置和已输入内容。
• 常见任务沿用用户已有认知；资源浏览默认展示，编辑必须明确触发，表单只收集当前任务必需且归当前对象所有的数据。
• 图标、强调方式和固定尺寸都必须表达稳定含义；不使用通用 AI 装饰、无意义强调边或只适配当前实例的尺寸制造层级。
• 视觉调整先沿用项目已有的设计变量、组件和密度，再处理层级、间距、排版、表面与反馈；没有项目标准时才使用参考规则中的兜底值，不把兜底值扩张成新的设计系统。
• 同一业务数据和同一含义只保留一个权威来源；优先修复数据流、父布局和共享实现，不在页面使用位置反复打补丁。
• 按业务归属组织组件、Hook、函数、类型、样式和测试；单模块代码就近放置，只有稳定跨模块复用时才进入共享层。
• 遇到复杂逻辑，先检查项目已有能力和成熟库；已有依赖不合适时，可以引入维护良好、与项目兼容的新库，不手写已有成熟方案覆盖的核心能力。简单逻辑直接实现，不为少量代码引入新依赖。
• 项目历史不是正确性的证明；错误模式应被替换，相关使用位置完成迁移后删除旧代码、fallback、legacy 逻辑和失效状态。

参考文件读取顺序

1. 触发后先只阅读本文件，明确任务、对象和改动范围，不预先读取参考文件。
2. 如果任务不涉及用户可见界面、前端状态与数据流、组件实现或前端代码组织，停止使用本 Skill。
3. 先按用户要改变的结果选择一个主要规则，不按文件类型或代码中出现的 CSS、动画关键词选规则。
4. 简单局部改动只读取一个主要规则；任务确实同时包含第二个独立问题时才补充一个。只有跨页面综合评审可以读取三个，不得更多。
5. 不因关键词出现、文件内链接或“保险起见”继续读取规则。视觉症状由数据、状态或父布局造成时，读取真正负责根因的规则，不额外加载视觉规则。

当前任务	主要规则	仅在这些情况补充
“看起来不对”、视觉精修、层级、间距、排版、颜色、圆角、边框、阴影或图标	视觉工程	需要修改共享 Token、组件默认样式或变体时读 组件与代码组织；改变分栏、滚动或响应式结构时改读 视口与弹窗 为主要规则
动画、过渡、微交互、展开收起、拖拽反馈、滚动动效或卡顿	动效与性能	动效承担动作反馈或视觉层级时读 视觉工程；根因是异步状态时改读 状态与加载 为主要规则
模块边界、组件、Hook、函数、类型、样式归属、共享样式、CSS 组织或共享实现	组件与代码组织	需要新增检查时读 自动化
新增或改变文案、动作含义、图标、点击反馈或视觉强调	信息与动作	涉及对象身份、图片或选择器时读 资源识别
列表、卡片、详情、表格或批量操作	集合与详情	涉及资源身份时读 资源识别；涉及编辑时读 交互与编辑
表单、选择、编辑或多步工作流	交互与编辑	涉及保存范围和流程连续性时读 数据与操作范围
查询结果、分页、候选集合、保存范围、批量范围或请求结果归属	数据与操作范围	同时改变 loading、refreshing、empty、error 或 processing 呈现时读 状态与加载
loading、refreshing、empty、filtered-empty、error、queued、processing 或骨架	状态与加载	同时涉及查询快照、操作范围或保存结果归属时读 数据与操作范围
改变页面尺寸、分栏、滚动、弹窗结构或响应式行为	视口与弹窗	涉及下拉、菜单、提示等依附触发器的浮层时读 弹层

以下情况不触发额外读取：

• 代码中存在 Tailwind、CSS、transition 或动画库，不代表任务是视觉或动效任务。
• 改变颜色、间距、边框、阴影、排版等可见属性时，以视觉工程为主要规则；只有任务同时要求调整样式归属、共享方式或模块边界时才补充组件与代码组织规则。
• 只修复颜色变量名、类名、类型或导入错误，且不改变视觉结果时，不读取视觉工程规则。
• 只为既有动效改业务状态、事件绑定或数据来源，且不改变运动方式和性能时，不读取动效规则。
• 只移动现有控件，且不改变文案、动作含义或反馈时，不读取信息与动作规则。
• 只调整普通父子容器归属，且不改变尺寸、滚动、弹窗或响应式行为时，不读取视口与弹窗规则。
• 参考文件中的链接只说明相关规则的位置，不表示必须继续读取。

术语速查

本文件和参考规则中的核心词汇，按这里的定义理解：

• 资源身份：让用户认出"这是哪个对象"的最小信息组合——图片 + 名称 + 一个区分字段。例：成员列表显示"头像 + 姓名 + 部门"，而不是"uuid + 类型标签"。
• 伪操作：看似可用、实际不产生真实结果的控件。例：点"保存"只改了本地 state、刷新即丢失；删除按钮永久 disabled 占位。
• 单个组件的视觉补丁：在页面使用共享组件的位置，只给这一个组件补样式。例：<Dialog className="h-[640px]">、!important 覆盖、页面专属选择器改组件内部。正确做法是修共享组件本身，或新增按用途命名的组件变体。
• 按用途命名的组件变体（variant）：用“为什么不同”命名。例：variant="destructive"、size="compact" 合格；variant="blue"、variant="userListPage" 不合格。
• 主导动作：当前页面、弹窗或操作区域中完成主要任务的那一个操作。同一区域最多一个高强调按钮。
• 提交边界：一次修改何时真正生效——即时生效、自动保存、显式统一提交，或仅临时预览。
• 忙碌范围：请求进行中需要防止重复操作的最小区域。单项请求只锁定该项，不用全页遮罩。
• 已提交查询快照：由同一次响应共同确定的查询条件、列表、结果总数和分页信息。新查询完成前，旧快照仍属于旧条件。
• 同类批量任务：对一批同类对象重复填写相同字段的任务，如批量排期、批量改价。
• 可编辑工作表：为同类批量任务让多行持续处于编辑态的表格。与之相对的是资源列表：默认展示，编辑必须明确触发。

决策顺序

改动前依次回答。

任务与对象：

1. 用户当前要完成什么任务，什么结果表示完成？
2. 页面管理哪个核心对象，字段分别归谁所有？
3. 当前是浏览、比较、选择还是编辑，是否沿用用户熟悉的结构和术语？

数据与范围：

4. 数据来自完整集合、当前可见集合还是搜索结果？
5. 操作、忙碌状态和提交边界分别影响什么范围；远程查询条件与当前列表是否已经属于同一次已提交结果？
6. 用户靠哪些信息区分相邻对象？
7. 能否删除文字、步骤、确认、重复输入或系统已经知道的字段？
8. 哪些信息属于集合，哪些只属于详情？

结构与状态：

9. 当前页面、弹窗或操作区域的主导动作是什么？
10. 首屏、滚动容器和弹层边界分别由谁负责？
11. loading、empty、filtered-empty、queued、processing、error、ready 如何互斥？

视觉与动效，仅在任务要求改变时回答：

12. 当前项目用哪些 Token、组件和相邻页面定义层级、密度与动效语言？真正不一致的是哪个可见属性？
13. 动效是在反馈状态、解释空间关系还是装饰；能否只使用 transform、opacity 或已有组件能力完成？

落点：

14. 是否已有正确归属的模块、组件、Hook、函数、类型、统一设计变量或样式，最终应修改哪个数据源、父布局或共享实现？

无法明确回答时，先停止添加界面元素：向用户提出最关键的 1–2 个问题；无法提问时按最小可验证范围实施，并在输出中声明所做的假设。

执行流程

1. 还原事实

• 搜索项目已有的模块、组件、Hook、函数、类型、统一设计变量和样式，确认相同含义是否已经存在正确实现。
• 找出所有使用共享组件的页面和组件，以及相同数据的其他入口。
• 评审请求只给证据与建议；用户要求修改时才实施。

2. 明确范围

• 明确核心对象、字段所有者、数据集合、操作范围、忙碌范围和提交边界。
• 区分页面结构问题、组件默认行为、页面使用方式错误和数据流错误。
• 视觉问题只记录能够指出具体元素、属性、现有依据和代码落点的差异；不能确定正确值时先使用项目既有 Token 或相邻同类组件，不凭审美发明精确数值。

3. 先删除

• 删除不影响判断的内容、重复状态、重复入口、重复确认和只针对单个组件的视觉补丁。
• 删除没有真实状态变化或不能真正保存数据的伪操作。
• 删除已经被新实现替代的旧组件、旧函数、旧类型、旧状态、fallback、legacy 逻辑、旧样式和失效引用。

4. 选择结构

• 先检查项目中同类任务页面和共享容器组件的既定用法；只有既有模式符合本规范时才沿用，否则按真实任务重新选择结构。
• 根据浏览、比较、选择、批量配置或深度编辑任务，选择列表、表格、工作表、选择器、弹窗或完整工作区。
• 让列表负责识别和比较，让详情负责完整内容，让编辑器负责修改。
• 视觉调整按“信息层级 → 空间与对齐 → 排版 → 表面 → 控件状态 → 动效”的顺序处理；前一层已经解决问题时停止，不继续叠加装饰。

5. 修复真正出错的位置

• 优先修复数据范围、操作范围、父布局、共享组件默认行为和含义稳定的组件变体。
• 重复出现的资源身份、菜单、弹层、加载、弹窗和操作栏使用共享组件。
• 只有职责、输入输出和行为稳定重复时才抽象；不要因为局部结构相似就复制组件，也不要用大量页面开关制造万能组件。
• 既有共享组件、函数、样式或数据流本身错误时，在授权范围内直接修复或替换真正出错的共享实现，并处理所有受影响的使用位置；不要为了兼容历史继续新增错误实现。
• 无法在当前范围内全部改完时，停止扩大旧模式，明确报告还剩哪些旧使用位置以及这次改到哪里，不得声称已经统一。
• 修复可重复检测的问题时，判断项目是否确实需要新增 lint、测试或检查规则；需要时按路由表补充读取 自动化，并计入补充规则数量。小改动不为此前置搭建自动化。
• 不修改无关区域。

6. 验证

• 运行项目现有且与改动相关的类型检查、Lint、测试或构建。
• 简单局部改动只检查修改位置、直接行为和最近的使用位置，不展开完整状态矩阵。
• 改动涉及共享组件、数据范围、异步状态、表单流程、滚动、响应式或多个页面时，再检查受影响的状态、数据范围、代表性视口和全部使用位置。
• 视觉改动检查真实内容、主要状态和受影响视口；动效改动只按类型检查适用的中断、重复触发、退出、卸载或滚动行为。只有复杂动效或真实卡顿才使用性能录制，不把每个过渡升级成性能专项。
• 只报告已验证项、未验证项和阻断原因。

独立自检

仅当前端评审涉及多个页面、所有使用共享组件的位置、多种视口或状态，或大范围规则调整时，才派发无历史上下文的独立自检。单页面、单组件、单截图和局部差异由主 Agent 直接检查。

独立自检只接收检查对象、范围和 oil-frontend，不接收对话历史、既有结论、问题猜测、预期答案或修复方案。

输出要求

先给结论，再给证据。只输出：

1. 具体问题；
2. 应删除的内容；
3. 正确的信息、动作和空间结构；
4. 应修改的模块、共享组件或数据流；
5. 已验证和未验证项。

禁止使用"提升体验""更现代""更直观"等不能指导实现的描述。

不主动扩展成无障碍专项审计。实现 UI 时继续使用原生交互元素，不破坏项目已有的焦点、键盘、标签和 ARIA 行为；只有用户明确要求或当前改动直接造成任务不可完成时才展开检查。