Modern Web 指南如何让 AI 写现代前端代码

Modern Web Guidance 不是承担整个前端开发流程的代码生成器。它把现代 Web 最佳实践封装成编码 Agent 可以识别、加载和执行的技能包，让模型在生成代码时优先考虑浏览器原生能力、安全实践与扩展发布规范。它的价值不在于增加一个更长的提示词，而在于改变模型面对 Web 能力时的默认答案。

因此，Chrome Modern Web Guidance 开源源码解析的重点，并不是逐页阅读 Markdown，而是理解现代 Web 知识如何被组织成 Agent 可以消费的技能：入口如何描述和触发技能，正文如何给出约束，引用文档如何按需补充细节，以及这些规则最终能否在生成代码和真实浏览器中生效。

这个仓库解决什么问题

modern-web-guidance-src 的核心交付物不是 React、Vue 或某个前端脚手架，而是一组结构化规则。它试图解决 AI 编码中的默认选择问题：模型在可以选择 fetch、轮询、服务端代理或浏览器原生 API 时，是否知道哪些选择更符合当前 Web 平台；面对 DOM 注入、身份认证和扩展权限时，是否会主动采用更安全的实现。

它和几种常见形态的区别如下。

形态	主要内容	进入模型的方式	约束强度
普通提示词	一段临时要求	用户每次复制进上下文	容易被长上下文稀释
规则文档	完整规范、示例和模板	人工查找后粘贴	内容完整，但发现和加载不稳定
编码 Agent 技能包	技能描述、核心指令、引用文档、模板	Agent 根据任务语义发现并加载	仍然是模型指令，不是编译器级约束
代码生成器	模型、工具链和项目脚手架	直接执行并产出代码	负责生成，但不天然掌握团队的 Web 规范

Modern Web Guidance 位于“提示词”和“代码生成器”之间。它不替开发者决定页面结构，也不直接输出一个完整应用，而是向已经具备编码能力的 Agent 提供现代 Web 规则。相关介绍将其描述为把现代 Web 平台最佳实践注入 AI 编程助手的技能包；另一份资料引用了它面向 AI Agent、改善前端代码质量的定位，并称其为“The Anti-Slop Frontend Framework for AI Agents”.

技能仍然是软约束。模型可能没有触发技能，也可能只读了摘要而没有打开引用文档，还可能理解了规则却在具体代码中执行偏离。安装成功只说明规则已经进入可发现的位置，不能保证每次生成都会遵守。

源码应按什么顺序阅读

这个仓库会持续更新，因此分析时不应把 main、某个目录或一条命令写成永久事实。分析应记录完整 commit SHA，并把结论绑定到该版本。

git clone https://github.com/GoogleChrome/modern-web-guidance-src.git
cd modern-web-guidance-src
git rev-parse HEAD
git status --short
git log --oneline --all -n 20

git rev-parse HEAD 的输出才是一份可复现分析记录中的版本标识。正式发布文章时，应同时保留访问日期、完整 SHA 和关键文件路径；只写仓库名或分支名，后续很容易无法判断某条命令究竟对应哪个版本。

推荐的阅读顺序是“README → 技能入口文件 → 引用文档 → 示例与模板 → Git 提交历史”。这套顺序对应的是一条从发现到执行的链路，而不是从项目宣传到具体代码的顺序。

路径或层次	职责	触发场景	影响哪类输出
README.md	项目定位、技能清单、安装入口和目录说明	用户判断是否采用、如何安装	接入方式和技能选择
各技能目录中的 SKILL.md	描述适用任务，给出核心工作流和约束	Agent 识别到任务与技能匹配	后续代码的默认选型
技能引用的规则文档	补充平台 API、安全要求和边缘情况	核心技能要求继续查阅	具体实现细节
示例与模板	展示预期产物、字段和写作格式	任务需要产出扩展或文档	代码及发布材料的结构
CHROMEWEBSTORE.md	Chrome Web Store 发布信息的单一事实源	功能、权限或数据收集方式变化	商店描述、权限说明等材料
chromewebstore-template.md	将发布信息映射到后台字段	准备提交商店审核	必填项、建议项和素材规格
permissions.md	权限选择与解释原则	生成 manifest.json 或审核权限	API 权限与主机权限
privacy-policy.md	隐私政策和数据申报要求	涉及数据收集或敏感权限	隐私文案及后台申报
Git 提交历史	解释规则为何变化	升级、回归定位和团队审阅	规则可信度与维护成本

