技能使用指南

frontend-ux（以太坊dApp前端UX开发规则）Skill 是什么？如何安装？

frontend-ux 技能把以太坊 dApp 前端最容易踩的坑固化成 7 条强制规则：链上按钮加载与禁用、代币批准四状态流程、Address 地址组件、美元价值显示、RPC 配置与发布前检查清单，专治 AI 代理生成的「能跑但不好用」代码。本文详解安装验证思路、使用方法、竞品对比与真实场景体验，帮你用 AI 快速写出可信赖的 dApp 前端。

以太坊dApp前端UX开发规则Skillfrontend-ux
8 个章节 约 18 分钟阅读 AI 智能生成

以太坊dApp前端UX开发规则Skill：让 AI 代理不再写出「按钮不会禁用」的链上交互

  • 一个专治 AI 代理 UI 通病的规则集：这个技能把以太坊去中心化应用（dApp）前端最容易踩的坑浓缩成 7 条强制规则，覆盖链上按钮状态、代币批准流程、地址显示、美元价值、RPC 配置和发布前元数据。
  • 直击最高频错误：AI 生成的钱包交互按钮往往“钱包一签名就恢复可点击”，导致用户重复点击、发送重复交易；该技能要求按钮从点击到链上确认全程禁用并显示加载指示器。
  • 有明确的技术栈偏好但不止于此：围绕 Scaffold-ETH 2（下称 SE2）构建，核心模式同样适用于任何以太坊前端，例如“批准 → 操作”的四状态流程、<Address/> 与 <AddressInput/> 的使用规范。
  • 可直接变成检查清单：技能内置发布前检查清单与 externalContracts.ts 预注册要求，能在部署前把品牌残留、公共 RPC 限速、合约地址错配等问题一次性拦住。
  • 适合人群：用 AI 代理（Cursor、Claude 等）快速搭建 dApp 的前端开发者、Web3 独立开发者、黑客松参赛者，以及需要给团队统一 dApp 交互规范的技术负责人。

1. 该技能叫什么？如何下载安装 AI 技能提升开发效率？

基本信息

项目 内容
中文名 以太坊dApp前端UX开发规则Skill
英文名 frontend-ux
技能 ID 13697
定位 以太坊去中心化应用前端用户体验的强制规则集合
技术基座 Scaffold-ETH 2（模式适用于任何以太坊前端）

它解决什么问题

当你让 AI 代理写一个 dApp 前端时，代理通常会回答“按钮工作”——它能调用合约、能弹出钱包、交易能上链。但在真实用户体验层面，问题一大堆：

  • 用户点了“批准”，在钱包里签名，回到页面发现按钮又亮了，于是再点一次，结果两笔批准同时挂起；
  • 原始的 wagmi writeContractAsync 在钱包签名后立刻返回，前端误以为交易已完成，实际上还在内存池里排队；
  • 地址以原始十六进制 0x1234...5678 展示，没有 ENS、没有区块头像、没有复制按钮、没有区块浏览器跳转；
  • 金额只显示“1,000 TOKEN”，用户完全不知道这值多少钱；
  • 页面顶部先有一个显示应用名的 Header，下面又来一个一模一样的 <h1> 标题；
  • 生产环境仍然命中公共 RPC，被限速后出现随机失败；
  • 上线时 Open Graph 图片还是 localhost，页脚还挂着 Scaffold-ETH 2 的默认品牌。

这个技能就是把这些“AI 每次都跳过的细节”变成不可协商的规则，让 AI 代理在生成代码时直接按规范产出。

一键安装的思路与步骤

AI 技能的安装方式取决于你使用的 AI 客户端或技能市场，具体命令、入口与账号要求请以官方说明为准。通用的安装思路如下：

  1. 确认前提：你已经在使用支持“技能/插件”机制的 AI 开发工具（例如带技能库的编程助手或 IDE 插件），并且具备可调用本地文件系统或项目上下文的权限。
  2. 定位技能：在技能市场或技能库中，用英文名 frontend-ux 或技能 ID 13697 检索；也可以直接用中文名“以太坊dApp前端UX开发规则”搜索。
  3. 执行安装：按平台提供的安装入口（一键安装按钮或安装命令）添加技能，具体命令以官方说明为准；安装后确认技能状态为“已启用”。
  4. 验证是否生效：在对话中提出一个典型的 dApp 前端需求，例如“帮我写一个代币质押页面的批准按钮”。如果技能已生效，AI 的输出应主动包含独立的加载状态、禁用逻辑、批准额度读取和错误反馈，而不是一个裸 <button>。
  5. 项目内固化：把技能输出的规则同步进项目的 AI 规则文件（如规则说明文档），让团队后续所有 AI 生成代码都遵循同一套标准。

