modern-web-guidance：Chrome 把「AI 写前端」的知识缺口，做成了一套带评测闭环的技能库

一、导读

编码智能体写得快，但写出来的前端代码常被资深工程师一眼挑出毛病：过时的 polyfill、缺失的无障碍支持、本该用 CSS 却硬写的 JavaScript。Google Chrome 团队的开源项目 Modern Web Guidance（仓库为 modern-web-guidance-src）把 250 个现代 web 平台特性的专家指南做成 Agent Skills 包与离线检索 CLI，再用一套「金标解校准 + Playwright 判卷」的评测闭环证明这些指南真的能改写模型行为——11 月 8 日的评测快照里，三大主流编码智能体加上它之后，现代 web 检查通过率从 52%–60% 提升到 82%–96%。11 月 10 日项目发布 1.0 稳定版，Firefox 与 Edge 宣布加入，GitHub 单日涨星近八百。

二、项目速览

维度	数据（截至 2026-11-13）
仓库	GoogleChrome/modern-web-guidance-src（发行包在 modern-web-guidance）
Star / Fork	2,813 / 190，11 月 13 日单日涨星 799，位列 GitHub Trending 日榜第四
创建时间	2026-01-27；npm 首包 2026-04-30，1.0 稳定版 2026-11-10
License	代码 Apache-2.0，guides 内容 CC-BY 4.0（部分派生自 MDN/W3C/WHATWG/IETF 文档）
主要语言	TypeScript（评测与工具链），内容为结构化 Markdown
内容规模	250 个 web 平台特性（CSS 140、HTML/DOM 36、JavaScript/APIs 74），六大方向
分发	npm 包 modern-web-guidance，121 个版本，最近一周下载 12.8 万次
贡献者	71+ 人，含 Chrome、Edge、Firefox 与 MDN 团队成员
遥测	匿名采集安装数与检索 ID，不收原始 prompt，`DISABLE_TELEMETRY=1` 可退出

三、为什么是它

直接动因是 1.0 稳定版发布：官方博客于 11 月 10 日刊出（作者 Philip Walton），HN 上 11 月 11 日出现讨论帖。但能让涨星持续三天，靠的是三层叠加：

第一，时机踩在行业痛点上。 博客里有个判断很犀利：当所有人都在用编码智能体时，速度不再是竞争优势，差异化回到可用性与体验质量。而前沿模型「能跑」与「写对」之间的缺口集中在四个领域——无障碍（焦点管理、prefers-reduced-motion、表单校验）、交互体验（滑动手势、弹层过渡、明暗主题）、性能（主线程任务调度、布局偏移防护）、安全（HTML 净化、严格 CSP、passkey）。这些恰恰是训练语料里旧模式最密集的区域。

第二，1.0 带来了三个实质增量。 一是面向存量代码的现代化工作流（legacy-scan，1.0 覆盖约 20% 语料、41 条规则，11 月 12 日刚新增 6 条）；二是全量指南通过人工评审，用户可见组件的指南由依赖辅助技术的无障碍专家实测签核；三是公开评测仪表盘，把「加了它到底有没有用」变成可查数字——这在同类技能包项目里几乎是独一份。市场用脚投票的迹象也明显：npm 最近一周下载 12.8 万次，从 4 月底首包到 1.0 共发出 121 个版本，迭代节奏接近日更。

第三，项目升格为跨浏览器联盟。 1.0 宣布 Firefox 与 Edge 加入，与 Chrome、MDN 共同维护，背书从「单一厂商的工具」变成「web 平台各方的共同投资」，这对企业采用是关键信任项。

四、架构原理

MWG 的架构可以拆成四层：内容层生产指南、服务层把指南送进智能体上下文、验证层用闭环评测保证内容有效、治理层保证内容持续不腐烂。它的核心洞察是：给模型补课之前，先测出模型已经会什么，把 token 花在真正的知识缺口上。

Modern Web Guidance 四层架构手绘信息图：内容层、服务层、验证层与治理层，以及评测驱动的内容修剪闭环

