# Tauri Shell

一个基于 Tauri v2 的轻量级桌面应用壳子，使用 Sidecar 模式承载主要业务逻辑。

## 项目特点

- **架构**: Sidecar 模式 - Tauri 仅提供原生桌面能力，Web 逻辑全部由 Sidecar Server 处理
- **后端**: Rust (Edition 2021)
- **异步运行时**: Tokio
- **设计理念**: 分离关注点 - Tauri 负责原生功能（文件对话框、系统通知等），Sidecar 负责业务逻辑

## 快速开始

### 环境要求

- Rust 1.92.0+
- Tauri CLI v2
- Node.js (用于前端构建，如果有的话)

推荐使用 [mise](https://mise.jdx.dev/) 管理工具版本（见 `mise.toml`）。

### 开发运行

```bash
# 开发模式（带 hot-reload）
tauri dev

# 仅运行 Rust 二进制
cargo run
```

### 构建

```bash
# 开发构建
cargo build

# 生产构建
cargo build --release

# 打包应用（生成安装程序）
tauri build
```

## Sidecar 配置

### Sidecar 命名规则

Tauri 使用平台特定的命名约定来识别 Sidecar 二进制文件。在 `tauri.conf.json` 中配置基础名称，Tauri 会自动根据目标平台添加后缀。

#### 配置示例

```json
{
  "bundle": {
    "externalBin": [
      "binaries/server"
    ]
  }
}
```

#### 平台命名规则

Tauri 会根据以下规则查找对应平台的二进制文件：

| 平台 | 架构 | 文件名格式 | 示例 |
|------|------|-----------|------|
| **Windows** | x64 | `{name}-x86_64-pc-windows-msvc.exe` | `server-x86_64-pc-windows-msvc.exe` |
| **Windows** | ARM64 | `{name}-aarch64-pc-windows-msvc.exe` | `server-aarch64-pc-windows-msvc.exe` |
| **macOS** | Intel (x64) | `{name}-x86_64-apple-darwin` | `server-x86_64-apple-darwin` |
| **macOS** | Apple Silicon | `{name}-aarch64-apple-darwin` | `server-aarch64-apple-darwin` |
| **Linux** | x64 | `{name}-x86_64-unknown-linux-gnu` | `server-x86_64-unknown-linux-gnu` |
| **Linux** | ARM64 | `{name}-aarch64-unknown-linux-gnu` | `server-aarch64-unknown-linux-gnu` |

**重要提示**：
- `{name}` 是 `externalBin` 中配置的基础名称（不含路径）
- Windows 平台的可执行文件必须包含 `.exe` 扩展名
- macOS 和 Linux 平台的二进制文件无扩展名
- 文件必须放在 `binaries/` 目录中

#### 目录结构示例

```
tauri-shell/
├── binaries/
│   ├── .gitignore
│   ├── server-x86_64-pc-windows-msvc.exe      # Windows x64
│   ├── server-aarch64-pc-windows-msvc.exe     # Windows ARM64
│   ├── server-x86_64-apple-darwin             # macOS Intel
│   ├── server-aarch64-apple-darwin            # macOS Apple Silicon
│   ├── server-x86_64-unknown-linux-gnu        # Linux x64
│   └── server-aarch64-unknown-linux-gnu       # Linux ARM64
└── tauri.conf.json
```

### Sidecar 进程管理

本项目在 `src/sidecar.rs` 中实现了以下功能：

1. **自动端口扫描**: 从端口 3000 开始查找可用端口
2. **环境变量注入**: 通过 `NITRO_PORT` 等变量配置 Sidecar
3. **进程生命周期管理**: 应用退出时自动清理子进程
4. **超时处理**: 启动超时设置为 5 秒

#### 使用示例

```rust
use tauri::Manager;

// 在 lib.rs 中启动 sidecar
tauri::async_runtime::spawn(async move {
    sidecar::spawn_sidecar(app_handle.clone()).await;
});

// 在应用退出时清理
app.run(move |app_handle, event| {
    sidecar::cleanup_sidecar_process(app_handle, &event);
});
```

## 开发指南

### 代码检查

```bash
# 编译检查
cargo check

# 代码质量检查
cargo clippy

# 格式化检查
cargo fmt -- --check

# 自动格式化
cargo fmt
```

### 测试

```bash
# 运行所有测试
cargo test

# 显示测试输出
cargo test -- --nocapture
```

### 提交前检查

- [ ] `cargo fmt` 格式化通过
- [ ] `cargo clippy` 无警告
- [ ] `cargo check` 编译通过
- [ ] `cargo test` 测试通过
- [ ] 验证 Tauri 应用正常启动和退出

## 项目结构

```
tauri-shell/
├── src/
│   ├── main.rs          # 入口文件
│   ├── lib.rs           # 核心应用逻辑
│   ├── commands/
│   │   └── mod.rs       # Tauri 命令定义
│   └── sidecar.rs       # Sidecar 进程管理
├── binaries/            # Sidecar 二进制文件
├── capabilities/        # Tauri v2 权限配置
├── icons/               # 应用图标资源
├── Cargo.toml          # Rust 项目配置
├── tauri.conf.json     # Tauri 应用配置
└── mise.toml           # 开发工具版本管理
```

## 技术栈

- **Tauri**: v2 (桌面应用框架)
- **Rust**: Edition 2021
- **Tokio**: 异步运行时
- **Serde**: 序列化/反序列化
- **Tauri Plugins**:
  - `tauri-plugin-shell`: Shell 和 Sidecar 支持
  - `tauri-plugin-opener`: 文件/URL 打开支持

## 详细文档

- [AGENTS.md](./AGENTS.md) - AI 编程助手和开发者指南，包含详细的代码风格规范

## License

MIT

## 作者

imbytecat