# 配置参考与运行手册

> 说明 `config/config.yaml` 及关联 `.env` 字段的含义、取值范围、默认值，以及热更新与运行流程。

---

## 1. 总览

配置分为以下章节：

1. `env` & 账户
2. 策略模式与参数 (`strategy_mode`, `grid`, `scalper`)
3. 风控 (`risk`)
4. 对冲 (`hedge`)
5. 监控与降级 (`telemetry`, `adaptive_mode`, `liquidity`, `funding`)

所有配置经过 `zod` 校验：缺失/类型不匹配会阻止启动。运行期可通过配置热更新，但需要遵循金丝雀流程（见下文）。

---

## 2. 基础配置

| 字段 | 类型 / 默认值 | 描述 | 热更新 |
|------|----------------|------|--------|
| `env` | `mainnet` \| `testnet`（默认 `testnet`） | 影响 API base/WS endpoint | 需重启 |
| `api_base` | URL (`https://api.pacifica.fi/api/v1`) | REST 接口根路径 | 否 |
| `ws_url` | URL (`wss://ws.pacifica.fi/ws`) | 行情 WebSocket | 否 |

`.env` 需提供：
```
PACIFICA_MAKER_ADDRESS=<address>
PACIFICA_MAKER_PRIVATE_KEY=<base58/base64 ed25519>
PACIFICA_HEDGER_ADDRESS=<address>
PACIFICA_HEDGER_PRIVATE_KEY=<private key>
```

---

## 3. 账户配置

```yaml
accounts:
  maker:
    address: ${PACIFICA_MAKER_ADDRESS}
    private_key: ${PACIFICA_MAKER_PRIVATE_KEY}
    subaccount: maker-01
    role: maker
  hedger:
    address: ${PACIFICA_HEDGER_ADDRESS}
    private_key: ${PACIFICA_HEDGER_PRIVATE_KEY}
    subaccount: hedger-01
    role: hedger
```

- `role` 标识账户用途（如 maker/hedger），Runner 会根据该字段分配策略与对冲。若未填写，则使用账户 ID。
- `address` 是 Pacifica 账户地址（API key），用于 REST header `X-Pacific-Key` 以及下单 payload 中的 `account` 字段。
- `private_key` 采用 base58 / base64 表示的 Ed25519 私钥。
- 如需兼容旧配置，可继续使用 `api_key` / `secret` 字段，Runner 会自动回退处理，但推荐尽快迁移到新命名。
- 热更新：❌（变更后必须重启以刷新签名上下文）。

---

## 4. 策略模式

```yaml
strategy_mode: grid  # grid | scalper | both
```

| 模式 | 描述 | 热更新行为 |
|------|------|------------|
| `grid` | 仅运行网格策略 | 支持，下一周期生效 |
| `scalper` | 仅运行剥头皮 | 支持 |
| `both` | 同时运行，Coordinator 协调 | 支持，需确保两策略配置完整 |

---

## 5. 网格策略 (`grid`)

```yaml
grid:
  enabled: true
  symbol: BTC
  grid_step_bps: 0.8
  grid_range_bps: 15
  base_clip_usd: 30
  base_clip_equity_pct: 0.01
  base_clip_leverage: 40
  max_layers: 20
  hedge_threshold_base: 0.12
  tick_size: 1
  lot_size: 0.00001
  incremental_mode: true
  fill_rate_control:
    enabled: true
    target_fills_per_minute: 30
    target_maker_ratio: 0.85
    max_self_trade_ratio: 0.01
    kp_step: 0.02
    ki_step: 0.002
    kp_clip: 0.1
    ki_clip: 0.01
    min_grid_step_bps: 0.5
    max_grid_step_bps: 3.0
    min_clip_usd: 15
    max_clip_usd: 60
    min_maker_ratio_for_adjust: 0.7
    emergency_step_multiplier: 1.5
  adaptive:
    enabled: true
    volatility_window_minutes: 30
    min_volatility_bps: 0.3
    max_volatility_bps: 5
    min_grid_step_bps: 0.6
    max_grid_step_bps: 2.5
    recenter_enabled: true
    recenter_threshold_bps: 500
    recenter_cooldown_ms: 900000
    min_step_change_ratio: 0.3
    tick_interval_ms: 60000
    hedge_pending_timeout_ms: 30000
    post_only_cushion_bps: 0.5
    min_layers: 3
    max_placement_concurrency: 4
    placement_batch_delay_ms: 200
    rate_limit_backoff_ms: 500
  trend_filter:
    enabled: false
    lookback_periods: 12
    trend_threshold_bps: 50
  volatility_monitor:
    enabled: false
    min_daily_range_bps: 80
    action: notify
```