graph TD
    subgraph 内容层
        A[guide.md 专家指南<br>250 个平台特性] --> B[demo.html 金标准实现]
        A --> C[expectations.md<br>自然语言可观测断言]
    end
    subgraph 服务层
        D[SKILL.md 入口<br>约 205 tokens 触发规则] --> E[search 离线检索<br>embedding + BM25]
        E --> F[retrieve 注入指南<br>>9.5KB 落盘防截断]
        F --> G[合规自检与引用披露]
    end
    subgraph 验证层
        C --> H[gd dev 生成评测胶囊<br>grader + task + 金标解]
        H --> I[校准循环<br>金标 100% 过 / 基座 0% 过]
        I --> J[guided vs unguided<br>端到端对比]
        J --> K[公开仪表盘与 GCS 归档]
        K -->|opportunity/uplift<br>驱动内容修剪| A
    end
    D -. 智能体按任务触发 .-> E

内容层：一份指南三件套。 每条指南目录里，guide.md 是给智能体读的规范性指南（含 Baseline 兼容数据与构建期宏），demo.html 是金标准独立实现，expectations.md 是人类专家写的自然语言断言清单——比如「弹层打开时背景页面必须对辅助技术不可见」。三者都由领域专家（SME）手写，内容贡献者到此为止，不需要碰任何 Playwright 代码，专家只对内容准确性负责，评测基建由工程团队接手。

服务层：离线检索而非全文注入。 这是最值得借鉴的上下文工程设计。入口 SKILL.md 只有约 205 tokens，靠「MANDATORY：所有 HTML/CSS 与客户端 JS 任务必须先执行」的措辞和精确的正反向触发词（弹窗、暗色模式、锚点定位要触发；SQL、CI/CD、Vite 配置不触发）让智能体在对的时机调用 CLI。检索环节 modern-web-guidance search "light dismiss dialog" 用一个离线、零依赖的 embedding 模型加 BM25 混合匹配，全程无网络调用、无 API key——官方特意强调 npm 包自包含、无额外依赖，兼顾低延迟与供应链安全；而用 npx 拉取最新包又保证内容不因本地缓存而腐烂，这是「离线执行、在线分发」的一对平衡。命中后 retrieve <id> 把指南全文注入上下文，超过 9.5KB 自动落盘成临时文件防截断。危险特性另有门控：近三个月内单引擎发布或仍在波动的「volatile」特性与 Origin Trial API 可以搜到，但 retrieve 需要 .mwgrc 里显式 opt-in，防止智能体擅自采用不稳定 API。流程末端还有一个容易被忽视的设计——第四步「引用披露」：智能体必须在回复末尾列出实际应用了哪条指南、引用了哪句原文，搜了但没用也要说明为什么；这条强制自白让「技能是否真的生效」在单次会话里就可审计，而不是黑盒。

验证层：把「指南有效」变成可证伪命题。 评测闭环分四步。第一步生成评测胶囊：从 expectations.md 自动生成 Playwright 判卷器 grader.ts、任务提示词 task.md（刻意不点名任何 API，只说「让我的图片加载更快」，考的是智能体能否自己发现并检索对的指南），以及两个真实基座应用（daily-grind 与 devtools-times）上的多智能体金标解——由 Gemini、Claude、GPT 三个模型家族分别实现，保证判卷器对风格差异鲁棒；双基座设计还顺带验证了指南的跨应用泛化性，避免内容只对某个样板项目有效。第二步是自愈校准：判卷器必须让所有金标解 100% 通过、未修改的基座应用 0% 通过（每条 MUST NOT 断言与一条正向存在性检查配对，防止「本来就不存在」的假通过），不达标自动重生成，最多 5 次尝试。第三步跑对照实验：同一批任务在「带 MWG」与「不带 MWG」两种模式下各跑一遍，沙箱用 bwrap/sandbox-exec 把智能体隔离在临时 HOME 里，看不到判卷器源码；每次运行还会记录所用模型与推理力度档位（优先取日志观测值，其次配置值，再次模型 ID 后缀，最后默认档），档位冲突直接启动报错——同一个模型在不同推理力度下表现差异很大，不锁住这个变量，对照数字就没有意义。第四步算两个指标——opportunity（100% 减去无指导通过率，即还剩多少知识缺口）与 uplift（有指导减无指导）；模型已经会的直接从指南里剪掉，这就是官方说的「评测驱动的 token 节约」。评测结果经 gd eval、gd compare 等命令归档到 GCS（gs://guidance-evals），公开仪表盘按智能体与指南两个维度呈现；配套仓库里甚至有一组维护评测体系自身的技能（夜评调查、判卷器重放、开发提示词金丝雀），工程流程本身也交给了智能体。

