# 跨链集成AI技能

`跨链` `区块链` `AI代理` `SDK` `支付` `DeFi` `Web3`

# Trails Agent Skill for Claude Code

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)
[![Trails Docs](https://img.shields.io/badge/docs-trails.build-purple?style=flat-square)](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)