refactor: 重构项目结构与文件命名规范
- 移除已过时的忽略规则并更新 Cargo 和 Tauri 生成文件的忽略配置 - 删除已过时的项目协作指南文件AGENTS.md - 重命名 binaries/.gitignore 文件以保持项目结构一致性 - 重命名构建脚本文件以符合项目根目录的规范 - 删除了包含所有依赖项及其哈希值的锁文件，移除了项目所有构建工具和平台特定二进制文件的详细版本信息。 - 重命名能力配置文件以统一路径结构 - 重命名 Cargo.lock 文件以匹配项目根目录的命名规范 - 重命名 Cargo.toml 文件以统一项目根目录的配置文件路径 - 重命名图标文件以统一项目中的资源路径 - 重命名图标文件以正确反映其在项目中的位置 - 重命名图标文件以正确反映其在项目中的位置 - 重命名图标文件以统一项目中的资源路径结构 - 重命名图标文件路径以保持项目结构一致性 - 重命名图标文件以统一项目资源路径 - 重命名图标文件以正确反映其在项目中的新路径 - 重命名图标文件以正确匹配新路径结构 - 重命名图标文件以正确反映其在项目中的位置 - 重命名图标文件以匹配新路径结构 - 重命名图标文件以正确反映其在项目中的位置 - 重命名图标文件以匹配新的项目路径结构 - 重命名图标文件以正确反映其在项目中的新路径 - 重命名图标文件以正确反映其在项目中的新路径 - 重命名图标文件以正确反映其在项目中的位置 - 重命名图标文件以正确反映其在项目中的位置 - 删除项目中的 package.json 文件及其中定义的依赖和脚本配置 - 删除 README.md 文件 - 删除不再需要的构建和生成文件忽略规则 - 重命名源文件路径以符合项目结构规范 - 重命名主源文件路径以符合项目结构规范 - 重命名 tauri.conf.json 文件以统一配置文件路径
This commit is contained in:
283
AGENTS.md
283
AGENTS.md
@@ -1,283 +0,0 @@
|
||||
# AGENTS.md - Coding Agent Guide
|
||||
|
||||
This file provides essential information for AI coding agents working in this repository.
|
||||
|
||||
## 📋 Project Overview
|
||||
|
||||
**Tech Stack**: Tauri 2.x Desktop Application
|
||||
- **Frontend**: Vanilla TypeScript + Vite 6.0.3
|
||||
- **Backend**: Rust (edition 2021)
|
||||
- **Package Manager**: Bun (preferred) or npm
|
||||
- **Build Tool**: Vite + Tauri CLI
|
||||
- **Runtime**: mise (for Rust toolchain management)
|
||||
|
||||
**Project Structure**:
|
||||
```
|
||||
tauri-demo/
|
||||
├── src/ # Frontend TypeScript/HTML/CSS
|
||||
│ ├── main.ts # Application entry point
|
||||
│ ├── styles.css # Global styles
|
||||
│ └── assets/ # Static resources
|
||||
├── src-tauri/ # Rust backend
|
||||
│ ├── src/ # Rust source code
|
||||
│ │ ├── main.rs # Rust entry
|
||||
│ │ └── lib.rs # Tauri commands
|
||||
│ ├── Cargo.toml # Rust dependencies
|
||||
│ ├── tauri.conf.json # Tauri configuration
|
||||
│ ├── capabilities/ # Permission configs
|
||||
│ └── icons/ # Multi-platform icons
|
||||
├── index.html # HTML entry
|
||||
├── package.json # Node.js config
|
||||
├── tsconfig.json # TypeScript config
|
||||
└── vite.config.ts # Vite config
|
||||
```
|
||||
|
||||
## 🔧 Build/Lint/Test Commands
|
||||
|
||||
### Development
|
||||
```bash
|
||||
# Start frontend dev server (port 1420)
|
||||
bun run dev
|
||||
|
||||
# Start Tauri in dev mode (recommended for full app testing)
|
||||
bun run tauri dev
|
||||
|
||||
# Preview production build
|
||||
bun run preview
|
||||
```
|
||||
|
||||
### Building
|
||||
```bash
|
||||
# Build frontend only (TypeScript compile + Vite bundle)
|
||||
bun run build
|
||||
|
||||
# Build complete Tauri application (all platforms)
|
||||
bun run tauri build
|
||||
|
||||
# Build for specific platform
|
||||
bun run tauri build --target x86_64-pc-windows-msvc # Windows
|
||||
bun run tauri build --target x86_64-apple-darwin # macOS
|
||||
bun run tauri build --target x86_64-unknown-linux-gnu # Linux
|
||||
```
|
||||
|
||||
### Type Checking
|
||||
```bash
|
||||
# TypeScript type check (run before build)
|
||||
tsc --noEmit
|
||||
|
||||
# Watch mode for continuous type checking
|
||||
tsc --noEmit --watch
|
||||
```
|
||||
|
||||
### Rust Commands
|
||||
```bash
|
||||
# Check Rust code (fast compile check)
|
||||
cd src-tauri && cargo check
|
||||
|
||||
# Format Rust code
|
||||
cd src-tauri && cargo fmt
|
||||
|
||||
# Lint Rust code
|
||||
cd src-tauri && cargo clippy
|
||||
|
||||
# Run Rust tests
|
||||
cd src-tauri && cargo test
|
||||
|
||||
# Run a specific Rust test
|
||||
cd src-tauri && cargo test test_name
|
||||
|
||||
# Run tests with output
|
||||
cd src-tauri && cargo test -- --nocapture
|
||||
```
|
||||
|
||||
### Testing
|
||||
**Note**: No test framework is currently configured. To add testing:
|
||||
|
||||
**Frontend Testing** (recommended: Vitest):
|
||||
```bash
|
||||
bun add -D vitest @vitest/ui
|
||||
# Run all tests: bun run vitest
|
||||
# Run single test: bun run vitest path/to/test.test.ts
|
||||
```
|
||||
|
||||
**Rust Testing**: Use built-in `cargo test` (see above)
|
||||
|
||||
## 📐 Code Style Guidelines
|
||||
|
||||
### TypeScript/JavaScript
|
||||
|
||||
#### Imports
|
||||
- Use ES6 imports: `import { foo } from "bar"`
|
||||
- Tauri API imports: `import { invoke } from "@tauri-apps/api/core"`
|
||||
- Group imports: external packages first, then local modules
|
||||
- No unused imports (enforced by `noUnusedLocals`)
|
||||
|
||||
Example:
|
||||
```typescript
|
||||
import { invoke } from "@tauri-apps/api/core";
|
||||
import { open } from "@tauri-apps/plugin-opener";
|
||||
|
||||
import { helperFunction } from "./utils";
|
||||
```
|
||||
|
||||
#### Types
|
||||
- **Always use explicit types** for function parameters and return values
|
||||
- Use type inference for simple variable assignments
|
||||
- Prefer `interface` for object shapes, `type` for unions/intersections
|
||||
- Enable all strict mode checks (already configured in tsconfig.json)
|
||||
|
||||
Example:
|
||||
```typescript
|
||||
// Good ✅
|
||||
async function greet(name: string): Promise<string> {
|
||||
return await invoke("greet", { name });
|
||||
}
|
||||
|
||||
// Bad ❌
|
||||
async function greet(name) {
|
||||
return await invoke("greet", { name });
|
||||
}
|
||||
```
|
||||
|
||||
#### Naming Conventions
|
||||
- **Variables/Functions**: camelCase (`greetUser`, `userName`)
|
||||
- **Constants**: UPPER_SNAKE_CASE (`MAX_RETRIES`, `API_URL`)
|
||||
- **Types/Interfaces**: PascalCase (`UserData`, `AppConfig`)
|
||||
- **Private members**: prefix with underscore (`_internalState`)
|
||||
|
||||
#### Error Handling
|
||||
- Always handle promises with `async/await` or `.catch()`
|
||||
- Use try-catch for critical operations
|
||||
- Provide meaningful error messages
|
||||
|
||||
Example:
|
||||
```typescript
|
||||
async function callRustCommand(): Promise<void> {
|
||||
try {
|
||||
const result = await invoke<string>("greet", { name: "World" });
|
||||
console.log(result);
|
||||
} catch (error) {
|
||||
console.error("Failed to call Rust command:", error);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Rust
|
||||
|
||||
#### Formatting
|
||||
- Use `cargo fmt` (rustfmt) for automatic formatting
|
||||
- 4 spaces for indentation (standard Rust)
|
||||
- Line length: 100 characters (rustfmt default)
|
||||
|
||||
#### Naming Conventions
|
||||
- **Functions/Variables**: snake_case (`greet_user`, `user_name`)
|
||||
- **Types/Structs/Enums**: PascalCase (`UserData`, `AppState`)
|
||||
- **Constants**: SCREAMING_SNAKE_CASE (`MAX_CONNECTIONS`)
|
||||
- **Lifetimes**: lowercase single letter (`'a`, `'static`)
|
||||
|
||||
#### Tauri Commands
|
||||
- Mark with `#[tauri::command]` attribute
|
||||
- Use `&str` for string parameters (efficient)
|
||||
- Return owned types (`String`, not `&str`)
|
||||
- Register in `invoke_handler!` macro
|
||||
|
||||
Example:
|
||||
```rust
|
||||
#[tauri::command]
|
||||
fn process_data(input: &str, count: i32) -> Result<String, String> {
|
||||
if count < 0 {
|
||||
return Err("Count must be non-negative".to_string());
|
||||
}
|
||||
Ok(format!("Processed {} with count {}", input, count))
|
||||
}
|
||||
|
||||
// Register in lib.rs:
|
||||
.invoke_handler(tauri::generate_handler![process_data])
|
||||
```
|
||||
|
||||
#### Error Handling
|
||||
- Use `Result<T, E>` for fallible operations
|
||||
- Prefer `?` operator for error propagation
|
||||
- Use `expect()` only when panic is acceptable
|
||||
- Return descriptive error messages
|
||||
|
||||
Example:
|
||||
```rust
|
||||
#[tauri::command]
|
||||
fn read_config() -> Result<Config, String> {
|
||||
let data = std::fs::read_to_string("config.json")
|
||||
.map_err(|e| format!("Failed to read config: {}", e))?;
|
||||
|
||||
serde_json::from_str(&data)
|
||||
.map_err(|e| format!("Invalid JSON: {}", e))
|
||||
}
|
||||
```
|
||||
|
||||
## 🔌 Tauri-Specific Patterns
|
||||
|
||||
### Frontend → Rust Communication
|
||||
```typescript
|
||||
import { invoke } from "@tauri-apps/api/core";
|
||||
|
||||
// Simple command
|
||||
const result = await invoke<string>("command_name", { param: value });
|
||||
|
||||
// With error handling
|
||||
try {
|
||||
const data = await invoke<ReturnType>("command", args);
|
||||
} catch (error) {
|
||||
console.error("Command failed:", error);
|
||||
}
|
||||
```
|
||||
|
||||
### Adding New Commands
|
||||
1. Define in `src-tauri/src/lib.rs`:
|
||||
```rust
|
||||
#[tauri::command]
|
||||
fn new_command(param: &str) -> String {
|
||||
// implementation
|
||||
}
|
||||
```
|
||||
|
||||
2. Register in `invoke_handler`:
|
||||
```rust
|
||||
.invoke_handler(tauri::generate_handler![greet, new_command])
|
||||
```
|
||||
|
||||
3. Call from frontend:
|
||||
```typescript
|
||||
await invoke("new_command", { param: "value" });
|
||||
```
|
||||
|
||||
## 📦 Dependencies
|
||||
|
||||
### Adding Dependencies
|
||||
|
||||
**Frontend**:
|
||||
```bash
|
||||
bun add package-name # Production dependency
|
||||
bun add -D package-name # Dev dependency
|
||||
```
|
||||
|
||||
**Rust**:
|
||||
```bash
|
||||
cd src-tauri
|
||||
cargo add package-name # Production dependency
|
||||
cargo add --dev package-name # Dev dependency
|
||||
```
|
||||
|
||||
## ⚠️ Common Pitfalls
|
||||
|
||||
1. **Port conflicts**: Dev server uses port 1420, HMR uses 1421
|
||||
2. **Type mismatches**: Ensure Rust return types match TypeScript expectations
|
||||
3. **Missing command registration**: New Tauri commands must be added to `generate_handler!`
|
||||
4. **Permission issues**: Update `src-tauri/capabilities/default.json` for new capabilities
|
||||
5. **Build errors**: Run `tsc` before `vite build` (automated in build script)
|
||||
|
||||
## 🚀 Workflow Tips
|
||||
|
||||
- Always run `tsc --noEmit` before committing to catch type errors
|
||||
- Test Tauri commands with `bun run tauri dev`, not just `bun run dev`
|
||||
- Use `cargo clippy` to catch common Rust mistakes
|
||||
- Check both frontend and Rust console for errors during development
|
||||
- Clear Vite cache if seeing stale builds: `rm -rf node_modules/.vite`
|
||||
Reference in New Issue
Block a user