| 字段 | 取值 / 默认 | 说明 | 热更新 |
|------|--------------|------|--------|
| `grid_step_bps` | `0.5`–`10`（默认 `0.8`） | 初始单层间距 (bps)，PI/自适应控制的基准 | 支持，立即重挂 |
| `grid_range_bps` | `10`–`80` | 覆盖范围，微网格建议保持窄区间 | 更新后触发 `reset()` |
| `base_clip_usd` | >0 | 单层挂单名义 | 支持 |
| `base_clip_equity_pct` | 0–1 | 按权益比例动态 clip 下限 | 支持 |
| `base_clip_leverage` | ≥1 | 动态 clip 杠杆倍数 | 支持 |
| `max_layers` | `4`–`40` | 每侧层数上限 | 支持 |
| `hedge_threshold_base` | >0 | 累积 Delta 超阈触发对冲 | 支持 |
| `incremental_mode` | bool (默认 `true`) | 启用 `reconcileGrid` 增量挂单 | 支持 |
| `tick_size` / `lot_size` | `>0` | 价格/数量步长，GridMaker 会整形 | 支持 |

### 5.1 成交率闭环 (`fill_rate_control`)

| 字段 | 默认 | 说明 | 热更新 |
|------|------|------|--------|
| `enabled` | `false` | 开关；开启后 PI 控制优先于 `adaptive` | 支持 |
| `target_fills_per_minute` | 30 | 目标成交率 | 支持 |
| `target_maker_ratio` | 0.85 | 目标 maker 占比 | 支持 |
| `max_self_trade_ratio` | 0.01 | 自成交上限 | 支持 |
| `kp_step` / `ki_step` | 0.02 / 0.002 | 步长调节增益 | 支持 |
| `kp_clip` / `ki_clip` | 0.1 / 0.01 | 数量调节增益 | 支持 |
| `min_grid_step_bps` / `max_grid_step_bps` | 0.5 / 3.0 | PI 输出步长范围 | 支持 |
| `min_clip_usd` / `max_clip_usd` | 15 / 60 | PI 输出数量范围 | 支持 |
| `min_maker_ratio_for_adjust` | 0.7 | maker 比例低于此值时暂停继续收紧 | 支持 |
| `emergency_step_multiplier` | 1.5 | 紧急模式步长放宽倍数 | 支持 |

### 5.2 自适应模块 (`adaptive`)

| 字段 | 默认 | 说明 | 热更新 |
|------|------|------|--------|
| `enabled` | `true` | 波动率驱动步长与重心 | 支持 |
| `volatility_window_minutes` | 30 | 波动率统计窗口 | 支持 |
| `min/max_volatility_bps` | 0.3 / 5 | 波动率映射范围 | 支持 |
| `min/max_grid_step_bps` | 0.6 / 2.5 | 自适应输出步长 | 支持 |
| `recenter_enabled` | `true` | 偏离重心后是否重布 | 支持 |
| `recenter_threshold_bps` | 500 | 重心偏移阈值 | 支持 |
| `recenter_cooldown_ms` | 900000 | 连续重置冷却 | 支持 |
| `min_step_change_ratio` | 0.3 | 触发重布的最小相对变化 | 支持 |
| `tick_interval_ms` | 60000 | 自适应检查间隔 | 支持 |
| `hedge_pending_timeout_ms` | 30000 | 对冲挂单超时阈值 | 支持 |
| `post_only_cushion_bps` | 0.5 | Post-only 缓冲 | 支持 |
| `min_layers` | 3 | 最少档位数 | 支持 |
| `max_placement_concurrency` | 4 | 单批下单并发上限 | 支持 |
| `placement_batch_delay_ms` | 200 | 批次间延迟 | 支持 |
| `rate_limit_backoff_ms` | 500 | 命中限流后的退避时间 | 支持 |

