18 KiB

Raw Blame History

date	status	depth	origin
2026-06-13	active	standard	null

feat: Tauri 2.x Desktop Client

Summary

创建 Tauri 2.x 桌面客户端外壳，将现有 Vue 3 GUI 包装为跨平台桌面应用（Windows/macOS/Linux）。Tauri 管理窗口和 Python 后端进程生命周期，前端代码仅做最小适配（动态 API baseURL + Splash 启动流程），不修改任何 GUI 组件、布局、样式或业务逻辑。

Problem Frame

当前 AgentKit GUI 只能通过浏览器访问（agentkit gui 启动后自动打开浏览器），用户需要：

手动启动后端进程
在浏览器中操作，缺乏原生体验（无系统托盘、无桌面集成、无自动更新）
无法像桌面应用一样安装、启动、关闭

竞品（Cursor、Devin）均提供原生桌面客户端。AgentKit 需要对齐这一体验标准。

Key Technical Decisions

KTD-1: Tauri 2.x 作为桌面壳。 Tauri 使用系统 WebView（不打包 Chromium），安装包 ~5-10MB + PyInstaller 产物 ~30-80MB，总计远小于 Electron 方案（~200MB+）。启动快（窗口 <500ms），内存低（~110-200MB vs Electron ~300-500MB）。Tauri 2.x 插件化架构更灵活，capabilities 权限模型更安全，且是长期维护版本。

KTD-2: PyInstaller 打包 Python 后端为 sidecar。 PyInstaller 将 Python 后端打包为独立单文件二进制，Tauri 通过 tauri-plugin-shell sidecar API 管理其生命周期。比 Nuitka 兼容性更好，社区更成熟。

KTD-3: 端口 0 + stdout 解析实现端口发现。 Python 后端以 --port 0 启动，OS 分配随机可用端口，uvicorn 启动后通过 stdout 输出 AGENTKIT_PORT=XXXXX，Rust 侧解析后通过 Tauri IPC 传递给前端。避免端口冲突，无需用户配置。

KTD-4: 前端最小适配策略。 仅修改 api/base.ts（动态 baseURL）和 App.vue（Splash 启动流程），新增 api/tauri.ts（Tauri invoke 封装）和 TitleBar.vue（自定义标题栏）。所有现有 GUI 组件、布局、样式、业务逻辑不做任何修改。

KTD-5: 双窗口 Splash 方案。 Tauri 配置两个窗口：splash（小窗口，加载动画）和 main（主窗口，初始隐藏）。后端就绪后 Rust 侧关闭 splash、显示 main。比前端内 Splash 更干净，不侵入现有 App.vue 的布局逻辑。

High-Level Technical Design

┌──────────────────────────────────────────────────────┐
│  Tauri Application (Rust)                            │
│                                                      │
│  ┌─────────────┐  ┌──────────────┐  ┌─────────────┐ │
│  │ Splash      │  │ Main Window  │  │ System Tray │ │
│  │ (loading)   │  │ (Vue 3 SPA)  │  │ (minimize)  │ │
│  └─────────────┘  └──────┬───────┘  └─────────────┘ │
│                          │ HTTP/WS                    │
│  ┌───────────────────────▼──────────────────────────┐│
│  │  Python Backend (sidecar process)                ││
│  │  FastAPI + uvicorn on random port                ││
│  └──────────────────────────────────────────────────┘│
│                                                      │
│  Rust Modules:                                       │
│  - sidecar.rs: start/stop/health Python process      │
│  - tray.rs: system tray menu                        │
│  - lib.rs: Tauri Builder + plugin registration       │
└──────────────────────────────────────────────────────┘

启动序列：

1. 用户双击桌面图标 → Tauri 启动
2. Rust setup() → 创建系统托盘
3. Splash 窗口显示（加载动画）
4. 前端 invoke('start_backend')
5. Rust spawn sidecar: agentkit-server --port 0
6. Python 绑定随机端口 → stdout: AGENTKIT_PORT=XXXXX
7. Rust 解析端口 → 存入 BackendState → emit('backend-ready')
8. 前端设置 apiBaseURL → 健康检查通过
9. Rust 关闭 splash → 显示 main 窗口

关闭序列：

1. 用户点击关闭按钮 → 窗口隐藏到托盘（不退出）
2. 托盘菜单"退出" → Rust 发送 SIGTERM 给 Python 进程
3. Python 优雅关闭 → Tauri app.exit(0)

Scope Boundaries

在范围内：

Tauri 2.x 项目脚手架和配置
Rust 侧 sidecar 进程管理（启动/停止/健康检查/端口发现）
前端最小适配（api/base.ts 动态 baseURL、api/tauri.ts 封装、App.vue Splash 流程、TitleBar.vue）
系统托盘（显示/隐藏窗口、退出）
单实例锁
自定义标题栏（无边框窗口）
PyInstaller 打包脚本
跨平台 CI 构建（GitHub Actions）

