English

简体中文

Poly Maker 代码导览与扩展手册

这份文档把你当成刚接触这个仓库的人来写。目标不是让你马上记住每一行代码，而是让你知道：

• 程序从哪里启动。
• 每个目录负责什么。
• 每个文件、类、函数大概做什么。
• 想加某个功能时应该改哪里。
• 后续做方向预测、机器学习、实时优化时，从哪里开始最稳。

1. 一句话理解这个项目

这是一个 Polymarket 做市机器人。它会定期读取目标市场 YES/NO 两个 token 的盘口、持仓、最近成交和奖励信息，然后用一个短期预测器估计 fair price，再生成 GTC + Post-only 挂单，最后通过 Polymarket CLOB API 下单、撤单和同步订单。

核心主路径是：

graph TD
    A[main.py] --> B[BotConfig 读取 .env]
    B --> C[PolymarketAdapter 连接]
    C --> D[MarketMaker.bootstrap 初始化]
    D --> E[MarketMaker.tick 循环]
    E --> F(AdvancedPredictor 预测)
    E --> G(QuoteEngine 报价)
    E --> H(OrderReconciler 同步)
    E --> I(PolymarketAdapter 交易)
    E --> J(DataRecorder 记录)

2. 目录总览

.
├── main.py                         # 主入口
├── config.py                       # .env 配置读取与校验
├── market_maker.py                 # 做市策略主循环
├── polymarket_adapter.py           # Polymarket API 适配层
├── quote_engine.py                 # 报价引擎
├── emergency_exit.py               # 紧急 maker 退出逻辑
├── order_reconciler.py             # GTC 订单同步/保留队列位置
├── predictors.py                   # 基础预测接口
├── advanced_predictors.py          # 当前使用的增强预测器
├── data_recorder.py                # 每轮行情/预测/持仓数据记录
├── docs/                           # 文档网站文件
├── tests/                          # 单元测试
└── ...

3. 核心文件详解

• main.py: 程序入口，负责启动配置、日志、API adapter 和 MarketMaker。
• config.py: 把 .env 里的字符串变成程序可用的配置对象。
• polymarket_adapter.py: 把 Polymarket SDK/API 包一层，主策略不直接碰 SDK 细节。
• market_maker.py: 策略主循环。它决定每一轮看什么数据、做什么预测、挂什么单、什么时候停。
• advanced_predictors.py: 当前主策略实际使用的增强预测器。
• quote_engine.py: 把预测 fair value 变成实际可挂的 maker-safe limit price。
• order_reconciler.py: GTC 挂单不要每轮无脑撤换。它会比较目标订单和 live open orders，尽量保留不变的订单队列位置。
• emergency_exit.py: 模块化处理“已有 YES/NO 持仓突然逆向时，尽快用 maker 挂单退出”的逻辑。
• data_recorder.py: 异步写 CSV，记录每轮行情、预测和持仓数据。