QuantDinger 實戰手冊｜開源 AI 交易作業系統 — 策略、回測、實盤與 MCP

01這是什麼

不是訊號服務，是自託管的交易作業系統。

QuantDinger 解決的是量化交易者在雲端服務與黑盒子訊號之間的兩難：行情、策略程式碼、券商憑證、回測與實盤狀態全部分散，且難以審計。專案把研究、編碼、驗證、執行與監控收斂到同一個本地優先堆疊，操作者持有資料與部署主導權。

核心是一個可攜的 Python 合約。圖表指標僅負責視覺化，Strategy API V2 才是唯一可執行的策略介面：原始碼擁有市場、標的、頻率、排程、風險與槓桿設定，編譯器產生 manifest，回測與實盤共用同一份定義，無須重寫。

執行面以行程邊界隔離長週期與有限任務。HTTP API 只做驗證與委派；trading-worker 擁有策略運行時與待處理訂單；scheduler-worker 負責投資組合、部署與訊號排程；celery-worker 處理有限可重試工作；快取 Redis 與任務 Redis 分離實例與淘汰策略，避免相互干擾。

AI 研究
策略撰寫
回測驗證
模擬 / 實盤
監控與稽核

面向	涵蓋內容
市場	加密貨幣（Binance、OKX、Bitget、Bybit、Gate、HTX 等）、美股、港股、A 股、外匯；行情、因子、新聞與總體資料聚合
策略介面	指標（圖表覆蓋、標記、區間）與 Strategy API V2（`initialize / handle_data / on_rebalance`、訂單意圖、風控與帳務）分離
執行	伺服器端回測、實驗流程、紙上交易與實盤、訂單對帳、券商適配器（Crypto 與 IBKR / Alpaca）
存取	桌面 Web、行動 H5、Human API、Agent Gateway（`/api/agent/v1`）、MCP 伺服器
營運	PostgreSQL 狀態、雙 Redis、可觀測性疊加（Prometheus / Grafana / Alertmanager）、JSON 日誌與審計軌跡

AI research → Strategy code → Backtest → Paper / Live execution → Monitoring

— QuantDinger README · 產品閉環定義

02安裝

一行指令啟動，或從原始碼自建。

預設以 Docker Compose 交付，不需本機 Python 或 Node。兩條路徑：選項 A 拉取 GHCR 預建映像一鍵啟動；選項 B 從原始碼建置以便二次開發。兩者皆在 127.0.0.1 曝露服務，生產環境需以 TLS 反向代理收斂至 80/443。

選項 A · 預建映像（最快）

Linux / macOS 執行安裝腳本，Windows 以 PowerShell 執行對應版本。腳本會詢問初始管理員帳密、產生必要密鑰、下載 GHCR Compose 堆疊並啟動。

# 一鍵安裝並啟動
curl -fsSL https://raw.githubusercontent.com/OpenByteInc/QuantDinger/main/install.sh | bash

# Windows PowerShell
irm https://raw.githubusercontent.com/OpenByteInc/QuantDinger/main/install.ps1 | iex

啟動後開啟：http://127.0.0.1:8888（桌面 Web）、http://127.0.0.1:8889（行動 H5）、http://127.0.0.1:5000/api/health（後端健康檢查）。桌面與行動前端為獨立倉庫的 GHCR 映像，本倉僅消費其發布物。

選項 B · 從原始碼啟動

適合需修改後端、適配器或任務的情境。複製環境範本、填入生產密鑰、建置並啟動核心堆疊。

git clone https://github.com/OpenByteInc/QuantDinger.git
cd QuantDinger
cp backend_api_python/env.example backend_api_python/.env
cp .env.example .env
# 編輯兩份 .env：填入 SECRET_KEY、CREDENTIAL_ENCRYPTION_KEY、ADMIN_USER / ADMIN_PASSWORD、POSTGRES / REDIS 密碼
python -c "import secrets; print(secrets.token_hex(32))"  # 產生獨立隨機密鑰
docker compose up -d --build
docker compose ps

生產疊加與可觀測性

上線前驗證組態，疊加 hardened 與可選監控：

