# 微网格控制框架与迭代任务

> 目标：在“未知趋势、上下 50/50”场景下，通过对称化的网格控制实现稳定的做市收益与库存安全。本框架总结当前设计要点，并列出下一版本需要落地的研发任务。

---

## 1. 控制目标（长期不变）

- **Delta 中性**：账户净仓位长期逼近 0。
- **成交 KPI**：单位时间成交次数 `fills/min ≥ f*`，同时 maker 成交通道占比 `≥ m*`。
- **费用为正**：`maker 返佣 – taker 手续费 – 滑点` ≥ 0。

---

## 2. 基线对称配置（开箱即用）

| 项目 | 建议值 | 说明 |
| --- | --- | --- |
| 挂单价格 | mid 或 mid±1 tick 对称 | 以中价为基准构建对称网格 |
| 网格间距 `ΔP` | ≥ 0.8 × 最优价差 `S=a₁-b₁` | tick 对齐，确保 maker-only |
| 单格数量 `Q` | 0.05%～0.10% NAV | 再按盘口深度缩放 |
| 层数 `N` | 单侧 4–8 层（总 8–16） | 初期密度控制 |
| 撤单刷新 `τ` | 2–5 s 或订单簿事件驱动 | 避免队列过度滞后 |
| maker-only | 默认开启 | taker 仅作纠偏/止损 |
| 自成交保护 | 双账户互挂或同账户 price+nonce 过滤 | 防止 self-trade |

---

## 3. 五个闭环控制

### 3.1 库存闭环（Inventory Loop）
- 指标：`δ = |Q_long - Q_short| / Q_total`。
- 阈值：`δ_max = 1.5%`（建议 1–2%）。
- 当 `δ > δ_max`：
  - 将“偏仓方向”的网格整体外移 1–2 tick，提升反向成交概率。
  - 减小偏仓侧 `Q`（例如乘以 0.7）。
  - 必要时触发小额 taker 对冲。
- 当 `δ < 0.5 · δ_max` 时，恢复完全对称。

### 3.2 成交率闭环（Fill Rate Loop）
- 误差：`e_f = f* - f(t)`，采用 30–60 s 滑窗。
- 每 5–10 s 更新：`ΔP ← clip(ΔP - Kp·e_f - Ki·Σe_f, ΔP_min, ΔP_max)`。
- 若成交不足：收紧 `ΔP` 或增加 `N`。
- 若撤单/滑点/自成交偏高：扩大 `ΔP` 或减小 `Q`。
- 初始参数：`Kp=0.2`，`Ki=0.05`，`ΔP_min = S`，`ΔP_max = 4S`。

### 3.3 簿内结构跟随（Orderbook Following）
- 保底：`ΔP ≥ c1 · S`（`c1 ∈ [0.8, 1.2]`），防止太靠近而失去 maker 资格。
- `Q` 与深度相关：`Q ∝ depth₁₋₃`，深度浅 → 降 `Q`/加层，深度深 → 提 `Q`/减层。
- 深度不平衡：`I = (bidDepth - askDepth) / (bidDepth + askDepth)`，仅作为库存闭环的辅助信号。

### 3.4 费用拨盘（Fee Dial）
- 若 maker 返佣 ≥ taker 费：
  - 提高 `f*`，收紧 `ΔP`，加快 `τ`，专注于 maker 成交。
- 若 maker 返佣 < taker 费：
  - 降低 `f*`，放大 `ΔP`，依靠价差弥补成本。
- 永续资金费方向一致时可略微加密当侧，反向则减密。

### 3.5 队列与时延管理（Queue & Latency Loop）
- 追踪各价位的队列位置与更新率：队列过深且替换率低时，上移 1 tick 重挂。
- 撤单失败或链路延迟 > 200 ms，短期内增大 `ΔP`、放慢 `τ`。
- 固化 kill-switch：自成交率 > 0.5%、滑点损失超阈、API 失败率超线等立即降级或停机。

