chore

apps/demo-server/src-tauri/.gitignore

@@ -0,0 +1,10 @@
+# Generated by Cargo
+# will have compiled files and executables
+/target/
+
+# Generated by Tauri
+# will have schema files for capabilities auto-completion
+/gen/schemas
+
+# Tauri Sidecar
+binaries/

apps/demo-server/src-tauri/AGENTS.md

@@ -0,0 +1,357 @@
+# AGENTS.md - Tauri Shell 项目开发指南
+
+本文档为 AI 编程助手和开发者提供项目规范、构建命令和代码风格指南。
+
+## 项目概览
+
+- **项目类型**: Tauri v2 桌面应用（轻量级壳子）
+- **后端**: Rust (Edition 2021)
+- **架构**: Sidecar 模式 - Sidecar App 承载主要业务逻辑
+- **设计理念**: Tauri 仅提供原生桌面能力（文件对话框、系统通知等），Web 逻辑全部由 Sidecar App 处理
+- **开发模式**: 使用 localhost:3000（需手动启动开发服务器）
+- **生产模式**: 自动启动 Sidecar 二进制
+- **异步运行时**: Tokio
+- **Rust 版本**: 1.92.0+
+- **工具管理**: 使用 mise 管理 Rust 和 Tauri CLI 版本（见 `mise.toml`）
+
+## 构建、测试、运行命令
+
+### 开发运行
+```bash
+# 开发模式运行 (需要先启动开发服务器)
+# 终端 1: 启动前端开发服务器
+bun run dev
+
+# 终端 2: 启动 Tauri 应用
+tauri dev
+
+# 或者使用单命令并行启动（需要配置 package.json）
+bun run dev:tauri
+```
+
+**开发模式说明**：
+- 开发模式下，Tauri 直接连接到 `localhost:3000`（不启动 sidecar 二进制）
+- 需要手动运行 `bun run dev` 来启动开发服务器
+- 支持热重载（HMR），无需重启 Tauri 应用
+
+### 构建
+```bash
+# 开发构建 (debug mode)
+cargo build
+
+# 生产构建
+cargo build --release
+
+# Tauri 应用打包 (生成安装程序)
+tauri build
+```
+
+### 代码检查
+```bash
+# 编译检查 (不生成二进制)
+cargo check
+
+# Clippy 代码质量检查
+cargo clippy
+
+# Clippy 严格模式 (所有警告视为错误)
+cargo clippy -- -D warnings
+
+# 代码格式化检查
+cargo fmt -- --check
+
+# 自动格式化代码
+cargo fmt
+```
+
+### 测试
+```bash
+# 运行所有测试
+cargo test
+
+# 运行单个测试 (按名称过滤)
+cargo test test_function_name
+
+# 运行特定模块的测试
+cargo test module_name::
+
+# 显示测试输出 (包括 println!)
+cargo test -- --nocapture
+
+# 运行单个测试并显示输出
+cargo test test_name -- --nocapture
+```
+
+### 清理
+```bash
+# 清理构建产物
+cargo clean
+```
+
+## 项目结构
+
+```
+app-desktop/
+├── src/
+│   ├── main.rs          # 入口文件 (仅调用 lib::run)
+│   ├── lib.rs           # 核心应用逻辑 (注册插件、命令、状态)
+│   ├── commands/
+│   │   └── mod.rs       # 原生桌面功能命令 (文件对话框、通知等)
+│   └── sidecar.rs       # Sidecar 进程管理 (启动、端口扫描、清理)
+├── binaries/            # Sidecar 二进制文件
+│   └── app-*   # Sidecar App 可执行文件 (示例: app)
+├── capabilities/        # Tauri v2 权限配置
+│   └── default.json
+├── icons/               # 应用图标资源
+├── gen/schemas/         # 自动生成的 Schema (不要手动编辑)
+├── Cargo.toml          # Rust 项目配置
+├── tauri.conf.json     # Tauri 应用配置
+├── build.rs            # Rust 构建脚本
+└── mise.toml           # 开发工具版本管理
+```
+
+## Rust 代码风格指南
+
+### 导入 (Imports)
+
+- 使用标准库、外部 crate、当前 crate 的顺序，用空行分隔
+- 按字母顺序排列
+- 优先使用具体导入而非通配符 `*`
+
+```rust
+// ✅ 推荐
+use std::sync::Mutex;
+use std::time::Duration;
+
+use tauri::Manager;
+use tauri_plugin_shell::ShellExt;
+use tauri_plugin_shell::process::{CommandEvent, CommandChild};
+
+// ❌ 避免
+use tauri::*;
+```
+
+### 命名规范
+
+- **函数和变量**: `snake_case`
+- **类型、结构体、枚举、Trait**: `PascalCase`
+- **常量和静态变量**: `SCREAMING_SNAKE_CASE`
+- **生命周期参数**: 简短小写字母，如 `'a`, `'b`
+
+```rust
+// ✅ 推荐
+struct SidecarProcess(Mutex<Option<CommandChild>>);
+const DEFAULT_PORT: u16 = 3000;
+async fn find_available_port(start: u16) -> u16 { }
+
+// ❌ 避免
+struct sidecar_process { }
+const defaultPort: u16 = 3000;
+```
+
+### 类型注解
+
+- 函数参数必须有类型注解
+- 函数返回值必须明确声明 (除非返回 `()`)
+- 优先使用具体类型而非 `impl Trait` (除非必要)
+- 使用 `&str` 而非 `String` 作为只读字符串参数
+
+```rust
+// ✅ 推荐
+#[tauri::command]
+fn greet(name: &str) -> String {
+    format!("Hello, {}!", name)
+}
+
+async fn is_port_available(port: u16) -> bool {
+    tokio::net::TcpListener::bind(format!("127.0.0.1:{}", port))
+        .await
+        .is_ok()
+}
+```
+
+### 错误处理
+
+- 使用 `Result<T, E>` 返回可能失败的操作
+- 使用 `expect()` 时提供有意义的错误消息 (中文)
+- 避免 `unwrap()` 在生产代码中，除非逻辑上保证不会 panic
+- 使用 `?` 操作符传播错误
+- 记录关键错误信息到控制台
+
+```rust
+// ✅ 推荐
+let sidecar = app_handle
+    .shell()
+    .sidecar("app")
+    .expect("无法找到 app sidecar");
+
+let (mut rx, child) = sidecar.spawn().expect("启动 sidecar 失败");
+
+// 日志记录
+eprintln!("✗ Sidecar App 启动失败");
+println!("✓ Sidecar App 启动成功！");
+
+// ❌ 避免
+let data = read_file().unwrap();  // 无上下文信息
+```
+
+### 异步代码
+
+- 使用 `async/await` 而非手动创建 Future
+- Tauri 内部使用 `tauri::async_runtime::spawn` 启动异步任务
+- 使用 Tokio 的异步 API (如 `tokio::net::TcpListener`)
+- 避免阻塞异步运行时 (使用 `tokio::task::spawn_blocking`)
+
+```rust
+// ✅ 推荐
+tauri::async_runtime::spawn(async move {
+    let port = find_available_port(3000).await;
+    // ...
+});
+```
+
+### 格式化
+
+- 使用 `cargo fmt` 自动格式化
+- 缩进: 4 空格
+- 行宽: 100 字符 (rustfmt 默认)
+- 结构体和枚举的字段每行一个 (如果超过一定长度)
+- 链式调用适当换行提高可读性
+
+### 注释
+
+- 使用中文注释说明复杂逻辑
+- 代码块前添加简短说明注释
+- 避免显而易见的注释
+
+```rust
+// ✅ 推荐
+// 全局状态：存储 Sidecar App 进程句柄
+struct SidecarProcess(Mutex<Option<CommandChild>>);
+
+// 检查端口是否可用
+async fn is_port_available(port: u16) -> bool { }
+```
+
+## Tauri 特定规范
+
+### 模块组织
+
+- **`lib.rs`**: 主入口，负责注册插件、命令、状态管理
+- **`commands/mod.rs`**: 所有 Tauri 命令集中定义，命令必须是 `pub fn`
+- **`sidecar.rs`**: Sidecar 进程管理逻辑，导出公共 API（`spawn_sidecar`, `cleanup_sidecar_process`）
+
+```rust
+// lib.rs - 模块声明
+mod commands;
+mod sidecar;
+
+use sidecar::SidecarProcess;
+
+// 注册命令时使用模块路径
+.invoke_handler(tauri::generate_handler![commands::greet])
+```
+
+### 命令定义
+
+- 使用 `#[tauri::command]` 宏标记命令
+- 命令函数必须是公开的或在 `invoke_handler` 中注册
+- 参数类型必须实现 `serde::Deserialize`
+- 返回类型必须实现 `serde::Serialize`
+
+```rust
+#[tauri::command]
+fn greet(name: &str) -> String {
+    format!("Hello, {}!", name)
+}
+
+// 在 Builder 中注册
+.invoke_handler(tauri::generate_handler![greet])
+```
+
+### 状态管理
+
+- 使用 `app.manage()` 注册全局状态
+- 状态必须实现 `Send + Sync`
+- 使用 `Mutex` 或 `RwLock` 保证线程安全
+
+```rust
+struct SidecarProcess(Mutex<Option<CommandChild>>);
+
+// 注册状态
+app.manage(SidecarProcess(Mutex::new(None)));
+
+// 访问状态
+if let Some(state) = app_handle.try_state::<SidecarProcess>() {
+    *state.0.lock().unwrap() = Some(child);
+}
+```
+
+### Sidecar 进程管理
+
+- Sidecar 二进制必须在 `tauri.conf.json` 的 `bundle.externalBin` 中声明
+- 使用 `app.shell().sidecar()` 启动 sidecar
+- 在应用退出时清理子进程 (监听 `RunEvent::ExitRequested`)
+
+```rust
+// 启动 sidecar
+let sidecar = app_handle
+    .shell()
+    .sidecar("app")
+    .expect("无法找到 app sidecar")
+    .env("PORT", port.to_string());
+
+// 清理进程
+match event {
+    tauri::RunEvent::ExitRequested { .. } | tauri::RunEvent::Exit => {
+        if let Some(child) = process.take() {
+            let _ = child.kill();
+        }
+    }
+    _ => {}
+}
+```
+
+## 依赖管理
+
+- 在 `Cargo.toml` 中明确声明依赖版本
+- 使用语义化版本 (如 `"2"` 表示兼容 2.x.x)
+- 仅启用需要的 feature 以减少编译时间和二进制大小
+
+```toml
+tauri = { version = "2", features = [] }
+tauri-plugin-opener = "2"
+tauri-plugin-shell = "2"
+serde = { version = "1", features = ["derive"] }
+tokio = { version = "1", features = ["net"] }
+```
+
+## 开发工具
+
+推荐安装以下 VSCode 扩展:
+- `tauri-apps.tauri-vscode` - Tauri 官方支持
+- `rust-lang.rust-analyzer` - Rust 语言服务器
+
+## 最佳实践
+
+1. **开发环境配置**: 
+   - 开发模式下需先启动前端开发服务器（`bun run dev`），再启动 Tauri（`tauri dev`）
+   - 生产构建自动打包 sidecar 二进制，无需额外配置
+2. **进程生命周期**: 始终在应用退出时清理子进程和资源
+3. **端口管理**: 
+   - 开发模式固定使用 3000 端口（与开发服务器匹配）
+   - 生产模式使用端口扫描避免硬编码端口冲突
+4. **超时处理**: 异步操作设置合理的超时时间 (如 5 秒)
+5. **日志**: 使用表情符号 (✓/✗/🔧/🚀) 和中文消息提供清晰的状态反馈
+6. **错误退出**: 关键错误时调用 `std::process::exit(1)`
+7. **窗口配置**: 使用 `WebviewWindowBuilder` 动态创建窗口
+
+## 提交代码前检查清单
+
+- [ ] `cargo fmt` 格式化通过
+- [ ] `cargo clippy` 无警告
+- [ ] `cargo check` 编译通过
+- [ ] `cargo test` 测试通过
+- [ ] 更新相关注释和文档
+- [ ] 检查是否有 `unwrap()` 需要替换为 `expect()`
+- [ ] 验证 Tauri 应用正常启动和退出

