ghost-bridge 0.3.0 → 0.4.0

package/README.md

@@ -1,18 +1,20 @@
-# Ghost Bridge（Claude MCP 无重启调试桥）
+# Ghost Bridge
 
-> 目标：在日常 Chrome 内零启动参数附加 DevTools，面向线上压缩代码（无 sourcemap）快速定位。
+> 无侵入 Chrome AI 副驾 —— 通过 MCP 让 AI 无缝接管你正在使用的浏览器，实时调试、观察页面、操控交互，无需启动新浏览器实例。
 
-## 目录结构
-- `server.js`：MCP server，通过 stdio 被 Claude CLI 拉起，与扩展用 WebSocket 通信
-- `extension/`：Chrome MV3 扩展，使用 `chrome.debugger` 附加当前激活标签
+## ✨ 特性
 
-# Ghost Bridge（Claude MCP 无重启调试桥）
+- 🔌 **零配置附加** — 不依赖 `--remote-debugging-port`，通过 Chrome 扩展直接获取 CDP
+- 🔍 **无 sourcemap 调试** — 片段截取、字符串搜索、覆盖率分析，在压缩代码中定位问题
+- 🌐 **网络请求分析** — 完整记录请求/响应，支持多维度过滤和响应体查看
+- 📸 **页面截图与内容提取** — 视觉分析 + 结构化数据提取
+- 🎯 **DOM 交互操控** — AI 可直接点击按钮、填写表单、按键提交，使用 CDP 物理级模拟，兼容 React/Vue/Angular
+- 📊 **性能诊断** — JS 堆内存、DOM 规模、Layout 开销、Web Vitals、资源加载分析
+- 🔄 **多实例支持** — 自动单例管理，多个 MCP 客户端共享同一 Chrome 连接
 
-> 目标：在日常 Chrome 内零启动参数附加 DevTools，面向线上压缩代码（无 sourcemap）快速定位。
+## 快速开始
 
-## 快速使用
-
-### 1. 安装與初始化
+### 1. 安装与初始化
 
 ```bash
 # 全局安装
@@ -25,61 +27,130 @@ ghost-bridge init
 ### 2. 加载 Chrome 扩展
 
 1. 打开 Chrome，访问 `chrome://extensions`
-2. 开启右上角的“开发者模式”
-3. 点击“加载已解压的扩展程序”
+2. 开启右上角的 **开发者模式**
+3. 点击 **加载已解压的扩展程序**
 4. 选择目录：`~/.ghost-bridge/extension`
-   > 提示：运行 `ghost-bridge extension --open` 可直接打开该目录
 
-### 3. 开始使用
+> 💡 运行 `ghost-bridge extension --open` 可直接打开该目录
+
+### 3. 连接并使用
+
+1. 点击浏览器工具栏中的 Ghost Bridge 图标
+2. 点击 **连接**，等待状态变为 ✅ 已连接
+3. 打开 Claude Desktop 或 Claude CLI，即可使用所有调试工具
+
+## CLI 命令
+
+| 命令 | 说明 |
+|------|------|
+| `ghost-bridge init` | 配置 MCP 并复制扩展文件 |
+| `ghost-bridge status` | 检查配置状态 |
+| `ghost-bridge extension` | 显示扩展安装路径（`--open` 打开目录） |
+| `ghost-bridge start` | 手动启动 MCP 服务（通常不需要） |
+
+## 工具一览
+
+### 🔍 基础调试
+
+| 工具 | 说明 |
+|------|------|
+| `get_server_info` | 获取服务器状态（端口、连接状态、角色） |
+| `get_last_error` | 汇总最近的异常 / console 错误 / 网络报错，附行列与脚本标识 |
+| `get_script_source` | 抓取目标脚本源码，支持按 URL 片段筛选、指定行列定位、beautify |
+| `coverage_snapshot` | 启动执行覆盖率采集（默认 1.5s），返回最活跃的脚本列表 |
+| `find_by_string` | 在页面脚本源码中按关键词搜索，返回 200 字符上下文窗口 |
+| `symbolic_hints` | 采集资源列表、全局变量 key、localStorage key、UA 与 URL |
+| `eval_script` | 在页面执行 JS 表达式（谨慎使用） |
+
+### � 网络请求分析
+
+| 工具 | 说明 |
+|------|------|
+| `list_network_requests` | 列出捕获的网络请求，支持按 URL / 方法 / 状态 / 资源类型过滤 |
+| `get_network_detail` | 获取单个请求的详细信息（请求头、响应头、timing），可选获取响应体 |
+| `clear_network_requests` | 清空已捕获的网络请求记录 |
+
+### 📸 页面内容
+
+| 工具 | 说明 |
+|------|------|
+| `capture_screenshot` | 截取页面截图（支持完整长截图、指定区域、JPEG/PNG 格式） |
+| `get_page_content` | 提取页面内容：纯文本 / HTML / 结构化数据（标题、链接、按钮、表单） |
+
+### 🎯 页面交互（DOM 操作）
 
