一天一个开源项目（第259篇）：Modern Web Guidance —— Chrome 团队给 AI 编码 Agent 的「现代 Web 最佳实践」外挂

引言

「Keep your coding agent up to date with the latest web best practices.」

这是「一天一个开源项目」系列的第 259 篇 。今天的项目是 GoogleChrome 的 Modern Web Guidance。

让 AI 写前端，经常会遇到一个别扭的现象：它写出来的东西能跑，但很「旧」。弹窗自己用 JavaScript 去算位置，浏览器早就有原生方案；动画和无障碍靠一堆库兜底，平台本身已经支持。原因很直接，模型的训练数据里，老代码远多于新写法。

这个项目的思路是：不去改模型，而是在 Agent 工作时，把经过筛选的现代 Web 指南喂进它的上下文。更有意思的是，它不止提供内容，还自带一套评测流水线，用数据说明「喂了指南」到底有没有用。本文基于 README 和仓库文档整理，我没有安装并实际跑过这些命令。

你将学到什么

Modern Web Guidance 解决什么问题，和直接让模型「自己查文档」有什么不同
search 与 retrieve 两步检索是怎么工作的，为什么能离线运行
它怎么处理新特性的兼容性风险：渐进增强、降级方案和「门控」
项目自带的评测流水线，以及官方公布的提升数据怎么读
怎么安装到 Claude Code、Codex 等不同 Agent 里

前置知识

用过 Claude Code、Codex 或类似的 AI 编码 Agent，了解 Skill 的概念
对前端和浏览器 API 有基本认识
可选：了解 Baseline（浏览器兼容性基线）

项目背景

项目简介

Modern Web Guidance 是一组把 Web 平台知识、最佳实践和浏览器兼容性数据送进 AI 编码 Agent 的 Skill。README 说它由 Chrome、Edge、Firefox、MDN 团队以及更广泛的 Web 社区共同维护。

要注意仓库的分工：本文链接的 modern-web-guidance-src 是源码仓库 ，放指南原稿、脚本、评测框架、基础示例应用和 CLI 工具，所有 Issue 和 PR 都提交在这里；另一个 GoogleChrome/modern-web-guidance 是只读的发布仓库 ，存放编译好的 Skill 和插件配置。合并后的改动每周发布到发布仓库和 npm 包 modern-web-guidance。

项目数据

⭐ GitHub Stars：约 4,045
🍴 Forks：约 238
💻 语言：TypeScript
📅 创建时间：2026-01-27，最近一次推送为 2026-11-13，仍在活跃更新
📄 许可证：代码为 Apache-2.0；guides/ 下的指南内容为 CC-BY 4.0
👤 维护方：GoogleChrome，README 称由 Chrome、Edge、Firefox 与 MDN 团队共同维护
🔗 文档：developer.chrome.com 上有专门页面（见项目地址）

主要功能

它解决的问题

objectivec 复制代码

没有指引时：
  Agent 凭训练数据写代码 → 偏向老写法、重 JavaScript、多余的库
  ↑ 即使知道某个 API 存在，也缺少足够多的现代真实示例

有指引时：
  Agent 遇到 Web 平台问题 → 调用 CLI 检索 → 拿到精选指南
  ↓ 指南里有代码模式、坑点、降级方案
  ↑ 产出更接近现代、可用于生产的写法

快速开始

交互式安装：

bash 复制代码

npx modern-web-guidance@latest install

不安装，直接试用三个子命令：

bash 复制代码

# 按描述搜索最匹配的指南
npx modern-web-guidance@latest search "animate a dialog modal backdrop"

# 按 ID 取回指南全文
npx modern-web-guidance@latest retrieve "animate-to-from-top-layer"

# 扫描当前项目里的老写法
npx modern-web-guidance@latest legacy-scan .

安装后，Agent 在处理相关任务时会激活 modern-web-guidance 这个 Skill，并被要求遇到 Web 平台问题就走 CLI。更新用 npx modern-web-guidance@latest update。

