338 lines
9.4 KiB
Markdown
338 lines
9.4 KiB
Markdown
# 跨链集成AI技能
|
||
|
||
`跨链` `区块链` `AI代理` `SDK` `支付` `DeFi` `Web3`
|
||
|
||
# Trails Agent Skill for Claude Code
|
||
|
||
[](LICENSE)
|
||
[](https://docs.trails.build)
|
||
|
||
这是一个专家级 AI 代理技能，通过智能引导和可运行代码生成，帮助您将 [Trails](https://trails.build) 跨链基础设施集成到您的应用中。
|
||
|
||
> **快速开始**：一条命令完成安装：
|
||
> ```bash
|
||
> npx skills add 0xsequence-demos/trails-skills
|
||
> ```
|
||
> 然后问您的 AI 代理：*"我想在 Next.js 应用中添加跨链支付功能"*
|
||
|
||
---
|
||
|
||
## 什么是 Trails？
|
||
|
||
Trails 可实现跨多条区块链网络的无缝代币转账、兑换和智能合约执行。用户可以用任意支持链上的任意代币进行支付、兑换或充值，Trails 会自动处理路由、跨链桥接和执行，可通过 `npm i 0xtrails` 下载使用。
|
||
|
||
### 核心功能
|
||
|
||
**🔗 跨链操作**
|
||
- 在 10+ 条 EVM 链之间桥接代币（以太坊、Base、Arbitrum、Optimism、Polygon 等）
|
||
- 通过最优流动性路径自动路由
|
||
- 即使复杂的多跳操作也能实现单次交易的用户体验
|
||
|
||
**💱 代币兑换与支付**
|
||
- 接受任意代币支付，以您偏好的代币收款
|
||
- 用户选择输入代币，您指定输出代币（或反之亦然）
|
||
- 实时定价并带有滑点保护
|
||
|
||
**🎯 智能合约执行**
|
||
- 跨链桥接后在目标链上执行合约调用
|
||
- 完美适配 DeFi 存款、NFT 铸造、金库质押等场景
|
||
- 支持动态调用数据的自动占位金额
|
||
|
||
**⚡ 开发者体验**
|
||
- 即插即用的 Widget 组件，快速集成（不到 10 行代码）
|
||
- 无界面 Hooks，提供完全自定义 UX 的全控制权
|
||
- REST API 用于服务端自动化和后端
|
||
- 内置 wagmi 支持与 Web3 钱包集成
|
||
|
||
---
|
||
|
||
## 集成方式
|
||
|
||
Trails 提供三种集成方案：
|
||
|
||
### 🎨 Widget（即插即用 UI）
|
||
**适用场景：** 希望快速获得跨链功能的 React/Next.js 应用
|
||
|
||
预构建的可主题化 UI 组件：
|
||
- **Pay 模式** — 接受精确金额支付（EXACT_OUTPUT）
|
||
- **Swap 模式** — 代币交易界面
|
||
- **Fund 模式** — 可选合约执行的充值流程（EXACT_INPUT）
|
||
- **Earn 模式** — 带收益优化的 DeFi 协议存款
|
||
|
||
```tsx
|
||
<TrailsWidget
|
||
mode="pay"
|
||
destinationChainId={8453}
|
||
destinationTokenAddress="0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
|
||
destinationAmount="10000000" // 10 USDC
|
||
/>
|
||
```
|
||
|
||
### 🎛️ 无界面 SDK（自定义 UX）
|
||
**适用场景：** 已有 UI/UX、需要程序化控制的 React 应用
|
||
|
||
用于自定义实现的 React Hooks：
|
||
- 带自定义 UI 的交易执行
|
||
- 代币/链的发现与筛选
|
||
- 交易历史记录与状态追踪
|
||
|
||
```tsx
|
||
const { useQuote } = useQuote();
|
||
const { supportedTokens: tokens } = useSupportedTokens();
|
||
```
|
||
|
||
### 🔌 直接 API（服务端）
|
||
**适用场景：** 后端服务、自动化、非 React 应用、AI 代理
|
||
|
||
用于服务端集成的 REST API：
|
||
- **SDK 客户端**，适用于 Node.js/TypeScript 项目
|
||
- **原始 HTTP/Fetch**，适用于 AI 代理、Python、Go 或任意语言
|
||
- 报价生成与意图执行
|
||
- 交易监控与收据
|
||
|
||
```typescript
|
||
// SDK 客户端（Node.js）
|
||
const quote = await trails.quoteIntent({ ... });
|
||
const intent = await trails.commitIntent({ quoteId });
|
||
const receipt = await trails.executeIntent({ intentId });
|
||
|
||
// 或原始 Fetch（通用）
|
||
const quote = await fetch('https://api.trails.build/quote', {
|
||
method: 'POST',
|
||
headers: { 'Authorization': `Bearer ${apiKey}` },
|
||
body: JSON.stringify({ ...params })
|
||
});
|
||
```
|
||
|
||
---
|
||
|
||
## 此技能的功能
|
||
|
||
安装后，Trails 技能将成为您的 AI 集成助手，它能：
|
||
|
||
✅ **检测您的技术栈** — 扫描 React、Next.js、wagmi、viem
|
||
✅ **推荐最佳方案** — Widget、无界面 SDK 或直接 API
|
||
✅ **生成可运行代码** — Provider 配置、集成代码片段、环境变量配置
|
||
✅ **引导高级功能** — 调用数据编码、代币发现、错误处理
|
||
✅ **排查问题** — Provider 层级、弹窗渲染、交易调试
|
||
|
||
### 触发关键词
|
||
|
||
当您提到以下内容时，技能会自动激活：
|
||
- **Trails 相关**："trails"、"integrate trails"、"cross-chain"
|
||
- **操作相关**："bridge tokens"、"swap"、"payments"、"pay widget"
|
||
- **模式相关**："fund mode"、"earn mode"、"swap widget"
|
||
- **概念相关**："intents"、"chain abstraction"、"unified liquidity"
|
||
- **用例相关**："accept any token"、"cross-chain payments"、"bridge and execute"
|
||
|
||
---
|
||
|
||
## 安装
|
||
|
||
### 通用安装（推荐）
|
||
|
||
使用通用 [Skills CLI](https://skills.sh/) 安装：
|
||
|
||
```bash
|
||
npx skills add 0xsequence-demos/trails-skills
|
||
```
|
||
|
||
支持以下工具：
|
||
- OpenClaw
|
||
- Claude Code
|
||
- Cursor
|
||
- Cline
|
||
- Windsurf
|
||
- 以及其他 AI 编码代理
|
||
|
||
然后**重启您的 AI 代理**，并尝试询问：
|
||
|
||
```
|
||
我想将 Trails 集成到我的 Next.js 应用中
|
||
```
|
||
|
||
### Claude Code（原生）
|
||
|
||
也可以在 Claude Code 中执行：
|
||
|
||
```
|
||
/plugin marketplace add 0xsequence-demos/trails-skills
|
||
/plugin install trails@0xsequence-demos/trails-skills
|
||
```
|
||
|
||
然后**完全重启 Claude Code**。
|
||
|
||
### 验证安装
|
||
|
||
当您提到以下词语时，技能应自动激活：
|
||
- "trails"、"cross-chain"、"bridge"、"swap"
|
||
- "accept any token"、"cross-chain payments"
|
||
- "pay widget"、"fund mode"、"earn mode"
|
||
|
||
---
|
||
|
||
## 使用场景
|
||
|
||
### 跨链支付
|
||
让客户用任意代币支付，而您收到所需的精确金额：
|
||
- 电商结账
|
||
- 订阅付款
|
||
- 商家结算
|
||
|
||
### DeFi 协议充值
|
||
无需复杂桥接，允许用户从任意链存款：
|
||
- 带自动转换的金库存款
|
||
- 跨链入口的质押
|
||
- 来自任意来源的流动性提供
|
||
|
||
### 代币兑换与交易
|
||
提供具有跨链流动性的兑换功能：
|
||
- 跨链 DEX 聚合
|
||
- 投资组合再平衡
|
||
- 代币迁移流程
|
||
|
||
### 智能合约执行
|
||
在单一流程中完成桥接与执行：
|
||
- 用任意代币支付的 NFT 铸造
|
||
- 跨链参与的 DAO 投票
|
||
- 多链协议交互
|
||
|
||
---
|
||
|
||
## 快速示例
|
||
|
||
### Widget：Pay 模式
|
||
|
||
```tsx
|
||
import { TrailsWidget } from '@0xtrails/trails';
|
||
|
||
<TrailsWidget
|
||
mode="pay"
|
||
destinationChainId={8453}
|
||
destinationTokenAddress="0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
|
||
destinationAmount="10000000" // 10 USDC（6 位小数）
|
||
destinationRecipient="0xYourMerchantAddress"
|
||
/>
|
||
```
|
||
|
||
### 无界面 SDK：自定义兑换
|
||
|
||
```tsx
|
||
import { useQuote } from '@0xtrails/trails';
|
||
|
||
function SwapButton() {
|
||
const { quote, isPending, isSuccess } = useQuote({
|
||
destinationChainId: 8453,
|
||
destinationTokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
|
||
destinationAmount: '1000000',
|
||
});
|
||
|
||
return (
|
||
<div>
|
||
<button disabled={isPending || isSuccess}>
|
||
{isPending ? '处理中...' : isSuccess ? '已完成！' : '兑换'}
|
||
</button>
|
||
{isSuccess && <p>兑换成功！</p>}
|
||
</div>
|
||
);
|
||
}
|
||
```
|
||
|
||
### 直接 API：后端结算
|
||
|
||
```typescript
|
||
import { TrailsAPI } from '@0xtrails/trails-api';
|
||
|
||
const trails = new TrailsAPI({ apiKey: process.env.TRAILS_API_KEY });
|
||
|
||
const quote = await trails.quoteIntent({
|
||
sourceChainId: 1,
|
||
destinationChainId: 8453,
|
||
amount: '1000000000',
|
||
tradeType: 'EXACT_INPUT',
|
||
});
|
||
|
||
const intent = await trails.commitIntent({ quoteId: quote.quoteId });
|
||
const receipt = await trails.executeIntent({ intentId: intent.intentId });
|
||
```
|
||
|
||
---
|
||
|
||
## 获取 Trails API Key
|
||
|
||
**集成 Trails 前，您需要先获取 API Key。** 如果您还没有，技能会提示您去获取。
|
||
|
||
### 获取 Key
|
||
|
||
1. 访问 **[https://dashboard.trails.build](https://dashboard.trails.build)**
|
||
2. 创建账号（或已有账号则登录）
|
||
3. 进入 API Keys 页面
|
||
4. 生成新的 API Key
|
||
5. 复制您的 Key
|
||
|
||
### 添加到项目
|
||
|
||
创建或更新您的 `.env` 文件：
|
||
|
||
```bash
|
||
# 用于 React/Next.js（客户端）
|
||
NEXT_PUBLIC_TRAILS_API_KEY=your_api_key_here
|
||
|
||
# 用于服务端（直接 API）
|
||
TRAILS_API_KEY=your_api_key_here
|
||
```
|
||
|
||
**技能会自动检查此配置并引导您完成设置！**
|
||
|
||
---
|
||
|
||
## 支持的网络
|
||
|
||
- 完整列表请查看 [docs.trails.build](https://docs.trails.build)
|
||
|
||
---
|
||
|
||
## 文档与支持
|
||
|
||
### 官方文档
|
||
- **Trails 文档**：[docs.trails.build](https://docs.trails.build)
|
||
- **API 参考**：见技能内嵌文档
|
||
- **控制台**：[dashboard.trails.build](https://dashboard.trails.build)（获取 API Key）
|
||
|
||
### 常见问题
|
||
|
||
**Q：我应该使用哪种集成方式？**
|
||
A：直接问技能就好！说"我想集成 trails"，它会根据您的技术栈推荐最佳方案。
|
||
|
||
**Q：不用 React 也能使用 Trails 吗？**
|
||
A：可以！对于 Node.js、Python、Go 或任意支持 HTTP 的语言，请使用直接 API。
|
||
|
||
### 故障排查
|
||
|
||
如果技能未能激活：
|
||
|
||
1. **验证安装**：检查 `.claude/skills/trails/` 目录是否存在且包含 `SKILL.md`
|
||
2. **重启 Claude Code**：完全退出并重新打开（不只是重新加载）
|
||
3. **使用明确触发词**：尝试"使用 trails 技能，帮我集成跨链支付"
|
||
4. **查看 Claude Code 日志**：查找与技能加载相关的错误信息
|
||
|
||
---
|
||
|
||
## 关于 Trails
|
||
|
||
[Trails](https://trails.build) 是跨链基础设施，让代币转账、兑换和智能合约执行像单链交易一样简单——专为支付、稳定币和跨链编排而构建。
|
||
|
||
由 [0xtrails](https://twitter.com/0xtrails) 打造，旨在消除跨链交互的复杂性。
|
||
|
||
---
|
||
|
||
## 许可证
|
||
|
||
MIT © 0xtrails
|
||
|
||
---
|
||
|
||
## 贡献
|
||
|
||
此技能为开源项目。如需贡献或报告问题，请访问：
|
||
[github.com/0xsequence-demos/trails-skills](https://github.com/0xsequence-demos/trails-skills) |