-启动 Claude Desktop 或 Claude CLI，Ghost Bridge 工具即可直接通过 MCP 调用。无需额外启动任何服务（MCP 会自动管理）。
+| 工具 | 说明 |
+|------|------|
+| `get_interactive_snapshot` | 扫描页面所有可见可交互元素，返回带 ref 短标识（e1, e2...）的精简列表，支持 Shadow DOM 穿透 |
+| `dispatch_action` | 对目标元素执行动作（click / fill / press / scroll / select / hover / focus），使用 CDP 物理级模拟 |
 
----
+**交互工作流示例：**
 
-## 常用命令
+```
+1. AI 调用 get_interactive_snapshot
+   → 返回: [{ref:"e1", tag:"input", placeholder:"Search..."}, {ref:"e2", tag:"button", text:"Login"}]
+
+2. AI 调用 dispatch_action({ref: "e1", action: "fill", value: "hello"})
+   → 在搜索框中输入 "hello"
 
-- `ghost-bridge init`: 配置 MCP 并复制扩展文件
-- `ghost-bridge status`: 检查配置状态
-- `ghost-bridge extension`: 显示扩展安装路径
-- `ghost-bridge start`: 手动启动 MCP 服务（通常不需要）
+3. AI 调用 dispatch_action({ref: "e2", action: "click"})
+   → 点击 Login 按钮
+
+4. AI 调用 capture_screenshot 验证操作结果
+```
 
-## 默认配置
-- 端口：`3301`（`server.js` / `extension/background.js`）
-- token：`1`（仅用于本机 WS 校验，如需修改请保持两端一致）
+### 📊 性能分析
 
-## 工具说明
+| 工具 | 说明 |
+|------|------|
+| `perf_metrics` | 获取页面性能指标，包含三层数据：|
 
-### 基础调试工具
-- **get_last_error**：汇总最近异常/console/网络报错，附带行列与脚本标识
-- **get_script_source**：支持 `scriptUrlContains`、`line`、`column`，返回源码片段（无 sourcemap 仍可用）
-- **coverage_snapshot**：默认 1.5s，输出调用次数最高的脚本
-- **find_by_string**：在脚本源码里按关键词搜索，返回上下文 200 字符窗口
-- **symbolic_hints**：采集资源列表、全局变量 key、localStorage key、UA 与 URL
-- **eval_script**：只读表达式执行；谨慎使用，避免改写页面状态
+**`perf_metrics` 返回的数据：**
 
-### 🆕 网络请求分析工具
-- **list_network_requests**：列出捕获的网络请求
-  - 支持按 URL 关键词过滤（`filter`）
-  - 支持按请求方法过滤（`method`: GET/POST/PUT/DELETE）
-  - 支持按状态过滤（`status`: success/error/failed/pending）
-  - 支持按资源类型过滤（`resourceType`: XHR/Fetch/Script/Image）
-  - 返回：URL、方法、状态码、耗时、大小等摘要信息
+- **引擎级指标** — JS 堆内存（使用量/总量/占比）、DOM 节点数、事件监听器数、Layout 重排次数与耗时、脚本执行时间
+- **Web Vitals** — Navigation Timing 各阶段（DNS / TTFB / DOM Interactive / Load）、FP、FCP、Long Tasks 统计
+- **资源加载摘要** — 按类型分组统计（count / size / avgDuration）、最慢资源识别
 
