mirror of
https://github.com/QwenLM/qwen-code.git
synced 2025-12-22 09:47:47 +00:00
295 lines
6.6 KiB
Markdown
295 lines
6.6 KiB
Markdown
# Chrome Qwen Bridge 调试指南
|
||
|
||
## 🚀 快速开始调试
|
||
|
||
### 一键启动（推荐）
|
||
|
||
最简单的方式是使用我们提供的一键启动脚本：
|
||
|
||
```bash
|
||
# 进入项目目录
|
||
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 命令
|
||
|
||
```bash
|
||
# 开发调试
|
||
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
|
||
|
||
```bash
|
||
# macOS/Linux
|
||
cd native-host
|
||
./install.sh
|
||
|
||
# Windows（管理员权限）
|
||
cd native-host
|
||
install.bat
|
||
```
|
||
|
||
### 步骤 2：启动 Qwen 服务器（可选）
|
||
|
||
```bash
|
||
# 如果安装了 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 日志：
|
||
```bash
|
||
# macOS/Linux
|
||
tail -f /tmp/qwen-bridge-host.log
|
||
|
||
# 或使用 npm 命令
|
||
npm run logs
|
||
```
|
||
|
||
测试 Native Host 连接：
|
||
```javascript
|
||
// 在 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 中添加日志：
|
||
```javascript
|
||
// 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 是否正确安装：
|
||
```bash
|
||
# macOS
|
||
ls ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/
|
||
|
||
# Linux
|
||
ls ~/.config/google-chrome/NativeMessagingHosts/
|
||
```
|
||
|
||
2. 验证 manifest.json 中的路径是否正确
|
||
3. 确保 host.js 有执行权限：
|
||
```bash
|
||
chmod +x native-host/host.js
|
||
```
|
||
|
||
### 问题：Qwen CLI 未响应
|
||
|
||
**症状**：显示 Qwen CLI 未安装或无响应
|
||
|
||
**解决方案**：
|
||
1. 确认 Qwen CLI 已安装：
|
||
```bash
|
||
qwen --version
|
||
```
|
||
|
||
2. 手动启动 Qwen 服务器：
|
||
```bash
|
||
qwen server --port 8080
|
||
```
|
||
|
||
3. 检查端口是否被占用：
|
||
```bash
|
||
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. **启用远程调试**：
|
||
```bash
|
||
google-chrome --remote-debugging-port=9222
|
||
```
|
||
|
||
2. **访问调试界面**：
|
||
```
|
||
http://localhost:9222
|
||
```
|
||
|
||
3. **使用 Chrome DevTools Protocol**：
|
||
可以编程控制和调试
|
||
|
||
## 💡 开发建议
|
||
|
||
1. **使用 console.log 大量输出日志**
|
||
- 在开发阶段多打日志
|
||
- 生产环境再移除
|
||
|
||
2. **利用 Chrome Storage API 存储调试信息**
|
||
```javascript
|
||
chrome.storage.local.set({debug: data});
|
||
```
|
||
|
||
3. **创建测试页面**
|
||
- 包含各种测试场景
|
||
- 方便重复测试
|
||
|
||
4. **使用 Postman 测试 API**
|
||
- 测试与 Qwen 服务器的通信
|
||
- 验证数据格式
|
||
|
||
## 📚 相关资源
|
||
|
||
- [Chrome Extension 开发文档](https://developer.chrome.com/docs/extensions/mv3/)
|
||
- [Native Messaging 文档](https://developer.chrome.com/docs/apps/nativeMessaging/)
|
||
- [Chrome DevTools 文档](https://developer.chrome.com/docs/devtools/)
|
||
- [项目 API 参考](./api-reference.md)
|
||
|
||
## 🆘 获取帮助
|
||
|
||
如果遇到问题：
|
||
|
||
1. 查看 [技术细节文档](./technical-details.md)
|
||
2. 检查 [API 参考文档](./api-reference.md)
|
||
3. 提交 Issue 到 GitHub
|
||
4. 查看日志文件寻找错误信息
|
||
|
||
---
|
||
|
||
祝调试愉快！🎉 |