开源 macOS 多模态 AI 助手

macOSpilot 可以在任何应用中回答你关于任何内容的问题，无需切换到其他窗口。只需使用键盘快捷键唤起助手，通过语音或文字输入问题，它就能在几秒内结合当前上下文，以文字和音频形式给出答案。在后台，macOSpilot 会在触发时截取当前活动窗口的屏幕截图，并将其与问题的转写文本一起发送给 OpenAI GPT Vision。答案将以文字形式显示，并通过 OpenAI TTS（text to speech，文本转语音）转换成音频。

适用于 macOS 中的任何应用： macOSpilot 与具体应用无关。触发助手时，它只会截取当前活动窗口的屏幕截图。

使用键盘快捷键触发，并说出你的问题： 无需在多个窗口之间来回切换，只需按下键盘快捷键，然后说出问题。如果你更喜欢打字，也可以使用文字输入。

结合上下文并通过音频回答： 问题的答案会显示在当前活动窗口上方的一个小型悬浮窗口中，同时还会通过音频播放（使用 text-to-speech）。

macOSpilot 基于 NodeJS/Electron 运行。只需安装 NodeJS 项目及其依赖（参见下文），并在 index.js 中完成必要配置。之后，你可以选择在终端运行 yarn start，也可以按照下方说明使用 Electron 将其打包。添加 OpenAI API key 后，让应用在后台运行即可。

需要使用 macOSpilot 时，请按下你配置的键盘快捷键（默认为 Command+Shift+'）。macOSpilot 会截取当前活动的 macOS 应用窗口，并启用麦克风。

对着麦克风说出你的问题，然后再次按下相同的键盘快捷键，结束麦克风录音。如果启用了文字输入，你可以直接输入问题并按 Enter，而不必使用语音。

macOSpilot 会将你的问题发送到 OpenAI 的 Whisper API，随后把转写文本连同屏幕截图一起发送到 OpenAI 的 Vision API。

Vision API 的响应会显示在当前活动 macOS 应用窗口上方的一个小型通知窗口中；经 OpenAI 的 TTS（text to speech）API 处理后，答案还会被朗读出来。

当前会话中问题答案的简单历史记录，会显示在另一个可以隐藏或最小化的窗口中。

最近一次屏幕截图、音频录音和 TTS 响应会存储在你的设备上，部分目的是便于调试。每次都会使用相同的文件名，因此旧文件会被覆盖；但在关闭或删除应用时，这些文件不会被自动删除。

更喜欢看视频？可以前往 YouTube 观看演示，了解如何开始使用、应用如何运行，以及对其底层工作原理的简要说明。

请确保你的设备已经安装 NodeJS。然后克隆 repo，并按照以下步骤操作。

git  clone  https://github.com/elfvingralf/macOSpilot-ai-assistant.git

进入该文件夹，然后运行 yarn install 或 npm install。这应该会安装所有依赖。

运行 yarn start 或 npm start。由于应用需要读取屏幕、使用麦克风以及读写文件等权限，你需要按照系统提示授予相关访问权限，并且可能需要重启终端。

请点击主窗口右上角的设置图标，添加你的 OpenAI API key。（它不会被加密存储！）

如果你想修改默认值，以下是一些可能值得调整的内容，它们都位于 index.js 中：

键盘快捷键： 默认键盘快捷键 keyboardShortcut 设置为 "CommandOrControl+Shift+'"（因为其他应用似乎很少使用这个组合键）。

键盘快捷键： 默认键盘快捷键 keyboardShortcut 设置为 "CommandOrControl+Shift+'"（因为其他应用似乎很少使用这个组合键）。

OpenAI Vision prompt： conversationHistory 中的 OpenAI Vision API system prompt，目前仅设置为 "You are helping users with questions about their macOS applications based on screenshots, always answer in at most one sentence."

OpenAI Vision prompt： conversationHistory 中的 OpenAI Vision API system prompt，目前仅设置为 "You are helping users with questions about their macOS applications based on screenshots, always answer in at most one sentence."

VisionAPI 图像尺寸： 为了节省一些费用，可以调整图像大小参数。我在 callVisionAPI() 中保留了一个实现示例（我发现使用它时，结果质量会差很多）。

VisionAPI 图像尺寸： 为了节省一些费用，可以调整图像大小参数。我在 callVisionAPI() 中保留了一个实现示例（我发现使用它时，结果质量会差很多）。

应用窗口尺寸和设置： 主窗口尺寸由 mainWindowWidth 和 mainWindowHeight 控制。始终置顶的通知窗口尺寸由 notificationWidth 和 notificationHeight 控制。

应用窗口尺寸和设置： 主窗口尺寸由 mainWindowWidth 和 mainWindowHeight 控制。始终置顶的通知窗口尺寸由 notificationWidth 和 notificationHeight 控制。

更多通知窗口设置： 通知窗口的透明度由 notificationOpacity 控制。通知窗口激活时，相对于当前活动窗口移动到的位置，在 positionNotificationAtTopRight() 中设置（我知道，这个命名很糟糕）。

更多通知窗口设置： 通知窗口的透明度由 notificationOpacity 控制。通知窗口激活时，相对于当前活动窗口移动到的位置，在 positionNotificationAtTopRight() 中设置（我知道，这个命名很糟糕）。

使用 Electron 将其转换为 .app

想创建一个 .app 可执行文件，而不是每次都从终端运行吗？

首先打开 index.js，将 const useElectronPackager 从 false 修改为 true。

根据你使用的平台，在终端中运行以下命令之一。

npm  run  package-mac
npm  run  package-win
npm  run  package-linux

请注意，我只在 Mac 上测试过它，包括 Apple silicon 和 Intel 机型。

进入项目文件夹中的 /release-builds/，然后选择与你的平台对应的文件夹。其中包含一个可执行文件；如果你使用的是 Mac，它就是一个 .app 文件。双击即可打开应用。请注意，首次启动可能需要几秒钟，请耐心等待。

应用打开后，触发你配置的键盘快捷键。系统会要求你授予 Privacy & Security 权限。为了让所有权限正常生效，你可能需要再重复操作一两次，并重新启动应用。

我希望进行的一些改进，以下排名不分先后

• 支持选择性地在不同会话之间（打开或关闭应用后）保留对话状态
• 使用 buffer，而不是将屏幕截图和音频文件写入磁盘后再读取
• 在 UI 中提供助手音频配置（例如调整速度、将音频播放设为可选）
• 在 UI 中提供始终置顶窗口的配置（例如切换固定位置、启用或禁用）
• 在 UI 中提供屏幕截图设置（例如选择区域或截取整个屏幕）
• 修复以 .app 运行时麦克风无法工作的问题——已在 @claar 的帮助下修复
• 支持使用文字输入代替语音

我是自学编程的，非常喜欢东拼西凑地做一些有趣的项目。我写出的代码能够运行，但可能既不漂亮，也不高效。我把它们分享出来，是希望其他人或许会觉得有用。

你可以在 Twitter/X 上通过 @ralfelfving 找到我。如果你喜欢这个项目，也可以看看我的 YouTube 频道 @ralfelfving 上发布的教程。