掘金热榜最近有个现象挺有意思:大厂官方仓库成批上榜,带的几乎都是给AI编程助手看的规范文件,有篇盘点说这类仓库最近一周在热榜占了32席。这里面动静最大的是Chrome的Modern Web Guidance------11月10日出到1.0,Edge、Firefox、MDN团队也进了维护名单,等于四大浏览器系一起给"AI该怎么写前端"定了调。
我对此一直有个疑问:这类规范包到底是个什么成色的东西?宣传语都差不多,"把现代Web最佳实践塞进你的coding agent",听着像一份精装修的prompt合集。决定它价值的是细节:指南内容是文档还是指令?检索是噱头还是真基础设施?扫描器到底能不能认出老代码?热榜上的文章都停在盘趋势,没人拆开看。正好这玩意一条npx命令就能跑,我直接把它拆了一遍。
包里是什么
先看体积:npm上的包16.5MB,版本1.0.0。装进去(npx会缓存到本地)翻目录,结构比我想的简单:
bash
modern-web-guidance/
├── skills/modern-web-guidance/
│ ├── SKILL.md # 给agent看的说明书
│ ├── modern-web.mjs # 主CLI入口
│ ├── legacy-scan.mjs # 扫描器,5MB
│ └── gen/ # 离线语义检索的索引
│ ├── guide-chunks.i8 # int8量化的指南向量
│ └── query-words.i8 # 7.4MB查询词表
└── policies/
那个gen/目录是重点。所谓"本地离线语义搜索"不是营销话术------它把指南内容做成了int8量化的embedding索引直接打进包里,检索全程不联网。我翻源码仓库(modern-web-guidance-src)对了一下,仓库里有252篇guide.md、51个规则文件,但npm包里只打包了35条规则、分摊在33篇指南上。也就是说官方宣称的203篇用例指南是发布版的口径,源码领先于发布版,像structured-clone(教你把JSON.parse(JSON.stringify())换成structuredClone)这类纯JS规则在仓库里有、包里没有。这个差距后面还惹出了别的事,先按下不表。
检索:0.77秒,内容形态像"带守卫的指令"
检索是这套东西的核心工作流。agent写前端前先search拿相关指南的ID,再retrieve拉全文。我试了个最常见的场景:
ruby
$ npx modern-web-guidance@latest search "light dismiss dialog"
[{"id":"light-dismiss-a-dialog","description":"Create a modal dialog that can be closed via light dismiss..."},
{"id":"platform-controls-dismiss-dialog",...},
{"id":"dialog",...},
...共10条]
搜"点外面关闭对话框",它返回的第一条确实是对的,排序也合理。拿到ID再retrieve:
ruby
$ npx modern-web-guidance@latest retrieve "light-dismiss-a-dialog"
这条命令完整跑下来0.77秒------包括npx解析包的时间。输出的指南长这样:closedby="any" 属性的用法,后面跟着一组硬指令:MANDATORY用showModal()打开、DO NOT对非模态对话框用closedby、还有一条"别把关键逻辑挂在click事件上,要听close或cancel"。最让我意外的是fallback策略那段:
Browser support for
<dialog closedby>: Limited availability. Supported by: Chrome 134 (Mar 2025), Edge 134 (Mar 2025), and Firefox 141 (Jul 2025).
精确到版本号和月份,Safari没列------意思是Safari还没跟上。这不是给人读的文档的写法,是给agent划的硬边界:能用、不能动、要兜底,一页写清。说它是"带守卫的指令"更准确,agent拿到就能直接执行,不用自己再去查兼容性。
顺手翻了几个别的指南,这个格式是统一的:frontmatter里声明依赖哪些web-feature-ids、交叉引用哪些别的指南,正文全是动作指令加fallback。成色确实比我想的好。
比指南内容更有意思的是SKILL.md------那份给agent看的说明书本身就是一套工作规程。它规定了agent怎么搜索:查询必须2到5个词、动作导向,禁止带React、Vue这类框架名,"删除时先弹确认框"这种用户意图要先翻译成"confirmation modal dialog"再搜,多功能的复合需求要拆成两次search。开头还有一段触发条件的硬规定:所有HTML/CSS和客户端JS任务必须先执行本技能,"Do NOT skip",但后端、CI/CD、Docker这类任务明确不许触发。看到这我才反应过来,这份东西不是给agent的参考书,是往agent工作流里插的一道关卡。
扫描器:第一轮0命中,问题出在哪
真正让我花时间的是legacy-scan,也就是新出的modernization扫描器:扫你现有的项目,找出老写法,映射到对应的指南。README里的示例看着挺美好,扫etherpad-lite能报出autocomplete缺失、::-webkit-scrollbar该换scrollbar-color这些。我先造了一段"2015年味"的代码喂给它------手动createElement拼modal、hover显隐的tooltip、JSON.parse(JSON.stringify())深拷贝、requestAnimationFrame手写动画,全是AI最爱生成的老货。
结果:0命中。
erlang
Modern Web Guidance Analyzer --- .
0 findings from 33 qualified guides.
Note: legacy-scan covers legacy patterns for 33 guides (~20% of the guidance corpus).
一开始我以为是扫描器不行。不甘心,回去翻规则源码,翻到scrollbar那条规则时发现了门道------里面有个文件级守卫:
kotlin
// 1. If stylesheet already defines standard scrollbar properties, skip
if (
ctx.stylesheetHasProperty('scrollbar-width') ||
ctx.stylesheetHasProperty('scrollbar-color')
) { return; }
整个样式表里只要出现过一次标准的scrollbar-width或scrollbar-color,这个文件里所有::-webkit-scrollbar的命中全部放弃。逻辑是:既然你已经写了标准属性,那些vendor前缀大概率是故意留的fallback,报出来就是误报。我原来的测试文件里恰好有一行.sidebar { scrollbar-width: thin; },把整个文件的命中都压掉了。把vendor前缀单独拆个文件再扫,同一模式立刻报出2条命中。
看明白守卫的逻辑,再回头看第一轮的0命中,就懂了大半:扫描器走的是确定性规则匹配(TypeScript AST、CSS解析、package.json依赖),35条规则每条都写得极窄------比如深拷贝那条在源码里带着一长串"不可克隆对象"的排除名单(localStorage、Vue的reactive返回值、AbortController......都会跳过)。规则宁缺毋滥,我的demo代码恰好都不在窄缝里。我按规则精确构造了第二个测试项目,两处命中都砍在点子上:
ini
* autofill-sign-in-form (1 finding)
Password input in sign-in or credential form should specify
autocomplete="current-password" or autocomplete="new-password".
- signin.html:3
<input type="password" name="password">
* form-fields-automatically-fit-contents (1 finding)
Imperative JavaScript auto-resizing of textareas and inputs using
scrollHeight or autosize() should be replaced with CSS field-sizing: content.
- app.js:5
ta.style.height = ta.scrollHeight + 'px';
这两刀我都认:表单密码框确实常年缺autocomplete,textarea手动算scrollHeight也确实该换成field-sizing: content。每条命中还带keepWhen/dropWhen的核对标准,让agent(或人)二次确认,不是见模式就报。
但这也暴露了它的天花板:35条规则只覆盖约20%的指南语料,剩下八成场景它根本不看------我那demo里的手动modal、手写动画,规则清单里压根没有对应条目。官方自己也写明白了:legacy-scan只查有确定性规则的子集,其余靠agent主动search。拿它当体检工具,预期得放低:它报的砍得准,没报的不代表没问题。
拆规则文档的时候还看到一个让我有点好感的细节:format-support.md里专门写了一条纪律------对支持扫描的文件格式,"0 findings不能静默地等于没看",解析失败必须可见地报出来,不许悄悄算成0命中。不过注释里也承认,这套跳过统计的代码"still being wired up",还没接完。第一轮那声0命中如果是解析失败造成的,按现在的版本我是看不到差别的。这种把自家没做完的事写在明面上的做法,比README里清一色的卖点口号可信多了。
前面说的源码与发布版的差距在这里也咬人了:仓库里的structured-clone规则能认JSON.parse(JSON.stringify()),发布包里没有,所以我的深拷贝老代码它装看不见。这套工具迭代很快,规则清单会跟上,只是现在这个时点,源码和npm包是两个版本的故事。
"完全离线"是真的,隐私要自己动手
拆包的时候我顺手翻到telemetry的实现,发现一个README里没对齐的地方。Quickstart一节说CLI"works offline, completely private and local",但Telemetry一节又承认:默认收集安装次数、agent名称、guide检索ID、还有"agent生成的搜索查询"。
代码里写得明白:isTelemetryEnabled()默认返回true,只有设置DISABLE_TELEMETRY=1才关。发出去的东西包括search的查询原文、命中的guide ID、通过环境变量探测到的agent名(它专门列了Claude Code、Codex、Devin的检测逻辑)、操作系统和延迟分桶。也就是说检索本身确实离线、不需要API key,但你的agent每搜一次什么,默认都会有一条记录发回Google的clearcut端点。用它的建议就一句:挂上之前先在shell配置里加export DISABLE_TELEMETRY=1,企业环境尤其如此。
这东西的定位
跑完这一圈,我的判断是:它的价值不在扫描器------那只是个只认两成场景的窄工具------而在那203篇指南本身。fallback精确到浏览器版本号、指令带keepWhen/dropWhen守卫,每篇还有评测数据(Google自己公布的口径是有指南的agent通过率从约50%提到约90%,日本note公司报61%到94%,数字看着漂亮,但我没法在本机复现他们的评测,姑且存疑)。模型权重里那堆十年前的代码不会消失,那就在外面挂一层会过期的常识库,版本号跟着Baseline走。挂上的成本几乎为零,npx一条命令,检索不花钱。扫描器就当个窄口径的体检表,报一条核一条,没报的自己心里有数。哦对,别忘了那条环境变量。