Hermes-Skills/crypto-t-monitor/SKILL.md

---
name: crypto-t-monitor
description: "OKX 币圈日内做T监控 - 多币种 + 动态 ATR + 网络重试 + 新币自动挑选,推结果到QQ。t-monitor cron 每15分钟跑。v2.3: 每次扫前2名, 池子最多保6个, 超限自动裁旧。"
version: 2.3.0
author: Hermes Agent
license: MIT
platforms: [linux, macos]
metadata:
  hermes:
    tags: [trading, crypto, okx, t-monitor, position, automatic, backtest, multi-coin, new-coin-scanner]
    related_skills: [okx-auto-position, okx-crypto, intraday-trading]
scripts:
  - okx_t_monitor.py: "核心做T脚本, 多币种 + 动态 ATR + 自动重试 + 新币扫描"
  - backtest.py: "回测工具, 验证策略在历史 K 线上的表现"
requires:
  - python3
  - OKX API 凭证 (in ~/.bashrc)
  - Clash 代理 (http://127.0.0.1:7890)
  - push_to_qq.sh
---

# Crypto T-Monitor (币圈日内做T) v2.3.0

OKX 币圈日内做T自动监控系统。**核心定位**:**与股票做T(长桥)完全独立**,本 skill 只负责币圈。

## 🚦 何时使用本 skill

**使用场景**:
- 用户在 OKX 持有币种(ETH/BTC/SOL/DOGE/XRP)做T
- 想在动态 ATR 价位自动低吸/高抛
- 验证策略历史表现(用 backtest)

**不要使用**:
- 跟单交易员信号 → 用 `okx-auto-position`
- 现货/DCA 长持 → 用 `dividend-investing` / `dca-monitor`
- 股票做T → 用 `longbridge-t-monitor`

## ✨ v2.3.0 新功能 (2026-07-10): 新币自动挑选池

**问题**: 用户想要 **30 天内新上市的币** 自动监控,但:
- 不全要 (太多噪音)
- 每次扫描都刷新(非累积)

**解决方案** (用户原话: "新币最多保留六个, 每次扫描后筛选"):

| 常量 | 值 | 含义 |
|------|---|------|
| `NEW_COIN_PICKS` | `2` | **每次扫描后筛 X 个** (按 24h vol 排序) |
| `NEW_COIN_POOL_MAX` | `6` | **永久保留上限** (超过自动裁最早加入) |
| `NEW_COIN_DAYS` | `30` | 30 天内新列 |
| `NEW_COIN_MIN_VOLUME_USDT` | `1_000_000` | 24h vol ≥ $1M (排除无人币) |

**实现逻辑**:
```
1. 拉 OKX 所有 SWAP (公共 endpoint, 不需 credentials)
2. 筛 list_time 在 30 天内的
3. 拉每个的 24h 成交量 (tickers 端点)
4. 过滤 vol < $1M
5. 按 24h vol 降序排序, 取前 NEW_COIN_PICKS=2
6. 比对 state['_new_coin_picks'] 当前次, 变化才推 QQ
7. 加入永久池 state['_new_coin_pool']
8. 池子 > NEW_COIN_POOL_MAX=6 → 按 added_at 升序, 删最早的
```

**QQ 推送格式**:
```
🆕 新币扫描 (30 天内新上市, vol 前 2):

📊 CAP: 24h vol $442.5M | 上线 13.6 天前
📊 NES: 24h vol $67.0M | 上线 15.6 天前

💡 已自动加入监控池 (上限 6 个)
```

**裁剪通知** (超限时):
```
🗑️ 新币池超限 (>6), 移除: ['OLDXYZ', 'ABC123']
```

**代码位置**: `crypto/okx_t_monitor.py:194` (常量) + `:328` (`monitor()` 调用)

## ✨ v2.1.0 新功能 (2026-07-10): 变化驱动推送 (C 方案)

**问题**: v2.0 每次 cron 跑都推"💤 无持仓, 跳过做T",用户**嫌噪音**,问"有变化时推, 计划怎么改?"

**解决方案**: 实现 v2.1 推送规则 (用户拍板的 **C 方案**):
- ❌ 之前: 每次 cron 都推 (噪音)
- ✅ 现在: **只在有变化时推**,其他时间静默 (本地 print 但不推 QQ)

**推送触发条件 (4 类事件,任一触发就推)**:

| # | 事件 | 检测方法 | 推送格式 |
|---|------|---------|---------|
| 1 | **持仓变化** | 对比 `state[sym]_prev_pos` 与当前 `pos_qty`, 差异 > 0.001 张 | `🔄 持仓变化: 1.45 → 1.00 张` |
| 2 | **价格触及关键位** | 当前价距 buy1/buy2/sell1/sell2 任一 < 0.5% | `📍 价格触及 buy2=1762 (距 0.32%)` |
| 3 | **浮盈大幅波动** | 浮盈 ≥ 5% 且相对上次 ≥ 3% | `📈 浮盈变化: -2% → +5% (+7%)` |
| 4 | **做T成交** | buy/sell 实际成交 (原有逻辑) | `✅ 做T自动执行 v2.1` |
| 5 | **做T失败** | buy/sell `code != '0'` | `❌ {sym} {action} 失败: {msg}` |

**静默分支** (全部跳过,只本地 print):
- 没持仓 + 无变化 → `💤 静默: 无持仓, 无变化`
- 有持仓 + 价格距最近关键位 > 0.5% + 浮盈变化 < 3% → `💤 静默: 有持仓但无变化`

**详细实现** 见 `references/change-driven-push.md`。

## ✨ v2.0.0 新功能

**相比 v1.0.0**:
1. **多币种自动** (ETH/BTC/SOL/DOGE/XRP), 不再硬编码 ETH
2. **动态 ATR 价位** (基于 1H K线, 14期 ATR)
3. **网络重试机制** (Clash 抽风时自动重试 2 次)
4. **STATE_FILE 自动清理** (7 天前自动删除)
5. **支持 limit 单** (替代 market 滑点)
6. **回测工具** (`backtest.py`)

## 📦 核心组件

### 1. 监控脚本: `crypto/okx_t_monitor.py`

**位置**: `~/.hermes/scripts/crypto/okx_t_monitor.py`  
**兼容**: `~/.hermes/scripts/t_monitor.py` (symlink)

**核心逻辑**:
```
1. 加载 ~/.bashrc 的 OKX_* 凭证
2. 对每个币种:
   a. 查 OKX 持仓
   b. 如果有持仓 → 拉 1H K线
   c. 计算 ATR(14 期)
   d. 动态算 buy1/buy2/sell1/sell2 价位 (ATR × 0.5)
3. 检查价格是否触及 buy/sell 价位
4. 拉余额/持仓, 成交
5. 记录到 STATE_FILE (自动清理 7 天前)
6. 推结果到 QQ
```

### 2. 回测工具: `crypto/backtest.py`

### 2. 回测工具: `crypto/backtest.py`

**位置**: `~/.hermes/scripts/crypto/backtest.py`

**默认参数 (用户偏好: 默认短期做T, 2026-07-10)**:

| 参数 | 默认 | 说明 |
|------|------|------|
| `--mode` | **short** | 用户原话"默认是短期", 即 1H K 线 + 7 天窗口。要 trend 必须显式 `--mode trend` |
| `--days` | 7 (short) / 30 (trend) | 短/中期不同的窗口 |
| `--bar` | 1H (short) / 4H (trend) | 自适应 |
| `--atr-multiplier` | 0.5 (short) / 1.5 (trend) | 严格说代码当前是 trend=1.5; 但实测 short 下 0.7 才是甜点 |

**用户实测发现**:
- 默认 `--mode trend` 时, fail 拉数据 (4H K线 + 翻页有 bug), 当前只在 1H 跑通
- `short` 模式下 ATR=0.7 实测胜率 81.6% (200 根 K 线回测), 优于 0.5 / 1.0 / 1.5
- **实战 ATR=0.7 比默认 0.5 更好**, 但代码默认是 trend 给的 1.5。**用户跑 short 时需要显式 `--atr-multiplier 0.7`**

**用法**:
```bash
# 默认 (ETH, short = 1H, 7天)
python3 ~/.hermes/scripts/crypto/backtest.py ETH

# 短期 + 实测甜点参数 (推荐)
python3 ~/.hermes/scripts/crypto/backtest.py ETH --mode short --atr-multiplier 0.7

# 趋势 (4H, 30天, 较宽 ATR)
python3 ~/.hermes/scripts/crypto/backtest.py BTC --mode trend

# 自定义参数
python3 ~/.hermes/scripts/crypto/backtest.py ETH \
  --days 14 \
  --bar 4H \
  --atr-multiplier 0.5 \
  --t-qty 0.03

# 输出: 买入/卖出次数, 胜率, 总盈亏, Top 5 盈利交易
```

**重要数据源备注**: OKX 历史 K 线 `bar=4H` 翻页有 bug (当前 backtest.py 只能稳定拉 1H); 跑 trend 必须显式 `--days 7 + --bar 1H` 验证基础链路, 然后慢慢试 4H. 详见 backtest.py 注释.

### 3. cron 任务

| Job ID | 名称(**已重命名清晰化**) | 频率 |
|--------|------|------|
| `db03f9255ad0` | **币圈OKX做T** | `*/15 * * * *` (每 15 分钟) |
| `a82a3ab0d48d` | signal-queue-retry | `*/5 * * * *` |

**命名教训 (2026-07-10)**: cron 名 "t-monitor" 太模糊,用户问"是币圈还是股票"。已重命名 `db03f9255ad0` 为 "币圈OKX做T"。股票侧用 `港股日内交易监控` / `美股日内交易监控` 已经清晰,**所有做T cron 一律带市场名 + 交易所** (例: `币圈OKX做T` / `港股日内交易监控` / `美股日内交易监控` / `A股...`)。**规则**: 任何新的做T cron, 名称必须显式标 "市场 + 交易所 + 动作" 三段。

## 🔧 配置 (`crypto/okx_t_monitor.py`)

### 默认币种
```python
DEFAULT_SYMBOLS = ['ETH', 'BTC', 'SOL', 'DOGE', 'XRP']
```

### 合约规格 (v2.0.0)
```python
SYMBOL_SPECS = {
    'ETH': {'ct_val': 0.1, 'leverage': 25, 't_qty': 0.05},
    'BTC': {'ct_val': 0.01, 'leverage': 25, 't_qty': 0.03},
    'SOL': {'ct_val': 1.0, 'leverage': 20, 't_qty': 5.0},
    ...
}
```

### 动态价位算法 (已实测调优: ATR × 0.7)
```python
ATR = sum(trs[-14:]) / 14                    # 1H K线, 14 期 ATR
buy1  = price - ATR * 0.7 * 0.7             # = ATR * 0.49
buy2  = price - ATR * 0.7                   # = ATR * 0.70
sell1 = price + ATR * 0.7 * 0.7
sell2 = price + ATR * 0.7
```

**实测调优 (2026-07-10, 200 根 K 线回测)**:

| atr 系数 | 交易次数/7天 | 胜率 | 总盈亏 |
|---------|-------------|------|-------|
| 0.5     | 62 + 62  | 79.0% | $16.36 |
| **0.7** | 适中    | **81.6%** ⭐ | **$16.41** |
| 1.0     | 偏少    | 78.8% | $11.54 |
| 1.5     | 很少    | 66.7% | $4.17  |

**结论**: ATR × 0.7 是甜点——胜率最高且总盈亏最大。**已落地到 v2.0.0 代码默认**(修过 `0.5 → 0.7`), 不要退回 0.5。

**含义**: 价格距 ATR 中位 ±50% / ±100%(0.7 倍 ATR),自动调整会追市场波动。

## 📊 STATE_FILE

`~/.hermes/trading/t_state.json`:
```json
{
  "ETH_2026-07-10": ["buy1", "sell1"],
  "BTC_2026-07-10": ["buy2"]
}
```

**自动清理**: `cleanup_state(state, keep_days=7)`, 跨 7 天前的 entry 自动删除。

## 📋 推送格式

**成交** (推 QQ):
```
✅ 做T自动执行 v2.0

🟢低吸 ETH 0.05张 @ $1770.50
级别: 1768.23（buy2）
ATR: $11.20

📊 持仓: 4.05张 @ $1768.23
💰 可用: $52.68
💹 浮盈: +$2.45
```

## 🚨 关键避坑 (2026-07-10 实战教训)

### 1. 默认是短期做T (用户偏好)

用户原话: "默认是短期". 所以:
- 默认 `--mode short`(1H K线, 7 天窗口)
- 默认 `atr_multiplier=0.7`
- 默认单笔 t_qty 占持仓 5-10%
- 不要默认跑 `--mode trend`(那是"等回调"思路,用户没要求)

### 2. 默认监控币种必须包含持仓 (Symbol Coverage Pitfall) ⚠️ 重要

用户曾在 OKX 持有 SPCX, 但 `DEFAULT_SYMBOLS` 没列、`SYMBOL_SPECS` 也没列 → cron 报"💤 无持仓"多次, 但实际持仓 1.45 张。**两类 pitfall**:
- `DEFAULT_SYMBOLS` 缺 → `monitor()` 跳过该币种, 静默
- `SYMBOL_SPECS` 缺 → 拉到持仓计算 LEVELS 时 `KeyError`

**修复**:
- 静态补全: 把持仓币种同时加进两个 dict
- **推荐用 `get_monitored_symbols()` 模式**: 启动时拉 OKX 持仓, 跟静态列表去重合并
- **t_qty 关键定义**: 是"每次做T张数",**不是**总持仓 (SPCX 持仓 1.45 → t_qty=0.5, 不是 1.45)

详见 `references/symbol-coverage-pitfall.md`。

### 3. 实盘前必跑回测 (200 根 K 线起步)

```bash
# 测试新参数
python3 ~/.hermes/scripts/crypto/backtest.py ETH --days 7

# 要求:
# - 胜率 ≥ 55%(预期值正)
# - 最大回撤 ≤ 15%
# - 交易频率适中(7天 20-50 次, 不要 > 100)
# - 总盈亏 > 0

# 实战第一次跑, 必须用 0.01-0.05 张试水
# (SPOT/合约都从最小单位开始, 2-3 天后验证策略再扩仓)
```

### 3. 单向持仓 → 自动退出 (不做贪婪)

- 持仓触及 sell2 (ATR × 0.7 上方) 必须平, **不允许"想再涨点"**
- 跌破 buy2 (ATR × 0.7 下方) 必须加仓? 看 30% utilization 线,不超就加, 不允许"等再跌点"
- **全规则跟随 advisor (okx-auto-position)** 的 close-position 路径, 不自己拍脑袋决定

### 4. cron 失败 ≠ 没运行 (网络抽风)

**症状**: cron 报 `💤 无持仓,跳过做T`,但实际你持 ETH/SPCX。  
**原因**: 在 OKX `fetch_positions` 时网络超时(Clash 抽风), 抛异常被 try/except 吞掉, 误判为空仓。  
**修复**: 在 `monitor()` 函数 `fetch_positions` 失败时记 ERROR, 不要当空仓处理。  
**临时绕过**: 手动 `python3 ~/.hermes/scripts/crypto/okx_t_monitor.py` 复查。

### 5. 状态文件 (t_state.json) 跨日会"恢复"

如果某天没成交 (例如网络挂了), 当天 `traded_levels` 是空。下一天 `state_key` 变了("ETH_2026-07-11"), `traded_levels` 也默认空, 所以**已经触及的价位, 隔夜会再次触发**(如果第二天价格还在那)。  
**修复**: 如果你想"7日内一次性" 触发, 用 `keep_days=7` 删旧 state key 后重做。 v2.0.0 用的是 `cleanup_state(keep_days=7)` 自动删 7 天前的, 但**不**阻止"跨日重复触发同价位"。

## ⚠️ 关键限制

1. **有持仓才做T** (没持仓的币种跳过) — 这是个隐性前提。SPCX 这类"已有持仓"会被监听到,纯增量币种不会主动开仓。
2. **网络依赖**: Clash 死了就完全不能跑(虽然有重试,但重试也失败就崩)
3. **不支持止损** (OKX advisor v4.5.0 才有 SL conditional algo). 持仓被套只能手动 App 或调用 `okx-auto-position/scripts/okx_position_advisor.py --execute` 走 SL-only conditional。
4. **atr_multiplier=0.7** 是实测甜点(不要退回 0.5,见上表)。`1.5` 太宽捕捉不到,`0.5` 交易频率过高产生大量手续费。
5. **不要假设有亏损保护**: `--mode short` 时 81% 胜率不代表实战也 81%——滑点/拒单/网卡都还没建模。

## 🔄 跟其他 skill 的关系

| Skill | 用途 | 冲突? |
|-------|------|------|
| `okx-auto-position` | 信号跟单 (麻吉/熬鹰等) | ✅ 互补 |
| `okx-crypto` | OKX 数据查询 | ✅ 配合 |
| `intraday-trading` | 股票日内 | ❌ 独立 |
| `longbridge-t-monitor` | 股票做T | ❌ 独立 |

## 🔧 故障排查

### Cron 失败?
1. **检查 Clash**: `pgrep mihomo`
2. **测连通**: `curl -s --max-time 8 -x http://127.0.0.1:7890 https://www.okx.com/api/v5/public/time`
3. **看 cron 输出**: `ls -lt ~/.hermes/cron/output/db03f9255ad0/ | head -3`

### 没触发做T?
1. **检查持仓**: `python3 ~/.hermes/scripts/crypto/okx_t_monitor.py` (dry-run 手动跑)
2. **看价格 vs 价位**: 脚本会 print "动态价位"
3. **手动改 LEVELS**: 不推荐 (v2.0.0 全自动)

## 🚀 快速使用

### 监控(自动, 推荐)
```bash
# 加 cron (已存在):
db03f9255ad0 t-monitor */15 * * * *

# 手动跑一次:
python3 ~/.hermes/scripts/crypto/okx_t_monitor.py
```

### 回测(调试新策略)
```bash
# 测试 ETH 默认参数
python3 ~/.hermes/scripts/crypto/backtest.py ETH

# 对比不同 ATR 倍数
for m in 0.3 0.5 0.7 1.0; do
  echo "--- ATR × ${m} ---"
  python3 ~/.hermes/scripts/crypto/backtest.py ETH --atr-multiplier $m
done
```

### 修改默认币种
编辑 `crypto/okx_t_monitor.py` 的 `DEFAULT_SYMBOLS`。

## 📚 相关文档

- `references/change-driven-push.md` - **v2.1 推送策略** (持仓/价格/浮盈变化检测细节, 必读)
- `references/backtest-usage.md` - 回测详细使用 (待写)
- `references/level-dynamic-calculation.md` - ATR 算法详解 (待写)
- `references/api-fallback.md` - 网络重试机制 (待写)

## 🔄 版本历史

- **v2.3.0** (2026-07-10): **新币自动挑选池** (NEW_COIN_PICKS=2, POOL_MAX=6)
- **v2.2.0** (2026-07-10): **静默模式+持仓自动包含** (AUTO_INCLUDE_HOLDINGS, 默认主流币+持仓合并)
- **v2.1.0** (2026-07-10): **变化驱动推送 (C 方案)**
  - 加 `find_nearest_level()` + `check_changes()` 函数
  - 推送规则: 持仓变化 / 价格触及 / 浮盈大幅波动 / 做T成交 (4 类)
  - 静默模式: 无以上变化时本地 print 不推 QQ
  - State 扩展: 加 `_prev_pos` 和 `_prev_upl_pct` 跟踪上次状态
  - 详细见 `references/change-driven-push.md`
- **v2.0.0** (2026-07-10): 
  - 多币种 (ETH/BTC/SOL/DOGE/XRP)
  - 动态 ATR 价位 (实测甜点 0.7, 已落地)
  - 网络重试
  - STATE_FILE 自动清理
  - 支持 limit 单
  - 新增 backtest.py
- **v1.0.0** (2026-07-10): 初始版本, ETH 4 张硬编码