表中的发布文件名称和职责来自 chrome-extensions 技能资料。它们在具体版本中的父目录可能调整，解析时应以 SKILL.md 内的链接为准，不应凭文件名猜路径。

以 chrome-extensions 为切入口，可以观察整个仓库的组织方式：技能入口负责识别“正在开发 Chrome 扩展”的任务，permissions.md 决定最小权限，CHROMEWEBSTORE.md 汇总发布事实，chromewebstore-template.md 将这些事实映射到商店后台，privacy-policy.md 则约束隐私说明与数据申报。这比单独阅读某一份规则更容易理解现代 Web 指南的设计思路。

一条规则怎样进入 AI 的上下文

现代 Web 知识进入模型上下文的过程，可以拆成五步：

1. Agent 先读取技能名称和描述，判断当前任务是否匹配。
2. 匹配成功后，Agent 打开 SKILL.md，获得核心规则和执行步骤。
3. 当正文要求查看细节时，再加载权限、安全、平台兼容性等引用文档。
4. Agent 根据已经加载的规则生成代码、配置或文档。
5. 项目通过静态检查和真实浏览器测试验证结果。

其中，“技能描述负责发现，技能正文负责约束，引用文档负责补充细节”属于 Agent Skills 的通用组织方式；“Chrome 扩展发布信息由 CHROMEWEBSTORE.md 统一维护”则是这个仓库自己的内容设计。

假设开发者要求：“做一个 Chrome 扩展，在用户点击扩展按钮后高亮当前网页中的选中文本。”一个支持技能机制的 Agent 可能先匹配到 chrome-extensions，然后读取权限规则，判断这个场景不需要长期访问所有网站，接着生成使用 activeTab 的 manifest.json。准备提交商店时，它再读取 CHROMEWEBSTORE.md 和模板，补齐权限解释、商店描述及素材清单。

不同 Agent 的技能发现和加载方式并不相同。CLI 型编码 Agent 往往在启动时扫描技能，或者根据任务描述动态打开技能；IDE 型 Agent 可能把技能显示在侧边栏，要求用户确认加载；只支持普通项目规则文件的 Agent 则不会自动完成技能发现。即使两个 Agent 都宣称支持技能，一个可能默认完整加载，另一个只在任务明显匹配时加载引用文档。

上下文预算也会改变结果。完整安装所有技能可以减少漏项，却可能把大量无关规则塞进上下文；按需安装更节省上下文，但如果触发描述写得太窄，Agent 可能根本没有加载需要的技能。规则内容、加载策略和模型能力必须一起评估。

哪些现代 Web 能力值得优先交给 AI

仓库涉及的方向可以归纳为现代浏览器平台能力、浏览器原生 AI、前端安全，以及 Chrome 扩展构建与发布。它们并不是同等确定的“最佳实践”，接入时需要区分平台基础能力、实验性能力和依赖具体运行环境的能力。

以浏览器原生 AI 为例，相关资料重点讨论了 Prompt API 和 Translator 的端侧推理路径。代码结构示意如下，实际方法名和参数仍应以目标浏览器版本为准：

async function summarizeWithBrowserAI(input, fallback) {
  if (!("LanguageModel" in window)) {
    return fallback(input);
  }

  const session = await window.LanguageModel.create();
  return session.prompt(input);
}

这类规则引导 AI 生成的代码先识别浏览器是否具备对应能力，再决定是否使用端侧推理；不支持时走服务端、静态结果或其他降级路径。它改变的不只是 API 名称，还包括错误处理、模型就绪状态、用户权限和回退策略。