延迟到后续迭代：

自动更新器（tauri-plugin-updater 集成 + 签名密钥 + 发布服务器）
应用签名和公证（macOS code signing / Windows Authenticode）
多语言支持
离线模式
深度链接（deep link / URL scheme 注册）
文件关联

不在范围内：

修改现有 GUI 组件、布局、样式
修改后端 API 或业务逻辑
移动端适配（Tauri 2.x 支持 iOS/Android，但不在本次范围）
多用户协作

Implementation Units

U1. Tauri 2.x 项目脚手架

Goal: 创建 Tauri 2.x 项目结构，配置构建管线，验证 dev 模式可运行。

Requirements: KTD-1, KTD-4

Dependencies: 无

Files:

src-tauri/Cargo.toml — Rust 依赖（tauri 2, tauri-plugin-shell, tauri-plugin-single-instance, serde, tokio, reqwest）
src-tauri/tauri.conf.json — Tauri 核心配置（窗口、sidecar 声明、bundle 设置）
src-tauri/capabilities/default.json — 权限声明
src-tauri/src/main.rs — Rust 入口
src-tauri/src/lib.rs — Tauri Builder（占位，后续单元填充）
src-tauri/build.rs — 构建脚本
src-tauri/icons/ — 应用图标（占位）
package.json — 添加 Tauri CLI 和 API 依赖

Approach:

在项目根目录初始化 Tauri 2.x：npm create tauri-app@latest 或手动创建 src-tauri/ 目录
tauri.conf.json 配置双窗口（splash + main），main 初始 visible: false
build.beforeDevCommand 指向前端 dev 脚本，build.beforeBuildCommand 指向前端 build 脚本
build.frontendDist 指向前端构建输出目录
bundle.externalBin 声明 sidecar 二进制名
安装前端依赖：@tauri-apps/api@^2, @tauri-apps/plugin-shell@^2
验证 npm run tauri dev 能启动窗口

Patterns to follow: Tauri 2.x 官方项目结构

Test scenarios:

npm run tauri dev 启动后显示 Tauri 窗口（前端内容可能为空，因为后端未启动）
npm run tauri build 能生成安装包（可能因缺少 sidecar 二进制而失败，此为预期）

Verification: npm run tauri dev 能启动 Tauri 窗口并加载前端页面

U2. Rust Sidecar 进程管理

Goal: 实现 Python 后端进程的启动、停止、健康检查和端口发现。

Requirements: KTD-2, KTD-3

Dependencies: U1

Files:

src-tauri/src/sidecar.rs — sidecar 管理模块（新建）
src-tauri/src/lib.rs — 注册 invoke handler 和 BackendState
src-tauri/Cargo.toml — 添加 regex 依赖

Approach:

定义 BackendState 结构体：port: Mutex<Option<u16>>, pid: Mutex<Option<u32>>
实现 start_backend 命令：
- 通过 app.shell().sidecar("agentkit-server") 创建 sidecar 命令
- 传入 --port 0 和 AGENTKIT_GUI_MODE=1 环境变量
- spawn 后监听 stdout/stderr，用正则解析 AGENTKIT_PORT=(\d+)
- 端口就绪后 emit backend-ready 事件
- 带超时等待（30s）
实现 get_backend_port 命令：返回当前端口
实现 stop_backend 命令：发送 SIGTERM（Unix）或 taskkill（Windows）
实现 check_backend_health 命令：HTTP GET http://127.0.0.1:{port}/api/v1/health
在 lib.rs 中注册所有命令和 BackendState managed state

Technical design:

start_backend() flow:
  sidecar("agentkit-server").args(["--port", "0"]).env("AGENTKIT_GUI_MODE", "1")
  → spawn → tokio::spawn listen stdout/stderr
  → parse AGENTKIT_PORT=XXXXX → store in BackendState.port
  → emit("backend-ready", { port }) → return port

stop_backend() flow:
  BackendState.pid → SIGTERM/taskkill → clear port & pid

Patterns to follow: tauri-plugin-shell sidecar API 文档

Test scenarios:

启动 sidecar 后 get_backend_port 返回有效端口号
check_backend_health 在后端就绪后返回 true
stop_backend 能成功终止 Python 进程
后端启动超时（30s）时返回错误
后端意外崩溃时 Rust 侧能检测到并清理状态

Verification: 手动测试 invoke('start_backend') → invoke('get_backend_port') → invoke('check_backend_health') → invoke('stop_backend') 全流程

U3. 前端适配 — 动态 API baseURL + Splash 启动流程

Goal: 前端支持 Tauri 环境，动态设置 API baseURL，添加 Splash 启动流程。

Requirements: KTD-3, KTD-4, KTD-5

