跳至主要內容

讀懂 engine_trades.csv

約 5 分鐘閱讀

engine_trades.csv 參考文件:PineForge 替開放語料庫中每支策略寫出的交易清單。逐欄說明、各列如何配對成交易,再附上一個 pandas 載入器。

pineforge-engine 目前的最新版本是 v1.12.0(2026-11-12 發行)。

2026-09-30 更新:內容已改為引擎實際寫出的格式(pineforge-engine v1.0.0)。

engine_trades.csv 是引擎的交易清單,CSV 的格式仿照 TradingView 的「交易清單」匯出檔,讓兩者能逐筆交易對照。這個檔案由引擎 repo 的 scripts/run_strategy.py 寫出;公開的 pineforge-corpus 裡,312 支策略每一支都附有一份,旁邊放著 TradingView 自己的匯出檔 tv_trades.csv(只有一支自我測試策略例外,它改為每個模式各附一份 TradingView 匯出檔,也就是 trades-<mode>.csv)。Docker 映像和 MCP 伺服器則以 JSON 回傳相同的交易,放在報告的 trades 陣列裡;本文談的是 CSV。

這個檔案是什麼

每一列代表一筆已平倉交易的其中一側:出場或進場。每筆交易剛好有兩列,出場列在前,兩列的 Trade # 相同。交易由新到舊排列:檔案從最大的交易編號開始,最後是第 1 筆交易。

逐欄說明

欄位型別說明
Trade #整數交易編號,出場列與進場列共用。
Type文字Entry long、Exit long、Entry short 或 Exit short。
Date and time文字以 UTC 表示的成交時間,格式為 YYYY-MM-DD HH:MM,沒有時區後綴。
Price浮點數這一側的成交價。
Qty浮點數成交的單位數,一律為正數。
Net PnL浮點數這筆交易的淨損益。兩列的值相同。
Net PnL %浮點數以百分比表示的 Net PnL。兩列的值相同。
Favorable excursion USD浮點數交易期間最大的未實現獲利,為零或正數。
Adverse excursion USD浮點數交易期間最大的未實現虧損,為零或負數(TradingView 的慣例)。
Cumulative PnL浮點數從第 1 筆交易到這筆交易的 Net PnL 累計總和。兩列的值相同。
Engine entry incarnation整數或空白引擎為這筆實際進場成交指定的 id,只出現在進場列;出場列為空白。
Engine range-endopen 或空白只出現在引擎 v0.13.0 及之後版本(包括 v1.0.0)產生的檔案:若部位是在資料範圍結束時由引擎平倉,其出場列會標為 open。

Trade #:配對的鍵

依 Trade # 分組,就能重建一趟完整的來回交易。每一組剛好有一列進場、一列出場。會加碼(pyramiding)的策略,每次進場都會拿到一個交易編號,編號方式和 TradingView 相同。

兩列都有的 Net PnL 與 Cumulative PnL

一筆交易的兩列,都帶有該筆交易的 Net PnL、Net PnL % 和 Cumulative PnL。加總 Net PnL 時,每筆交易只能算一次(例如只加總出場列)。

有利與不利偏移

Favorable excursion USD 和 Adverse excursion USD 是部位在平倉前達到的最佳與最差未實現結果,以帳戶貨幣計。不利偏移的值為零或負數,和 TradingView 的匯出檔一樣。兩者合起來可以用來評估停損的位置:獲利交易的不利偏移很小,代表這個部位從頭到尾都沒被逆向走勢壓迫過。

用 pandas 載入

下面這個載入器,會把每筆交易的進場列和出場列合併成一列。它已經用一個語料庫檔案驗證過(analyzer-anvil-percent-costs-01:325 筆交易,淨損益 −2,817.54)。

import pandas as pd
 
def load_trades(path: str) -> pd.DataFrame:
    df = pd.read_csv(path)
 
    # Times are UTC, formatted "YYYY-MM-DD HH:MM", with no timezone suffix
    df["Date and time"] = pd.to_datetime(df["Date and time"], utc=True)
 
    entries = df[df["Type"].str.startswith("Entry")].rename(columns={
        "Date and time": "entry_dt",
        "Price":         "entry_price",
        "Type":          "direction",
    })
    entries["direction"] = entries["direction"].str.replace("Entry ", "")
 
    exits = df[df["Type"].str.startswith("Exit")].rename(columns={
        "Date and time":           "exit_dt",
        "Price":                   "exit_price",
        "Net PnL":                 "net_pnl",
        "Net PnL %":               "net_pnl_pct",
        "Favorable excursion USD": "mfe",
        "Adverse excursion USD":   "mae",
    })
 
    # One entry row and one exit row per Trade #
    trades = entries[["Trade #", "direction", "entry_dt", "entry_price", "Qty"]].merge(
        exits[["Trade #", "exit_dt", "exit_price", "net_pnl", "net_pnl_pct", "mfe", "mae"]],
        on="Trade #",
    )
    return trades.sort_values("Trade #").reset_index(drop=True)
 
 
if __name__ == "__main__":
    trades = load_trades("engine_trades.csv")
    print(trades[["Trade #", "direction", "entry_dt", "exit_dt", "net_pnl", "mfe", "mae"]]
          .head(5)
          .to_string(index=False))
    print(f"\nTotal trades: {len(trades)}")
    print(f"Win rate:     {(trades['net_pnl'] > 0).mean():.1%}")
    print(f"Net P&L:      {trades['net_pnl'].sum():.2f}")

常見陷阱

每筆交易只算一次。 一筆交易的兩列都有 Net PnL,直接加總整欄會得到兩倍的結果。請只加總出場列,或先依 Trade # 分組。

檔案由新到舊排列。 第 1 列是最後一筆交易的出場。如果需要照時間順序,請依 Trade # 排序。

時間戳記是 UTC。 TradingView 自己的匯出檔使用你圖表的時區,所以比較時間之前,要先把兩邊對齊。語料庫的 TradingView 交易清單中,交易時間採用 Asia/Taipei(UTC+8);除非策略的 inputs.json 在 tv_trades_csv_tz 裡指定了其他時區,否則評分程式都會這樣假設。

結束時仍未平倉的部位會被平倉。 和 TradingView 一樣,引擎會把最後一根 K 線之後仍未平倉的部位平掉,所以它會以一筆正常交易的形式出現(目前的引擎會在 Engine range-end 欄標記它的出場列)。

和 TradingView 的匯出檔比對

TradingView 的「交易清單」匯出檔欄位更多,名稱也不同:Trade number(較舊的匯出檔是 Trade #)、Signal、帶貨幣後綴的 Price USDT、Size (qty)、Net PnL USDT 等等,日期則採用你圖表的時區。請依欄位的意義、而不是名稱來對應欄位,就像引擎的評分程式 scripts/verify_corpus.py 那樣:它接受每一種寫法,並依方向、進場時間(一小時以內)與進場價來配對交易。

下一步

  • 瀏覽畫廊:策略頁面會把引擎的交易清單和 TradingView 的並列,並附上兩份 CSV 檔案的連結。
  • 從 Claude 或 Cursor 使用 MCP 伺服器:backtest_pine 會以 JSON 回傳相同的交易,交給你的 AI 助理分析;報告太大、無法直接放在回應裡時,本機伺服器會把它存成檔案,託管伺服器則會提供下載連結。