# AI 驱动的链上 V3 LP 自动调仓策略

## 策略简介

集中流动性（Concentrated Liquidity）是 Uniswap V3 引入的核心机制——LP 将资金集中在一个价格范围内做市，相比全范围 LP 可获得数十倍的资本效率和手续费收入。但代价是：价格一旦超出范围，LP 立即停止赚取手续费，且面临更大的无常损失。

本策略的核心思路：**用波动率决定范围宽度**。低波动率时收紧范围、提高资本效率；高波动率时放宽范围、减少调仓和无常损失。同时结合趋势分析进行不对称调整——看涨时向上延伸范围，看跌时向下延伸范围，始终让流动性跟随市场方向。

与传统的固定范围 LP 管理不同，本策略深度融合了 **AI Agent** 和 **OKX OnchainOS**，实现了从市场分析、范围计算、链上调仓到迭代优化的全流程自动化。

---

## 核心架构

```
┌─────────────────────────────────────────────────────────┐
│                    AI Agent (Claude)                     │
│  策略设计 → 回测验证 → 参数调优 → 复盘迭代              │
└──────────────────────┬──────────────────────────────────┘
                       │ 生成 / 优化
┌──────────────────────▼──────────────────────────────────┐
│               策略脚本 (Python)                          │
│  价格采集 → 波动率分析 → 范围计算 → 调仓决策 → 执行     │
└──────────────────────┬──────────────────────────────────┘
                       │ 调用
┌──────────────────────▼──────────────────────────────────┐
│              OnchainOS (onchainos CLI)                   │
│  行情报价 · K线ATR · 钱包余额 · LP头寸 · DeFi操作      │
│  TEE签名 · DEX路由 · 手续费领取 · 流动性管理            │
└──────────────────────┬──────────────────────────────────┘
                       │ 上链
┌──────────────────────▼──────────────────────────────────┐
│                  Base L2 链上执行                         │
│       Uniswap V3 池 → LP NFT 头寸管理 → 手续费收入      │
└─────────────────────────────────────────────────────────┘
```

---

## 功能特性

### 范围引擎（Range Engine）

- **波动率自适应范围（Volatility-Adaptive Range）** — 基于 1H K 线 ATR 动态计算范围宽度。低波动率（<1.5%）时收紧到 2×ATR（资本效率 ~20×），高波动率（3-5%）时放宽到 5×ATR（减少调仓），极端波动（>5%）时拉宽到 8×ATR（安全优先）
- **趋势不对称调整（Trend Asymmetry）** — 复用网格策略的多时间框架（MTF）趋势分析。看涨时上方放宽、下方收紧，跟随上涨空间；看跌时下方放宽、上方收紧，防御下跌风险
- **多时间框架分析（MTF）** — 25 分钟短期 EMA + 1 小时中期 EMA + 4 小时长期 EMA + 8 小时结构检测，判断趋势方向与强度

### 智能调仓触发

不是每个 tick 都调仓——只有满足触发条件且通过防过度调仓检查时才执行：

- **出范围（Out of Range）** — 价格超出 LP 范围，零收益状态，必须调仓
- **波动率突变（Volatility Shift）** — ATR 变化超过 30%，当前范围不再最优
- **时间衰减（Time Decay）** — 持仓超 24 小时，基于过时数据的范围需要刷新

### 防过度调仓（Anti-Churn）

每次调仓涉及 4 步链上操作（claim → remove → swap → deposit），成本不低。防过度调仓机制确保调仓的收益大于成本：

- **最小持仓时间** — 头寸至少持有 2 小时（出范围除外）
- **日频率限制** — 每日最多 6 次调仓
- **Gas 成本检查** — Gas 超过预期手续费的 50% 时跳过
- **最小范围变化** — 新范围与旧范围差异不足 5% 时跳过

### 风控体系