2. 该技能的主要功能和特点

  • 规则 1：每个链上按钮必须有加载器 + 禁用状态。点击后立即禁用、显示“批准中…/质押中…”等文案、保持禁用直到链上确认、完成后给出成功或错误反馈。技能特别强调：永远不要多个按钮共享一个 isLoading，每个按钮独立维护加载状态。
  • 强制使用 Scaffold 钩子而非原始 wagmi。useScaffoldWriteContract 内部通过 useTransactor 等待区块确认，而原始 writeContractAsync 在用户点击 MetaMask 确认后立即返回。这一条直接决定了前端“成功提示”是不是假成功。
  • 规则 2：四状态交互流程。未连接 → 错误网络 → 批准额度不足 → 可执行操作，一次只显示一个明显的大按钮。禁止用“请连接钱包以继续”这类文字提示替代按钮，并且网络检查必须排在最前面。
  • 规则 3：地址显示与输入的统一组件。展示用 <Address/>（内置 ENS 解析、区块头像、复制、截断、区块浏览器链接），输入用 <AddressInput/>（内置 ENS 解析、头像预览、校验、粘贴处理）。同时要求在主页面底部展示已部署合约地址，方便用户去区块浏览器核验。
  • 规则 4：处处显示美元价值。任何代币或 ETH 金额都要带美元估值，任何金额输入都要有实时美元预览；ETH 价格可用 SE2 内置的 useNativeCurrencyPrice()，自定义代币可用 DexScreener API、链上 Uniswap 报价或 Chainlink 预言机。
  • 规则 5：禁止重复标题。SE2 的 Header 已经展示应用名，页面主体不要再放同名 <h1>。
  • 规则 6：RPC 配置规范。禁止使用公共 RPC，需在 scaffold.config.ts 中设置 rpcOverrides 与 pollingInterval: 3000，API 密钥放在 .env.local；并特别提醒从 services/web3/wagmiConfig.tsx 的后备传输数组中移除裸 http()，否则 viem 的 fallback() 仍会并行命中公共 RPC 并触发 429 限速。
  • 规则 7：发布前检查清单。包含 Open Graph / Twitter 卡片的绝对生产域名图片、移除全部 SE2 默认品牌（README、页脚、网站图标、标签标题）、合约地址与部署一致、无硬编码测试网值等十多项。
  • externalContracts.ts 前置注册：所有外部合约（代币、协议）必须在构建前端前登记到 externalContracts.ts，否则 Scaffold 钩子会静默失败；deployedContracts.ts 由 yarn deploy 自动生成，禁止手改。
  • 人类可读金额转换：统一用 formatEther / formatUnits / parseEther / parseUnits 在合约单位与显示单位之间转换，绝不把 wei 直接丢给用户看。

和普通工具比强在哪：普通代码生成工具只保证“能跑”，这个技能保证“能用、不容易出错、上线不丢人”。它把 Web3 前端里那些只能靠经验积累的隐性知识，变成了 AI 可以直接执行的显式约束。

3. 如何使用该技能？

步骤 1：明确任务上下文

在向 AI 提出需求时，说明技术栈与目标链，例如“使用 Scaffold-ETH 2 在 Base 链上做一个代币质押页面”。技能围绕 SE2 构建，明确技术栈能让规则命中率更高。

步骤 2：让技能参与生成，而不是事后补救

推荐在写第一个组件前就调用技能，而不是等页面写完再让它审查。示例提示词：

请按照 frontend-ux 技能的规则，帮我实现一个“批准 USDC 并质押”的组件。要求：批准额度用 useScaffoldReadContract 读取；批准与质押分别使用 useScaffoldWriteContract；两个按钮各自独立加载状态；未连接钱包时显示大号连接按钮；网络错误时显示切换到 Base 的按钮。

步骤 3：检查输出是否符合规则

拿到代码后，按技能给的模式逐条核对：

  • 按钮是否有 disabled={isApproving} 且文案在加载态切换为“批准中…”？
  • 是否读取了 allowance，而不是用本地 state 跟踪批准额度？
  • 网络检查是否在批准判断之前？
  • 地址展示是否用了 <Address/>，输入是否用了 <AddressInput/>？
  • 金额旁边是否有美元估值？

