# BitPilot 产品架构与功能说明书

> **BitPilot — AI 自动驾驶你的加密资产**
>
> 版本：2.0.0 | 更新日期：2026-04-01

---

## 一、产品定位

BitPilot 是构建在 **Bitget Agent Hub** 之上的 AI 策略执行平台。它不替代 Bitget 官方交易工具，而是在其 58 个原子操作之上，提供**策略编排层 + 风控层 + 自动化层**，将零散的交易 API 转化为 7×24 小时无人值守的资产管理系统。

### 我们解决什么问题

| 现状 | BitPilot 的解决方案 |
|------|-------------------|
| Bitget API 是原子操作（买/卖/查），用户需自行组合 | 预置 7 种经过验证的策略模板，一条命令启动 |
| 没有风控机制，API 调错就直接执行 | 6 步安全检查链，每笔交易过 6 道门 |
| 手动盯盘，不能 24/7 运行 | 守护进程 + 崩溃自恢复 + 指数退避重试 |
| AI Agent 只能调单个工具 | Skill 封装让 AI 理解策略语义，自然语言直接操控 |
| 策略之间孤立运行 | BitPilot Pro 三引擎联动，全局熔断 + 跨池资金调度 |

### 目标用户

- **加密交易者**：想自动化但不想写代码
- **AI 工具用户**：Claude Code / Cursor 用户，用自然语言管理资产
- **稳健型投资者**：追求低波动、持续收益，不想频繁操作
- **开发者**：想在 Bitget 上构建自己的量化策略

---

## 二、系统架构

### 2.1 三层架构

```
┌─────────────────────────────────────────────────────────────┐
│                    用户交互层                                │
│                                                             │
│   自然语言（Claude Code / Cursor / 40+ AI Agent）           │
│           ↓ Skill 解析                                      │
│   CLI 命令（bgtask run / status / dashboard）               │
└──────────────────────┬──────────────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────────────┐
│                   策略执行层（bgtask）                        │
│                                                             │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐       │
│  │SleepYield│ │  Alpha   │ │  Yield   │ │ BitPilot │       │
│  │ 费率套利  │ │ Rotator  │ │  Pilot   │ │   Pro    │       │
│  │          │ │ 动量轮动  │ │ 收益路由  │ │ 三引擎   │       │
│  └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘       │
│       │            │            │            │              │
│  ┌────▼────────────▼────────────▼────────────▼─────┐        │
│  │              安全检查链（6 步）                    │        │
│  │  危险拦截 → Dry-run → 日限额 → 仓位% → 大额确认   │        │
│  │  → 持仓冲突                                      │        │
│  └────────────────────┬────────────────────────────┘        │
│                       │                                     │
│  ┌────────────────────▼────────────────────────────┐        │
│  │          守护进程（Daemon）                       │        │
│  │  后台运行 · 崩溃恢复 · 任务持久化 · IPC 通信      │        │
│  └────────────────────┬────────────────────────────┘        │
└───────────────────────┼─────────────────────────────────────┘
                        │
┌───────────────────────▼─────────────────────────────────────┐
│                  基础设施层（Bitget Agent Hub）               │
│                                                             │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐                     │
│  │  Core   │  │   CLI   │  │  REST   │   三级 Provider     │
│  │Provider │  │Provider │  │Provider │   自动降级           │
│  │(最快)   │→│(备选)    │→│(兜底)    │                     │
│  └────┬────┘  └────┬────┘  └────┬────┘                     │
│       └────────────┴────────────┘                           │
│                     │                                       │
│  ┌──────────────────▼──────────────────────┐                │
│  │     Bitget Exchange API（58 个工具）      │                │
│  │  现货 · 合约 · 理财 · 跟单 · 杠杆 · P2P  │                │
│  └─────────────────────────────────────────┘                │
└─────────────────────────────────────────────────────────────┘
```

### 2.2 Provider 三级降级

系统通过 Provider 抽象层对接 Bitget，自动检测并选择最优通道：

