引言
「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 上有专门页面（见项目地址）
主要功能
它解决的问题
没有指引时：
Agent 凭训练数据写代码 → 偏向老写法、重 JavaScript、多余的库
↑ 即使知道某个 API 存在，也缺少足够多的现代真实示例
有指引时：
Agent 遇到 Web 平台问题 → 调用 CLI 检索 → 拿到精选指南
↓ 指南里有代码模式、坑点、降级方案
↑ 产出更接近现代、可用于生产的写法
快速开始
交互式安装：
npx modern-web-guidance@latest install
不安装，直接试用三个子命令：
# 按描述搜索最匹配的指南
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）：
# 允许 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 与技能市场，所有内容均经过真实企业级工作流验证。没有噱头，只有真正有效的东西。
更多实用知识和有趣产品，欢迎访问我的个人主页
