miaw-ai-desktop

¿Qué es miaw-ai-desktop?

miaw-ai-desktop es una app de escritorio basada en Electron, priorizada para Windows, que proporciona una interfaz de chat flotante simple para “Miaw”. El proyecto se centra en recrear la interfaz de usuario React existente de Miaw y preservar una superficie de comandos compatible (incluyendo shims de cliente compatibles con Tauri) para que la app interactúe con comandos de backend soportados para chat, historial, imágenes y capturas de pantalla.

El repositorio también documenta la configuración local mediante un archivo .env, soporta un endpoint OpenAI compatible con LiteLLM como proveedor de modelos predeterminado, e incluye instrucciones de compilación para desarrollo, producción y empaquetado de EXE para Windows.

Características principales

• Interfaz de ventana de chat flotante (shell de Electron) diseñada para reflejar la interfaz Miaw basada en React existente, incluyendo una tarjeta de configuración cuando el backend no está disponible.
• Soporte para ícono en la bandeja y acceso directo global (Ctrl+Shift+Space) para mostrar/ocultar la superposición de chat.
• Shims de cliente Tauri para módulos @tauri-apps/api (core, event, window, dpi) para que el frontend reutilice llamadas internas existentes.
• Superficie de comandos para streaming de chat y gestión de conversaciones, incluyendo ask_ollama, cancel_generation, reset_conversation, además de operaciones de historial de conversaciones como save_conversation, persist_message, list_conversations, load_conversation y delete_conversation.
• Comandos para imágenes y capturas de pantalla, incluyendo comandos para guardar/eliminar imágenes y comandos de captura de pantalla (capture_screenshot_command, capture_full_screen_command).
• Hooks de ventana/evento y utilidades varias como notify_frontend_ready, notify_overlay_hidden y open_url; más get_model_config.

Cómo usar miaw-ai-desktop

1. Clona el repositorio y copia la plantilla de entorno proporcionada: copia .env.example a .env.
2. Edita .env para apuntar a tu proveedor de modelos. Los valores predeterminados documentados usan un endpoint OpenAI compatible con LiteLLM, como:
   • THUKI_PROVIDER=litellm
   • THUKI_API_BASE_URL=http://127.0.0.1:4000
   • THUKI_API_KEY= (vacío en el ejemplo)
   • THUKI_SUPPORTED_AI_MODELS=gemma-3-4b-it
3. Ejecuta localmente para desarrollo:
   • npm install
   • npm run dev (Alternativamente, el repositorio menciona comandos de Bun.)
4. Para empaquetado de producción, compila el frontend primero (npm run build) y luego ejecuta Electron sin el servidor de desarrollo Vite (npm run start). También se proporcionan comandos de distribución para Windows (dist:portable, dist:win).

Casos de uso

• Chat flotante local para prompts rápidos: usa el acceso directo global (Ctrl+Shift+Space) para mostrar la superposición e interactuar mediante los comandos de chat de la app.
• Gestión de sesiones de chat: guarda, lista, carga y elimina historial de conversaciones usando la superficie de comandos de historial integrada en la app.
• Trabajo con flujos relacionados con imágenes: activa comandos que guardan o eliminan imágenes y realizan limpieza de imágenes huérfanas al usar las funciones de imágenes de la interfaz de chat.
• Captura de contenido del escritorio: usa comandos de captura de pantalla para alimentar contexto visual a través de la misma superficie de comandos expuesta a la interfaz.
• Configuración de un proxy de modelo local: configura la app para usar un endpoint OpenAI compatible con LiteLLM en la URL base especificada en .env, habilitando el comportamiento del proveedor de modelos predeterminado.

Preguntas frecuentes

¿El proyecto soporta macOS?
El repositorio indica que “los comandos de permisos/onboarding solo para macOS devuelven valores predeterminados seguros de Windows”, lo que significa que la compilación actual es priorizada para Windows y que el comportamiento específico de macOS se maneja de forma conservadora para Windows.

¿Cómo se conecta la app a un proveedor de modelos de IA?
Por defecto, el proveedor de modelos está configurado para usar un endpoint OpenAI compatible con LiteLLM. Configuras THUKI_PROVIDER, THUKI_API_BASE_URL, THUKI_API_KEY y los modelos soportados mediante .env.

¿Está implementada la búsqueda?
El repositorio indica que “la búsqueda está simulada como SandboxUnavailable para que la interfaz existente renderice la tarjeta de configuración”, lo que significa que la búsqueda no es completamente funcional en la implementación actual.

¿El arrastre y movimiento de ventana de escritorio son completamente nativos?
No. El arrastre para mover “aún no es completamente nativo” y “el movimiento de ventana es una tarea pendiente”.

¿Cómo se empaquetan las compilaciones de producción para Windows?
El repositorio proporciona comandos de compilación para Windows, incluyendo npm run dist:portable para un EXE portátil y npm run dist:win para un instalador de Windows. También menciona la regeneración del ícono para miaw.ico desde public/miaw-logo.png para mantener la marca sincronizada.

Alternativas

• Clientes de escritorio “chat flotante” que se integran con servidores LLM locales: estos suelen enfocarse en una interfaz siempre disponible similar, pero pueden no reutilizar la superficie de comandos existente de Miaw ni las llamadas de cliente compatibles con Tauri.
• Clientes de chat genéricos para APIs compatibles con OpenAI (locales o remotas): útiles si solo necesitas una interfaz de chat estándar y no requieres el conjunto específico de comandos para conversaciones/historial, comandos de imágenes y capturas de pantalla.
• Construir desde una superposición basada en React con Electron: si quieres control total sobre accesos directos, comportamiento de bandeja y conectividad de modelos, una integración personalizada puede ser más flexible que usar una app precompilada enfocada en Miaw.
• Otros enfoques de wrappers multiplataforma Tauri/Electron: si tu objetivo principal es preservar una superficie de comandos existente y llamadas del frontend, una estrategia de wrapper diferente puede ajustarse mejor a tus plataformas objetivo y necesidades de comportamiento de ventana.