cedh-playgroup

cEDH 遊戲團體

此技能維護一個小型、可手動編輯的 cEDH 遊戲團體記錄，並結合 TopDeck.gg 的賽事資料。它有以下四項主要工作，並能將結果發布到團體的 Discord 頻道：

1. 玩家：透過 TopDeck 個人檔案 ID 新增成員，以及他們擁有的牌組。
2. 環境：查詢目前主流牌組與勝率，預設為過去 30 天。
3. 輸入：記錄練習結果、當前牌組、環境筆記、出席狀況。
4. 對局：安排練習對局，讓團體獲得有價值的練習經驗。

所有計算邏輯都位於 scripts/ 目錄下的 Python 腳本中（僅使用標準函式庫）。你的工作是執行這些腳本、讀取它們的輸出，並將其轉化為團體可用的建議。請勿手動重新計算統計數據。腳本已處理好各種邊際情況（如搭檔名稱、平局、小樣本），重複計算可能導致結果不一致。

設定與檔案位置

• 腳本：位於此檔案旁的 scripts/ 目錄。執行方式為 python <skill-dir>/scripts/<name>.py ...。
• 資料：位於 ~/cedh-playgroup/（可透過 CEDH_PLAYGROUP_DIR 環境變數覆蓋）。包含 roster.json、games.json、notes.json、availability.json 以及 cache/tournaments.json（TopDeck 資料快取）。這些都是純 JSON 格式，因此可以直接向使用者顯示或讓他們手動編輯。
• TopDeck API 金鑰：TOPDECK_API_KEY 環境變數。可在 https://topdeck.gg/account 免費取得。如果缺少金鑰，請說明並解釋如何設定。不要要求使用者在聊天中貼入金鑰。