---

## 4. 关键监控指标

| 分类 | 指标 | 说明 |
| --- | --- | --- |
| 库存 | `δ`, `net_position`, `inventory_pnl` | 保持在阈值内 |
| 成交 | `fills/min`, `maker_ratio`, `cancel_ratio` | 驱动 PI 控制 |
| 盘口 | `S`, `depth₁₋₃`, `queue_position` | 决定间距与数量 |
| 费用 | `rebate - fee - slippage`, `funding_pnl` | 验证费用拨盘 |
| 稳定性 | `cancel_latency`, `ws_error_rate`, `rate_limiter_hits` | 用于退避与降级 |

### 4.1 指标计算说明
- `fills/min`：最近 `window` 秒内成交笔数 / `window` × 60（默认 `window=60s`）。
- `maker_ratio`：同期 Maker 成交量 / (Maker+Taker) 成交量。
- `cancel_ratio`：撤单成功次数 / 尝试撤单次数。
- `S`（最优价差）：`bestAsk - bestBid`，按 tick 归一化。
- `depth₁₋₃`：从一级到三级价位的累积挂单数量（按 base 或 quote 选一单位）。
- `queue_position`：同价位挂单中的顺序排名 / 同价位总挂单量。
- `δ`：`abs(net_position) / total_notional`，其中 total_notional 取当前网格所有未成交委托总名义。
- `rebate - fee - slippage`：按成交明细汇总；若 API 未返回实际返佣，需使用费率配置估算。
- `cancel_latency`：`cancel_ack_ts - cancel_submit_ts` 的滑动平均与 95 分位。

---

## 5. 研发任务清单（下一迭代）

### T1. 指标采集与监控
- [ ] 实时输出 `fills/min`、`maker_ratio`、`δ`、`S`、`depth₁₋₃`、`queue_position` 等指标。
- [ ] 新增 Prometheus / 日志埋点，支持滑动窗口统计与告警。
- **交付物**：指标聚合模块、Prometheus exporter、Grafana 面板草稿。
- **实施要点**：复用 `GridMaker.getStatus()`、`globalOrderCoordinator` 与 `ShadowBook` 数据；统计窗口需支持配置与热更新。
- **验收标准**：测试环境连续运行 10 分钟可收集全部指标，Grafana 面板无空白；日志中无指标计算异常。
- **依赖**：若缺少盘口深度/队列信息需扩展 `ShadowBook.snapshot`。

### T2. 库存闭环执⾏器
- [ ] 在 `GridMaker` 中实现库存偏移检测与参数偏置（价格外移、数量缩放）。
- [ ] 实现小额 taker 对冲接口，并设定冷却时间与规模上限。
- **交付物**：库存闭环策略类（含配置）、单元测试、使用示例。
- **实施要点**：在 `buildTargetLevels`/`placeGridOrder` 增加偏置钩子；taker 对冲需调用 `router` 并和风险限额协同。
- **验收标准**：模拟偏仓后 3 个刷新周期内 `δ` 回落到阈值内；日志记录偏置动作和原因。
- **依赖**：依赖 T1 指标输出与 taker 下单通道。

### T3. 成交率 PI 控制
- [ ] 构建 `fills/min` 滑窗统计。
- [ ] 设计可配置的 `Kp/Ki/ΔP_min/ΔP_max`，驱动 `ΔP` 与 `N` 自动调整。
- [ ] 为闭环添加限幅、死区与恢复逻辑，避免高频震荡。
- **交付物**：PI 控制器模块、参数配置项、仿真脚本。
- **实施要点**：支持 Anti-windup，避免与库存闭环互相抵消；输出动作需节流。
- **验收标准**：回放环境中 `fills/min` 偏差 < 10%，`ΔP` 收敛无明显震荡；真实跑 30 分钟指标稳定。
- **依赖**：依赖 T1 与 T2 的输出。

