miaw-ai-desktop

Cos'è miaw-ai-desktop?

miaw-ai-desktop è un'app desktop basata su Electron, pensata principalmente per Windows, che fornisce un'interfaccia chat fluttuante semplice per “Miaw”. Il progetto si concentra sulla ricreazione dell'interfaccia Miaw React esistente e sulla preservazione di una superficie di comandi compatibile (inclusi shim client compatibili con Tauri) in modo che l'app possa interagire con i comandi backend supportati per chat, cronologia, immagini e screenshot.

Il repository documenta anche la configurazione locale tramite file .env, supporta un endpoint OpenAI compatibile con LiteLLM come provider di modello predefinito e include istruzioni di build per sviluppo, produzione e packaging EXE per Windows.

Caratteristiche Principali

• Interfaccia UI finestra chat fluttuante (shell Electron) pensata per rispecchiare l'interfaccia Miaw basata su React esistente, inclusa una scheda di setup quando il backend non è disponibile.
• Supporto icona tray e scorciatoia globale (Ctrl+Shift+Space) per mostrare/nascondere l'overlay chat.
• Shim client Tauri per i moduli @tauri-apps/api (core, event, window, dpi) in modo che il frontend possa riutilizzare le chiamate interne esistenti.
• Superficie di comandi per streaming chat e gestione conversazioni, inclusi ask_ollama, cancel_generation, reset_conversation, oltre a operazioni sulla cronologia conversazioni come save_conversation, persist_message, list_conversations, load_conversation e delete_conversation.
• Comandi per immagini e screenshot, inclusi salvataggio/rimozione comandi immagini e comandi cattura schermo (capture_screenshot_command, capture_full_screen_command).
• Hook finestra/eventi e utility varie come notify_frontend_ready, notify_overlay_hidden e open_url; più get_model_config.

Come Usare miaw-ai-desktop

1. Clona il repository e copia il template ambiente fornito: copia .env.example in .env.
2. Modifica .env per puntare al tuo provider di modello. I valori predefiniti documentati usano un endpoint OpenAI compatibile con LiteLLM, come:
   • THUKI_PROVIDER=litellm
   • THUKI_API_BASE_URL=http://127.0.0.1:4000
   • THUKI_API_KEY= (vuoto nell'esempio)
   • THUKI_SUPPORTED_AI_MODELS=gemma-3-4b-it
3. Esegui localmente per sviluppo:
   • npm install
   • npm run dev (In alternativa, il repo nota comandi Bun.)
4. Per packaging produzione, builda prima il frontend (npm run build) e poi avvia Electron senza server dev Vite (npm run start). Sono forniti anche comandi distribuzione Windows (dist:portable, dist:win).

Casi d'Uso

• Chat fluttuante locale per prompt rapidi: usa la scorciatoia globale (Ctrl+Shift+Space) per aprire l'overlay e interagire tramite i comandi chat dell'app.
• Gestione sessioni chat: salva, elenca, carica ed elimina cronologia conversazioni usando la superficie di comandi storia integrata nell'app.
• Lavoro con flussi immagini: attiva comandi che salvano o rimuovono immagini e puliscono immagini orfane quando usi le feature immagini dell'UI chat.
• Cattura contenuti dal desktop: usa comandi screenshot per fornire contesto visivo tramite la stessa superficie di comandi esposta all'UI.
• Setup proxy modello locale: configura l'app per usare un endpoint OpenAI compatibile con LiteLLM all'URL base specificato in .env, abilitando il comportamento provider di modello predefinito.

FAQ

Il progetto supporta macOS? Il repository nota che “i comandi permessi/onboarding solo macOS restituiscono default Windows sicuri”, indicando che la build attuale è Windows-first e che il comportamento macOS-specifico è gestito in modo conservativo per Windows.

Come si connette l'app a un provider di modello AI? Per default, il provider di modello è configurato per usare un endpoint OpenAI compatibile con LiteLLM. Imposti THUKI_PROVIDER, THUKI_API_BASE_URL, THUKI_API_KEY e i modelli supportati tramite .env.

La ricerca è implementata? Il repository afferma che “la ricerca è stubbed a SandboxUnavailable così l'UI esistente rende la scheda setup”, il che significa che la ricerca non è pienamente funzionale nell'implementazione attuale.

Il trascinamento e movimento finestra desktop sono pienamente nativi? No. Il trascinamento per muovere è “non ancora pienamente nativo” e “il movimento finestra è ancora un task successivo”.

Come sono packagati i build produzione per Windows? Il repo fornisce comandi build Windows inclusi npm run dist:portable per un EXE portatile e npm run dist:win per un installer Windows. Nota anche la rigenerazione icona per miaw.ico da public/miaw-logo.png per mantenere il branding sincronizzato.

Alternative

• Client desktop “chat fluttuante” che integrano con server LLM locali: tipicamente focalizzati su UI sempre disponibile simile, ma potrebbero non riutilizzare la superficie di comandi Miaw esistente o chiamate client Tauri-compatibili.
• Client chat generici per API OpenAI-compatibili (locali o remote): utili se hai bisogno solo di un'UI chat standard e non richiedi il set di comandi specifico per conversazioni/cronologia, comandi immagini e screenshot.
• Costruire da overlay React-based con Electron: se vuoi pieno controllo su scorciatoie, comportamento tray e connettività modello, un'integrazione custom potrebbe essere più flessibile di un'app Miaw prebuilt.
• Altre approcci wrapper cross-platform Tauri/Electron: se il tuo obiettivo principale è preservare una superficie di comandi esistente e chiamate frontend, una strategia wrapper diversa potrebbe adattarsi meglio alle tue piattaforme target e bisogni comportamento finestra.