使用 TopDeck API 的條件是必須標示來源。 每個使用賽事資料的回答結尾都應包含：*賽事資料來自 TopDeck.gg (https://topdeck.gg)*。腳本會自動印出此資訊。在總結時請務必保留。

資料新鮮度：先同步

TopDeck 沒有「根據玩家查詢成績」的端點。sync.py 會拉取指定日期範圍內所有已完成的 EDH 賽事，所有玩家和環境統計數據都來自這個快取。在進行環境報告、玩家統計或安排對局前，請先檢查快取的更新時間（cache/tournaments.json 中的 synced 列表）。如果快取超過一天，或未涵蓋所需的日期範圍，請執行同步：

python scripts/sync.py              # 最近 30 天，每週拉取一次
python scripts/sync.py --days 60    # 環境報告中的「Δ share」趨勢欄位也需要
python scripts/sync.py --import saved_response.json   # 離線 / 測試用

批量端點有速率限制。腳本會在遇到 HTTP 429 時自動退避，因此讓它運行即可。一次 30 天的同步可能需要一到兩分鐘。

1. 玩家

python scripts/playgroup.py add-player "Eric" --topdeck https://topdeck.gg/profile/<id> --deck kinnan
python scripts/playgroup.py set-decks "Sam" --deck najeela --deck "tymna kraum" --primary najeela
python scripts/playgroup.py set-decks "Lee" --deck "magda" --add
python scripts/playgroup.py set-decks "Jo" --deck glarb --gauntlet-pilot yes
python scripts/playgroup.py remove-player "Max"
python scripts/analyze.py players

• --topdeck 接受個人檔案連結（topdeck.gg/profile/<id> 或 topdeck.gg/profile/%40handle）、@handle 或純 ID。賽事排名只知道原始玩家 ID，因此腳本會開啟個人檔案頁面並從其 player-id 中繼標籤讀取 ID。它會印出找到的 TopDeck 顯示名稱。如果該名稱與使用者所指的人不符，請說明。如果查詢失敗（離線狀態），它會儲存所給的資料並發出警告。稍後請重新加入該玩家以使統計數據正確。如果使用者只提供名稱，請詢問他們的 TopDeck 個人檔案連結。僅透過顯示名稱配對可能會誤認同名同姓的人。
• 指揮官名稱會進行模糊比對，以對應 TopDeck 的拼寫方式（例如 "tymna kraum" → "Tymna the Weaver / Kraum, Ludevic's Opus"）。腳本會印出它選擇的比對結果。如果列出多個選項，請與使用者確認。playgroup.py resolve <name> 可檢查名稱而不儲存任何資料。
• 考驗型玩家（gauntlet pilot） 願意使用團體共用的牌組，而非自己的牌組。這樣一來，沒人擁有的頂級環境牌組也能出現在對局中。
• 如果在指定時間範圍內某玩家沒有參與任何 TopDeck 賽事，這並非錯誤。他們只是最近沒有參加有記錄的比賽。可以建議使用 sync.py --days 90 獲取更多歷史資料。

在報告玩家資訊時，應優先提供對練習有用的內容：當前牌組、近期戰績（勝負記錄及排名）以及他們的練習日誌。不要只是重複表格。

2. 環境報告

python scripts/analyze.py meta                       # 30 天, 16+ 玩家賽事, 前 25 名
python scripts/analyze.py meta --days 14 --min-players 32 --top 15
python scripts/analyze.py matchups "kinnan"
python scripts/analyze.py matchups --player Eric

欄位包括：出場次數、環境佔比、與前一個相同時間範圍相比的佔比變化、勝率、平局率、頂尖賽事轉換率以及最佳成績。

三種環境分析視角。 根據問題選擇合適的視角，或當使用者只是問「現在環境如何？」時，並排顯示本地和大型賽事的資料：

視角	指令	回答內容
本地	meta --local	我們的團體實際會面對的：在設定家庭位置半徑內的賽事，大小不拘，最近 30 天
大型賽事	meta --big	大型錦標賽的贏家：超過 100 名玩家，地點不拘，最近 90 天（這類賽事較少）
全域	meta	TopDeck 上所有 16 人以上的賽事

使用 playgroup.py home --zip 18201 --miles 100 --big-min 101 一次性設定家庭區域和「大型賽事」門檻，或使用 --zip Z --miles M 單次指定。本地視角使用 TopDeck 的賽事座標。線上賽事和沒有地點的賽事無法定位，報告會說明有多少筆資料遺漏。本地樣本較小，因此將佔比視為「誰會出現」，勝率則為參考。當本地和大型賽事的數據不一致時，這正是有用的資訊：一套牌在本地流行但在大型賽事中表現不佳，或一套牌在大型賽事中勝率高但在你附近還沒人玩。pods.py --local 或 --big 會讓「面對頂級環境」使用該視角。

正確解讀數據比列印數據更重要：

• 勝率是四人遊戲的數字。 平均約為 25%，考慮平局後會更低。報告會印出該時間範圍內的觀測平均值。30% 的勝率已經非常強。千萬不要用 50% 來評估勝率。
• 小樣本具有誤導性。 少於約 20 條出場記錄，或在 matchups 分析中少於約 10 場共享牌桌的數據，請將其視為「參考」而非「結論」。
• 流行度（佔比）和強度（勝率、轉換率）是兩個不同的問題。指出那些表現優於其佔比的牌組，以及那些流行但轉換率差的牌組。
• --min-players 16 用於將小型本地賽事排除在環境分析之外。如果使用者詢問本地環境，可以調低此門檻。
• 在相關的情況下，引入團體自己的 notes.json（例如「你提到在當地卡店看到很多 Magda，而它在全球範圍內也上升了 2%」）。

將回答組織成：3-5 個要點摘要，然後是表格（精簡到相關部分），最後說明這對團體的練習意味著什麼（例如，沒人擁有 Najeela，而它是第三主流；值得準備一份共用牌組）。

3. 輸入：結果、牌組、筆記、出席狀況

python scripts/playgroup.py log-game --date 2026-11-08 \
    --seat "Eric=Kinnan" --seat "Sam=Najeela" --seat "Lee=Tymna Kraum" --seat "Kim=Yuriko" \
    --winner Sam                     # 或 --winner draw；若順序未知可加 --no-order
python scripts/playgroup.py note "最近在當地卡店看到很多 Magda" --author Eric --tag meta
python scripts/playgroup.py avail 2026-11-08 Eric Sam Lee Kim Jo      # --replace 可覆蓋
python scripts/playgroup.py gauntlet-deck add "Najeela" --list <url>
python scripts/playgroup.py show games      # roster | games | notes | avail

人們會隨意回報結果（例如「Sam 用 Najeela 贏了，我和 Lee、Kim 分別用 Kinnan、Tymna、Yuriko，然後有一場平局」）。請將每場對局轉換為一次 log-game 呼叫。

座位順序即為回合順序，這點很重要：在 TopDeck 的四人格鬥中，座位 1 的勝率約為 23%，而座位 4 約為 14%。請按回合順序列出 --seat（座位 1 優先）。如果回報內容未說明回合順序，請詢問一次（「誰先手？」）。如果他們不確定，請使用 --no-order 記錄。對局仍會計入戰績和對局分析，只是不計入座位統計。建議團體使用最佳回報格式，因為這有助於完善每個人的座位分析：G1 (回合順序): Eric Kinnan, Sam Najeela, Lee Tymna/Kraum, Kim Yuriko. 贏家 Sam。如果任何影響統計數據的資訊不明確，例如誰贏了或某人使用哪副牌，請在記錄前先詢問。記錄後，用一行摘要回讀每一場對局，以便及時發現錯誤。

如果使用者貼上多場對局，請全部記錄，然後總結該晚的結果：誰贏了什麼，以及任何連勝記錄。

4. 練習對局

誰參加這次聚會

出席狀況每週都會變化，因此請在安排對局前先確定誰會參加。偏好順序如下：

1. 使用者直接指定人員（例如「除了 Jeff 以外的人」、「Eric、Ryan、Saige、Alex」）。
2. 該日期已儲存的出席名單（playgroup.py show avail）。
3. 詢問。如果你的用戶端有複選題工具，請將名單列為核取方塊，如果人數超過一個問題的容量則分題詢問，同時詢問日期。否則，用一行文字詢問。

儲存答案以確保對局、Discord 貼文和後續報告一致：

python scripts/playgroup.py avail 2026-11-08 --all --remove Jeff Saige   # 除了...之外的所有人
python scripts/playgroup.py avail 2026-11-08 Ishmael                      # 新增遲來的確認
python scripts/playgroup.py avail 2026-11-08 --remove Ryan                # 移除遲來的取消
python scripts/pods.py --date 2026-11-08                                  # 根據已儲存名單建立對局
python scripts/pods.py --all --except Jeff                                # 一次性，不儲存

如果名單在對局發布後發生變更，請重新建立對局並說明誰被調整了。不要在不通知的情況下重新安排已經看到自己對局的人員。

python scripts/pods.py --date 2026-11-08               # 使用該晚的出席狀況
python scripts/pods.py --players Eric Sam Lee Kim Jo Ana Max
python scripts/pods.py --date 2026-11-08 --focus Eric  # Eric 的弱點對局權重加倍
python scripts/pods.py --date 2026-11-08 --deck "Sam=Tymna Kraum" --w-repeat 0

建立器會搜尋不同的座位安排和牌組選擇，並根據以下四個目標進行評分（所有目標預設為開啟）。可將其權重設為 0 以關閉目標，或提高權重以強調該目標：

目標	旗標	獎勵條件
面對頂級環境	--w-meta	每桌有最多副頂級環境牌組（--top-meta 15）
平衡的對局	--w-balance	每桌的平均強度相近（玩家記錄 + 牌組勝率）
避免重複	--w-repeat	避免最近記錄的對局中已同組的玩家再次同組
針對弱點對局	--w-matchup	讓玩家面對他們會輸給的牌組（詳見下文）

誰的弱點對局？ 「練習我的弱點對局」是針對該玩家本人，而非牌組。建立器會根據該玩家自己的 TopDeck 對局記錄和練習對局，估算他們對抗每個對手指揮官的勝率。由於樣本數小，它會將結果向該牌組在相同配對中的整體表現收斂。一位對上 Rograkh/Thrasios 戰績為 1/11 的玩家，即使 Kinnan 玩家整體上對抗這副牌表現不錯，仍會被視為弱勢。在為那些詢問自己弱點對局的玩家安排對局前，請自己先查看證據：

python scripts/analyze.py matchups --player Eric --days 90   # Eric 自己的對局，所有賽事規模
python scripts/analyze.py matchups kinnan                    # 該牌組的整體表現，作為對比

當兩者不一致時，請直說（「Kinnan 整體上對抗 Najeela 還不錯，但你對上 Sam 的戰績是 0/3」）。這是有用的指導：問題出在玩家的操控，而非牌組本身。

座位安排。 建立器也會設定每桌的回合順序。使用 --seat-mode practice（預設值）時，每位玩家會被安排在他相對於該座位的正常勝率表現最差的座位。座位 2 的戰績是 0/6 很糟，而座位 4 的戰績是 2/10 則屬正常。--seat-mode best 則讓他們練習最好的座位（例如在比賽前），而 random 只是隨機分配。每位玩家的座位和對局分析證據：

python scripts/analyze.py profile

解說對局安排：這是重點。 對於每個座位，腳本會印出該玩家的證據數量、座位分析（最差、最佳、或尚無資料，附帶戰績及相對於座位平均的點數）、此桌的對局分析（「需要練習 vs …」和「佔優 vs …」，附帶該玩家的個人戰績和整體數據），以及此桌沒有的弱點對局。將這些資訊轉化為針對每位玩家的簡短、基於數據的「為什麼」，例如：

座位 1: Alex 使用 Tayam。 座位 1 是 Alex 最差的座位（戰績 1/10，比座位 1 的平均勝率低約 7 分），所以他在此練習。此外，他在比賽中對上 Sisay 的戰績是 0/7，而 Darison 的 Sisay 就在這桌。他對上 Ob Nixilis 則有優勢，所以這是他應該贏的對局。

解說規則：

• 引用實際戰績（1/10，0/7）。這是使其具有說服力的關鍵。
• 當依據少於約 6 場對局時，應說明「樣本數較少」。不要過分吹捧 0/2 的戰績。
• 如果某玩家沒有資料（沒有 TopDeck 連結，沒有記錄的對局），請說明他們的座位只是暫時安排，練習報告會逐步完善。不要編造理由。
• 最後說明更多練習資料可以改善什麼。每場記錄了回合順序的對局都能提高座位和對局分析的準確度。

對局大小為四人一組，不足四人則以三人湊數。如果有 5 名玩家，則一人輪空並輪替。如果使用者寧可進行五人對局，請說明由他們決定並安排好所有人。輸出中的「Sitting out」一行會指出輪替的人選。

以淺顯易懂的方式說明每個對局安排的原因：他們會遇到哪些環境主流牌組、每位玩家要練習哪個弱點對局，以及任何無法避免的重複配對。腳本的備註是原始素材。選出每個對局中重要的一兩點，不要全部貼上。如果分配了共用牌組，請確保操作者知道。