ابنِ أداة بحث عن البطاقات بالذكاء الاصطناعي Commander باستخدام Scryfall

تقوم أداة البحث عن بطاقات Scryfall Commander بتحويل وصف البطاقة التي تحتاجها إلى عملية بحث يمكنك فحصها. في هذا الدرس، ستبني Open Query، وهو وكيل Quickchat AI يعرض استعلام Scryfall الخاص به، ويعيد سجلات بطاقات حقيقية، ويشرح لماذا قد يناسب كل مرشح مجموعتك.

ابدأ بموضع واحد في مجموعة Commander أحادية الأخضر. أنت تريد مخلوقًا لديه trample وسعره أقل من خمسة دولارات أمريكية. في النهاية، ستتمكن من كتابة هذا الطلب، وفتح البطاقات المعادة، وتنقيح البحث من دون حفظ كل عامل تشغيل.

يظهر الجزء المفيد عندما يصبح الطلب أصعب. تبدو عبارة “اسحب بطاقة عندما يدخل مخلوق آخر” دقيقة، لكن البحث عن الكلمتين enters وdraw يعثر أيضًا على بطاقات تفعل شيئًا آخر. سوف تلتقط هذا الاختلاف وتضيّق الاستعلام، مستخدمًا نص البطاقة المعاد بوصفه دليلًا.

ماذا ستبني، وماذا تحتاج؟

ستربط Scryfall بإجراء واحد من نوع API Action مخصص للقراءة فقط. بعد ذلك، ستمنح الوكيل التعليمات التي توضّح له كيف يبحث عن البطاقات، ثم تختبر الإعداد في محادثة. عنوان URL الذي يستدعيه الإجراء ثابت في الإعدادات، بينما يوفّر النموذج استعلام البحث ورقم الصفحة لكل طلب. يعيد Scryfall سجلات البطاقات، ويستخدم الوكيل تلك السجلات كأساس لإجابته.

1. أنشئ حساب Quickchat AI ووكيلًا باسم Open Query. تحتاج إلى أرصدة AI متاحة للمحادثات والاختبارات. راجع الخطط الحالية.
2. أبقِ Identity وActions & MCPs وAI Preview الخاصة بالوكيل متاحة أثناء العمل. لا حاجة إلى رفع مجموعة بطاقات.
3. استخدم واجهة API العامة الخاصة بـ Scryfall. لا تحتاج إلى حساب Scryfall أو مفتاح API لهذه العمليات البحثية.

تتضمن حزمة البداية ملف Main Prompt، ووصفة الإجراء، ومسارات مرشح الاستجابة، ورسائل الاختبار. تستخدم الأمثلة نص Oracle باللغة الإنجليزية وأسعار USD. أبقِ عوامل تشغيل الاستعلام وأسماء البطاقات كما هي مكتوبة عند المتابعة بلغة أخرى.

الخطوة 1: كيف تحوّل طلب بطاقة إلى استعلام Scryfall؟

يجمع استعلام Scryfall بين قيود تفصل بينها مسافات. لطلبنا الأول، استخدم:

f:commander id<=g t:creature kw:trample usd<5

هناك خياران صغيران مهمان. يبحث kw:trample عن الكلمة المفتاحية، بينما يبحث o:trample عن الكلمة في نص Oracle. قد تذكر بطاقة مخلوق trample من دون أن تمتلك هذه القدرة بنفسها. لقد اختبرنا الاثنين. وأنتج البحث النصي مجموعة أوسع.

تختلف عبارة “يناسب مجموعة أحادية الأخضر” أيضًا عن “له هوية خضراء بالضبط”. الأولى تسمح بالبطاقات عديمة اللون. استخدم id=g للحالة الثانية، أو id<=ur للبحث ضمن ألوان قائد أزرق أحمر. هذه قيود هوية، وليست تحققًا كاملًا من قانونية المجموعة.

