给 coding agent 补上"2019 年以前的 Web 知识":Modern Web Guidance 怎么装、怎么验

2026-11-16 Skills前端coding agentChromeBaseline

先说问题。你让 agent 写个模态框,它给你画遮罩、手写焦点管理、监听 scroll 锁滚动——五十行 JS。而浏览器早就有了 <dialog> 加 showModal()。它会写 innerHTML 拼高亮,而 CSS.highlights 已经能用。

不是模型不知道这些名字,是它的训练数据里旧写法太多了,默认就会往那儿走。

Modern Web Guidance 就是冲着这个来的:Chrome、Edge、Firefox、MDN 四家团队一起维护的一套技能包,把”这个特性现在该怎么写、什么浏览器支持、降级怎么做”直接喂进 agent 的上下文。

它到底是什么

不是模型,不是插件运行时,是两样东西:

  1. 一个 CLI(modern-web-guidance),本地跑,带一个离线的 embedding 模型加 BM25 检索,不联网、不要 API key、npm 包零依赖
  2. 一段 skill 说明,告诉 agent:遇到 Web 平台问题时,先调这个 CLI

它的工作方式就三步:agent 识别到这是个 Web 问题 → 跑 search "用白话描述的需求" → 跑 retrieve <guide-id>,把对应指南的代码范式、坑、fallback 拉进上下文。

数据库规模

  • 250 个现代 Web 特性:CSS 与布局 140 个、JavaScript 与 API 74 个、HTML 与 DOM 36 个
  • 203 篇真实开发场景的用例
  • 覆盖到 View Transitions、容器查询、:has()、Popover API、Anchor Positioning、scheduler.yield、内置 AI API 这些
  • 每篇带 Baseline 的浏览器支持数据,所以 agent 能挑一个符合你支持目标的写法,再补一小段降级,而不是塞一整个 polyfill

安装

在项目根目录跑:

npx modern-web-guidance@latest install

装过早期预览版的用 update:

npx modern-web-guidance@latest update

它会问你装到哪个 agent(本质上就是把 skill 目录和一份说明放进去),因为工具本身只是个 CLI,任何能跑 shell、能读技能文件的 agent 都能用。

先别装,试两条命令

# 问一个具体需求,看它给什么指南
npx modern-web-guidance@latest search "animate a dialog modal backdrop"

# 直接取某一篇
npx modern-web-guidance@latest retrieve "animate-to-from-top-layer"

这一步很关键。如果 search 返回的 ID 跟你的问题不相关,说明它认不出你的场景,装了也是白装——agent 拿到的是错的指南,比没有更糟。

扫一遍你的存量代码

npx modern-web-guidance@latest legacy-scan .

它扫 HTML、CSS、JS 和 package.json,标出可以现代化的旧写法。目前是静态分析,覆盖的模式有限(官方说会扩),所以把它当”线索清单”而不是”待办清单”。

我建议的用法是:先跑一遍,人工挑 3 条最没争议的(比如表格布局、手写 polyfill),让 agent 改,跑测试。改完再扫一次,看数字有没有降。

两档实验特性默认被关着

Origin Trial 阶段的 API、以及只有单一引擎实现的”易变特性”,agent 能 search 到,但 retrieve 会被拦。要放开必须显式改配置:

npx modern-web-guidance@latest set-allow-origin-trials
npx modern-web-guidance@latest set-allow-volatile-features

这个默认值是对的。别顺手全开——否则 agent 会开始往你的生产代码里塞只有 Chrome 能跑的 API。

5 条验收标准

装完别急着说”好用”,按这 5 条验:

  1. 检索命中:拿 5 个你真实做过的需求去 search,至少 4 个返回的指南主题是对的。低于这个数就别装了。
  2. 不联网:断网跑一次 search,仍然有结果。它本来就是离线检索,如果报错说明装错了版本。
  3. 旧写法真的少了:legacy-scan . 前后各跑一次,改动的那几个文件命中数下降。数字不降说明 agent 根本没调它。
  4. gate 生效:不开 .mwgrc 的情况下,让 agent 写一个只有单引擎支持的 API,它应该拒绝或者给出 Baseline 警告。
  5. 降级不超标:让它改一个有兼容要求的老页面,diff 里新增的降级代码不超过 50 行。超了就是在拿 polyfill 换 polyfill。

泼冷水

第一,它治的是”知识过期”,不是”判断力”。agent 知道你该用 <dialog>,不代表它知道你的产品里那个弹窗要不要拦 ESC。

第二,这份指南是浏览器厂商写的。四家一起维护降低了偏袒单一引擎的风险,但”什么是现代最佳实践”这件事本身有立场——比如它对某些新 API 的推荐力度,会比保守的团队更激进。你自己的支持矩阵仍然是最终标准。

第三,别指望它提升所有任务。后端逻辑、数据处理、构建配置——这些它一个字都不管。

最后,官方挂了公开的评估面板(用来展示每篇指南的评测结果),但 README 里没有给具体分数。想验证效果,还是回到第 1 条和第 3 条:用你自己的需求测命中率,用你自己的仓库测下降幅度。

仓库:https://github.com/GoogleChrome/modern-web-guidance 评估面板:https://googlechrome.github.io/modern-web-guidance-src/