# AGENTS.md

## Project Overview

Wails v2 desktop app ("XK 文件工具箱") — file processing toolbox for PDF, Word, Excel, and images. Go backend + Vue 3 frontend, compiled to native Windows executable.

## Build & Dev Commands

```bash
wails dev          # Development with hot reload (Vite + Go)
wails build        # Production build → build/bin/xk.exe
cd frontend && npm run build   # Frontend only
cd frontend && npm run dev     # Vite dev server only
go build ./...     # Backend only (check compilation)
```

**Prerequisites**: Go 1.25+, Node.js, Wails CLI (`go install github.com/wailsapp/wails/v2/cmd/wails@latest`)

## Architecture

```
main.go           → Wails app entry, binds FileHandler to frontend
handlers.go       → FileHandler: all Go methods exposed to JS via Wails IPC
app.go            → App struct (minimal, unused greeting method)
services/         → Business logic per format
  pdf_service.go    → gopdf-based PDF operations
  word_service.go   → Word to PDF conversion
  excel_service.go  → Excel to CSV/JSON conversion
  image_service.go  → imaging library: compress, resize, rotate, crop, grayscale, brightness, contrast, saturation, flip, removebg
  utils.go          → Path helpers, JSON serialization
frontend/src/
  App.vue           → Root layout: 64px sidebar + main content
  components/
    HomeView.vue    → Tool grid with shortcuts and recent uses
    ToolView.vue    → ALL tool UI in one component (~1800 lines, handles all categories)
    SettingsView.vue → Output directory config
  router/index.js   → Hash router: /, /tool/:category/:action?, /settings
```

## Key Patterns

- **Wails IPC**: Frontend calls Go via `window.go.main.FileHandler.MethodName()`. Bindings auto-generated in `frontend/wailsjs/`.
- **Single tool component**: `ToolView.vue` handles all tools (PDF/Word/Excel/Image) via route params `category` and `action`. Switching tools resets state.
- **Auto-processing**: Image tools auto-process on parameter change (500ms debounce) via `watch` on param refs.
- **CSS variables**: Theme defined in `style.css` `:root` — dark SaaS style with glassmorphism. All colors via CSS vars (`--bg-primary`, `--accent-primary`, etc.).
- **Element Plus**: UI component library. Global overrides in `style.css` with `!important`.
- **Image processing**: Backend uses `github.com/disintegration/imaging`. Frontend can do canvas-based operations (background removal uses in-browser pixel manipulation).

## Gotchas

- `ToolView.vue` is ~1800 lines. Changes to one tool's UI can affect others. Search for the specific tool's section before editing.
- Image processing has TWO preview systems: backend-processed (via `ProcessFile`) and frontend canvas-based (background removal). Don't confuse them.
- `FileResult` returns both `size` (output) and `originalSize` (input) for size comparison display.
- Backend temp files go to `os.TempDir()` with `xk_` prefix. They are never cleaned up automatically.
- The `removebg` tool has both a backend threshold (`req.Threshold`) and a frontend canvas tolerance (`bgRemovalTolerance`). The frontend tolerance is what actually controls the canvas-based removal.
- HomeView.vue had `overflow: hidden` that blocked scrolling — use `overflow: visible` if you see scroll issues.

## UI/UX Skill

`.opencode/skills/ui-ux-pro-max/` contains a searchable design database. Use `python scripts/search.py "<query>" --design-system` to generate design systems. Requires Python 3.