| 级别 | Provider | 方式 | 延迟 | 依赖 |
|------|----------|------|------|------|
| 1 | CoreProvider | Node.js 原生调用 `bitget-core` | ~5ms | `npm i -g bitget-core` |
| 2 | CliProvider | 子进程调用 `bgc` CLI | ~50ms | `npm i -g bitget-client` |
| 3 | RestProvider | HTTPS REST API 直连 | ~200ms | 仅需环境变量 |

- 自动检测当前环境可用的 Provider
- 支持 HTTP/HTTPS 代理（`HTTPS_PROXY` / `HTTP_PROXY`）
- `bgtask check` 命令可验证所有 Provider 状态

### 2.3 守护进程架构

```
┌──────────────────────────────────────────────┐
│              Daemon（主进程）                  │
│                                              │
│  ┌────────┐  ┌────────┐  ┌────────┐         │
│  │Worker 1│  │Worker 2│  │Worker 3│  ← 子进程│
│  │ sleep  │  │ alpha  │  │ yield  │         │
│  │ yield  │  │rotator │  │ pilot  │         │
│  └───┬────┘  └───┬────┘  └───┬────┘         │
│      │           │           │               │
│      └───────────┴───────────┘               │
│              IPC 通信                         │
│         (Unix Socket)                        │
│                                              │
│  Task Store → ~/.bgtask/tasks/*.json         │
│  Daily Counter → ~/.bgtask/daily-trades-*.json│
│  Logs → ~/.bgtask/logs/*.log                 │
│  Lock → ~/.bgtask/daemon.lock                │
└──────────────────────────────────────────────┘
```

**任务生命周期：**

```
pending → running → completed (正常结束)
                  → stopped   (手动停止)
                  → restarting → running (daemon restart 恢复)
                  → failed    (3 次重试后失败)

重试策略：指数退避 2s → 4s → 8s，最多 3 次
```

---

## 三、策略引擎

### 3.1 SleepYield — 睡后引擎（资金费率套利）

**原理：** 现货买入 + 合约等量做空 = Delta 中性（零方向敞口），纯吃多头向空头支付的资金费率。

```
                资金费率（每 8h 结算）
    多头持仓者 ──────────────────→ 空头持仓者
                                      ↑
                                   我们在这里
    
    同时持有：
    ┌──────────┐    ┌──────────┐
    │ 现货多头  │ +  │ 合约空头  │ = 方向中性，只赚费率
    │ +500 USDT│    │ -500 USDT│
    └──────────┘    └──────────┘
```

**入场条件：**
1. 资金费率连续 3 期（24h）为正且 ≥ 0.01%/8h
2. 多空比 > 1.2（结构性支撑正费率）
3. 盘口价差 < 0.05%（流动性充足）

**出场条件：**
- 累计收益达止盈线（默认 2%）
- 连续 2 期费率转负
- 现货/合约基差偏移 > 3%
- 持仓超过最大天数（默认 30 天）

**收益模型：**

| 场景 | 费率/8h | 年化收益 | 回本天数 |
|------|---------|---------|---------|
| 保守（震荡市） | 0.01% | 10-11% | ~8.5 天 |
| 标准（上行市） | 0.02% | 18-20% | ~4.3 天 |
| 牛市 | 0.03%+ | 25-30% | ~2.8 天 |

**最大回撤：** < 3%（仅在基差极端偏移时发生）

**使用的 Bitget 工具（13 个）：**
- 合约模块：开仓、平仓、杠杆设置、保证金模式、持仓查询
- 现货模块：下单、撤单、余额查询
- 理财模块：申购、赎回（闲置资金停泊）
- 账户模块：总资产、手续费查询

---

### 3.2 AlphaRotator — 强势雷达（动量轮动）

**原理：** 每月对币池所有币种进行三因子量化评分，买入最强的 Top N，卖出最弱的，并用 ATR 波动率缩放仓位——波动大的少买，波动小的多买。

**三因子评分模型：**

```
总分 = ROC(20) × 40% + RSI(14) × 30% + MACD × 30%

┌──────────────┬────────────────────┬────────┐
│    因子       │      含义          │  权重   │
├──────────────┼────────────────────┼────────┤
│ ROC(20)      │ 20 日涨幅          │  40%   │
│ RSI(14)      │ 相对强弱           │  30%   │
│ MACD 柱状图   │ 趋势加速/减速      │  30%   │
└──────────────┴────────────────────┴────────┘

RSI 评分曲线：
  0-30  → 低分（弱势）
  30-50 → 中等
  50-65 → 最高分（强势上升通道）
  65-80 → 中等偏高
  80+   → 扣分（过热风险）
```

