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-end | open 或空白 | 只出現在引擎 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 助理分析;報告太大、無法直接放在回應裡時,本機伺服器會把它存成檔案,託管伺服器則會提供下載連結。