其他安装方式

README 给了多个工具的安装入口：

工具	命令或方式
Vercel Skills CLI	`npx skills add GoogleChrome/modern-web-guidance`
GitHub CLI	`gh skill install GoogleChrome/modern-web-guidance`
OpenAI Codex	`codex plugin marketplace add GoogleChrome/modern-web-guidance`，再 `codex plugin add modern-web-guidance@googlechrome`
Claude Code	通过插件市场安装，之后在 `/plugin` 里开启自动更新并 `/reload-plugins`
GitHub Copilot CLI	`/plugin marketplace add`，再 `/plugin install modern-web-guidance@googlechrome`
Google Antigravity	`agy plugin install <仓库地址>`
Grok Build CLI	`grok plugin install <仓库地址> --trust`
Kimi Code	`/plugins install <仓库地址>`

另外有两个 Skill 包可选，用 install --choose 挑选：modern-web-guidance（浏览器 API、布局、性能）和 chrome-extensions（Manifest V3、Worker、扩展 API、商店发布）。

内容覆盖范围

README 列出的规模是：250 个现代 Web 特性 （CSS 与布局 140 个、HTML 与 DOM 36 个、JavaScript 与 API 74 个），以及 203 个真实开发场景 。指南按类别组织：accessibility、built-in-ai、css、forms、html、js、performance、privacy、pwa、security、ui-atoms、ui-behaviors、ui-components、user-experience、visual-design、wasm、webmcp。发布仓库里指南路径形如 skills/modern-web-guidance/guides/ui-components/navigation-drawer.md。

项目详细剖析

两步检索：先 search，再 retrieve

激活：Agent 在相关任务里启用 Skill，被告知用 CLI 回答 Web 平台问题
search：用一个离线、零依赖的嵌入模型加 BM25，把自然语言查询匹配到最合适的指南，不联网、不需要 API Key
retrieve：按指南 ID 把代码模式、坑点和降级方案放进 Agent 的上下文

npm 包是自包含的，没有额外依赖，README 的说法是为了低延迟和供应链安全。用 npx 则是为了让内容不过期，同时 CLI 本身可以离线运行。

安全采用新特性的几条原则

新 API 的最大风险是兼容性。项目把「怎么安全地用」写成了几条规则：

渐进增强：纯增量的特性，旧浏览器静默忽略即可；影响关键行为的，要给出经过考虑、开销低的降级方案
优先轻量降级：自定义降级代码控制在 50 行以内，或者有条件地加载 polyfill，而不是引入重型依赖
记录坑点 ：例如 fetchLater() 有 64KB 的负载配额，以及 macOS 上特有的滚动条行为
基于 Baseline：用 Baseline 兼容性数据，让 Agent 按当前的真实支持情况调整
门控：对 Origin Trial 或不稳定特性（最近 3 个月内只在单一引擎发布，或仍在稳定中），search 能搜到，但 retrieve 默认需要开发者同意才会返回

同意可以写进项目根目录的 .mwgrc（或用户级的 ~/.mwgrc）：

bash 复制代码

# 允许 Origin Trial 指南
npx modern-web-guidance@latest set-allow-origin-trials
# 允许不稳定的单引擎特性指南
npx modern-web-guidance@latest set-allow-volatile-features

这个文件可以提交到仓库，让团队共用同一套设置。

自带的闭环评测

这是我觉得最有参考价值的部分。多数 Skill 项目只交付内容，这个项目把「内容有没有用」做成了流水线：

专家撰写指南
自动生成评测目标：任务、标准答案（golden solution）、Playwright 评分脚本
自校准：评分脚本必须在标准答案上 100% 通过，在未修改的基础应用上 100% 失败，否则不合格
端到端运行 ：让 Agent 在「有指引」和「无指引」两种模式下完成任务，任务基于两个基础应用 daily-grind 和 devtools-times，提示词不点名具体 API
按指标迭代：

指标	含义
opportunity（机会）	100% 减去无指引时的通过率，代表还有多少提升空间
uplift（提升）	有指引通过率减去无指引通过率