**ATR 波动率缩放：**
```
某币仓位 = 基础仓位 × (平均 ATR / 该币 ATR)

示例：BTC ATR 低 → 多分配；SOL ATR 高 → 少分配
效果：等波动率敞口，防止单一高波币拖垮组合
```

**默认币池：** BTC, ETH, SOL, BNB, XRP, AVAX（可自定义）
**筛选标准：** Bitget 上市、日均交易量 > 1 亿 U、非稳定币、上市 > 6 个月

**恐惧指数避险机制：**
```
Fear & Greed Index < 20（极度恐惧）
  → 全仓卖出，资金转入 Earn 理财
  → 等待指数恢复到 30+ 才重新入场
  → 防止在市场崩盘时持有高波资产
```

**收益模型：**

| 场景 | 年化收益 | 最大回撤 |
|------|---------|---------|
| 保守（震荡） | 8-10% | 14-18% |
| 标准（趋势） | 19-20% | 12-15% |
| 牛市 | 35%+ | 10% |

**止损机制：**
- 单币止损：-15% 自动卖出
- 止损后进入 60 天冷却期，不再选入
- 全局避险：恐惧指数 < 20 全仓退出

---

### 3.3 YieldPilot — 收益导航（智能资金路由）

**原理：** 每 8 小时比较两个收益池的 APY，资金自动流向收益更高的一侧。

```
  ┌─────────────────────────┐
  │      YieldPilot 决策引擎  │
  │    每 8h 比较一次 APY     │
  └──────────┬──────────────┘
             │
    ┌────────┴────────┐
    ▼                 ▼
┌─────────┐    ┌──────────┐
│  Earn   │    │  Delta   │
│  理财    │    │ Neutral  │
│ 5-11%   │    │ 10-25%+  │
│ APY     │    │  APY     │
│ 零风险   │    │ 极低风险  │
└─────────┘    └──────────┘
```

**切换逻辑：**
- 费率年化 > Earn APY + 5% → 转入 Delta-Neutral
- 费率年化 < Earn APY 或连续 2 期负费率 → 转入 Earn
- 两者都不好 → 停在 USDT 等待

**防频繁切换：** 最少持仓 72 小时才允许切换（防止手续费损耗）

**收益模型：**

| 场景 | 年化收益 |
|------|---------|
| 保守（80% Earn / 20% DN） | 7.6% |
| 标准（50/50） | 9.5% |
| 牛市（80% DN / 20% Earn） | 21% |

---

### 3.4 BitPilot Pro — 全自动驾舱（三引擎编排）

**原理：** 三个策略引擎协同运行，通过全局风控和跨池资金调度实现风险最优组合。

```
┌──────────────────────────────────────────────────────┐
│                 BitPilot Pro 调度器                    │
│                                                      │
│   ┌──────────┐  ┌──────────┐  ┌──────────┐          │
│   │ 稳健引擎  │  │ 增长引擎  │  │ 储备仓   │          │
│   │SleepYield│  │  Alpha   │  │  Earn   │          │
│   │   60%    │  │ Rotator  │  │  10%    │          │
│   │          │  │   30%    │  │         │          │
│   └────┬─────┘  └────┬─────┘  └────┬────┘          │
│        │             │             │                │
│        └─────────────┴─────────────┘                │
│                      │                              │
│   ┌──────────────────▼──────────────────┐           │
│   │          全局风控引擎                 │           │
│   │                                     │           │
│   │  恐惧指数 < 15 → 全部避险到 Earn     │           │
│   │  总回撤 > 8%   → 全部避险到 Earn     │           │
│   │  恢复条件：Fear ≥ 25 且 回撤 < 4%    │           │
│   └─────────────────────────────────────┘           │
└──────────────────────────────────────────────────────┘
```

**跨引擎资金联动：**

