【2026 最新】FDE-Gym 教學：本機首跑五步驟，先問需求再用客戶 KPI 驗收

你讓 AI 寫完自動化程式，測試全綠，客戶卻說夜間警報仍然吵、真正緊急的事件反而漏掉。FDE-Gym 教學要解決的，就是「程式能跑」與「客戶願意交付」之間的距離。先問清楚哪件事應該變好，再決定改哪段程式。

這篇專為剛接觸 Agent 的讀者寫：先用白話理解客戶 KPI，再帶你準備本機 Docker 首跑、整理需求訪談，最後設計「直接開工」與「先澄清」的同題對照。你需要一台已裝好 Docker Compose 的電腦、Python 3.9 以上，以及自行準備的小額模型額度；終端機指令會逐段說明。

本文依 2026 年 10 月 18 日查到的官方程式與文件編寫，固定程式提交 1d9ed027，其 Harness 回報版本為 1.3.0。本次寫作環境缺少 Docker，下面是可依循的操作與驗收方法；兩種流程的成績欄留給你完成首跑後填入。

先說結論：交付＝目標＋限制＋證據

FDE-Gym＝模擬客戶現場＋可修改系統＋以客戶指標驗收。把它想成接手一家店：老闆說「請換收銀機」，你要先確定他真正煩惱的是排隊、算錯帳，還是店員每天花兩小時對帳。換機器是方案，改善工作才是目標。

FDE 是 forward-deployed engineer，常譯為前線部署工程師；這裡練的，是進入客戶環境、發現需求、做出取捨與交付。KPI 則是關鍵績效指標，像恢復服務所需時間、有效處理量或人工負擔。若想先補 Agent 的工作迴圈，可讀 Agent Harness 是什麼：模型負責推理，Harness 負責工具、狀態與驗收。

作者的 FDE-Gym 論文 v1於 2026 年 10 月 15 日提交，包含 20 個客戶情境、95 項任務。這是作者建構的模擬環境與評測；本機公開案例練習和完整論文評測，應各自保留任務範圍。

FDE-Gym 教學第一步：固定版本，先把環境與資料分開

為什麼昨天的教學，今天按鈕就不同？早期專案更新很快。先留下版本收據，之後才能追查差異。以下在一個新資料夾操作；checkout --detach 是停在指定提交，不是刪除檔案。

git clone https://github.com/deeplethe/fde-gym.git
cd fde-gym
git checkout --detach 1d9ed027af7c8312bacb1abad1467c87a91c004b
git rev-parse HEAD
python3 harness/run.py --version
docker compose version

檢查點是完整提交雜湊一致、Harness 顯示 1.3.0，以及 Compose 能回報版本。若最後一行找不到指令，先依 Docker 官方安裝說明完成環境；此時先別執行案例。固定程式提交仍不等於鎖住整個環境：這版 Compose 的物件儲存映像使用 latest，案例下載也讀取資料集當下的 main。

因此第一次抓完資料與建好映像後，保存終端機輸出、案例副本及 docker compose images 的清單；做 A/B 時兩輪使用同一套檔案和映像，先別更新。若要跨日嚴格比較，再把案例檔案雜湊、映像 digest 與模型完整識別碼一併固定。

金鑰像店門鑰匙，不該放進交給施工者的紙箱。官方 Harness 設定使用 Repo 外的檔案存 OpenRouter key。先建立私人資料夾與檔案，再用文字編輯器填入自己的金鑰，避免把金鑰直接寫進終端機歷史：

mkdir -p "$HOME/.fdegym"
chmod 700 "$HOME/.fdegym"
touch "$HOME/.fdegym/openrouter_key"
chmod 600 "$HOME/.fdegym/openrouter_key"

這四行只建立容器要讀的檔案，還沒填 key。別把檔案、截圖或含 key 的設定傳給 coding agent。接著回到 Repo 根目錄，依 官方 Quick Start執行：

python3 scripts/fetch_cases.py
docker compose up --build

公開案例資料集標示 CC BY-NC 4.0，程式碼則採 Apache 2.0；兩者授權分開。此處用公開案例做個人練習，不重發題庫或用於模型訓練。下載器把三個公開情境放進 cases/；啟動後用瀏覽器打開 http://127.0.0.1:8787。這版 Compose 由網站、runner、PostgreSQL 與物件儲存四個服務組成。先確認服務成功啟動、網頁可開、案例清單可見，才算完成環境驗收。第一次註冊的帳號會成為管理員，請只在自己的本機環境完成這一步。按 Begin 會執行案例的工作區生成程式，交付評分也會執行你修改的系統；這輪只載入官方公開案例，使用題目提供的模擬資料，不把真實客戶文件或正式環境憑證放進工作區。

