qwen-code/packages/chrome-qwen-bridge/docs/api-reference.md

Chrome Qwen Bridge API 参考文档

Chrome Extension APIs

Background Service Worker

消息类型

连接管理

CONNECT

// 请求
{
  type: 'CONNECT'
}

// 响应
{
  success: boolean,
  status?: string,      // 'connected' | 'running' | 'stopped'
  error?: string
}

GET_STATUS

// 请求
{
  type: 'GET_STATUS'
}

// 响应
{
  connected: boolean,
  status: string        // 'disconnected' | 'connecting' | 'connected' | 'running'
}

Qwen CLI 控制

START_QWEN_CLI

// 请求
{
  type: 'START_QWEN_CLI',
  config?: {
    mcpServers?: string[],    // MCP 服务器列表
    httpPort?: number         // HTTP 端口，默认 8080
  }
}

// 响应
{
  success: boolean,
  data?: {
    status: string,
    pid: number,
    port: number
  },
  error?: string
}

STOP_QWEN_CLI

// 请求
{
  type: 'STOP_QWEN_CLI'
}

// 响应
{
  success: boolean,
  data?: string,
  error?: string
}

数据操作

EXTRACT_PAGE_DATA

// 请求
{
  type: 'EXTRACT_PAGE_DATA'
}

// 响应
{
  success: boolean,
  data?: {
    url: string,
    title: string,
    domain: string,
    path: string,
    timestamp: string,
    meta: object,
    content: {
      text: string,
      html: string,
      markdown: string
    },
    links: Array<{
      text: string,
      href: string,
      target: string,
      isExternal: boolean
    }>,
    images: Array<{
      src: string,
      alt: string,
      title: string,
      width: number,
      height: number
    }>,
    forms: Array<{
      action: string,
      method: string,
      fields: Array<object>
    }>,
    consoleLogs: Array<{
      type: string,
      message: string,
      timestamp: string,
      stack: string
    }>,
    performance: {
      loadTime: number,
      domReady: number,
      firstPaint: number
    }
  },
  error?: string
}

CAPTURE_SCREENSHOT

// 请求
{
  type: 'CAPTURE_SCREENSHOT'
}

// 响应
{
  success: boolean,
  data?: string,        // Base64 编码的图片
  error?: string
}

GET_NETWORK_LOGS

// 请求
{
  type: 'GET_NETWORK_LOGS'
}

// 响应
{
  success: boolean,
  data?: Array<{
    method: string,
    params: object,
    timestamp: number
  }>,
  error?: string
}

SEND_TO_QWEN

// 请求
{
  type: 'SEND_TO_QWEN',
  action: string,       // 'analyze_page' | 'analyze_screenshot' | 'ai_analyze' | 'process_text'
  data: any
}

// 响应
{
  success: boolean,
  data?: any,          // Qwen CLI 返回的数据
  error?: string
}

Content Script APIs

消息类型

EXTRACT_DATA

// 请求
{
  type: 'EXTRACT_DATA'
}

// 响应
{
  success: boolean,
  data: {
    // 同 EXTRACT_PAGE_DATA 的 data 字段
  }
}

GET_SELECTED_TEXT

// 请求
{
  type: 'GET_SELECTED_TEXT'
}

// 响应
{
  success: boolean,
  data: string          // 选中的文本
}

HIGHLIGHT_ELEMENT

// 请求
{
  type: 'HIGHLIGHT_ELEMENT',
  selector: string      // CSS 选择器
}

// 响应
{
  success: boolean
}

EXECUTE_CODE

// 请求
{
  type: 'EXECUTE_CODE',
  code: string         // JavaScript 代码
}

// 响应
{
  success: boolean,
  data?: any,          // 执行结果
  error?: string
}

SCROLL_TO

// 请求
{
  type: 'SCROLL_TO',
  x?: number,
  y?: number,
  smooth?: boolean
}

// 响应
{
  success: boolean
}

工具函数

extractPageData()

function extractPageData(): PageData

interface PageData {
  url: string;
  title: string;
  domain: string;
  path: string;
  timestamp: string;
  meta: Record<string, string>;
  content: {
    text: string;
    html: string;
    markdown: string;
  };
  links: Link[];
  images: Image[];
  forms: Form[];
  consoleLogs: ConsoleLog[];
  performance: PerformanceMetrics;
}

extractTextContent(element)

function extractTextContent(element: HTMLElement): string
// 提取元素的纯文本内容，移除脚本和样式

htmlToMarkdown(element)

function htmlToMarkdown(element: HTMLElement): string
// 将 HTML 转换为 Markdown 格式

getSelectedText()

function getSelectedText(): string
// 获取用户选中的文本

highlightElement(selector)

function highlightElement(selector: string): boolean
// 高亮指定的元素，3秒后自动移除

executeInPageContext(code)

async function executeInPageContext(code: string): Promise<any>
// 在页面上下文中执行 JavaScript 代码

Native Host APIs

消息协议

请求消息格式

interface RequestMessage {
  id?: number;          // 请求 ID，用于匹配响应
  type: string;         // 消息类型
  action?: string;      // 具体动作
  data?: any;          // 携带的数据
  config?: object;     // 配置选项
}

响应消息格式

interface ResponseMessage {
  id?: number;          // 对应的请求 ID
  type: 'response' | 'event' | 'handshake_response';
  data?: any;          // 响应数据
  error?: string;      // 错误信息
  success?: boolean;   // 操作是否成功
}