python backend_api_python/scripts/check_production_config.py \
  --env-file .env --env-file backend_api_python/.env

docker compose \
  -f docker-compose.yml \
  -f docker-compose.production.yml \
  -f docker-compose.observability.yml \
  up -d --build
# 僅加可觀測性（不加 hardened）
docker compose -f docker-compose.yml -f docker-compose.observability.yml up -d

03能力總覽

策略、行情、執行與 Agent 工具箱。

QuantDinger 的能力沿三條邊界組織：策略合約定義可做什麼，執行與資料適配器決定如何落地，Agent Gateway 與 MCP 把同一套能力以機器可用的方式曝露。所有可變操作皆以冪等鍵與範圍化授權保護。

Strategy · V2

Strategy API V2

唯一可執行的策略合約

以 initialize(context) 宣告標的與訂閱，handle_data / on_rebalance / schedule 實現邏輯。編譯器產出 manifest，統一回測與實盤的標的、頻率與風控。

Visual · 01

Indicators

僅用於圖表分析

Python 指標在 IDE 中讀取 K 線 DataFrame，輸出 plots / signals / layers。不可下單、回測或讀取帳務；交易需轉譯為 Strategy API V2。

Research · 02

Universe & Factors

時點正確的研究輸入

公開股票池、時點因子與基本面依賴納入 manifest，與回測保持一致，避免前視偏差。

Execution · 03

Backtest Engine

伺服器端回測與實驗

以 manifest 為準的非同步任務，支援日期、初始資金、成本與參數；透過 /jobs/{id} 輪詢或 SSE 串流取得結果。

Execution · 04

Trading Workers

長週期實盤擁有權

策略運行時、待處理訂單、券商會話與對帳由 trading-worker 以租約、心跳與圍欄令牌持有，不由 HTTP 行程持有。

Adapters · 05

Crypto Exchanges

多所交易所歸一

Binance、OKX、Bitget、Bybit、Gate、HTX 等透過 app/services/live_trading 歸一為下單與帳務合約，支援擴充適配器。

Adapters · 06

IBKR / Alpaca

傳統券商工作流

互動經紀商與 Alpaca 的帳戶、持倉與委託流程獨立封裝，憑證加密儲存，交易可審計。

Data · 07

Market Data Stack

行情與聚合層

data_sources 接原始 K 線與報價，data_providers 聚合大盤、總體、新聞與情緒，快取鍵含市場、交易所、標的、週期與數量。

AI · 08

Multi-Agent Research

多提供者的市場研究

支援 OpenRouter、OpenAI 相容、Google、DeepSeek、Grok、MiniMax 與自訂端點，用於研究與策略輔助生成。

Agent · 09

Agent Gateway

`/api/agent/v1` 機器介面

租戶範圍的 Token 以 R / W / B / N / T / C 劃分能力，附市場與標的白名單、速率限制、有效期與紙上交易限制。每個可變請求需 Idempotency-Key。

MCP · 10

quantdinger-mcp

給 Cursor / Claude Code 的MCP 包裝

以 pip install quantdinger-mcp 取得，預設 stdio，支援 SSE / streamable-http。工具涵蓋行情、指標、策略編譯與部署、回測任務、帳務觀測與受控下單。

Ops · 11

Observability

可選的監控疊加

Prometheus 採集 API 與 Worker 指標，Grafana 儀表板，Alertmanager 分組與告警。預設不啟動，需疊加 docker-compose.observability.yml。

該走哪條路徑？一張表決定

你想做什麼	用什麼	關鍵約束
畫一條均線或標記訊號	Indicator IDE（`output` 合約）	不可下單或回測；需轉為 Strategy API V2 才能交易
驗證交易邏輯是否有效	Strategy API V2 + 伺服器端回測	標的與週期由 manifest 決定，非回測參數
讓策略自動運行	儲存 source → 建立 stopped deployment → 啟動	新部署預設停止；槓桿僅限 Crypto 合約
用 AI 編碼助手操作	Agent Gateway / MCP（`quantdinger-mcp`）	依 `R/W/B/N/T` 範圍授權，實盤需多重確認

