技术拆解 046｜modern-web-guidance：给 coding agent 装一本「现代 Web 说明书」

背景：v1.0.0 发布一天，3000 星和一场治理论战

2026 年 11 月 10 日，GitHub 仓库 GoogleChrome/modern-web-guidance 发布 v1.0.0，Apache-2.0 许可，截至 11-11 核验已超 3,000★（3,109）。同日 Show HN 上榜，209 分、58 条评论。

这个项目最扎眼的不是星数，是署名：README 自述由 Google Chrome、Microsoft Edge、Mozilla Firefox、MDN 四个团队与 Web 开发社区共同维护。四大浏览器阵营给同一份「agent 说明书」背书，这在 Web 标准史上不多见。

它要解决的问题一句话讲得清：LLM 的训练数据里堆满了遗留代码，agent 默认生成臃肿 JS，而任务往往已有原生高性能方案；即使模型知道 API 存在，也缺少生产级实现模式的密度。Chrome 团队的 paulirish 在 HN 顶楼举例：浏览器原生已能处理过去要 50 行 JS 或一个依赖的事，CSS.highlights 做文本高亮，dialog 加 showModal() 自带 backdrop 和焦点管理，field-sizing 让 textarea 随输入自动增高。模型知道这些 API 的名字，但就是不会默认用。

做法是把 Web 平台专业知识、最佳实践、浏览器兼容性数据打包成 skills，直接嵌入 coding agent 的工作流。品类信号藏在安装清单里：Vercel Skills CLI、gh skill install、各家 agent 的插件市场，一个 README 集齐八条分发通道，说明「给 agent 装外挂知识」正在成为基础设施，而浏览器厂商是第一次集体下场当内容供给方。还要注意仓库分工：这个仓是分发打包仓，内容源码在 GoogleChrome/modern-web-guidance-src，浅 clone 里只有 Release v1.0.0 一条提交，项目开发史都在 -src 那边。

架构与原理：文档即产品，检索即管线

本地统计（不含 .git）：265 个文件，其中 236 个 markdown，没有传统意义的源码，本质是个「文档即产品」仓库。主体是 skills/modern-web-guidance/ 下 209 篇指南，分 17 个领域目录：css、js、html、forms、accessibility、performance、security、privacy、pwa、wasm、webmcp、built-in-ai、ui-components、ui-atoms、ui-behaviors、visual-design、user-experience 等。另带第二个 skill 包 chrome-extensions（Manifest V3、后台 worker、扩展 API 与 Chrome Web Store 发布）。README 自述覆盖 250 项现代 Web 特性，全部链到 Baseline 项目（web-platform-dx）的特性页，兼容性口径对齐四浏览器共同支持。

工作管线三步：agent 因任务触发 skill；本地跑 search，README 自述用离线零依赖 embedding 模型加 BM25 检索，不发网络请求、不要 API key；命中后 retrieve 把指南全文注入上下文。两个工程细节值得抄：其一，search 命令强制带 —skill-version 2026_11_09-5bcc021b 参数，指南内容与 skill 版本钉死，防漂移；其二，实验性 Origin Trial API 和「易变特性」（单引擎、发布 3 个月内或仍在稳定化）在 search 里可见，但 retrieve 被门控，要开发者显式跑 set-allow-origin-trials 或 set-allow-volatile-features 解锁，agent 不能擅自采用不稳定 API。

内容侧还有套自我修剪机制。README 自述指南「为省 token 而设计」，配套 eval 流程算两个数：opportunity（100% 减去无指导通过率）和 uplift（有指导减无指导的通过率差）。模型不看指南也能做对的内容直接剪掉，agent 挣扎的地方加密度。SKILL.md 本身也压到约 205 token，chrome-extensions 包约 175 token，安装时还能用 —choose 只挑需要的包。领域覆盖也透着野心：webmcp 目录教 agent 用 WebMCP 把网页表单和客户端 JS 函数暴露成 AI 工具，built-in-ai 目录讲浏览器本地跑翻译、摘要、语言检测的原生 API，都是还在前沿的能力。

关键机制细读：把「触发」写成强制条款

SKILL.md 只有 90 行，触发设计相当激进：description 写明「MANDATORY: Execute FIRST for all HTML/CSS and clientside JS tasks. Do NOT skip」，理由是 web API 演进快、训练权重里全是过时模式；随后列一长串触发场景（modal、popover、container queries、view transitions、scroll-driven animations、autofill、passkeys、CWV、built-in AI、WASM 等），也明确列出不触发场景：后端 SQL/ORM、CI/CD、Docker、Python/Go、构建工具、测试。边界写得比多数人类团队的规范清楚。

