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 跨平台包装方法：如果主要目标是保留现有命令面板和前端调用，则不同的包装策略可能更匹配目标平台和窗口行为需求。