Хотя руководство по современной веб-разработке призвано приблизить вашу разработку к подходу «правильно по умолчанию», вы можете иногда сталкиваться с проблемами активации агента, точностью реализации или обнаружением функций. В этом разделе представлены диагностические шаги, которые помогут вам решить распространенные проблемы, такие как обеспечение правильного запуска навыка современной веб-разработки в ответ на ваши запросы или проверка соответствия резервных вариантов кода установленному базовому статусу вашего проекта. Если вы столкнетесь с постоянными техническими трудностями или обнаружите устаревшие рекомендации, мы рекомендуем вам сообщить о проблеме, чтобы помочь нам поддерживать точность и эффективность этих ресурсов.
Диагностика проблемы: агент не распознает Modern Web Skill.
Любой агент, установивший расширение навыка, сможет активировать его, используя «современное веб-руководство» тем или иным способом, но если по какой-либо причине у используемого вами агента возникнут трудности, вы можете вызвать его напрямую следующим образом:
/modern-web-guidance <your prompt>
Это применимо к средам разработки с поддержкой ИИ, которые принимают 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"
Диагностика отсутствия резервных вариантов для определенных функций веб-браузера.
Это зависит от статуса базовой версии, установленного в вашем проекте. Если API был выпущен совсем недавно, у агента может не быть эквивалентного резервного варианта, или же эта функция доступна в рамках «базовой версии» достаточно давно, поэтому резервные варианты или полифилы могут быть не нужны.
Диагностика смещения, вызванного устаревшими обучающими данными.
Если агент предлагает более старую библиотеку вместо современного API браузера, это, вероятно, означает либо использование базовых обучающих данных, либо то, что ваш базовый статус еще не поддерживает эту функцию, и был реализован резервный вариант.
Для дополнительной проверки вы можете принудительно установить приоритет для соответствующего навыка, явно выполнив поиск в библиотеке руководств с помощью командной строки:
# Search for a specific feature
npx modern-web-guidance search "<feature>"
Диагностика устаревших рекомендаций
Крайне важно, чтобы наша информация была актуальной, поэтому мы просим вас сообщать о проблемах в репозитории, если вы обнаружите, что код, реализованный на основе руководства, устарел. При этом убедитесь, что рекомендации агента основаны на навыке modern-web разработки и его руководствах, а не на базовых обучающих данных модели LLM, которую может использовать ваша IDE с поддержкой ИИ.
В окне агента или терминале вы можете отслеживать ход его мыслей, а также попросить его сообщить, как он пришел к выводу об изменении кода. Как только вы убедитесь, что это действительно связано с навыком, передайте нам эту обратную связь и подтверждающие данные.
Обратная связь
Если у вас возникли дополнительные вопросы или замечания по поводу этих новых функций, сначала ознакомьтесь с информацией о том, как внести свой вклад в Modern Web Guidance , прежде чем создавать заявку в нашем репозитории Github. При создании заявки укажите первоначальные подсказки агента, скриншоты и журналы процесса обдумывания агентом, а также рекомендуемое окончательное изменение кода, основанное на этом процессе.