Agent 本来就能做对的指南会被裁剪；效果弱的指南会被改进。评分脚本检查的是源码模式、计算样式、运行时 DOM 行为和无障碍状态。

官方公布的结果怎么读

README 里有一张按日期更新的结果表，我看到的是 11 月 8 日这一批：

Agent	无指引 → 有指引	提升
antigravity_cli	58% → 94%	+36 个百分点
claude_code	57% → 88%	+31 个百分点
codex_cli	54% → 82%	+28 个百分点

README 自己概括为约 +27 到 +36 个百分点。读这些数字时请记住：

这是项目方自己的评测，用的是项目自己设计的任务和评分脚本，不是第三方基准
任务集由同一团队编写，指南和评测同源，结果对「在这套任务上有效」有说服力，对「你的业务代码也能提升同样幅度」没有保证
表中写的模型版本是 README 的原文，我没有核实
评测在持续更新，页面上还有按 Agent 和按指南拆分的仪表盘

遥测

README 明确说会收集匿名数据：安装次数、Agent 名称、被检索的指南 ID，以及 Agent 生成的搜索查询；不收集用户的原始提示词。关闭方式是设置环境变量 DISABLE_TELEMETRY=1。用于公司项目前，建议先确认这一条是否符合你们的合规要求。

想贡献内容怎么办

CONTRIBUTING.md 的要点：

全新指南原则上只开放给已入驻的 Peer，除非 Content ATL 或 Owner 授权；任何人都可以提 Issue，或为现有指南提 PR
内容工作包括使用场景、guide.md、demo.html、expectations.md 和自检
合并前需要签署 Google CLA，纯文档改动也一样
本地开发需要 pnpm 和 Node.js >=22.18.0，完整检查命令是 pnpm preflight（构建、类型检查、lint、单元测试）

局限与注意事项

评测数据来自项目方，且处于持续更新中，数字会变
指南的覆盖面再大，也只是约 250 个特性、203 个场景，不在列表里的问题仍然靠模型自己
对新特性的门控依赖开发者的判断，开启后兼容性风险由你承担
遥测默认开启，需要手动关闭
README 把项目状态描述得很活跃，但没有标注 beta 或 stable，使用前自己评估成熟度

项目地址与资源

🌟 源码仓库 ：github.com/GoogleChrom...
📦 发布仓库（只读）：GoogleChrome/modern-web-guidance
📚 文档：仓库主页指向 developer.chrome.com 上的专门页面（goo.gle/modern-web-guidance）
📊 评测仪表盘：README 中链接的 Eval Dashboard
📄 许可证：代码 Apache-2.0，指南内容 CC-BY 4.0

总结与展望

核心要点回顾

问题定位准确：AI 写前端偏老，根源是训练数据，所以从上下文入手补
两步检索 ：离线 search 加 retrieve，无需联网和 Key
安全采用新特性：渐进增强、轻量降级、Baseline 数据，外加对不稳定特性的门控
内容与评测一体：指南有没有用，靠有无指引的对照实验来裁剪和改进
数字要打折读：+27 到 +36 个百分点是项目方自己的评测，不是第三方结论

适用人群

常用 AI Agent 写前端，觉得产出偏旧、偏重的开发者
想把团队的前端最佳实践沉淀成 Skill 的人
想学习「如何为 Skill 内容做评测」的开发者，这套闭环值得借鉴

学习建议

先别装，直接用 search 试几条你工作里常见的需求，比如「模态框」「滚动驱动动画」，看返回的指南质量。再对自己的项目跑一次 legacy-scan .，看它认为哪些是老写法。最后读一读 docs/EVALS.md，那里是整个项目最有特色的部分。

欢迎访问 PrimeSkills ------ 一个精心策划的 AI Agent 与技能市场，所有内容均经过真实企业级工作流验证。没有噱头，只有真正有效的东西。

更多实用知识和有趣产品，欢迎访问我的个人主页