Dependencies: U2

Files:

src/agentkit/server/frontend/src/api/base.ts — 修改：支持 Tauri 环境动态 baseURL
src/agentkit/server/frontend/src/api/tauri.ts — 新增：Tauri invoke 封装
src/agentkit/server/frontend/src/App.vue — 修改：添加 Splash 启动流程
src/agentkit/server/frontend/src/components/layout/SplashScreen.vue — 新增：Splash 加载组件
src/agentkit/server/frontend/src/components/layout/TitleBar.vue — 新增：自定义标题栏
src/agentkit/server/frontend/src/views/AgentLayout.vue — 修改：集成 TitleBar
src/agentkit/server/frontend/vite.config.ts — 修改：Tauri 环境适配

Approach:

api/tauri.ts：封装 Tauri invoke 调用
- isTauri() 检测是否在 Tauri 环境中（'__TAURI_INTERNALS__' in window）
- startBackend() → invoke('start_backend')
- getBackendPort() → invoke('get_backend_port')
- stopBackend() → invoke('stop_backend')
- checkBackendHealth() → invoke('check_backend_health')
api/base.ts：动态 baseURL
- 新增 initApiBaseURL() 函数
- Tauri 环境：从 getBackendPort() 获取端口，设置 apiBaseURL = http://127.0.0.1:{port}
- 浏览器环境：apiBaseURL = ''（保持现有相对路径行为）
- BaseApiClient 的 request() 和 createWebSocket() 方法使用动态 baseURL
App.vue：Splash 启动流程
- 新增 loading 和 loadingProgress 响应式状态
- onMounted 时：如果 isTauri()，调用 startBackend() → initApiBaseURL() → checkBackendHealth()
- 加载完成前显示 SplashScreen，完成后显示 RouterView
- 浏览器环境保持现有行为不变
SplashScreen.vue：加载动画组件
- 品牌 Logo + 加载进度条 + 状态文字（"正在启动后端..."、"正在连接..."）
- 使用现有 Design Token 变量
TitleBar.vue：自定义标题栏
- data-tauri-drag-region 使标题栏可拖拽
- 最小化/最大化/关闭按钮（关闭时隐藏到托盘）
- 仅在 Tauri 环境中显示
vite.config.ts：Tauri 适配
- 读取 TAURI_DEV_HOST 环境变量
- envPrefix 添加 TAURI_
- server.watch.ignored 排除 src-tauri/

Patterns to follow: 现有 api/base.ts 的 BaseApiClient 模式；现有 Design Token 体系

Test scenarios:

浏览器模式：所有 API 调用正常工作（相对路径不变）
Tauri 模式：initApiBaseURL() 设置正确的 http://127.0.0.1:{port}
Tauri 模式：WebSocket 连接到正确的 ws://127.0.0.1:{port}/api/v1/...
Splash 在后端就绪前显示，就绪后消失
TitleBar 拖拽移动窗口，按钮功能正确
后端启动失败时显示错误信息

Verification: npm run tauri dev 启动后：Splash 显示 → 后端启动 → 主界面加载 → API 调用正常

U4. 系统托盘 + 单实例 + 窗口管理

Goal: 实现系统托盘、单实例锁和窗口关闭行为（最小化到托盘）。

Requirements: KTD-1

Dependencies: U2

Files:

src-tauri/src/tray.rs — 新增：系统托盘模块
src-tauri/src/lib.rs — 修改：注册托盘、单实例插件、窗口事件
src-tauri/Cargo.toml — 添加 tauri-plugin-single-instance

Approach:

系统托盘（tray.rs）：
- 菜单项：显示主窗口 / 分隔线 / 退出
- 左键点击托盘图标：显示并聚焦主窗口
- 退出菜单项：先 stop_backend()，再 app.exit(0)
单实例锁：
- 注册 tauri-plugin-single-instance
- 第二个实例启动时：聚焦已有主窗口
窗口关闭行为：
- CloseRequested 事件中 api.prevent_close() + window.hide()
- 窗口隐藏到托盘而非退出
Splash → Main 切换：
- start_backend 成功后，Rust 侧关闭 splash 窗口、显示 main 窗口

Patterns to follow: Tauri 2.x tray API 文档

Test scenarios:

点击关闭按钮后窗口隐藏，托盘图标仍在
托盘"显示"菜单恢复窗口
托盘"退出"菜单停止后端并退出应用
左键点击托盘图标恢复窗口
启动第二个实例时聚焦已有窗口

Verification: 完整的窗口生命周期测试：启动 → 关闭到托盘 → 从托盘恢复 → 托盘退出

U5. PyInstaller 打包脚本 + Python 侧适配

Goal: 创建 PyInstaller 打包脚本，Python 后端支持 --port 0 并输出端口信息。

Requirements: KTD-2, KTD-3

Dependencies: U2

