miaw-ai-desktop

O que é miaw-ai-desktop?

miaw-ai-desktop é um app desktop baseado em Electron, priorizando Windows, que fornece uma interface de chat flutuante simples para “Miaw”. O projeto foca em recriar a UI React existente do Miaw e preservar uma superfície de comandos compatível (incluindo shims de cliente compatíveis com Tauri) para que o app interaja com comandos de back-end suportados para chat, histórico, imagens e screenshots.

O repositório também documenta configuração local via arquivo .env, suporta um endpoint OpenAI compatível com LiteLLM como provedor de modelo padrão e inclui instruções de build para desenvolvimento, produção e empacotamento de EXE para Windows.

Principais Recursos

• UI de janela de chat flutuante (shell Electron) projetada para espelhar a interface Miaw baseada em React existente, incluindo um card de configuração quando o back-end não está disponível.
• Suporte a ícone na bandeja e atalho global (Ctrl+Shift+Space) para mostrar/ocultar a sobreposição de chat.
• Shims de cliente Tauri para módulos @tauri-apps/api (core, event, window, dpi) para que o front-end reutilize chamadas internas existentes.
• Superfície de comandos para streaming de chat e gerenciamento de conversas, incluindo ask_ollama, cancel_generation, reset_conversation, além de operações de histórico de conversas como save_conversation, persist_message, list_conversations, load_conversation e delete_conversation.
• Comandos de imagem e screenshot, incluindo salvamento/remoção de comandos de imagem e comandos de captura de tela (capture_screenshot_command, capture_full_screen_command).
• Hooks de janela/evento e utilitários diversos como notify_frontend_ready, notify_overlay_hidden e open_url; mais get_model_config.

Como Usar miaw-ai-desktop

1. Clone o repositório e copie o template de ambiente fornecido: copie .env.example para .env.
2. Edite .env para apontar para o seu provedor de modelo. Os padrões documentados usam um endpoint OpenAI compatível com LiteLLM com valores como:
   • THUKI_PROVIDER=litellm
   • THUKI_API_BASE_URL=http://127.0.0.1:4000
   • THUKI_API_KEY= (vazio no exemplo)
   • THUKI_SUPPORTED_AI_MODELS=gemma-3-4b-it
3. Execute localmente para desenvolvimento:
   • npm install
   • npm run dev (Alternativamente, o repositório menciona comandos Bun.)
4. Para empacotamento de produção, construa o front-end primeiro (npm run build) e depois execute o Electron sem o servidor de dev Vite (npm run start). Comandos de distribuição para Windows também são fornecidos (dist:portable, dist:win).

Casos de Uso

• Chat flutuante local para prompts rápidos: use o atalho global (Ctrl+Shift+Space) para abrir a sobreposição e interagir via comandos de chat do app.
• Gerenciamento de sessões de chat: salve, liste, carregue e delete histórico de conversas usando a superfície de comandos de histórico integrada ao app.
• Trabalho com fluxos relacionados a imagens: acione comandos que salvam ou removem imagens e realizam limpeza de imagens órfãs ao usar os recursos de imagem da UI de chat.
• Captura de conteúdo do desktop: use comandos de screenshot para fornecer contexto visual pela mesma superfície de comandos exposta à UI.
• Configuração de proxy de modelo local: configure o app para usar um endpoint OpenAI compatível com LiteLLM na URL base especificada em .env, ativando o comportamento do provedor de modelo padrão.

FAQ

O projeto suporta macOS?
O repositório observa que “comandos de permissão/onboarding exclusivos do macOS retornam padrões seguros do Windows”, indicando que o build atual é priorizado para Windows e que o comportamento específico do macOS é tratado de forma conservadora para Windows.

Como o app se conecta a um provedor de modelo de IA?
Por padrão, o provedor de modelo é configurado para usar um endpoint OpenAI compatível com LiteLLM. Você define THUKI_PROVIDER, THUKI_API_BASE_URL, THUKI_API_KEY e os modelos suportados via .env.

A busca está implementada?
O repositório afirma que “a busca está stubada para SandboxUnavailable para que a UI existente renderize o card de configuração”, significando que a busca não é totalmente funcional na implementação atual.

O arrastar e mover janelas do desktop é totalmente nativo?
Não. O arrastar para mover “ainda não é totalmente nativo” e “o movimento da janela ainda é uma tarefa pendente”.

Como os builds de produção são empacotados para Windows?
O repositório fornece comandos de build para Windows, incluindo npm run dist:portable para um EXE portátil e npm run dist:win para um instalador Windows. Também menciona regeneração de ícone para miaw.ico a partir de public/miaw-logo.png para manter a identidade visual sincronizada.

Alternativas

• Clientes desktop de “chat flutuante” que integram com servidores LLM locais: tipicamente focam em uma UI sempre disponível similar, mas podem não reutilizar a superfície de comandos existente do Miaw ou chamadas de cliente compatíveis com Tauri.
• Clientes de chat genéricos para APIs compatíveis com OpenAI (locais ou remotas): úteis se você precisar apenas de uma UI de chat padrão e não requerer o conjunto específico de comandos para conversa/histórico, comandos de imagem e screenshots.
• Construção a partir de uma sobreposição baseada em React com Electron: se quiser controle total sobre atalhos, comportamento da bandeja e conectividade de modelo, uma integração personalizada pode ser mais flexível que um app pré-construído focado em Miaw.
• Outras abordagens de wrapper cross-platform Tauri/Electron: se o objetivo principal for preservar uma superfície de comandos e chamadas de front-end existentes, uma estratégia de wrapper diferente pode se adequar melhor às suas plataformas-alvo e necessidades de comportamento de janela.