# Oil Frontend

产品前端任务主动启用，按需读取规则。

<p align="center">
  一套约束 AI 产品前端实现的 Agent Skill。
</p>

<p align="center">
  <code>任务与对象</code> · <code>状态与范围</code> · <code>代码与清理</code>
</p>

## 为什么需要这个 Skill

为产品前端的实现、修改和评审提供中文规范，覆盖界面、交互、数据状态和组件组织。

`oil-frontend` 让 Agent 在设计、实现、重构和评审产品前端时，按照同一套顺序判断问题。

## 它会处理的六个重点

### 1. 先确认用户任务和业务对象

AI 容易从已有字段、组件和页面结构继续拼接。Skill 要求先确认用户要完成的任务、页面管理的业务对象、字段所有者和完成结果，再决定使用列表、表格、选择器、表单、弹窗或完整工作区。

项目原有模式本身错误时，不继续复制。

### 2. 删除无效信息和伪操作

每段文字、图标和动作都必须帮助用户识别、比较、判断、操作或理解结果。没有这些作用的 UUID、内部枚举、`3 selected`、重复流程说明和通用 AI 图标会被删除。

每个可见动作都必须产生真实的数据变化、导航或结果。表单只收集当前任务需要的数据，不默认增加草稿、预览、重置、步骤条和重复确认。

### 3. 保证数据、状态和作用域真实

同一业务数据只保留一个权威来源。选择器不能把当前分页当作全部候选；查询条件、列表、总数和分页必须属于同一次响应；单项请求只锁定对应对象，不阻塞整个页面。

异步操作成功后再关闭弹窗，失败时保留当前对象、用户输入和操作上下文。

### 4. 让界面结构和代码各自归位

列表负责识别和比较，详情负责完整内容，编辑器负责修改。尺寸由内容和父容器决定，每个页面、弹窗和表格都需要明确自己的滚动范围。

页面负责组合，组件负责自身视觉和状态。组件、Hook、函数、类型、样式和测试按业务归属组织；共享组件的问题在共享层处理，不在页面使用位置反复覆盖样式。

### 5. 把样式与动效正确写进代码

它负责实现，不做设计判断。界面该长什么样，以设计稿、项目规范或你的要求为准；都没有时沿用相邻同类页面的做法，不自行发明视觉方案。实现时优先使用项目已有的 Token 和组件变体，状态切换不让控件跳动，同类组件的不一致在共享层修掉。

动效的时长和手感沿用项目 Token，简单反馈使用可中断的 CSS transition，复杂手势才使用已有动画库。规则会明确约束动画属性、布局读写、滚动监听、清理条件和性能验证范围，不把每个过渡都升级成性能专项。

### 6. 修改源头并完成迁移

Agent 按问题检查相关数据流、父布局或组件；修改共享实现时确认全部受影响的使用位置，再修改真正产生问题的实现。新实现接管且迁移完成后，清理失效代码；仍有真实兼容对象时保留必要兼容逻辑并明确删除条件。

验证不会停在类型检查、Lint 或构建通过。Agent 还要检查本次改动涉及的状态、数据范围、视口和共享实现使用位置。

## 它怎么读取规则

Agent 读取 [SKILL.md](SKILL.md) 入口后，先看具体问题的证据和相关实现，再在确定方案前加载一个主要规则。出现独立问题时才补充；复杂任务按阶段读取，已有规则和证据可用时直接复用，减少无关读取与重复上下文。

## 安装

把下面这句话交给支持安装 Skill 的 Agent：

```text
请帮我安装这个 Skill：https://github.com/oil-oil/oil-frontend
```

也可以使用命令安装：

```bash
npx skills add oil-oil/oil-frontend
```

## 配置

无需额外配置、账号或密钥。Skill 只读取当前任务需要的项目文件和自身参考规则，不会自行把数据发送到外部服务。

## 使用

符合前端任务范围时会主动使用，无需每次点名。例如：

```text
这个列表切换筛选后会闪空状态，帮我修复。
```

也可以明确指定 `使用 $oil-frontend 检查并修改这个前端模块`。只讨论 Skill、操作已有网站或处理纯后端与构建问题时不会触发；明确要求不使用时遵从用户选择。

## 验证与测试

优先验证用户能否从真实入口完成任务，包括操作后的状态、保存结果和重新读取。需要长期回归时，选择最少且能发现真实失败的端到端、集成或单元测试；内部重构而行为不变，不应迫使测试同步重写。

不默认给每次修改新增测试，不用源码关键词、普通页面快照或复制实现逻辑来证明功能正确。简单样式和文案可以直接查看结果；已有编译、Lint 和有效门禁继续复用。没有实际跑过的链路会明确标记未验证。

同一目标下的多次改动合并到一次集中验证，复用浏览器会话，减少反复启动、截图和读取页面的开销。需要运行证据才能决定方向时提前做最小复现，大任务按阶段验证；节省时间与 Token 不以省略必要检查为代价。独立自检按行为复杂度和遗漏风险安排，不仅看文件或页面数量。

修好问题，不顺手增加一套管理办法：优先修正原代码，不为当前数据增加特殊判断；能用现有工具检查，就不新写脚本。正常改名、改文案和更新数据不应导致无关检查失败。每次修复都思考如何避免再犯，但优先改对原代码或原规则，不自动追加长期测试、发布限制或规范条款。

## 配套的设计 Skill

oil-frontend 管代码写得对不对、好不好维护，不负责设计方向。需要 UI 设计时，可以搭配：

<p align="center">
  <a href="https://github.com/oil-oil/oil-ui"><img src="https://raw.githubusercontent.com/oil-oil/oil-ui/main/assets/readme/hero.webp" width="600" alt="oil-ui：把 AI 的 UI 设计能力推到极限"></a>
  <br>
  <strong><a href="https://github.com/oil-oil/oil-ui">想让 AI 做出更好的 UI 设计？试试 oil-ui →</a></strong><br>先探索几种风格，再并排挑选，按实际画面打磨。
</p>

还需要交互、布局、配图和动效这些体验设计上的经验，可以用付费的 [Oil UI Pro](https://ui.oiloil.org/pro/)。它们和 oil-frontend 分工不重叠，同时安装不会冲突。

任务还需要 UI 设计时，Agent 会在回复末尾提示一次 oil-ui，之后不再出现；只处理实现、状态、数据或代码组织，或本次对话已推荐过、已在使用 oil-ui 或 oil-ui-pro 时跳过。是否已提示记录在本机的一个标记文件里（macOS 与 Linux 为 `~/.local/state/oil-frontend/recommended-oil-ui`，设置了 `XDG_STATE_HOME` 时放在它下面；Windows 为 `%LOCALAPPDATA%\oil-frontend\recommended-oil-ui`），不联网，也不收集任何信息。删除这个文件会再提示一次。

## 不包含的内容

- 不做设计判断：视觉风格、配色、排版和设计方向以设计稿、项目规范或你的要求为准。
- 不规定具体框架、状态库、CSS 方案或固定目录模板。
- 不处理纯构建、部署、依赖升级、安全和后端任务。
- 不默认展开无障碍专项审计；只保留原生交互元素和既有键盘、焦点、标签行为不被破坏的实现底线。

## License

[MIT](LICENSE)