Files:

scripts/build-backend.sh — 新增：PyInstaller 打包脚本
scripts/build-backend.ps1 — 新增：Windows 版打包脚本
src/agentkit/cli/main.py — 修改：gui 命令支持 --port 0
src/agentkit/server/runner.py — 修改：uvicorn 启动后输出 AGENTKIT_PORT=XXXXX

Approach:

Python 侧适配：
- gui 命令的 --port 参数支持 0（让 OS 分配随机端口）
- uvicorn 启动后，在 lifespan startup 中检测实际绑定端口
- 通过 stdout 输出 AGENTKIT_PORT={port}（flush=True），供 Rust 解析
- 当 --port 0 时，host 默认改为 127.0.0.1（仅本地访问，安全）
PyInstaller 打包脚本：
- --onefile 模式打包
- --name agentkit-server 命名
- 包含必要的 --hidden-import（uvicorn.logging, agentkit.server 等）
- --add-data 包含 agentkit.yaml 和 configs 目录
- 输出到 src-tauri/binaries/ 并添加平台后缀
平台后缀命名：
- macOS ARM: agentkit-server-aarch64-apple-darwin
- macOS Intel: agentkit-server-x86_64-apple-darwin
- Windows: agentkit-server-x86_64-pc-windows-msvc.exe
- Linux: agentkit-server-x86_64-unknown-linux-gnu

Patterns to follow: 现有 agentkit gui 命令的启动流程

Test scenarios:

python -m agentkit gui --port 0 启动后 stdout 输出 AGENTKIT_PORT=XXXXX
PyInstaller 打包的二进制能独立运行
打包的二进制支持 --port 0 和 AGENTKIT_GUI_MODE=1
打包的二进制在无 Python 环境的机器上能运行

Verification: 在当前平台执行 scripts/build-backend.sh，产物放入 src-tauri/binaries/，npm run tauri dev 能通过 sidecar 启动后端

U6. 跨平台 CI 构建

Goal: 配置 GitHub Actions 自动构建 Windows/macOS/Linux 安装包。

Requirements: KTD-1

Dependencies: U1, U5

Files:

.github/workflows/release-desktop.yml — 新增：桌面客户端发布工作流

Approach:

触发条件：推送 v* tag
构建矩阵：macOS (aarch64 + x86_64)、Windows (x86_64)、Linux (x86_64)
每个平台步骤：
- Setup Node.js 20 + Rust stable + Python 3.11
- 安装 Linux 系统依赖（libwebkit2gtk-4.1-dev 等）
- pip install pyinstaller + 执行 scripts/build-backend.sh
- npm ci + npm run tauri build
使用 tauri-apps/tauri-action@v0 构建和发布
产物上传到 GitHub Release（draft）

Patterns to follow: Tauri 官方 GitHub Actions 模板

Test scenarios:

推送 tag 后工作流在所有 4 个目标上成功运行
产物正确上传到 GitHub Release

Verification: 手动触发工作流或推送 tag，检查 GitHub Release 页面

Risks & Dependencies

风险	影响	缓解
PyInstaller 打包后部分依赖缺失	后端无法启动	逐步测试，添加 `--hidden-import`
Linux WebView 兼容性差异	GUI 渲染异常	测试主流发行版（Ubuntu 22.04+），文档说明依赖
Python sidecar 启动慢（3-5s）	用户等待时间长	Splash 加载画面 + 进度反馈
macOS 签名/公证缺失	用户安装时被 Gatekeeper 阻止	延迟到后续迭代，文档说明绕过方法
Tauri 2.x API 变更	代码需调整	锁定 Tauri 2.x 稳定版

Assumptions

用户机器上有 WebView2（Windows 10+ 自带）、WebKit（macOS 自带）、WebKitGTK（Linux 需安装）
Python 后端不需要 GPU 加速或其他特殊硬件
单用户本地使用场景，不需要多用户认证
首个版本不需要应用签名和公证

Open Questions

自动更新服务器的部署方案（S3 / GitHub Releases / 自建）— 延迟到后续迭代
是否需要支持 Linux ARM64 — 视用户需求决定
PyInstaller 产物体积优化（是否排除不必要的依赖）— 实现时评估

18 KiB Raw Blame History Unescape Escape

feat: Tauri 2.x Desktop Client

Summary

Problem Frame

Key Technical Decisions

High-Level Technical Design

Scope Boundaries

Implementation Units

U1. Tauri 2.x 项目脚手架

U2. Rust Sidecar 进程管理

U3. 前端适配 — 动态 API baseURL + Splash 启动流程

U4. 系统托盘 + 单实例 + 窗口管理

U5. PyInstaller 打包脚本 + Python 侧适配

U6. 跨平台 CI 构建

Risks & Dependencies

Assumptions

Open Questions

18 KiB

Raw Blame History