miaw-ai-desktop

miaw-ai-desktop이란?

miaw-ai-desktop은 Electron 기반 Windows 우선 데스크톱 앱으로, “Miaw”의 간단한 부유형 채팅 인터페이스를 제공합니다. 이 프로젝트는 기존 Miaw React UI를 재현하고 호환 명령 표면(타우리 호환 클라이언트 심 포함)을 유지하여 채팅, 히스토리, 이미지, 스크린샷 백엔드 명령과 상호작용할 수 있도록 합니다.

리포지토리는 .env 파일을 통한 로컬 설정을 문서화하고, 기본 모델 제공자로 LiteLLM 호환 OpenAI 엔드포인트를 지원하며, 개발, 프로덕션, Windows EXE 패키징 빌드 지침을 포함합니다.

주요 기능

• 기존 React 기반 Miaw 인터페이스를 반영한 부유형 채팅 창 UI(Electron 쉘), 백엔드 미연결 시 설정 카드 포함.
• 채팅 오버레이 표시/숨김을 위한 트레이 아이콘 및 전역 단축키(Ctrl+Shift+Space) 지원.
• @tauri-apps/api 모듈(core, event, window, dpi)에 대한 타우리 클라이언트 심으로 프론트엔드에서 기존 내부 호출 재사용.
• 채팅 스트리밍 및 대화 관리 명령 표면: ask_ollama, cancel_generation, reset_conversation 등, 대화 히스토리 작업(save_conversation, persist_message, list_conversations, load_conversation, delete_conversation) 포함.
• 이미지 및 스크린샷 명령: 이미지 명령 저장/제거, 화면 캡처 명령(capture_screenshot_command, capture_full_screen_command).
• 창/이벤트 훅 및 기타 유틸리티: notify_frontend_ready, notify_overlay_hidden, open_url; get_model_config 포함.

miaw-ai-desktop 사용 방법

1. 리포지토리 클론 후 제공된 환경 템플릿 복사: .env.example을 .env로 복사.
2. .env 편집하여 모델 제공자 지정. 문서화된 기본값은 LiteLLM 호환 OpenAI 엔드포인트 사용:
   • THUKI_PROVIDER=litellm
   • THUKI_API_BASE_URL=http://127.0.0.1:4000
   • THUKI_API_KEY= (예시에서 비어 있음)
   • THUKI_SUPPORTED_AI_MODELS=gemma-3-4b-it
3. 개발용 로컬 실행:
   • npm install
   • npm run dev (대안으로 리포지토리 Bun 명령 참조.)
4. 프로덕션 패키징 시 프론트엔드 먼저 빌드(npm run build) 후 Vite 개발 서버 없이 Electron 실행(npm run start). Windows 배포 명령도 제공(dist:portable, dist:win).

사용 사례

• 빠른 프롬프트용 로컬 부유형 채팅: 전역 단축키(Ctrl+Shift+Space)로 오버레이 표시 후 앱 채팅 명령 상호작용.
• 채팅 세션 관리: 앱 내장 히스토리 명령 표면으로 대화 히스토리 저장, 나열, 로드, 삭제.
• 이미지 관련 워크플로우 작업: 채팅 UI 이미지 기능 사용 시 이미지 저장/제거 명령 및 고아 이미지 정리 트리거.
• 데스크톱 콘텐츠 캡처: UI에 노출된 동일 명령 표면으로 스크린샷 명령 사용해 시각적 컨텍스트 제공.
• 로컬 모델 프록시 설정: .env 지정 기본 URL의 LiteLLM 호환 OpenAI 엔드포인트로 앱 구성하여 기본 모델 제공자 동작 활성화.

자주 묻는 질문

macOS를 지원하나요?
리포지토리는 “macOS 전용 권한/온보딩 명령이 안전한 Windows 기본값 반환”이라고 명시하여 현재 빌드가 Windows 우선이며 macOS 특정 동작을 Windows에서 보수적으로 처리함을 나타냅니다.

앱이 AI 모델 제공자에 어떻게 연결하나요?
기본적으로 LiteLLM 호환 OpenAI 엔드포인트를 모델 제공자로 구성합니다. .env로 THUKI_PROVIDER, THUKI_API_BASE_URL, THUKI_API_KEY, 지원 모델 설정.

검색이 구현되었나요?
리포지토리는 “검색이 SandboxUnavailable로 스텁되어 기존 UI가 설정 카드 렌더링”이라고 하여 현재 구현에서 검색이 완전하지 않음을 의미합니다.

데스크톱 창 드래그 및 이동이 완전 네이티브인가요?
아니요. 드래그-이동은 “아직 완전 네이티브 아님”, “창 이동은 후속 작업”입니다.

Windows 프로덕션 빌드는 어떻게 패키징하나요?
리포지토리는 휴대용 EXE용 npm run dist:portable과 Windows 설치 프로그램용 npm run dist:win 빌드 명령 제공. public/miaw-logo.png에서 miaw.ico 아이콘 재생성으로 브랜딩 동기화도 명시.

대안

• 로컬 LLM 서버와 통합된 데스크톱 “부유형 채팅” 클라이언트: 유사 항상 사용 가능 UI 중심이지만 Miaw 기존 명령 표면이나 타우리 호환 클라이언트 호출 재사용 안 할 수 있음.
• OpenAI 호환 API(로컬/원격)용 일반 채팅 클라이언트: 표준 채팅 UI만 필요하고 대화/히스토리, 이미지 명령, 스크린샷 명령 세트 불필요 시 유용.
• Electron으로 React 기반 오버레이 빌드: 단축키, 트레이 동작, 모델 연결 완전 제어 원할 시 사전 빌드 Miaw 중심 앱보다 유연할 수 있음.
• 다른 Tauri/Electron 크로스플랫폼 래퍼 접근: 기존 명령 표면 및 프론트엔드 호출 유지 목표 시 대상 플랫폼과 창 동작 요구에 더 적합한 래퍼 전략 가능.