桌面应用

Forgexa Desktop 是基于 Tauri 2 构建的原生应用，封装了 Web 前端，集成了守护进程管理、系统托盘和操作系统通知。

运行时依赖

Forgexa Desktop 内置了一个基于 Python 的守护进程，用于在本机执行 AI Agent 任务。 使用守护进程功能前，必须先安装 Python 3.9 或更高版本。

检查 Python 版本

# macOS / Linux
python3 --version

# Windows
python --version

输出应为 Python 3.9.x 或更高版本。

安装 Python

1. 从 python.org/downloads 下载 Windows 安装包。
2. 运行安装程序。在第一个界面 勾选"Add Python to PATH"，再点击 Install。
3. 打开新的终端窗口，验证：

   python --version

4. 在 Forgexa 应用中打开 设置 → 守护进程，点击 启动。

请勿使用 Microsoft Store 版本

Windows 11 在 %LOCALAPPDATA%\Microsoft\WindowsApps 中放置了一个 python.exe 占位符。在未安装 Python 的情况下，该占位符在无控制台窗口（CREATE_NO_WINDOW）模式下会静默退出，不产生任何输出，导致守护进程启动失败。请务必从 python.org 安装。

症状：daemon.log 中只有反复出现的 SESSION START

如果打开 %USERPROFILE%\.forgexa\daemon\daemon.log 后只看到反复出现的 === DAEMON SESSION START === 而没有后续内容，说明 Python 未安装或安装不正确。 请从 python.org 安装 Python 后重启应用。

Python 依赖包

守护进程所需的依赖包由应用在首次启动时自动安装，无需手动执行 pip install。

下载安装

从 Releases 页面 下载最新版本。

平台	格式	说明
macOS	.dmg	通用二进制（Intel + Apple Silicon）
Linux（Debian/Ubuntu）	.deb	Ubuntu 22.04+
Linux（其他发行版）	.AppImage	任何现代发行版
Windows	.msi、.exe	Windows 10+（.msi = WiX，.exe = NSIS）

未签名安装包

当前版本尚未进行代码签名，请按照各平台的安装步骤绕过系统安全提示。

macOS

1. 打开下载的 .dmg 文件（如 Forgexa_1.2.3_universal.dmg）
2. 将 Forgexa.app 拖入 Applications（应用程序） 文件夹
3. 移除 macOS 隔离属性，允许应用运行：

sudo xattr -cr /Applications/Forgexa.app

如果 macOS 在拖拽前就已阻止 .dmg 本身，先对下载文件执行同样的命令，然后重复上述步骤：

sudo xattr -cr ~/Downloads/Forgexa_1.2.3_universal.dmg

完成后，在「应用程序」中双击 Forgexa 启动。

Linux — .deb（Ubuntu / Debian）

sudo dpkg -i ~/Downloads/Forgexa_1.2.3_amd64.deb

安装完成后，从应用菜单启动，或在终端运行 forgexa。

Linux — .AppImage

chmod +x ~/Downloads/Forgexa_1.2.3_amd64.AppImage
./Forgexa_1.2.3_amd64.AppImage

也可以安装 AppImageLauncher，将 AppImage 集成到系统应用菜单。

Windows

提供两种安装包格式，选择其一即可：

选项 A — .exe（NSIS，推荐大多数用户使用）

1. 双击 Forgexa_1.2.3_x64-setup.exe
2. 如果 Windows SmartScreen 显示警告，点击 更多信息 → 仍要运行
3. 按照安装向导完成安装

选项 B — .msi（WiX，适合企业/组策略部署）

1. 双击 Forgexa_1.2.3_x64-setup.msi
2. 如果 SmartScreen 显示警告，点击 更多信息 → 仍要运行
3. 按照安装向导完成安装

功能特性

• 守护进程管理 — 直接在 UI 中启动、停止和重启 Forgexa 守护进程
• 系统托盘 — 最小化到托盘，提供快速访问菜单（显示 / 启动守护进程 / 停止守护进程 / 退出）
• 服务器连接 — 连接本地或远程 API 服务器，自动健康检查
• 原生通知 — 构建、测试和门禁结果通过操作系统通知中心推送
• 自动启动 — 可选开机自启

前置条件（从源码构建）

工具	版本
Rust	1.77+
Node.js	18+
tauri-cli	2.x（cargo install tauri-cli）

Linux 额外依赖

sudo apt install libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev patchelf

开发

# 启动前端开发服务器（单独终端）
cd frontend && npm run dev

# 启动 Tauri 开发模式（热重载）
cd desktop && cargo tauri dev

构建

macOS

./desktop/scripts/build-macos.sh             # 当前架构
./desktop/scripts/build-macos.sh --universal  # 通用二进制
./desktop/scripts/build-macos.sh --sign       # 签名和公证

Linux

./desktop/scripts/build-linux.sh              # .deb + .AppImage
./desktop/scripts/build-linux.sh --deb-only   # 仅 .deb
./desktop/scripts/build-linux.sh --appimage-only

Windows

.\desktop\scripts\build-windows.ps1

通过 Makefile

make desktop-dev    # Tauri 开发模式
make desktop-build  # 为当前平台构建