docs: 添加项目初始化文档，包含完整使用说明

- 添加项目初始化文档，包含架构说明、快速开始、Sidecar 配置、开发指南及项目结构等完整使用说明。
2026-01-17 15:34:07 +08:00
parent 9ac5bfe6e7
commit 368563c685
1 changed files with 196 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,196 @@
+# 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