名称： scryfall-mtg
描述： "使用 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={查询}

参数：
- 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={名称}
GET /cards/named?fuzzy={名称}

使用 fuzzy 进行模糊匹配（例如 "jac bele" → "Jace Beleren"）。
添加 &set={系列代码} 可限定至特定系列。

随机卡牌

GET /cards/random
GET /cards/random?q={查询}

按 ID 获取卡牌

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

自动补全

GET /cards/autocomplete?q={部分名称}

返回最多 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 – 来自多明纳里亚系列的卡牌
- 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 获取错误信息。