apps/demo-server/src-tauri/Cargo.toml

@@ -0,0 +1,24 @@
+[package]
+name = "app-desktop"
+version = "0.1.0"
+description = "A Tauri App"
+authors = ["imbytecat"]
+edition = "2021"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[lib]
+# The `_lib` suffix may seem redundant but it is necessary
+# to make the lib name unique and wouldn't conflict with the bin name.
+# This seems to be only an issue on Windows, see https://github.com/rust-lang/cargo/issues/8519
+name = "app_desktop_lib"
+crate-type = ["staticlib", "cdylib", "rlib"]
+
+[build-dependencies]
+tauri-build = { version = "2", features = [] }
+
+[dependencies]
+tauri = { version = "2", features = [] }
+tauri-plugin-shell = "2"
+serde = { version = "1", features = ["derive"] }
+tokio = { version = "1", features = ["net"] }

apps/demo-server/src-tauri/build.rs

@@ -0,0 +1,3 @@
+fn main() {
+    tauri_build::build()
+}

apps/demo-server/src-tauri/capabilities/default.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "../gen/schemas/desktop-schema.json",
+  "identifier": "default",
+  "description": "Capability for the main window",
+  "windows": ["main"],
+  "local": true,
+  "remote": {
+    "urls": [
+      "http://localhost:*",
+      "http://127.0.0.1:*",
+      "http{s}?://localhost(:\\d+)?/*"
+    ]
+  },
+  "permissions": [
+    "core:default",
+    "core:window:allow-set-title",
+    {
+      "identifier": "shell:allow-execute",
+      "allow": [
+        {
+          "name": "binaries/app",
+          "sidecar": true
+        }
+      ]
+    }
+  ]
+}

