Scryfall MTG 卡牌搜索

使用 Scryfall API 搜索《万智牌：指挥官》（Magic: The Gathering）卡牌。

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" —— 文本中包含 “draw a card” 的卡牌
• cmc=3 r:rare —— 法术力值为 3 的稀有卡牌
• e:dom —— 来自 Dominaria 系列的卡牌
• f:standard —— 在 Standard 赛制中合法的卡牌
• usd<1 —— USD 售价低于 $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 字段获取具体错误信息。