13.1 · 桌面应用（Desktop Application）

桌面应用

桌面应用程序

相关源文件

本章引用的主要源码文件：

• desktop/.gitignore
• desktop/README.md
• desktop/package-lock.json
• desktop/package.json
• desktop/scripts/generate-icons.sh
• desktop/src-tauri/Cargo.lock
• desktop/src-tauri/Cargo.toml
• desktop/src-tauri/build.rs
• desktop/src-tauri/gen/schemas/acl-manifests.json
• desktop/src-tauri/gen/schemas/capabilities.json
• desktop/src-tauri/gen/schemas/desktop-schema.json
• desktop/src-tauri/gen/schemas/macOS-schema.json
• desktop/src-tauri/src/main.rs
• desktop/src-tauri/tauri.conf.json
• desktop/src-tauri/tauri.windows.conf.json
• desktop/src/index.html
• desktop/src/titlebar.js

Onyx 桌面应用程序是一款基于 Tauri 框架构建的跨平台客户端。它为 macOS、Windows 和 Linux 提供原生体验，在封装 Onyx Web 界面的同时，增加了全局键盘快捷键、原生通知和本地配置管理等桌面专属功能。

桌面应用程序位于 desktop/ 目录下 desktop/README.md:101，与 Web 应用程序共享核心前端逻辑，同时利用基于 Rust 的后端进行系统级集成。

架构与数据流

该应用程序遵循标准的 Tauri 架构，将 UI（Next.js/React）与系统级操作（Rust）分离。Rust 核心负责窗口管理、托盘图标和文件系统访问。

系统组件交互

下图展示了桌面应用程序如何与本地文件系统和远程 Onyx 后端进行交互。

桌面应用程序组件图

来源：desktop/src-tauri/src/main.rs:23-24、desktop/src-tauri/src/main.rs:35-36、desktop/src-tauri/src/main.rs:39

配置与自定义

桌面应用程序将持久化设置存储在本地。这使得用户可以将应用程序指向不同的 Onyx 实例（例如，自托管的生产实例与本地开发环境）。

配置文件

配置文件名为 config.json desktop/src-tauri/src/main.rs:36。

• macOS： ~/Library/Application Support/app.onyx.desktop/config.json desktop/README.md:139
• Windows： %APPDATA%/app.onyx.desktop/config.json desktop/README.md:141
• Linux： ~/.config/app.onyx.desktop/config.json desktop/README.md:140

server_url 自定义

主要的配置选项是 server_url。默认情况下，应用程序指向 Onyx 云实例（https://cloud.onyx.app）desktop/src-tauri/src/main.rs:35，但对于自托管部署，必须将其更新为 FastAPI 后端的地址。

要为自托管实例自定义 server_url：

1. 启动应用程序一次以生成默认的 config.json。
2. 打开配置文件（例如，在 macOS 上按 ⌘ ,，或手动导航到该路径）。
3. 修改 server_url 字段 desktop/README.md:151。
4. 重新启动应用程序以使更改生效。

来源：desktop/src-tauri/src/main.rs:35-36、desktop/README.md:133-157

键盘快捷键

桌面应用程序实现了多个全局和本地键盘快捷键。这些快捷键在 main.rs 的 Rust 后端中定义。

来源：desktop/README.md:17-27、desktop/src-tauri/src/main.rs:15-17

构建与分发

Onyx 桌面应用程序使用 Tauri CLI 构建 desktop/package.json:12。

构建说明

1. 前置条件：

• Rust（最新稳定版）desktop/README.md:30-34
• Node.js（18+）desktop/README.md:37-45
• Xcode 命令行工具（仅限 macOS）desktop/README.md:47-49

1. 步骤：

    cd desktop
    npm install [desktop/README.md:56]
    npm run build [desktop/README.md:70]

通用二进制文件（macOS）

要构建适用于 macOS 的通用二进制文件（同时支持 Intel 和 Apple Silicon），必须添加特定的 Rust 目标。

rustup target add x86_64-apple-darwin [desktop/README.md:77]
rustup target add aarch64-apple-darwin [desktop/README.md:78]
npm run build:dmg [desktop/README.md:81]

生成的 .dmg 文件将位于 src-tauri/target/release/bundle/dmg/ 目录下 desktop/README.md:84。

平台特定构建

• Windows： npm run build:windows 使用 cargo-xwin 进行交叉编译 desktop/package.json:10。
• Linux： npm run build:linux 将应用程序打包为 .deb 和 .rpm 格式 desktop/package.json:11。

构建流程映射

下图展示了桌面应用程序的构建过程。

桌面应用程序构建流程

来源：desktop/package.json:8-11、desktop/src-tauri/Cargo.toml:1-22、desktop/src-tauri/tauri.conf.json:1-69、desktop/README.md:73-82

开发说明

自定义标题栏

在 macOS 上，通过 titlebar.js desktop/src-tauri/src/main.rs:38 注入自定义标题栏。该脚本使用 -webkit-app-region: drag desktop/src/titlebar.js:102 创建可拖拽区域，并处理主题感知的玻璃效果 desktop/src/titlebar.js:177-178。

控制台输出捕获

应用程序注入 CONSOLE_CAPTURE_SCRIPT 以捕获前端日志。它重写了 console.log、console.warn 等方法，并使用 invoke('log_from_frontend', ...) 将消息发送到 Rust 后端 desktop/src-tauri/src/main.rs:210-222。

对话链接拦截

CHAT_LINK_INTERCEPT_SCRIPT 拦截对话会话中的导航 desktop/src-tauri/src/main.rs:48。它确保外部链接（目标 _blank）或特定协议（如 mailto: 和 tel:）通过 open_in_browser 使用系统浏览器打开 desktop/src-tauri/src/main.rs:89。

窗口状态与毛玻璃效果

• 窗口状态： 应用程序使用 tauri-plugin-window-state 来记住窗口大小和位置 desktop/src-tauri/Cargo.toml:14。
• 毛玻璃效果： 在 macOS 上，应用程序应用 NSVisualEffectMaterial 以实现原生半透明效果 desktop/src-tauri/src/main.rs:29。

来源：desktop/src-tauri/src/main.rs:29、desktop/src-tauri/src/main.rs:38、desktop/src-tauri/src/main.rs:48、desktop/src-tauri/src/main.rs:210-222、desktop/src-tauri/Cargo.toml:14、desktop/src/titlebar.js:102-178