匯入資料要特別小心。Issue #19回報 --from 搭配 --force 可能先刪掉與目的地重疊的來源。這版 下載器原始碼也能看到先移除目的地、再複製來源的順序。新手先用預設下載，不加 --force；已有資料時保留副本。若必須本機匯入，來源、目的地連同旁邊的 data/raw 都應在互不重疊的資料樹，並檢查符號連結是否其實指向同一處。

FDE-Gym 教學第二步：開一個案例，先寫四欄需求單

不知道要先看什麼？選定一題，先把願望翻成問題。從案例清單找到 oncall_incident，按 Begin 開始。公開資料集把它描述為 B2B 發票 API 的 AI 夜間值班案例；L3 brief 的目標包括減少無謂叫醒工程師、加快恢復，並讓你使用基礎設施 API 與操作手冊。情境中的數字與公司是題目材料，別當成外部公司的營運統計。

先看這次工作區提供的 TASK.md、docs/ 與既有 system/。把工作區當成客戶交給你的辦公桌；Repo 內的評分器、參考答案與其他層級 brief 則是出題者的資料。這輪只讀桌上的材料，才能保留需求探索的意義。

• 目標 KPI：客戶用什麼數字判定改善？原始指標越高越好，還是越低越好？目前只知道「少打擾、快恢復」，先標為待確認。
• 未確認假設：是否每種警報都允許自動修復？哪種操作需要先取得授權？把猜想寫成問句。
• 不可違反限制：哪些服務、資料或緊急事件必須受到保護？只抄已提供的規則，未知的留白。
• 可詢問角色：誰懂值班流程、誰能決定風險、誰知道歷史事故？依工作區實際名單挑人，不猜人物 ID。

這張單不是模型的標準答案。它的作用，是讓每個改動有依據：一項客戶目標、一項可確認的限制，以及一份可檢查的產物。像 建立 Agent Harness 的方法一樣，先定義停止條件，才開始反覆呼叫工具。

第三步：先問需求，再交給 coding agent

訪談怕問太多、也怕漏問？優先問會改變實作決策的問題。以下是建議問法，並非官方 stakeholder 已給出的回答；每次只問一個具體問題，收到回覆才更新紀錄：

• 「你判定一次值班處理成功的主要指標是什麼？」
• 「哪些情況即使能自動修復，也必須先通知或取得人工授權？」
• 「我想把這類警報自動處理；哪個例外會讓這個方案不被接受？」

訪談紀錄逐筆存下「問誰、原問題、原回答、因此改變哪個決策、還缺哪個證據」。若回答沒有改變任何判斷，下一次就換更具體的問法。官方計分會扣除詢問與試跑等互動成本；全面問一輪未必比問對關鍵人更划算。

這裡要分清兩套工具。依 現版 self-hosting 文件，網頁內建 coding agent 使用 pi；由管理員設定模型端點、步數與每次 run 的金額上限。若自訂端點不回傳費用，這版介面的美元上限不會生效，仍依每則訊息步數限制；有回傳費用時，也是下次呼叫前再檢查累計用量，可能超額。網頁的 Agent 面板和你電腦裡的 Claude Code，是兩個執行環境。網頁流程中，客戶提問與 trial day 由操作的人發起；不要預期內建 agent 自己替你完成所有訪談。

如果你已使用 Claude Code，可以把工作區內允許閱讀的題目與訪談重點，另存到一個只有這些材料的新資料夾，讓它當「需求整理助手」。不要從含評分器的 Repo 根目錄啟動。先用以下提示產出待問清單，再由你在 FDE-Gym 向角色確認：

先讀這個資料夾的客戶題目與訪談紀錄，暫時不要實作。
列出：目標 KPI、未知假設、不可違反限制、建議詢問角色。
每個問題說明：不同答案會讓哪個實作決策改變？
將已確認事實與推測分開，引用對應檔案。
只使用我提供的材料，不搜尋評分器、參考解答或其他難度 brief。

Claude Code 的自動化成本可再細分。官方 CLI 參考記載 --max-budget-usd 用於 -p 列印模式，依用戶端估算費用停止，單次呼叫仍可能超過設定值。它管的是 Claude Code 那次呼叫，FDE-Gym 網頁的模型費與角色對話另記。先參考 Claude token 成本管理，在帳戶供應商端也設小額預算與通知。

在管理員 Agent 設定先選定可用模型與小額每-run 上限；A/B 使用同一完整模型 ID、相同步數與預算。把 coding agent 用量、角色／評分模型用量、額外 Claude Code 用量分開登記。這些是不同帳本，任一處顯示的上限都不應當成整場練習的總帳單保證。

第四步：同一個起點，做「直接開工」與「先澄清」對照

怎樣知道提問真的有幫助？先把其他變因固定。選相同案例版本與相同題號，各按一次 Begin 建立新的 run；在自己的紀錄表將兩個 run ID 標為 A、B，兩輪不共用對話或先前修改。A 只依初始材料開工；B 先做上面的需求澄清，再交付。兩輪的模型、可用工具、總時間與預算相同；B 的訪談時間包含在總時間內。

