Modern Web Guidance

Modern Web Guidance 是面向 Web 应用编程智能体的开源 Skill 与 CLI。它将 Web 平台指南、兼容性语境和可落地的实现模式放进 Agent 可检索的上下文，帮助模型优先选择当前原生 API，而不是惯性地加入旧库、polyfill 或大量 JavaScript 替代方案。项目由 Chrome、Edge、Mozilla 和 MDN 团队与 Web 开发社区共同维护。它用于辅助实现和评审，不能代替在目标浏览器与辅助技术中的实际测试。

它提供什么

• 可搜索的 Agent 指南：在受支持的编程 Agent 环境安装 Skill 后，先搜索具体 UI 或平台任务，再取回聚焦的指南。
• 现代化扫描器：npx modern-web-guidance@latest legacy-scan . 可静态识别已支持的旧模式，并将每个发现映射到建议采用的现代方案。
• 经过整理的覆盖范围：1.0 版本覆盖 250 项 Web 平台特性中的 203 个使用场景，包括 CSS 布局、表单、无障碍、性能、UI 组件、PWA、安全和浏览器内置 AI API。
• 兼容性意识工作流：刚发布或单引擎的易变特性在取回前需要明确 opt-in，可避免实验性 API 被悄悄当成生产建议。

实用工作流

在分支或干净检出中运行 CLI。先用 legacy-scan 收集机械化候选项，再在修改前打开每条关联指南。新功能应以具体原语搜索，例如“确认模态对话框”，而不是模糊的产品需求；取回结果后，再根据项目的浏览器支持策略实现。最后以项目测试、无障碍检查和真实目标浏览器验证结果。指南无法判断某项回退、分析需求或框架集成是否适合你的产品。

适用位置

当 Agent 要处理训练数据中积累了许多历史写法的前端代码时，Modern Web Guidance 特别有帮助。它可与用于验证的 Playwright Automation 和用于 UI 质量检查的 ai-design-check 配合。它不是组件库，不提供视觉设计系统，也不能替代团队自己的设计 token 与支持矩阵；与通用代码助手相比，它聚焦于 Web 平台决策。

局限与安全采用

仓库公开的评测结果可作为项目材料，不能保证对某个模型、框架或浏览器基线同样有效。应把扫描发现当作评审提示，尤其是旧模式可能出于跨浏览器行为、产品分析或安全原因而存在时。不要仅因指南提到实验 API 就启用它；应检查浏览器状态、用户影响和回退路径。在受管环境中，Skill 更新也应像其他开发依赖一样固定或审阅。

如何开始

运行 npx modern-web-guidance@latest install，选择所用的编程 Agent 集成。先在一个范围受控的组件上搜索或扫描，做最小且可审阅的修改，再在用户实际使用的浏览器中比较结果。这样既能获得现代实现选择，又不会把 Skill 变成未经审阅的代码生成来源。

常见问题

它能替代浏览器测试吗？

不能。它提供实现建议和静态检查，浏览器、无障碍、性能与产品测试仍然必要。

它只适用于 Chrome 吗？

不是。项目称由 Edge、Mozilla 和 MDN 贡献者共同维护，但每项特性仍应按自己的浏览器支持政策核验。

总结

Modern Web Guidance 让编程智能体能以紧凑、可复核的方式查找当前 Web 平台模式。先从小范围扫描或明确的 UI 任务开始，并把正常工程验证保留为最终决策依据。