04官方原則 · 架構守則

先懂邊界，再擴充功能。

QuantDinger v5 的重構主軸是明確的行程與模組邊界。下列原則直接來自架構與流程文件，改動前先對照，避免把長週期行為塞進 HTTP 行程或把交換所邏輯混入路由。

PRINCIPLE 01 · HTTP 只做驗證與委派

路由保持薄層：解析輸入、驗證權限、呼叫服務、映射回應。交易迴圈、排程與大量 DB 工作一律下沉至 Worker 或服務層。

來源 · docs/architecture/ARCHITECTURE.md · Route Rules

PRINCIPLE 02 · 長週期歸 trading-worker

策略運行時、待處理訂單與券商會話由 trading-worker 持有；有限可重試工作歸 Celery。可撤銷的長時間迴圈不屬於 HTTP。

來源 · docs/architecture/PROCESS_ROLES_AND_TASKS.md

PRINCIPLE 03 · 雙 Redis 各司其職

快取 Redis 與任務 Redis 分離實例與淘汰策略。前者可拋棄，後者需持久化；禁止將快取 Redis 作為 Celery broker。

來源 · README · What changed in v5

PRINCIPLE 04 · Manifest 擁有交易事實

市場、標的、頻率、依賴、暖機與槓桿許可由 Strategy API V2 編譯出的 manifest 決定。回測與部署不得以參數覆寫原始碼事實。

來源 · docs/trading/STRATEGY_DEV_GUIDE.md

PRINCIPLE 05 · 指標與策略切分

指標輸出 plots / signals / layers 僅作圖，不可下單或回測。交易想法需轉譯為 Strategy API V2 再驗證與部署。

來源 · docs/trading/INDICATOR_DEV_GUIDE.md

PRINCIPLE 06 · 適配器保持無知

交易所與券商適配器僅歸一第三方 API 為平台合約，不感知使用者、JWT 或前端文案；業務層決定錯誤是否可重試或需面向使用者。

來源 · docs/architecture/ARCHITECTURE.md · Adapter Rules

PRINCIPLE 07 · Agent 能力範圍化

Agent Token 以 R/W/B/N/T 劃分讀、寫、回測、通知與交易能力，附白名單與名目金額上限；實盤需同時滿足 Token、伺服器開關與操作者授權。

來源 · docs/agent/AGENT_QUICKSTART.md

PRINCIPLE 08 · 冪等與審計

所有可變的 W/B/N/T 操作需客戶端產生 Idempotency-Key，重試必須重用同一鍵；緊急停止會撤銷租戶全部 T 範圍 Token 並需人工覆核交換所失敗。

來源 · docs/agent/AGENT_QUICKSTART.md · docs/agent/MCP_SETUP.md

05使用實例

從 MCP 指令到回測與部署的完整路徑。

以一個可驗證的端到端流程示範：透過 Agent Gateway / MCP 建立 SPY 均線策略、編譯與儲存、發起回測、建立停止狀態的部署。下述指令對應真實工具與端點，憑證與金鑰以環境變數注入，未在日誌或提示中明文出現。



# 1 — 準備 MCP 連線（stdio，後端已在 127.0.0.1:8888 運行）
$ export QUANTDINGER_BASE_URL=http://localhost:8888
$ export QUANTDINGER_AGENT_TOKEN=$QD_AGENT_RWBT
$ pip install "quantdinger-mcp==0.5.0" && quantdinger-mcp
# [mcp] stdio ready · tools: whoami, compile_strategy_code, save_strategy_source, submit_backtest …


# 2 — 驗證身份與權限
$ whoami
# { "tenant": "lab", "scopes": "R/W/B/T", "paper_only": true, "allowlist": ["USStock:*","Crypto:*@spot"] }


# 3 — 編譯 Strategy API V2（最小可執行範例，來自官方 Strategy Guide）
$ compile_strategy_code(code="\"\"\"SPY 20-Day MA … initialize/handle_data …\"\"\"")
# { "valid": true, "manifest": { "api_version": "V2", "universe": ["USStock:SPY"], "frequency": "1d", "warmup": 120, "leverage": false } }


