# MCP Inspector Bridge > 专为 **Cocos Creator 2.4.x** 打造的现代化运行时节点审查与 DevTools 桥接插件。 基于 Vue 3 + Electron BrowserView 架构，提供双分栏沉浸式调试体验：左侧游戏预览、右侧节点树/属性检查/DevTools/性能分析，彻底解决原版内嵌 Chromium DevTools 的挂起死锁问题。 --- ## 🚀 快速开始 ### 环境要求 - Cocos Creator **2.4.x** （广泛兼容官方原版以及魔改升级至 Electron 14+ 的特殊高版本环境） - Node.js ≥ 14 ### 安装 将本项目克隆或复制到 Cocos Creator 的插件目录中： ```bash # 全局插件目录 ~/.CocosCreator/packages/mcp-inspector-bridge/ # 或项目级插件目录 your-project/packages/mcp-inspector-bridge/ ``` ### 构建 ```bash # 安装依赖（包含 esbuild） npm install # 编译 TypeScript + 打包探针模块与 MCP 客户端 npm run build ``` ### 使用 1. 在 Cocos Creator 中打开任意场景 2. 菜单栏 → **MCP 桥接器** → **开启运行时面板** 3. 点击 **预览运行** 按钮，插件面板将自动捕获游戏预览并加载节点树 --- ## ✨ 核心特性 ### 🖥️ 双分栏工作流 采用 Vue 3 构建主面板，左侧 Webview 渲染游戏视口，右侧集成多功能调试标签页，实现"边玩边审"的沉浸式体验。 ### ⚡ 运行时探针与节点树 基于预加载脚本 (`preload.ts`) 无侵入注入探针至游戏运行时，实时截获完整节点树结构。 - **多关键词穿透搜索**：支持空格分词的 AND 逻辑匹配，可穿透至组件类名层级搜索（如输入 `Animation` 定位所有挂载该组件的节点） - **严格路径过滤**：搜索结果仅展示命中节点及其直系祖先，自动隐藏无关分支 - **空白区域取消选中**：点击空白即可清除所有焦点，联动属性面板归零与高亮退场 ### 🎯 节点高亮与屏幕拾取 - **包围盒高亮**：鼠标悬停/选中节点时，游戏画面实时渲染精准的贴边多边形轮廓，零宽高节点自动降级为十字准星 - **屏幕拾取器**：直接在游戏画面中点击选取节点，基于多摄像机阵列扫描 + CullingMask 分组继承 + 面积权重透层算法，完美适配多镜头、多分组、Fit 缩放等复杂场景 ### 🤖 AI MCP 集成桥 (Multi-Instance Ready) 为 LLM (大模型如 Claude/Cursor) 提供双端通信与跨进程的游戏引擎交互视界。 - **多实例动态寻址 (Multi-Instance Support)**：内置 `EADDRINUSE` 冲突递增机制，支持同时开启多个编辑器实例，实现不同项目端口的自动隔离（默认 4456）。 - **基于项目身份的握手协议**：心跳回执注入 `projectName` 与 `projectPath`，允许 AI 快速识别目标平行宇宙。 - **多端全平台自动配置**：支持向 22 款主流 AI 客户端（如 Claude Desktop、Cursor 等）进行自动探测与免配桥接。 - **MCP 路由工具扩展**：提供 `get_active_instances` 扫描活跃端口、`set_active_instance` 绑定指定项目端口、以及 `refresh_preview` 主动刷新游戏预览窗口。 - **环境安全异常零漏截获 (Eager Log Capture)**：针对 Webview 预览采用 CDP `Runtime.consoleAPICalled` 零注入被动监听（非侵入式，完美保留 DevTools 源归属）；针对 BrowserView 采用原生 `console-message` 事件。双重防御配合每秒后台激进式探测定时器，在游戏初始化第一帧即接管日志，彻底杜绝早期生命周期错误丢失。CDP 不可用时自动降级至注入方案。 - **超保真渲染验证实况图**：直接为大语言模型一键注入运行时截图，打破次元壁。 - **可视化 MCP 通信降维打击 (Debug Console)**：在偏好设置面板内置专属通信日志流，实时抓取前后端请求细节与返回结构；更具备极致的数据防爆护城河（自动截断长字符串与双峰队首淘汰流控机制），轻松排查大语言建模幻觉与传输丢包。 ### 🔍 属性检查器 **遵循现代化卡片化 UI 设计规范 (Modern Card-based UI)**，选中节点后实时展示结构清晰、分栏合理的组件属性库： - **双向属性同步与编辑**：`number` / `string` / `boolean` 以及现代化多行下潜渲染的 `array`、`Anchor`、`Color`、`Opacity`、`Group` 等全景属性双向实时更新；`string` 属性支持多行文本编辑 (textarea 替代 input，Enter 键插入换行)；并且内置 0.5 秒高频属性轮询挂载鼠标与焦点双重意图拦截保护，在节点产生自动动画、物理位移时实现完美的数据追平，而在用户试图编辑时自动停止刷新以防光标跳跃。 - **纯运行时注入**：所有修改直接操作内存实例，不脏化编辑器 Scene 数据，无"是否保存"弹窗 - **组件启停控制**：统一的的复选开关 `enabled`，一键休眠/唤醒指定组件 - **引用追踪定位 🎯**：节点级引用、资源字典、预制体地址均可无痛一键跳转定位归属并闪烁对焦 - **智能枚举下拉**：基于运行时原型的强反射抓取，自动兼容多达 40 种官方内置枚举（诸如 `Sprite.type`) 以及业务测自定义枚举列表，拒绝盲填查字典的痛苦 - **组件 JSON 免签分发**：点击组件 🖨️ 图标，将规避循环污染后的数据一键打印直出控制台绿幕，并自动顺时写入系统安全剪贴板 - **节点对象直连控制台**：点击节点基础属性区右上角的 🖨️ 图标，将整个实例对象剥离序列化负担，直接交由 DevTools 原生审查，突破隐藏私有字段盲区 ### 📉 内存剖析器 按 Bundle 分域聚合的资源内存排行榜： - **极值水位追踪**：实时记录每个 Bundle 的历史最高/最低内存，趋势箭头（↑↓）即时预警 - **UUID 逆向解码**：自动将混淆的 UUID 还原为 `db://assets/textures/...` 可读路径 - **一键资源定位 🎯**：点击即可在编辑器资源管理器中高亮对应文件 - **宏观内存汇总**：榜单头部实时聚合由底层探针累加的总体内存消耗 ### 🩺 渲染调试器 运行时 DrawCall 合批断流诊断： - **静默拦截**：AOP 劫持渲染管线，零控制台污染 - **频次聚合**：Hash 去重 + 触发次数徽章，60FPS 连环断流也不卡 - **帧快照三栏分析**：渲染命令树 / 单步回绘画布 / 管线参数明细 - **逆向节点定位 📌**：从 DrawCall 直接跳转至游戏节点 ### 📊 实时性能叠加框 在游戏预览区左上角渲染半透明 Vue 性能数据面板，彻底解决引擎内置 `cc.debug.setDisplayStats()` 在高分辨率/移动端预览下完全无法辨认的问题： - **帧率全维度**: 瞬时 FPS、平均帧率 (Avg)、1% Low FPS、0.1% Low FPS，基于 600 帧环形缓冲区逐帧统计百分位 - **渲染指标**: DrawCall、Logic 耗时、Render 耗时 - **资源概况**: 实时内存占用 (Mem)、场景节点总数 (Nodes) - **智能轮询**: 性能数据 200ms、内存 1s、节点计数 2s 三档独立速率，节点 O(n) 遍历开销可控 - **颜色自适应**: 各项指标根据预设阈值独立着色（绿/橙/红），低帧阈值逐级放宽 ### ⏭️ 引擎控制 - 暂停/恢复游戏引擎 - 单帧步进 - **FPS 叠加框开关** (替代引擎内置 FPS，控制插件叠加框显隐) - 全局静音 ### 📐 自定义预览分辨率 在偏好设置面板（⚙️ 设置标签页）中管理全局自定义分辨率预设，出现在预览窗口下拉菜单的「自定义」分组中： - **添加 / 编辑 / 删除**：自定义分辨率名称（选填，未填显示 `自定义分辨率（W×H）`）与宽高 - **全局持久化**：基于 `Editor.Profile` 全局存储，一次配置多项目共享 - **即时同步**：修改后下拉菜单实时刷新，正在使用的分辨率被删除时自动回退为「自动充满」 ### 📸 游戏截图 在游戏预览区右上角提供半透明截图按钮（📷），与 FPS 叠加框风格一致，一键截取当前游戏画面。 - **Chromium 合成器级截图**：基于 `webContents.capturePage()` 精确捕获游戏渲染输出，不受 WebGL `preserveDrawingBuffer` 限制，无黑屏问题。 - **并行双通道输出**：点击即自动复制到系统剪贴板，同时弹出保存对话框（PNG 格式，默认时间戳文件名），互不阻塞。 - **设计分辨率感知**：运行时探针自动采集 `cc.view.getDesignResolutionSize()`，预留精确缩放能力。 ### 🎥 游戏录屏 在截图按钮下方提供半透明录屏按钮（📹），支持一键录像并弹出系统保存文件对话框，并在“⚙️ 设置”面板提供专属配置。 - **动态帧率及分辨率缩放**：可在设置中调节录制帧率（15、24、30、60 FPS）和分辨率缩放（0.5x、1.0x、1.5x、2.0x）。支持离屏双缓冲 Canvas 后台渲染以规避 WebGL OOM 并输出高清视频。 - **播放器进度条与寻道自动修复 (EBML Duration Fix)**：自主重写 WebM EBML 二进制头部时长的注入，100% 解决 MediaRecorder 录屏视频在常规播放器里“无法拖拽、进度条不匹配”的问题。 - **游戏音轨旁路混音**：全局代理 `AudioNode.prototype.connect`。当发声源连接到扬声器时，自动静默双路连接至录制目标，实现音视频轨道在流级的纳秒级完美对齐。 - **MP4 转码与安全自愈降级**：支持保存为 `.webm` 或 `.mp4` 格式。保存 MP4 时优先检测插件根目录下 `<插件根目录>/bin/win32/ffmpeg.exe`（或其他系统环境变量中的 FFmpeg），智能使用 H.264 (libx264) 或内置 MPEG-4 编码器执行转码。若未检测到 FFmpeg，则自动弹窗警告并安全回退保存为已修复进度条的 `.webm` 格式。 ### 🔭 全景环境探针 - **动态图集监测 (Dynamic Atlas)**：实时查阅框架层 Dynamic Atlas 的详细开关设置与贴图出血 (Bleeding) 策略。 - **动态图集高性能查看器 (High Performance Atlas Viewer)**：突破闭包壁垒实现 WebGL 显存级纹理直出。内置受控二维抛拽视口结构 (2D Transform Viewport)，支持超大缓冲纹理 (如 2048x2048) 的平移、无极中心滚轮缩放与首屏自适应显示，根除浏览器的 `zoom` 滚动条塌缩崩溃。 - **2D 物理与碰撞洞察**：可随时监测物理系统 (PhysicsManager) 的宏观步进设置与复杂的调试遮罩 (DrawFlags)，以及基础碰撞组件 (CollisionManager) 的轮廓标记渲染开关。 - **加载器快照追踪**：直接暴露底层环境下的 Downloader 核心池指标及并发状态。 ### 🎛️ 响应式界面 - **分辨率模拟**：内建 32+ 款覆盖全生态的高精度设备分辨率预设（涵盖 iOS/iPadOS 新老阵营、安卓直板全档位、折叠屏全形态以及平板横向视口），完美支撑全场景安全区及越界适配检测，并支持一键横竖屏翻转。 - **预制体资源定位器 (Prefab Asset Locator 🎯)**：自动侦测组件所在预制体并提供跳转捷径。 - **响应式渲染诊断面板**：流体自适应的三列布局代替硬性百分比，并辅以无原生括号的极简说明文本。 - **UI 无极缩放与字号解耦**：右侧特设“⚙️ 设置”，支持分别操控全局缩放比例（Zoom）以统御框架，或调节基础字号（Base Font）打磨排版，根除 1080P 或低分辨率下的拥挤死锁。 - **检查器多维排版**：支持“横向/纵向”双模式切换，解除固有排版约束；节点树/属性面板尺寸任您拖动并自动持久保存。 - **拖拽排序标签页**：自定义标签顺序，重启保持 - **紧凑图标工具栏**：极窄面板下也不变形，悬浮提示补全信息 - **防溢出画面**：双层 CSS 注入锁死滚动条，横竖屏均无杂物 ### 💾 偏好持久化 分辨率、FPS 叠加框开关、静音状态、面板宽度等设置自动保存至项目级 `settings/` 目录，重启即恢复。 ### 🧼 零噪音调试 默认静默所有探针日志，控制台 100% 留给游戏业务。需要排障时设置 `window.__MCP_DEBUG__ = true` 即可开启底层追踪。 --- ## 🛡️ 稳定性保障 | 机制 | 说明 | |------|------| | **场景校验沙盒** | 以 IPC `isEditorSceneActive` 为唯一放行条件，未就绪时完全不访问预览服务器，根治 `stashScene` 崩溃 | | **后台挂起复原** | `ResizeObserver` + `pendingRefresh` 标记，后台切回自动恢复画面 | | **多实例端口适配** | 核心桥接器端口自动冲突探测并向上扫描，多开项目实例互不串台 | | **IPC 降级容错** | 原生通道失联时自动切入 DOM 轮询，2 秒后静默警告 | | **单向数据流** | 严格杜绝面板↔探针的 IPC 递归循环 | | **Scene 节点只读** | 自动拦截 `cc.Scene` 属性访问，防止引擎报错 | | **Electron 跨代容灾** | 针对移除了 `remote` 模块的高版本引警环境 (Electron 14+) 实施智能垫片防空回退，防止面板因强制解构陷入瘫痪白屏 | | **IPC 克隆防御隔离** | 将对象结构化克隆(`structuredClone`)降级为跨沙盒的安全 JSON 序列化，杜绝探针在上传不可克隆引用（如原型函数/DOM）时导致整条通信链挂起崩溃 | --- ## 📦 项目结构 ```text mcp-inspector-bridge/ ├── package.json # 插件清单与脚本定义 ├── main.js # Cocos 插件主进程入口 ├── dist/ # 编译产物目录 ├── src/ │ ├── main.ts # 主进程逻辑 (IPC 注册、 BrowserView 管理) │ ├── preload.ts # Webview 预加载脚本 (IPC 桥接 + 探针注入) │ ├── scene-script.ts # 编辑器 Scene 进程脚本 (仅用于少量原生操作) │ ├── ipc-router.ts # 分发 IPC 与 WebContents 异步交互路由 │ ├── cdp-log-listener.ts # CDP 日志监听器 (BrowserView 原生事件 / Webview CDP debugger / 注入降级) │ ├── panel/ │ │ ├── index.ts # 面板入口，Vue 3 应用挂载 │ │ ├── index.html # 面板 HTML 模板与样式 │ │ ├── store.ts # 全局响应式状态 │ │ ├── composables/ # Vue Composable 模块 │ │ │ ├── useLayout.ts # 分辨率/布局/拖拽 │ │ │ ├── useGameView.ts # 游戏视图生命周期 │ │ │ ├── useDevTools.ts # DevTools BrowserView 管理 │ │ │ ├── useNodeSystem.ts # 节点选择/属性系统 │ │ │ ├── useProfiler.ts # 性能数据采集 │ │ │ └── useTabs.ts # 标签页排序 │ │ └── components/ # Vue 组件 │ │ ├── NodeTree.ts # 节点树组件 │ │ ├── NodeInspector.ts # 属性检查器 │ │ ├── RenderDebugger.ts # 渲染调试器 │ │ └── WidgetVisualizer.ts # Widget 可视化 │ ├── mcp-client/ # MCP 原生客户端与服务层 │ │ ├── index.ts # MCP Stdio 服务器入口，处理多实例扫描与路由切换 │ │ ├── tools.ts # MCP 工具集定义 (ping, get_active_instances, etc.) │ │ ├── resources.ts # MCP 资源订阅定义 (scene://hierarchy) │ │ ├── prompts.ts # MCP 提示词下发策略 │ │ └── configurator.ts # 22+ 款主流 AI 客户端配置自动注入器 │ └── probe/ # 探针模块 (esbuild → dist/probe.js) │ ├── index.ts # 探针主入口与生命周期 │ ├── crawler.ts # 节点树爬虫 │ ├── highlighter.ts # 高亮渲染层 │ ├── picker.ts # 屏幕拾取器 │ ├── profiler.ts # 帧率/耗时采集 │ ├── memory.ts # 内存资源扫描 │ ├── render-debugger.ts # 渲染管线劫持 │ └── logger.ts # 调试日志门控 ├── memory/ # 项目章程文档 └── specs/ # 功能规范文档 ``` --- ## 💡 开发说明 - **技术栈**：TypeScript + Vue 3 + Electron BrowserView + Cocos Creator 2.4.x Extension API - **构建工具**：`tsc` (主面板) + `esbuild` (探针模块 IIFE 打包) - **监听模式**：`npm run watch` 可同时启动 tsc 和 esbuild 的文件监听 - **调试开关**：在游戏预览的控制台中执行 `window.__MCP_DEBUG__ = true` 开启探针详细日志 - **详细更新记录**：参见 [UPDATE_LOG.md](./UPDATE_LOG.md)