ghost-bridge 0.5.1 → 0.6.0

package/README.md

@@ -1,183 +1,151 @@
 # 👻 Ghost Bridge
 
 [![npm version](https://img.shields.io/npm/v/ghost-bridge.svg?style=flat-square)](https://www.npmjs.com/package/ghost-bridge)
+[![npm total downloads](https://img.shields.io/npm/dt/ghost-bridge.svg?style=flat-square&label=downloads)](https://www.npmjs.com/package/ghost-bridge)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
 
-> **Zero-restart Chrome AI Copilot** — Subvert your workflow. Allow AI to seamlessly take over the browser you're already using, enabling real-time debugging, visual observation, and interactive manipulation without launching a new Chrome instance.
+> Zero-restart Chrome bridge for MCP clients. Let AI inspect, debug, and operate the browser session you are already using.
 
----
+## Why
 
-## ✨ Why Ghost Bridge?
+Most browser-capable AI tools start a separate browser. Ghost Bridge connects AI to your existing Chrome session instead, so it can work with the page state you already have: logged-in accounts, reproduced bugs, in-progress flows, network failures, and real UI state.
 
-- 🔌 **Zero-Config Attach** — Bypasses the need for `--remote-debugging-port`. Captures Chrome's native DevTools Protocol directly via an extension.
-- 🔍 **No-Sourcemap Debugging** — Slice code fragments, perform string searches, and analyze coverage to pinpoint bugs straight in minified production code.
-- 🌐 **Deep Network Analysis** — Comprehensive capture of requests/responses with multi-dimensional filtering and response body inspection.
-- 📸 **Visual & Structural Perception** — Full-page or clipped high-fidelity screenshots paired with structural data extraction (titles, links, forms, buttons).
-- 🎯 **DOM Physical Manipulation** — Empowers AI to click, type, and form-submit with CDP-level physical simulation. Fully compatible with complex SPAs (React/Vue/Angular/Svelte).
-- 📊 **Performance Diagnostics** — Get granular engine metrics: JS Heap, Layout recalculations, Web Vitals (TTFB/FCP/LCP), and resource loading speeds.
-- 🔄 **Multi-Client Mastery** — Built-in singleton manager automatically coordinates multiple MCP clients sharing a single Chrome transport.
+## What It Does
 
----
+- Attach to Chrome without `--remote-debugging-port`
+- Inspect page structure, text, screenshots, errors, and network traffic
+- Search and extract script sources, even in production bundles
+- Click, type, scroll, and submit forms on the current page
+- Share one Chrome transport across multiple MCP clients
 
-## 🚀 Quick Start
+## What's New in 0.6.0
 
-### 1. Install & Initialize
+- `inspect_page` now collects structured page data and interactive elements in one browser-side snapshot, reducing duplicate DOM scans and cutting one round-trip from the hot path
+- `capture_screenshot` now defaults to JPEG for better transfer efficiency: visible viewport screenshots default to `quality: 80`, and `fullPage` screenshots default to `quality: 70`
+- Use `format: "png"` when you need high-fidelity text rendering, 1px lines, icon edges, transparency, or pixel-level UI inspection
+- Attachment and request cleanup paths are more robust under concurrent usage and multi-client reconnect scenarios
+
+## Quick Start
+
+### 1. Install
 
 ```bash
-# Install globally
 npm install -g ghost-bridge
-
-# Auto-configure MCP (Claude Code, Codex, Cursor, Antigravity) and prepare the extension directory
 ghost-bridge init
 ```
 
-> `ghost-bridge init` currently writes:
-> - Claude Code: `~/.claude/settings.json` or legacy `~/.claude.json`
-> - Codex: `~/.codex/config.toml`
-> - Cursor: `~/.cursor/mcp.json`
-> - Antigravity: `~/.gemini/antigravity/mcp.json`
->
-> **Note on other MCP clients (Windsurf, Roo, others):** 
-> `ghost-bridge init` attempts to auto-configure supported clients. If your client isn't auto-detected, add one of the following snippets to the appropriate MCP configuration file:
->
-> JSON-style MCP configs (`mcp.json`, Claude JSON config, Cursor):
-> ```json
-> {
->   "mcpServers": {
->     "ghost-bridge": {
->       "command": "/absolute/path/to/node",
->       "args": ["/absolute/path/to/global/node_modules/ghost-bridge/dist/server.js"]
->     }
->   }
-> }
-> ```
->
-> Codex TOML config (`~/.codex/config.toml`):
-> ```toml
-> [mcp_servers.ghost-bridge]
-> type = "stdio"
-> command = "/absolute/path/to/node"
-> args = ["/absolute/path/to/global/node_modules/ghost-bridge/dist/server.js"]
-> ```
-
-### 2. Load the Chrome Extension
-
-1. Open Chrome and navigate to `chrome://extensions`
-2. Toggle **Developer mode** in the top right corner.
-3. Click **Load unpacked**
-4. Select the directory: `~/.ghost-bridge/extension`
-
-> 💡 *Tip: Run `ghost-bridge extension --open` to reveal the directory directly.*
-
-### 3. Connect & Command
-
-1. Click the **Ghost Bridge** ghost icon in your browser toolbar.
-2. Click **Connect** and wait for the status to turn to ✅ **ON**.
-3. Open Claude Desktop or your Claude CLI. All tools are now primed and ready!
-
-**Prompting tips:**
-- You usually do not need to say "please use ghost-bridge". Direct requests like `分析当前页面`、`看看这个网站的 DOM 结构`、`帮我检查这个页面为什么布局错了`、`帮我点击登录按钮并提交表单` should be enough.
-- `inspect_page` is the default entry tool for generic page analysis.
-- For visual/UI issues, the model should prefer `capture_screenshot`.
-- For text/DOM extraction, the model should prefer `get_page_content`.
-- For page actions, the model should start with `get_interactive_snapshot` and then call `dispatch_action`.
-
----
-
-## 🛠️ Tool Arsenal
-
-### 🔍 Core Debugging
-
-| Tool | Capability |
-|------|------------|
-| `inspect_page` | Best default entry for page analysis. Returns metadata, structured content, and an interactive-elements overview. |
-| `get_server_info` | Retrieves server instance status, WebSocket ports, and client roles. |
-| `get_last_error` | Aggregates recent exceptions, console errors, and failed network requests with mapped locators. |
-| `get_script_source` | Pulls raw script definitions. Supports URL-fragment filtering, specific line targeting, and beautification. |
-| `coverage_snapshot` | Triggers a quick coverage trace (1.5s default) to identify the most active scripts on the page. |
-| `find_by_string` | Scans page script sources for keywords, returning a 200-character context window. |
-| `symbolic_hints` | Gathers context clues: Resource lists, Global Variable keys, LocalStorage schema, and UA strings. |
-| `eval_script` | Executes raw JavaScript expressions in the page context. *(Use with caution)* |
-
-### 🌍 Network Intelligence
-
-| Tool | Capability |
-|------|------------|
-| `list_network_requests` | Lists captured network traffic. Supports filtering by URL, Method, Status Code, or Resource Type. |
-| `get_network_detail` | Dives deep into a specific request's Headers, Timing, and optional Response Body extraction. |
-| `clear_network_requests` | Wipes the current network capture buffer. |
-
-### 📸 Page Perception
-
-| Tool | Capability |
-|------|------------|
-| `capture_screenshot` | Captures the viewport or emulates full-page scrolling screenshots. |
-| `get_page_content` | Extracts raw text, sanitized HTML, or structured actionable data representations. |
-
-### 🎯 Interactive Automation (DOM)
-
-| Tool | Capability |
-|------|------------|
-| `get_interactive_snapshot` | Scans for visible interactive elements, returning a concise map `[e1, e2...]`. Pierces open Shadow DOMs. |
-| `dispatch_action` | Dispatches physical UI actions (click, fill, press, hover) against targeted element references (e.g., `e1`). |
-
-**Example Agent Workflow:**
-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"})`
-3. AI: `dispatch_action({ref: "e2", action: "click"})`
-4. AI: `capture_screenshot` to verify state changes.
-
-### 📊 Performance Profiling
-
-| Tool | Capability |
-|------|------------|
-| `perf_metrics` | Collects layered performance data (Engine Metrics, Web Vitals, and Resource Load Summaries). |
-
----
-
-## ⚙️ Configuration
-
-| Setting | Default | Description |
-|---------|---------|-------------|
-| **Base Port** | `33333` | WS port. Auto-increments if occupied. |
-| **Token** | *Monthly UUID* | Local WS auth token, auto-rotates on the 1st of every month. |
-| **Auto Detach** | `false` | Keeps debugger attached to actively buffer invisible exceptions and network calls. |
-
-**Environment Variables:**
-- `GHOST_BRIDGE_PORT` — Override base port.
-- `GHOST_BRIDGE_TOKEN` — Override connection token.
+`ghost-bridge init` currently writes config for:
 
----
+- Claude Code: `~/.claude/settings.json` or `~/.claude.json`
+- Codex: `~/.codex/config.toml`
+- Cursor: `~/.cursor/mcp.json`
+- Antigravity: `~/.gemini/antigravity/mcp.json`
 
-## 🏗️ Architecture
+If your MCP client is not auto-detected, add one of these manually.
 
-```mermaid
-graph LR
-    A[Claude CLI/Desktop] <-->|stdio| B(MCP Server\nserver.js)
-    B <-->|WebSocket| C(Chrome Extension\nbackground.js)
-    C <-->|CDP| D[Browser Tab\nTarget Context]
+JSON config:
+
+```json
+{
+  "mcpServers": {
+    "ghost-bridge": {
+      "command": "/absolute/path/to/node",
+      "args": ["/absolute/path/to/global/node_modules/ghost-bridge/dist/server.js"]
+    }
+  }
+}
+```
+
+Codex TOML:
+
+```toml
+[mcp_servers.ghost-bridge]
+type = "stdio"
+command = "/absolute/path/to/node"
+args = ["/absolute/path/to/global/node_modules/ghost-bridge/dist/server.js"]
 ```
 
-- **MCP Server**: Spawned by Claude via standard I/O streams. Orchestrates WS connections.
-- **Chrome Extension (MV3)**: Taps into `chrome.debugger` API. Utilizes an Offscreen Document to prevent WS hibernation.
-- **Singleton Design**: If multiple agents spawn servers, the first becomes the master bridge while subsequent instances chain transparently as clients.
+### 2. Load the Extension
+
+1. Open `chrome://extensions`
+2. Enable Developer mode
+3. Click `Load unpacked`
+4. Select `~/.ghost-bridge/extension`
 
----
+You can also run:
+
+```bash
+ghost-bridge extension --open
+```
 
-## ⚠️ Known Limitations
+### 3. Connect
 
-- **Service Workers Suspending**: MV3 background workers may suspend. We've built robust auto-reconnection logic, but prolonged inactivity might require re-toggling.
-- **DevTools Conflict**: If you manually open Chrome DevTools (F12) on the target tab, `chrome.debugger.attach` may be rejected.
-- **Beautify Overhead**: Beautifying massive single-line bundles is expensive; the server will auto-truncate overly large scripts.
-- **Cross-Origin OOPIF**: Elements and errors deeply embedded in strict Cross-Origin Iframes might evade the primary debugger hook without further multi-target attach logic.
+1. Click the Ghost Bridge extension icon
+2. Click `Connect`
+3. Wait until the status becomes `ON`
+4. Open your MCP client and start working on the current page
 
----
+Typical prompts:
+
+- `Analyze the current page`
+- `Check why this layout is broken`
+- `Inspect the DOM structure`
+- `Click the login button and submit the form`
+
+## Tools
+
+| Tool | Purpose |
+|------|---------|
+| `inspect_page` | Default entry point for page analysis |
+| `capture_screenshot` | Visual inspection and UI debugging |
+| `get_page_content` | Text, HTML, and structured DOM extraction |
+| `get_interactive_snapshot` | Find clickable and editable elements |
+| `dispatch_action` | Click, fill, press, scroll, hover, select |
+| `list_network_requests` | Inspect captured network traffic |
+| `get_network_detail` | Read one request in detail |
+| `get_last_error` | Inspect recent errors and exceptions |
+| `get_script_source` | Extract page scripts |
+| `find_by_string` | Search within bundled script content |
+| `coverage_snapshot` | Identify active scripts quickly |
+| `perf_metrics` | Collect Web Vitals and engine metrics |
+
+Recommended flow:
+
+1. Start with `inspect_page`
+2. Use `capture_screenshot` for visual issues
+   Default is optimized for transfer with JPEG; switch to `png` for pixel-level checks
+3. Use `get_page_content` for DOM or text extraction
+4. Use `get_interactive_snapshot` before `dispatch_action`
+
+## Configuration
+
+| Setting | Default | Notes |
+|---------|---------|-------|
+| Port | `33333` | Set `GHOST_BRIDGE_PORT` to override |
+| Token | Monthly UUID | Set `GHOST_BRIDGE_TOKEN` to override |
+| Auto detach | `false` | Keeps debugger attached for ongoing capture |
+
+## Architecture
+
+```mermaid
+flowchart LR
+    A["AI Client<br/>Claude / Codex / Cursor"]
+    B["Ghost Bridge MCP Server<br/>server.js"]
+    C["Chrome Extension<br/>background.js"]
+    D["Browser Tab<br/>Target Context"]
+
+    A <-->|"stdio"| B
+    B <-->|"WebSocket"| C
+    C <-->|"CDP"| D
+```
 
-## 🤝 Contributing
+## Limitations
 
-Contributions, issues, and feature requests are welcome! 
-Check out our [Contributing Guide](CONTRIBUTING.md) to get started building tools or improving the bridge.
+- Chrome DevTools on the target tab can conflict with `chrome.debugger.attach`
+- MV3 background lifecycle can still cause reconnect scenarios after long idle periods
+- Very large minified bundles may be truncated during beautify or extraction
+- Deep cross-origin iframe cases are not fully covered yet
 
-## 📄 License
+## License
 
-This project is [MIT](LICENSE) licensed.
+[MIT](LICENSE)

package/dist/server.js

@@ -28536,7 +28536,6 @@ var GHOST_BRIDGE_VERSION = packageJson.version;
 
 // src/server.js
 var BASE_PORT = Number(process.env.GHOST_BRIDGE_PORT || 33333);
-var MAX_PORT_RETRIES = 10;
 function getMonthlyToken() {
   const now = /* @__PURE__ */ new Date();
   const firstDayOfMonth = new Date(now.getFullYear(), now.getMonth(), 1, 0, 0, 0, 0);
@@ -28567,6 +28566,10 @@ function getExistingService() {
     if (!fs2.existsSync(PORT_INFO_FILE)) return null;
     const info = JSON.parse(fs2.readFileSync(PORT_INFO_FILE, "utf-8"));
     if (!info.pid || !info.port) return null;
+    if (info.port !== BASE_PORT) {
+      fs2.unlinkSync(PORT_INFO_FILE);
+      return null;
+    }
     if (!isProcessRunning(info.pid)) {
       log(`\u65E7\u670D\u52A1 PID ${info.pid} \u5DF2\u4E0D\u5B58\u5728\uFF0C\u6E05\u7406\u65E7\u4FE1\u606F`);
       fs2.unlinkSync(PORT_INFO_FILE);
@@ -28618,22 +28621,14 @@ function isPortAvailable(port) {
   });
 }
 async function startWebSocketServer() {
-  for (let i = 0; i < MAX_PORT_RETRIES; i++) {
-    const port = BASE_PORT + i;
-    const available = await isPortAvailable(port);
-    if (available) {
-      actualPort = port;
-      const wss2 = new import_websocket_server.default({ port });
-      if (port !== BASE_PORT) {
-        log(`\u26A0\uFE0F \u7AEF\u53E3 ${BASE_PORT} \u88AB\u5360\u7528\uFF0C\u5DF2\u5207\u6362\u5230\u7AEF\u53E3 ${port}`);
-      }
-      log(`\u{1F680} WebSocket \u670D\u52A1\u5DF2\u542F\u52A8\uFF0C\u7AEF\u53E3 ${port}${WS_TOKEN ? "\uFF08\u542F\u7528 token \u6821\u9A8C\uFF09" : ""}`);
-      return wss2;
-    } else {
-      log(`\u7AEF\u53E3 ${port} \u88AB\u5360\u7528\uFF0C\u5C1D\u8BD5\u4E0B\u4E00\u4E2A...`);
-    }
+  const available = await isPortAvailable(BASE_PORT);
+  if (!available) {
+    throw new Error(`\u56FA\u5B9A\u7AEF\u53E3 ${BASE_PORT} \u4E0D\u53EF\u7528\uFF0C\u8BF7\u91CA\u653E\u8BE5\u7AEF\u53E3\u6216\u901A\u8FC7 GHOST_BRIDGE_PORT \u6307\u5B9A\u5176\u4ED6\u7AEF\u53E3`);
   }
-  throw new Error(`\u65E0\u6CD5\u627E\u5230\u53EF\u7528\u7AEF\u53E3\uFF08\u5DF2\u5C1D\u8BD5 ${BASE_PORT} - ${BASE_PORT + MAX_PORT_RETRIES - 1}\uFF09`);
+  actualPort = BASE_PORT;
+  const wss2 = new import_websocket_server.default({ port: BASE_PORT });
+  log(`\u{1F680} WebSocket \u670D\u52A1\u5DF2\u542F\u52A8\uFF0C\u7AEF\u53E3 ${BASE_PORT}${WS_TOKEN ? "\uFF08\u542F\u7528 token \u6821\u9A8C\uFF09" : ""}`);
+  return wss2;
 }
 async function initWebSocketService() {
   const existing = getExistingService();
@@ -28653,6 +28648,16 @@ async function initWebSocketService() {
       }
     }
   }
+  if (!await isPortAvailable(BASE_PORT)) {
+    const valid = await verifyExistingService(BASE_PORT);
+    if (valid) {
+      actualPort = BASE_PORT;
+      isMainInstance = false;
+      log(`\u2705 \u590D\u7528\u56FA\u5B9A\u7AEF\u53E3\u4E0A\u7684\u73B0\u6709\u670D\u52A1\uFF0C\u7AEF\u53E3 ${actualPort}`);
+      return null;
+    }
+    throw new Error(`\u56FA\u5B9A\u7AEF\u53E3 ${BASE_PORT} \u5DF2\u88AB\u5176\u4ED6\u8FDB\u7A0B\u5360\u7528\uFF0C\u8BF7\u91CA\u653E\u8BE5\u7AEF\u53E3\u6216\u901A\u8FC7 GHOST_BRIDGE_PORT \u6307\u5B9A\u5176\u4ED6\u7AEF\u53E3`);
+  }
   const wss2 = await startWebSocketServer();
   isMainInstance = true;
   fs2.writeFileSync(
@@ -28808,9 +28813,18 @@ function connectToMainInstance() {
   });
 }
 function failAllPending(message) {
-  pendingRequests.forEach(({ reject, timer }) => {
-    clearTimeout(timer);
-    reject(new Error(message));
+  pendingRequests.forEach((pending, id) => {
+    if (pending.reject) {
+      clearTimeout(pending.timer);
+      pending.reject(new Error(message));
+    } else if (pending.source) {
+      try {
+        if (pending.source.readyState === import_websocket.default.OPEN) {
+          pending.source.send(JSON.stringify({ id, error: message }));
+        }
+      } catch {
+      }
+    }
   });
   pendingRequests.clear();
 }
@@ -29063,18 +29077,18 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: "capture_screenshot",
-      description: "\u3010\u63A8\u8350\u7528\u4E8E\u89C6\u89C9\u5206\u6790\u3011\u622A\u53D6\u5F53\u524D\u9875\u9762\u7684\u622A\u56FE\uFF0C\u8FD4\u56DE base64 \u56FE\u7247\u3002\u9002\u7528\u4E8E\uFF1A1) \u67E5\u770B\u9875\u9762\u5B9E\u9645\u89C6\u89C9\u6548\u679C 2) \u6392\u67E5 UI/\u6837\u5F0F/\u5E03\u5C40/\u989C\u8272\u95EE\u9898 3) \u9A8C\u8BC1\u9875\u9762\u6E32\u67D3 4) \u5206\u6790\u5143\u7D20\u4F4D\u7F6E\u548C\u95F4\u8DDD 5) \u67E5\u770B\u56FE\u7247/\u56FE\u6807\u7B49\u89C6\u89C9\u5185\u5BB9\u3002\u5F53\u7528\u6237\u8BF4\u201C\u770B\u770B\u8FD9\u4E2A\u9875\u9762\u957F\u4EC0\u4E48\u6837\u201D\u201C\u5E2E\u6211\u5206\u6790\u754C\u9762/\u5E03\u5C40/\u6837\u5F0F\u201D\u65F6\uFF0C\u5E94\u4F18\u5148\u4F7F\u7528\u6B64\u5DE5\u5177\uFF0C\u65E0\u9700\u7528\u6237\u663E\u5F0F\u63D0\u5230 ghost-bridge\u3002\u5F53\u9700\u8981\u770B\u5230\u9875\u9762\u300C\u957F\u4EC0\u4E48\u6837\u300D\u65F6\u4F7F\u7528\u6B64\u5DE5\u5177\u3002\u5982\u4EC5\u9700\u6587\u672C/\u94FE\u63A5\u7B49\u4FE1\u606F\uFF0C\u5EFA\u8BAE\u4F7F\u7528\u66F4\u5FEB\u7684 get_page_content\u3002",
+      description: "\u3010\u63A8\u8350\u7528\u4E8E\u89C6\u89C9\u5206\u6790\u3011\u622A\u53D6\u5F53\u524D\u9875\u9762\u7684\u622A\u56FE\uFF0C\u8FD4\u56DE base64 \u56FE\u7247\u3002\u9002\u7528\u4E8E\uFF1A1) \u67E5\u770B\u9875\u9762\u5B9E\u9645\u89C6\u89C9\u6548\u679C 2) \u6392\u67E5 UI/\u6837\u5F0F/\u5E03\u5C40/\u989C\u8272\u95EE\u9898 3) \u9A8C\u8BC1\u9875\u9762\u6E32\u67D3 4) \u5206\u6790\u5143\u7D20\u4F4D\u7F6E\u548C\u95F4\u8DDD 5) \u67E5\u770B\u56FE\u7247/\u56FE\u6807\u7B49\u89C6\u89C9\u5185\u5BB9\u3002\u5F53\u7528\u6237\u8BF4\u201C\u770B\u770B\u8FD9\u4E2A\u9875\u9762\u957F\u4EC0\u4E48\u6837\u201D\u201C\u5E2E\u6211\u5206\u6790\u754C\u9762/\u5E03\u5C40/\u6837\u5F0F\u201D\u65F6\uFF0C\u5E94\u4F18\u5148\u4F7F\u7528\u6B64\u5DE5\u5177\uFF0C\u65E0\u9700\u7528\u6237\u663E\u5F0F\u63D0\u5230 ghost-bridge\u3002\u5F53\u9700\u8981\u770B\u5230\u9875\u9762\u300C\u957F\u4EC0\u4E48\u6837\u300D\u65F6\u4F7F\u7528\u6B64\u5DE5\u5177\u3002\u9ED8\u8BA4\u4F18\u5148\u4F7F\u7528\u66F4\u7701\u4F20\u8F93\u7684 JPEG\uFF1A\u666E\u901A\u622A\u56FE\u9ED8\u8BA4 quality 80\uFF0C\u5B8C\u6574\u957F\u622A\u56FE\u9ED8\u8BA4 quality 70\u3002\u5F53\u9700\u8981\u68C0\u67E5\u6587\u5B57\u6E05\u6670\u5EA6\u30011px \u7EC6\u7EBF\u3001\u56FE\u6807\u8FB9\u7F18\u3001\u900F\u660E\u80CC\u666F\u6216\u50CF\u7D20\u7EA7\u7EC6\u8282\u65F6\uFF0C\u5E94\u4F18\u5148\u4F7F\u7528 PNG\u3002\u5982\u4EC5\u9700\u6587\u672C/\u94FE\u63A5\u7B49\u4FE1\u606F\uFF0C\u5EFA\u8BAE\u4F7F\u7528\u66F4\u5FEB\u7684 get_page_content\u3002",
       inputSchema: {
         type: "object",
         properties: {
           format: {
             type: "string",
             enum: ["png", "jpeg"],
-            description: "\u56FE\u7247\u683C\u5F0F\uFF0C\u9ED8\u8BA4 png\uFF08\u65E0\u635F\uFF09\uFF0Cjpeg \u66F4\u5C0F"
+            description: "\u56FE\u7247\u683C\u5F0F\u3002\u9ED8\u8BA4\u4F7F\u7528 jpeg\uFF1B\u9700\u8981\u9AD8\u4FDD\u771F\u6587\u5B57\u3001\u7EC6\u7EBF\u3001\u900F\u660E\u80CC\u666F\u65F6\u7528 png"
           },
           quality: {
             type: "number",
-            description: "JPEG \u8D28\u91CF (0-100)\uFF0C\u4EC5\u5F53 format \u4E3A jpeg \u65F6\u6709\u6548\uFF0C\u5EFA\u8BAE 80"
+            description: "JPEG \u8D28\u91CF (0-100)\uFF0C\u4EC5\u5F53 format \u4E3A jpeg \u65F6\u6709\u6548\u3002\u9ED8\u8BA4\u666E\u901A\u622A\u56FE 80\uFF0C\u5B8C\u6574\u957F\u622A\u56FE 70"
           },
           fullPage: {
             type: "boolean",
@@ -29187,20 +29201,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   try {
     if (name === "inspect_page") {
       const { selector, includeInteractive = true, maxElements = 30 } = args;
-      const page = await askChrome("getPageContent", {
-        mode: "structured",
+      const snapshot = await askChrome("inspectPageSnapshot", {
         selector,
-        maxLength: 2e4,
-        includeMetadata: true
+        includeInteractive,
+        maxElements
       });
-      let interactive = null;
-      if (includeInteractive) {
-        interactive = await askChrome("getInteractiveSnapshot", {
-          selector,
-          includeText: true,
-          maxElements
-        });
-      }
+      const page = snapshot?.page;
+      const interactive = snapshot?.interactive ?? null;
       const links = page?.counts?.links;
       const buttons = page?.counts?.buttons;
       const forms = page?.counts?.forms;
@@ -29352,6 +29359,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       }
       const metadata = {
         format: res.format,
+        ...res.quality !== void 0 ? { quality: res.quality } : {},
         fullPage: res.fullPage,
         width: res.width,
         height: res.height,

package/extension/background.js

@@ -7,7 +7,6 @@ function getMonthlyToken() {
 
 const CONFIG = {
   basePort: 33333,
-  maxPortRetries: 10,
   token: getMonthlyToken(),
   autoDetach: false,
   maxErrors: 100,
@@ -23,7 +22,7 @@ let lastErrors = []
 let lastErrorLocation = null
 let requestMap = new Map()
 let networkRequests = []
-let state = { enabled: false, connected: false, port: null, currentPort: null, scanRound: 0 }
+let state = { enabled: false, connected: false, port: null, currentPort: null, connectionStatus: 'disconnected', connectionError: '' }
 
 // 待处理的请求（等待 offscreen 响应）
 const pendingRequests = new Map()
@@ -399,46 +398,57 @@ function compactStack(stackTrace) {
 
 // ========== Debugger 操作 ==========
 
+// attach 互斥锁：防止并发调用 ensureAttached 导致重复 attach / 状态竞态
+let _attachLock = Promise.resolve()
+
 async function ensureAttached() {
-  if (!state.enabled) throw new Error("扩展已暂停，点击图标开启后再试")
-  const [tab] = await chrome.tabs.query({ active: true, lastFocusedWindow: true })
-  if (!tab) throw new Error("没有激活的标签页")
-  if (attachedTabId !== tab.id) {
-    if (attachedTabId) {
-      try { await chrome.debugger.detach({ tabId: attachedTabId }) } catch (e) {}
-    }
-    try {
-      await chrome.debugger.attach({ tabId: tab.id }, "1.3")
-      setBadgeState("on")
-    } catch (e) {
-      attachedTabId = null
-      if (state.connected) {
+  let _release
+  const _prev = _attachLock
+  _attachLock = new Promise(r => _release = r)
+  await _prev
+  try {
+    if (!state.enabled) throw new Error("扩展已暂停，点击图标开启后再试")
+    const [tab] = await chrome.tabs.query({ active: true, lastFocusedWindow: true })
+    if (!tab) throw new Error("没有激活的标签页")
+    if (attachedTabId !== tab.id) {
+      if (attachedTabId) {
+        try { await chrome.debugger.detach({ tabId: attachedTabId }) } catch (e) {}
+      }
+      try {
+        await chrome.debugger.attach({ tabId: tab.id }, "1.3")
         setBadgeState("on")
-      } else {
-        setBadgeState("att")
+      } catch (e) {
+        attachedTabId = null
+        if (state.connected) {
+          setBadgeState("on")
+        } else {
+          setBadgeState("att")
+        }
+        throw e
       }
-      throw e
+      attachedTabId = tab.id
+      scriptMap = new Map()
+      scriptSourceCache = new Map()
+      networkRequests = []
+      requestMap = new Map()
+      await chrome.debugger.sendCommand({ tabId: attachedTabId }, "Runtime.enable")
+      await chrome.debugger.sendCommand({ tabId: attachedTabId }, "Log.enable")
+      await chrome.debugger.sendCommand({ tabId: attachedTabId }, "Console.enable").catch(() => {})
+      await chrome.debugger.sendCommand({ tabId: attachedTabId }, "Debugger.enable")
+      await chrome.debugger.sendCommand({ tabId: attachedTabId }, "Profiler.enable")
+      await chrome.debugger.sendCommand({ tabId: attachedTabId }, "Network.enable").catch(() => {})
+
+      // Enable auto-attach to sub-targets (iframes, workers) for comprehensive capture
+      await chrome.debugger.sendCommand({ tabId: attachedTabId }, "Target.setAutoAttach", {
+        autoAttach: true,
+        waitForDebuggerOnStart: false,
+        flatten: true,
+      }).catch(() => {})
     }
-    attachedTabId = tab.id
-    scriptMap = new Map()
-    scriptSourceCache = new Map()
-    networkRequests = []
-    requestMap = new Map()
-    await chrome.debugger.sendCommand({ tabId: attachedTabId }, "Runtime.enable")
-    await chrome.debugger.sendCommand({ tabId: attachedTabId }, "Log.enable")
-    await chrome.debugger.sendCommand({ tabId: attachedTabId }, "Console.enable").catch(() => {})
-    await chrome.debugger.sendCommand({ tabId: attachedTabId }, "Debugger.enable")
-    await chrome.debugger.sendCommand({ tabId: attachedTabId }, "Profiler.enable")
-    await chrome.debugger.sendCommand({ tabId: attachedTabId }, "Network.enable").catch(() => {})
-    
-    // Enable auto-attach to sub-targets (iframes, workers) for comprehensive capture
-    await chrome.debugger.sendCommand({ tabId: attachedTabId }, "Target.setAutoAttach", {
-      autoAttach: true,
-      waitForDebuggerOnStart: false,
-      flatten: true,
-    }).catch(() => {})
+    return { tabId: attachedTabId }
+  } finally {
+    _release()
   }
-  return { tabId: attachedTabId }
 }
 
 async function maybeDetach(force = false) {
@@ -880,13 +890,17 @@ function roundMs(seconds) {
 
 async function handleCaptureScreenshot(params = {}) {
   const target = await ensureAttached()
-  const { format = 'png', quality, fullPage = false, clip } = params
+  const { format: requestedFormat, quality: requestedQuality, fullPage = false, clip } = params
+  const format = requestedFormat || 'jpeg'
+  const quality = format === 'jpeg'
+    ? (requestedQuality ?? (fullPage ? 70 : 80))
+    : undefined
 
   await chrome.debugger.sendCommand(target, 'Page.enable')
 
   let captureParams = {
     format,
-    ...(quality !== undefined && format === 'jpeg' ? { quality } : {}),
+    ...(format === 'jpeg' ? { quality } : {}),
   }
 
   if (clip) {
@@ -928,7 +942,7 @@ async function handleCaptureScreenshot(params = {}) {
         }
         await chrome.debugger.sendCommand(target, 'Emulation.clearDeviceMetricsOverride').catch(() => {})
         return {
-          imageData: data, format, fullPage: true, width: maxWidth, height: maxHeight,
+          imageData: data, format, quality, fullPage: true, width: maxWidth, height: maxHeight,
           note: pageSize.height > maxHeight ? `页面高度 ${pageSize.height}px 超过限制，已截取前 ${maxHeight}px` : undefined,
         }
       } catch (e) {
@@ -944,7 +958,207 @@ async function handleCaptureScreenshot(params = {}) {
     returnByValue: true,
   })
 
-  return { imageData: data, format, fullPage: false, width: sizeResult?.value?.width, height: sizeResult?.value?.height }
+  return {
+    imageData: data,
+    format,
+    quality,
+    fullPage: false,
+    width: sizeResult?.value?.width,
+    height: sizeResult?.value?.height
+  }
+}
+
+async function handleInspectPageSnapshot(params = {}) {
+  const target = await ensureAttached()
+  const { selector, includeInteractive = true, maxElements = 30 } = params
+
+  const selectorStr = selector ? JSON.stringify(selector) : 'null'
+
+  const expression = `(function() {
+    try {
+      if (document.readyState === 'loading') {
+        return { error: '页面尚未加载完成，请稍后重试', readyState: document.readyState };
+      }
+
+      const includeInteractive = ${includeInteractive};
+      const maxEls = ${maxElements};
+      const selector = ${selectorStr};
+      const result = {};
+      let targetElement = document.body;
+
+      if (selector) {
+        try {
+          targetElement = document.querySelector(selector);
+          if (!targetElement) {
+            return { error: '选择器未匹配到任何元素', selector: selector, suggestion: '请检查选择器是否正确' };
+          }
+          result.selector = selector;
+          result.matchedTag = targetElement.tagName.toLowerCase();
+        } catch (e) {
+          return { error: '无效的 CSS 选择器: ' + e.message, selector: selector };
+        }
+      }
+
+      result.metadata = {
+        title: document.title || '',
+        url: window.location.href,
+        description: document.querySelector('meta[name="description"]')?.content || '',
+        keywords: document.querySelector('meta[name="keywords"]')?.content || '',
+        charset: document.characterSet,
+        language: document.documentElement.lang || '',
+      };
+
+      const structured = {};
+      const headings = targetElement.querySelectorAll('h1,h2,h3,h4,h5,h6');
+      structured.headings = Array.from(headings).slice(0, 50).map(h => ({
+        level: parseInt(h.tagName[1]),
+        text: h.innerText.trim().slice(0, 200)
+      }));
+      const links = targetElement.querySelectorAll('a[href]');
+      structured.links = Array.from(links).slice(0, 100).map(a => ({
+        text: (a.innerText || '').trim().slice(0, 100),
+        href: a.href
+      })).filter(l => l.href && !l.href.startsWith('javascript:'));
+      const buttons = targetElement.querySelectorAll('button, input[type="button"], input[type="submit"], [role="button"]');
+      structured.buttons = Array.from(buttons).slice(0, 50).map(b => ({
+        text: (b.innerText || b.value || b.getAttribute('aria-label') || '').trim().slice(0, 100),
+        type: b.type || 'button',
+        disabled: b.disabled || false
+      }));
+      const forms = targetElement.querySelectorAll('form');
+      structured.forms = Array.from(forms).slice(0, 20).map(f => {
+        const fields = Array.from(f.querySelectorAll('input, select, textarea')).slice(0, 30);
+        return {
+          action: f.action || '',
+          method: (f.method || 'GET').toUpperCase(),
+          fieldCount: fields.length,
+          fields: fields.map(field => ({
+            tag: field.tagName.toLowerCase(),
+            type: field.type || '',
+            name: field.name || '',
+            placeholder: field.placeholder || '',
+            required: field.required || false
+          }))
+        };
+      });
+      const images = targetElement.querySelectorAll('img');
+      structured.images = Array.from(images).slice(0, 50).map(img => ({
+        alt: img.alt || '',
+        src: img.src ? img.src.slice(0, 200) : ''
+      })).filter(img => img.src);
+      const tables = targetElement.querySelectorAll('table');
+      structured.tables = Array.from(tables).slice(0, 10).map(table => {
+        const headers = Array.from(table.querySelectorAll('th')).map(th => th.innerText.trim().slice(0, 50));
+        const rows = table.querySelectorAll('tr');
+        return { headers: headers.slice(0, 20), rowCount: rows.length };
+      });
+
+      result.page = {
+        metadata: result.metadata,
+        ...(result.selector ? { selector: result.selector, matchedTag: result.matchedTag } : {}),
+        structured,
+        counts: {
+          headings: structured.headings.length,
+          links: structured.links.length,
+          buttons: structured.buttons.length,
+          forms: structured.forms.length,
+          images: structured.images.length,
+          tables: structured.tables.length
+        },
+        mode: 'structured'
+      };
+
+      if (!includeInteractive) {
+        result.interactive = null;
+        return result;
+      }
+
+      let refCounter = 0;
+      const elements = [];
+      const INTERACTIVE_SELECTOR = 'a,button,input,select,textarea,[role="button"],[role="link"],[role="tab"],[role="menuitem"],[role="checkbox"],[role="radio"],[role="switch"],[role="combobox"],[tabindex]:not([tabindex="-1"]),[contenteditable="true"],[onclick]';
+
+      function isVisible(el) {
+        const style = window.getComputedStyle(el);
+        if (style.display === 'none' || style.visibility === 'hidden' || parseFloat(style.opacity) === 0) return null;
+        if (!el.offsetParent && el.tagName !== 'HTML' && el.tagName !== 'BODY' &&
+            style.position !== 'fixed' && style.position !== 'sticky') return null;
+        const rect = el.getBoundingClientRect();
+        if (rect.width === 0 && rect.height === 0) return null;
+        return rect;
+      }
+
+      function buildEntry(el, rect) {
+        refCounter++;
+        const ref = 'e' + refCounter;
+        el.setAttribute('data-ghost-ref', ref);
+        const tag = el.tagName.toLowerCase();
+        const entry = { ref, 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 (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) + '...';
+        if (el.disabled) entry.disabled = true;
+        return entry;
+      }
+
+      function scanRoot(root) {
+        const candidates = root.querySelectorAll(INTERACTIVE_SELECTOR);
+        for (let i = 0; i < candidates.length && elements.length < maxEls; i++) {
+          const rect = isVisible(candidates[i]);
+          if (rect) elements.push(buildEntry(candidates[i], rect));
+        }
+        if (elements.length < maxEls) {
+          const all = root.querySelectorAll('*');
+          for (let i = 0; i < all.length && elements.length < maxEls; i++) {
+            const el = all[i];
+            if (el.shadowRoot) scanRoot(el.shadowRoot);
+            if (el.onclick && !el.hasAttribute('data-ghost-ref')) {
+              const rect = isVisible(el);
+              if (rect) elements.push(buildEntry(el, rect));
+            }
+          }
+        }
+      }
+
+      document.querySelectorAll('[data-ghost-ref]').forEach(el => el.removeAttribute('data-ghost-ref'));
+      scanRoot(targetElement);
+
+      result.interactive = {
+        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
+      };
+
+      return result;
+    } 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
 }
 
 async function handleGetPageContent(params = {}) {
@@ -1062,78 +1276,65 @@ async function handleGetInteractiveSnapshot(params = {}) {
       let refCounter = 0;
       const elements = [];
 
-      // 判断元素是否可见
+      const maxEls = ${maxElements};
+      // 候选集选择器——用浏览器原生选择器引擎代替全树 JS 递归
+      const INTERACTIVE_SELECTOR = 'a,button,input,select,textarea,[role="button"],[role="link"],[role="tab"],[role="menuitem"],[role="checkbox"],[role="radio"],[role="switch"],[role="combobox"],[tabindex]:not([tabindex="-1"]),[contenteditable="true"],[onclick]';
+
+      // 可见性检测（单次 getComputedStyle，返回 rect 复用）
       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;
+        if (style.display === 'none' || style.visibility === 'hidden' || parseFloat(style.opacity) === 0) return null;
+        if (!el.offsetParent && el.tagName !== 'HTML' && el.tagName !== 'BODY' &&
+            style.position !== 'fixed' && style.position !== 'sticky') return null;
         const rect = el.getBoundingClientRect();
-        if (rect.width === 0 && rect.height === 0) return false;
-        return true;
+        if (rect.width === 0 && rect.height === 0) return null;
+        return rect;
       }
 
-      // 判断元素是否可交互
-      function isInteractive(el) {
+      function buildEntry(el, rect) {
+        refCounter++;
+        const ref = 'e' + refCounter;
+        el.setAttribute('data-ghost-ref', ref);
         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;
+        const entry = { ref, 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) + '...';
+        }
+        if (el.disabled) entry.disabled = true;
+        return entry;
       }
 
-      // 递归遍历 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) + '...';
+      // 候选集扫描（含 Shadow DOM 穿透）
+      function scanRoot(root) {
+        const candidates = root.querySelectorAll(INTERACTIVE_SELECTOR);
+        for (let i = 0; i < candidates.length && elements.length < maxEls; i++) {
+          const rect = isVisible(candidates[i]);
+          if (rect) elements.push(buildEntry(candidates[i], rect));
+        }
+        // 穿透 Shadow DOM + 兜底检测 el.onclick = fn 形式的 JS 属性绑定
+        if (elements.length < maxEls) {
+          const all = root.querySelectorAll('*');
+          for (let i = 0; i < all.length && elements.length < maxEls; i++) {
+            const el = all[i];
+            if (el.shadowRoot) scanRoot(el.shadowRoot);
+            // CSS 选择器只能匹配 [onclick] 属性，这里兜住 el.onclick = fn 的情况
+            if (el.onclick && !el.hasAttribute('data-ghost-ref')) {
+              const rect = isVisible(el);
+              if (rect) elements.push(buildEntry(el, rect));
             }
-            // disabled 状态
-            if (el.disabled) entry.disabled = true;
-            elements.push(entry);
-          }
-          // 递归子节点
-          walkDOM(el, root);
-          // 穿透 Shadow DOM
-          if (el.shadowRoot) {
-            walkDOM(el.shadowRoot, root);
           }
         }
       }
@@ -1141,7 +1342,6 @@ async function handleGetInteractiveSnapshot(params = {}) {
       // 清理旧的 ref 标记
       document.querySelectorAll('[data-ghost-ref]').forEach(el => el.removeAttribute('data-ghost-ref'));
 
-      // 确定扫描根节点
       let rootEl = document.body;
       const sel = ${selectorStr};
       if (sel) {
@@ -1149,7 +1349,7 @@ async function handleGetInteractiveSnapshot(params = {}) {
         if (!rootEl) return { error: '选择器未匹配到任何元素', selector: sel };
       }
 
-      walkDOM(rootEl, rootEl);
+      scanRoot(rootEl);
 
       return {
         url: window.location.href,
@@ -1369,6 +1569,7 @@ async function handleCommand(message) {
     else if (command === "clearNetworkRequests") result = await handleClearNetworkRequests()
     else if (command === "perfMetrics") result = await handlePerfMetrics(params)
     else if (command === "captureScreenshot") result = await handleCaptureScreenshot(params)
+    else if (command === "inspectPageSnapshot") result = await handleInspectPageSnapshot(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)
@@ -1396,10 +1597,8 @@ function broadcastStatus() {
     status = 'disconnected'
   } else if (state.connected) {
     status = 'connected'
-  } else if (state.scanRound >= 4) {
-    status = 'not_found'
   } else {
-    status = 'scanning'
+    status = state.connectionStatus || 'connecting'
   }
 
   let tabUrl = ''
@@ -1425,7 +1624,7 @@ function broadcastStatus() {
         port: state.port,
         currentPort: state.currentPort,
         basePort: CONFIG.basePort,
-        scanRound: state.scanRound,
+        connectionError: state.connectionError,
         errorCount: actualErrors.length,
         recentErrors: actualErrors.slice(0, 5),
         tabTitle,
@@ -1474,18 +1673,32 @@ chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
     if (message.status === 'connected') {
       state.connected = true
       state.port = message.port
+      state.currentPort = message.port
+      state.connectionStatus = 'connected'
+      state.connectionError = ''
       setBadgeState('on')
       log(`✅ 已连接到 ghost-bridge 服务 (端口 ${message.port})`)
       ensureAttached().catch((e) => log(`attach 失败：${e.message}`))
     } else if (message.status === 'disconnected') {
       state.connected = false
       state.port = null
+      state.connectionStatus = 'connecting'
+      state.connectionError = ''
       if (state.enabled) setBadgeState('connecting')
-    } else if (message.status === 'scanning') {
+    } else if (message.status === 'connecting') {
       state.currentPort = message.currentPort
+      state.connectionStatus = 'connecting'
+      state.connectionError = ''
       setBadgeState('connecting')
+    } else if (message.status === 'error') {
+      state.currentPort = message.currentPort
+      state.connectionStatus = 'error'
+      state.connectionError = message.errorMessage || ''
+      setBadgeState('err')
     } else if (message.status === 'not_found') {
-      state.scanRound++
+      state.currentPort = message.currentPort
+      state.connectionStatus = 'not_found'
+      state.connectionError = ''
       setBadgeState('connecting')
     }
     broadcastStatus() // 状态变化时主动推送
@@ -1516,10 +1729,8 @@ chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
       status = 'disconnected'
     } else if (state.connected) {
       status = 'connected'
-    } else if (state.scanRound >= 4) {
-      status = 'not_found'
     } else {
-      status = 'scanning'
+      status = state.connectionStatus || 'connecting'
     }
 
     let tabUrl = ''
@@ -1544,7 +1755,7 @@ chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
         port: state.port,
         currentPort: state.currentPort,
         basePort: CONFIG.basePort,
-        scanRound: state.scanRound,
+        connectionError: state.connectionError,
         errorCount: actualErrors.length,
         recentErrors: actualErrors.slice(0, 5),
         tabTitle,
@@ -1561,7 +1772,11 @@ chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
       chrome.storage.local.set({ basePort: message.port })
     }
     state.enabled = true
-    state.scanRound = 0
+    state.connected = false
+    state.port = null
+    state.currentPort = CONFIG.basePort
+    state.connectionStatus = 'connecting'
+    state.connectionError = ''
     setBadgeState('connecting')
 
     // 启动 offscreen 并开始连接
@@ -1570,7 +1785,6 @@ chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
         type: 'connect',
         basePort: CONFIG.basePort,
         token: CONFIG.token,
-        maxPortRetries: CONFIG.maxPortRetries,
       }).catch(() => {})
     })
 
@@ -1582,7 +1796,10 @@ chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
   if (message.type === 'disconnect') {
     state.enabled = false
     state.connected = false
-    state.scanRound = 0
+    state.port = null
+    state.currentPort = null
+    state.connectionStatus = 'disconnected'
+    state.connectionError = ''
     setBadgeState('off')
     detachAllTargets().catch(() => {})
 

package/extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "Ghost Bridge",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Zero-restart Chrome debugger bridge for Claude MCP, optimized for no-sourcemap production debugging.",
   "permissions": [
     "debugger",

package/extension/offscreen.js

@@ -7,7 +7,6 @@ let manualDisconnect = false  // 用户主动断开标志，防止 onclose 触
 let config = {
   basePort: 33333,
   token: '',
-  maxPortRetries: 10,
 }
 
 function log(msg) {
@@ -23,29 +22,17 @@ function getMonthlyToken() {
 }
 
 // 连接到服务器
-function connect(portIndex = 0, isNewRound = false) {
+function connect() {
   // 如果已手动断开，不再尝试连接
   if (manualDisconnect) return
 
-  if (portIndex >= config.maxPortRetries) {
-    log(`扫描完毕，未找到服务，2秒后重试...`)
-    reconnectTimer = setTimeout(() => connect(0, true), 2000)
-    chrome.runtime.sendMessage({ type: 'status', status: 'not_found' }).catch(() => {})
-    return
-  }
-
-  const port = config.basePort + portIndex
+  const port = config.basePort
   const url = new URL(`ws://localhost:${port}`)
   url.searchParams.set('token', config.token)
-
-  if (portIndex === 0 && isNewRound) {
-    log(`开始扫描端口 ${config.basePort}-${config.basePort + config.maxPortRetries - 1}`)
-  }
-
-  log(`尝试连接端口 ${port}...`)
+  log(`尝试连接固定端口 ${port}...`)
   chrome.runtime.sendMessage({
     type: 'status',
-    status: 'scanning',
+    status: 'connecting',
     currentPort: port,
   }).catch(() => {})
 
@@ -59,8 +46,11 @@ function connect(portIndex = 0, isNewRound = false) {
   }, 2000) // 增加到 2 秒
 
   let identityVerified = false
+  let socketOpened = false
+  let terminalErrorMessage = ''
 
   ws.onopen = () => {
+    socketOpened = true
     clearTimeout(connectionTimeout)
     log(`WebSocket 已连接端口 ${port}，等待身份验证...`)
   }
@@ -84,9 +74,15 @@ function connect(portIndex = 0, isNewRound = false) {
             port: port,
           }).catch(() => {})
         } else {
-          log(`身份验证失败，尝试下一个端口...`)
+          terminalErrorMessage = `Port ${port} is occupied by a non-matching service, or the token does not match.`
+          log('身份验证失败，将在固定端口上重试...')
+          chrome.runtime.sendMessage({
+            type: 'status',
+            status: 'error',
+            currentPort: port,
+            errorMessage: terminalErrorMessage,
+          }).catch(() => {})
           ws.close()
-          setTimeout(() => connect(portIndex + 1), 50)
         }
         return
       }
@@ -107,15 +103,28 @@ function connect(portIndex = 0, isNewRound = false) {
     if (manualDisconnect) return
 
     if (!identityVerified) {
-      // 连接失败，尝试下一个端口
-      setTimeout(() => connect(portIndex + 1), 50)
+      if (terminalErrorMessage || socketOpened) {
+        const errorMessage = terminalErrorMessage || `Port ${port} is occupied or responding with a non-ghost-bridge protocol.`
+        log(`${errorMessage} 2秒后重试...`)
+        chrome.runtime.sendMessage({
+          type: 'status',
+          status: 'error',
+          currentPort: port,
+          errorMessage,
+        }).catch(() => {})
+        reconnectTimer = setTimeout(() => connect(), 2000)
+        return
+      }
+      log(`固定端口 ${port} 未发现可用服务，2秒后重试...`)
+      chrome.runtime.sendMessage({ type: 'status', status: 'not_found', currentPort: port }).catch(() => {})
+      reconnectTimer = setTimeout(() => connect(), 2000)
       return
     }
 
     // 连接断开，重试
-    log('连接断开，尝试重连...')
+    log(`端口 ${port} 连接断开，尝试重连...`)
     chrome.runtime.sendMessage({ type: 'status', status: 'disconnected' }).catch(() => {})
-    reconnectTimer = setTimeout(() => connect(0, true), 1000)
+    reconnectTimer = setTimeout(() => connect(), 1000)
   }
 
   ws.onerror = () => {
@@ -151,10 +160,9 @@ chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
   if (message.type === 'connect') {
     config.basePort = message.basePort || 33333
     config.token = message.token || getMonthlyToken()
-    config.maxPortRetries = message.maxPortRetries || 10
     disconnect()
     manualDisconnect = false  // 用户重新连接，清除断开标志
-    connect(0, true)
+    connect()
     sendResponse({ ok: true })
     return true
   }

package/extension/popup.html

@@ -121,6 +121,15 @@
     }
     body.connected-state .bg-ripple-2 { animation-delay: 1.25s; }
 
+    .ghost-error .ghost-body { fill: #ef4444; }
+    .ghost-error .ghost-eyes-normal { opacity: 1; }
+
+    body.error-state .bg-ripple {
+      stroke: #ef4444;
+      animation: bg-ripple-scan 1.8s infinite cubic-bezier(0, 0, 0.2, 1);
+    }
+    body.error-state .bg-ripple-2 { animation-delay: 0.9s; }
+
     @keyframes bg-ripple-scan {
       0% { r: 10%; opacity: 0.8; stroke-width: 3; }
       100% { r: 80%; opacity: 0; stroke-width: 0; }

package/extension/popup.js

@@ -53,7 +53,7 @@ const STATUS_MAP = {
 }
 
 function renderUI(state) {
-  const { status, port, scanRound, enabled, currentPort, basePort, errorCount, recentErrors, tabTitle } = state
+  const { status, port, enabled, currentPort, basePort, connectionError, errorCount, recentErrors, tabTitle } = state
   const config = STATUS_MAP[status] || STATUS_MAP.disconnected
 
   // Update classes for color & animations
@@ -66,6 +66,9 @@ function renderUI(state) {
   } else if (config.statusClass === 'connecting') {
     headerGhost.className = 'ghost-wrapper ghost-connecting'
     document.body.className = 'connecting-state'
+  } else if (config.statusClass === 'error') {
+    headerGhost.className = 'ghost-wrapper ghost-error'
+    document.body.className = 'error-state'
   } else {
     headerGhost.className = 'ghost-wrapper ghost-disconnected'
     document.body.className = 'disconnected-state'
@@ -117,8 +120,7 @@ function renderUI(state) {
     
     detailContainer.classList.remove('collapsed')
   } else if ((status === 'connecting' || status === 'verifying' || status === 'scanning') && currentPort) {
-    const roundText = scanRound > 0 ? ` [R${scanRound + 1}]` : ''
-    portVal.textContent = `Scanning: ${currentPort}${roundText}`
+    portVal.textContent = `Connecting: ${currentPort}`
     portVal.className = 'detail-value highlight'
     tabRow.classList.add('hidden')
     errorRow.classList.add('hidden')
@@ -131,6 +133,12 @@ function renderUI(state) {
     tabRow.classList.add('hidden')
     errorRow.classList.add('hidden')
     detailContainer.classList.remove('collapsed')
+  } else if (status === 'error') {
+    portVal.textContent = `Port ${currentPort || basePort || '-'} blocked`
+    portVal.className = 'detail-value warning'
+    tabRow.classList.add('hidden')
+    errorRow.classList.add('hidden')
+    detailContainer.classList.remove('collapsed')
   } else {
     detailContainer.classList.add('collapsed')
   }
@@ -145,8 +153,11 @@ function renderUI(state) {
   }
 
   // Scan info text
-  if ((status === 'connecting' || status === 'scanning') && scanRound > 2) {
-    scanInfo.textContent = `Round ${scanRound}: Is your MCP Server running?`
+  if (status === 'error' && connectionError) {
+    scanInfo.textContent = connectionError
+    scanInfo.classList.remove('collapsed')
+  } else if (status === 'not_found' && basePort) {
+    scanInfo.textContent = `Port ${basePort} unavailable. Is your MCP server running on this port?`
     scanInfo.classList.remove('collapsed')
   } else {
     scanInfo.classList.add('collapsed')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ghost-bridge",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "private": false,
   "type": "module",
   "description": "Ghost Bridge: Zero-restart Chrome debugger bridge for Claude MCP. Includes CLI for easy setup.",
@@ -48,5 +48,8 @@
     "fs-extra": "^11.1.1",
     "js-beautify": "^1.14.11",
     "ws": "^8.14.2"
+  },
+  "dependencies": {
+    "ghost-bridge": "^0.5.2"
   }
 }