openbridge-token-usage-viewer/src-tauri/AGENTS.md

AGENTS.md - Tauri Shell 项目开发指南

本文档为 AI 编程助手和开发者提供项目规范、构建命令和代码风格指南。

项目概览

• 项目类型: Tauri v2 桌面应用（轻量级壳子）
• 后端: Rust (Edition 2021)
• 架构: Sidecar 模式 - Sidecar Server 承载主要业务逻辑
• 设计理念: Tauri 仅提供原生桌面能力（文件对话框、系统通知等），Web 逻辑全部由 Sidecar Server 处理
• 异步运行时: Tokio
• Rust 版本: 1.92.0+
• 工具管理: 使用 mise 管理 Rust 和 Tauri CLI 版本（见 mise.toml）

构建、测试、运行命令

开发运行

# 开发模式运行 (带 hot-reload)
tauri dev

# 仅运行 Rust 二进制 (不推荐，需要手动启动 Sidecar Server)
cargo run

构建

# 开发构建 (debug mode)
cargo build

# 生产构建
cargo build --release

# Tauri 应用打包 (生成安装程序)
tauri build

代码检查

# 编译检查 (不生成二进制)
cargo check

# Clippy 代码质量检查
cargo clippy

# Clippy 严格模式 (所有警告视为错误)
cargo clippy -- -D warnings

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

# 自动格式化代码
cargo fmt

测试

# 运行所有测试
cargo test

# 运行单个测试 (按名称过滤)
cargo test test_function_name

# 运行特定模块的测试
cargo test module_name::

# 显示测试输出 (包括 println!)
cargo test -- --nocapture

# 运行单个测试并显示输出
cargo test test_name -- --nocapture

清理

# 清理构建产物
cargo clean

项目结构

tauri-shell/
├── src/
│   ├── main.rs          # 入口文件 (仅调用 lib::run)
│   ├── lib.rs           # 核心应用逻辑 (注册插件、命令、状态)
│   ├── commands/
│   │   └── mod.rs       # 原生桌面功能命令 (文件对话框、通知等)
│   └── sidecar.rs       # Sidecar 进程管理 (启动、端口扫描、清理)
├── binaries/            # Sidecar 二进制文件
│   └── server-*   # Sidecar Server 可执行文件 (示例: server)
├── 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 的顺序，用空行分隔
• 按字母顺序排列
• 优先使用具体导入而非通配符 *

// ✅ 推荐
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

// ✅ 推荐
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 作为只读字符串参数

// ✅ 推荐
#[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
• 使用 ? 操作符传播错误
• 记录关键错误信息到控制台

// ✅ 推荐
let sidecar = app_handle
    .shell()
    .sidecar("server")
    .expect("无法找到 server sidecar");

let (mut rx, child) = sidecar.spawn().expect("启动 sidecar 失败");

// 日志记录
eprintln!("✗ Sidecar Server 启动失败");
println!("✓ Sidecar Server 启动成功！");

// ❌ 避免
let data = read_file().unwrap();  // 无上下文信息

异步代码

• 使用 async/await 而非手动创建 Future
• Tauri 内部使用 tauri::async_runtime::spawn 启动异步任务
• 使用 Tokio 的异步 API (如 tokio::net::TcpListener)
• 避免阻塞异步运行时 (使用 tokio::task::spawn_blocking)

// ✅ 推荐
tauri::async_runtime::spawn(async move {
    let port = find_available_port(3000).await;
    // ...
});

格式化

• 使用 cargo fmt 自动格式化
• 缩进: 4 空格
• 行宽: 100 字符 (rustfmt 默认)
• 结构体和枚举的字段每行一个 (如果超过一定长度)
• 链式调用适当换行提高可读性

注释

• 使用中文注释说明复杂逻辑
• 代码块前添加简短说明注释
• 避免显而易见的注释

// ✅ 推荐
// 全局状态：存储 Sidecar Server 进程句柄
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）

// lib.rs - 模块声明
mod commands;
mod sidecar;

use sidecar::SidecarProcess;

// 注册命令时使用模块路径
.invoke_handler(tauri::generate_handler![commands::greet])

命令定义

• 使用 #[tauri::command] 宏标记命令
• 命令函数必须是公开的或在 invoke_handler 中注册
• 参数类型必须实现 serde::Deserialize
• 返回类型必须实现 serde::Serialize

#[tauri::command]
fn greet(name: &str) -> String {
    format!("Hello, {}!", name)
}

// 在 Builder 中注册
.invoke_handler(tauri::generate_handler![greet])

状态管理

• 使用 app.manage() 注册全局状态
• 状态必须实现 Send + Sync
• 使用 Mutex 或 RwLock 保证线程安全

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)

// 启动 sidecar
let sidecar = app_handle
    .shell()
    .sidecar("server")
    .expect("无法找到 server sidecar")
    .env("NITRO_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 以减少编译时间和二进制大小

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. 进程生命周期: 始终在应用退出时清理子进程和资源
2. 端口管理: 使用端口扫描避免硬编码端口冲突
3. 超时处理: 异步操作设置合理的超时时间 (如 5 秒)
4. 日志: 使用表情符号 (✓/✗) 和中文消息提供清晰的状态反馈
5. 错误退出: 关键错误时调用 std::process::exit(1)
6. 窗口配置: 使用 WebviewWindowBuilder 动态创建窗口

提交代码前检查清单

• cargo fmt 格式化通过
• cargo clippy 无警告
• cargo check 编译通过
• cargo test 测试通过
• 更新相关注释和文档
• 检查是否有 unwrap() 需要替换为 expect()
• 验证 Tauri 应用正常启动和退出