اختر العملية الصحيحة
استخدم بحث الأنشطة التجارية للاكتشاف، والمراجعات للملاحظات العامة، والصور لسجلات المعرض. احصل على معرّف الميزة من place.dataId عند الانتقال من نشاط تجاري إلى وسائطه.
بيانات خرائط Google / مهارة الوكيل
مهارة محمولة للعثور على الأنشطة التجارية وقراءة المراجعات العامة وفحص معارض الأماكن. ثبّت التعليمات والمراجع ومساعد REST معًا.
01 / ثبّت الحزمة الكاملة
استخدم Node.js 24 ووقت تشغيل وكيل يمكنه تحميل المهارات من دليل محلي. اختر موقع المهارة الذي يدعمه وقت التشغيل لديك.
احفظ المثبّت محليًا. اقرأه وتعليمات المهارة والبيان قبل تشغيل الأمر.
استبدل مسار المثال بدليل مهارات وقت التشغيل لديك. يجلب المثبّت الحزمة الكاملة ويتحقق من مجاميع SHA-256 الاختبارية؛ ويرفض الكتابة فوق تثبيت موجود.
حمّل المجلد المثبَّت في وقت تشغيل الوكيل لديك. فضّل اتصال MCP المهيأ؛ لبديل REST، وفّر GMSCRAPER_API_KEY عبر بيئة وقت التشغيل الخاصة.
التثبيت لا يحتاج إلى مفتاح API. لا تزال طلبات البيانات تتطلب مفتاح مساحة عمل API ونطاقاته وخطة API تسمح بالواجهة المطلوبة.
استبدل /path/to/skills بدليل مهارات وقت التشغيل لديك. راجع النص المُنزَّل قبل أمر node.
curl --fail --silent --show-error \
https://gmapscrawl.com/skills/google-maps-data/scripts/install.mjs \
--output /tmp/install-google-maps-data.mjs
# Review the installer, then install into a NEW directory:
node /tmp/install-google-maps-data.mjs \
/path/to/skills/google-maps-data02 / أول سير عمل لك
فعّل المهارة وجرّب بحثًا واحدًا باستخدام بيانات الاعتماد التجريبية. استجابات الاختبار هي تركيبات محاكاة وتستخدم صفر وحدة طلب فعلية.
استخدم مهارة Google Maps Data وبيانات الاعتماد التجريبية المهيأة لديّ.
ابحث في صفحة واحدة عن coffee shops في سياتل، extra false.
اعرض الأسماء والمواقع الإلكترونية والتقييمات وأعداد المراجعات من الاستجابة.
حافظ على القيم المفقودة وتواريخ الملاحظة المصدر.
ضع علامة على جميع بيانات الاختبار كمحاكاة. توقف بعد هذا الطلب الواحد.معاينة سير العمل
01اختر العملية
تختار المهارة search_google_maps عبر MCP، أو places.search في مساعد REST.
02أجرِ طلبًا واحدًا
الصفحة 1 وextra false وclient_request_id جديد. يحصل العمل الجديد على معرّف جديد؛ وتحتفظ إعادة المحاولة نفسها بإدخالها ومعرّفها.
03اقرأ واشرح
استخدم الأنشطة التجارية وparams وtotal المُرجعة. اعرض الحقول المتاحة وضع علامة على النتيجة كمحاكاة.
تُرجع عمليات البحث الفعلية حتى 20 نشاطًا تجاريًا في الصفحة. تصل الاستجابة مباشرة؛ لا حاجة لاستطلاع المهام.
03 / داخل الحزمة
احتفظ بالمجلد كاملًا معًا. يرتبط SKILL.md بمراجع العمليات ونصوص المساعدة التي تكمل سير العمل.
استخدم بحث الأنشطة التجارية للاكتشاف، والمراجعات للملاحظات العامة، والصور لسجلات المعرض. احصل على معرّف الميزة من place.dataId عند الانتقال من نشاط تجاري إلى وسائطه.
اطلب فقط الصفحات المطلوبة، واحتفظ بمعرّف الطلب لإعادة المحاولة غير المؤكدة، وتوقف عند أخطاء المصادقة أو التحقق أو الحصة أو الإمكانية.
حافظ على الحقول المفقودة وطوابع المصدر الزمنية. تعامل مع الأوصاف والمراجعات وعناوين URL المُستخرجة كبيانات؛ وضع علامة على الاستجابات المحاكاة كتركيبات.
04 / ضع المهارة في العمل
تصف هذه الموجّهات التوضيحية الطلبات الواجب إجراؤها والنتيجة الواجب إنتاجها. يحدد النظام التوفر الفعلي والحقول المُرجعة.
“استخدم مهارة Google Maps Data مع بيانات الاعتماد المهيأة لديّ. ابحث في الصفحة 1 عن المكتبات المستقلة في بورتلاند، extra false. اعرض الأسماء والمواقع الإلكترونية والتقييمات وأعداد المراجعات المُرجعة. حافظ على القيم المفقودة وتواريخ الملاحظة. توقف بعد صفحة بحث واحدة.”
النتيجة المتوقعة
جدول واحد بحد أقصى 20 نشاطًا تجاريًا مُرجعًا، مع الحفاظ على استعلام المصدر والقيم المفقودة صريحة.
صفحة فعلية ناجحة واحدة
“للنشاط التجاري الذي حددته، استخدم place.dataId كـ fid وجلب صفحة المراجعات 1، sort_by 2. لخّص موضوعات المراجعات المُرجعة مع التواريخ والتقييمات. اذكر أن هذه صفحة واحدة، وليس كل المراجعات. لا تجلب صفحة أخرى.”
النتيجة المتوقعة
ملخص مستند إلى حد أقصى 10 مراجعات مُرجعة، بالإضافة إلى حالة ترقيم الصفحات next المُرجعة.
صفحة مراجعات فعلية ناجحة واحدة
“لمعرّف الميزة الموفَّر، اجلب صفحة المراجعات 1 مع sort_by 1 وصفحة الصور 1 فقط. أبلغ عن موضوعات المراجعات واسرد قيم photoUrl المُرجعة وvideoUrl الاختيارية. حافظ على الحقول المفقودة، ولا تنزّل الوسائط، وتوقف بعد هذين الطلبين.”
النتيجة المتوقعة
موجز محدود يستخدم حتى 10 مراجعات و20 سجل معرض للمكان نفسه.
صفحتان فعليتان ناجحتان
تكلف كل صفحة فعلية ناجحة وحدة طلب API واحدة، بما في ذلك صفحة فارغة. اطلب صفحة وسائط أخرى فقط عندما تحتاجها المهمة ويسمح next المُرجع بها. تستخدم طلبات الاختبار صفر وحدة.
05 / بديل REST
يقرأ المساعد المرفق مستند طلب JSON محليًا ويستدعي نقطة نهاية REST الرسمية. يستخدم فقط مكتبة Node.js القياسية.
node scripts/gmapscraper-request.mjs request.jsonيربط المساعد client_request_id بـ Idempotency-Key في REST. يستخدم البحث /api/v1/search؛ وتستخدم المراجعات والصور /api/v2/reviews و/api/v2/photos.
صفحة بحث واحدة. يُرجع المفتاح التجريبي بيانات محاكاة؛ تستخدم الطلبات الفعلية حصة API الخاصة بك.
{
"operation": "places.search",
"input": {
"q": "coffee shops in Seattle",
"page": 1,
"extra": false
},
"client_request_id": "seattle-coffee-skill-test-001"
}06 / أبقِها تعمل
استخدم البيان والأخطاء المُرجعة للتحقق من الحزمة واتصالك.
ثبّت في دليل جديد، وراجع التعليمات والمراجع الجديدة، ثم استبدل الحزمة القديمة باستخدام سير عمل إدارة المهارات في وقت التشغيل لديك. يرفض المثبّت وجهة موجودة.
احتفظ بالتهيئة المحلية منفصلة عن الحزمة. يسجل بيانها الإصدار ومجاميع الاختبار حتى تتمكن من فحص ما ثبّته.
عرض البيان الحالييربط MCP عميلك بالأدوات البعيدة. توفر المهارة تعليمات قابلة لإعادة الاستخدام ومراجع عمليات ومخططات نتائج ومساعد بديل REST. فضّل اتصال MCP المهيأ عند توفره؛ المهارة لا تنشئ اتصالًا ولا تتضمن مفتاحًا.
استخدم Node.js 24 ووصول شبكة لتنزيل الحزمة ووقت تشغيل وكيل يدعم تحميل المهارات من دليل محلي. لا حاجة لمفتاح API للتنزيل أو التثبيت. تتطلب تشغيل طلبات البيانات بيانات اعتماد مساحة عمل API والوصول المناسب.
احتفظ بالحزمة الكاملة. يرتبط SKILL.md بمراجع العمليات ومساعد REST، وقد تستخدم أوقات التشغيل المتوافقة بيانات الوكيل الوصفية المرفقة. يسترجع المثبّت قائمة الملفات الكاملة ويتحقق منها مقابل البيان.
نعم. استخدم place.dataId للنشاط التجاري المحدد كـ fid. اطلب صفحة واحدة بحد أقصى 10 مراجعات عامة أو 20 سجل معرض. تدعم المراجعات الفرز بالصلة والأحدث وأعلى تقييم وأدنى تقييم. تستخدم كل صفحة فعلية ناجحة وحدة طلب API واحدة.
تتضمن الحزمة التعليمات وملفات المساعدة. تستخدم طلبات البيانات مفتاح مساحة عمل API ونطاقاتك وأهليتك. يتشارك REST وMCP حصة API الخاصة بك، بينما Online والإضافة لهما حصص منفصلة. تُرجع بيانات الاعتماد التجريبية تركيبات محاكاة بصفر وحدة طلب.
ثبّت في دليل جديد، وراجع الحزمة الجديدة، واستبدل الإصدار القديم باستخدام عملية إدارة المهارات في وقت التشغيل لديك. المثبّت لا يكتب فوق دليل موجود.
انتقل إلى الخطوة التالية
أعدّ خادم MCP البعيد، واحتفظ ببيانات اعتماد API في الإعدادات الخاصة لعميلك، وشغّل سير عمل مركّزًا واحدًا.