Translator 可以采用相同结构：先检测能力，再创建翻译器，最后处理不可用场景。这里不能把“现代”写成“所有浏览器均可直接使用”。浏览器版本、操作系统、设备条件、模型下载状态和语言支持，都可能影响最终结果。

安全规则覆盖 Passkey、Trusted Types 与 HTML 净化。三者的关注点不同：

• Passkey 把认证凭据绑定到 WebAuthn 流程，生成代码时不能省略服务端挑战和验证环节。
• Trusted Types 用浏览器策略约束 DOM 注入路径，但它不是 HTML 净化器，仍需要可靠的白名单净化实现。
• HTML 净化负责处理不可信输入，不能因为使用了一个现代 DOM API 就省略服务端校验和输出编码。

Modern Web Guidance 所强调的“现代”有明确边界：优先采用平台能力的前提，是同时检查权限、兼容性、安全边界和降级方案。

同一需求前后生成结果会差在哪里

差异最容易出现在权限申请上。假设一个扩展只需要在用户点击工具栏按钮后操作当前页面，没有接入指导时，模型可能生成这样的宽权限配置：

{
  "manifest_version": 3,
  "permissions": ["tabs"],
  "host_permissions": ["<all_urls>"]
}

接入 chrome-extensions 技能并读取权限规则后，更合理的候选方案可能是：

{
  "manifest_version": 3,
  "permissions": ["activeTab", "scripting"]
}

如果功能明确只服务于一个特定域名，则可以进一步收窄主机权限：

{
  "manifest_version": 3,
  "permissions": ["scripting"],
  "host_permissions": ["*://*.example.com/*"]
}

这里的 scripting 是否需要，仍取决于扩展是否真的调用脚本注入 API，不能机械添加。这些变化不只体现在代码行数上：宽泛的主机权限扩大了可访问范围，而 activeTab 更适合用户主动触发当前标签页的场景；限定具体域名则把能力约束在明确业务范围内。这些选择会同时影响安全说明、商店审核成本和后续维护。

Chrome Web Store 资料还区分了 permissions 与 host_permissions：前者主要对应 chrome.* API 访问权，后者对应跨域数据访问权。权限解释应分别写清用途，例如“读取用户访问的网站数据，用于在网页上高亮选中的文字”比营销式描述更容易说明实际功能。

原生 AI 场景中的差异则更偏向执行结构。没有技能约束时，生成结果可能只有一个笼统的服务端调用；接入规则后，代码更可能包含能力检测、就绪状态、错误分支和降级路径。这里仍不能仅凭代码出现某个 API 名称就判定合格，因为 API 可能处于实验阶段，或者目标浏览器并不支持。

项目强调“反泔水前端框架”，也意味着验收不能只检查 API 是否运行。生成代码的层级、响应式状态、可访问性以及视觉一致性仍需要人工评审。规则可以提高默认质量，但不能替代设计判断。

怎样接入不同编码 Agent

按仓库 README 公布的方式，正式安装入口仍采用 npx skills add，仓库参数为 GoogleChrome/modern-web-guidance-src：

npx skills add GoogleChrome/modern-web-guidance-src

自动化环境执行前，应先核对当前 CLI 的参数，避免从旧文章复制已经变化的选项：

npx skills add --help

当前 skills CLI 的完整安装流程会解析仓库中的技能，并允许在交互界面选择需要安装的项目和目标 Agent。只启用扩展技能，可以使用按需入口：

npx skills add GoogleChrome/modern-web-guidance-src --skill chrome-extensions

需要作为个人跨项目环境使用时，可以采用用户级安装：

npx skills add GoogleChrome/modern-web-guidance-src --global

这些属于 CLI 层选项，而不是仓库自身定义的规则参数。如果本机帮助输出与上述命令不同，应以实际安装器为准。当前 CLI 通常把项目级技能放在 .agents/skills/，用户级技能放在 ~/.agents/skills/，并可能为 Claude Code、Cursor、Codex 等支持的 Agent 建立各自的链接或入口；最终落盘位置应以安装输出为准。IDE 型 Agent 不一定自动索引 CLI 安装的目录，修改后通常还需要刷新工作区或重新加载 Agent。