يشرح مرجع صيغة البحث الخاص بـ Scryfall هذه العوامل. في هذا الدرس، أبقِ الاستعلام مرئيًا في كل إجابة حتى تتمكن من ملاحظة لون محذوف، أو عملة غير متوقعة، أو بحث أوسع من طلبك.

الخطوة 2: كيف تصل واجهة API الخاصة بـ Scryfall بوكيلك؟

أنشئ API Action واحدًا يرسل طلب GET إلى نقطة نهاية البحث عن البطاقات الخاصة بـ Scryfall. تختار إعداداته الثابتة المزوّد والترتيب. وتسمح معلمتاه للوكيل باختيار البحث والصفحة.

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، أضف هاتين المعلمتين المطلوبتين. يمكن للوكيل ملؤهما من المحادثة. ولا تعني التسمية أنه يجب عليه أن يطلب منك كتابة صيغة الاستعلام الخام.

اضبط نقطة النهاية ومعلمات الاستعلام والترويسات

اختر 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.

احفظ الإجراء وتحقق من أنه نشط. يشرح دليل بنية إجراء HTTP كيف تعمل المعلمات والطلب والوصف معًا.

الخطوة 3: كيف ينبغي لأداة البحث عن البطاقات أن تشرح نتائجها؟

يحتاج الوكيل إلى تعليمات لعرض استعلامه، وربط التوصيات بالسجلات المعادة، والتمييز بين تطابق كلمة وتفاعل قواعد. افتح 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، وهوية أخضر أو عديم اللون، ونوع المخلوق، وtrample، وسعر USD أقل من 5. افتح رابط Scryfall لإحدى البطاقات وقارن النص ذي الصلة والهوية والسعر مع الإجابة. السعر هو ملاحظة ناتجة عن الاستعلام للطبعة المعادة، وليس عرض سعر عند الدفع.

ترتّب نتائج API حسب الاسم، لا حسب مدى الملاءمة. يختار الوكيل قائمة مختصرة من الصفحة التي تم جلبها. يتجنب 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

في تحققنا المباشر من Scryfall بتاريخ 10 نوفمبر 2026، أعاد هذا 161 مرشحًا، بما في ذلك Abundant Growth. يحدث السحب فيه عندما تدخل الـ Aura نفسها. إنه يحتوي على الكلمتين كلتيهما، لكنه لا يوفّر محرك سحب متكررًا عند دخول المخلوقات كما يوحي الطلب.

جرّب هذا التنقيح:

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 وأنشئ مجموعة بيانات باسم Open Query checks باستخدام Create Dataset → Paste messages. الصق رسائل الاختبار المستقلة من الحزمة.
2. شغّل الاختبارات. وقيّم ما إذا كانت الإجابة تعرض استعلامها، وتستشهد بالبطاقات المعادة، وتشرح مواضع عدم اليقين.
3. افتح المحادثة المطابقة في Inbox وافحص استدعاء الإجراء. تحقّق من الاستعلام، ورقم الصفحة، والحالة، والحقول المعادة. استخدم عنصر التحكم View logs الخاص بالإجراء للعثور على الاستدعاءات الفردية.
4. اختبر التنقيح وترقيم الصفحات في محادثة مستمرة، حيث يكون الاستعلام السابق متاحًا.

بالنسبة لاختبار عدم وجود تطابق، أرسل:

Find a Commander card named definitely-not-a-real-card-xyz.

