使用 Scryfall 建立 AI Commander 卡牌查找器

Scryfall Commander 卡牌搜尋助手會將你對所需卡牌的文字描述，轉換成一個可以親自檢視的搜尋查詢。在本教學中，你將建立名為 Open Query 的 Quickchat AI Agent。它會把實際使用的 Scryfall 查詢顯示出來，回傳資料庫中的真實卡牌記錄，並逐一解釋這些候選卡牌為什麼可能符合你的牌組需求。

先考慮單綠 Commander 牌組中一個尚待填補的卡位。這個卡位需要一張具有踐踏異能、價格低於五美元的生物牌。完成教學後，你就能用文字描述這個需求，開啟搜尋結果中的卡牌連結，並根據看到的結果繼續調整搜尋，無須先把所有搜尋運算子都背下來。

真正有用的部分是在需求變得更難時。「當另一個生物進場時抽牌」聽起來很精確，但搜尋 enters 和 draw 這兩個字，也會找到做其他事情的卡。你將會抓出這種不符並縮小查詢，並把回傳的卡牌文字當作證據。

你會建立什麼，又需要什麼？

這個教學只需要設定一個用於讀取資料的 API Action，把你的 Agent 與 Scryfall 連接起來。你會先為 Agent 寫好搜尋指示，再透過實際對話檢查它的表現。兩者的分工很明確：Action 始終請求你在設定中指定的固定 URL，模型則負責根據目前的對話提供搜尋查詢與頁碼。Scryfall 回傳卡牌記錄後，Agent 會以這些記錄為依據組織回答。

1. 建立一個 Quickchat AI 帳號，並建立一個名為 Open Query 的 Agent。你需要可用的 AI 點數來進行對話與測試。請參閱目前方案。
2. 在操作過程中，請保留 Agent 的 Identity、Actions & MCPs 與 AI Preview 可供使用。不需要上傳卡牌收藏。
3. 使用 Scryfall 的公開 API。這些搜尋不需要 Scryfall 帳號或 API 金鑰。

starter kit 內含 Main Prompt、Action 配方、response-filter 路徑與測試訊息。範例使用英文 Oracle 文字與 USD 價格。若你以其他語言跟著操作，請保持查詢運算子與卡名原樣。

步驟 1：如何把卡牌需求轉成 Scryfall 查詢？

一個 Scryfall 查詢會把多個限制條件以空格分隔組合起來。對於我們的第一個需求，請使用：

f:commander id<=g t:creature kw:trample usd<5

有兩個小選擇很重要。kw:trample 會搜尋關鍵字。o:trample 會搜尋 Oracle 文字中的單字。 一個生物可能提到踐踏，但自己並不具有該異能。我們兩種都測過。文字搜尋產生了更廣的結果集。

「適合單綠牌組」也不同於「顏色身分剛好是綠色」。 前者允許無色卡。後者請使用 id=g，或使用 id<=ur 在藍紅指揮官的顏色範圍內搜尋。這些是身分限制，不是完整的牌組合法性檢查。

Scryfall 的搜尋語法參考說明了這些運算子。在本教學中，請讓每個答案都顯示查詢，這樣你才能注意到遺漏的顏色、意外的貨幣，或比你的需求更寬鬆的搜尋。

步驟 2：如何把 Scryfall API 連接到你的 Agent？

建立一個 API Action，向 Scryfall 的卡牌搜尋端點送出 GET 請求。它的固定設定會選擇供應商與排序方式。它的兩個參數則讓 Agent 選擇搜尋內容與頁碼。

1. 開啟 Actions & MCPs → Add Action → API Action。
2. 使用下方的 builder 請求，然後對照配方檢查產生的設定。API Action builder 指南 說明了產生與檢查流程。
3. 將 API Action Name 設為 Search Scryfall cards。

Create a read-only Scryfall card-search Action using GET https://api.scryfall.com/cards/search. Add required Text query and Integer page parameters. Map q to query and page to page in Query Params. Fix unique=cards and order=name. Send Accept: application/json and User-Agent: QuickchatTutorialCardFinder/1.0 (+https://quickchat.ai). No authentication and no request body. Fetch one page only. Preserve pagination, warnings, card IDs, names, Oracle text including card_faces, color identity, Commander legality, USD prices and Scryfall links in the response.

定義兩個參數

在 What to ask the user first 下，加入以下必要參數。Agent 可以從對話中填入它們。這個標籤不代表它一定要要求你輸入原始查詢語法。

設定端點、查詢參數與標頭

選擇 GET 並輸入：

https://api.scryfall.com/cards/search

在 Query Params 下，加入以下四列。對於動態值，使用 Add AI Data 來選取你建立的參數。下方的 {{query}} 與 {{page}} 表示那些參數晶片。

請使用查詢參數欄位，讓空格、引號與運算子被編碼為參數值。端點 URL 請保持固定。

將 Body 留空。不需要驗證。User-Agent 是可識別的用戶端名稱，不是憑證。部署你的版本時，請使用你自己的適當應用程式名稱與聯絡 URL。

讓回應保持實用

