grid_skeleton/docs/CONFIG_REFERENCE.md

配置参考与运行手册

说明 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. 账户配置

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. 策略模式

strategy_mode: grid  # grid | scalper | both

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

---

5. 网格策略 (grid)

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)

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)

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.6    # |Delta| > 1.6 BTC
      - type: hedge_failure_count
        threshold: 3      # 连续对冲失败 3 次
      - type: data_gap_sec
        threshold: 3      # 行情断流 3 秒
      - type: pnl_drawdown
        threshold: 1.0    # 单独的 PnL 触发（可选）

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

---

8. 对冲 (hedge)

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)

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. 监控与自适应

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 启动

pnpm install
cp config/config.example.yaml config/config.yaml
pnpm run build
pnpm run live -- --config config/config.yaml

11.2 停止

curl -X POST http://localhost:4000/api/halt -d '{"reason":"maintenance"}'

11.3 查看当前配置

curl http://localhost:4000/api/config/current

11.4 金丝雀流程

pnpm run canary -- --config config/new.yaml --symbols BTC
# 观察 metrics: maker_ratio, delta_abs, hedge_latency_p95

---

12. 版本管理

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