步骤 4：补充外部合约登记

在写前端代码之前，先把外部合约写入 packages/nextjs/contracts/externalContracts.ts，包含链 ID、地址和 ABI。示例：

export default {
  8453: {
    USDC: {
      address: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      abi: [ /* ERC-20 ABI */ ],
    },
  },
} as const;

步骤 5：配置 RPC 与轮询间隔

在 scaffold.config.ts 中设置 rpcOverrides 与 pollingInterval: 3000，密钥写入 .env.local，并从 wagmiConfig.tsx 的后备数组中移除裸 http()。

步骤 6：跑一遍发布前清单

部署前逐项勾选技能提供的检查清单：Open Graph 图片是否为绝对生产域名 URL、Twitter 卡片类型是否为 summary_large_image、页脚与 README 是否已清理 SE2 品牌、标签标题是否为你的应用名、合约地址是否与部署一致。

输出说明：技能本身不产出可运行的服务，它的产出是“符合规范的代码 + 一份可执行的检查清单”。你拿到的是被规则约束过的实现，而不是需要反复返工的半成品。

4. 同类型竞品对比分析

方案名称 定位 核心功能 安装/使用门槛 适用场景 优势与不足
frontend-ux（本技能） 面向 AI 代理的 dApp 前端 UX 强制规则集 7 条硬规则 + 发布前检查清单 + 外部合约预注册 + 人类可读金额转换 低，安装后在对话中调用即可；具体入口以官方说明为准 用 AI 快速搭建以太坊 dApp 前端、黑客松、独立开发 优势：直接约束 AI 输出，覆盖真实高频错误，规则可复用为团队规范。不足：深度绑定 Scaffold-ETH 2 生态，非 SE2 项目需自行迁移部分规则
Scaffold-ETH 2 官方文档与 UI 组件库 官方文档 + 现成组件 组件用法、钩子说明、示例代码 中，需要主动阅读并自行总结成规范 学习 SE2 用法、查阅组件 API 优势：权威、全面、随版本更新。不足：是“参考资料”而非“执行约束”，AI 代理不会自动遵守，需要人反复提醒
通用 AI 编程助手（默认模式） 通用代码生成 根据自然语言生成组件与逻辑 低，开箱即用 一般业务前端、原型开发 优势：灵活、速度快。不足：缺少 Web3 领域知识，默认产出常常“能跑但不好用”，按钮状态、批准流程、RPC 配置全靠用户自己把关
自定义 ESLint 规则 + 人工代码评审清单 工程侧静态检查与流程约束 代码风格检查、评审规范 高，需要团队自己编写与维护规则 中大型团队的质量门禁 优势：可自动化、可强制。不足：难以覆盖“用户拒绝签名后是否显示错误”这类交互逻辑，且建设成本高、迭代慢

选择建议：如果你正在用 AI 代理写 dApp，本技能是投入产出比最高的选择——它补的正是通用助手最缺的那块领域经验；如果你不用 AI 写代码，官方文档 + 组件库 + 自建评审清单更合适。

5. 该技能的典型应用场景与实际体验情况

场景一：黑客松限时开发

角色：独立开发者或 2-3 人小队，48 小时内要交出可演示的 dApp。

痛点：时间紧，AI 生成的页面“看起来能跑”，但演示时评委点了两次批准按钮，链上出现两笔待处理交易，现场比较尴尬。

使用方式：在生成任何钱包交互组件前先调用技能，把四状态流程和独立加载状态写进第一个版本。

实际体验：上手难度很低，只要把技能给出的按钮模板当作基线，几乎不会再出现重复提交。需要注意的是，黑客松常切换测试网，记得把 rpcOverrides 与链 ID 一起改，否则会命中公共 RPC 出现偶发失败。

场景二：Web2 前端转型 Web3

角色：熟悉 React 但不熟悉链上交互的前端工程师。

痛点：不知道 writeContractAsync 和 useScaffoldWriteContract 的语义差别，误以为签名成功就是交易成功，导致“成功提示”其实是假成功。

使用方式：把技能当作 Web3 交互入门手册，重点看规则 1、规则 2 和“人类可读金额”部分。

实际体验：规则里对“签名返回 vs 区块确认”的解释非常具体，能快速建立正确心智模型。注意 <Address/>、<AddressInput/> 是 SE2 生态组件，非 SE2 项目要自行实现等价能力。

