Initial commit: Hermes Agent skills collection

- Trading skills (OKX, dividend, lottery, quantitative) - Creative skills (ASCII art, diagrams, video) - Development skills (GitHub, debugging, TDD) - Research skills (arXiv, blog monitoring) - Productivity skills (email, documents, notes) - MCP integration skills - Custom user skills
2026-07-05 02:31:15 -04:00
commit 6770bc9b9d
908 changed files with 239614 additions and 0 deletions
@@ -0,0 +1,175 @@
+# OKX API 关键Pitfalls
+
+## 1. posMode=net_mode vs long_short_mode
+
+**问题**：账户可能是 `net_mode`（净头寸）而非 `long_short_mode`（多空分离）。
+
+**检查方法**：
+```python
+GET /api/v5/account/config
+# 响应中 "posMode": "net_mode" 或 "long_short_mode"
+```
+
+**影响**：
+- `net_mode`：**禁止传 `posSide` 参数**，否则报错 `sCode=51000 "Parameter posSide error"`
+- `long_short_mode`：**必须传 `posSide`** (long/short)
+
+**下单示例（net_mode）**：
+```python
+{
+    "instId": "ETH-USDT-SWAP",
+    "tdMode": "cross",
+    "side": "buy",       # buy=开多/平空, sell=开空/平多
+    "ordType": "market",
+    "sz": "1"            # 不传posSide！
+}
+```
+
+**设置杠杆（net_mode）**：
+```python
+{
+    "instId": "ETH-USDT-SWAP",
+    "lever": "25",
+    "mgnMode": "cross"   # 不传posSide！
+}
+```
+
+**切换模式**（需要主账户权限）：
+```python
+POST /api/v5/account/set-position-mode
+{"posMode": "long_short_mode"}  # 或 "net_mode"
+```
+
+---
+
+## 2. OCO订单合并（加仓场景）
+
+**问题**：加仓后，旧OCO只覆盖旧仓位，新OCO只覆盖新仓位，导致多个OCO并存。
+
+**错误示例**：
+- 持仓5张，OCO(sell 5, SL=1660, TP=1746)
+- 加仓1张 → 持仓6张
+- 新建OCO(sell 1, SL=1666.8, TP=1775.1)
+- 结果：2个OCO并存，旧OCO触发只平5张，剩1张单独走
+
+**正确流程**：
+1. 查现有OCO：`GET /api/v5/trade/orders-algo-pending?ordType=oco`
+2. 找到同instId的旧OCO algoId
+3. 删除旧OCO：`POST /api/v5/trade/cancel-algo` → `[{instId, algoId}]`
+4. 创建新OCO覆盖全部持仓
+
+**验证**：
+```bash
+# 查pending OCO
+curl -X GET "https://www.okx.com/api/v5/trade/orders-algo-pending?ordType=oco" \
+  -H "OK-ACCESS-KEY: $KEY" ...
+
+# 应该只有一个OCO per instId
+```
+
+---
+
+## 3. 补推信号必须先查持仓
+
+**场景**：模型断线后补推积压信号。
+
+**错误做法**：直接用历史信号数据推送推荐（如"4,290 ETH加仓到4,455"）。
+
+**正确做法**：
+1. 先查当前持仓：`GET /api/v5/account/positions`
+2. 再查当前algo orders：`GET /api/v5/trade/orders-algo-pending?ordType=oco`
+3. 用**当前持仓数据**而非历史信号数据生成推荐
+
+**案例**：
+- 历史信号说"4,290 ETH"
+- 实际持仓已是5张（可能中间已有多次变动）
+- 用历史数据推"加仓到4,455"是错误的
+
+---
+
+## 4. 遍历查询algo orders
+
+**问题**：`ordType` 参数不能组合查询，需逐个类型查。
+
+```python
+for algo_type in ["oco", "conditional", "trigger", "move_order_stop"]:
+    result = okx_get(f"/api/v5/trade/orders-algo-pending?ordType={algo_type}")
+    # 处理 result["data"]
+```
+
+**注意**：某些类型可能返回错误（如账户未开通该功能），需忽略错误继续。
+
+---
+
+## 5. 密码中含特殊字符
+
+**问题**：`OKX_PASSPHRASE` 含 `$` 等特殊字符时，bash 会尝试变量展开。
+
+**错误**：`export OKX_PASSPHRASE=mikeOkxID$1` → `$1` 展开为空
+
+**正确**：
+```bash
+export OKX_PASSPHRASE='mikeOkxID$1'  # 单引号
+```
+
+**或从文件读取**：
+```python
+with open("~/.bashrc", "r") as f:
+    for line in f:
+        if "OKX_PASSPHRASE" in line:
+            passphrase = line.split("=", 1)[1].strip().strip('"').strip("'")
+```
+
+---
+
+## 6. 凭证变量名：OKX_SECRET（不是OKX_SECRET_KEY）
+
+bashrc里实际变量名是 `OKX_SECRET`，不是 `OKX_SECRET_KEY`。
+
+**脚本内部**：`load_credentials()` 用 `OKX_\w+` 正则匹配，自动兼容，不受影响。
+
+**手动ccxt初始化**（agent写临时Python时）：
+```python
+# ❌ 错误 — 会 KeyError
+creds['OKX_SECRET_KEY']
+
+# ✅ 正确
+creds['OKX_SECRET']
+
+# ✅ 兼容写法
+secret = creds.get('OKX_SECRET', '') or creds.get('OKX_SECRET_KEY', '')
+```
+
+**三个变量**：`OKX_API_KEY`、`OKX_SECRET`、`OKX_PASSPHRASE`
+
+---
+
+## 7. --execute 必须同时带 --rec-json
+
+脚本代码 `if args.execute and args.rec_json:` 要求两个参数同时存在。
+
+**错误**：只传 `--execute` 不传 `--rec-json` → 静默跳过执行，fall through到推荐流程
+
+**正确两步流程**：
+```bash
+# 第1步：获取推荐JSON
+python3 okx_position_advisor.py --symbol HYPE --side long --leverage 10 --json > /tmp/rec.json
+
+# 第2步：执行下单（必须同时带 --execute 和 --rec-json）
+python3 okx_position_advisor.py --symbol HYPE --side long --leverage 10 --execute --json --rec-json "$(cat /tmp/rec.json)"
+```
+
+---
+
+## 8. 余额为零时ZeroDivisionError
+
+**问题**：`recommend_position()` 函数在计算 `margin_pct = total_margin / acct_info['usdt_free'] * 100` 时，如果 `usdt_free=0`（用户满仓），会抛出 `ZeroDivisionError`。
+
+**修复**：在调用 `recommend_position()` 前检查余额：
+```python
+if acct_info['usdt_free'] < 0.01:
+    print("⚠️ 余额不足（可用0 USDT），无法开仓")
+    sys.exit(0)
+```
+
+**format_signal.py 已加 try/except 处理此场景。**