mirror of
https://github.com/QwenLM/qwen-code.git
synced 2025-12-22 09:47:47 +00:00
feat(chrome-qwen-bridge): 🔥 init chrome qwen code bridge
This commit is contained in:
yiliang114
295
packages/chrome-qwen-bridge/docs/debugging.md
Normal file
295
packages/chrome-qwen-bridge/docs/debugging.md
Normal file
@@ -0,0 +1,295 @@
|
||||
# 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. 查看日志文件寻找错误信息
|
||||
|
||||
---
|
||||
|
||||
祝调试愉快！🎉
|
||||
Reference in New Issue
Block a user