61 lines
3.4 KiB
Markdown
61 lines
3.4 KiB
Markdown
|
# 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.
|