### 5.3 趋势与低波动模块

- `trend_filter`: 根据 `lookback_periods`（单位为 5 分钟）计算趋势，涨跌超出 `trend_threshold_bps` 时暂停网格，冷却期后自动恢复。
- `volatility_monitor`: 日内振幅低于阈值时触发 `action`，可选择 `notify`（告警）、`reduce_step`（自动加宽步长）或 `switch_strategy`（切换至其它策略模式）。

> 🎯 **推荐起始配置**：参考 `config/grid.example.yaml`，根据账户规模调整 `base_clip_usd` 与 `hedge_threshold_base`，并保证 `max_base_abs ≥ hedge_threshold_base × 1.5` 以预留缓冲。

> ⚠️ **极限贴盘口模式（实验）**：将 `grid_step_bps` / `adaptive.min_grid_step_bps` 压到 1–2 bps、`post_only_cushion_bps` 调至 0–1 bps 并配合 `min_layers ≥ 10` 可实现“微网格”密集挂单。此时务必：
> - 同步降低 `tick_interval_ms`、`min_step_change_ratio` 并启用批次节流，避免一次 burst 触发限流；
> - 多账户部署时为内圈/外圈实例分别配置账户与风险限额，防止互相踩限；
> - 先在测试环境验证 post-only 成功率与 RPC 延迟，再逐步推广至实盘。

---

## 6. 剥头皮策略 (`scalper`)

```yaml
scalper:
  enabled: false
  trigger:
    spread_bps: 180
    obi_threshold: 0.6
    trade_imbalance: 0.55
    min_cooldown_ms: 300
  execution:
    passive_clip_usd: 400
    taker_clip_usd: 200
    tp_bps: 30
    sl_bps: 60
```

| 字段 | 说明 | 默认 | 范围 | 热更新 |
|------|------|------|------|--------|
| `spread_bps` | 触发最小价差 | 180 | 120–400 | 支持 |
| `obi_threshold` | 订单簿不平衡阈值 | 0.6 | 0.3–0.8 | 支持 |
| `trade_imbalance` | 成交流偏置 | 0.55 | 0.4–0.8 | 支持 |
| `min_cooldown_ms` | 触发冷却 | 300 | ≥100 | 支持 |
| `tp_bps` | 止盈 | 30 | 10–80 | 支持 |
| `sl_bps` | 止损 | 60 | 20–120 | 支持 |

热更新后，Scalper 在下一次触发时使用新参数。

---

## 7. 风控 (`risk`)

```yaml
risk:
  max_notional_abs: 100000
  max_base_abs: 0.8
  max_order_sz: 0.2
  kill_switch:
    drawdown_pct: 0.5     # 累计回撤 50bps 触发停机
    triggers:
      - type: delta_abs
        threshold: 1.2    # |Delta| > 1.2 BTC
      - type: hedge_failure_count
        threshold: 3      # 连续对冲失败 3 次
      - type: data_gap_sec
        threshold: 3      # 行情断流 3 秒
```

- `max_notional_abs`：策略总名义，若超出 RiskEngine 拒单。
- `max_base_abs`：库存上限；对网格策略尤为重要。
- `max_order_sz`：单笔订单上限；适配拆单逻辑。
- `kill_switch` 支持多触发器；可扩展 `latency_p99`, `funding_correlation`, `stp_rate`, `pnl_drawdown` 等指标。
- 热更新：允许调整阈值；若需要更改 kill-switch 类型，应经评审后重启。

---

## 8. 对冲 (`hedge`)