治理层：让内容跟得上平台演进。 内容区域技术负责人（ATL）按目录与特性两条轴在 .github/atls.json 里注册，CI 自动给他们指派评审；指南走「用例立项 → 撰写 → 评测落地」三阶段流水线，带 volatility 标签的争议两周内必须裁决；expectations.md 一旦比判卷器新，自动标记为过期进重跑队列。再加上 1.0 引入的无障碍专家专项签核，这套治理保证了「web 平台每月都在变」的内容不会烂在仓库里。

性能与取舍。 这套设计的代价也要看清：离线 embedding 模型换来了隐私与零延迟，代价是语义匹配精度弱于云端大模型向量服务，所以工程上叠了 BM25 兜底、并在 SKILL.md 里写死「弱结果先换同义词重搜一次再放弃」的降级路径；指南按需注入而非全文常驻，把 token 成本压到「入口 205 tokens + 命中的那一两篇」，但前提是触发词工程足够准——触发太松会浪费检索轮次，太紧则智能体该问不问，这正是 Roselli 批评里「该激活没激活」问题的根源，官方用 MANDATORY 措辞与穷举触发词清单来逼近平衡，本质是在概率系统上做确定性工程。

与同类路线相比，差异一目了然：静态规则文件（Cursor Rules、AGENTS.md）是「写死就完」，无法验证是否生效；服务端 RAG（各类文档检索 MCP）解决了检索但内容无评测；而 MWG 把「内容生产 — 注入 — 效果验证」闭成环，评测结果反过来驱动内容增删——它本质上是给 LLM 做的「教材 + 考试 + 教研」体系，而不是又一个提示词集合。

五、应用场景

场景一：新功能开发时给智能体「划重点」

痛点：让智能体实现抽屉导航或弹层动画，它默认给你一套 jQuery 时代的 transform + pointer 事件代码，动效生硬、无障碍缺失。如何解决：MWG 的指南会引导智能体改用原生机制——比如 navigation-drawer 指南用 <dialog> 或 popover="manual" 做顶层弹层、CSS scroll-snap 两个停靠点原生实现滑动手势（动量与打断跟踪由浏览器免费提供）、scroll-driven animation 把遮罩透明度绑到滚动位置，零 JavaScript 指针代码。最小示例：

npx -y modern-web-guidance@latest search "navigation drawer swipe"
npx -y modern-web-guidance@latest retrieve "navigation-drawer"

安装过 skill 的智能体会在实现 UI 任务时自动走「search → retrieve → 写码 → 自检 → 披露引用」五步。收益：11 月 8 日快照显示，Claude（opus-5-5）通过率 57%→88%，GPT（gpt-6.1-sol）54%→82%，Gemini（gemini-4-argon）58%→94%。边界：只覆盖 web 前端与客户端 JS，后端、CI、构建工具任务按设计不触发；查询要用「2–5 个词的动宾短语」描述用户可见能力，别把框架名和业务名词混进去。

场景二：存量代码现代化

痛点：老项目里堆满过时 workaround、没人敢删的 polyfill，人工审计成本高。解决：1.0 的现代化工作流用静态分析扫描 HTML/CSS/JS 与 package.json，找出可安全升级的模式，再引导智能体逐项改造，fallback 策略内建在指南里（轻量 <50 行定制回退或按需加载 polyfill，而不是引重型三方包）。最小示例：

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

收益：日本内容平台 note（9000 万月活）用它配合自家设计体系现代化 Next.js 前端，180 次评测把现代 web 检查通过率从 61% 提到 94%，431 个合并 PR 中 LCP 图片优先级正确处理提升 28%。边界：1.0 的静态扫描只覆盖约 20% 指南语料（41 条规则），官方明说先求结果可预测，语义级的「智能体自主审计」在后续版本；对深度耦合业务逻辑的改造仍需人工把关。

场景三：CI/CD 里的自动审查与性能修复

