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

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.

3.4 KiB Raw Blame History