-- **get_network_detail**：获取单个请求的详细信息
-  - 请求头和响应头
-  - 请求方法、状态码、MIME 类型
-  - 耗时分析（timing）
-  - 可选获取响应体（`includeBody: true`）
+## 配置
 
-- **clear_network_requests**：清空已捕获的网络请求记录
+| 项目 | 默认值 | 说明 |
+|------|--------|------|
+| 端口 | `33333` | WebSocket 服务端口，自动递增寻找可用端口 |
+| Token | 当月自动生成 | 本机 WS 校验，基于当月 1 号时间戳 |
+| 自动 Detach | `false` | 保持附加，便于持续捕获异常和网络请求 |
 
-## 设计取舍
-- 不依赖 `--remote-debugging-port`，完全通过扩展获取 CDP，满足"零重启"
-- 默认 `autoDetach=false` 保持附加，便于持续捕获异常和网络请求；可通过图标 OFF 立即解除调试
-- 无 sourcemap 时通过片段截取、字符串搜索与覆盖率提供线索
-- 网络请求完整记录，支持查看请求/响应详情和响应体
+环境变量：
+
+- `GHOST_BRIDGE_PORT` — 自定义基础端口
+- `GHOST_BRIDGE_TOKEN` — 自定义 token
+
+## 架构
+
+```
+┌──────────────┐     stdio      ┌──────────────┐    WebSocket    ┌──────────────┐
+│  Claude CLI  │ ◄────────────► │  MCP Server  │ ◄──────────────►│Chrome Extension│
+│  / Desktop   │                │ (server.js)  │                 │(background.js)│
+└──────────────┘                └──────────────┘                 └──────┬───────┘
+                                                                       │ CDP
+                                                                 ┌─────▼──────┐
+                                                                 │  浏览器页面  │
+                                                                 └────────────┘
+```
+
+- **MCP Server** — 通过 stdio 被 Claude 拉起，与扩展通过 WebSocket 通信
+- **Chrome Extension (MV3)** — 使用 `chrome.debugger` API 附加页面，Offscreen Document 维持 WebSocket 长连接
+- **单例模式** — 多个 MCP 客户端自动协调，首个实例为主服务，后续实例作为客户端连接
 
 ## 已知限制
-- 扩展 service worker 可能被挂起，已内置 1s 重连策略；若长时间无流量需重新唤醒
-- 若目标页面自带 DevTools 打开，`chrome.debugger.attach` 可能失败，请关闭后重试
-- 大体积单行 bundle beautify 可能耗时，server 端对超长源码会只截取片段
+
+- 扩展 Service Worker 可能被挂起，已内置重连策略；若长时间无流量需重新唤醒
+- 若目标页面已打开 DevTools，`chrome.debugger.attach` 可能失败，请关闭后重试
+- 大体积单行 bundle beautify 可能耗时，服务端对超长源码会截取片段
+- 跨月时 token 会自动更新，扩展和服务端需在同月内启动
+- DOM 交互：SPA 路由变化后 ref 标识会失效，需重新调用 `get_interactive_snapshot`
+- DOM 交互：跨域 iframe 内的元素暂不支持细粒度操作
+- DOM 交互：Shadow DOM 内的元素可以被扫描到，但部分封闭模式的 Shadow Root 可能无法穿透
+
+## License
+
+MIT

package/dist/server.js

@@ -28896,7 +28896,7 @@ function buildSnippet(source, line, column, { beautifyEnabled = true, contextLin
   return result;
 }
 var server = new Server(
-  { name: "ghost-bridge", version: "0.3.0" },
+  { name: "ghost-bridge", version: "0.4.0" },
   { capabilities: { tools: {} } }
 );
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
@@ -29067,6 +29067,66 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
           }
         }
       }
