اگرچه هدف راهنمای وب مدرن، حرکت توسعه شما به سمت رویکردی «صحیح به طور پیشفرض» است، اما ممکن است گاهی اوقات با مشکلاتی در فعالسازی عامل، دقت پیادهسازی یا کشف ویژگیها مواجه شوید. این بخش مراحل تشخیصی را برای کمک به شما در حل چالشهای رایج ارائه میدهد، مانند اطمینان از اینکه مهارت وب مدرن به درستی توسط درخواستهای شما فعال میشود یا تأیید اینکه کدهای جایگزین با وضعیت پایه تعیینشده پروژه شما همسو هستند. اگر با موانع فنی مداوم مواجه شدید یا راهنماییهای قدیمی را شناسایی کردید، شما را تشویق میکنیم تا یک مشکل را ثبت کنید تا به ما در دقیق و مؤثر نگه داشتن این منابع کمک کنید.
تشخیص عدم انتخاب Modern Web Skill توسط نماینده
هر اعلانی که افزونه مهارت را نصب کرده باشد، باید بتواند آن را با استفاده از «راهنمای وب مدرن» به نحوی فعال کند، اما اگر به هر دلیلی عاملی که استفاده میکنید با مشکل مواجه است، میتوانید مستقیماً آن را به این صورت فراخوانی کنید:
/modern-web-guidance <your prompt>
این مورد برای IDE های مبتنی بر هوش مصنوعی که npx skills add <skill-extension> میپذیرند، قابل اجرا است.
تشخیص کد «توهمآلود» یا پیادهسازیهای حدسی
این یک اتفاق رایج است که در آن مدل LLM بدون هشدار، شکافهای دانش را پر میکند. برای جلوگیری از اختراع اطلاعات توسط عامل، دریافتیم که افزودن دستورالعمل زیر به درخواستهای شما بسیار مفید است.
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 Guidance (برای مثال،
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"
تشخیص عدم وجود fallback برای برخی از ویژگیهای مرورگر وب
این به وضعیت پایهای که در پروژه خود تنظیم کردهاید بستگی دارد. اگر API به تازگی منتشر شده باشد، ممکن است عامل جایگزین معادلی برای تکیه بر آن نداشته باشد، یا این ویژگی به مدت طولانی به صورت "Baseline Widely" در دسترس بوده است که ممکن است نیازی به جایگزینها یا polyfillها نباشد.
تشخیص سوگیری دادههای آموزشی قدیمی
اگر عامل به جای یک API مرورگر مدرن، یک کتابخانه قدیمیتر را پیشنهاد دهد، احتمالاً یا به دادههای آموزشی پایه خود متکی است یا وضعیت پایه شما طوری پیکربندی شده است که هنوز از آن ویژگی پشتیبانی نمیکند و جایگزین پیادهسازی شده است.
برای بررسی مجدد، میتوانید با جستجوی صریح کتابخانه راهنما با استفاده از رابط خط فرمان (CLI)، مهارت را مجبور به اولویتبندی کنید:
# Search for a specific feature
npx modern-web-guidance search "<feature>"
تشخیص راهنماییهای منسوخشده
بهروز بودن اطلاعات ما از اهمیت بالایی برخوردار است، بنابراین از شما خواهشمندیم در صورت مشاهدهی کدی که از یک راهنما پیادهسازی شده و قدیمی است، مشکل را در مخزن ثبت کنید. هنگام انجام این کار، شواهدی جمعآوری کنید که نشان دهد نماینده به شما از مهارت modern-web و راهنماهای آن توصیه میکند، نه از دادههای آموزشی پایه از مدل LLM که IDE مبتنی بر هوش مصنوعی شما ممکن است از آن استفاده کند.
در پنجره یا ترمینال عامل خود، ممکن است بتوانید تفکر آن را پیگیری کنید، اما همچنین میتوانید از آن بخواهید که به شما اطلاع دهد که چگونه به نتیجه تغییر کد رسیده است. هنگامی که به این نتیجه رسیدید که واقعاً از مهارت است، آن بازخورد و شواهد را برای ما ارسال کنید.
بازخورد
اگر در مورد این ویژگیهای جدید سؤال یا بازخورد دیگری دارید، ابتدا قبل از ثبت مشکل در مخزن گیتهاب ما، در مورد نحوه مشارکت در Modern Web Guidance مطالعه کنید . هنگام ایجاد مشکل، دستورالعملهای اولیه عامل، تصاویر و گزارشهای فرآیند تفکر عامل و تغییر کد نهایی توصیه شده بر اساس آن تفکر عامل را ارائه دهید.