### T4. 簿内结构跟随
- [ ] 实现对 1–3 档深度的采样与归一化、以及临时的 `ΔP`/`Q` 调整策略。
- [ ] 在日志中记录调节原因（深度不足/过深/不平衡）。
- **交付物**：深度采样器、数量调节函数、调节日志。
- **实施要点**：设计深度不足时的 fallback；与库存闭环共享权重，避免过度偏移。
- **验收标准**：手动调整深度后 2 个周期内 `Q` 改变且日志包含调节原因。
- **依赖**：依赖 T1 输出深度指标。

### T5. 费用拨盘模块
- [ ] 统一处理 maker 返佣、taker 费率、资金费率，计算净费用。
- [ ] 根据净费用结果调整 `f*` 与刷新节奏 `τ`。
- [ ] 配置化阈值与开关，便于在不同交易所复用。
- **交付物**：费用模型组件、配置项、单元测试。
- **实施要点**：支持返佣估算、资金费率滚动更新；与成交率闭环共享 `f*`。
- **验收标准**：在费用为正/负两种场景下，系统能自动调节目标成交率并输出动作日志。
- **依赖**：依赖 T1 费用指标和 T3 控制接口。

### T6. 队列位置与退避
- [ ] 记录各价位队列排名与订单替换率。
- [ ] 若排位靠后且替换率低，自动上移重挂。
- [ ] 与 rate-limit/backoff 机制整合，避免无限重试。
- **交付物**：队列跟踪器、退避策略、参数配置。
- **实施要点**：需要交易所提供队列数据或本地估算；与现有撤单退避逻辑整合。
- **验收标准**：模拟队列拥堵时自动调整价位且 rate limiter 命中率不升高。
- **依赖**：依赖 T1/T3 指标、现有 rate-limit 组件。

### T7. 安全边界与 Kill-Switch
- [ ] 新增自成交率、滑点损失、API 失败率等阈值与触发动作。
- [ ] 与风险模块协作，确保触发后能优雅降级或停机。
- **交付物**：安全阈值配置、kill-switch 流程、集成测试。
- **实施要点**：触发动作需幂等可回退；与 `risk` 模块共享状态。
- **验收标准**：模拟超阈事件后系统自动降级/停机并有清晰告警。
- **依赖**：依赖 T1 指标、T2/T3 控制接口。

---

## 6. 后续工作流建议

1. **文档固化**：将本文件纳入产品/技术设计基线，供团队讨论与复审。
2. **Roadmap 拆解**：依据任务列表在 issue tracker 中建立对应条目，明确负责人与优先级。
3. **里程碑划分**：先实现 T1–T3（最关键闭环），随后推进簿内结构、费用拨盘与队列管理。
4. **验证计划**：在模拟或小资金环境中对各闭环逐一验收，记录 KPI 变化并校准参数。

### 6.1 里程碑规划示例

| 里程碑 | 范围 | 预计周期 | 验收要点 |
| --- | --- | --- | --- |
| M1：Telemetry 基线 | 完成 T1 指标采集、Grafana 面板、报警规则 | 1 sprint | 指标齐全，报警触发有效 |
| M2：核心闭环上线 | 部署 T2/T3，实现库存与成交率自调 | 1–2 sprint | `δ` 自动回归阈值，`fills/min` 收敛 |
| M3：结构/费用调节 | 上线 T4/T5，完成深度跟随与费用拨盘 | 1 sprint | 深度变动有响应，费用拨盘动作记录完整 |
| M4：稳定性收尾 | 上线 T6/T7，与风险/退避逻辑整合 | 1 sprint | 队列退避有效、kill-switch 验证通过 |

---