+    },
+    {
+      name: "get_interactive_snapshot",
+      description: "\u3010\u64CD\u4F5C\u9875\u9762\u524D\u5FC5\u987B\u5148\u8C03\u7528\u3011\u626B\u63CF\u5F53\u524D\u9875\u9762\u6240\u6709\u53EF\u89C1\u7684\u53EF\u4EA4\u4E92\u5143\u7D20\uFF08\u6309\u94AE/\u94FE\u63A5/\u8F93\u5165\u6846/\u4E0B\u62C9\u6846\u7B49\uFF09\uFF0C\u8FD4\u56DE\u5E26\u6709 ref \u77ED\u6807\u8BC6\uFF08\u5982 e1, e2, e3\uFF09\u7684\u7CBE\u7B80\u5217\u8868\uFF0C\u5305\u542B\u5143\u7D20\u7C7B\u578B\u3001\u6587\u672C\u548C\u4F4D\u7F6E\u3002Token \u6781\u7701\uFF08\u901A\u5E38 < 1000 tokens\uFF09\uFF0C\u4E13\u4E3A AI \u64CD\u4F5C\u9875\u9762\u800C\u8BBE\u8BA1\u3002\u83B7\u53D6\u540E\u53EF\u901A\u8FC7 dispatch_action \u5DE5\u5177\u4F7F\u7528 ref \u6807\u8BC6\u6765\u70B9\u51FB\u3001\u586B\u5199\u3001\u6309\u952E\u7B49\u3002\u652F\u6301 Shadow DOM \u7A7F\u900F\u3002\n\u26A0\uFE0F \u4EC5\u7528\u4E8E\u4EA4\u4E92\u64CD\u4F5C\u524D\u7684\u5143\u7D20\u5B9A\u4F4D\u3002\u5982\u9700\u6392\u67E5 UI/CSS \u5E03\u5C40\u95EE\u9898\uFF0C\u8BF7\u4F7F\u7528 capture_screenshot \u6216 get_page_content\u3002",
+      inputSchema: {
+        type: "object",
+        properties: {
+          selector: {
+            type: "string",
+            description: "CSS \u9009\u62E9\u5668\uFF0C\u9650\u5B9A\u626B\u63CF\u8303\u56F4\u3002\u4E0D\u6307\u5B9A\u5219\u626B\u63CF\u6574\u4E2A\u9875\u9762"
+          },
+          includeText: {
+            type: "boolean",
+            description: "\u662F\u5426\u5305\u542B\u5143\u7D20\u7684\u6587\u672C/\u5360\u4F4D\u7B26\u7B49\u4FE1\u606F\uFF0C\u9ED8\u8BA4 true"
+          },
+          maxElements: {
+            type: "number",
+            description: "\u6700\u5927\u8FD4\u56DE\u5143\u7D20\u6570\u91CF\uFF0C\u9ED8\u8BA4 100"
+          }
+        }
+      }
+    },
+    {
+      name: "dispatch_action",
+      description: "\u3010\u64CD\u4F5C\u9875\u9762\u5143\u7D20\u3011\u5BF9 get_interactive_snapshot \u8FD4\u56DE\u7684\u5143\u7D20\u6267\u884C\u52A8\u4F5C\u3002\u901A\u8FC7 ref \u6807\u8BC6\uFF08\u5982 e1, e5\uFF09\u7CBE\u51C6\u5B9A\u4F4D\u5143\u7D20\uFF0C\u4F7F\u7528 CDP \u7269\u7406\u7EA7\u6A21\u62DF\u6267\u884C\u64CD\u4F5C\uFF0C\u517C\u5BB9\u6240\u6709\u524D\u7AEF\u6846\u67B6\uFF08React/Vue/Angular\uFF09\uFF0C\u6210\u529F\u7387\u6781\u9AD8\u3002\n\u652F\u6301\u7684\u52A8\u4F5C\uFF1Aclick\uFF08\u70B9\u51FB\uFF09\u3001fill\uFF08\u586B\u5199\u8F93\u5165\u6846\uFF09\u3001press\uFF08\u6309\u952E\u5982 Enter\uFF09\u3001scroll\uFF08\u6EDA\u52A8\uFF09\u3001select\uFF08\u4E0B\u62C9\u9009\u62E9\uFF09\u3001hover\uFF08\u60AC\u505C\uFF09\u3001focus\uFF08\u805A\u7126\uFF09\u3002\n\u26A0\uFE0F \u4F7F\u7528\u524D\u5FC5\u987B\u5148\u8C03\u7528 get_interactive_snapshot \u83B7\u53D6\u5143\u7D20\u5217\u8868\u3002\u64CD\u4F5C\u540E\u5EFA\u8BAE\u7528 capture_screenshot \u6216\u518D\u6B21 get_interactive_snapshot \u9A8C\u8BC1\u7ED3\u679C\u3002",
+      inputSchema: {
+        type: "object",
+        properties: {
+          ref: {
+            type: "string",
+            description: "\u76EE\u6807\u5143\u7D20\u7684 ref \u6807\u8BC6\uFF0C\u5982 'e1'\u3001'e5'\uFF08\u4ECE get_interactive_snapshot \u83B7\u53D6\uFF09"
+          },
+          action: {
+            type: "string",
+            enum: ["click", "fill", "press", "scroll", "select", "hover", "focus"],
+            description: "\u8981\u6267\u884C\u7684\u52A8\u4F5C\u7C7B\u578B"
+          },
+          value: {
+            type: "string",
+            description: "fill \u65F6\u4E3A\u8981\u8F93\u5165\u7684\u6587\u672C\uFF1Bselect \u65F6\u4E3A\u8981\u9009\u62E9\u7684 option value\uFF1Bpress \u65F6\u4E3A\u6309\u952E\u540D\uFF08\u53EF\u9009\uFF09"
+          },
+          key: {
+            type: "string",
+            description: "press \u52A8\u4F5C\u7684\u6309\u952E\u540D\uFF0C\u5982 'Enter'\u3001'Escape'\u3001'Tab'\u3001'Backspace'\u3002\u9ED8\u8BA4 'Enter'"
+          },
+          deltaX: {
+            type: "number",
+            description: "scroll \u52A8\u4F5C\u7684\u6C34\u5E73\u6EDA\u52A8\u91CF\uFF08\u50CF\u7D20\uFF09\uFF0C\u9ED8\u8BA4 0"
+          },
+          deltaY: {
+            type: "number",
+            description: "scroll \u52A8\u4F5C\u7684\u5782\u76F4\u6EDA\u52A8\u91CF\uFF08\u50CF\u7D20\uFF09\uFF0C\u9ED8\u8BA4 300\uFF08\u6B63\u6570\u5411\u4E0B\uFF0C\u8D1F\u6570\u5411\u4E0A\uFF09"
+          },
+          waitMs: {
+            type: "number",
+            description: "\u64CD\u4F5C\u540E\u7B49\u5F85\u9875\u9762\u54CD\u5E94\u7684\u65F6\u95F4\uFF08\u6BEB\u79D2\uFF09\uFF0C\u9ED8\u8BA4 500\uFF0C\u6700\u5927 3000"
+          }
+        },
+        required: ["ref", "action"]
+      }
     }
   ]
 }));
