grid_skeleton

Pacifica Delta-Neutral + Dual-Sided Scalping — TS Skeleton

Overview

本仓库提供一个面向 Pacifica 永续合约的多账户 Delta 中性策略骨架，涵盖连接器、执行路由、风控、策略、行情管线和监控模块，便于快速验证网格/剥头皮等中性策略。

核心模块：

• connectors：Pacifica REST/WebSocket 适配器、签名、限频/指标、账户注册表
• utils：ShadowBook、MarketDataAdapter 等行情聚合工具
• execution：OrderRouter（滑点、post-only、节流、STP）与 GlobalOrderCoordinator
• risk / portfolio / hedge：RiskEngine（kill-switch）、PositionManager、HedgeEngine、FundingRateMonitor
• strategies：GridMaker、MarketMaker、MicroScalper
• apps/runner：加载配置、注册账户、启动策略与风险/行情管线

Quick Start

pnpm install
cp .env.example .env
cp config/config.example.yaml config/config.yaml
pnpm run live        # 正常启动
# 常用检查
pnpm lint
pnpm test
pnpm typecheck

Logging

• Runner 默认使用 pino 结构化日志，除标准输出外，还会写入 logs/runner-<timestamp>.log（目录自动创建）。启动时会在控制台打印实际 log 文件路径，便于后续复盘。
• 可用环境变量定制行为：
  • LOG_DIR：日志目录（默认 logs，仅在 LOG_FILE 未指定时生效）
  • LOG_FILE：自定义日志文件（接受相对或绝对路径）
  • LOG_FILE_LEVEL：写入文件的最低级别（默认跟随 LOG_LEVEL，例如设置 debug 捕获全量明细）
• 结构化日志可以直接供 Codex 或外部工具重放，建议在本地调试时保留原始 JSON，必要时再结合 pino-pretty 做人类可读打印。

Docs-first Workflow

• 开发前务必查阅并遵循：docs/ARCHITECTURE_DESIGN.md, docs/IMPLEMENTATION_PLAN.md, docs/CODE_DELIVERY_PLAN.md, docs/API_CONNECTOR_SPEC.md, docs/MODULE_INTERFACES.md, docs/SEQUENCE_FLOW.md, docs/CONFIG_REFERENCE.md, docs/TESTING_PLAN.md, docs/OPERATIONS_PLAYBOOK.md, docs/MICRO_GRID_CONTROL.md, docs/MICRO_GRID_ROADMAP.md
• 若实现与文档不一致，先更新文档再提交代码，并在 PR 描述说明差异。
• PR 模板要求列出引用章节与测试结果，CI 应覆盖 pnpm lint / pnpm test / pnpm typecheck。

Codex 准则

1. 以暗猜接口为耻，以认真查阅为荣
   
2. 以模糊执行为耻，以寻求确认为荣
   
3. 以盲想业务为耻，以人类确认为荣
   
4. 以创造接口为耻，以复用现有为荣
   
5. 以跳过验证为耻，以主动测试为荣
   
6. 以破坏架构为耻，以遵循规范为荣
   
7. 以假装理解为耻，以诚实无知为荣
   
8. 以盲目修改为耻，以谨慎重构为荣

Reference Documentation

• 快速上手：docs/CONFIG_GUIDE.md
• 架构与规划：docs/ARCHITECTURE_DESIGN.md, docs/IMPLEMENTATION_PLAN.md, docs/MICRO_GRID_CONTROL.md, docs/MICRO_GRID_ROADMAP.md, docs/MICRO_GRID_EXECUTION_SCHEDULE.md
• 接口规范：docs/API_CONNECTOR_SPEC.md, docs/MODULE_INTERFACES.md
• 流程与配置：docs/SEQUENCE_FLOW.md, docs/CONFIG_REFERENCE.md
• 质量保障与运维：docs/TESTING_PLAN.md, docs/OPERATIONS_PLAYBOOK.md
• 即将到来的 M1.6 设计：docs/M16_INCREMENTAL_GRID_DESIGN.md, docs/M16_PLACEMENT_THROTTLING_DESIGN.md, docs/M16_FILL_DRIVEN_TIGHTENING_DESIGN.md
• 历史资料：见 docs/archive/

Tests

• 单元测试位于 tests/ 目录，使用 Vitest (pnpm test)
• pnpm lint 运行 ESLint (@typescript-eslint)，pnpm typecheck 执行 tsc --noEmit
• 建议在 PR 中附测试日志与关键指标（REST 请求指标、delta_abs、kill-switch 状态等）

Notes

• 运行前需在 .env 中填写 Pacifica API 密钥，config/config.yaml 例子说明账户、策略、风险、执行等参数
• AdapterRegistry 支持 maker/hedger 多账户，Residence of funding 监控通过 FundingRateMonitor
• TODO（见计划）：接入真实 WS 行情、完善资金费率管线、补充更多单测/集成测试