1. 项目概述与核心思路1.1 我为什么要做这个项目先聊聊背景。做H5开发的朋友应该都有过这种体验页面在PC端好好的一上真机就各种诡异问题白屏、请求失败、数据不对。传统做法是让用户帮忙打开调试工具或者用vConsole这种前端调试面板在页面上手动操作然后截图、录屏再把这些信息整理成文字反馈给AI工具帮忙分析。这一套流程下来沟通成本极高信息损耗也相当严重。我自己试过让AI看录屏分析问题效果很差。AI能识别个大概但具体到日志内容、请求参数、响应状态码这些细节光靠画面根本看不清楚。而且录屏文件大、上传慢效率极低。我当时就在想能不能有一种方式让AI像打开浏览器开发者工具一样直接读取H5页面上的console日志、网络请求、localStorage数据这个项目要解决的就是这个问题。我把vConsole这个移动端调试面板接入MCPModel Context Protocol模型上下文协议让AI不再通过人的转述来了解页面状态而是直接通过MCP协议读取H5的运行时数据。换句话说AI变成了一个拿着调试工具的助手消息可以像走WebSocket通道一样实时把页面上的日志和请求流转到AI那边。1.2 这个方案适合什么样的场景我用下来最直接的感觉是这套东西适合三类人群。第一类是日常做H5、小程序内嵌页、Hybrid App开发的同学尤其是经常要远程协助排查问题的场景。第二类是正在做AI Agent、AI自动化测试相关工作的工程师需要一个可靠的数据通道来获取前端运行时信息。第三类是想提升AI辅助开发效率的团队与其让AI猜不如把真实数据主动喂给AI。从我的实践来看vConsole MCP最核心的价值在于它把描述问题变成了共享数据。人只需要把问题告诉AIAI自己去看日志、查请求整个调试过程从人工摘录信息变成了AI自主侦察这完全是两种体验。2. vConsole基础与MCP协议解析2.1 vConsole的工作机制与能力边界vConsole是一个移动端H5的前端调试面板很多同学应该不陌生。它在页面里注入一个悬浮按钮点击后可以展开一个类似浏览器DevTools的界面能够查看console日志、网络请求、存储数据、元素结构等信息。在正式讲MCP接入之前我得先说清楚vConsole的机制。vConsole本质上是一组JavaScript模块通过new VConsole()实例化后挂载到页面上。它的数据捕获能力依赖的是对console.*方法的拦截、对XMLHttpRequest和fetch的包装、以及对localStorage和sessionStorage的读取封装。单纯的vConsole只能把日志显示在页面上数据是闷在浏览器里的。要把它和工作流结合起来让外部工具能主动拉取数据还需要一个通道。我的做法是给vConsole加一个自定义插件它会把内部收集到的日志、请求数据实时推送到后台再通过WebSocket转发给MCP server最终让AI模型能以工具调用的方式读取到这些数据。2.2 MCP协议的设计思路MCPModel Context Protocol解决的痛点是AI模型无法直接感知外部世界它需要的是一种标准化的接口让外部工具以可被调用的函数形式暴露给模型。打个不恰当的比方MCP像是给AI装上了一套乐高接口任何符合规范的模块都能插上去用。vConsole MCP的架构可以分为三层。最底层是H5页面上运行的vConsole插件负责采集数据中间层是WebSocket服务端负责把浏览器端数据转成MCP可识别的结构化格式最上层是MCP server本身它定义了一组工具tools比如get_console_logs、get_network_requests、get_storage_dataAI可以通过调用这些工具获取所需信息。我之所以选择MCP而不是自己写一套API核心原因是标准化。MCP现在发展很快主流AI编程工具、IDE插件、自动化框架都在往这个协议上靠。项目接了MCP之后可扩展性会好很多以后想接入其他支持MCP的AI工具基本不需要改动底层逻辑。2.3 工具的选型与方案取舍说实话第一版实现我纠结过要不要直接使用playwright-mcp这类浏览器自动化方案让AI控制一个真实的浏览器实例。后来我否掉了这个方案原因很简单playwright-mcp需要完整的浏览器环境而我面对的是真实用户的手机H5页面场景完全不同。后来我也研究过直接用vConsole官方提供的API把日志手动导出再粘贴给AI。这个思路存在的问题是操作链路太长而且只能做单次快照没法实现请求和日志的实时联动分析。最终定下来的方案是以vConsole为数据源以自定义插件作为数据搬运工以WebSocket连接为传输通道以MCP tool作为AI的眼睛。这个方案的最大好处是保留了vConsole的完整调试能力同时又建立了AI可直接消费的数据通道。3. 核心细节解析与实操要点3.1 整体流程与事件方向整个数据流的方向是这样的用户打开H5页面vConsole开始捕获日志和网络请求插件层监听捕获事件对数据进行格式化通过WebSocket推送到本地服务端服务端维护一个环形缓冲区MCP server根据AI发来的查询指令从缓冲区拉取对应数据进行返回。这里有个值得细说的设计点数据方向是单向的。从页面流向AI而不是反向的。我一开始想过做双向控制比如让AI直接操作页面上的按钮后来考虑到安全性和复杂度决定先把让AI看见这件事做扎实。项目里我最满意的处理是日志级别的过滤。vConsole捕获的日志有debug、log、info、warn、error五种级别如果全量推送数据量很大且噪音多。我参考了vConsole的过滤逻辑把Viewer的数据结构改造了一下新增了一个mcpStreaming模式在该模式下只推流warn和error级别日志普通日志只有在AI显式请求时才返回。3.2 插件开发中需要注意的坑vConsole插件开发有几个坑我在实际编码过程中踩到过值得单独拿出来说。第一个坑是vConsole的插件生命周期。vConsole插件有init、render、addTool、remove等事件钩子其中init阶段在vConsole构造函数执行时就触发了此时DOM可能还没完全准备好。如果你的插件需要在页面元素渲染后才执行某些操作应该挂在render事件里否则会出现DOM为空的诡异情况。第二个坑是网络请求的重放。vConsole本身在network面板能看到请求但它的数据是经过处理的不是原始请求对象。我的插件在捕获请求时发现直接把XMLHttpRequest实例塞进插件事件里会导致在序列化时拿不到requestHeaders和responseHeaders。解决方案是在请求完成的回调里手动把这些数据抽出来存储。第三个坑是WebSocket连接的生命周期。H5页面在移动端的生命周期非常不可控页面切后台、网络切换、应用被杀都会导致WebSocket断开。我在插件里做了断线重连机制同时加了心跳检测每15秒发一次ping如果连续三次没有收到pong消息就主动断开重连。3.3 自动捕获与实时推送配置配置自动捕获时有几个关键参数需要注意采样率、推送频率、数据大小上限。我建议采样率设为100%也就是所有日志和请求都采集因为调试场景下少一条关键信息可能就导致AI判断失误。推送频率不用太高WebSocket本身是长连接数据可以即时推送但要注意控制单条数据的大小。vConsole捕获到的一个请求响应体有可能达到几百KB如果全量推给AItoken消耗会非常夸张。我的做法是做了三层限制。第一层是请求体截断超过2KB的请求体只保留前2KB第二层是响应体采样超过10KB的响应体只保留前10KB并且标注内容已截断第三层是全局数据量限制每5秒内推送的数据总量最多500KB超出的部分进入本地缓冲区等待后续查询。// 插件核心初始化逻辑简化版 import VConsole from vconsole; class MCPPlugin { public pluginId mcp-stream-plugin; public disabled false; private socket: WebSocket | null null; private buffer: ArrayLogEntry | NetworkEntry []; private readonly MAX_BUFFER_SIZE 500 * 1024; private readonly HEARTBEAT_INTERVAL 15000; constructor(private config: MCPPluginConfig) { this.onServerEvent this.onServerEvent.bind(this); } public init(vConsole: VConsole) { // 注册vConsole事件捕获新的日志内容 vConsole.on(logAdd, (logType: string, logs: any[]) { if (this.disabled) return; if (logType error || logType warn) { this.pushToBuffer({ type: console, level: logType, content: logs.map(item this.safeStringify(item)), timestamp: Date.now() }); } }); // 网络请求监听 vConsole.on(networkAdd, (data: any) { if (this.disabled) return; this.pushToBuffer({ type: network, url: data.url, method: data.method, status: data.status, request: this.truncate(data.request, 2 * 1024), response: this.truncate(data.response, 10 * 1024), timestamp: Date.now() }); }); this.connectSocket(); } private pushToBuffer(entry: LogEntry | NetworkEntry) { this.buffer.push(entry); while (this.getBufferSize() this.MAX_BUFFER_SIZE) { this.buffer.shift(); // 丢弃最老的数据留出空间 } this.flushBuffer(); } }上面这段代码是插件核心逻辑的展示。可以看到vConsole.on(logAdd)和vConsole.on(networkAdd)是获取数据的关键钩子pushToBuffer负责数据入队和溢出清理flushBuffer则是把数据批量推送到WebSocket。4. 实操过程与核心环节实现4.1 搭建WebSocket服务与MCP serverWebSocket服务我在Node.js环境里实现使用ws库比较简单可靠。服务端接收来自浏览器的连接每个连接分配一个会话IDMCP server通过这些会话ID来定位数据源。一个同时接入多个H5页面的场景需要处理用户打开PC端的AI工具手机上打开了多个H5页面每个页面的vConsole插件都会建立一条WebSocket连接MCP server需要知道该从哪条连接取数据。我在服务端维护了一个MapsessionId, WebSocketConnection同时提供一个select_session工具AI可以显式切换要观察的会话。MCP server我参考了官方TypeScript SDK来实现定义工具时有个细节需要注意工具描述要写清楚返回数据的格式和含义。AI本身并不了解vConsole的数据结构如果描述写得模糊它在调用工具时会犹豫或拿不到预期结果。// MCP 工具注册示例简化版 server.tool( get_console_logs, 获取当前H5页面的console日志列表返回数组包含level、content、timestamp字段。level取值有debug/log/info/warn/error。该工具适用于白屏、报错、数据异常等场景。, { since: 可选ISO时间字符串只返回该时间之后的日志 }, async ({ since }) { const sessionId getCurrentSessionId(); const logs await dataCenter.getLogsSince(sessionId, since); return { content: [{ type: text, text: JSON.stringify(logs) }] }; } );4.2 H5端的实际接入流程H5端接入流程其实很简单我写了个npm包安装后引入并初始化就行。核心流程分四步第一步安装依赖。npm install vconsole-mcp-plugin然后在你的入口文件里引入。第二步初始化。new MCPPlugin({ serverUrl: ws://your-host:8080 })这里要保证WebSocket连接是可访问的。第三步开启vConsole。通过new VConsole({ plugins: [mcpPlugin] })挂载。第四步设置环境标识比如__MCP_ENV__ dev确保生产环境不会误开启。我遇到过的真实问题是很多开发同学把这个插件直接加到了线上环境导致用户的手机一直往开发服务器推日志。这个一定要加环境判断只在development或qa环境下启用。4.3 让AI有针对地查询数据MCP server打通之后关键就在于能让AI以一种比较自然的方式用这些工具。比如说我让AI排查一个点击按钮无反应的问题。AI会先调用get_console_logs看有没有报错再调用get_network_requests看点击按钮时有没有发出请求。如果请求发出了但响应500AI会进一步查询特定请求的响应详情。整个过程AI自己是能组织好的你只需要告诉它看一下当前H5页面点击按钮后为什么没反应它就知道该用什么工具查什么数据。我自己实测下来给AI的prompt要尽量描述清楚现象比如用户反馈在Android微信里打开页面白屏请查看当前会话的console错误和最近请求。描述清楚现象之后AI会自动决定查询策略。尽量不要让AI自由发挥因为它的工具选择有时比较发散。明确指令能省不少token。4.4 关键配置一览我整理了一份配置表方便大家直接参考配置项推荐值说明插件挂载模式仅开发/QA环境绝对别在生产环境开WebSocket地址域名或局域网IP跨域需要服务端允许日志推送级别warn error高频日志会爆炸请求体截断2KB防止token爆炸响应体截断10KB超长响应只留头部缓冲区上限500KB超出丢弃最老数据心跳间隔15秒检测连接存活4.5 多连接会话隔离的实现在项目里是怎么做的说到会话隔离这里有个容易出错的地方值得展开。我在开发调试时遇到过会话串线的诡异问题同时开着手机端和浏览器模拟器AI查到的是模拟器的数据但IP地址却是手机的。排查了半天发现是WebSocket连接没有绑定页面。这个问题的根因在于一个页面可以直接打开多个WebSocket服务端无法判断哪条连接是当前活跃的。因此我在插件初始化时生成了一个UUID把它作为参数拼在WebSocket连接URL上例如ws://host:8080?sessionIdxxxx。服务端拿到这个参数后建立会话后续的数据都挂在UUID下。请求AI操作时我会在描述里指定sessionIdAI查询时就会带上这个标识数据就不会串了。5. 常见问题与排查技巧实录5.1 WebSocket连不上怎么办这是大家反馈最多的问题十有八九是跨域或网络权限导致的。如果WebSocket服务端和H5页面不在同一个域需要在服务端配置CORS允许跨域。ws库原生不支持CORS要通过verifyClient手动处理Origin头。另外移动端真机调试时H5页面可能是用IP地址访问的如果你使用的是localhost作为WebSocket地址手机永远连不上。建议先确认手机能ping通你电脑的局域网IP然后WebSocket地址写ws://192.168.x.x:8080。5.2 AI拿到的日志不完整或者乱码怎么办日志不完整大概率是数据截断策略导致的。如果你自己调试时发现某条关键日志被截断了可以把截断阈值调大或者把截断策略改为白名单模式只截断超过特定大小的内容保留所有小体积日志。乱码问题通常是编码不对。H5页面如果是GBK编码而你的插件用UTF-8推送数据就会出现乱码。处理方案是在插件初始化时检测document.characterSet根据实际编码做一次decodeURIComponent或TextDecoder转换。5.3 AI完全没反应或报工具不存在先用MCP调试客户端测试看看MCP server的初始化是否正常。很多时候AI工具没反应问题不在MCP server这边而是AI客户端没有正确加载到工具列表。我遇到过IDE缓存导致MCP配置未生效的情况重启IDE之后就好了。也可以在MCP server端打印日志看AI调用工具时的请求有没有到达服务端。这一步能快速定位问题是在传输层还是模型层。5.4 真机调试时的性能影响有多大一个大家关心的实际问题这套方案会不会影响H5性能我在低端Android机上实测过。vConsole本身会有少量性能损耗因为它在捕获日志和请求时会做拦截处理。加了MCP插件后每次日志推送会多一次WebSocket发送这个开销很小。真正影响的瓶颈在于如果你开启了全部日志级别的推送console信息量大的页面会有明显卡顿。实测结论在dev环境下建议只开warn和error推送这个组合在红米Note这类中端机上几乎无感。localStorage的读取操作不用频繁推送让AI按需查询就好。5.5 排查问题的问题排查速查表现象可能原因处理动作WebSocket连不上跨域限制 / 内网IP不通配置CORS验证改用局域网IP日志缺失截断策略过严 / 推送级别过滤调大阈值修改过滤级别请求数据只有头部响应体截断调大截断上限会话串线缺少sessionId区分连接带上UUID参数AI报错工具不存在MCP配置文件未加载重启客户端检查配置路径页面性能下降全量日志推送只保留warn和error推送数据乱码页面编码与推送编码不一致根据characterSet做转码6. 项目进一步扩展的可能性6.1 从调试到自动化测试的演进vConsole MCP做出来后我发现它的能力不止于调试还能延伸到自动化测试领域。通过MCP测试框架可以读取到页面在特定操作后的状态变化比如表单提交后有没有报错、某个按钮点击后有没有产生预期的请求。这比传统的断言DOM元素要强大得多因为你能穿透到运行时数据层。我计划下一步加一个track_operation工具AI可以通过它模拟用户操作然后再查日志和请求形成一个操作-观察-分析的闭环这样自动化测试就能覆盖更多场景。6.2 与其他MCP server的组合玩法这个项目更大的潜力在于它可以和其他MCP server协同工作。比如结合浏览器自动化的MCP serverAI可以自动操作页面的同时读取H5运行日志形成一个更完整的触觉加视觉的能力。虽然我的方案WebSocket部分通常运行在本地但如果你的手机和开发机不在同一网络就会受限。目前我还在考虑加一个中继服务让移动端的日志数据能跨网络传输这样远程协作场景下不在同一局域网的同事也能共享调试信息。7. 个人实操体会与总结这个项目从构思到落地我完整的走了一遍。最初只是想要一个AI能看日志的工具结果发现要做的事远不止这些。真正让我花最多时间的地方不是vConsole插件开发也不是MCP protocol本身而是数据链路中各层之间的对接。比如vConsole捕获的数据是纯浏览器环境的产物而AI这边期望的是结构化、有时间戳、有上下文关联的数据这两者的差异需要靠中间层做转换。我在这个转换层上反复打磨了很久。根据自己的实践给想做类似方案的朋友一个建议先明确你要解决的核心问题是什么再做架构选型。如果目标只是让AI能读日志最简单的方案就是写一个定时抓取的HTTP接口但如果你想实现AI像DevTools一样随时查数据那MCP这套东西就非做不可。选型永远是目的决定方案。另外如果你想在团队里推广这个方案不要急着让所有人都接入。先在两三个人之间跑通积累几个典型的调试案例把工具描述、系统提示词都调教到位确认体验真的比截图文字描述好很多再推向团队。工具好不好用从来不是功能决定的而是体验决定的。vConsole MCP这个项目我在持续迭代中后续会把WebSocket服务做成一个独立安装的npm包方便大家只用一条命令就启动服务端也会预留接口让更多类型的H5数据源接入进来比如路由变化、全局状态变化等。这些东西如果做成了说不定能让AI调试H5的体验再上一个台阶。