@@ -29223,6 +29283,16 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       const res = await askChrome("getPageContent", { mode, selector, maxLength, includeMetadata });
       return { content: [{ type: "text", text: jsonText(res) }] };
     }
+    if (name === "get_interactive_snapshot") {
+      const { selector, includeText, maxElements } = args;
+      const res = await askChrome("getInteractiveSnapshot", { selector, includeText, maxElements });
+      return { content: [{ type: "text", text: jsonText(res) }] };
+    }
+    if (name === "dispatch_action") {
+      const { ref, action, value, key, deltaX, deltaY, waitMs } = args;
+      const res = await askChrome("dispatchAction", { ref, action, value, key, deltaX, deltaY, waitMs }, { timeoutMs: 1e4 });
+      return { content: [{ type: "text", text: jsonText(res) }] };
+    }
     return { content: [{ type: "text", text: `\u672A\u77E5\u5DE5\u5177\uFF1A${name}` }] };
   } catch (e) {
     return { content: [{ type: "text", text: `Error: ${e.message}` }] };

package/extension/background.js

@@ -912,6 +912,299 @@ async function handleGetPageContent(params = {}) {
   return result?.value
 }
 
+// ========== DOM 交互：可交互元素快照 ==========
+
+async function handleGetInteractiveSnapshot(params = {}) {
+  const target = await ensureAttached()
+  const { selector, includeText = true, maxElements = 100 } = params
+
+  const selectorStr = selector ? JSON.stringify(selector) : 'null'
+
+  const expression = `(function() {
+    try {
+      let refCounter = 0;
+      const elements = [];
+
+      // 判断元素是否可见
+      function isVisible(el) {
+        if (!el.offsetParent && el.tagName !== 'HTML' && el.tagName !== 'BODY' &&
+            window.getComputedStyle(el).position !== 'fixed' &&
+            window.getComputedStyle(el).position !== 'sticky') return false;
+        const style = window.getComputedStyle(el);
+        if (style.display === 'none' || style.visibility === 'hidden' || parseFloat(style.opacity) === 0) return false;
+        const rect = el.getBoundingClientRect();
+        if (rect.width === 0 && rect.height === 0) return false;
+        return true;
+      }
+
+      // 判断元素是否可交互
+      function isInteractive(el) {
+        const tag = el.tagName.toLowerCase();
+        if (['a', 'button', 'input', 'select', 'textarea'].includes(tag)) return true;
+        if (el.getAttribute('role') === 'button' || el.getAttribute('role') === 'link' ||
+            el.getAttribute('role') === 'tab' || el.getAttribute('role') === 'menuitem' ||
+            el.getAttribute('role') === 'checkbox' || el.getAttribute('role') === 'radio' ||
+            el.getAttribute('role') === 'switch' || el.getAttribute('role') === 'combobox') return true;
+        if (el.getAttribute('tabindex') && parseInt(el.getAttribute('tabindex')) >= 0) return true;
+        if (el.getAttribute('contenteditable') === 'true') return true;
+        if (el.onclick || el.getAttribute('onclick')) return true;
+        return false;
+      }
+
+      // 递归遍历 DOM 树（含 Shadow DOM）
+      function walkDOM(node, root) {
+        if (elements.length >= ${maxElements}) return;
+        const children = node.children || [];
+        for (let i = 0; i < children.length; i++) {
+          if (elements.length >= ${maxElements}) return;
+          const el = children[i];
+          if (isInteractive(el) && isVisible(el)) {
+            refCounter++;
+            const ref = 'e' + refCounter;
+            el.setAttribute('data-ghost-ref', ref);
+            const tag = el.tagName.toLowerCase();
+            const rect = el.getBoundingClientRect();
+            const entry = {
+              ref: ref,
+              tag: tag,
+              cx: Math.round(rect.left + rect.width / 2),
+              cy: Math.round(rect.top + rect.height / 2),
+            };
+            // 类型信息
+            if (el.type) entry.type = el.type;
+            if (el.name) entry.name = el.name;
+            if (el.getAttribute('role')) entry.role = el.getAttribute('role');
+            // 文本信息
+            if (${includeText}) {
+              if (el.placeholder) entry.placeholder = el.placeholder.slice(0, 80);
+              if (el.value && tag !== 'textarea') entry.value = el.value.slice(0, 80);
+              if (tag === 'a') entry.href = (el.href || '').slice(0, 150);
+              if (tag === 'select') {
+                entry.options = Array.from(el.options).slice(0, 10).map(o => ({
+                  value: o.value, text: o.text.slice(0, 50), selected: o.selected
+                }));
+              }
+              const text = (el.innerText || el.textContent || el.getAttribute('aria-label') || '').trim();
+              if (text && text.length <= 100) entry.text = text;
+              else if (text) entry.text = text.slice(0, 97) + '...';
+            }
+            // disabled 状态
+            if (el.disabled) entry.disabled = true;
+            elements.push(entry);
+          }
+          // 递归子节点
+          walkDOM(el, root);
+          // 穿透 Shadow DOM
+          if (el.shadowRoot) {
+            walkDOM(el.shadowRoot, root);
+          }
+        }
+      }
+
+      // 清理旧的 ref 标记
+      document.querySelectorAll('[data-ghost-ref]').forEach(el => el.removeAttribute('data-ghost-ref'));
+
+      // 确定扫描根节点
+      let rootEl = document.body;
+      const sel = ${selectorStr};
+      if (sel) {
+        rootEl = document.querySelector(sel);
+        if (!rootEl) return { error: '选择器未匹配到任何元素', selector: sel };
+      }
+
+      walkDOM(rootEl, rootEl);
+
+      return {
+        url: window.location.href,
+        title: document.title,
+        elementCount: elements.length,
+        viewport: {
+          width: window.innerWidth,
+          height: window.innerHeight,
+          scrollX: Math.round(window.scrollX),
+          scrollY: Math.round(window.scrollY),
+        },
+        elements: elements,
+      };
+    } catch (e) { return { error: e.message }; }
+  })()`
+
+  const { result } = await chrome.debugger.sendCommand(target, "Runtime.evaluate", {
+    expression,
+    returnByValue: true,
+  })
+
+  if (result?.value?.error) throw new Error(result.value.error)
+  return result?.value
+}
+
+// ========== DOM 交互：动作分发器 ==========
+
+async function handleDispatchAction(params = {}) {
+  const target = await ensureAttached()
+  const { ref, action, value, key, deltaX, deltaY, waitMs = 500 } = params
+
+  if (!ref) throw new Error("需要提供 ref（元素标识，如 'e1'）")
+  if (!action) throw new Error("需要提供 action（动作类型：click/fill/press/scroll/select/hover/focus）")
+
+  // Step 1: 实时获取目标元素的最新坐标和状态
+  const locateExpression = `(function() {
+    try {
+      const el = document.querySelector('[data-ghost-ref="${ref}"]');
+      if (!el) return { error: '元素未找到，ref 可能已失效，请重新获取快照' };
+      const rect = el.getBoundingClientRect();
+      if (rect.width === 0 && rect.height === 0) return { error: '元素不可见（宽高为 0）' };
+      return {
+        found: true,
+        tag: el.tagName.toLowerCase(),
+        type: el.type || '',
+        cx: Math.round(rect.left + rect.width / 2),
+        cy: Math.round(rect.top + rect.height / 2),
+        disabled: el.disabled || false,
+        value: (el.value || '').slice(0, 100),
+      };
+    } catch (e) { return { error: e.message }; }
+  })()`
+
+  const { result: locResult } = await chrome.debugger.sendCommand(target, "Runtime.evaluate", {
+    expression: locateExpression,
+    returnByValue: true,
+  })
+
+  const loc = locResult?.value
+  if (!loc || loc.error) throw new Error(loc?.error || "无法定位元素")
+  if (loc.disabled) throw new Error(`元素 ${ref} 已被禁用 (disabled)`)
+
+  const cx = loc.cx
+  const cy = loc.cy
+
+  let actionResult = { ref, action, success: true }
+
+  // Step 2: 根据动作类型执行 CDP 命令
+  if (action === "click") {
+    // 物理级 CDP 鼠标点击
+    await chrome.debugger.sendCommand(target, "Input.dispatchMouseEvent", {
+      type: "mousePressed", x: cx, y: cy, button: "left", clickCount: 1,
+    })
+    await chrome.debugger.sendCommand(target, "Input.dispatchMouseEvent", {
+      type: "mouseReleased", x: cx, y: cy, button: "left", clickCount: 1,
+    })
+    actionResult.detail = `已点击 ${ref} (${loc.tag}) 坐标 (${cx}, ${cy})`
+
+  } else if (action === "fill") {
+    if (value === undefined || value === null) throw new Error("fill 动作需要提供 value 参数")
+    // 先点击聚焦
+    await chrome.debugger.sendCommand(target, "Input.dispatchMouseEvent", {
+      type: "mousePressed", x: cx, y: cy, button: "left", clickCount: 1,
+    })
+    await chrome.debugger.sendCommand(target, "Input.dispatchMouseEvent", {
+      type: "mouseReleased", x: cx, y: cy, button: "left", clickCount: 1,
+    })
+    // 全选并清空已有内容
+    await chrome.debugger.sendCommand(target, "Runtime.evaluate", {
+      expression: `(function() {
+        const el = document.querySelector('[data-ghost-ref="${ref}"]');
+        if (el) { el.focus(); el.select && el.select(); }
+      })()`,
+    })
+    // 用 CDP 模拟键盘输入
+    await chrome.debugger.sendCommand(target, "Input.insertText", {
+      text: String(value),
+    })
+    // 强制触发 input/change 事件（兼容 React/Vue）
+    await chrome.debugger.sendCommand(target, "Runtime.evaluate", {
+      expression: `(function() {
+        const el = document.querySelector('[data-ghost-ref="${ref}"]');
+        if (el) {
+          el.dispatchEvent(new Event('input', { bubbles: true }));
+          el.dispatchEvent(new Event('change', { bubbles: true }));
+        }
+      })()`,
+    })
+    actionResult.detail = `已在 ${ref} (${loc.tag}) 中填入 "${String(value).slice(0, 50)}"`
+
+  } else if (action === "press") {
+    // 模拟键盘按键
+    const keyName = key || value || "Enter"
+    // 先确保元素聚焦
+    await chrome.debugger.sendCommand(target, "Runtime.evaluate", {
+      expression: `(function() {
+        const el = document.querySelector('[data-ghost-ref="${ref}"]');
+        if (el) el.focus();
+      })()`,
+    })
+    await chrome.debugger.sendCommand(target, "Input.dispatchKeyEvent", {
+      type: "keyDown", key: keyName,
+    })
+    await chrome.debugger.sendCommand(target, "Input.dispatchKeyEvent", {
+      type: "keyUp", key: keyName,
+    })
+    actionResult.detail = `已在 ${ref} 上按下 ${keyName}`
+
+  } else if (action === "scroll") {
+    const dx = deltaX || 0
+    const dy = deltaY || 300
+    await chrome.debugger.sendCommand(target, "Input.dispatchMouseEvent", {
+      type: "mouseWheel", x: cx, y: cy, deltaX: dx, deltaY: dy,
+    })
+    actionResult.detail = `已在 ${ref} 位置滚动 (${dx}, ${dy})`
+
+  } else if (action === "select") {
+    // 下拉框选择
+    if (value === undefined) throw new Error("select 动作需要提供 value 参数")
+    await chrome.debugger.sendCommand(target, "Runtime.evaluate", {
+      expression: `(function() {
+        const el = document.querySelector('[data-ghost-ref="${ref}"]');
+        if (el && el.tagName === 'SELECT') {
+          el.value = ${JSON.stringify(String(value))};
+          el.dispatchEvent(new Event('change', { bubbles: true }));
+        }
+      })()`,
+    })
+    actionResult.detail = `已在 ${ref} 选择值 "${value}"`
+
+  } else if (action === "hover") {
+    await chrome.debugger.sendCommand(target, "Input.dispatchMouseEvent", {
+      type: "mouseMoved", x: cx, y: cy,
+    })
+    actionResult.detail = `已将鼠标悬停到 ${ref} (${cx}, ${cy})`
+
+  } else if (action === "focus") {
+    await chrome.debugger.sendCommand(target, "Runtime.evaluate", {
+      expression: `(function() {
+        const el = document.querySelector('[data-ghost-ref="${ref}"]');
+        if (el) el.focus();
+      })()`,
+    })
+    actionResult.detail = `已聚焦到 ${ref}`
+
+  } else {
+    throw new Error(`不支持的动作类型: ${action}，可选: click/fill/press/scroll/select/hover/focus`)
+  }
+
+  // Step 3: 等待页面响应
+  if (waitMs > 0) {
+    await sleep(Math.min(waitMs, 3000))
+  }
+
+  // Step 4: 获取操作后状态摘要
+  const { result: afterResult } = await chrome.debugger.sendCommand(target, "Runtime.evaluate", {
+    expression: `(function() {
+      return {
+        url: window.location.href,
+        title: document.title,
+        readyState: document.readyState,
+      };
+    })()`,
+    returnByValue: true,
+  })
+  if (afterResult?.value) {
+    actionResult.pageAfter = afterResult.value
+  }
+
+  return actionResult
+}
+
 // 处理来自服务器的命令
 async function handleCommand(message) {
   const { id, command, params, token } = message
@@ -938,6 +1231,8 @@ async function handleCommand(message) {
     else if (command === "perfMetrics") result = await handlePerfMetrics(params)
     else if (command === "captureScreenshot") result = await handleCaptureScreenshot(params)
     else if (command === "getPageContent") result = await handleGetPageContent(params)
+    else if (command === "getInteractiveSnapshot") result = await handleGetInteractiveSnapshot(params)
+    else if (command === "dispatchAction") result = await handleDispatchAction(params)
     else throw new Error(`未知指令 ${command}`)
 
     sendToServer({ id, result })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ghost-bridge",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "private": false,
   "type": "module",
   "description": "Ghost Bridge: Zero-restart Chrome debugger bridge for Claude MCP. Includes CLI for easy setup.",