Frontman：基于MCP协议的AI前端编辑助手，实现浏览器实时可视化开发

1. 项目概述一个“活”在浏览器里的AI前端编辑助手如果你是一名前端开发者或者团队里有设计师、产品经理需要频繁调整界面那你一定经历过这样的场景设计师指着屏幕说“这个按钮颜色能不能再亮一点”或者产品经理说“这段文案感觉不够有力我们换个说法吧”。然后你作为开发者就需要切回代码编辑器在一堆文件里找到对应的组件、样式文件修改、保存、刷新浏览器再问一句“现在这样行吗”。这个来回沟通、定位、修改、确认的循环往往比修改本身耗费更多时间。Frontman 就是为了终结这个循环而生的。它不是一个独立的AI代码生成工具也不是一个在线的设计稿转代码平台。它是一个开源的AI智能体直接“寄生”在你的本地开发环境里。更准确地说它“活”在你的浏览器和开发服务器之间。你不需要离开正在运行的应用程序直接在浏览器里点击任何一个元素用自然语言描述你想要的变化比如“把这个标题改成蓝色加粗”Frontman就能理解你的意图找到对应的源代码文件可能是React组件、Vue模板、Svelte组件或者CSS文件直接修改并触发热重载修改瞬间生效。整个过程你甚至不需要知道代码文件在哪里。它的核心价值在于上下文感知。传统的AI编码工具无论是Cursor还是GitHub Copilot它们的工作上下文是你的源代码文件。它们“看”不到代码运行起来是什么样子不知道一个div在浏览器里实际渲染出的尺寸、颜色、位置也不知道这个div是由哪个具体的组件、经过哪些状态逻辑计算后生成的。Frontman则反其道而行之它从浏览器里“看到”的实时DOM树、计算后的CSS样式、组件层级关系出发反向定位到源代码。这意味着它的修改建议极其精准因为它知道“你看到的是什么以及它从哪里来”。2. 核心设计思路从“运行时”逆向“构建时”的编辑范式大多数开发工具的思路是“代码 - 构建 - 运行”。Frontman的创新在于它建立了一条从“运行 - 代码”的逆向通道。这个设计思路决定了它与其他工具的根本不同也带来了独特的优势和适用场景。2.1 为什么选择“浏览器优先”的架构传统的AI辅助编码发生在IDE里上下文是静态的文本。但前端开发本质上是视觉化的、动态的。一个margin: auto;在Flex布局和Grid布局下的效果天差地别一个组件的样式可能被父级组件的CSS模块、全局样式表、甚至运行时JavaScript多重影响。仅仅分析源代码AI很难准确预测最终的渲染结果。Frontman选择将AI智能体部署在浏览器端让它能直接访问完整的DOM树不仅仅是HTML结构还包括动态插入的节点、第三方库生成的元素。计算后的样式Computed Style这是最关键的一点。它能获取元素最终生效的所有CSS属性值包括继承来的、覆盖掉的精确到像素和颜色值。组件树映射通过与框架中间件Next.js/Astro/Vite插件通信它能将DOM节点映射回框架的组件实例知道这个按钮是Button variant”primary”而不是一个普通的button。服务器上下文对于Next.js等服务端渲染框架它还能获取到服务器端的路由信息、API响应、构建日志等。这样当你要求“把这个从API加载的数据列表排个序”时它能知道数据源和逻辑在哪里。这种“所见即所得”的编辑上下文使得非技术角色设计师、PM的意图能够被无损地翻译成准确的代码修改。他们描述的是视觉结果“间距再大点”而Frontman能理解并执行成具体的代码操作找到对应的组件将margin-bottom从1rem改为1.5rem。2.2 基于MCP协议的模块化通信Frontman的架构之美在于它采用了Model Context Protocol。你可以把MCP理解为一套标准化的“工具调用”协议。在这个架构中浏览器和开发服务器各自运行着一个MCP服务器分别暴露不同的“工具”Tools。浏览器MCP服务器提供的工具包括get_element_info获取元素DOM路径和样式、take_screenshot、get_console_logs等。开发服务器中间件提供的工具包括resolve_component将DOM节点解析为组件和道具、read_source_file、write_source_file、get_route_info等。Frontman的核心AI协调服务器用Elixir/Phoenix编写则作为一个MCP客户端根据用户的自然语言指令智能地组合调用这些分散的工具完成“理解意图 - 探查上下文 - 制定修改计划 - 执行写操作 - 触发热重载”的全流程。这种基于协议的解耦设计非常清晰也便于扩展。未来如果需要支持新的框架比如Solid.js或Qwik只需要为该框架实现一套暴露相同MCP工具的中间件即可核心的AI逻辑无需改动。3. 实战部署与核心配置详解理论很美好我们来点实际的。下面我将以最流行的Next.js项目为例手把手带你走一遍安装、配置、使用的全过程并分享一些官方文档里没写的细节和坑。3.1 环境准备与安装首先确保你有一个正在开发中的Next.js项目App Router或Pages Router均可并且Node.js版本在18以上。安装步骤# 在你的Next.js项目根目录下执行 npx frontman-ai/nextjs install这个命令会做以下几件事安装frontman-ai/nextjs和modelcontextprotocol/sdk等必要的NPM包。在你的next.config.js或next.config.mjs中添加Frontman的插件配置。在项目根目录创建一个frontman.config.js配置文件。可能会在package.json中添加一个开发用的脚本。安装后的关键文件解读next.config.js的改动通常如下// next.config.js const withFrontman require(frontman-ai/nextjs/plugin); /** type {import(next).NextConfig} */ const nextConfig { // ... 你原有的配置 }; // 关键是这一行用withFrontman包裹你的配置 module.exports withFrontman(nextConfig);这个插件会在Next.js开发服务器中注入Frontman的中间件用于提供服务器端的MCP工具。frontman.config.js是核心配置文件初始内容比较简单// frontman.config.js /** type {import(frontman-ai/nextjs).FrontmanConfig} */ const config { // 在这里配置你的AI模型API密钥 ai: { provider: openai, // 或 anthropic, openrouter apiKey: process.env.OPENAI_API_KEY, // 强烈建议使用环境变量 }, }; module.exports config;重要提示踩坑记录安装过程有时会因为网络或权限问题未能成功修改next.config.js。安装后务必亲自打开next.config.js文件检查确认withFrontman插件已被正确添加。我曾遇到过插件导入语句缺失导致开发服务器启动后无法访问/frontman路径的情况。3.2 配置AI模型与API密钥Frontman采用BYOK模式你需要自己准备AI服务的API密钥。这既是优点无额外费用直接按用量付费给供应商也需要一点设置。1. 选择模型供应商OpenAI (ChatGPT)通用性强速度通常较快对代码理解好。推荐使用gpt-4-turbo-preview或更新的版本。Anthropic (Claude)Claude 3系列如Claude 3 Opus/Sonnet在复杂指令遵循和长上下文理解上表现优异特别适合需要多步骤推理的修改任务。OpenRouter这是一个聚合平台可以接入数十种模型包括Claude、GPT、Llama、Mistral等。优势是统一接口和计费方便对比不同模型的效果。对于个人开发者OpenRouter的费率有时更有竞争力。2. 安全地配置密钥绝对不要将API密钥明文写在frontman.config.js里并提交到代码仓库这是最高优先级的安全纪律。正确做法是使用环境变量# 在项目根目录创建 .env.local 文件Next.js会自动加载 echo OPENAI_API_KEYsk-your-actual-api-key-here .env.local # 或者 echo ANTHROPIC_API_KEYsk-ant-your-actual-api-key-here .env.local然后修改frontman.config.jsconst config { ai: { provider: openai, // 根据你使用的改 apiKey: process.env.OPENAI_API_KEY, // 可选指定模型 model: gpt-4-turbo, }, };3. 模型选择与成本权衡实操心得日常微调改颜色、文案、间距使用gpt-4-turbo或claude-3-sonnet就完全足够成本可控响应速度快。复杂重构调整组件结构、逻辑修改如果涉及复杂的逻辑判断或数据结构变更建议在配置中临时切换到能力更强的模型如claude-3-opus或gpt-4。你可以在frontman.config.js里快速修改model字段并重启开发服务器。启用流式响应在配置中设置stream: true可以让Frontman在思考时逐步显示修改建议体验更好虽然对最终结果没影响。3.3 启动与访问配置好后像往常一样启动你的开发服务器npm run dev # 或 yarn dev, pnpm dev如果一切正常控制台除了Next.js的启动信息外应该能看到Frontman相关的日志例如Frontman MCP server running on port...。接下来不要直接打开你的应用首页。Frontman提供了一个独立的操作界面。打开浏览器访问http://localhost:3000/frontman请注意这个/frontman路径是固定的由中间件注入。你会看到一个分屏界面左侧是你的应用实际运行页面右侧是Frontman的聊天和控制面板。注意第一次访问时由于需要建立WebSocket连接并初始化AI Agent可能会有几秒钟的加载时间。如果长时间卡住请检查浏览器控制台有无WebSocket连接错误并确认你的开发服务器运行正常。4. 核心工作流程与高级编辑技巧现在你已经进入了Frontman的操作界面。我们来演练一个完整的编辑流程并深入一些高级用法。4.1 基础编辑点哪改哪假设你的页面上有一个标题你觉得它的颜色不够醒目。点击“选择元素”模式在Frontman面板上通常会有一个鼠标指针的图标点击它。此时你的鼠标在左侧应用页面上移动时元素会被高亮。点击目标元素点击那个你想修改的标题。Frontman面板会立即更新显示该元素的详细信息包括它的HTML标签、CSS类名、计算后的样式颜色、字体、大小等以及它对应的React/Vue组件名称如果能解析到。用自然语言描述修改在聊天输入框里用英语或中文描述你的需求。例如“把这个标题的颜色改成品牌主蓝色 (#0070f3)并把字体加粗。”审核与执行Frontman的AI会分析你的指令、元素上下文和源代码然后生成一个修改计划。它会在面板上清晰地告诉你将要修改的文件例如/app/components/Header.tsx具体的代码变更Diff它会展示旧代码和新代码的对比高亮显示被修改的行。修改理由解释为什么这样改。确认应用你检查Diff如果觉得没问题点击“应用”或“确认”。Frontman会直接写入源文件Next.js的热重载机制会立即触发左侧页面上的标题瞬间就变成了蓝色和加粗。整个过程中你从未打开过Header.tsx这个文件。4.2 高级技巧复杂指令与多元素协同编辑Frontman的能力远不止改颜色。你可以发出更复杂的指令布局调整“让这个卡片容器内部的所有元素垂直居中并且间距统一为16像素。”内容重组“把用户资料栏和设置菜单这两个模块的位置对调一下。”样式重构“让这个按钮在鼠标悬停时背景色轻微变深并有一个向上的微动效。”逻辑微调“如果购物车是空的就在这个区域显示‘快去选购吧’的提示和一张商品推荐图而不是空白的列表。”这里有一个非常重要的实操心得指令的清晰度直接决定修改质量。模糊的指令会导致AI猜测可能产生意想不到的修改。例如你说“让这个页面更现代化”AI可能会同时修改字体、颜色、间距、阴影等数十处结果可能很混乱。更好的做法是分解任务先“将主字体从Arial改为Inter”再“将主色调从#333调整为#111”最后“将段落的行高从1.4增加到1.6”。提供参考如果公司有设计系统可以直接引用。“将这个按钮的样式改为和我们设计系统中‘Primary Button’组件一致。”结合截图虽然当前版本可能不支持直接上传图片但你可以在指令中描述参考对象。“让这个表单的布局和间距看起来像我们产品首页的登录框那样。”4.3 与OpenClaw集成自动化工作流的延伸Frontman本身专注于“视觉化编辑”。但前端工作流中还有很多其他重复性任务比如运行测试、执行构建、提交代码、生成组件等。这就是OpenClaw的用武之地。OpenClaw是另一个开源的AI智能体框架擅长处理通用的自动化任务操作Shell、读写文件、调用API等。你可以将Frontman作为OpenClaw的一个“技能”来安装openclaw skill install frontman-dev安装后你就可以对OpenClaw发出这样的复合指令 “OpenClaw请先运行单元测试如果全部通过就用Frontman技能把首页的欢迎文案更新为最新的营销话术然后帮我提交代码提交信息写‘feat: update homepage hero copy’。”这个组合打开了自动化的大门。Frontman负责需要“视觉上下文”的精细编辑OpenClaw负责流程性的任务编排两者通过MCP协议协同工作。5. 深入原理MCP、热重载与安全边界要真正用好Frontman理解其底层原理和设计边界至关重要这能帮你避免困惑和误用。5.1 MCP协议如何实现精准映射当你在浏览器点击一个元素时Frontman的浏览器端MCP服务器会捕获这个元素的唯一选择器如CSS Selector或XPath和它在DOM树中的位置。同时Next.js开发服务器端的MCP服务器维护着一份“源代码 - 编译后模块”的映射表以及框架的组件树信息。AI协调服务器收到编辑指令后会进行以下关键查询调用浏览器工具的get_element_info获取元素的完整样式和DOM路径。调用服务器工具的resolve_component_from_dom传入DOM路径。这个工具会利用框架的调试符号和Source Map反向查找出是哪个组件文件包括行号、列号生成了这个DOM节点以及当前传递给该组件的具体属性props是什么。调用read_source_file读取该组件的源代码。AI结合源代码、组件属性、计算样式和你的指令生成一个编辑计划Edit Plan。这个计划会精确到在哪个文件的哪一行将什么代码替换成什么。调用write_source_file执行写操作。调用trigger_hot_reload通知开发服务器。由于文件被修改Next.js/Vite的文件监听机制会自动触发模块热更新浏览器即时刷新。5.2 热重载的魔法与限制Frontman依赖框架本身的热重载能力。这对于Next.js (Fast Refresh)、Vite、Astro来说都是原生支持的。这意味着样式修改几乎无感更新状态不会丢失。组件逻辑修改对于React组件如果修改了渲染逻辑但未改变组件签名如useState的顺序Fast Refresh会保留组件状态。如果修改了Hooks的顺序或组件签名则会触发一个完整的重载。服务器组件修改Next.js App Router修改服务器组件会导致该路由的重新渲染这是框架行为。需要注意的限制Frontman修改的是你的源文件。这意味着如果你有未保存的更改Frontman的写入会覆盖它们。最佳实践是在使用Frontman前先提交或暂存你的更改。它无法修改node_modules里的第三方库代码。如果你点击的元素来自一个库Frontman可能无法解析到可编辑的源文件或者只能建议你通过覆盖样式的方式修改。5.3 安全性与生产环境这是所有开发者最关心的问题Frontman安全吗会不会被打包到生产环境答案是非常安全且完全不影响生产包。开发环境限定Frontman的所有代码浏览器脚本、服务器中间件都通过条件判断只在NODE_ENVdevelopment模式下被引入和运行。当你运行npm run build进行生产构建时Next.js/Vite的构建器会进行Tree Shaking所有Frontman相关的代码都会被完全剥离。无运行时依赖Frontman不向你的应用代码注入任何运行时依赖。它只是一个开发时的“脚手架”和“通信层”。你的生产打包产物与是否安装Frontman完全一致。代码修改权限Frontman需要读写你的源代码文件。这听起来有风险但它运行在你的本地开发环境与你的代码编辑器VS Code拥有相同的文件系统权限。你信任VS Code的扩展可以修改文件同理也适用于Frontman。它不会将你的代码发送到远程服务器除非你使用的AI模型API是远程的但那是代码内容的问题不是Frontman工具本身的问题。API密钥安全如前所述你的AI API密钥只存在于本地环境变量或配置文件中Frontman服务器仅将其用于向AI服务商发起请求不会收集或存储。6. 常见问题排查与性能优化在实际使用中你可能会遇到一些问题。下面是我总结的常见故障排查清单和优化建议。6.1 连接与加载问题问题现象可能原因解决方案访问localhost:3000/frontman显示404或空白页1. Frontman插件未正确安装或启用。2. 开发服务器未运行在默认端口。1. 检查next.config.js是否被withFrontman包裹。2. 检查终端确认开发服务器已启动且Frontman日志出现。3. 如果使用了自定义端口如3001访问localhost:3001/frontman。Frontman面板一直显示“连接中”或“初始化”1. 浏览器与Frontman服务器的WebSocket连接失败。2. AI模型API密钥无效或网络问题。1. 打开浏览器开发者工具F12的“网络”选项卡查看WebSocket (ws) 连接是否报错。2. 检查终端是否有Frontman服务器报错。3. 确认frontman.config.js中的API密钥正确且对应服务可访问如OpenAI是否被墙需要网络代理。点击元素无反应面板不更新1. 浏览器扩展如广告拦截器可能拦截了Frontman的脚本。2. 页面是静态HTML或框架未正确挂载。1. 尝试在无痕模式下使用或禁用广告拦截器。2. 确保页面是由框架动态渲染的CSR或SSR纯静态HTML站点可能无法解析组件树。6.2 编辑功能异常问题现象可能原因解决方案AI无法理解指令或生成无关修改1. 指令过于模糊。2. 使用的AI模型能力不足。3. 上下文可能不完整如点击了Shadow DOM内的元素。1.拆解指令一次只要求一个明确修改。2. 在配置中切换到更强的模型如GPT-4/Claude 3 Opus。3. 尝试点击更外层的、由你的代码直接控制的元素。修改被应用但页面无变化或报错1. 热重载失败。2. AI生成的代码有语法错误。3. 修改了关键逻辑导致运行时错误。1. 手动刷新浏览器页面。2. 查看浏览器控制台和终端是否有错误信息。3. Frontman通常会展示Diff应用前务必仔细检查生成的代码。养成先看Diff再确认的习惯。无法解析到组件只能看到HTML标签1. 项目构建未生成完整的Source Map或调试信息。2. 点击的元素来自iframe或第三方小部件。1. 确认开发服务器是以development模式运行。2. 对于某些复杂的构建配置如自定义Webpack可能需要调整以生成更详细的Source Map。3. 这类元素通常无法直接编辑需找到其父级可控组件进行修改。6.3 性能与成本优化控制Token消耗复杂的指令和大的代码库上下文会消耗更多AI Token增加成本。对于简单的样式修改使用速度更快、更便宜的模型如GPT-3.5-Turbo如果支持可能更经济。你可以在frontman.config.js中根据任务类型动态调整model配置虽然需要重启但可以准备不同环境的配置。优化响应速度AI模型的思考时间占了大头。保持指令简洁明确能减少AI的“纠结”时间。此外确保你的开发服务器运行在性能足够的机器上避免文件读写成为瓶颈。团队协作配置如果团队多人使用每人配置自己的API密钥即可。Frontman本身无状态不涉及协同编辑。代码修改最终会通过Git进行版本管理和协作评审这符合标准的开发流程。7. 适用场景与团队协作模式Frontman并非要取代开发者而是改变“需求 - 代码”的传递路径。理解其最佳适用场景能让它发挥最大价值。7.1 谁最适合使用Frontman独立开发者或小团队一人身兼数职需要快速在“开发者”和“设计者”角色间切换。用Frontman调整UI无需上下文切换效率提升立竿见影。设计-开发紧密协作的团队设计师可以直接在运行的原型上标注和描述修改甚至可以在开发人员的监督下自行操作Frontman进行微调。这极大地减少了沟通失真和往返时间。产品经理与内容运营对于文案修改、图片替换、简单的布局调整如调整模块顺序产品经理可以自行完成无需打扰开发。修改通过Git提交后开发人员依然可以进行代码审查确保质量。前端开发人员自身即使是资深开发者在调试复杂的CSS效果或追踪组件渲染关系时Frontman提供的“可视化-代码”双向映射也是一个强大的调试工具。7.2 集成到现有工作流引入Frontman不需要颠覆现有流程开发阶段像安装一个开发依赖一样引入用于快速原型迭代和UI调整。代码审查所有通过Frontman生成的修改都会以标准的Git Diff形式呈现可以像审查其他代码一样在GitHub、GitLab等平台进行审查。持续集成由于生产构建会自动剔除Frontman因此对CI/CD流水线零影响。一个建议的协作模式是为设计师和产品经理创建一个具有有限权限的“预览环境”分支。他们可以在该分支上使用Frontman进行大胆的视觉尝试然后将满意的修改合并到主开发分支。这样既给予了非技术成员创作空间又保证了主分支代码的稳定性。我个人在几个项目中引入Frontman后最深的体会是它把“视觉反馈环”缩短到了近乎实时。以前需要“改代码 - 等构建 - 刷新看效果”的循环现在变成了“描述 - 立即看到效果”。这种即时性对于培养对细节的敏感度和进行设计探索有不可估量的价值。它更像是一个超级强大的、可对话的浏览器开发者工具而不是一个代码生成器。它的目标不是写出你写不出的复杂逻辑而是帮你省去那些在视觉和代码之间反复横跳的、繁琐的机械操作时间。