Files
2026-06-14 14:31:47 +08:00

260 lines
24 KiB
Plaintext
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
与 Gemini 对话
开始搜索和介绍 `npx modern-web-guidance install` 的作用,细节在 goo.gle/mwg 上; 还有 介绍 navigator.modelContext 和 registerTool 的作用,这就是 webmcp 吗,我是高级前端工程师,我希望做个快速了解
作为高级前端工程师,这套技术栈可以说是当下(2026年)AI + Web 平台的最前沿组合。我们可以用最硬核、最高效的方式将它们拆解为两部分:研发侧的 AI 提效工具(Modern Web Guidance),以及运行时(Runtime)的 Web 智能体交互标准(WebMCP)。
下面为你快速梳理它们的核心作用和技术本质:
一、 npx modern-web-guidance install 的作用
goo.gle/mwg(Modern Web Guidance,简称 MWG)是 Google Chrome 团队、Microsoft Edge 团队及社区联合推出的一套面向 AI 编码 Agent(如 Claude Code, GitHub Copilot, Vercel Agent, Google Antigravity 等)的「Web 知识技能包」。
核心痛点: 现有的 LLM(如 Claude、GPT)的训练数据经常滞后,容易让 AI 写出废弃的旧语法、过时的 Layout 模式,或者忽略最新的浏览器兼容性及最佳实践(如性能优化、Manifest V3 规范)。
它的本质: 运行 npx modern-web-guidance@latest install 会启动一个交互式向导,将现代 Web 的标准、代码模式、陷阱(Gotchas)以及回退方案(Fallbacks),以本地 Skill / 插件的形式注入到你常用的 AI 编码 Agent 中。
底层机制: 1. 纯本地与隐私安全: 它使用本地 CPU 高效的 TensorFlow.js 模型进行本地语义搜索,无需联网,无需 API Key。
2. 当你的 Agent 遇到相关的 Web 开发任务时,会自动调用 modern-web-guidance search "<query>" 匹配最合适的 Guide。
3. 通过 retrieve <guide-id> 将精准的 Web 标准和代码范式(约 200+ tokens)塞进 AI 的 Context Window,从而强行纠正 AI 的幻觉,让 AI 写出符合现代标准的 Web 代码。
二、 navigator.modelContext 与 registerTool
正如你所猜测的,这就是 WebMCP(Web Model Context Protocol)的 JavaScript 命令式 API(Imperative API)!
1. 什么是 WebMCP?
WebMCP 是 Google 为浏览器内置智能体(Browser-built-in Agents)设计的一种拟议的浏览器标准(Proposed Browser Standard)。
它并不是传统服务器端 MCP(Model Context Protocol)的直接 JS 实现,而是受 MCP 启发、专为浏览器前端运行时定制的 API。
核心目的: 让运行在实时标签页(Tab)中的 AI 智能体(Agent)不再像普通网络爬虫那样靠“猜 UI / 盲猜点击”来和你的网站交互,而是让前端开发者显式、结构化地向 Agent 暴露网站的能力和逻辑。
2. API 细节与运作方式
WebMCP 包含声明式(HTML)和命令式(JavaScript)两种接入方式。你提到的就是命令式 API:
JavaScript
// 向浏览器的 AI 智能体注册一个特定的「工具」
if (navigator.modelContext && navigator.modelContext.registerTool) {
navigator.modelContext.registerTool({
name: "book_appointment",
description: "用于在当前网站预订会议或医生预约。当用户明确要求预约时使用此工具。",
parameters: {
type: "object",
properties: {
date: { type: "string", description: "ISO 格式的日期,例如 2026-06-15" },
time: { type: "string", description: "24小时制时间,例如 14:30" }
},
required: ["date", "time"]
},
// 当 Agent 决定调用该工具时执行的逻辑
execute: async ({ date, time }) => {
try {
const result = await myAppInternalBookingMethod(date, time);
return { success: true, message: `预约成功:${result.id}` };
} catch (err) {
return { success: false, error: err.message };
}
},
// 安全策略:默认对其他跨域 iframe 隔离,可精细化授权
exposedTo: ["https://trusted-agent-service.com"]
});
}
3. WebMCP 相比传统 MCP / UI 自动化的核心优势:
作为高级前端,你可以从以下几个维度理解它的工程价值:
零网络延迟与实时上下文: 因为它直接运行在浏览器的內部系统,Agent 与工具的通信是内存级别、几乎即时(Instant)的。而且它可以直接访问当前 Tab 页内的实时会话数据、Cookies 和内存中的 DOM 状态,无须和远程 MCP 服务器做网络往返。
UI 表现与业务逻辑解耦(抗改版): 以前前端改个样式、重构一下 class 名,自动化脚本或 Agent 就会因为找不到 DOM 而崩溃。现在通过 registerTool 绑定了底层的应用逻辑(Application Logic),无论你重构多少次 UI,Agent 依然能通过结构化 API 精准调用功能。
掌控交互权: 以前是“求着 Agent 别点错按钮”,现在是开发者定义标准 schema,“直接引导(Steer)Agent 该怎么跟我的应用玩”。
总结
modern-web-guidance 是让 AI 辅助你写出更现代、更少 Bug 的前端代码(本地 RAG 增强)。
WebMCP (navigator.modelContext.registerTool) 是你作为前端开发者,给浏览器的 AI Agent 提供结构化的 JS 函数接口,让 AI 能够极其丝滑地在你的网站上完成自动化操作(如一键订票、动态表单填写等)。
我们一样一样讲,你说第一样,它是一个使用本地的算力进行计算。给我举一个场景,你先真的去看一下这个网页儿,了解这个技术背后的细节。针对我们可能有这个外部 web 应用,还有这个 electron 的桌面端 web 应用,他们使用这个工具有什么应用场景,能解决什么问题?举几个例子让我看一看
好,那我们直奔主题,重点拆解第一样:npx modern-web-guidance install(以下简称 MWG)。
正如你提到的,“本地算力”是这个工具非常硬核且精妙的设计。我刚看了 Chrome for Developers 的最新底层设计文档,我们先用 1 分钟梳理它“在本地怎么跑”的细节,然后再来看外部 Web 应用和 Electron 应用的硬核场景。
🛠️ 它是怎么在本地利用算力闭环的?
MWG 是 Google Chrome 和 Microsoft Edge 团队联合推出的项目。当你运行 npx modern-web-guidance@latest install 时,它会作为插件/技能(Skill)注入到你的 AI 编码 Agent(如 Claude Code、Vercel Agent、GitHub Copilot、或者 Google 最新的 Antigravity CLI)中。
本地语义向量库:安装时,它会在你本地盘上下载一个包含现代 Web 标准、最新浏览器 Baseline 兼容数据、现代 CSS(如 Anchor Positioning、Subgrid)以及 Chrome 内置 AI 最佳实践的精简知识库。
本地 TensorFlow.js 匹配:当你的 AI Agent 在写代码时遇到了 Web 相关的任务,它不会去联网查 Google,而是直接在本地隐式执行 modern-web-guidance search "<你的需求>"。
0 延迟、0 密钥、0 隐私泄露:它在本地用 TensorFlow.js 驱动一个超轻量的 CPU 优化模型 进行语义搜索(Semantic Search)。匹配成功后,通过 retrieve <guide-id> 将几百个 Token 的精准“现代 Web 范式、Gotchas(避坑指南)和 Fallbacks(降级方案)”直接截胡塞进 Agent 的 Context Window(上下文窗口)。
强行纠正 AI 幻觉:这等于是在本地给 AI 强行打了个“最新 Web 标准补丁”,防止它用 5 年前的过时语法或带 Bug 的 Flexbox 乱写代码。
🏢 针对【外部 Web 应用】的场景与痛点解决
在传统的 Web 应用研发中,我们经常遇到复杂的 CSS 布局、各种屏幕适配、以及性能优化的深水区。
场景 1:用最新的 CSS 替代复杂的 JS 脚本(如:悬浮弹出层、右键菜单)
痛点:以前让 AI 写一个悬浮菜单(Tooltip / Popover),AI 会很自然地引入一个几万行的 popper.js 或者写一堆监听 scroll 和 resize 的复杂的 JS 算坐标代码,容易引发页面卡顿和内存泄漏。
MWG 的解法:当你在 Claude Code 里说:“帮我写一个点击头像弹出的用户面板”。
本地运行:Agent 自动触发 MWG 本地搜索,匹配到 CSS Anchor Positioning(锚定定位) 和 Popover API 的现代标准指南。
结果:AI 不再写一行 JS 坐标计算,直接用 @supports (anchor-name: --x) 配合 position-try-fallbacks: flip-block 写出纯 CSS 的高性能原生的悬浮层,并自动附带了针对老旧浏览器的绝对定位降级方案(Fallback)。
场景 2:前沿的「浏览器内置 AI(Window AI)」研发
痛点:你想在网页里直接调用 Chrome 内置的 Gemini Nano(如 window.ai.languageModel)做本地文本摘要。但由于这些 API 太新,市面上的大模型(如 GPT-4o)根本没有这些训练数据,或者全都在胡思乱想乱编 API。
MWG 的解法:你在开发一个在线文档 Web 应用,想加一个“本地 AI 摘要”功能。
本地运行:AI 触发 MWG 中关于 Built-in AI (WebMCP & Prompt API) 的官方权威规范指南。
结果:AI 写出的代码极其精准,包含了规范中要求的 capabilities() 检查、流式返回(readableStream)的正确处理,以及模型未下载时的用户提示逻辑,一行没偏。
💻 针对【Electron 桌面端 Web 应用】的场景与痛点解决
作为高级前端你一定知道,Electron 应用的一大死穴就是内存和多进程性能消耗,同时它又要求极致的原生桌面级体验(如无缝拖拽、硬件加速、多窗口卡顿控制)。
场景 1:解决多组件、多卡片容器的高性能响应式(Container Queries)
痛点:在 Electron 做的看板软件(类似 Trello 或 飞书文档)中,组件会根据拖拽放入不同的父容器中。如果用传统的 window.addEventListener('resize') 去用 JS 动态改写各个组件的样式,当卡片多了以后,Electron 的渲染进程(Renderer Process)CPU 会瞬间飙高甚至假死。
MWG 的解法:你让 AI 编写一个可以任意拖拽、自适应复杂布局的桌面看板卡片。
本地运行:MWG 截获需求,向 Agent 注入 Container Queries(容器查询) 和 Subgrid(子网格) 的深度 Dos & Don'ts。
结果:AI 写出的卡片完全基于 @container。当卡片在桌面被任意拉伸或放入狭窄的侧边栏时,渲染完全由 Chromium 底层 C++ 搞定,JS 线程零消耗。同时自动避开了“在 Flex 元素上混用 flex-basis 和 width 导致 Electron 渲染错位”的经典隐蔽 Bug。
场景 2:Electron 特殊视图的无缝性能优化与无障碍(A11y)
痛点:Electron 应用经常需要用 flex-direction: row-reverse 或者 order 去动态做视图的上下/左右翻转切换(例如聊天软件的左右侧边栏切换)。这时候,键盘聚焦(Tab 键导航)的顺序其实还在原地,导致视觉顺序和 DOM 焦点顺序不一致,这在桌面端单凭鼠标/键盘盲操时是灾难性的体验。
MWG 的解法:当你给 Agent 下达重构 Electron 侧边栏的指令时。
本地运行:MWG 在本地检索到一条重磅的 CSS Layout Don'ts:“绝对不要在可交互内容上使用 grid-auto-flow: dense 或 order 来改变视觉,这会破坏屏幕阅读器和键盘 Focus 的 DOM 链”。
结果:AI 被本地规约“喝止”了,它会主动放弃偷懒的 CSS 翻转方案,转而通过 Electron 渲染进程高效修改 DOM 结构的语义化方案,并自动把 tabindex 树整理得漂漂亮亮,直接通过了桌面无障碍合规性审查。
💡 总结
对于你(高级前端)来说,npx modern-web-guidance install 解决的绝对不是“怎么写 div”的问题,它是一个工程治理工具。
它通过本地离线算力,在你编写外部 Web 平台应用和内核敏感的 Electron 应用时,把 Google 和 Edge 团队最新的性能红线、现代 API 实践、以及底层的避坑经验,强行卡在 AI 产出代码的前一秒注入进去。
这确保了你的 Agent 既有大模型的通用编程逻辑,又拥有一个“不脱网、懂最新 Chromium 内核原理的前端专家”在本地实时给它做 Code Review。
接下来,你想继续深入看看它是怎么强行扭转 AI 代码的对比示例,还是我们直接推进到第二样——在 Chrome 150+ 已经正式由 navigator 升级为 document.modelContext.registerTool 的 WebMCP 运行时?
还有你刚才提到第二点 web MCP 我看了大概是理解了,但现在这个落地情况是什么样?它什么时候可以使用呢?就现在就可以使用吗?比如它对 Chrome 的版本要求是什么?内置浏览器是否可以使用?Safari 是否可以使用?然后有哪些现场的案例可以测试和演示?这样不用自己写 demo 了,找到一些合适的场景给我科普做一个说明
作为高级前端,你最关心的必然是兼容性红线、API 稳定性以及现成的调试环境。WebMCP(Web Model Context Protocol)是近期由 Google、Microsoft 工程师在 W3C 社区组(Web Machine Learning Community Group)联合推进的拟议 Web 标准。
关于它的落地现状、版本要求、生态支持,我们可以从以下几个最硬核的指标来拆解:
1. 落地现状与版本要求:能用了吗?
现状结论:目前处于 Early Preview(早期预览)和快速演进阶段,属于“可以在实验室、特定产品线(如 AI 浏览器/插件生态)进行试验和落地,但尚未进入主流大众浏览器 Stable 默认开启”的状态。
API 变更: 这个标准演进极快。就在近期,原先的 navigator.modelContext 已经因为架构调整被废弃(Deprecated),全面迁移到了 document.modelContext(部分地方也在推进 window.modelContext)。如果你现在写 demo,应该使用 document.modelContext.registerTool。
Chrome 版本要求: * 支持起点是 Chrome 146+(于 2026 年初在 Canary 频道首次引入)。
目前最新的 Chrome 149 和 150+ 已经内置了更完善的实验支持。
如何开启: 它是默认关闭的。你需要在 Chrome 地址栏输入 chrome://flags,搜索并启用 #enable-webmcp-testing 和 #devtools-webmcp-support(用于开发者工具调试面板)。
内置浏览器(如 WebView、Electron、移动端)是否可用?
Chromium 内核的套壳/内置浏览器(如新版 Electron、Tauri 等): 如果其底层 Chromium 内核升级到了 146+,并且你在启动时显式传递了对应的开启 Flags 命令行参数(--enable-features=WebMCP),它是完全可以使用的。
微信/支付宝等内置 WebView: 目前无法使用。因为这类内置 WebView 往往内核版本滞后,且为了安全性会主动裁剪、禁用这类直接和系统级 AI 引擎或底层上下文通信的实验性 API。
Safari 和 Firefox 是否可以使用?
Safari (WebKit) 和 Firefox (Gecko): 目前完全不支持。这是由 Google 和 Microsoft 主导的 W3C 提案,Apple 和 Mozilla 目前还在持观望态度。短期内(2026年内)不要指望 Safari 会原生支持它。
2. 现成的案例与演示场景(如何测试?)
目前由于它是早预发布阶段,各大公网商业网站(如携程、淘宝)还没有在生产环境大规模上线(因为普通用户默认开不了 flag),但 Google 官方和开源社区已经提供了极其完备的调试工具和现成场景。
你不需要自己从零写模型、写复杂的 agent 交互,可以通过以下“现成案例”和调试套路直接体验:
场景 A:使用 Chrome DevTools 自带的 WebMCP 调试面板(最推荐)
在最新的 Chrome 149/150 中,DevTools 已经在 Application(应用)面板的侧边栏中直接内置了 WebMCP 调试工具。
测试方法: 1. 开启上述 flags 后,打开任意一个你自己的前端本地网页。
2. 在控制台直接粘贴一段注册代码,比如注册一个叫 change_theme 的工具:
JavaScript
document.modelContext.registerTool({
name: "change_theme",
description: "当用户要求切换网页暗黑/明亮模式时调用此工具",
parameters: { type: "object", properties: { mode: { type: "string", enum: ["dark", "light"] } } },
execute: async ({ mode }) => { document.documentElement.className = mode; return { success: true }; }
});
打开 F12 开发者工具 -> Application 面板 -> 找到 WebMCP 侧边栏。你会看到你注册的工具已经以完美的 JSON Schema 形式可视化地躺在那里。你可以在 DevTools 里模拟 AI 直接点击“触发(Invoke)”它,看你的网页是否做出了响应。
场景 B:Google I/O 2026 官方演示场景——"Agentic Era 智能体购物"
在今年 Google I/O 开发者大会的 “Build your website for the agentic era” 专题中,官方释出了专门的演示场景。
科普说明: 设想一个电商网站。传统的 AI Agent 要帮你买衣服,需要用爬虫去扫 DOM 里的 input,经常因为页面改版找不到输入框。
WebMCP 落地表现: 该演示网站在底层直接部署了 WebMCP 声明式(HTML tags)和命令式 API。当用户拉出 Chrome 的侧边栏 AI 助理(基于内置的 Gemini Nano),对助理说:“帮我把这件衣服加入购物车,并改成 L 码”。
交互细节:
浏览器直接调用了该网页注册的 add_to_cart(size, quantity) 工具。
网页甚至可以捕获到一个新型的事件:SubmitEvent.agentInvoked。这让前端能够感知到:“噢!这次提交不是人类用鼠标点的,而是 AI Agent 帮他点的”。
这样,网站可以自动跳过繁琐的滑动验证码、或者弹出一个优雅的二级确认框(“AI 正在帮您下单,请确认金额”),实现了完美的人机协同。
场景 C:开源社区的 WebMCP DevTools 扩展插件
Chrome Web Store 上目前已经有了 WebMCP DevTools Extension 官方/社区辅助插件。它提供了一个直观的 Playground,让你在没有写任何 Agent 客户端的情况下,直接在侧边栏用自然语言对当前标签页下达指令,它会去匹配页面上的 WebMCP 工具并执行。
💡 针对高级前端的落地建议
短期内(2026年中): 把它当作 Electron 桌面应用、企业内部特定 AI 浏览器插件生态、或是面向 AI 编码工具(如 Claude Code、Cursor) 的特定优化技术。如果在公网 Web 2C 业务中使用,需要做好 if (document.modelContext) 的渐进增强(Progressive Enhancement)判断,绝不能当作硬性依赖。
它的终局思考: 以前我们做前端是给“人类的眼睛”看的(注重 UI/UX),而 WebMCP 的出现意味着前端研发正式进入“面向 AI 代理编程(Programmable for Agents)”的时代。你的网站不仅要有漂亮的界面,还要有一套通过 document.modelContext 暴露给浏览器的完美 API 声明,这才是未来 1-2 年内大前端的重要护城河。
我理解一下你说的第一个事儿,第一个事儿有点像咱之前的这个外部兼容性有个 bounce list, 它会内置一个 circle light, 通过这种方式来查询当前的 CSS 后缀是不是要增加兼容代码。而这个工具呢,是把 baseline 的最新最新属性最新值内置进去了,并实时更新。后面比如我们说在使用 flash 的时候,可能在某些情况下会出现幻觉,需要使用非常复杂的 flash,这个有 bug 版本,或者说我们再写一些简单的透视展示的时候,我们需要使用 JS 来做啊。引了这个工具,这个工具是 MCP 或者 K,我忘是哪一个使用它来之后呢,他会自己去查库,看就是有没有更好的方案。这样的话,他可能就使用 HTML+CSS 就可以来完成,不用引入复杂的业务逻辑?
你这个类比太有灵性了!你提到的 bounce list(比如我们前端熟知的 browserslist / caniuse 数据集)和 CSS 前缀自动补全(比如 autoprefixer),和这个工具的底层逻辑在本质上是完全相通的。
你完全抓住了核心。我们来做个精准的对齐:
以前的模式(人类+自动化工具):我们把最新的兼容性数据(Baseline 数据)写进本地的 node_modules(如 browserslist),打包工具去查这个库,发现某一代内核不支持,就自动加上 -webkit- 前缀,或者通过 Babel 把高级语法编译成打包后的 JS 老代码。
现在的模式(AI Agent + MWG):大模型(AI Agent)成了写代码的人,但大模型不知道最新的浏览器内核支持到哪了(它有幻觉、有数据滞后)。所以,Google 联合微软把最新的 Baseline 权威数据和现代 Web 避坑指南 变成了本地的向量库。当 AI Agent 想用复杂的 JS 去算坐标、或者准备用老旧的 Bug 语法硬啃一个特效时,这个本地工具(MWG)就会像一个智能的拦截器(Interceptor),查库后对 AI 说:“别折腾 JS 了,现在 Chromium 140+ 已经原生支持这个 CSS 特性了,用这个优雅方案,我把官方标准喂给你!”
💡 针对你提到的两个经典场景,我们来看看它是怎么消灭复杂业务逻辑的:
场景一:你提到的“简单的透视展示 / 悬浮弹出层(复杂 Flash 或 JS 计算)”
像你说的,以前做一些具有层级透视、悬浮、跟随鼠标或特定锚点弹出的复杂交互(以前可能用 Flash,后来用复杂的 JS 去算 getBoundingClientRect()、动态监听 scroll),不仅代码冗长,还特别容易在边界情况(如滚动条、缩放)下出现错位 Bug。
AI 的盲区:如果你让 Claude Code 或 Copilot 帮你写,它们受旧数据影响,大概率还是会去引入一个几万行的 popper.js 或者写一堆复杂的 JS resize 监听逻辑。
MWG 的介入:当 AI 准备写这一堆 JS 业务逻辑时,MWG 在本地检索到最新的 CSS Anchor Positioning(锚定定位 API)。它直接把标准喂给 AI。
最终代码:AI 放弃了 JS 计算,只写了下面这两行纯 CSS。浏览器底层用 C++ 自动去算透视和避让坐标,页面性能提升几个数量级,业务逻辑里一行 JS 都没有。
CSS
.my-popup {
position: anchor(bottom right); /* 纯 CSS 原生锚定,零 JS 消耗 */
position-try-options: flip-block, flip-inline; /* 空间不够时自动翻转透视 */
}
场景二:视图翻转与焦点错乱(无障碍与性能潜规则)
再比如你让 AI 写一个复杂的网格(Grid)看板,为了实现某种酷炫的“透视或重排”视觉效果,AI 可能会用 JS 去动态计算每一个卡片的 DOM 位置并重新渲染。
MWG 的介入:MWG 查库发现,针对这种现代布局,CSS Grid 的 Subgrid(子网格) 和 Container Queries(容器查询) 已经是现在的 Baseline 标准了,而且它会警告 AI:“不要用 JS 去改 DOM 顺序,否则键盘聚焦(Tab 键)会错乱!”
最终代码:AI 乖乖听话,用纯 CSS 实现了极其复杂的自适应网格透视,不仅消除了 JS 业务逻辑,还顺手把无障碍(A11y)的坑给避开了。
🛠️ 澄清一下你提到的名词(MCP 还是其他的?)
你提到的“它是 MCP 还是什么”,这里有一个很清晰的边界:
npx modern-web-guidance(MWG):它在形式上是一个本地 RAG(检索增强生成)工具/Agent 插件。它不需要复杂的网络 MCP 协议,它直接通过本地命令行(CLI)和本地微型模型(TensorFlow.js)和你的 AI 工具交互。它是用来帮你(高级前端)在写代码时卡死红线的。
WebMCP(document.modelContext):它是你提到的第二个事,是运行时(Runtime)的浏览器标准协议。它是你的网站做好了、上线了之后,用来给浏览器的 AI Agent 开放接口(Tools)的。
所以,你现在的理解完全正确:MWG 就是新时代的“AI 专用版 Browserslist + 实时避坑补丁”。它利用本地算力查库,强行用最新的 HTML5 / CSS3+ 标准 替代掉 AI 试图写出来的、臃肿且带 Bug 的旧 JS 业务逻辑。
你觉得这种在编写阶段就用“本地标准库”强行纠偏 AI 的工程思路,能解决你们目前团队在 AI 辅助编程时遇到的代码质量失控问题吗?
Gemini 是一款 AI 工具,其回答未必正确无误。