EzVibeR/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

EzVibeR+ is a desktop Live2D mascot application (desktop pet) built with Tauri v2. It displays interactive Live2D models on a transparent, always-on-top window with a system tray interface.

Key Commands

npm run dev          # Start Vite frontend dev server (port 1420)
npm run build        # TypeScript check + Vite production build
npm run tauri:dev    # Full Tauri development (RUST_BACKTRACE=full)
npm run tauri        # Run Tauri CLI directly

Architecture

Frontend (src/)

File	Purpose
live2d/index.vue	Main mascot view: PixiJS + pixi-live2d-display, model loading, dragging, toolbars
components/Config.vue	Settings panel for model selection, paths, and remote model management
hooks/useBackendEvents.ts	Listens to Tauri events from Rust backend
hooks/useListenEvent.ts	Generic event listener hook
hooks/useUpdate.ts	Version update checker
plugins/index.ts	Bridges Rust commands (via modelserve) to frontend
plugins/modelserve.ts	Exposes model_list command to frontend
plugins/autostart.ts	Autostart plugin binding
plugins/checkupdate.ts	Update checker plugin binding
util/index.ts	Config read/write, throttle utility

Dual Window Model

• live2d.html — The mascot display window using PIXI.js + pixi-live2d-display
• index.html — Configuration/settings window using Vue 3 + NaiveUI

Both are built into the Vite rollup via vite.config.ts multi-entry setup.

Rust Backend (src-tauri/src/)

Module	Purpose
main.rs	App entry, 60-second background loop, tray setup
app/commands.rs	Tauri command handlers: read_file, write_file, model_list, read_config, write_config, get_emotion, get_scheduler_status, get_memory_count, search_memories, interact, chat, trigger_reminder
app/config.rs	AppConf struct for persisting user settings
app/menu.rs	Menu utilities
app/mstruct.rs	Misc structs
modules/brain.rs	LLM integration with RAG; currently NoopLLMProvider (no LLM configured)
modules/emotion.rs	EmotionEngine tracks emotional state and transitions
modules/scheduler.rs	TaskScheduler fires timed behaviors based on uptime
modules/memory.rs	MemorySystem provides vector search over conversation history
plugins/autostart.rs	Tauri plugin for auto-start on login
plugins/checkupdate.rs	Tauri plugin for version checking
utils.rs	Utility functions

Web Server (src-tauri/web_server/)

Separate Cargo workspace member (axum-based) that serves local Live2D model files on a configurable port.

Database

ezvibe_memory.db — SQLite database for the MemorySystem (vector storage via rusqlite). Initialized with a DummyEmbedder (384-dim zero vectors), not a real embedding model.

Communication Flow

Frontend ↔ Tauri IPC → Rust commands (commands.rs) ↔ Subsystems (emotion, scheduler, brain, memory) ↔ web_server serves model files

System Tray

Tray icon with menu items: 显示桌宠, 隐藏桌宠, 配置中心, 关闭软件. Window management done via get_webview_window("main") and get_webview_window("config").

Backend Events (emitted to frontend)

• ezvibe:heartbeat — 60s tick with emotion state, tick count, uptime
• ezvibe:reminder — Fired scheduled behaviors with action details
• ezvibe:action — General action events
• ezvibe:emotion — Emotion state changes

60-Second Background Loop (main.rs:51)

Coordinates all subsystems:

1. scheduler.on_timer_tick() fires scheduled behaviors
2. brain.think() generates responses via LLM (or Noop fallback)
3. Emits ezvibe:heartbeat event to frontend with emotion state