四步工作流同样具体。search 要求 2-5 词动作导向查询，一次只查一个能力点，禁带框架名和应用名词，用户说「删除前确认」要翻译成「confirmation modal dialog」再查；无结果换一次具体名词，再降级 list。retrieve 支持逗号取多篇，输出超 9.5KB 自动落临时文件防截断，并要求 agent 用文件读取工具而非 cat/head。第三步对照指南自查实现，明确说 legacy-scan 不用于此步。第四步交付时附「### Modern Web Guidance」披露节，逐条写明应用了哪个 id、防了什么坑，还要带指南原文短引，且禁止凭记忆编造引语。

指南本体的质量可以看 navigation-drawer 一篇：抽屉用 top-layer 元素（modal dialog 或 popover 的 manual 模式）实现，滑动手势交给一个横向滚动容器加两个 scroll-snap 停靠点，动量、速度、打断追踪全部由浏览器原生处理，零 JS pointer-event 代码；backdrop 透明度用 scroll-driven animation 绑滚动位置；再挂一个 IntersectionObserver 判定开合状态。这就是「模型知道 API 名字但不会这样组合」的密度补齐。

legacy-scan 是独立入口：扫存量代码找遗留模式，但只覆盖约 20% 的指南子集（有确定性规则的那部分），扫出结果要人工对照 keepWhen/dropWhen 规则去伪。

执行环境的坑也提前填了。SKILL.md 要求权限白名单精确到 npx -y modern-web-guidance@latest *，明令禁止放行裸的 npx *；沙箱或审批制环境（Codex、Claude Code）里要在首次执行前主动申请带网络访问的授权，免得超时；~/.npm 只读时设 NPM_CONFIG_CACHE 指到 /tmp；断网挂起就退回 npx —offline 重试；有 pnpm 优先用 pnpx。还有一条底线写在 Guidelines 里：永远先 search，不许凭记忆幻觉出指南内容，指南是用户项目的首选本地标准。

分发与评估：一套内容，喂给八个 agent 生态

分发做了三层。CLI 层：npx modern-web-guidance@latest 加 7 个子命令（install/search/retrieve/legacy-scan/update/set-allow-origin-trials/set-allow-volatile-features），Node 22 起。安装层：README 给了八条路，交互式向导、Vercel Skills CLI（npx skills add）、gh skill install、Google Antigravity、GitHub Copilot CLI、Claude Code 插件、Grok Build CLI、Kimi Code、OpenAI Codex，各家一条命令。清单层：仓库同时放 plugin.json（agent-plugins.org schema 1.0.0）、gemini-extension.json、kimi.plugin.json 三份 manifest，同一套 skill 分别打包给通用 agent、Gemini、Kimi。另有 policies/modern-web-guidance.toml，把 modern-web 命令在 plan 模式下设为 ask_user。

效果数字全部是 README 自述：11 月 8 日一轮 eval，antigravity_cli（gemini-4-argon）58% 到 94%（+36pp），claude_code（opus-5-5）57% 到 88%（+31pp），codex_cli（gpt-6.1-sol）54% 到 82%（+28pp），任务约 215 个、断言约 1800 条。eval 的出题方式值得一提：在两个完整基准应用（daily-grind、devtools-times）上定义模拟真实开发者的 prompt，比如「让我的图片加载更快」，故意不点名任何 API，考的是 agent 能否自然发现并用对指南；评分器用 Claude/Codex/AGY 三家 agent 的黄金解校准（100% 通过目标），再配一个未修改的基线应用（0% 通过目标）。README 里的成绩表从 11 月 2 日起每隔两天注入更新一轮，三家 agent 各一份逐指南明细挂在公开的 Eval Dashboard 上。这些是官方口径，未经第三方复核，但「unguided 基线也一起报」的姿态比只报高分诚实。

遥测如实披露：匿名收集安装数、调用 agent 名、指南 id 与 search 查询词，不收原始 prompt，收集代码位置写在 README 里。HN 上有人给出侧面证据：几个月前就装上了，Claude Doctor 一直没把它清掉，说明在生效。

争议与风险：谁有资格定义「现代」