如果你親自操作，先做過一輪就會知道更多背景。換一個空白對話並不能讓人忘記答案。最保守的寫法是把它記成「同一操作者的探索紀錄」；若要比較流程效果，可用不同且未看過另一輪紀錄的操作者，或讓隔離的新 agent session 執行固定流程。仍應保存順序與干預，別只公布較漂亮的一次。

每輪依需求修改 system/，留下變更檔案、測試輸出及決策理由。用工作區提供的測試／trial 檢查，記下試跑次數；最後核對即將交出的檔案，再 hand over。這版流程每個 run 交付一次；要再嘗試，開新的 run，別把多次修補後的最好結果冒充第一次成功。

控制隱藏資料的邊界同樣關鍵：操作的 agent 只看到該 run 工作區，不把 grader.py、truth.json 或出題者的生成資料掛進去。自架者能接觸題庫，不等於參賽流程應讀題庫。學習後可以另開解析階段，並將它和盲測結果分開保存。

第五步：先看事故，再看 KPI，最後算提問值不值得

分數高就代表少花一樣比例的錢嗎？先讀分數的分母。官方 Harness 用客戶原始 KPI，相對於「原系統」與「參考解法」正規化。依 固定版本的計分程式，核心關係可寫成：

uplift = (本輪 KPI − 原系統 KPI) / (參考解法 KPI − 原系統 KPI)
uplift_net = uplift − contact_cost

如果原始指標是越小越好的損失，分子與分母可能同為負數，改善後仍得到正向 uplift。0 對應原系統，1 對應參考解法；看到 0.8，應讀成正規化尺度的位置，不能直接換成真實成本下降 80%。程式還會處理分母為零與事故情況；遇到 incident，uplift 被限制為不大於零，再依互動成本計算淨分。

每輪結果用同一張紀錄單逐項抄回：原始 KPI、baseline／reference、uplift、uplift_net、incidents、互動成本、模型用量、總時間及交付檔案。網頁結果頁提供分數、客戶指標、事故與聯絡紀錄；CLI 則將結果寫入 result.json。若有缺欄位，保留缺值，回查自己的用量與事件紀錄。

判讀順序很簡單：出事故先追原因；沒有事故，再看原始工作是否改善；最後才問為這個改善花了多少提問與模型成本。B 若問得更多但淨分下降，下一輪就檢查哪些問題沒有影響決策。B 若原始 KPI 改善而事故增加，也先處理限制。兩輪結果只能幫你發現下一個假設；要推論流程普遍較好，還需要更多任務和重複執行。

論文中「最佳配置解決 14／95 題」是指定評測配置的作者報告。公開例題 資料集說明則是三個完整原始情境，其他隱藏變體與完整榜單有自己的評測範圍。跑通一題，先把結論留在「這個版本、這一題、這一輪」。

常見問題：八個新手最容易卡住的地方

1. 不會寫程式，可以練什麼？

可以先練需求判讀。先完成四欄需求單與三個關鍵問題，再用 coding agent 協助實作；修改是否安全仍要對回案例規則與測試。

2. 一定要用 Claude Code 嗎？

依本文固定版本，網頁內建使用 pi。Claude Code 是可另加的需求整理助手；先選一條清楚的路徑，分開記錄成本與資料去向。

3. 把所有情況都轉人工，最保險嗎？

要看客戶目標。若目標包括減少人工打擾，全轉人工可能保留原來痛點。先確認必須升級的條件，再用案例驗收判斷。

4. 問越多角色就會分數越高嗎？

不一定。互動有成本，資訊也要被正確落實。每次提問先寫出它會改變哪個決策。

5. 可以用同一個對話做完 A，再做 B 嗎？

會污染比較。B 可能已讀過 A 的答案與錯誤；另開新 run 與新對話，並記錄操作者是否已知道關鍵資訊。

6. 下載公開例題，就能重跑 95 題嗎？

範圍不同。公開頁提供三個原始情境；論文還包含其他情境與隱藏變體。把案例版本和任務集合寫清楚。

7. 為何本機啟動仍要模型金鑰？

角色對話會使用模型。現版文件也說明部分公開案例的評分可不呼叫模型，但不要因此把整個互動流程當成零模型費。

8. 停止練習後，如何保留資料？

先保存紀錄，再停止。用 docker compose down 停服務，保留具名 volumes；避開會刪掉 volumes 的 down -v，並依 self-hosting 文件備份資料庫與物件儲存。

給新手的三個重點

• 先寫目標和限制，再請模型改程式；每個關鍵假設都能指回客戶材料或回答。
• 先固定起點，再改流程；訪談時間、模型費、失敗與人工干預都留下來。
• 先看事故與原始 KPI，再看正規化淨分；把一次成功接回實際交付證據。