Scryfall 頁面可能包含許多記錄。請保留 Agent 需要的欄位，以及告訴它是否還有更多頁面的資訊。展開 Advanced settings 並找到 Response filter。使用 Add JSONPath，然後按下加號按鈕，將下方每個路徑分別新增為獨立項目：

$.total_cards
$.has_more
$.next_page
$.warnings
$.data[*].id
$.data[*].name
$.data[*].oracle_text
$.data[*].card_faces
$.data[*].color_identity
$.data[*].legalities.commander
$.data[*].prices.usd
$.data[*].scryfall_uri

請保留 card_faces。 有些卡會把文字放在各個牌面上，而不是頂層。也請保留 warnings： HTTP 成功不代表 Scryfall 已如預期解讀每個子句。Card object reference 說明了這些欄位。

在 API Action Description 中貼上：

Use when a player wants to find real cards matching a confirmed request. Build an inspectable Scryfall query, fetch one page, and explain matching evidence from returned fields. Show the executed query and any returned warnings. Return at most five initial recommendations, with Scryfall links, relevant Oracle text, color identity and USD price. If more API pages exist, say so and offer the next page; do not claim the first results are exhaustive. Treat broad text searches as candidates until their Oracle text establishes the requested interaction.

儲存 Action，並確認它已啟用。HTTP Action anatomy guide 說明了參數、請求與描述如何共同運作。

步驟 3：卡牌查找器應該如何解釋結果？

Agent 需要指示來顯示查詢、把推薦建立在回傳記錄上，並區分文字匹配與規則互動。開啟 Identity → Main Prompt，貼上 starter kit 中的完整提示詞，如下重現。

You are Open Query, a Commander card-search helper. Clarify format, color identity and budget currency when needed. Turn the confirmed request into documented Scryfall syntax, call Search Scryfall cards, and show the executed query in a code block followed by up to five linked results. Recommend only records returned by this Action. Include each card's name, Scryfall link, color identity, returned USD price and the relevant Oracle text. Summarize without inventing text or cards. Use periods or semicolons rather than em dashes. Use text on card_faces when present.
For mono-green deck eligibility use id<=g; this includes colorless. For exactly green identity use id=g. A baseline trample request uses f:commander id<=g t:creature kw:trample usd<5.
Separate word matches from rules interpretation. If a card mentions the requested words but does not establish the requested trigger, label it a candidate to inspect, not a confirmed fit. Prices are provider observations, not seller quotes; a missing price is unknown. Say the total result count and whether more API pages exist. Start at page 1. Fetch the next page only when asked, using the same query and the next page number. Never fetch every page automatically. A shortlist is not exhaustive. If asked for more from this page, fetch the same query and page again, then choose returned cards you have not already shown. The next API page is different.
Do not build a full deck, invent cards, or claim a rules ruling. If a search returns no results or an error, explain it and offer a specific query change for confirmation. Inspect response warnings as well as errors. If Scryfall ignores part of a query, report that warning, do not recommend cards from that broadened result, and ask before changing the query. Do not silently retry an altered query. If rate limited, stop and ask the reader to try later.

現在開啟 AI Preview 並送出：

Find Commander-legal creatures in mono-green color identity with trample, priced below 5 USD.

這個示範把單綠牌組適用性解讀為綠色或無色。若你要的是剛好綠色身分，請明確說明。

在看推薦之前，先讀已執行的查詢。它應保留 Commander、綠色或無色身分、生物類型、踐踏，以及低於 5 USD。打開其中一張卡的 Scryfall 連結，將相關文字、身分與價格和答案對照。這個價格是對回傳版本的查詢觀察值，不是結帳報價。

API 結果是依名稱排序，不是依適配度排名。Agent 會從已抓取頁面中挑選簡短名單。unique=cards 可避免把每個版本都列成獨立結果。這不代表所選記錄就是你能買到的最便宜版本。

步驟 4：如何修正找到錯誤互動的搜尋？

透過閱讀反例並加入缺少的條件來縮小查詢。在整個微調過程中，持續區分尋找候選卡與確認其文字。

請問：

Find green cards that draw when another creature enters, under 5 USD.

一個寬鬆的候選搜尋是：

f:commander id<=g o:enters o:draw usd<5

在我們於 2026 年 11 月 10 日直接進行的 Scryfall 檢查中，這個搜尋回傳了 161 個候選，其中包含 Abundant Growth。它的抽牌是在該靈氣本身進場時發生。它同時包含這兩個字，但並沒有提供需求所暗示的、可重複觸發的生物進場抽牌引擎。

試試這個微調：

Keep the same colors and budget. Look for “whenever another creature”, then check the conditions in each returned card's text.

我們檢查過的較窄查詢是：

f:commander id<=g o:"whenever another creature" o:enters o:draw usd<5

微調後的搜尋回傳了四個候選。Garruk’s Packleader 是一個有用的條件式匹配。另一個生物必須具有 3 點或以上的力量。這個差異應該寫進推薦說明中。若是有大量 1/1 生物衍生物的策略，可能就需要不同的卡。

只加入 o:"another creature" 的精確度較低。我們的測試仍然找到了 Disciple of Freyalise，它自身進場時可能讓你犧牲另一個生物並抽牌。這也是為什麼你應該檢查整個異能，而不是把額外片語當成證據。