- **止损（Stop Loss）** — 组合价值跌幅达 15% 自动停止
- **追踪止损（Trailing Stop）** — 从峰值回落 10% 触发保护
- **无常损失容忍度（IL Tolerance）** — 无常损失超过 5% 硬停
- **熔断机制（Circuit Breaker）** — 连续 5 次执行失败后进入 1 小时冷却
- **紧急回退部署（Emergency Fallback）** — 调仓中途失败（如 remove 后 deposit 失败），以 3× 正常宽度紧急部署，确保资金不裸露

### 运维与监控

- **Discord 实时通知** — 调仓成功（绿色）、无操作（灰色）、错误/停止（红色）
- **每日报告** — 自动生成中文日报，统计手续费收入、Gas 消耗、无常损失、净收益率
- **结构化 JSON 输出** — 每次 tick 输出机器可读的分析数据，供 AI Agent 解析和复盘

---

## 与网格交易的区别

两个策略都是链上自动交易，但核心逻辑和收益来源完全不同：

| 维度 | 网格交易 | V3 LP 调仓 |
|------|---------|-----------|
| **收益来源** | 网格价差（低买高卖） | LP 手续费（为交易者做市） |
| **持仓形式** | ETH + USDC 代币余额 | LP NFT 头寸（锁定在价格范围内） |
| **链上操作** | 单步 swap | 四步流水线：claim → remove → swap → deposit |
| **核心参数** | 网格间距、层数 | 范围宽度、tick 间距 |
| **波动率响应** | 调整网格宽度和步距 | 调整范围宽度 + 是否触发调仓 |
| **主要风险** | 单边行情踏空 | 无常损失（IL） |
| **Gas 敏感度** | 低（单次 swap） | 高（多步操作） |
| **交易频率** | 每 tick 可能触发 | 仅在触发条件满足时调仓 |
| **收益模式** | 主动交易赚差价 | 被动做市赚手续费 |

简单说：**网格是主动交易者，LP 调仓是智能做市商**。

---

## 与 AI 的结合

### 1. AI 生成策略代码

整套策略脚本由 AI Agent 设计和编写。通过 **策略工厂（Strategy Factory）** 流水线，5 个专家 Agent 协作完成：

```
Lead Agent（协调）
  → Strategy Agent：设计范围算法、编写 Python 脚本
  → Backtest Agent：拉取历史数据、验证参数有效性
  → Infra Agent：本地验证 → VPS 部署
  → Publish Agent：打包为独立 Skill 发布
  → Iteration Agent：分析实盘数据、提出优化方案
```

策略工厂的核心规则：每步有质量门禁（Gate），必须通过才能进入下一步；Lead 只协调不写代码；迭代优化必须用户确认，绝不自动执行。

### 2. AI 驱动版本迭代

波动率自适应算法的参数（ATR 乘数、趋势不对称系数、调仓阈值等）并非拍脑袋设定，而是通过 AI 分析历史数据和回测结果不断优化：

```
v1.0 初始版本，固定范围
  ↓ AI 分析发现
  • 低波动期范围太宽，资本效率仅 2×
  • 高波动期范围太窄，频繁出范围
  • 无趋势感知，看涨时下方浪费大量流动性
  ↓ AI 设计优化方案
v1.0 + 波动率自适应 + 趋势不对称 + 防过度调仓
  ↓ AI 回测验证
  Time-in-range 92.5%，年化净收益 18.5%
```

### 3. AI 实时复盘

策略每次 tick 输出结构化 JSON（价格、波动率、范围、触发条件、费用、IL），AI Agent 可随时：

- 分析每次调仓的触发原因和成本效益
- 追踪 time-in-range（在范围内的时间占比）和净收益率
- 识别反模式（如震荡市中频繁调仓导致 Gas 吃掉利润）
- 提出参数调整建议（如 "ATR 乘数从 3.0 提高到 3.5 可减少 20% 的调仓次数"）

### 4. AI 看板生成