## 7. 验证与回归 Checklist
- [ ] **仿真回放**：至少两段历史行情（常规/剧烈）跑全策略，记录 `δ`、`fills/min` 收敛过程。
- [ ] **沙盒演练**：在低资金环境连续运行 ≥24h，确认五大闭环均有触发与恢复。
- [ ] **费用对账**：对照交易所返佣/手续费/资金费率账单，验证费用拨盘判断。
- [ ] **Kill-switch 演练**：模拟 API 失败、自成交异常、滑点爆表等，确保系统降级或停机。
- [ ] **日志审计**：所有闭环动作具备结构化日志（含原因、参数、结果），支持事后回溯。
- [ ] **监控报警**：Grafana/Alertmanager 配置库存、成交率、延迟、API 错误等报警，并经过一次演练。

---

## 8. 数据与基础设施需求

| 模块 | 需求内容 | 目前状态 | 备注 |
| --- | --- | --- | --- |
| 行情数据 | 实时 L2 盘口、成交推送、资金费率 | `ShadowBook` 已支撑 L2，需补齐队列位置 | 若交易所暂不提供队列数据，需研发本地估算 |
| 指标存储 | 时序数据库（Prometheus）与报警 | 待建设 | 评估是否重用现有监控平台 |
| 仿真环境 | 历史回放、事件驱动模拟 | 部分回放脚本 | 需要支持滑窗指标钩子与闭环控制注入 |
| 配置管理 | 支持热更新、环境隔离 | `config.yaml` 基础完成 | 后续考虑拆成模块化配置 |
| 风险系统 | Kill-switch、限额协同 | 风险模块已存在 | T7 集成时需扩充接口 |

基础设施优先级：**Prometheus + Grafana (P0)** → **历史仿真工具 (P1)** → **队列数据/估算 (P1)** → **配置热更新 (P2)**。

---

## 9. 参数配置示例（草案）

```yaml
grid_control:
  fills_per_min_target: 30
  maker_ratio_target: 0.85
  inventory:
    delta_max_pct: 0.015
    delta_recover_pct: 0.0075
    price_bias_ticks: 2
    qty_scale_on_bias: 0.7
    taker_hedge:
      enabled: true
      max_notional_usd: 200
      cooldown_ms: 60000
  fill_rate_pi:
    kp: 0.2
    ki: 0.05
    dp_min_multiplier: 1.0   # × S
    dp_max_multiplier: 4.0
    smoothing_window_sec: 60
    deadband_fills_per_min: 2
  depth_following:
    min_depth_ratio: 0.3
    max_depth_ratio: 1.5
    rebalance_interval_ms: 5000
  fee_dial:
    maker_rebate_bps: 2.0
    taker_fee_bps: 1.5
    funding_weight: 0.5
    tighten_threshold_bps: 0.3
    loosen_threshold_bps: -0.2
  queue_management:
    max_queue_percent: 0.6
    low_turnover_threshold: 0.1
    retry_backoff_ms: 300
  safety:
    max_self_trade_ratio_pct: 0.5
    max_slippage_loss_usd_per_min: 50
    api_error_threshold_pct: 3
```

> 上述参数仅供参考，落地时需结合交易所费率、资金规模进行校准。

---

## 10. 未决事项与风险清单

1. **队列位置数据缺失**：若交易所无法提供精确排名，需评估本地估算准确度；直接影响 T6 实施。
2. **返佣/费用实时性**：部分交易所返佣是日结，需要临时估算；若误差大可能导致费用拨盘误判。
3. **仿真数据稀缺**：缺少历史深度与成交数据会降低闭环调参效率；需优先搜集或外部采购。
4. **多标的协同**：当前框架默认单一标的，扩展到多币对时需考虑共享库存限额与风险敞口。
5. **策略切换兼容性**：与 scalper/mm 的共存策略尚未定义，需在后续版本评估资源争抢与风险隔离。
6. **Kill-switch 责任划分**：触发后由风控、交易还是服务治理模块接管？需要跨团队对齐。
7. **性能上线**：控制循环频率（5s）可能带来额外 CPU/IO 压力，需在 Bench 中确认无瓶颈。

---

若需讨论或补充，请在 PR/Issue 中引用本文件并注明章节。欢迎对控制逻辑与参数提出进一步优化建议。
