让 AI 写个模态框，十次有九次你会拿到一个 div + position: fixed + 手写监听器的组合——不是写不对，而是训练数据里旧代码太多。这件事现在有官方出手了：GitHub Trending 上连续两天霸榜的 modern-web-guidance，由 Google Chrome、Microsoft Edge、Mozilla Firefox 和 MDN 团队联合维护，把过去几年的现代 Web 平台特性打包成编码 Agent 能随时检索的知识库。我作为前端出身的博主，第一反应是对”官方教条”有点戒心，但在 M4 Mac 上跑完一组 A/B 对照之后，这个项目让我改了看法。本文记录 CLI 三板斧的实测结果、一次压力测试、以及免费模型装与不装这个 skill 的真实差距。
它是什么，为什么浏览器厂商要管 AI 写代码
项目本体在 GoogleChrome/modern-web-guidance 仓库，Apache-2.0 协议。我写稿时 GitHub API 实查 7,378 star，最近推送 11 月 10 日，热度还在往上走。官方文档在 Chrome for Developers 上，源码与评测数据单独放在 modern-web-guidance-src，还有个公开的 Eval Dashboard——光是这个”把评测数据摆出来”的动作，就比大多数 Agent 技能项目体面。
它的逻辑很直白：LLM 训练数据里堆满了旧代码，模型即使知道新 API 存在，也缺真实生产级的写法密度。所以 Chrome、Edge、Firefox、MDN 四家把 UI 动效、CSS 布局、性能、表单、无障碍、内置 AI 六大方向的现代特性写成指南，共覆盖 250 项平台特性，每条都带可运行示例和兼容性数据。指南刻意做了 token 瘦身——官方说他们跑过评测，把模型本来就懂的内容剪掉了。
CLI 三板斧实测：search、retrieve 和一个隐藏坑
不用装进任何 Agent，先拿 npx 直接跑（Node v22.22.2，CLI 版本 1.0.0）：
npx -y modern-web-guidance@latest search "animate a dialog modal backdrop"
npx -y modern-web-guidance@latest retrieve "animate-to-from-top-layer"
npx -y modern-web-guidance@latest legacy-scan .search 返回 id + description 的 JSON 列表。我故意用了一句混着框架噪声的长 query「close React settings modal on outside click」，照样返回了 light-dismiss-a-dialog、dialog 这些正确结果——搜索对口语化输入的容错比我预期好。retrieve 给出完整指南，含可直接抄的 CSS 示例。
第一个坑在这里：单篇 retrieve 输出超过 9.5KB 时不会走 stdout，而是写到临时文件，命令行只剩 321 字节的路径提示。我用 o200k 计数器量了一遍：list 全量 208 条 = 8,256 token；单篇指南约 1.9-2.2k token（animate-to-from-top-layer 是 10.7KB）。直接管道捕获大指南的输出，你只会拿到一行”已存盘”——脚本里处理这个工具必须按 SKILL.md 说的去读临时文件全文。
# 输出超 9.5KB 时的真实返回（实测原文）：
# Output (10.7 KB, 244 lines) saved to /var/folders/.../mwg-guide-xxxx.md
# Read /var/folders/.../mwg-guide-xxxx.md in full using your file-reading toollegacy-scan 压力测试：11 个旧写法只抓到 2 类
legacy-scan 是给存量代码找旧模式的静态扫描器。我先声明工具自己的定位：它只对 33 篇指南配了确定性规则，约为语料库的 20%，SKILL.md 里也明说了这个数字，输出还自带”结果仅供参考”的提示。
我自造了一个靶子：4 个文件、11 处典型旧写法——手写 div modal、JS 定位 tooltip、resize 监听模拟容器查询、scroll 监听做进度条、IntersectionObserver 懒加载、手写 toast、纯 JS 表单校验、-webkit-scrollbar 前缀等。扫描结果：只命中 2 类、共 3 条——::-webkit-scrollbar（2 条）和密码框缺 autocomplete="new-password"（1 条）。div modal、JS tooltip、手写校验这些大头全部漏过。11 处抓 3 条，这个检出率说不上好看，但也说明它的规则都是「能确定性判断」的，不靠模型猜。
有意思的是扫真实项目反而有价值。我把自己的图片压缩工具 PicShrink 扫了一遍，它报出备份页里 CDN 引入的 JSZip 没加 SRI 完整性校验（integrity/crossorigin/referrerpolicy 三件套）——这是真问题，不是我埋的。--json 模式还会给每条规则附 keepWhen/dropWhen 判据，Agent 拿到后能自己判断该不该改，这个设计比单纯报行号高明。
A/B 对照：装与不装，差了一个时代
先装 skill（实测 79 个 agent 目标可装，--agent '*' -y 可非交互落盘，本地捆绑 209 篇指南约 2.3MB，另生成 skills-lock.json 记录哈希）：
npx -y modern-web-guidance@latest install --agent '*' -y然后同一道题测两轮：给项目加一个模态对话框，要求点按钮打开、半透明遮罩、点外面和 Esc 都能关、有淡入淡出动画。环境是 macOS 26.5.2 / M4 / OpenCode 2.1.4，模型用 openrouter 免费档。
不装指引的对照组：nemotron-3.5-lightning:free 根本没调用已装好的 skill 工具，直接手写——产物是一个 div.modal 加 JS 类名切换的典型旧式实现，grep 确认全文零处 <dialog>、零处 @starting-style。我不死心，又显式要求它”先 search 再 retrieve 按指南实现”，它跑了第一次真 shell 命令后开始幻觉出不存在的 search() 内置工具，最后以”工具在环境中不可用”收场，照样交旧代码。
按指南实现的实验组：换成 cohere/north-mini-code:free，同一个任务。它先 search 定位到 dialog 和 animate-to-from-top-layer 两条指南，retrieve 后按提示读了两个临时文件，最后产出的单文件实现用了原生 <dialog closedby="any">、声明式的 command="show-modal" + commandfor、@starting-style 入场动画、transition-behavior: allow-discrete，还自己带了 prefers-reduced-motion 降级和 overscroll-behavior: contain。两份代码放一起看，确实不是一个时代的东西——尤其声明式 invoker 和 closedby 这类太新的 API，免费模型不查指南绝无可能写出来。
顺手一提，这个结果和我前几天测过的 caveman 省 token 技能结论互相印证：skill 装了不等于生效，模型会不会主动调用 skill 工具是真实的适配面差异；免费模型里 nemotron 全程无视、cohere 照做，选模型比装 skill 更影响成败。
踩坑清单与我的使用建议
把这次实测的坑浓缩一下：
- retrieve 的 9.5KB 落盘：脚本化使用必须解析临时文件路径并全文读取，管道党会静默丢内容。
- legacy-scan 不是 lint：只覆盖 20% 语料，别指望它抓 div modal 这类”结构性旧写法”；它的强项是确定性可判的规则（前缀伪元素、缺属性、缺 SRI）。开槽前先想清楚预期。
- 免费模型的调用纪律参差：skill 的 SKILL.md 写着”HTML/CSS/JS 任务必须先 search”，但模型不配合就是空谈。cohere/north-mini-code:free 实测最守纪律，nemotron 直接无视。
- 不建议的场景：纯后端、CI/CD、基础设施代码不用装，SKILL.md 自己声明了不触发；legacy-scan 在大型 monorepo 上全量跑意义有限，建议按目录或
--guide过滤后针对性扫。
还有一个我没验证的点要交代清楚：本次只测了 OpenCode + openrouter 免费模型的组合，Claude Code、Cursor 等原生接入的表现、付费模型的遵守率、Windows/Linux 环境，均未实测，需人工确认。
这值不值得装
如果你日常让编码 Agent 写前端，这个包几乎是零成本高收益——CLI 本身确定性、离线可用、指南来自四家浏览器厂商加 MDN 联合背书，比任何单一博客的”现代 CSS 教程”权威。它和 graphify 这类代码理解工具解决的是 Agent 的两个不同短板：graphify 管”代码是什么”，它管”代码该怎么写”。配合 ha-mcp 这类 MCP 服务器和 Cloudflare 的审计技能，你的 Agent 知识栈基本就齐了——差的可能只剩一个懂产品的人。
示例指南可以看官方仓库里的 navigation-drawer 完整指南感受一下质量，比读十篇营销文有用。
一句题外话：浏览器厂商下场”喂”Agent 这个动作本身，比工具更值得记住——Web 平台的知识分发，正在从”人查 MDN”变成”Agent 查厂商喂的知识包”。