虽然现代 Web 指南旨在引导您采用“默认正确”的开发方法，但您有时可能会遇到代理激活、实现准确性或功能发现方面的问题。本部分提供了一些诊断步骤，可帮助您解决常见问题，例如确保 Modern Web 技能能够通过提示正确触发，或验证代码回退是否与项目的既定基准状态保持一致。如果您遇到持续的技术障碍或发现过时的指南，建议您提交问题，帮助我们确保这些资源的准确性和有效性。
诊断代理未使用 Modern Web Guidance 的问题
安装 Modern Web Guidance 后，系统会指示智能体将其用于任何 Web 开发任务。不过，客服人员有时会忽略这些说明。
您可以在提示末尾添加“使用 Modern Web Guidance”之类的短语，明确指示智能体使用 Modern Web Guidance。
某些代理还支持使用特定语法（例如 /modern-web-guidance 或 $modern-web-guidance，具体取决于代理）直接调用技能。
如果您不确定，请参阅代理的文档，或询问代理如何直接调用 modern-web-guidance 技能。
诊断“幻觉”代码或猜测的实现
这种情况很常见，LLM 会在没有警告的情况下填补知识空白。 为防止代理编造信息，我们发现将以下指令附加到提示中非常有用：
Bring up knowledge gaps and don't attempt to guess implementation. List them as open questions.
诊断未能触发特定指导的问题
如果您定位的是特定功能使用情形，但发现代理未发现该情形，请确保您的提示包含特定的关键字和锚定要求，以便代理能够正确发现该情形。 这有助于代理确定相关的指导轨道（例如：“视图转换”“LCP 优化”）。
跟踪智能体的思考过程：
- 检查输出，看看是否调用了
modern-web-guidance技能。 - 找到搜索调用（例如
npx -y modern-web-guidance@latest search "carousel scroll snap"），并确定关键字和生成的指南是否符合您的预期。 - 检查检索调用是否请求了相关指南，例如：
npx -y modern-web-guidance@latest retrieve "carousel-snap-highlights,carousel-slide-effects,scroll-snap-state-sync"。
Create a new folder and create a carousel web app for me that implements scroll-snap.
...
● Bash(npx -y modern-web-guidance@latest search "carousel scroll snap" --skill-version 2026_05_16-c5e7870)
⎿ [{"id":"carousel-snap-highlights","description":"Visually highlight the currently snapped non-interactive item in scroll-snapping carousels, galleries, or full-page swipe experiences. For example, expanding a card when snapped, or revealing hidden
content.","category":"user-experience","featuresUsed":["Container scroll-state queries"],"tokenCount":1442,"similarity":0.7783},
{"id":"carousel-slide-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"],"tokenCount":2105,"similarity":0.6625},
{"id":"scroll-snap-state-sync","description":"Synchronize navigation indicators, linked content panels, and analytics tracking with the actively snapped item in a scrollable container.","category":"user-experience","featuresUsed":["Scroll snap events","Scroll
snap"],"tokenCount":1053,"similarity":0.6166},
{"id":"scroll-snap-realtime-feedback","description":"Provide real-time visual feedback in linked UI elements while a user scrolls through snap-aligned content, before the scroll gesture completes.","category":"user-experience","featuresUsed":["Scroll snap events","Scroll
snap"],"tokenCount":1886,"similarity":0.5664},
{"id":"navigation-drawer","description":"Create a navigation drawer component that, when triggered from a menu button, slides in from the side overlayed on top of existing page content, and slides out when dismissed (by swiping away, tapping outside, or pressing
escape).","category":"user-experience","featuresUsed":["inert","Intersection observer","Popover","Registered custom properties","Scroll-driven animations","scroll-initial-target","Scroll snap"],"tokenCount":4317,"similarity":0.5099}]
● Bash(npx -y modern-web-guidance@latest retrieve "carousel-snap-highlights,carousel-slide-effects,scroll-snap-state-sync")
⎿ <output +158 lines>
}, undefined);
if (topEntry) setSelectedParagraph(topEntry.id);
},
{ root: main, threshold: 0.9 // Adjust based on your use case },
);
// Observe all snap targets (e.g., section headers)
document.querySelectorAll('h2').forEach(header => observer.observe(header));
}
- 您还可以在终端中自行运行搜索命令，查看哪些指南与您的搜索查询相符。
# Search for relevant guides
npx modern-web-guidance@latest search "carousel scroll snap"
反馈
如果您对这些新功能有任何其他问题或反馈，请先了解如何为“现代 Web 指南”做出贡献，然后再在我们的 GitHub 代码库中提交问题。创建问题时，请提供初始代理提示、代理思考过程的屏幕截图和日志，以及根据该思考过程推荐的最终代码更改。