更新已安装技能前，先查看当前 CLI 的更新范围：

npx skills update --help

对于由 CLI 管理的安装，可以执行：

npx skills update

团队基线不应通过这条命令直接更新到上游最新状态。更稳妥的做法是 fork 仓库，由团队审阅规则变化，再更新项目级安装，并保留新的 commit SHA。

使用场景	建议方式	原因
本机临时试用	临时项目目录或用户级安装	启动快，不污染团队仓库
单个项目使用	项目级、按需安装	目录、版本和变更容易追踪
团队统一基线	fork、固定 SHA、项目级安装	所有人都使用经过审阅的同一版本
不支持技能目录的通用 Agent	手工转换为项目规则文件	保留触发条件和关键引用，同时适配宿主机制

对于不支持技能机制的 CLI 或 IDE，可以克隆仓库后，手工引入最相关的 SKILL.md 及其引用文档。引入时无须复制全部 Markdown，应保留三部分：何时应用规则、必须遵守的约束、需要继续查阅的资料。可以将这些内容整理进项目已有的 AGENTS.md、IDE 规则文件或 Agent 的自定义指令中，并在文件头部记录来源仓库和 commit SHA。

对团队来说，项目级安装通常比用户级安装更合适。后者适合个人跨项目试用，却很难保证不同开发者、不同机器使用同一规则版本。长期使用还应建立提示词回归样本，覆盖新组件生成、旧项目现代化、Bug 定位、代码审查和浏览器 API 选型，防止规则升级后出现静默退化。

怎么确认 Agent 真的执行了规则

最直接的验证方式是使用相同模型、相同任务和尽可能一致的项目上下文，分别在无指导与有指导条件下生成代码，再做 A/B 对比。Agent 在回答中说“我已经读取 Modern Web Guidance”，不能作为执行证据。

测试任务可以包括：

• 生成一个带加载、空状态和错误状态的新组件；
• 把使用过时浏览器写法的旧页面迁移到现代 API；
• 定位一段涉及 DOM 注入或身份认证的 Bug；
• 审查一个申请了宽泛主机权限的扩展；
• 在原生 AI 不可用时设计降级方案。

对比时不要只看“代码是否更短”，而应检查以下项目：

验收维度	通过标准	证据
API 选型	使用了目标现代能力，没有回退到不必要的替代方案	代码差异、审查记录
权限	只申请功能实际需要的 permissions 与 host_permissions	manifest.json、权限说明
兼容性	包含能力检测、错误处理和降级路径	代码、测试用例
安全	不可信输入经过净化或安全 API 处理	安全测试、审查意见
发布材料	权限、功能、隐私文案与实际行为一致	发布资料对照表
运行结果	在目标浏览器和扩展环境中行为符合预期	浏览器测试记录

每次测试至少记录 Agent 名称、模型版本、仓库 commit SHA、浏览器版本、操作系统和测试日期。这样才能区分问题来自规则缺失、技能未触发、上下文截断、模型执行偏差，还是运行环境根本不支持目标 API。

还可以检查 Agent 的技能加载日志，确认它是否打开了目标 SKILL.md 以及必要引用。日志只能证明“读过”，不能证明“正确执行”，因此仍然需要代码检查和真实浏览器验证。

做 Chrome 扩展时为什么多一道发布检查

chrome-extensions 技能的价值不只是生成 manifest.json，还包括把构建和上架资料串成一条可复用的流程。其中，CHROMEWEBSTORE.md 是发布信息的单一事实源。功能、权限或数据收集方式变化时，应先更新这份文件，再同步到商店后台，避免代码已经改变，权限说明和隐私文案却仍停留在旧版本。

chromewebstore-template.md 负责把事实映射到提交表单，并区分 [REQUIRED] 与 [RECOMMENDED] 字段。资料列出的素材规格包括 128×128 的商店图标和 1280×800 的截图。必填字段缺失会直接阻塞提交，建议字段则可以根据扩展定位和商店页面质量决定是否投入制作。

发布检查至少覆盖以下环节：

