تحديد المشاكل وحلّها في "إرشادات الويب الحديث"

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

تشخيص عدم رصد الوكيل لمهارة "الويب الحديث"

يجب أن يكون بإمكان أي طلب تم تثبيت إضافة المهارة من خلاله تفعيلها عن طريق تضمين عبارة "إرشادات الويب الحديث" بطريقة ما، ولكن إذا كان الوكيل الذي تستخدمه يواجه صعوبة لسبب ما، يمكنك استدعاؤها مباشرةً على النحو التالي:

/modern-web-guidance <your prompt>

ينطبق ذلك على بيئات التطوير المتكاملة (IDE) المستندة إلى الذكاء الاصطناعي والتي تقبل npx skills add <skill-extension>.

تشخيص الرموز البرمجية "المختلَقة" أو عمليات التنفيذ المخمّنة

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

Bring up knowledge gaps and don't attempt to guess implementation. List them as open questions."

تشخيص تعذُّر عرض إرشادات معيّنة

إذا كنت تستهدف حالة استخدام ميزة معيّنة ولم تلاحظ أنّ الوكيل يكتشفها، تأكَّد من أنّ طلباتك تتضمّن كلمات رئيسية ومتطلبات ربط محدّدة لضمان إمكانية اكتشافها بشكل صحيح. يساعد ذلك الموظّف في تحديد مسار الإرشادات المناسب (على سبيل المثال: "عمليات الانتقال بين الصفحات" أو "تحسين مقياس سرعة عرض أكبر محتوى مرئي (LCP)").

/modern-web-guidance Execute LCP optimization against my Progressive Web App.

تتبُّع عملية التفكير لدى الوكيل:

• اتّبِع ما إذا كان قد اكتشف مهارة "إرشادات الويب الحديث" (على سبيل المثال، modern-web/SKILL.md).
• ابحث عن طلب البحث، مثل node modern-web.mjs search "scroll snap"، وحدِّد ما إذا كانت الكلمات الرئيسية والأدلة الناتجة هي ما توقعته. الدليل الأعلى ترتيبًا في نتائج البحث هو الدليل الذي تم اختياره لتطبيقه على طلبك.

/modern-web-guidance Create a new folder and create a carousel web app for me that implements scroll-snap.

...

● Bash(node --experimental-strip-types serving/bin/modern-web.ts search "carousel scroll-snap")
  ⎿  [{"id":"carousel-item-effects","description":"Create a carousel of slides with images or other visual elements, where each slide animates as they enter/center/exit their scroller. For example, the slides may fade-in/fade-out, rotate, get bigger or smaller, etc.","category":"user-experience","featuresUsed":["Scroll-driven animations","Scroll snap"]},
            {"id":"light-dismiss-content-overlay","description":"Create swipeable layered navigation menus using native overlays and scroll gestures.","category":"user-experience","featuresUsed":["Popover","Scroll snap","inert"]},
            {"id":"scroll-target-on-load","description":"Build a scrollable list of elements (e.g. a carousel of images or a chat conversation thread) that can be displayed with a particular element scrolled into view on the initial render.","category":"user-experience","featuresUsed":["scroll-initial-target","scrollIntoView()"]},
            {"id":"parallax-scroll-effects","description":"Create scroll-based effects (such as parallax) where foreground and background layers move at different rates, creating a sense
            of depth as the user scrolls.","category":"user-experience","featuresUsed":["Scroll-driven animations"]},
            {"id":"pull-to-reveal","description":"Build a pull-to-reveal feature that would enable the user to pull down on the screen to reveal more content, like a search bar.", "category":"user-experience","featuresUsed":["scroll-initial-target","Scroll snap"]}]

...

▾ Thought for 1s
  Ah, let's look at the actual folder names under `guides/user-experience/` that we listed earlier to find the exact ID mapping.
  Let's see the folders we found earlier:
  - `carousel-slide-effects`
  - `carousel-snap-highlights`
  - `scroll-snap-realtime-feedback`
  - `scroll-snap-state-sync`

  Ah! The ID in the filesystem is `carousel-slide-effects`, while the search index returns `carousel-item-effects`.

• نفِّذ أمر البحث عن الأدلة ذات الصلة بنفسك:

# Search for relevant guides
npx modern-web-guidance@latest search "scroll snap"

تحديد المشاكل وحلّها في عمليات الرجوع إلى الإصدارات السابقة لبعض ميزات متصفّح الويب

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

تشخيص الانحياز في بيانات التدريب القديمة

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

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

# Search for a specific feature
npx modern-web-guidance search "<feature>"

تشخيص الإرشادات القديمة

من المهم للغاية أن تكون معلوماتنا محدَّثة، لذا نرجو منك إبلاغنا عن أي مشكلة في المستودع إذا عثرت على رمز تم تنفيذه من دليل وكان قديمًا. عند إجراء ذلك، اجمع أدلة على أنّ المعلومات التي يقترحها عليك الوكيل مأخوذة من مهارة modern-web وأدلتها وليس من بيانات التدريب الأساسية من نموذج LLM الذي قد تستخدمه بيئة التطوير المتكاملة المستندة إلى الذكاء الاصطناعي.

في نافذة الوكيل أو الجهاز، قد تتمكّن من تتبُّع عملية التفكير، ولكن يمكنك أيضًا أن تطلب منه إعلامك بكيفية التوصّل إلى استنتاج تغيير الرمز. بعد التأكّد من أنّ الملاحظات واردة من المهارة، يُرجى إرسالها إلينا مع الأدلة.

الملاحظات

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