name: scryfall-mtg
description: "使用 Scryfall API 搜索和获取《万智牌》卡牌数据。当用户询问有关 MTG 卡牌、想通过名称、类别、颜色、法术力费用、规则文本、系列或其他卡牌属性搜索卡牌时，请使用此技能。也可用于获取卡牌图片、价格、规则解释、合法性信息或随机卡牌。触发词包括提及 MTG、Magic、Magic: The Gathering、卡牌名称、套牌构建问题或卡牌信息请求。"

Scryfall MTG 卡牌搜索

使用 Scryfall API 搜索《万智牌》卡牌。

API 概览

基础 URL: https://api.scryfall.com

必需请求头:

headers = {
    "User-Agent": "OpenClawMTGSkill/1.0",
    "Accept": "application/json"
}

速率限制: 请求间插入 50-100 毫秒延迟（最高 10 次请求/秒）。

核心端点

搜索卡牌

GET /cards/search?q={query}

参数:
- q (必需): 全文搜索查询
- unique: cards|art|prints (默认: cards)
- order: name|set|released|rarity|color|usd|tix|eur|cmc|power|toughness|edhrec|penny|artist|review
- dir: auto|asc|desc
- page: 分页页码

精确名称查找

GET /cards/named?exact={name}
GET /cards/named?fuzzy={name}

使用 fuzzy 进行模糊匹配（例如，"jac bele" → "Jace Beleren"）。
添加 &set={code} 可限制在特定系列中搜索。

随机卡牌

GET /cards/random
GET /cards/random?q={query}

按 ID 获取卡牌

GET /cards/{id}
GET /cards/{set_code}/{collector_number}

自动补全

GET /cards/autocomplete?q={partial_name}

返回最多 20 条卡牌名称建议。

搜索语法参考

完整搜索语法指南请参阅 references/search_syntax.md。

快速示例:
- c:red pow=3 - 力量为 3 的红色卡牌
- t:merfolk t:legend - 传奇人鱼
- o:"draw a card" - 规则文本中包含"抓一张牌"的卡牌
- cmc=3 r:rare - 总法术力费用为 3 的稀有牌
- e:dom - 多明纳里亚系列的卡牌
- f:standard - 标准赛制合法的卡牌
- usd<1 - 价格低于 1 美元的卡牌

实现方式

使用提供的脚本进行常见操作:

python3 scripts/scryfall_search.py search "lightning bolt"
python3 scripts/scryfall_search.py named --exact "Black Lotus"
python3 scripts/scryfall_search.py random
python3 scripts/scryfall_search.py random --query "t:dragon"

或使用正确的请求头和速率限制直接进行 API 调用。

卡牌对象关键字段

显示卡牌信息时，优先展示以下字段:
- name, mana_cost, type_line
- oracle_text, power, toughness
- image_uris.normal (用于卡牌图片)
- prices.usd, prices.usd_foil
- legalities (赛制合法性)
- set_name, rarity

对于双面牌，请检查 card_faces 数组。

错误处理

• 404: 卡牌未找到
• 422: 搜索查询无效
• 429: 超出速率限制（等待后重试）

始终验证响应是否包含 object 字段；如果 object: "error"，请检查 details 获取错误信息。