用途
Wagmi v3 技能用于在 React/Next.js 应用中集成 EVM 链钱包，并完成智能合约的读写交互。它聚焦于前端层面的钱包连接、合约调用与交易状态管理，适合需要与 EVM 链交互的 Web 前端项目。
主要能力
- 使用 Wagmi v3.x 钩子管理钱包状态，包括 useAccount、useWriteContract、useReadContract、useWaitForTransactionReceipt、useSimulateContract。
- 使用 viem v2 进行地址校验（getAddress）和交易工具处理（parseEther、parseGwei）。
- 创建自定义钩子，封装针对具体合约的交互逻辑。
- 显式处理连接状态：disconnected、connecting、connected、reconnecting。
- 在写入前模拟合约调用，以校验并估算 gas。
- 使用带 enabled 标志的条件查询，避免不必要的请求。
- 通过 cookie 存储处理 SSR，保持钱包状态持久化。
- 使用来自 OpenAPI 规范的生成合约 ABI 与类型。
- 借助 TanStack Query（通过 wagmi）缓存和重新获取合约数据。
使用方式
该技能要求使用 Wagmi v3.x（不兼容 v1 或 v2 的写法）。地址必须通过 viem 的 getAddress() 校验，不能直接将字符串断言为 Address。在 Next.js 中需正确处理 SSR，钱包组件应使用 dynamic 并设置 ssr: false。建议为合约交互创建自定义钩子，写入前先模拟合约，使用条件查询与 cookie 存储，并显式处理所有连接状态。应避免不必要地包装 OpenAPI 客户端生成的钩子、在组件中暴露私钥或敏感钱包数据，以及跳过地址校验。
适用场景
适用于 React/Next.js 前端连接 EVM 钱包、读取或写入智能合约、处理交易状态与错误等场景。该技能与 fastify 的 API 开发互补，并使用来自 OpenAPI 规范的生成合约 ABI 与类型。
限制
该技能不覆盖 Solana 前端开发、后端 RPC 交互和智能合约开发。其假设环境为 Wagmi v3.3.2+、viem v2.44.4、React 18+ 或 Next.js 14+、TypeScript v5+ 严格模式、TanStack Query v5+（wagmi 的 peer 依赖），以及可选的 WalletConnect v2+（用于 WalletConnect 连接器）。更多模式与代码示例见 PATTERNS.md。