# 4 — 儲存為私有 source（需冪等鍵）
$ save_strategy_source(name="spy-20ma", code="...", idempotency_key="src-spy-20ma-v1")
# { "source_id": 12, "version": 1, "manifest": { "benchmark": "USStock:SPY", "subscriptions": ["1d"] } }


# 5 — 以同一份程式碼發起回測（B 範圍，SSE 或輪詢）
$ submit_backtest(code="...", start_date="2025-01-01", end_date="2025-12-31", initial_capital=10000, params={"period":20}, idempotency_key="bt-spy-20ma-2025")
# { "job_id": "bt_9f3a", "status": "queued" }
$ wait_for_job(job_id="bt_9f3a")
# { "status": "completed", "metrics": { "return": "…", "max_drawdown": "…", "trades": "…" }, "artifacts": ["equity.csv","trades.csv"] }
# 或 curl 直連 Agent Gateway
> curl -H "Authorization: Bearer $QUANTDINGER_AGENT_TOKEN" -H "Idempotency-Key: bt-spy-20ma-2025" \
  > -d '{"code":"...","startDate":"2025-01-01","endDate":"2025-12-31","initialCapital":10000}' \
  > http://localhost:8888/api/agent/v1/backtest/run


# 6 — 建立停止狀態的部署（W 範圍，需 sourceId）
$ create_strategy(name="spy-trend", source_id=12, initial_capital=10000, execution_mode="signal", params={"period":20}, idempotency_key="deploy-spy-trend-v1")
# { "id": 7, "status": "stopped", "source_id": 12, "execution_mode": "signal" }
# 人工在 Web 確認風控與權限後再啟動；T 範圍可 stop / kill-switch


# 7 — 觀測與風控
$ runtime_overview
# { "strategies": 1, "open_paper_orders": 0, "workers": {"trading": "healthy", "scheduler": "healthy"} }
$ place_quick_order  # 需 confirm_order=true，實盤另需 confirm_live_trading=true
# [guarded] paper_only=true · max_order_notional / max_daily_notional enforced

"""SPY 20-Day Moving Average — 官方 Strategy Guide 最小可執行範例"""
# @param period int 20 range=5:100:5
# @param target_pct float 0.95 range=0.1:1.0:0.05

def initialize(context):
    g.symbol = "USStock:SPY"
    context.set_universe([g.symbol])
    context.subscribe(frequency="1d", fields=["open","high","low","close","volume"])
    context.set_warmup(120)
    context.set_benchmark("USStock:SPY")

def handle_data(context, data):
    # get_history(count, frequency, field, symbol) — count 在前
    bars = get_history(21, "1d", "close", g.symbol)
    if len(bars) < 20: return
    price = float(bars["close"].iloc[-1])
    avg = float(bars["close"].tail(20).mean())
    pos = get_position(g.symbol)
    desired = 0.95 if price > avg else 0.0
    if desired > 0 and pos.amount <= 0:
        order_target_percent(g.symbol, desired, reason="ma_long_entry", stop_loss_pct=0.05)
    elif desired == 0 and pos.amount > 0:
        order_target_percent(g.symbol, 0.0, reason="ma_long_exit")

The source owns its market, instruments, frequency, schedules, and trading logic. Run forms provide dates, initial capital, costs, and user params; they do not override source-controlled markets.

— docs/trading/STRATEGY_DEV_GUIDE.md · 編譯器擁有權規則

這段流程為何值得拆解

同一份 Strategy API V2 原始碼貫穿編譯、回測與部署，消除了「回測時一套邏輯、上線時另一套」的常見漂移。MCP 與 Agent Gateway 復用同一條服務層，機器與人工共用風控與稽核，而非繞過。

新部署一律為 stopped，啟動需額外授權與確認；實盤更需同時滿足 Token 能力、伺服器開關、憑證白名單與金額上限。這種多層門檻是刻意設計，讓自動化保持可撤銷。

06先看清楚這些

不是銀彈。知道邊界再上路。

警告