痛点：PR 评审里无障碍与语义问题最依赖专家经验，人工看不过来；性能告警的定位与修复来回拉扯数小时。解决：把 MWG 挂成 PR 自动审查 bot 或流水线修复智能体。收益（官方博客，截至 2026-11-10）：MetaMask 用三行 prompt 配置的审查 bot 五周看了约 480 个 PR，评论 64 个，工程师据此修复 43 处（多为无障碍与 HTML 语义问题）；腾讯海外视频 WeTV 在 CI/CD 里让智能体用 Chrome DevTools for agents 诊断性能回归、再用 MWG 修复，90% 未过的性能检查自动闭环，解决时间从 4 小时压到 30 分钟。边界：这两个案例都把 MWG 与运行时验证工具配对使用——MWG 负责写之前的知识，DevTools 负责跑之后的验证，官方也明确建议两者搭配而非单用。

场景四：按浏览器支持范围定制建议

痛点：同一功能在不同 Baseline 状态下写法不同，智能体不知道你的兼容目标，要么激进用新 API 破兼容，要么保守堆 polyfill。解决：指南内嵌 Baseline 兼容数据，search/retrieve 结合项目 .mwgrc 动态调整——默认锁保守，显式 opt-in 后才解锁 Origin Trial 与 volatile 特性指南。收益：印度 Policybazaar 在约 30 个高流量落地页上自动化性能审计（人工工作量减 92%），其姊妹平台 Pensionbazaar 新页面交付周期从约 4 天缩到几小时、新屏 UI bug 减少 90%+，工程负责人的反馈点名「在尊重我们浏览器兼容目标的前提下」采用现代标准是关键。边界：兼容目标本身仍要人来定，MWG 只是让建议服从目标；Baseline 数据不追踪无障碍特性的浏览器实现差异，这块仍靠专项评审兜底。

场景五：把指南库当团队教材与规范底座

痛点：团队的前端规范文档常年停在 Wiki 里吃灰，新人不看、智能体更不看，代码评审里同一批问题反复出现。解决：MWG 的指南本身就是高质量教材（官方博客提到不少开发者把它当学习资源直接阅读），团队可以在此基础上用 .mwgrc 沉淀自己的兼容策略，把「团队规范」变成智能体可执行、可考试的条目。最小示例：项目根提交一份 .mwgrc，再在 PR 模板里要求智能体按 SKILL.md 的披露格式列出每条改动引用的指南。收益：评审对话从「这里不对，改成 X」变成「指南 X 已用没用、为什么」，沟通成本显著下降；规范条目跟着指南版本走，平台演进时不会过期。边界：团队私有规范（设计系统、内部组件库）MWG 不管，需要仿照它的三件套结构自建，再通过 AGENTS.md 或自定义 skill 挂进工作流。

不建议使用的场景

非 web 项目（纯后端、移动原生、数据分析）；要求生成结果逐次确定的场景——LLM 的非确定性意味着指南只能提高概率，不能保证遵循；以及把 MWG 当无障碍合规证书用的场景——它提升下限，不替代真实辅助技术的验收测试。

六、快速上手

# 在项目根目录安装（交互式向导）
npx modern-web-guidance@latest install

# 或只装部分技能包（modern-web-guidance 约 205 tokens 入口 / chrome-extensions 约 175 tokens）
npx modern-web-guidance@latest install --choose

# 不安装直接体验 CLI 的三个命令
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 .

已有插件体系的智能体可走对应渠道：Claude Code 与 GitHub Copilot CLI 用 /plugin marketplace add GoogleChrome/modern-web-guidance，Codex 用 codex plugin marketplace add，还有 Vercel Skills CLI、Antigravity、Grok Build、Kimi Code 等安装方式。更新用 npx modern-web-guidance@latest update。企业内如需解锁实验特性，在项目根放 .mwgrc（"allowOriginTrials": true 或 "allowVolatileFeatures": true）。介意遥测的在 shell 配置里 export DISABLE_TELEMETRY=1。

七、横向对比

维度	modern-web-guidance	anthropics/skills	addyosmani/agent-skills	静态规则（Cursor Rules / AGENTS.md）
内容来源	浏览器厂商 + MDN 联盟专家评审	Anthropic 官方技能包	资深工程师个人整理	团队自写
覆盖域	250 个 web 平台特性，深度到单个 API	通用文档处理等办公技能	通用工程交付纪律	自定义，无标准
效果验证	全量指南评测闭环 + 公开仪表盘	无系统化评测	三层评测框架	无
运行方式	离线 CLI 检索，零依赖，按需注入	文件随上下文加载	文件随上下文加载	全文常驻或手动引用
token 成本	入口约 205 tokens，评测驱动剪枝	包定义不一	全文载入	常驻，易膨胀
治理与更新	ATL 制 + 三阶段流水线，随平台演进	官方维护	个人维护	人工，易过期