```yaml
hedge:
  kp: 0.6
  ki: 0.05
  qmax: 0.4
  min_interval_ms: 200
  latency_budget:
    target_p50_ms: 500
    target_p99_ms: 2000
    max_exposure_sec: 3
    retry_max: 2
    retry_slippage_increment_bps: 5
```

| 字段 | 说明 | 备注 |
|------|------|------|
| `kp`, `ki` | PI 控制参数 | 需结合回测调节 |
| `qmax` | 单次对冲最大数量 | 通常 ≤ `max_base_abs` |
| `min_interval_ms` | 对冲节流 | 防止秒内提交多笔 |
| `max_exposure_sec` | 超时强平阈值 | 超过时发起市价单 |
| `retry_max` | IOC 重试次数 | 失败记录指标 |

热更新：支持参数变化，但若增大 `qmax` 超过风控则需同步调整 Risk 配置。

---

## 9. 执行 (`execution`)

```yaml
execution:
  max_slippage_bps: 5
  min_order_interval_ms: 250
  ws_rate_limiter:
    burst: 6
    refill_per_sec: 5
    max_queue_depth: 60

market_data:
  poll_interval_ms: 1000
```

| 字段 | 说明 | 备注 |
|------|------|------|
| `max_slippage_bps` | Router 允许的最大滑点阈值 | 超过后拒单，单位 bps |
| `min_order_interval_ms` | 同账户连续下单的最小间隔 | 防止触发限频或竞态 |
| `ws_rate_limiter.burst` | 允许的瞬时并发请求数 | 建议 4–10，视交易所限额调整 |
| `ws_rate_limiter.refill_per_sec` | 每秒补充的令牌数 | 控制平均速率 |
| `ws_rate_limiter.max_queue_depth` | 排队上限 | 队列溢出会报错，提示降速 |

热更新：支持阈值调整，变更后下一次下单立即生效。

---

## 9. 监控与自适应

```yaml
telemetry:
  push_interval_ms: 5000
  enabled_metrics:
    - maker_ratio
    - hedge_latency_p99

adaptive_mode:
  enabled: true
  rv_threshold_high: 0.5
  actions_on_high_vol:
    - disable: scalper
    - grid.max_layers: 2

liquidity:
  min_top10_depth_usd: 50000
  max_clip_ratio: 0.05
  slippage_alert_bps: 2

funding:
  min_correlation: 0.8
  max_same_sign_ratio: 0.2
  alert_net_cost_bps_per_8h: 1
```

- `adaptive_mode.actions_on_high_vol` 支持指令：`disable:<strategy>`, `grid.max_layers:<value>`, `hedge.qmax:<value>`等。
- `liquidity` 被监控模块用于触发降级或调参。
- `funding` 指标用于 FundingRateMonitor 报警。

---

## 10. 热更新流程

1. 修改 `config.yaml` → `pnpm config:validate`（调用 zod 校验）。
2. 运行 `pnpm backtest --smoke` 验证核心指标。
3. `curl POST /api/config/reload` 触发 Runner 加载新配置：
   - Runner 校验新旧差异，写入审计日志。
   - 若 `strategy_mode` 变化 → Graceful 停止旧策略，启动新策略。
4. 观测金丝雀 10 分钟：`delta_abs`, `hedge_latency`, `hedge_success_rate`。
5. 达标后推广至生产；失败则 `POST /api/config/rollback`。

---

## 11. Runbook（常用操作）

### 11.1 启动
```bash
pnpm install
cp config/config.example.yaml config/config.yaml
pnpm run build
pnpm run live -- --config config/config.yaml
```

### 11.2 停止
```bash
curl -X POST http://localhost:4000/api/halt -d '{"reason":"maintenance"}'
```

### 11.3 查看当前配置
```bash
curl http://localhost:4000/api/config/current
```

### 11.4 金丝雀流程
```bash
pnpm run canary -- --config config/new.yaml --symbols BTC
# 观察 metrics: maker_ratio, delta_abs, hedge_latency_p95
```

---

## 12. 版本管理

- 配置文档更新需同步 bump `configSchemaVersion`。
- Runner 在启动日志中打印当前 schema 版本与配置摘要。