| 事件 | 资金流向 |
|------|---------|
| AlphaRotator 触发止损 (-15%) | 50% → SleepYield, 50% → Reserve |
| SleepYield 费率转负 | 全部 → Reserve (Earn) |
| Reserve 低于 5% | 从 SleepYield 利润补充 |
| 全局避险触发 | 三个引擎全部 → Earn |

**组合收益模型：**

| 指标 | 值 |
|------|-----|
| 预期年化 | 11-22% |
| 最大回撤 | 8-12% |
| 相比纯动量 | 回撤降低 40-50% |
| 相比纯套利 | 收益提升 30-50% |

---

## 四、安全体系

### 4.1 六步安全检查链

每一笔交易，无论来源（手动命令、策略自动触发、AI Agent 调用），都必须通过完整的 6 步安全检查链。任何一步失败，交易直接拒绝。

```
交易请求
    │
    ▼
┌────────────────────────────────┐
│ Step 1: 危险工具硬拦截          │
│ 永久禁止：提现、子账户操作等     │  ← 不可配置，硬编码
│ 命中 → 立即拒绝                │
└────────────┬───────────────────┘
             │ 通过
             ▼
┌────────────────────────────────┐
│ Step 2: Dry-run 检查           │
│ --dry-run 模式下只记录不执行    │  ← 开发/测试阶段使用
│ 命中 → 记录日志，跳过执行       │
└────────────┬───────────────────┘
             │ 通过
             ▼
┌────────────────────────────────┐
│ Step 3: 日交易次数限额          │
│ conservative: 3 笔/天          │
│ balanced:     10 笔/天         │  ← 计数持久化到磁盘
│ aggressive:   50 笔/天         │    daemon 重启不丢失
│ 超限 → 拒绝                    │    只计成功订单
└────────────┬───────────────────┘
             │ 通过
             ▼
┌────────────────────────────────┐
│ Step 4: 仓位比例检查            │
│ conservative: 单笔 ≤ 总资产 5%  │
│ balanced:     单笔 ≤ 总资产 10% │  ← 防止单笔过大
│ aggressive:   单笔 ≤ 总资产 20% │
│ 超限 → 拒绝                    │
└────────────┬───────────────────┘
             │ 通过
             ▼
┌────────────────────────────────┐
│ Step 5: 大额确认               │
│ conservative: > 200 USDT 需确认 │
│ balanced:     > 500 USDT 需确认 │  ← 前台：交互确认
│ aggressive:   > 1000 USDT 需确认│    后台：自动拒绝
│ --confirm 可跳过                │
└────────────┬───────────────────┘
             │ 通过
             ▼
┌────────────────────────────────┐
│ Step 6: 持仓冲突检测            │
│ 检查是否与现有仓位方向冲突       │
│ 例如：已做多 BTC 时禁止做空 BTC  │  ← aggressive 档关闭
│ 冲突 → 拒绝                    │
└────────────┬───────────────────┘
             │ 通过
             ▼
         执行交易
```

### 4.2 三级风控档位

| 维度 | Conservative | Balanced | Aggressive |
|------|-------------|----------|-----------|
| 单笔仓位上限 | 总资产 5% | 总资产 10% | 总资产 20% |
| 最大杠杆 | 3x | 10x | 20x |
| 止损线 | 2% | 5% | 10% |
| 止盈线 | 5% | 10% | 20% |
| 日交易限额 | 3 笔 | 10 笔 | 50 笔 |
| 大额确认阈值 | 200 USDT | 500 USDT | 1000 USDT |
| 持仓冲突检测 | 开启 | 开启 | 关闭 |

### 4.3 权限分级

所有 Bitget 工具按风险等级分为四类：

| 级别 | 说明 | 示例 | 策略可调用 |
|------|------|------|----------|
| READ | 只读查询 | 余额、行情、K线 | 全部允许 |
| TRADE | 交易操作 | 下单、平仓 | 经安全链后允许 |
| CONFIG | 配置变更 | 杠杆、保证金模式 | 策略初始化时允许 |
| DANGER | 高危操作 | 提现、子账户转账 | 永久禁止 |

---

## 五、通知系统

### 5.1 Telegram 通知

