PineForge 在 CI 中跑你的 Pine Script 回測;交易一偏離,build 就失敗。
為何在 CI 做對齊
策略跟任何程式碼一樣會漂移。改參數名、重構 helper、沒注意到的 Pine v6 API 變更 — 都可能悄悄挪動訊號卻不打破既有測試。CI 沒對齊門檻時,兩個月前的 commit 可能改掉上週成交列表,你要等實盤損益怪了才發現。
把參考成交列表跟策略原始碼一起 commit 的紀律,就是讓軟體可靠的同一套:描述預期輸出,實際一偏 build 就炸。對回測而言預期輸出就是成交列表 — 進場棒、出場棒、方向、部位、成交價 — 對釘死的歷史資料集。
每次 commit 都比對,就形成棘輪:策略歷史行為只能改善,不會意外退步。你能 精準指出 哪個 commit 改了輸出,因為該 commit build 失敗。權益曲線也有 git blame。
多數量化人一開始低估這件事。「我測過這策略」與「這策略每個歷史訊號都有可重現、版控紀錄」差距巨大。前者是截圖;後者是稽核軌跡。CI 讓你在每次 push 不必手動維持後者。
PineForge 適合這個場景,因為它的執行環境就是一個 Docker 映像檔:能跑 Docker 的地方就能執行,相同輸入得到相同交易,並輸出可用 jq 解析的 JSON 報告。回測本身不需要瀏覽器、不需要登入,也沒有頻率限制。
GitHub Actions 範例
完整流程:簽出你的策略,用 pineforge-release 映像檔把它轉譯成 C++,針對你固定版本的 OHLCV CSV 執行回測,再用jq解析 JSON 報告,與已 commit 的 baseline 比較;只要任何一筆交易的多空方向或進出場 K 線有變,或淨損益差超過門檻,就讓 build 失敗。
runtime 是一個 container image,所以沒有 API key 要管 — 在 job 裡 docker run 就好。建立.github/workflows/backtest.yml:
name: Backtest parity
on:
push:
branches: [main, "feat/**"]
pull_request:
jobs:
backtest:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
# Pin the image version so results only change when you change it.
- name: Transpile strategy to C++
run: |
docker run --rm --network=none \
-e PINEFORGE_TRANSPILE_ONLY=1 \
-v "$PWD/strategy.pine":/in/strategy.pine:ro \
ghcr.io/pineforge-4pass/pineforge-release:1.12.0 > strategy.cpp
- name: Run backtest
run: |
docker run --rm --network=none \
-v "$PWD/strategy.cpp":/in/strategy.cpp:ro \
-v "$PWD/data/ohlcv.csv":/in/ohlcv.csv:ro \
ghcr.io/pineforge-4pass/pineforge-release:1.12.0 \
> report.json
- name: Assert parity
run: |
# Every trade keeps its side and its entry and exit bars,
# and net P&L moves by at most THRESHOLD.
BARS='[.trades[] | [.side, .entry_bar_index, .exit_bar_index]]'
ACTUAL=$(jq '.summary.net_pnl' report.json)
BASELINE=$(jq '.summary.net_pnl' baseline/report.json)
DELTA=$(echo "$ACTUAL $BASELINE" | awk '{d=$1-$2; print (d<0)?-d:d}')
THRESHOLD="0.01"
if [ "$(jq -c "$BARS" report.json)" != "$(jq -c "$BARS" baseline/report.json)" ]; then
echo "Parity drift: a trade changed side, entry bar or exit bar"
elif awk "BEGIN{exit !($DELTA > $THRESHOLD)}"; then
echo "Parity drift: net_pnl delta $DELTA exceeds threshold $THRESHOLD"
else
echo "Parity OK - same sides and bars, net_pnl delta $DELTA (threshold $THRESHOLD)"
exit 0
fi
# One trade per line, so diff's line numbers are trade numbers.
TRADE='.trades[] | {side, entry_bar_index, exit_bar_index, entry_price, exit_price, qty, pnl}'
diff <(jq -c "$TRADE" baseline/report.json) <(jq -c "$TRADE" report.json)
exit 1把 baseline 報告放在 repo 的baseline/report.json,與策略原始碼一起 commit。PR 若刻意改行為,作者在 PR 內更新 baseline。該 diff 成為永久紀錄:改了什麼、為什麼。
同一流程在 GitLab CI、Bitbucket Pipelines 或任何支援 Docker 的 runner 等同運行 — 換 YAML 語法,shell 指令保留。
退出碼與對齊主張
PineForge runtime 乾淨執行時退出碼為0(正常執行完畢);失敗時則為非零:2 代表缺少輸入檔、3 代表編譯失敗、4 代表回測失敗、5 代表轉譯失敗(不支援的 Pine 或語法錯誤)。CI 會直接讀取這些退出碼,不需特別處理。
如何檢查結果,由你的工作流程決定。報告內容如下(已節錄):
{
"engine": "pineforge",
...
"summary": {
"total_trades": 3483,
"wins": 1288,
"losses": 2194,
"win_rate_pct": 36.9796,
"net_pnl": 2518.39,
"max_drawdown": -1382.76,
...
},
"trades": [
{
"n": 1,
"side": "long",
"entry_time": 1729402200000,
"exit_time": 1729422000000,
"entry_price": 2640.96,
"exit_price": 2645.15,
"qty": 1.0,
"pnl": 4.19,
"entry_bar_index": 34,
"exit_bar_index": 56,
...
}
],
"metrics": { "all": { "profit_factor": 1.06, ... }, "equity": { "sharpe_tv": ..., ... } },
"equity_curve": [ ... ],
"fingerprint": { "digest": "sha256:...", ... }
}簡單數值對齊可比較summary.net_pnl與summary.total_trades對 baseline。上面的工作流程也會讀取trades陣列:每筆交易都必須維持原本的多空方向與進出場 K 線。檢查未通過時,工作流程會以每行一筆交易的格式 diff 兩份成交列表,因此 diff 的行號就是交易編號;每一行列出一筆交易的多空方向、K 線、價格、數量與損益,並呈現變更前後的內容。
數值欄位實務門檻:浮點差容忍到0.01(即淨損益的一美分),超過就判定失敗。交易則不設任何容許誤差:只要多空方向、entry_bar_index或exit_bar_index有任何改變,不論損益多少,上面的工作流程都會失敗。交易落在不同的 K 線上,代表你的訊號邏輯已經變了。
實用的做法:把更新基準報告放在獨立的工作流程步驟中,並以 PR 標籤控管,這樣刻意的變更就會在程式碼審查中,與造成它的 Pine 修改並列呈現。