對你自己的牌組也重複同樣的流程：需求 → 查詢 → 卡牌文字 → 一次微調。如果預算排除了所有有用候選，請先詢問再放寬。如果某張卡有限制，請把限制說出來，而不是默默把它從說明中省略。

步驟 5：在使用前，如何測試這個卡牌查找器？

同時測試答案與 API 呼叫。一句看似可信的話，無法證明實際執行了哪個查詢，或回傳了哪些記錄。

1. 開啟 Testing，使用 Create Dataset → Paste messages 建立一個名為 Open Query checks 的資料集。貼上套件中的獨立測試訊息。
2. 執行測試。評估答案是否顯示查詢、引用回傳卡牌，並解釋不確定性。
3. 在 Inbox 中開啟對應對話，並檢查 Action 呼叫。檢查查詢、頁碼、狀態與回傳欄位。使用 Action 的 View logs 控制項來尋找個別呼叫。
4. 在持續對話中測試微調與分頁，因為先前的查詢在那裡可供使用。

對於無匹配測試，請送出：

Find a Commander card named definitely-not-a-real-card-xyz.

一次直接 API 測試顯示了為何警告很重要。格式錯誤的查詢 f:commander o:/[/ 回傳了 HTTP 200，但 Scryfall 回報它忽略了無效表達式。因此結果比需求更寬鬆。請保留該警告、解釋被忽略的篩選，並在推薦這些結果前修正查詢。

我們在本機 Agent 上的執行涵蓋了基準情況、微調、空結果與兩頁搜尋。獨立 API 檢查則涵蓋了缺少價格、牌面與語法警告。請使用受控的固定測試資料來測試速率限制，而不要發送過量流量。

卡牌搜尋端點文件 目前規定為每秒兩次搜尋請求。請讓請求之間至少間隔 500 毫秒。本教學是一個個人搜尋助手。若是服務許多玩家的公開機器人，則需要共享的速率限制與快取。要求模型放慢速度，並不能強制執行全域請求限制。

ChatGPT 或 Claude 可以幫忙設定嗎？

你可以使用 適用於 ChatGPT 的 Quickchat AI 外掛 或 適用於 Claude 的 Quickchat AI 連接器，透過帳號管理連線來設定 Agent。請自行完成登入，然後提供本教學與其 starter kit，並附上以下請求：

Use Quickchat AI to create a dedicated Agent called Open Query using the attached tutorial and starter kit. Set its Main Prompt and create the Search Scryfall cards API Action with the exact parameters, headers and response filters. Show me the saved configuration, then run the baseline and impossible-name tests and show their Action call records. Run only those two conversations; they use AI credits. Do not publish the Agent or connect a public channel.

帳號管理文件 說明了這個連線。這會設定你的 Quickchat AI 帳號。它不會自動讓其他人把 Open Query 當作 MCP 工具使用。

常見問題

我可以用自然語言搜尋 Scryfall 嗎？

AI 助手可以把白話需求翻譯成 Scryfall 搜尋語法，並透過 Scryfall API 執行。本教學會在 Quickchat AI 中建立這個助手，並讓它顯示查詢、連結的卡牌記錄，以及相關的 Oracle 文字，讓你可以檢查它的解讀。

我需要 Scryfall API 金鑰嗎？

不需要。公開的卡牌搜尋端點不需要帳號或 API 金鑰。請傳送可識別的 User-Agent 與 Accept 標頭，遵守 Scryfall 的速率限制，並有意識地請求額外頁面。

這個 AI 卡牌查找器會憑空捏造卡牌嗎？

這些指示會把推薦限制在 Action 回傳的記錄內，並附上 Scryfall 連結。模型仍然可能出錯，所以在依賴這個助手之前，請檢查回傳的 ID 與 Oracle 文字，並測試一個不可能存在的卡名。

在 Scryfall 上，id<=g 和 id=g 有什麼差別？

id<=g 包含綠色與無色身分，適合在單綠指揮官的顏色範圍內搜尋。id=g 則要求顏色身分必須剛好是綠色。顏色身分不同於卡牌顏色。進行 Commander 牌組構築時，請使用身分篩選。

Scryfall 價格有保證嗎？

沒有。prices.usd 欄位是回傳版本的供應商價格資料，不是賣家的報價。它可能是 null。usd<5 篩選的是低於五美元，不代表運費、供貨情況，或可購買版本中的最低價格。

一次搜尋會回傳所有符合條件的卡牌嗎？

一次搜尋只會回傳一個 API 頁面。回應會包含 total_cards、has_more，以及在相關時提供 next_page。Open Query 會從已抓取的頁面中最多顯示五個推薦。你可以要求顯示該頁更多內容，或明確要求下一個 API 頁面。簡短名單不是完整結果集。

這能幫我建立整副 Commander 牌組嗎？

本教學建立的是卡牌搜尋助手。它幫助你為牌組中的某個位置尋找並檢視候選卡。它不會驗證完整的 100 張牌組、不會最佳化牌表，也不能取代規則裁判。