AI Trading PK
我是怎麼蓋起來的

里程碑（最新在上）

每出一個有意義的版本就在這留一筆。下面各章節若有變更，會就地更新。

30 秒講完版本

有人只給你 30 秒，你就講這段。

為什麼有這個東西

五個你該知道的觀念

把這五個搞懂，幾乎所有同事問的問題你都答得出來。

一張圖看完架構

五層，依賴方向永遠由上往下。沒什麼花俏的。

技術棧逐層說明

每樣東西為什麼選它，一兩句講完。

引擎 tick

backend/app/engine/tick.py 裡面只有一個函數 advance_one_trading_day， 每天跑同樣的 6 個步驟，順序不變。Idempotent。沒有特例。

不能偷看未來，否則一切都是假的

業餘回測最常見的單一錯誤：不小心讓「過去的決策」用到了「未來的資料」。 這個系統有個測試，只要踩到這條線就會炸給你看。

# backend/tests/test_engine_no_lookahead.py — 守在這裡

def test_decision_never_reads_future_data(db):
    # 第 1-3 天股價 600..602；第 4 天跳到 999（這是「未來」）
    seed_path_bars(db, ticker="2330.TW", start=date(2026, 5, 4),
                   opens=[600, 601, 602, 999, 1000, 1001])

    snoop = SnoopProvider()
    advance_one_trading_day(db, comp, snoop, _snoop_snapshot)
    advance_one_trading_day(db, comp, snoop, _snoop_snapshot)
    advance_one_trading_day(db, comp, snoop, _snoop_snapshot)

    # 每次決策看到的日期，都不能 > 自己的 decision_date
    for dk_observed, seen in snoop.observations:
        assert all(d <= dk_observed for d in seen), \
            f"Decision on {dk_observed} saw future dates {seen}"

每次重構引擎都會跑這個測試。哪天有人「優化」程式碼結果偷讀了明天的 open， 測試就斷給你看。bug 進不了生產環境。

策略 schema：兩半

同一個 shape，一半是程式硬性守的、一半是自然語言。Personas 就是這個 shape 的預設值。

{
  "max_position_pct": 0.30,
  "max_holdings": 4,
  "max_trades_per_decision": 3,
  "cash_floor_pct": 0.10,
  "stop_loss_pct": 0.08,
  "take_profit_pct": 0.20
}

"鎖定 5 日與 20 日動能最強、且
above_ma20 的股票。持倉跌破 -8%
出場，獲利 +20% 起逐步停利。
動能消退立刻換股。"

為什麼要兩半：純 structured 太死板，沒個性；純 free_text 容易亂下單浪費手續費。 切兩半同時拿到「自然語言設定」的好處跟「程式守底線」的安全。

「agent 怎麼建立？」

同事常常以為 agent 是 markdown 設定檔。不是。 這節把心理模型講清楚，下次有人問你就能秒答。

個股 / Stocks tab

排行榜告訴你「誰在贏」，個股頁告訴你「該叫你的 agent 看哪些股票」。 讓使用者在調策略之前可以先逛 universe。

對 PK 來說為什麼重要：沒寫過程式的同事寫 free_text 策略時， 很容易寫「買漲的股票」這種模糊指令。給他看到 LLM 看到的實際 snapshot， 他就會學會寫「pct_5d > 10% 且 volume_ratio > 1.5 才買」這種具體可執行的指令。

三大法人

每個台股 trader 都會先看三大法人，才下單。如果我們的 agent 看不到，等於對台股市場最大的推力視而不見。

LLM 怎麼看到：snapshot 的每個 row 現在都帶著 foreign_net_lots、trust_net_lots、dealer_net_lots、 total_inst_net_lots，跟價量欄位並排。單位是「張」（1 張 = 1000 股）。 正數 = 淨買、負數 = 淨賣。系統 prompt 也明確跟 LLM 講該怎麼看 — 「三大法人買超 + 股價上漲 = 強訊號；賣超 + 股價反彈 = 警訊； 投信持續買進 = 多日行情的開始」。

# 實證：2454 聯發科 2026-05-29

ticker: 2454.TW
last_close: 4310.0          # 前一天 4410
pct_1d: -2.27%              # 跌
foreign_net_lots: -2325     # 外資倒貨 2,325 張
trust_net_lots: -1021       # 投信賣 1,021 張
dealer_net_lots: -130       # 自營小賣
total_inst_net_lots: -3476  # 三大法人合計賣 3,476 張

資料來源：https://www.twse.com.tw/rwd/zh/fund/T86（上市）跟 https://www.tpex.org.tw/web/stock/3insti/daily_trade/3itrade_hedge_result.php（上櫃）。 兩個都免費、都能用，每天收盤後 30 分內更新。一次 HTTP 拿回整個市場 — 所以更新 194 檔 universe 的三大法人，一天只要 2 個 request。

風險調整後的排行榜

三個指標把排行榜從「誰運氣好」變成「誰真的會做交易」。可以切換排序：報酬率 / Sharpe / 最大回撤。

為什麼重要：看看我們自己 demo 切換排序時發生什麼事：

Momentum 的報酬將近兩倍，但 Contrarian 用三分之一的回撤拿到一半的報酬 — 所以以風險調整後的角度，Contrarian 才是贏家。 這種比較讓排行榜從「吃角子老虎機」變成「面對懂金融的同事也站得住腳」的工具。

實作在 backend/app/services/metrics.py。用 252 個交易日年化。 資料不足（< 2 個 snapshot 或波動為零）時回傳 None，前端顯示「—」而不是亂湊。

「即時」到底有多即時

兩條資料流，分得清清楚楚。這個邊界僅次於 engine-as-source-of-truth，是整個架構的第二根脊椎。

一句話講邊界：即時資料只是 UI 上的塗料。 任何會改投組的東西（訂單、填單、MTM snapshot）都只讀日線資料 — 引擎保持決定性、no-look-ahead 測試依然能跑。

BYOK Claude：使用者金鑰怎麼運作

沒有共用的 Anthropic key。每個人連自己的。

# backend/app/services/crypto.py — 加密邊界

def _derive_key(secret: str) -> bytes:
    digest = hashlib.sha256(secret.encode("utf-8")).digest()
    return base64.urlsafe_b64encode(digest)

def encrypt(plaintext: str) -> bytes:
    return _fernet().encrypt(plaintext.encode("utf-8"))

def decrypt(token: bytes) -> str:
    return _fernet().decrypt(token).decode("utf-8")

使用者解除連結時 row 就刪。如果存的金鑰失效，LLM 呼叫會優雅失敗 — 決策記錄為「claude not connected」並回傳 0 個訂單。引擎絕不會在 tick 中崩潰。

賽馬場視覺改版的六個動作

第一版乾淨的 dark theme 表格 — 可讀但無聊。改版有意識地借用了「賽馬」的能量，靠這六個動作就完成大半。

講解話術

可以直接講出來的句子。每句都在 30 個字內。要 paraphrase，不要逐字念。 這是你蓋的東西 — 講起來要像你蓋的。

怎麼用這份文件