101 lines
3.3 KiB
Markdown
101 lines
3.3 KiB
Markdown
# AGENTS.md
|
|
|
|
This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
YwYMusic is a desktop music player built with Tauri 2 + Vue 3 + TypeScript. The app uses Tauri's Rust backend for native OS integration while the UI is built with Vue 3 and Naive UI components.
|
|
|
|
## Development Commands
|
|
|
|
```bash
|
|
# Install dependencies (uses pnpm workspaces)
|
|
pnpm install
|
|
|
|
# Run frontend dev server only (Vite on port 1420)
|
|
pnpm dev
|
|
|
|
# Run Tauri desktop app in dev mode (recommended)
|
|
pnpm tauri dev
|
|
|
|
# Build frontend (with TypeScript checking)
|
|
pnpm build
|
|
|
|
# Build Tauri desktop app for production
|
|
pnpm tauri build
|
|
|
|
# Preview production build
|
|
pnpm preview
|
|
```
|
|
|
|
## Architecture
|
|
|
|
### Frontend (Vue 3 + TypeScript)
|
|
|
|
- **Router**: Uses `createWebHashHistory` (required for Tauri file:// protocol)
|
|
- **State**: Lightweight reactive store pattern in `/src/stores/player.ts` (not Pinia)
|
|
- **UI Library**: Naive UI with auto-import resolver
|
|
- **Path Alias**: `@` maps to `./src`
|
|
|
|
### Backend (Tauri/Rust)
|
|
|
|
- Minimal Rust code in `/src-tauri/src/`
|
|
- Tauri handles native OS integration, window management, and system APIs
|
|
|
|
### Auto-Import Setup
|
|
|
|
**Critical**: This project uses unplugin-auto-import and unplugin-vue-components:
|
|
|
|
- Vue APIs (`ref`, `reactive`, `computed`, etc.) are auto-imported—no need to import from "vue"
|
|
- Naive UI hooks (`useMessage`, `useDialog`, etc.) are auto-imported
|
|
- Naive UI components are auto-imported—no need to register or import them
|
|
- TypeScript declarations are auto-generated in `src/types/auto-imports.d.ts` and `src/types/components.d.ts`
|
|
|
|
When writing Vue components, do not add manual imports for these APIs/components unless the auto-import fails.
|
|
|
|
### API Request Pattern
|
|
|
|
Centralized in `src/utils/request.ts`:
|
|
|
|
- Base URL from `VITE_BASE_API_URL` environment variable (see `.env`)
|
|
- Token stored in localStorage with key `"token"`
|
|
- Request interceptor adds `Authorization: Bearer <token>` header
|
|
- Response interceptor handles success (200) and unauthorized (401) codes
|
|
- Use exported functions: `get()`, `post()`, `put()`, `del()`, or generic `request()`
|
|
- All responses follow `ApiResponse<T>` type: `{ code: number, msg: string, data: T }`
|
|
|
|
### State Management
|
|
|
|
Player state lives in `src/stores/player.ts` using Vue's `reactive()`:
|
|
|
|
```typescript
|
|
playerState.current // Current song
|
|
playerState.queue // Play queue
|
|
playerState.isPlaying // Playing state
|
|
playerState.currentTime // Current playback position
|
|
playerState.volume // Volume level (0-100)
|
|
```
|
|
|
|
Use `playSong(song, queue?)` to update current song and queue.
|
|
|
|
## Key Files
|
|
|
|
- `vite.config.ts` - Vite configuration with auto-import plugins
|
|
- `src/main.ts` - Vue app entry point
|
|
- `src/router/index.ts` - Route definitions
|
|
- `src/utils/request.ts` - Axios instance with interceptors
|
|
- `src/types/global.ts` - Global TypeScript types
|
|
- `src-tauri/tauri.conf.json` - Tauri app configuration
|
|
- `src-tauri/src/lib.rs` - Tauri backend entry point
|
|
|
|
## TypeScript
|
|
|
|
- Base config: `tsconfig.json`
|
|
- Node config: `tsconfig.node.json`
|
|
- Auto-generated types in `src/types/` should not be manually edited
|
|
- Use type imports from `@/types/global.ts` for API responses
|
|
|
|
## Testing Frontend Changes
|
|
|
|
Always run `pnpm tauri dev` to test in the actual desktop environment, as Tauri apps behave differently from web apps (file protocol, window APIs, etc.).
|