أظهر اختبار API مباشر واحد سبب أهمية التحذيرات. أعاد الاستعلام المشوّه f:commander o:/[/ حالة HTTP 200، لكن Scryfall أفاد بأنه تجاهل التعبير غير الصالح. لذلك كانت النتائج أوسع من المطلوب. احتفظ بهذا التحذير، واشرح المرشح الذي تم تجاهله، وصحّح الاستعلام قبل التوصية بهذه النتائج.

غطّت تشغيلات وكيلنا المحلي الحالة الأساسية، والتنقيح، والنتائج الفارغة، وبحثًا من صفحتين. وغطّت فحوصات API المنفصلة الأسعار المفقودة، وأوجه البطاقات، وتحذيرات الصيغة. استخدم بيئة اختبار مضبوطة لاختبار حدود المعدل من دون إرسال حركة زائدة.

تنص وثائق نقطة نهاية البحث عن البطاقات حاليًا على طلبي بحث في الثانية. أبقِ بين الطلبات ما لا يقل عن 500 milliseconds. هذا الدرس مساعد بحث شخصي. أما الروبوت العام الذي يخدم كثيرًا من اللاعبين فيحتاج إلى تحديد معدل مشترك وتخزين مؤقت. إن مطالبة النموذج بالإبطاء لا تفرض حدًا عالميًا للطلبات.

هل يمكن لـ ChatGPT أو Claude المساعدة في إعداد هذا؟

يمكنك استخدام إضافة Quickchat AI لـ ChatGPT أو موصل Quickchat AI لـ Claude لإعداد الوكيل عبر اتصال إدارة الحساب. أكمل تسجيل الدخول بنفسك، ثم قدّم هذا الدرس وحزمة البداية الخاصة به مع الطلب التالي:

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 باللغة الطبيعية؟

يمكن لمساعد ذكاء اصطناعي ترجمة طلب بصياغة عادية إلى صيغة بحث Scryfall وتنفيذه عبر واجهة Scryfall البرمجية. يبني هذا الدرس ذلك المساعد في Quickchat AI ويجعله يعرض الاستعلام، وسجلات البطاقات المرتبطة، ونص Oracle ذي الصلة حتى تتمكن من التحقق من التفسير.

هل أحتاج إلى مفتاح API لـ Scryfall؟

لا. نقطة نهاية البحث العامة عن البطاقات لا تتطلب حسابًا أو مفتاح API. أرسل ترويسات User-Agent وAccept التعريفية، واتبع حدود المعدل الخاصة بـ Scryfall، واطلب الصفحات الإضافية عن قصد.

هل يمكن لأداة البحث هذه بالذكاء الاصطناعي أن تهلوس بطاقة؟

تقيّد التعليمات التوصيات بالسجلات التي يعيدها الإجراء، مع روابط Scryfall. ومع ذلك، قد يظل النموذج يخطئ، لذا تحقّق من المعرّف المعاد ونص Oracle، واختبر اسم بطاقة مستحيل قبل الاعتماد على المساعد.

ما الفرق بين id<=g و id=g في Scryfall؟

يتضمن id<=g الهويات الخضراء وعديمة اللون، وهو مناسب للبحث ضمن ألوان قائد أحادي الأخضر. أما id=g فيتطلب هوية خضراء فقط. هوية اللون تختلف عن لون البطاقة. استخدم مرشح الهوية عند بناء مجموعة Commander.

هل أسعار Scryfall مضمونة؟

لا. الحقل prices.usd هو بيانات تسعير من المزوّد للطبعة المعادة، وليس عرضًا من بائع. وقد يكون null. يبحث المرشح usd<5 عن أقل من خمسة دولارات أمريكية. لكنه لا يثبت تكاليف الشحن أو التوفر أو أرخص طبعة يمكن شراؤها.

هل تعيد عملية بحث واحدة كل البطاقات المطابقة؟

تعيد عملية البحث صفحة API واحدة. تتضمن الاستجابة total_cards وhas_more وnext_page عند الاقتضاء. يعرض Open Query ما يصل إلى خمس توصيات من الصفحة التي تم جلبها. اطلب المزيد من تلك الصفحة أو اطلب صراحة صفحة API التالية. القائمة المختصرة ليست مجموعة النتائج الكاملة.

هل يمكن لهذا أن يبني مجموعة Commander كاملة لي؟

يبني هذا الدرس مساعدًا للبحث عن البطاقات. وهو يساعد في العثور على المرشحين لموضع في المجموعة وفحصهم. لكنه لا يتحقق من مجموعة كاملة من 100 بطاقة، ولا يحسّن قائمة مجموعة، ولا يحل محل حكم قواعد.