概覽
策略庫
文件
學習

工作區結構

了解 Blave Agent 工作區的每個檔案與資料夾。

目錄總覽

workspace/
├── strategies/          # 你的策略
├── examples/            # 範例策略（參考用）
├── lib/                 # 共用函式庫
├── manager/             # 投組管理系統
├── cache/               # API 資料快取（自動產生）
├── references/          # 策略撰寫與部署指南
└── AGENTS.md            # Bot 行為規範

strategies/

每個策略放在自己的子資料夾。Bot 依 cron 排程執行 strategy.py，並自動寫入輸出檔案。

strategies/
└── my_strategy/
    ├── strategy.py      # 策略邏輯
    ├── scan.py          # 參數掃描（選用）
    ├── stats.json       # 回測結果 + 每日報酬
    ├── state.json       # 即時倉位狀態
    ├── pnl.png          # 資金曲線圖
    └── orders.jsonl     # 下單紀錄

lib/

所有共用工具都在 lib/。從這裡 import，不要在策略檔中重複實作。

檔案用途
runner.py統一回測與即時執行器（Type A 與 C）
data.py所有資料抓取——K 線、Alpha 指標、台股、期貨
execute.py即時狀態管理：載入/儲存/更新倉位、下單紀錄
pnl.py將每日報酬寫入 stats.json；為 manager 載入所有策略
portfolio.py彙整目標倉位、計算差值、執行 reconcile
strategy.py波動率 targeting 工具：add_realized_vol、apply_vol_scaling
analysis.pyPnL 圖表、市場狀態分析、滑點分析、隨機 B&H 基準
param_scan.py2D 參數掃描：percentile_thresholds、scan_grid、find_plateau、plot_heatmap
validation.py蒙地卡羅置換檢定（mcpt）—— 驗證策略統計顯著性
notify.pyTelegram 發送：make_sender()、send_text()、send_photo()

manager/

manager/ 負責多策略投組優化與訂單調倉。刪除個別策略時，不要動這個資料夾。

檔案用途
manager.py讀取所有策略的 stats.json，找出讓投組 slope/std 最大的配重，並將最佳配重與槓桿寫入 portfolio_config.json。
執行：python3 manager/manager.py --target-vol 0.30
reconciler.py每 5 秒輪詢一次；策略 state.json、下單金額或下單開關變動時對帳（每 5 分鐘另有保底輪），下單抹平目標與實際部位的差額。
執行：bash manager/start_reconciler.sh
flatten.py把所有已串接交易所的持倉全部市價平掉（工作區「全部平倉」按鈕跑的就是它）。執行前會先掛上下單開關，平倉後不會再開新倉。
執行：python3 manager/flatten.py
portfolio_config.json每個策略的下單金額（實盤倉位計算基準）、交易所路由，以及優化器的配重與槓桿。一律由工具維護——絕不手改。
orders.jsonl交易歷史——每筆已執行訂單一行，逐腿記錄交易所回報的成交價與數量。工作區「交易歷史」分頁讀的就是這個檔。
金額與配重：優化器的配重與槓桿是建議配置；真正決定實盤倉位的是每個策略的下單金額（target = amount × position），從工作區「下單設定」頁儲存。

資料流

strategy.py ──► state.json ──────────┐
   (cron)       stats.json           ├──► reconciler.py ──► exchange
manager.py ──► portfolio_config.json ┘

Reconciler 同時需要兩個來源才能算出下單金額：target = amount × position