qwen-code/packages/chrome-qwen-bridge/docs/debugging.md

Chrome Qwen Bridge 调试指南

🚀 快速开始调试

一键启动（推荐）

最简单的方式是使用我们提供的一键启动脚本：

# 进入项目目录
cd packages/chrome-qwen-bridge

# 方式一：使用 npm 脚本（跨平台）
npm run dev

# 方式二：使用 shell 脚本（macOS/Linux）
npm run dev:quick
# 或直接运行
./start.sh

脚本会自动完成以下操作：

1. ✅ 检查并配置 Chrome
2. ✅ 安装 Native Host
3. ✅ 检查 Qwen CLI
4. ✅ 启动 Qwen 服务器（端口 8080）
5. ✅ 启动测试页面服务器（端口 3000）
6. ✅ 启动 Chrome 并加载插件
7. ✅ 自动打开 DevTools

📝 可用的 npm 命令

# 开发调试
npm run dev              # 完整的开发环境启动（Node.js 脚本）
npm run dev:quick        # 快速启动（Shell 脚本）
npm run dev:stop         # 停止所有服务
npm run dev:chrome       # 仅启动 Chrome 加载插件
npm run dev:server       # 仅启动 Qwen 服务器

# 安装配置
npm run install:host           # 安装 Native Host 依赖
npm run install:host:macos     # macOS 安装 Native Host
npm run install:host:windows   # Windows 安装 Native Host

# 构建打包
npm run build            # 构建项目
npm run package          # 打包扩展为 zip
npm run package:source   # 打包源代码

# 日志查看
npm run logs             # 查看 Native Host 日志
npm run logs:qwen        # 查看 Qwen 服务器日志

# 清理
npm run clean            # 清理构建文件和日志

🔧 手动调试步骤

如果自动脚本有问题，可以手动进行调试：

步骤 1：安装 Native Host

# macOS/Linux
cd native-host
./install.sh

# Windows（管理员权限）
cd native-host
install.bat

步骤 2：启动 Qwen 服务器（可选）

# 如果安装了 Qwen CLI
qwen server --port 8080

步骤 3：加载插件到 Chrome

1. 打开 Chrome
2. 访问 chrome://extensions/
3. 开启「开发者模式」
4. 点击「加载已解压的扩展程序」
5. 选择 packages/chrome-qwen-bridge/extension 目录

步骤 4：测试插件

1. 打开任意网页（或访问 http://localhost:3000）
2. 点击工具栏中的插件图标
3. 点击「Connect to Qwen CLI」
4. 测试各项功能

🐛 调试技巧

1. Chrome DevTools

Service Worker (Background Script)

• 打开 chrome://extensions/
• 找到 Qwen CLI Bridge
• 点击「Service Worker」链接
• 在打开的 DevTools 中查看日志

Content Script

• 在任意网页上右键 → 检查
• 在 Console 中查看 content script 的日志
• 使用 Sources 面板设置断点

Popup

• 右键点击插件图标
• 选择「检查弹出内容」
• 在 DevTools 中调试 popup 代码

2. Native Host 调试

查看 Native Host 日志：

# macOS/Linux
tail -f /tmp/qwen-bridge-host.log

# 或使用 npm 命令
npm run logs

测试 Native Host 连接：

// 在 Service Worker console 中执行
chrome.runtime.sendNativeMessage('com.qwen.cli.bridge',
  {type: 'handshake', version: '1.0.0'},
  response => console.log('Native Host response:', response)
);

3. 消息调试

在 Service Worker 中添加日志：

// background/service-worker.js
chrome.runtime.onMessage.addListener((request, sender, sendResponse) => {
  console.log('Message received:', request, 'from:', sender);
  // ...
});

4. 网络请求调试

使用 Chrome DevTools Network 面板：

• 查看与 Qwen 服务器的 HTTP 通信
• 检查请求/响应头和内容
• 查看请求时间

🔍 常见问题排查

问题：Native Host 连接失败

症状：点击「Connect」后显示连接错误

解决方案：

1. 检查 Native Host 是否正确安装：

   # macOS
   ls ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/
   
   # Linux
   ls ~/.config/google-chrome/NativeMessagingHosts/
   

2. 验证 manifest.json 中的路径是否正确

3. 确保 host.js 有执行权限：

   chmod +x native-host/host.js
   

问题：Qwen CLI 未响应

症状：显示 Qwen CLI 未安装或无响应

解决方案：

1. 确认 Qwen CLI 已安装：

   qwen --version
   

2. 手动启动 Qwen 服务器：

   qwen server --port 8080
   

3. 检查端口是否被占用：

   lsof -i:8080
   

问题：插件图标不显示

症状：加载插件后工具栏没有图标

解决方案：

1. 点击 Chrome 扩展图标（拼图图标）
2. 找到「Qwen CLI Bridge」
3. 点击固定图标

问题：Content Script 未注入

症状：提取页面数据失败

解决方案：

1. 刷新目标网页
2. 检查 manifest.json 的 content_scripts 配置
3. 确认网页不是 Chrome 内部页面（chrome://）

📊 性能分析

Memory 分析

1. 打开 Chrome Task Manager（Shift + Esc）
2. 查看扩展的内存使用
3. 使用 DevTools Memory Profiler

Performance 分析

1. 在 DevTools 中打开 Performance 面板
2. 记录操作过程
3. 分析瓶颈

🔄 热重载开发

虽然 Chrome Extension 不支持真正的热重载，但可以：

1. 快速重载扩展：

   • 在 chrome://extensions/ 点击重载按钮
   • 或使用快捷键：Cmd+R (macOS) / Ctrl+R (Windows/Linux)

2. 自动重载 Content Script： 修改代码后刷新网页即可

3. 保持 Qwen 服务器运行： Qwen 服务器不需要重启，只需重载扩展

📱 远程调试

如果需要在其他设备上调试：

1. 启用远程调试：

   google-chrome --remote-debugging-port=9222
   

2. 访问调试界面：

   http://localhost:9222
   

3. 使用 Chrome DevTools Protocol： 可以编程控制和调试

💡 开发建议

1. 使用 console.log 大量输出日志

   • 在开发阶段多打日志
   • 生产环境再移除

2. 利用 Chrome Storage API 存储调试信息

   chrome.storage.local.set({debug: data});
   

3. 创建测试页面

   • 包含各种测试场景
   • 方便重复测试

4. 使用 Postman 测试 API

   • 测试与 Qwen 服务器的通信
   • 验证数据格式

📚 相关资源

• Chrome Extension 开发文档
• Native Messaging 文档
• Chrome DevTools 文档
• 项目 API 参考

🆘 获取帮助

如果遇到问题：

1. 查看 技术细节文档
2. 检查 API 参考文档
3. 提交 Issue 到 GitHub
4. 查看日志文件寻找错误信息

---

祝调试愉快！🎉