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={查询语句}

参数:
- 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 获取错误信息。