使用 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 密钥。

入门套件包含 Main Prompt、Action 配方、响应过滤路径和测试消息。示例使用英文 Oracle 文本和美元价格。若你用其他语言跟做，请保持查询运算符和卡名按原样书写。

第 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. 使用下面的构建器请求，然后根据配方检查生成的设置。API Action 构建器指南解释了生成和检查流程。
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 按你的预期解释了每个子句。卡牌对象参考描述了这些字段。

在 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 结构指南解释了参数、请求和描述如何协同工作。

第 3 步：卡牌查找器应该如何解释结果？

Agent 需要说明来展示它的查询、把推荐建立在返回记录之上，并区分词语匹配和规则互动。打开 Identity → Main Prompt，粘贴入门套件中的完整提示词，内容如下。

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。请自行完成登录，然后连同本教程和它的入门套件一起提供以下请求：

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 张牌组，不会优化牌表，也不能替代规则裁判。