一句话定位：前两者是「技能的格式与目录」，MWG 是「单一领域做到专家深度、并用考试证明教学效果」的垂直样本。

八、局限与风险

非确定性遵循是根本矛盾。 无障碍博主 Adrian Roselli 在 5 月的批评文章里实测发现：用 MWG 生成带动画的手风琴组件时，相关 a11y 技能根本没被激活（官方 issue #875 承认指导过于分散）；生成代码在 Firefox 里动画失效，与渐进增强承诺相悖；项目顾问 Lea Verou 也公开承认「无法保证任何指导会被任何给定的提示使用」。1.0 的无障碍专项评审是对这些批评的回应，但机制层面的问题没有消失——概率的提升不是合规的保证，出错的代码还可能更隐蔽。

覆盖与成熟度边界。 legacy-scan 首版只覆盖约 20% 语料；部分前沿特性指南依赖的 web 平台本身仍在变动（volatility 机制说明官方自己也把这类内容视为风险）；Baseline 体系不追踪无障碍特性的浏览器支持差异，这是平台级盲区。

厂商信任与供应链。 内容标准虽已多浏览器共治，但项目主导权仍在 Google；CLI 虽离线零依赖，默认匿名遥测会采集检索查询（可退出），企业内网需评估数据边界；npx 拉包模式要求团队接受 npm 供应链的常规风险面。评测口径的边界。 公开评测的考题、判卷器与被测技能同源于一个团队，「自己出题自己判」的 uplift 数字应视为强信号而非绝对结论——好在考题设计（不点名 API、真实基座应用、盲测基座 0% 通过、金标解跨三个模型族）与全开源的判卷器让外部复现验证成为可能，质疑者大可以自己跑一遍 gd eval。

九、小结与行动建议

MWG 的价值不在「又一个技能包」，而在它示范了上下文工程的完整方法论：先量化模型的知识缺口（opportunity），再针对性供给专家内容，最后用对照实验证明 uplift，并把修剪权交给评测而不是作者直觉。这个闭环适用于任何「给 LLM 补领域知识」的场景，不限于 web——医疗、金融、合规等任何「模型训练数据过时或不可靠」的垂直领域，都可以照此建设自己的「教材 + 考试 + 教研」体系。

行动建议：第一，前端团队今天就可在项目里跑 npx modern-web-guidance@latest install，零成本先看 legacy-scan 报告再决定深度接入；第二，把它与运行时验证（Chrome DevTools for agents 或你现有的 E2E 套件）配对使用，只靠「写前知识」不验证是当前已知的主要踩坑点；第三，治理自己的团队知识库时抄它的三件套结构（指南 + 金标准实现 + 可观测断言），让每条「给智能体的规矩」都可被考试；第四，企业接入前用 .mwgrc 明确兼容目标并评估遥测策略；第五，对无障碍与合规强相关的产出，保留人工与真实辅助技术的最终验收。

参考资料

官方发布博客 Modern Web Guidance 1.0（2026-11-10）：https://developer.chrome.com/blog/modern-web-guidance-v1
源码仓库 GoogleChrome/modern-web-guidance-src：https://github.com/GoogleChrome/modern-web-guidance-src
项目文档与评测仪表盘：https://developer.chrome.com/docs/modern-web-guidance 、https://googlechrome.github.io/modern-web-guidance-src/
仓库评测与架构文档 docs/EVALS.md、docs/CONTEXT.md（2026-11-02 版）：https://github.com/GoogleChrome/modern-web-guidance-src/tree/main/docs
HN 讨论「Modern Web Guidance 1.0」（2026-11-11）：https://news.ycombinator.com/
Adrian Roselli 批评文章 Maybe Don't Rely on Google's Modern Web Guidance（2026-05）：https://adrianroselli.com/2026/05/maybe-dont-rely-on-googles-modern-web-guidance.html
npm 包 modern-web-guidance 元数据（版本与下载量）：https://www.npmjs.com/package/modern-web-guidance