Modern Web Guidance：让AI写原生声明式对话弹窗

浏览器原生能力正在被AI编程助手重新发现。Google 推出的 Modern Web Guidance 项目，试图让 AI 在生成代码时优先使用平台自带的声明式 API，而不是继续堆砌熟悉的 JavaScript 事件监听。

问题：AI 默认写的是「旧代码」

当前大多数 AI 编程助手在实现弹窗、抽屉、提示框这类交互时，会条件反射式地写出一套事件监听逻辑。以本文演示的评论弹窗为例：左侧未启用 Modern Web Guidance 的 agent，在 index.html 中放了一个普通按钮，然后在 JavaScript 里生成了四个独立的事件监听器，分别负责打开对话框、关闭对话框以及实现点击遮罩层关闭的 light dismiss 行为。

这套写法能跑，但代码量大、重复度高，而且在无障碍、焦点管理和浏览器兼容性上往往依赖开发者手动兜底。浏览器平台其实早就提供了更简洁的声明式方案，只是 AI 不知道。

Modern Web Guidance 如何介入生成流程

Modern Web Guidance 的核心机制是在 agent 的推理过程中挂载一份「能力指南」。启用方式有两种：在 anti-gravity 环境中直接开启，或者安装到你所使用的编码 agent 中。

在实际演示中，操作者通过一个 slash command 显式调用该技能，确保 agent 会去检索对应的指南条目。演示的 prompt 是「实现这个新功能」，随后左右两侧的 agent 走上了不同的路径：左侧 agent 直接读项目、做规划、开始写代码；右侧 agent 则先搜索 Modern Web Guidance 中的对话模态相关条目，命中了一份名为 declarative dialogue pop-over control 的指南，并把这份指南拉入了上下文窗口。

这一步是整个流程的关键分叉点。命中指南之后，agent 的生成行为从「凭训练数据里的常见写法」转变为「参考平台推荐写法」。

AI 编程助手的上下文检索机制

当前主流编码 agent 在生成代码前的推理流程通常包括：读取项目文件、规划实现步骤、检索可用工具或知识库，最后才输出代码。Modern Web Guidance 的介入点位于「检索」阶段——它把一份结构化、持续维护的平台能力指南挂载为 agent 可调用的技能（skill），只有当 prompt 或任务语义与某条指南匹配时，agent 才会将其拉入上下文窗口。

这种按需注入的方式有两个好处：一是避免无关知识挤占有限的上下文预算，二是把「使用平台推荐写法」变成一次显式的检索动作，而不是依赖模型在训练数据里碰运气。因此，命中指南与否会直接改变 agent 的生成路径：未命中时倾向复用训练数据中的常见模式（往往是大段事件监听），命中后则转向平台原生、声明式的实现。理解这一机制，就能明白为什么安装指南之后，同一句「实现这个新功能」会产生形态完全不同的代码。

声明式 dialog：用属性替代事件监听

启用指南后生成的代码差异集中在两个文件。

HTML 侧，按钮不再只是一个裸元素，而是加上了 command 相关的 invoker command 属性，并配有 commandfor 与 close 值。这套属性直接告诉浏览器该按钮控制哪个 dialog，以及它执行的是打开还是关闭动作，浏览器据此可以安全地完成 dismiss 行为。

JavaScript 侧，生成的内容只剩下一段针对 closeby 的 fallback，用于在尚不支持该特性的浏览器中保持功能可用。切换 modal 和 light dismiss 都不再需要额外的事件处理器。

两边最终跑起来的效果相似，但引导版运行的代码量更少。这种「代码变少、依赖平台」的取向，正是 Modern Web Guidance 想推动的方向。

什么是 invoker command 属性

HTML 的 invoker command 属性（包括 command 与 commandfor）是浏览器平台为按钮（通常指 <button>）提供的声明式控制机制。开发者无需手写 JavaScript 事件监听，只需在按钮上声明 commandfor="目标元素ID" 指定被控元素，再用 command="show-modal"、command="close" 或 command="toggle-popover" 等值描述要执行的动作，浏览器便会自动完成对应行为，并内置处理好焦点管理、无障碍语义和必要的安全校验。

对弹窗场景而言，commandfor 指向 <dialog> 的 id，command="close" 表示点击该按钮关闭对话框。这类属性把原本散落在脚本里的开关逻辑收归为标记的一部分，因此当 AI agent 生成代码时，引导它优先使用 invoker command 可以显著减少事件绑定、DOM 查询和状态同步代码。需要注意的是，该特性仍处于逐步落地阶段，主流浏览器支持度不一，这也是文章示例中保留 closeby fallback 的原因。

light dismiss 与 closeby 的工作原理

light dismiss 指用户点击对话框外部区域（遮罩层）或按下 Esc 键时自动关闭弹窗的交互模式，属于浏览器对模态行为的原生支持。过去实现这一效果通常需要监听 document 上的 click 事件，判断点击目标是否位于 dialog 边界之外，再手动调用 close 方法。

HTML 新增的 closeby 属性（用于 <dialog>）则把这一判断交还给浏览器：声明 closeby 后，浏览器会在用户点击对话框外部或按下 Esc 时自动关闭它，无需任何 JavaScript。这与 closedby 属于同一类平台能力，用于统一控制弹窗的关闭触发源。由于 closeby 的浏览器覆盖率尚不完整，文章示例中生成的后备代码正是检测该属性是否被支持，不支持时再回退到传统的事件监听方案，从而在渐进增强与可用性之间取得平衡。

对开发者的实际意义

这个演示最有价值的地方不在于某个 dialog 怎么写，而在于它揭示了一种让 AI 输出更贴近平台最佳实践的可行路径。AI 编程助手的能力上限很大程度上取决于它能否拿到正确的上下文；训练数据里充斥着过时或次优的写法，靠模型自己「悟」出原生 API 并不现实。

通过外挂一份持续维护的指南，agent 可以在生成前先检索、再落笔，把重复的样板逻辑交还给浏览器。对于维护大型前端项目的团队来说，这意味着更少的自定义事件管理代码、更少的兼容性补丁，以及更贴近渐进增强理念的实现。当然，fallback 机制仍然不可省略——指南本身也把对 closeby 的支持检测写进了生成结果里，说明「使用原生能力」和「保证可用性」并不冲突。

如果你正在用编码 agent 处理前端任务，值得把这份指南装进工作流试一次。安装入口在 goo.gle.mwg。

渐进增强在现代前端中的位置

渐进增强是一种从可用内容出发、逐步叠加增强体验的开发策略：基础功能在尽可能广泛的浏览器中都能运行，高级特性则只在支持它们的浏览器上生效。文章中的引导版实现正是这一理念的体现——声明式 command / closeby 提供更简洁的原生路径，而针对不支持这些属性的浏览器保留 fallback 脚本，确保弹窗依然可以正常开关。

这与「只面向最新浏览器」的激进做法不同，也与「完全依赖 polyfill 抹平差异」的旧思路不同。它的关键在于识别哪些能力可以由平台原生承担、哪些必须由开发者兜底，并把边界清晰地写进代码结构里。当 AI agent 被引导优先采用平台能力时，它生成的代码天然更贴近渐进增强；但前提是 agent 也理解降级策略，否则在兼容性上反而可能留下缺口。对维护大型前端项目的团队来说，把渐进增强作为默认取向而非事后补丁，才是减少长期维护成本的关键。