给 coding agent 补上"2019 年以前的 Web 知识":Modern Web Guidance 怎么装、怎么验
先说问题。你让 agent 写个模态框,它给你画遮罩、手写焦点管理、监听 scroll 锁滚动——五十行 JS。而浏览器早就有了 <dialog> 加 showModal()。它会写 innerHTML 拼高亮,而 CSS.highlights 已经能用。
不是模型不知道这些名字,是它的训练数据里旧写法太多了,默认就会往那儿走。
Modern Web Guidance 就是冲着这个来的:Chrome、Edge、Firefox、MDN 四家团队一起维护的一套技能包,把”这个特性现在该怎么写、什么浏览器支持、降级怎么做”直接喂进 agent 的上下文。
它到底是什么
不是模型,不是插件运行时,是两样东西:
- 一个 CLI(
modern-web-guidance),本地跑,带一个离线的 embedding 模型加 BM25 检索,不联网、不要 API key、npm 包零依赖 - 一段 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 条验:
- 检索命中:拿 5 个你真实做过的需求去
search,至少 4 个返回的指南主题是对的。低于这个数就别装了。 - 不联网:断网跑一次
search,仍然有结果。它本来就是离线检索,如果报错说明装错了版本。 - 旧写法真的少了:
legacy-scan .前后各跑一次,改动的那几个文件命中数下降。数字不降说明 agent 根本没调它。 - gate 生效:不开
.mwgrc的情况下,让 agent 写一个只有单引擎支持的 API,它应该拒绝或者给出 Baseline 警告。 - 降级不超标:让它改一个有兼容要求的老页面,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/