HN 热评区正反两方都在。需求侧的共鸣很直接：有人说早就需要了，review 过太多「能换成 2 行现代特性却写成一坨」的 PR，自己还写过半成品工具。批评面三条。其一，「最佳实践在 AI 时代已死，很快没人会读 AI 生成的代码」；paulirish 回应可维护性是下一个前沿，1 行 CSS 方案好过 60 行 ResizeObserver 加 setTimeout 的业务代码；另一位补了半句：能改善用户体验的最佳实践没死，只是重心从开发者工效学移开了。其二，「现代 Web 原语」未必等于最佳实践，浏览器实现差异要磨十年，跨设备跨浏览器手工测试逃不掉；还有人把 agent 当随机机器，认为让它整体过一遍指南、取平均后照样没用。其三最重：治理。Chrome 在标准世界权力已经过大，让所有人的 LLM 都听 Chrome 团队指导，这条路通向「请用本浏览器访问本站」；回应方指出 Firefox 和 Edge 也是贡献者，且只推荐 Baseline 四浏览器都支持的实践，另有评论建议换个中立仓库发布观感会更好。这个顾虑有前史：2026 年 5 月项目早期形态就遭 Adrian Roselli 发文批评「Maybe Don’t Rely on Google’s Modern Web Guidance」，v1.0 拉上三家联合维护、对齐 Baseline，可以读作对这次批评的回应。但 Mozilla/Edge 的实际贡献深度，本次未独立核实。

风险还有两条。eval 是官方自己出题自己阅卷，opportunity/uplift 口径虽透明，任务集偏向有原生方案的场景，uplift 高不奇怪，选择偏差要在心里打个折。分发上，simonw 在 HN 提了个朴素建议：除 npm 包外，用 GitHub Pages 发布 markdown 索引页（当前 404），链接所有文档的纯 md 版本、为 grep 检索设计，不用装任何东西；Chrome 团队回应指到 developer.chrome.com 的 guides 页。换句话说，不想让 agent 跑 npx 的人，目前缺一扇官方平门。

结论与展望

modern-web-guidance 的价值不在 209 篇文档本身，而在它给「agent 知识供给」打了个样：知识不塞进权重，做成按需检索的外挂，存指针不存内容，版本钉死、实验特性门控、用法强制披露。HN 有人说这才是 agent 的圣杯形态：内置知识最小化，其余实时检索加缓存，我同意方向。三个后续值得盯：Mozilla/Edge 的贡献是署名还是实质，看 -src 仓库的提交分布就知道；eval 会不会出现第三方复现；官方纯 md 索引页会不会补上。对开发者，前端项目现在就可以装，成本低（一条 npx 命令），最坏情况是 agent 多查几次文档；对做 agent 基础设施的人，SKILL.md 的触发条款写法、opportunity/uplift 的内容修剪法、9.5KB 落盘防截断，三样都能直接搬进自己的 skill 体系。浏览器厂商把「别写过时代码」做成机器可执行的规范，这件事的信号意义，可能比 3000 星更大。

信息来源

• 仓库：github.com/GoogleChrome/modern-web-guidance（Apache-2.0；截至 11-11 超 3,000★，快照 3,109；v1.0.0 于 11-10 发布，git log 口径；内容源码在 GoogleChrome/modern-web-guidance-src）
• 11-11 本地 clone 只读统计（/tmp/mwg-1111）：265 个文件（不含 .git）、236 个 markdown；guides 209 篇、17 个领域目录；SKILL.md 90 行、README.md 636 行；plugin.json/gemini-extension.json/kimi.plugin.json 三份分发清单；policies/modern-web-guidance.toml
• README.md（四团队联合维护为官方自述；250 特性与 Baseline 链接；离线 embedding+BM25、—skill-version 2026_11_09-5bcc021b、Origin Trial/易变特性门控、八种安装方式、7 个 CLI 子命令、Node≥22、遥测披露均 README 口径；eval 表 Nov 8 三行 +36/+31/+28pp 为 README 自述，未经第三方复核；skill 包 token 数 ~205/~175 自述）
• SKILL.md（MANDATORY 触发条款原文、四步工作流、9.5KB 落盘、披露节格式、legacy-scan ~20% 覆盖）；guides/ui-components/navigation-drawer.md（抽屉实现案例）
• HN story 50443812（209▲/58💬，Algolia 检索）：paulirish 顶楼与回应、halflife、phyzix5761、sublinear、advisedwang、philipwalton、0o777、simonw 与 kinlan、nico、fumar、cyanydeez；正反观点并陈，非一致好评
• adrianroselli.com 2026/05「Maybe Don’t Rely on Google’s ‘Modern Web Guidance’」（HN 12▲）；Mozilla/Edge 实际贡献深度未独立核实

署名：永亮