259 lines
8.5 KiB
Markdown
259 lines
8.5 KiB
Markdown
# QwenPaw Desktop 桌面应用版使用指南
|
||
|
||
> ⚠️ **Beta 版本说明**
|
||
>
|
||
> 桌面应用目前处于 Beta 测试阶段，存在以下已知限制：
|
||
>
|
||
> - **兼容性测试不完整**：未在所有系统版本和硬件配置上进行充分测试
|
||
> - **性能可能存在缺陷**：启动速度、内存占用等方面可能需要进一步优化
|
||
> - **功能持续完善中**：部分功能可能不稳定或缺失
|
||
>
|
||
> ✅ 桌面应用现已采用 **Tauri** 构建，内置**应用内自动更新**，无需卸载重装即可升级到新版本。
|
||
>
|
||
> 欢迎反馈问题，帮助我们改进产品质量。
|
||
|
||
**下载地址**：[GitHub Releases][releases]
|
||
|
||
本文档说明如何在 Windows 和 macOS 系统上安装和使用 QwenPaw Desktop 桌面应用。
|
||
|
||
[releases]: https://qwenpaw.agentscope.io/downloads
|
||
|
||
## 特别说明
|
||
|
||
**首次启动可能需要较长时间（10-60秒不等，甚至可能更长），具体取决于您的系统配置。** 应用需要初始化 Python 环境、加载依赖库和启动 Web 服务，请耐心等待窗口出现。后续启动会更快。
|
||
|
||
## 目录
|
||
|
||
- [Windows 使用指南](#windows-使用指南)
|
||
- [macOS 使用指南](#macos-使用指南)
|
||
- [技术支持](#技术支持)
|
||
|
||
---
|
||
|
||
## Windows 使用指南
|
||
|
||
### 系统要求
|
||
|
||
- **操作系统**: Windows 10 或更高版本
|
||
- **架构**: x64 (64位)
|
||
|
||
### 安装步骤
|
||
|
||
1. **下载安装包**
|
||
从 [Release 页面][releases]下载 `QwenPaw-Tauri-<version>-Windows-setup.exe` 文件
|
||
|
||
2. **运行安装程序**
|
||
双击 `.exe` 文件，按照安装向导提示完成安装
|
||
- 默认安装位置：`C:\Users\<你的用户名>\AppData\Local\QwenPaw Desktop`
|
||
- 安装完成后会在桌面和开始菜单创建快捷方式
|
||
|
||
### 启动方式
|
||
|
||
安装完成后，您会看到**两个启动快捷方式**：
|
||
|
||
#### **QwenPaw Desktop** (推荐日常使用)
|
||
|
||
- **特点**: 静默启动，无终端窗口，界面简洁
|
||
- **适用场景**: 正常使用，不需要查看技术日志
|
||
- **启动方式**: 双击桌面或开始菜单的 "QwenPaw Desktop" 图标
|
||
- **技术说明**: 原生 Tauri 桌面应用，后台以 sidecar 方式运行 Python 后端
|
||
|
||
#### **QwenPaw Desktop (Debug)** (调试模式)
|
||
|
||
- **特点**: 打开终端窗口，以调试日志级别启动应用，并实时跟踪后端与应用日志
|
||
- **适用场景**:
|
||
- 遇到问题需要查看错误信息
|
||
- 开发测试
|
||
- 报告 Bug 时需要提供日志
|
||
- **启动方式**: 双击开始菜单的 "QwenPaw Desktop (Debug)" 图标
|
||
- **日志内容**:
|
||
- 应用启动信息
|
||
- Python 错误堆栈
|
||
- API 调用日志
|
||
- 按 Ctrl+C 或关闭窗口可停止查看日志
|
||
|
||
### 常见问题
|
||
|
||
**Q: 应用启动后窗口白屏，无法正常显示？**
|
||
|
||
A: 桌面应用依赖 **Microsoft WebView2** 运行时。安装程序通常会在联网时自动下载并静默安装 WebView2；如果因离线安装等原因缺失并导致白屏，可前往微软官网手动安装后重启应用：
|
||
[Microsoft WebView2](https://developer.microsoft.com/en-us/microsoft-edge/webview2/)
|
||
|
||
**Q: 应用启动后没有反应？**
|
||
|
||
A: 使用 "QwenPaw Desktop (Debug)" 模式启动，查看终端输出的错误信息
|
||
|
||
**Q: 如何卸载？**
|
||
|
||
A: 在 Windows 设置 → 应用 → 已安装的应用 → 找到 "QwenPaw Desktop" → 卸载
|
||
|
||
**Q: 安装包是否安全？**
|
||
|
||
A: 应用未经过 **Microsoft 代码签名**（成本 $200-800/年），Windows Defender SmartScreen 会显示警告
|
||
这是正常现象，点击 "更多信息" → "仍要运行" 即可
|
||
代码完全开源，构建过程在 GitHub Actions 上透明可查
|
||
|
||
---
|
||
|
||
## macOS 使用指南
|
||
|
||
### 系统要求
|
||
|
||
- **操作系统**: macOS 14 (Sonoma) 或更高版本
|
||
- **架构**:
|
||
- ✅ **Apple Silicon (M1/M2/M3/M4)** - 推荐
|
||
- ⚠️ Intel 芯片 - 可能可以运行，但可能无法使用内置的本地模型服务
|
||
|
||
### 安装步骤
|
||
|
||
1. **下载压缩包**
|
||
从 [Release 页面][releases]下载 `QwenPaw-Tauri-<version>-macOS.zip` 文件
|
||
|
||
2. **解压缩**
|
||
双击 `.zip` 文件自动解压，得到 `QwenPaw Desktop.app` 应用
|
||
|
||
3. **移动到应用程序文件夹 (可选)**
|
||
将 `QwenPaw Desktop.app` 拖到 `/Applications` 文件夹
|
||
|
||
### 首次启动：解除系统安全限制
|
||
|
||
#### 为什么需要手动信任？
|
||
|
||
QwenPaw 应用**未经过 Apple 开发者签名和公证（Notarization）**，macOS Gatekeeper 会默认阻止运行。
|
||
|
||
**为什么没有签名？**
|
||
|
||
- 📋 开发者签名需要额外成本和流程，后续版本会补上
|
||
|
||
**当前影响：**
|
||
|
||
- ✅ **不影响功能**：应用完全正常运行
|
||
- ⚠️ **首次需手动信任**：一次操作后永久有效
|
||
- 🔒 **安全性**：开源代码可审计，构建过程透明（CI/CD）
|
||
|
||
#### 如何解除限制？
|
||
|
||
#### 方法 1：右键打开 (推荐)
|
||
|
||
1. **右键点击**（或 Control + 点击）`QwenPaw Desktop.app`
|
||
2. 在菜单中选择 **"打开"**
|
||
3. 在弹出的对话框中，再次点击 **"打开"** 按钮
|
||
4. ✅ 之后双击即可正常启动，不会再弹窗
|
||
|
||
#### 方法 2：系统设置解除拦截
|
||
|
||
如果仍被拦截：
|
||
|
||
1. 打开 **系统设置 → 隐私与安全性**
|
||
2. 向下滚动，找到类似以下提示：
|
||
_"已阻止使用 'QwenPaw'，因为无法验证开发者"_
|
||
3. 点击 **"仍要打开"** 或 **"允许"** 按钮
|
||
4. 输入管理员密码确认
|
||
|
||
#### 方法 3：终端命令解除隔离
|
||
|
||
```bash
|
||
# 移除下载隔离属性
|
||
xattr -cr "/Applications/QwenPaw Desktop.app"
|
||
```
|
||
|
||
⚠️ **注意**: 此方法会完全移除安全检查，仅当您完全信任应用来源时使用。
|
||
|
||
### 🔍 权限请求
|
||
|
||
首次启动时，macOS 可能会弹窗请求以下权限：
|
||
|
||
- **桌面文件访问权限**
|
||
用于访问您的文件（如果使用文件相关功能）
|
||
- 点击 **"允许"** 以正常使用
|
||
- 点击 **"不允许"** 应用仍可运行，但部分功能受限
|
||
|
||
### 启动方式
|
||
|
||
#### 正常启动（双击）
|
||
|
||
- 双击 `QwenPaw Desktop.app` 即可启动
|
||
- 应用会在后台运行，打开应用窗口
|
||
- 应用日志输出到：`~/Library/Logs/io.agentscope.qwenpaw.desktop/qwenpaw-desktop.log`
|
||
- 后端 sidecar 日志位于工作目录：`~/.qwenpaw/desktop.log`
|
||
|
||
#### 终端启动（查看实时日志）
|
||
|
||
如果应用崩溃或需要查看详细日志，可直接从终端运行 Tauri 应用内的可执行文件，并开启调试日志级别：
|
||
|
||
```bash
|
||
# 以调试日志级别启动（直接运行 app 内的可执行文件）
|
||
QWENPAW_DESKTOP_DEBUG=1 "/Applications/QwenPaw Desktop.app/Contents/MacOS/qwenpaw-desktop"
|
||
```
|
||
|
||
**终端启动的优势：**
|
||
|
||
- ✅ 实时查看应用与后端的所有日志输出
|
||
- ✅ 看到完整的 Python 错误堆栈
|
||
- ✅ 便于调试和报告问题
|
||
- ✅ `QWENPAW_DESKTOP_DEBUG=1` 会把桌面日志级别提升为 debug，输出更详细信息
|
||
|
||
**查看日志文件：**
|
||
|
||
```bash
|
||
# 跟踪应用日志
|
||
tail -f ~/Library/Logs/io.agentscope.qwenpaw.desktop/qwenpaw-desktop.log
|
||
|
||
# 跟踪后端 sidecar 日志
|
||
tail -f ~/.qwenpaw/desktop.log
|
||
```
|
||
|
||
### 常见问题
|
||
|
||
**Q: 双击后没有任何反应？**
|
||
|
||
A: 请尝试以下步骤：
|
||
|
||
1. 检查 `~/.qwenpaw/desktop.log` 文件查看错误
|
||
2. 使用上述终端命令启动，查看实时输出
|
||
|
||
**Q: 提示"Apple 无法验证此应用"？**
|
||
|
||
A: 按照上述"解除系统安全限制"步骤操作
|
||
|
||
**Q: 如何卸载？**
|
||
|
||
A: 将 `QwenPaw Desktop.app` 拖到废纸篓，然后删除 `~/.qwenpaw` 配置文件夹
|
||
|
||
**Q: Intel Mac 可以用吗？**
|
||
A: 可以运行，但可能无法使用内置的本地模型服务
|
||
|
||
**Q: 应用为什么没有签名，为什么系统会提示有风险？**
|
||
|
||
A: 当前采用
|
||
|
||
- ✅ **开源透明**：所有代码和构建流程公开在 GitHub
|
||
- ✅ **CI/CD 可验证**：GitHub Actions 自动构建，日志可查
|
||
- ✅ **用户审计**：可以自行检查代码并本地构建
|
||
- ✅ **一次信任**：手动信任后永久有效
|
||
|
||
---
|
||
|
||
## 技术支持
|
||
|
||
- **GitHub Issues**: [提交问题](https://github.com/agentscope-ai/QwenPaw/issues)
|
||
- **桌面外壳与构建**: Tauri 桌面外壳位于 `console/src-tauri/`，打包脚本位于 `scripts/pack-tauri/`
|
||
- **日志位置**:
|
||
- Windows: Debug 快捷方式终端查看；应用日志 `%LOCALAPPDATA%\io.agentscope.qwenpaw.desktop\logs\qwenpaw-desktop.log`；后端 `%USERPROFILE%\.qwenpaw\desktop.log`
|
||
- macOS: 应用日志 `~/Library/Logs/io.agentscope.qwenpaw.desktop/qwenpaw-desktop.log`；后端 `~/.qwenpaw/desktop.log`
|
||
|
||
---
|
||
|
||
## 使用建议
|
||
|
||
### Windows 用户
|
||
|
||
- **日常使用**: 使用普通版（无终端窗口）
|
||
- **遇到问题**: 切换到 Debug 版查看日志
|
||
|
||
### macOS 用户
|
||
|
||
- **首次安装**: 务必按照"解除安全限制"步骤操作
|
||
- **调试问题**: 使用终端启动方式查看实时日志
|
||
- **权限问题**: 首次启动时请允许文件访问权限
|