miaw-ai-desktop

miaw-ai-desktop 是什麼？

miaw-ai-desktop 是一個基於 Electron、Windows 優先的桌面應用，提供「Miaw」的簡單浮動聊天介面。專案專注於重現現有的 Miaw React UI，並保留相容命令面板（包含 Tauri 相容客戶端 shims），讓應用能與支援的後端命令互動，涵蓋聊天、歷史、圖片和截圖。

儲存庫也記錄了透過 .env 檔案的本地設定，預設使用 LiteLLM 相容的 OpenAI 端點作為模型提供者，並包含開發、生产和 Windows EXE 封裝的建置指示。

主要功能

• 浮動聊天視窗 UI（Electron 外殼），旨在鏡像現有的 React 版 Miaw 介面，包含後端不可用時的設定卡片。
• 系統匣圖示和全域快捷鍵支援（Ctrl+Shift+Space）來顯示/隱藏聊天覆蓋層。
• Tauri 客戶端 shims 支援 @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 和支援模型。

搜尋功能已實作嗎？

儲存庫表示「搜尋被 stub 為 SandboxUnavailable，讓現有 UI 顯示設定卡片」，意指目前實作中搜尋尚未完全功能。

桌面視窗拖曳和移動完全原生嗎？

否。拖曳移動「尚未完全原生」，且「視窗移動仍是後續任務」。

生產建置如何封裝為 Windows？

儲存庫提供 Windows 建置指令，包含 npm run dist:portable 用於可攜式 EXE，以及 npm run dist:win 用於 Windows 安裝程式。也註明從 public/miaw-logo.png 重新產生 miaw.ico 以同步品牌。

替代方案

• 整合本地 LLM 伺服器的桌面「浮動聊天」客戶端：這些通常專注類似隨時可用 UI，但可能不重用 Miaw 現有命令面板或 Tauri 相容客戶端呼叫。
• OpenAI 相容 API（本地或遠端）的通用聊天客戶端：若只需標準聊天 UI，且不需特定對話/歷史、圖片命令和截圖命令集，則適用。
• 從 React 覆蓋層以 Electron 建置：若想完全控制快捷鍵、系統匣行為和模型連線，自訂整合可能比預建 Miaw 專屬應用更靈活。
• 其他 Tauri/Electron 跨平台包裝方式：若主要目標是保留現有命令面板和前端呼叫，不同包裝策略可能更符合目標平台和視窗行為需求。