apps/demo-server/src-tauri/src/commands/mod.rs

@@ -0,0 +1,8 @@
+// 原生桌面功能命令
+// 未来可能包含: 文件对话框、系统通知、剪贴板等
+
+// 示例命令 (可根据需要删除或替换)
+#[tauri::command]
+pub fn greet(name: &str) -> String {
+    format!("Hello, {}! You've been greeted from Rust!", name)
+}

apps/demo-server/src-tauri/src/lib.rs

@@ -0,0 +1,33 @@
+use tauri::Manager;
+
+// 模块声明
+mod commands;
+mod sidecar;
+
+use sidecar::SidecarProcess;
+
+#[cfg_attr(mobile, tauri::mobile_entry_point)]
+pub fn run() {
+    tauri::Builder::default()
+        .plugin(tauri_plugin_shell::init())
+        .setup(|app| {
+            // 注册全局状态
+            app.manage(SidecarProcess(std::sync::Mutex::new(None)));
+
+            // 启动 Sidecar 进程
+            let app_handle = app.handle().clone();
+            sidecar::spawn_sidecar(app_handle);
+
+            Ok(())
+        })
+        .invoke_handler(tauri::generate_handler![commands::greet])
+        .build(tauri::generate_context!())
+        .expect("error while building tauri application")
+        .run(|app_handle, event| {
+            // 监听应用退出事件，清理 Sidecar 进程
+            if let tauri::RunEvent::Exit = event {
+                // 只在 Exit 事件时清理，避免重复执行
+                sidecar::cleanup_sidecar_process(app_handle);
+            }
+        });
+}