Dashboard 同样由 AI 编写——零依赖纯 Python 生成自包含 HTML，支持：

- LP 头寸可视化（当前范围、价格位置、边缘距离）
- 波动率分类历史（低/中/高/极端的时间分布）
- 调仓时间线（每次调仓的触发原因、费用、IL）
- 资本效率追踪（范围宽度 vs 手续费捕获率）
- 净收益分解（手续费 - Gas - IL = 净收益）

---

## 与 OnchainOS 的结合

策略通过 **onchainos CLI** 与链上世界交互。相比网格交易仅需 swap，LP 调仓依赖更丰富的 DeFi 操作能力：

### 市场数据

| 能力 | onchainos 命令 | 用途 |
|------|---------------|------|
| 实时价格 | `market price` | 获取 ETH 当前价格 |
| K 线数据 | `market kline --bar 1H --limit 24` | 24 根 1H 烛图，计算 ATR 波动率 |
| 钱包余额 | `wallet balance` | 读取 ETH + USDC 持仓 |

### DeFi 操作（LP 管理核心）

| 能力 | onchainos 命令 | 用途 |
|------|---------------|------|
| 搜索池 | `defi search --keyword "ETH USDC"` | 查找目标流动性池 |
| 池详情 | `defi detail --investment-id <id>` | 获取池参数（fee tier、tick spacing） |
| 我的头寸 | `defi positions` | 查看所有 LP 头寸 |
| 头寸详情 | `defi position-detail --token-id <nft>` | 查看特定 LP NFT 的范围和累积手续费 |
| 计算入场 | `defi calculate-entry --tick-lower <t> --tick-upper <t>` | 计算指定范围需要的代币比例 |
| 添加流动性 | `defi deposit --tick-lower <t> --tick-upper <t>` | 在指定范围投入流动性 |
| 移除流动性 | `defi redeem --token-id <nft> --percent 100` | 全额移除头寸 |
| 领取手续费 | `defi claim --token-id <nft>` | 领取累积的交易手续费 |

### 交易操作

| 能力 | onchainos 命令 | 用途 |
|------|---------------|------|
| 兑换报价 | `swap quote` | 计算 ETH↔USDC 最优汇率 |
| 执行兑换 | `swap swap` | 调仓时调整代币比例 |
| 代币授权 | `swap approve` | ERC-20 Router 授权 |

### 完整调仓流程

一次完整的调仓涉及 4 步链上操作，全部通过 onchainos CLI 执行：

```
1. onchainos defi claim        → 领取累积手续费（不领就白白损失）
2. onchainos defi redeem       → 移除旧头寸的全部流动性
3. onchainos swap swap         → 根据新范围需要的比例兑换代币
4. onchainos defi deposit      → 在新的最优范围部署流动性
```

**关键优势：**

- **TEE 安全签名** — 私钥在可信执行环境中隔离，策略脚本永远接触不到私钥
- **DeFi 协议抽象** — onchainos 封装了 Uniswap V3 的复杂合约交互（NFT 管理、tick 计算、多步骤原子操作），策略脚本只需声明意图
- **DEX 聚合器** — 调仓兑换时自动在 500+ 流动性源中寻找最优路由，降低滑点
- **Agentic Wallet** — 无需手动管理钱包，onchainos 处理授权、签名、广播全流程

---

## 核心算法

### 范围计算流程

```
当前价格
    ↓
1H K线 (24根) → ATR 计算 → ATR%
    ↓
波动率分类
  < 1.5%  → Low      → 2× ATR 每侧 → 资本效率 ~20×
  1.5-3%  → Medium   → 3× ATR 每侧 → 资本效率 ~7×
  3-5%    → High     → 5× ATR 每侧 → 资本效率 ~3×
  > 5%    → Extreme  → 8× ATR 每侧 → 资本效率 ~1×
    ↓
趋势不对称 (MTF 分析)
  看涨 → 上方放宽，下方收紧
  看跌 → 下方放宽，上方收紧
  中性 → 对称范围
    ↓
Tick 对齐 (对齐到池的 tick_spacing=60)
    ↓
最终范围 [tick_lower, tick_upper]
```