消息类型

handshake

// 请求
{
  type: 'handshake',
  version: string      // 扩展版本
}

// 响应
{
  type: 'handshake_response',
  version: string,
  qwenInstalled: boolean,
  qwenStatus: string,
  capabilities: string[]
}

start_qwen

// 请求
{
  type: 'start_qwen',
  config?: {
    mcpServers?: string[],
    httpPort?: number
  }
}

// 响应
{
  type: 'response',
  id: number,
  success: boolean,
  data?: {
    status: string,
    pid: number,
    capabilities: string[]
  },
  error?: string
}

stop_qwen

// 请求
{
  type: 'stop_qwen'
}

// 响应
{
  type: 'response',
  id: number,
  success: boolean,
  data?: string,
  error?: string
}

qwen_request

// 请求
{
  type: 'qwen_request',
  action: string,
  data: any,
  config?: object
}

// 响应
{
  type: 'response',
  id: number,
  data?: any,
  error?: string
}

get_status

// 请求
{
  type: 'get_status'
}

// 响应
{
  type: 'response',
  id: number,
  data: {
    qwenInstalled: boolean,
    qwenStatus: string,
    qwenPid: number | null,
    capabilities: string[]
  }
}

事件消息

qwen_output

{
  type: 'event',
  data: {
    type: 'qwen_output',
    content: string      // stdout 输出
  }
}

qwen_error

{
  type: 'event',
  data: {
    type: 'qwen_error',
    content: string      // stderr 输出
  }
}

qwen_stopped

{
  type: 'event',
  data: {
    type: 'qwen_stopped',
    code: number         // 退出码
  }
}

Qwen CLI 集成

HTTP API 端点

POST /api/process

// 请求
{
  action: string,
  data: any
}

// 响应
{
  success: boolean,
  result?: any,
  error?: string
}

支持的动作

动作	描述	输入数据	返回数据
analyze_page	分析网页内容	PageData	分析结果
analyze_screenshot	分析截图	{ screenshot: string, url: string }	图片分析结果
ai_analyze	AI 深度分析	{ pageData: PageData, prompt: string }	AI 分析结果
process_text	处理文本	{ text: string, context: string }	处理后的文本

Chrome Storage API

配置存储

// 保存配置
await chrome.storage.local.set({
  mcpServers: 'chrome-devtools,playwright',
  httpPort: 8080,
  autoConnect: true
});

// 读取配置
const settings = await chrome.storage.local.get([
  'mcpServers',
  'httpPort',
  'autoConnect'
]);

存储结构

interface StorageSchema {
  mcpServers?: string;        // 逗号分隔的服务器列表
  httpPort?: number;          // HTTP 端口
  autoConnect?: boolean;      // 是否自动连接
  lastConnected?: string;     // 最后连接时间
  extensionVersion?: string;  // 扩展版本
}

错误代码

错误代码	描述	处理建议
NATIVE_HOST_NOT_FOUND	Native Host 未安装	运行安装脚本
QWEN_NOT_INSTALLED	Qwen CLI 未安装	安装 Qwen CLI
CONNECTION_FAILED	连接失败	检查 Native Host
PROCESS_START_FAILED	进程启动失败	检查 Qwen CLI 配置
REQUEST_TIMEOUT	请求超时	重试请求
INVALID_MESSAGE	消息格式错误	检查消息格式
PERMISSION_DENIED	权限不足	检查扩展权限
PORT_IN_USE	端口被占用	更换端口

使用示例

基本使用流程

// 1. 连接到 Native Host
const connectResponse = await chrome.runtime.sendMessage({
  type: 'CONNECT'
});

if (!connectResponse.success) {
  console.error('连接失败:', connectResponse.error);
  return;
}

// 2. 启动 Qwen CLI
const startResponse = await chrome.runtime.sendMessage({
  type: 'START_QWEN_CLI',
  config: {
    mcpServers: ['chrome-devtools-mcp'],
    httpPort: 8080
  }
});

// 3. 提取页面数据
const pageDataResponse = await chrome.runtime.sendMessage({
  type: 'EXTRACT_PAGE_DATA'
});

// 4. 发送给 Qwen 分析
const analysisResponse = await chrome.runtime.sendMessage({
  type: 'SEND_TO_QWEN',
  action: 'analyze_page',
  data: pageDataResponse.data
});

console.log('分析结果:', analysisResponse.data);

高级功能示例

// 监听 Qwen 事件
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  if (message.type === 'QWEN_EVENT') {
    console.log('Qwen 事件:', message.event);

    switch (message.event.type) {
      case 'qwen_output':
        // 处理输出
        updateUI(message.event.content);
        break;
      case 'qwen_error':
        // 处理错误
        showError(message.event.content);
        break;
      case 'qwen_stopped':
        // 处理停止
        handleStop(message.event.code);
        break;
    }
  }
});

版本兼容性

组件	最低版本	推荐版本
Chrome	88	最新稳定版
Node.js	14.0.0	18+
Qwen CLI	1.0.0	最新版
Manifest	V3	V3

性能指标

操作	预期延迟	超时时间
Native Host 连接	<100ms	5s
Qwen CLI 启动	<2s	10s
页面数据提取	<500ms	5s
截图捕获	<1s	5s
AI 分析请求	<5s	30s
消息往返	<50ms	1s