```
┌────────────────────────────┐
│  BitPilot 费率结算收入        │
│                            │
│  本次收入: +12.34 USDT     │
│  累计收入: +45.67 USDT     │
│  当前持仓: BTC 现货+合约    │
│  下次结算: 4h 后            │
│                            │
│  2026-04-01 16:00 UTC      │
└────────────────────────────┘
```

### 5.2 Webhook 通知

```json
{
  "product": "睡后引擎 SleepYield",
  "event": "funding_settled",
  "title": "费率结算收入",
  "details": [
    {"label": "本次收入", "value": "+12.34 USDT"},
    {"label": "累计收入", "value": "+45.67 USDT"}
  ],
  "timestamp": 1743523200000
}
```

### 5.3 支持的事件类型

| 事件 | 说明 |
|------|------|
| `entry` | 开仓/买入 |
| `exit` | 平仓/卖出 |
| `stop_loss` | 触发止损 |
| `fear_exit` | 恐惧指数避险 |
| `fear_recovery` | 恐惧指数恢复 |
| `global_shelter` | 全局避险触发 |
| `recovery` | 全局恢复 |
| `rebalance` | 轮动再平衡 |
| `funding_settled` | 费率结算 |
| `switch` | YieldPilot 切换收益池 |
| `daily_report` | 每日报告 |
| `risk_alert` | 风控预警 |
| `error` | 系统错误 |

---

## 六、Skill 生态与 AI Agent 集成

### 6.1 Skill 架构

```
┌─────────────────────────────────────────┐
│           AI Agent（龙虾）               │
│  Claude Code / Cursor / 40+ Agent       │
│                                         │
│  用户："帮我用 3000U 做费率套利"          │
│         │                               │
│         ▼                               │
│  ┌──────────────────┐                   │
│  │  Skill 解析层     │                   │
│  │  sleep-yield.md  │                   │
│  │                  │                   │
│  │  → 提取 budget   │                   │
│  │  → 选择策略      │                   │
│  │  → 风险提示      │                   │
│  │  → 环境检测      │                   │
│  └────────┬─────────┘                   │
│           │                             │
│           ▼                             │
│  bgtask run sleep-yield                 │
│    --symbols BTCUSDT                    │
│    --budget 3000                        │
│    --risk-profile conservative          │
│    --daemon                             │
└─────────────────────────────────────────┘
```

### 6.2 七个 Skill

| Skill | 触发词 | 对应策略 |
|-------|--------|---------|
| `sleep-mode` | 盯盘、睡觉模式、夜间守护 | 价格触发交易 |
| `event-mode` | 异动、暴跌、风控保护 | 事件驱动减仓 |
| `copy-mode` | 跟单、找交易员、copy trade | 智能跟单 |
| `sleep-yield` | 费率套利、睡后收入、delta neutral | 资金费率套利 |
| `alpha-rotator` | 动量轮动、买强卖弱、强势币 | 动量轮动 |
| `yield-pilot` | 闲钱理财、收益最大化 | 智能资金路由 |
| `bitpilot-pro` | 全自动、帮我管钱、自动驾驶 | 三引擎组合 |

### 6.3 零配置安装

每个 Skill 内置自动环境检测，用户导入 Skill 后说一句话，AI Agent 会自动：

1. 检测 bgtask 未安装 → `npm install -g @hunterweb303/bgtask`
2. 检测 Provider 缺失 → `npm install -g bitget-core`
3. 检测 API Key 缺失 → 引导用户获取并配置
4. 全部就绪 → 执行策略

**用户需要做的事：0 个命令，1 句话。**

---

## 七、Dashboard 实时面板