apps/demo-server/src-tauri/src/main.rs

@@ -0,0 +1,6 @@
+// Prevents additional console window on Windows in release, DO NOT REMOVE!!
+#![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]
+
+fn main() {
+    app_desktop_lib::run()
+}

apps/demo-server/src-tauri/src/sidecar.rs

@@ -0,0 +1,166 @@
+use std::sync::Mutex;
+use std::time::Duration;
+
+use tauri::Manager;
+use tauri_plugin_shell::process::{CommandChild, CommandEvent};
+use tauri_plugin_shell::ShellExt;
+
+// ===== 配置常量 =====
+
+/// Sidecar App 启动超时时间（秒）
+const STARTUP_TIMEOUT_SECS: u64 = 5;
+
+/// 默认起始端口
+const DEFAULT_PORT: u16 = 3000;
+
+/// 端口扫描范围（从起始端口开始扫描的端口数量）
+const PORT_SCAN_RANGE: u16 = 100;
+
+/// 窗口默认宽度
+const DEFAULT_WINDOW_WIDTH: f64 = 1200.0;
+
+/// 窗口默认高度
+const DEFAULT_WINDOW_HEIGHT: f64 = 800.0;
+
+/// 窗口标题
+const WINDOW_TITLE: &str = "Tauri App";
+
+// ===== 数据结构 =====
+
+/// 全局状态：存储 Sidecar 进程句柄
+pub struct SidecarProcess(pub Mutex<Option<CommandChild>>);
+
+// 检查端口是否可用（未被占用）
+async fn is_port_available(port: u16) -> bool {
+    tokio::net::TcpListener::bind(format!("127.0.0.1:{}", port))
+        .await
+        .is_ok()
+}
+
+// 查找可用端口
+async fn find_available_port(start: u16) -> u16 {
+    for port in start..start + PORT_SCAN_RANGE {
+        if is_port_available(port).await {
+            return port;
+        }
+    }
+    start // 回退到起始端口
+}
+
+/// 启动 Sidecar 进程并创建主窗口
+pub fn spawn_sidecar(app_handle: tauri::AppHandle) {
+    // 检测是否为开发模式
+    let is_dev = cfg!(debug_assertions);
+
+    if is_dev {
+        // 开发模式：直接创建窗口连接到 Vite 开发服务器
+        println!("🔧 开发模式");
+
+        match tauri::WebviewWindowBuilder::new(
+            &app_handle,
+            "main",
+            tauri::WebviewUrl::External("http://localhost:3000".parse().unwrap()),
+        )
+        .title(WINDOW_TITLE)
+        .inner_size(DEFAULT_WINDOW_WIDTH, DEFAULT_WINDOW_HEIGHT)
+        .center()
+        .build()
+        {
+            Ok(_) => println!("✓ 开发窗口创建成功"),
+            Err(e) => {
+                eprintln!("✗ 窗口创建失败: {}", e);
+            }
+        }
+
+        return;
+    }
+
+    // 生产模式：启动 sidecar 二进制
+    tauri::async_runtime::spawn(async move {
+        println!("🚀 生产模式");
+
+        // 查找可用端口
+        let port = find_available_port(DEFAULT_PORT).await;
+        println!("使用端口: {}", port);
+
+        // 启动 sidecar
+        let sidecar = app_handle
+            .shell()
+            .sidecar("app")
+            .expect("无法找到 app")
+            .env("PORT", port.to_string());
+
+        let (mut rx, child) = sidecar.spawn().expect("启动 sidecar 失败");
+
+        // 保存进程句柄到全局状态
+        if let Some(state) = app_handle.try_state::<SidecarProcess>() {
+            *state.0.lock().unwrap() = Some(child);
+        }
+
+        // 监听 stdout，等待服务器就绪信号
+        let start_time = std::time::Instant::now();
+        let timeout = Duration::from_secs(STARTUP_TIMEOUT_SECS);
+        let mut app_ready = false;
+
+        while let Some(event) = rx.recv().await {
+            if let CommandEvent::Stdout(line) = event {
+                let output = String::from_utf8_lossy(&line);
+                println!("App: {}", output);
+
+                // 检测 App 启动成功的标志
+                if output.contains("Listening on:") || output.contains("localhost") {
+                    app_ready = true;
+                    println!("✓ App 启动成功！");
+
+                    // 创建主窗口
+                    let url = format!("http://localhost:{}", port);
+                    tauri::WebviewWindowBuilder::new(
+                        &app_handle,
+                        "main",
+                        tauri::WebviewUrl::External(url.parse().unwrap()),
+                    )
+                    .title(WINDOW_TITLE)
+                    .inner_size(DEFAULT_WINDOW_WIDTH, DEFAULT_WINDOW_HEIGHT)
+                    .center()
+                    .build()
+                    .expect("创建窗口失败");
+
+                    break;
+                }
+            }
+
+            // 超时检查
+            if start_time.elapsed() > timeout {
+                eprintln!("✗ 启动超时: App 未能在 {} 秒内启动", STARTUP_TIMEOUT_SECS);
+                break;
+            }
+        }
+
+        if !app_ready {
+            eprintln!("✗ App 启动失败");
+            std::process::exit(1);
+        }
+    });
+}
+
+/// 清理 Sidecar 进程 (在应用退出时调用)
+pub fn cleanup_sidecar_process(app_handle: &tauri::AppHandle) {
+    let is_dev = cfg!(debug_assertions);
+
+    if is_dev {
+        // 开发模式：退出时发送异常信号（exit 1），让 Turbo 停止 Vite 服务器
+        println!("🔧 开发模式退出，终止所有依赖任务...");
+        std::process::exit(1);
+    }
+
+    // 生产模式：正常清理 sidecar 进程
+    println!("应用退出，正在清理 Sidecar 进程...");
+    if let Some(state) = app_handle.try_state::<SidecarProcess>() {
+        if let Ok(mut process) = state.0.lock() {
+            if let Some(child) = process.take() {
+                let _ = child.kill();
+                println!("✓ Sidecar 进程已终止");
+            }
+        }
+    }
+}

apps/demo-server/src-tauri/tauri.conf.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://schema.tauri.app/config/2",
+  "productName": "app-desktop",
+  "version": "0.1.0",
+  "identifier": "com.imbytecat.app-desktop",
+  "app": {
+    "withGlobalTauri": true,
+    "windows": [],
+    "security": {
+      "csp": null
+    }
+  },
+  "bundle": {
+    "active": true,
+    "targets": "all",
+    "icon": [
+      "icons/32x32.png",
+      "icons/128x128.png",
+      "icons/128x128@2x.png",
+      "icons/icon.icns",
+      "icons/icon.ico"
+    ],
+    "externalBin": ["binaries/app"]
+  }
+}