场景三：团队统一 AI 生成代码质量

角色：技术负责人，团队多人使用 AI 辅助开发。

痛点：每个人生成的前端风格不一，有人用原始 wagmi，有人用 Scaffold 钩子，代码评审时反复争论同一类问题。

使用方式：把技能输出整理成团队 AI 规则文件，并直接把发布前检查清单变成 PR 模板。

实际体验：评审效率明显提升，因为争议点从“应不应该”变成了“清单勾没勾”。注意清单里“移除 SE2 默认品牌”这类项容易被忽略，建议在 CI 或发布流程里显式列出。

场景四：dApp 上线前的最后一道关

角色：准备把项目从测试网推向生产环境的开发者。

痛点：Open Graph 图片还是 localhost、页脚还挂着模板品牌、标签标题还写着 Scaffold-ETH 2，分享到社交平台时缩略图空白。

使用方式：按规则 7 的检查清单逐项过一遍，重点是 Open Graph 图片必须是可访问的绝对生产域名 URL。

实际体验：这类问题一旦上线就很难补救（社交平台有缓存），清单化的检查能显著降低返工成本。建议在部署前把清单打印成一张纸逐个打勾。

6. 该技能能为用户带来的价值

把隐性经验变成显性约束：链上按钮的状态管理、批准流程的先后顺序、RPC 的后备陷阱，这些知识过去需要踩坑才能掌握。技能把它们固化成 AI 可以直接执行的规则，相当于给 AI 代理装上了一位有经验的 Web3 前端评审。

显著减少返工：重复交易、假成功提示、地址显示不规范这类问题，一旦进入测试甚至生产阶段，修复成本远高于生成时避开。规则在生成阶段就生效，属于“一次写对”的收益。

降低 Web3 前端门槛：不熟悉链上交互的开发者，可以借助规则快速建立起正确的实现范式，把注意力放在业务逻辑而不是基础设施细节上。

提升用户信任感：地址带 ENS 与区块头像、金额带美元估值、页面底部展示合约地址并可直接跳区块浏览器——这些细节累积起来，就是用户愿意连接钱包的理由。

长期价值：这套规则与具体项目解耦，可以作为团队长期沿用的 dApp 前端规范；随着 SE2 生态演进，规则中的模式（四状态流程、独立加载状态、金额转换）在非 SE2 项目中同样适用。

7. 常见问题 FAQ

Q1：这个技能怎么安装？需要付费吗？

A：安装入口与命令取决于你使用的 AI 客户端或技能市场，具体方式与是否收费请以官方说明为准。通用做法是在技能市场中用英文名 frontend-ux 或技能 ID 13697 检索后一键添加，然后通过一个“写个批准按钮”的小任务验证是否生效。

Q2：不用 Scaffold-ETH 2，还能用这个技能吗？

A：可以用，但需要做迁移。技能本身围绕 SE2 构建，<Address/>、<AddressInput/>、useScaffoldWriteContract 都是 SE2 生态的具体实现。不过核心模式——按钮从点击到链上确认全程禁用、四状态交互流程、金额带美元估值、RPC 不用公共节点、发布前元数据检查——在任何以太坊前端里都成立，替换成等价的组件与钩子即可。

Q3：技能会直接生成完整页面吗？

A：不会。它是一套规则与检查清单，作用是约束 AI 生成代码的过程与结果。你仍然需要描述业务需求，技能负责让输出符合 dApp 前端的可用性标准。把它理解为“给 AI 的代码评审意见前置到生成阶段”更准确。

Q4：为什么技能反复强调不要用原始 wagmi 的 writeContractAsync？

A：因为它在用户在钱包中点击确认后立即返回，此时交易还在内存池中、尚未上链。如果前端据此把按钮恢复为可点击并提示成功，用户会重复操作，产生重复交易。SE2 的 useScaffoldWriteContract 内部通过 useTransactor 等待区块确认，语义才是正确的。

Q5：和直接用官方文档、或者用通用 AI 助手相比怎么选？

A：官方文档适合系统学习，但它是参考资料，AI 不会自动遵守；通用 AI 助手灵活但缺 Web3 领域知识，容易产出“能跑不好用”的代码。如果你是“用 AI 写 dApp 前端”的工作流，优先选本技能；如果你不用 AI 写代码，官方文档加自建评审清单更划算。