```
┌─────────────────────────────────────────────────┐
│  BitPilot Dashboard              Running  12h   │
│─────────────────────────────────────────────────│
│                                                 │
│  Total: 10,234.56 USDT    Today: +23.45 USDT   │
│  Max DD: -1.2%             Fear: 45 (Neutral)   │
│                                                 │
│  ┌─────────────────────────────────────────┐    │
│  │ SleepYield  [████████░░]  +0.89%        │    │
│  │ BTC DN      Running      +12.34 USDT    │    │
│  ├─────────────────────────────────────────┤    │
│  │ AlphaRotator [██████░░░░]  +2.34%       │    │
│  │ SOL/BNB/ETH  Next rebal: 18d            │    │
│  ├─────────────────────────────────────────┤    │
│  │ Reserve     [██████████]  +0.12%        │    │
│  │ Earn USDT    APY: 7.2%                  │    │
│  └─────────────────────────────────────────┘    │
│                                                 │
│  Recent Events:                                 │
│  16:00  funding_settled  +4.56 USDT             │
│  08:00  daily_report     Total PnL: +23.45      │
│  02:00  funding_settled  +4.12 USDT             │
└─────────────────────────────────────────────────┘
```

---

## 八、CLI 命令总览

### 策略命令

| 命令 | 说明 |
|------|------|
| `bgtask run sleep-mode` | 价格触发交易 |
| `bgtask run event-mode` | 事件驱动减仓 |
| `bgtask run copy-mode` | 智能跟单 |
| `bgtask run sleep-yield` | 资金费率套利 |
| `bgtask run alpha-rotator` | 动量轮动 |
| `bgtask run yield-pilot` | 智能资金路由 |
| `bgtask run bitpilot-pro` | 三引擎全自动 |

### 管理命令

| 命令 | 说明 |
|------|------|
| `bgtask daemon start` | 启动守护进程 |
| `bgtask daemon stop` | 停止守护进程和所有任务 |
| `bgtask daemon restart` | 重启并恢复任务 |
| `bgtask daemon status` | 查看守护进程状态 |
| `bgtask list [--json]` | 列出所有任务 |
| `bgtask status <id> [--json]` | 查看任务详情 |
| `bgtask stop <id>` | 停止单个任务 |
| `bgtask logs <id> [-f] [-n N]` | 查看/追踪日志 |
| `bgtask check` | 验证环境和 Provider |
| `bgtask dashboard [--once]` | 实时面板 |
| `bgtask notify set <key> <value>` | 设置通知 |
| `bgtask notify test` | 测试通知 |

### 通用 Flag

| Flag | 说明 | 默认值 |
|------|------|-------|
| `--daemon` | 后台守护进程模式运行 | false |
| `--dry-run` | 只记录不执行 | false |
| `--confirm` | 跳过大额交互确认 | false |
| `--risk-profile` | 风控档位 | conservative |

---

## 九、环境变量

| 变量 | 说明 | 必需 |
|------|------|------|
| `BITGET_API_KEY` | Bitget API Key | 是 |
| `BITGET_SECRET_KEY` | Bitget Secret Key | 是 |
| `BITGET_PASSPHRASE` | Bitget API Passphrase | 是 |
| `HTTPS_PROXY` | HTTPS 代理地址 | 否 |
| `HTTP_PROXY` | HTTP 代理地址 | 否 |

---

## 十、数据存储

所有数据存储在 `~/.bgtask/` 目录：

```
~/.bgtask/
├── config.json                     # 应用配置（通知等）
├── daemon.lock                     # 守护进程 PID 锁
├── daemon.sock                     # IPC Unix Socket
├── daily-trades-YYYY-MM-DD.json    # 每日交易计数（安全链用）
├── tasks/
│   ├── sleep-yield-1743523200.json # 任务定义 + 运行状态
│   └── alpha-rotator-1743523200.json
└── logs/
    ├── sleep-yield-1743523200.log  # 任务日志
    └── alpha-rotator-1743523200.log
```

---

## 十一、技术栈

| 组件 | 技术 |
|------|------|
| 语言 | TypeScript (ES2022) |
| 运行时 | Node.js ≥ 18 |
| 构建 | tsup |
| 测试 | vitest |
| CLI 框架 | commander |
| WebSocket | ws |
| HTTP 客户端 | undici |
| 代理支持 | https-proxy-agent |
| 终端 UI | chalk |

---

## 十二、开源与许可

- **协议：** MIT
- **GitHub：** https://github.com/duolaAmengweb3/bgtask
- **npm：** `npm install -g @hunterweb303/bgtask`
- **Skills：** https://github.com/duolaAmengweb3/bitget-task-skills