Chrome给AI编程助手塞了203篇前端规范,我拆包实测:检索0.77秒是真快,扫描器有点挑食

掘金热榜最近有个现象挺有意思:大厂官方仓库成批上榜,带的几乎都是给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一条命令,检索不花钱。扫描器就当个窄口径的体检表,报一条核一条,没报的自己心里有数。哦对,别忘了那条环境变量。

相关推荐
北城笑笑29 分钟前
Vue 110 ,若依SSE流式接口限次空500排查与解决
前端·javascript·vue.js·后端·vue
程序员韩星1 小时前
OpenAI 兼容接口返回 404,先查请求地址,再查模型名
前端·人工智能·http
Patrick_Wilson1 小时前
构建通过了,为什么有些浏览器还会白屏?
前端·javascript·浏览器
ServBay1 小时前
Local harness 将退役,VS Code 本地开发要不要搬到云端?
后端·ai编程·visual studio code
其实防守也摸鱼2 小时前
用 Claude Code 重构遗留系统:从评估到落地的完整指南
前端·网络·人工智能·chrome·安全·重构
七仔啊2 小时前
CNC计算机数控加工模拟器
前端
T_Wizard2 小时前
AI 回复为什么要转圈 3 秒才「啪」一下全出来?把流式输出拆开看,顺便踩了 6 个坑
java·ai编程
0zien02 小时前
【AI编程 - 第二弹】宝石TD
ai编程
IT规划师2 小时前
热点速递 | 未来软件工程六大战略技术趋势
ai编程