vechain-kit

VeChain Kit 技能

关键规则

1. 首先阅读参考文件。 当用户请求涉及下方参考表中的任何主题时，先阅读相应文件，再进行其他操作——包括编写代码和做出决定。简要说明你正在阅读哪些文件，以便用户确认技能已启用（例如：“正在阅读 VeChain Kit 参考资料……”）。
2. VeChain 相关主题的信息优先级：（a）此技能中的参考文件——始终是主要信息来源。（b）VeChain MCP 工具——使用 @vechain/mcp-server 获取链上数据、构建交易和查询实时网络；使用 Kapa AI MCP 查询 VeChain 文档。（c）网络搜索——仅作为最后手段，且仅限参考文件未涵盖的主题。
3. **VeChain 任务优先直接在主对话中处理。**计划模式和子 Agent 不会继承技能上下文，可能会退而使用网络搜索，而不是参考文件。
4. **上下文压缩或丢失后，**重新阅读此 SKILL.md，以恢复对参考表和操作流程的了解，然后再继续工作。

范围

此技能专用于 VeChain Kit 和 dapp-kit 软件包：

• VeChain Kit：安装、设置、配置、Privy 集成
• dapp-kit：适用于非 React 或精简设置的轻量级钱包连接
• 钱包连接、社交登录（电子邮件、Google、passkey）、智能账户
• 预构建 UI 组件（WalletButton、TransactionModal）
• Hooks（useWallet、useSendTransaction、useCallClause、代币／域名／预言机 Hooks）
• 主题设置和 Privy 设置
• 使用 react-i18next 实现 i18n：双向语言同步（Kit ↔ 宿主应用）、针对缺失或未使用翻译键的提交前检查／ESLint

通用前端模式（React Query、Turborepo、状态管理、Chakra UI、交易 UX）请参阅 frontend 技能。

默认技术栈

层	默认选项	替代选项
前端	@vechain/vechain-kit	@vechain/dapp-kit-react（轻量级／非 React）
Node	Node 20 LTS（通过 nvm 管理）	--

操作流程

1. 检查 Node 版本

安装依赖或运行任何命令之前：

• 检查项目根目录中是否存在 .nvmrc。如果存在，运行 nvm use。
• 如果 .nvmrc 不存在，则创建该文件并写入 20（Node 20 LTS），然后运行 nvm use。

2. 检测项目结构

• 存在 turbo.json → 遵循 Turborepo 约定（apps/frontend、packages/*）
• 使用 useThor 访问 Thor 客户端（VeChain Kit 和 dapp-kit v2 均适用）。useConnex 已在所有场景中弃用。
• 仅在项目使用 Chakra UI、i18n、Zustand 时应用相应的条件模式

3. 选择合适的库

何时询问用户： 如果项目尚未使用 VeChain Kit 或 dapp-kit，且用户未指定使用哪一个，请先询问再做选择。关键问题：

• 是否需要社交登录（电子邮件、Google、passkey）？→ VeChain Kit
• 是否需要预构建的 UI 弹窗和 Hooks（WalletButton、TransactionModal、代币 Hooks）？→ VeChain Kit
• 是否希望使用依赖最少的轻量级纯钱包集成？→ dapp-kit
• 使用非 React 框架？→ dapp-kit

4. 实现前先澄清

如果用户的请求含糊不清，或有多种解决方式，请先询问，再开始构建。将调研与实现分开。

5. 确保实现符合 VeChain 特定要求

• 网络：始终明确指定（mainnet／testnet／solo）
• 社交登录：自动启用 Generic Delegator（用户使用 VET／VTHO／B3TR 支付 Gas）；可选应用赞助的委托，以改善用户体验；使用智能账户；在调用 sendTransaction 前预先获取数据

6. 验证并交付

只有通过所有适用的检查后，任务才算完成：

1. 代码可编译——无构建错误（npm run build 或等效命令成功）
2. 测试通过——现有测试仍然通过；新增逻辑有测试覆盖
3. 记录风险提示——说明任何与签名、费用或代币转账相关的影响

参考文件

在进行任何操作之前，请先阅读匹配的文件。请参阅上方的关键规则。

主题	文件	用户提及以下内容时阅读……
设置与配置	references/kit-setup.md	安装 VeChain Kit、配置 provider、CSS 框架、Tailwind、环境变量、登录方式、法律文件、生态应用、常见问题
Hooks	references/kit-hooks.md	useWallet、useCallClause、useSendTransaction、useBuildTransaction、useSignMessage、合约读取、交易、VET 域名、NFT、区块链 Hooks、语言/货币、@vechain/contract-getters
组件与模态框	references/kit-components.md	WalletButton、TransactionModal、TransactionToast、模态框 Hooks、隔离视图
社交登录	references/kit-social-login.md	社交登录、智能账户、账户抽象、Privy 设置、社交登录的费用代付、DIY 社交登录
主题	references/kit-theming.md	主题、颜色、字体、按钮、玻璃效果、底部弹出层、Chakra UI 兼容性、webpack 回退方案
dapp-kit	references/frontend-dappkit.md	dapp-kit、DAppKitProvider、轻量级钱包
翻译 + Kit	references/translations-vechain-kit.md	i18n、翻译、语言同步、VeChain Kit 语言、缺失的翻译、提交前检查、ESLint、未使用的键