grid_skeleton/docs/MICRO_GRID_CONTROL.md

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

目标：在“未知趋势、上下 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. 参数配置示例（草案）

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 中引用本文件并注明章节。欢迎对控制逻辑与参数提出进一步优化建议。