**實盤會下真單。**啟用實盤即可能送出真實委託。先以紙上交易驗證邏輯、使用最小權限的 API Key，並確認所在司法管轄區的合規與稅務要求。專案不提供投資建議。
**不要把指標當策略。**指標僅輸出圖表，無法下單或回測。交易前必須轉譯為 Strategy API V2，經 POST /api/strategies/verify 編譯驗證，並以回測確認行為。
**Manifest 不可繞過。**市場、標的、週期、因子依賴與槓桿許可由原始碼與 manifest 決定。回測與部署的表單僅提供日期、資金與參數，不得覆寫標的事實；槓桿僅限 Crypto 合約。
**憑證與密鑰管理。**券商憑證以 CREDENTIAL_ENCRYPTION_KEY 加密，Agent Token 為雜湊儲存。遺失 CREDENTIAL_ENCRYPTION_KEY 將無法解密既有憑證；切勿將 Token 或密鑰提交至版本控制或日誌。
**生產環境隔離。**僅對外曝露 TLS 反向代理的 80/443；PostgreSQL、雙 Redis、Prometheus、Grafana、Alertmanager 預設僅綁 127.0.0.1，不得直接曝露。生產疊加採非 root、唯讀根檔案系統與資源限制。
**冪等與撤銷成本。**所有可變 W/B/N/T 請求需附 Idempotency-Key，重試必須重用同一鍵。緊急停止（/quick-trade/kill-switch 或 emergency_stop_trading）會撤銷租戶全部 T 權杖並嘗試撤單，交換所的撤單失敗需人工覆核。
**版本與資料一致性。**原始碼版本以 VERSION 為準，Git 標籤為 v5.x.y。回測歷史不保證未來表現；AI 輸出與範例策略僅供研究，需自行覆核風險控管與委託限制。
**資源與相依。**後端需求為 Python 3.12、PostgreSQL 18、Redis 8 與 Docker Compose v2。大量回測與多策略並行會顯著增加 CPU、記憶體與儲存消耗；監控疊加為可選，需評估主機資源。

07進階路徑

把範例變成你的策略。

QuantDinger 的擴充點圍繞適配器、任務與路由展開。新增能力時，先確認所屬行程與模組邊界，再落到對應目錄。

進階地圖

**1. 開發你的第一個可交易策略。**以 docs/trading/STRATEGY_DEV_GUIDE.md 的最小範例為起點，在策略 IDE 中以 initialize 與 handle_data 建立邏輯，經 /api/strategies/verify 驗證 manifest，完成回測後再建立部署。

**2. 接入新的交易所或券商。**在 backend_api_python/app/services/live_trading（或對應券商套件）新增歸一適配器，保持錯誤處理貼近適配器、業務判斷留在服務層，並補上憑證策略與測試。

**3. 擴充行情或聚合資料。**原始行情在 app/data_sources，聚合與快取在 app/data_providers；快取鍵需含市場、交易所、標的、週期與數量，避免結果錯用。

**4. 以 MCP 自動化研究與部署。**透過 quantdinger-mcp 的 list_markets / search_symbols / get_klines 探勘標的，以 compile_strategy_code → save_strategy_source → submit_backtest → create_strategy 完成機器化工作流。

**5. 強化營運。**疊加 docker-compose.observability.yml 啟用 Prometheus / Grafana / Alertmanager；生產環境疊加 docker-compose.production.yml，並依 docs/deployment/PRODUCTION_HARDENING.md 完成檢查清單。

最該讀的三份文件

① docs/architecture/ARCHITECTURE.md —— 後端擁有權地圖與貢獻設計規則。 ② docs/trading/STRATEGY_DEV_GUIDE.md —— Strategy API V2 完整合約與編譯器規則。 ③ docs/agent/MCP_SETUP.md —— MCP 伺服器安裝、傳輸與安全邊界。

QuantDinger is a product of Open Byte Inc. The name, logo, product identity, and commercial licensing are managed separately from the code license.

— QuantDinger README · 授權與品牌說明

AI 研究

策略撰寫

回測驗證

模擬 / 實盤

監控與稽核