1. 根据真实功能确定 API 权限和主机权限。
2. 在 CHROMEWEBSTORE.md 中同步功能、权限和数据收集说明。
3. 按 chromewebstore-template.md 准备商店名称、描述、图标、截图等材料。
4. 对照 permissions.md 检查权限解释。
5. 对照 privacy-policy.md 检查隐私政策 URL、数据收集描述和后台申报。
6. 在真实扩展环境中验证权限、核心功能和商店文案是否一致。

权限环节尤其容易被泛化处理。最小权限原则要求删除历史功能遗留的“僵尸权限”；只在用户点击扩展图标后访问当前页面时，activeTab 通常比 tabs 加 <all_urls> 更合适；必须持续访问特定站点时，host_permissions 应尽量限定具体域名，而不是直接覆盖整个网络。

这不能保证“一次通过”审核。商店审核还会考虑功能描述、隐私合规、代码行为和用户数据处理方式。技能提供更一致的材料和更早的自查机制，但不能保证审核结果。

这套规则会在哪些情况下失效

Modern Web Guidance 的维护成本主要集中在规则触发、版本同步和浏览器验证，而不是安装本身。常见失效方式如下。

失效场景	表现	排查与处理
Agent 没有触发技能	输出仍是通用脚手架或旧写法	检查任务描述、技能发现结果和 Agent 日志
只记住规则摘要	主流程正确，但遗漏权限、隐私等细节	要求继续读取引用文档并检查输出
上下文过长	相关规则被截断，后半部分约束丢失	按需安装、拆分技能、缩短项目上下文
模型理解偏差	规则被套用到不合适的场景	补充项目约束、示例和反例，建立回归测试
浏览器不支持	生成了只在部分版本可用的 API	增加能力检测和渐进增强路径
实验能力不可用	模型下载、设备条件或权限阻断执行	保留服务端或静态降级，不让核心流程依赖实验能力
上游规则已经变化	本地版本仍使用旧 API 或旧清单	查看上游 diff，经审阅后升级 commit
本地修改未同步	团队成员生成的代码行为不一致	用 fork、PR 和固定 SHA 管理本地差异

如果第三方依赖比浏览器原生 API 更符合现有项目约束，也不必机械替换。合理的降级方案应说明依赖的安全更新、体积、服务端渲染兼容性和最低浏览器版本。规则用于建立默认选择，不应删除项目本身已经验证过的工程约束。

团队还需要防止一种管理误判：把“已经安装”记录成“已经生效”。真正可审计的状态至少应包含技能是否被发现、引用文档是否被加载、目标浏览器是否通过测试，以及使用的是哪个规则版本。

普通开发者怎样快速读懂它

普通开发者不必先遍历整个仓库，可以按六步阅读：

1. 阅读 README.md，确认项目定位、技能列表和当前安装方式。
2. 从技能目录中选一个与当前项目最相关的入口。
3. 阅读它的 SKILL.md，沿着引用链接找到规则正文和模板。
4. 用同一个明确任务分别生成有指导、无指导两份结果。
5. 在真实浏览器中检查 API、权限、兼容性和安全行为。
6. 将采用的规则版本、生成结果和测试记录一起保存。

Chrome 扩展开发者可以直接从 chrome-extensions 开始，因为它同时覆盖代码、权限和发布材料，能够较快看出技能包如何从一句任务描述延伸到可提交产物。

Zread.ai 一类源码解读工具也可以辅助第一步。它能够为公开 GitHub 仓库生成结构化指南、架构图、核心代码说明和调用关系，帮助开发者先建立项目地图。但它适合做导航，不适合替代对规则原文、README 和具体 commit 的核验；涉及安装命令、浏览器支持和商店字段时，最终仍应回到仓库源码。

Modern Web Guidance 适合作为 AI 前端开发的现代 Web 质量基线，但不能保证每次生成都正确。它的主要作用是改变 AI 面对 Web 能力时的默认答案，而不是提高代码产量；这些答案能否落地，仍取决于规则是否被正确接入、持续更新并经过真实浏览器验证。