### 示例（ETH @ $2000）

| 波动率 | ATR | 范围 | 宽度 | 资本效率 | 特点 |
|--------|-----|------|------|----------|------|
| Low (1.25%) | $25 | $1950-$2050 | 5.0% | 20× | 窄范围高效率，适合横盘 |
| Medium (2.25%) | $45 | $1865-$2135 | 13.5% | 7.4× | 平衡，日常波动 |
| High (3.5%) | $70 | $1650-$2350 | 35% | 2.9× | 宽范围防 IL，活跃行情 |
| Extreme (6%) | $120 | $1040-$2960 | 96% | 1.0× | 接近全范围，安全优先 |

---

## 部署方式

### 运行环境

```
VPS (7×24)
├── Cron 每 5 分钟 → python3 cl_lp_v1.py tick     → 数据采集+分析+调仓
├── Cron 每天 08:00 → python3 cl_lp_v1.py report   → 生成日报推送 Discord
└── Dashboard 定时生成 → 静态 HTML                   → 浏览器直接访问
```

### 前置条件

- **onchainos CLI** — OKX OnchainOS 命令行工具
- **OKX API Key** — 需有 DEX 交易权限 + DeFi 操作权限
- **Agentic Wallet** — TEE 签名钱包
- **Python 3.10+** — 零第三方依赖
- **VPS**（推荐）— 保证 7×24 稳定运行

### 快速安装

```bash
# 方式一：ClawHub 一键安装
npx clawhub install cl-lp-rebalancer

# 方式二：手动部署
cp cl_lp_v1.py config.json ~/scripts/
crontab -e
# */5 * * * * cd ~/scripts && python3 cl_lp_v1.py tick >> /tmp/cl_lp.log 2>&1
# 0 0 * * * cd ~/scripts && python3 cl_lp_v1.py report >> /tmp/cl_lp.log 2>&1
```

### 运维命令

| 命令 | 用途 | 触发方式 |
|------|------|----------|
| `tick` | 主循环：采集→分析→决策→执行→报告 | Cron 每 5 分钟 |
| `status` | 查看当前头寸、范围、指标、趋势 | 手动 |
| `report` | 生成中文每日报告 | Cron 每天 08:00 CST |
| `history` | 查看调仓历史 | 手动 |
| `reset` | 关闭头寸并重新部署 | 手动 |
| `close` | 完全退出头寸，领取手续费，提取所有资金 | 手动 |
| `analyze` | 输出详细 JSON 分析数据 | AI Agent 调用 |

---

## 适用场景

| 市场状态 | 效果 | 原因 |
|----------|------|------|
| 震荡行情 | 最佳 | 低波动 → 窄范围 → 高资本效率 → 大量手续费 |
| 温和趋势 | 良好 | 不对称范围跟随趋势，减少出范围概率 |
| 高交易量 | 良好 | 更多交易 = 更多手续费收入 |
| 剧烈单边 | 谨慎 | 频繁出范围 + 高 IL，但有紧急回退保护 |
| 极端波动 | 保守 | 极宽范围退化为 V2 全范围 LP，安全但低效 |

---

## 策略演进

```
v1.0  波动率自适应 + 趋势不对称 + 防过度调仓 + 紧急回退
      AI 策略工厂全流程：设计 → 回测 → 部署 → 发布
```

每次版本迭代均由策略工厂的 5 个 AI Agent 协作完成「数据分析 → 方案设计 → 代码实现 → 回测验证 → 上线部署」闭环。

---

*本策略完全由 AI Agent 设计、编写、回测和迭代优化，通过 OKX OnchainOS 实现安全的链上自动做市。*
