macOSpilot：您的个人 macOS AI 助手

macOSpilot 可以在任何应用程序中回答您提出的任何问题。无需切换到其他窗口。只需使用键盘快捷键触发助手，说出或输入您的问题，它就会在几秒钟内以情境化的方式并以语音形式给出答案。在后台，macOSpilot 会在被触发时截取当前活动窗口的屏幕截图，并将其连同您问题的转录文本一起发送给 OpenAI GPT Vision。随后，答案将以文本形式显示，并通过 OpenAI TTS（文本转语音）技术转换为语音。

https://github.com/elfvingralf/macOSpilot-ai-assistant/assets/94417497/5a9e9288-0479-4def-9a87-451dddd783af

• 适用于 macOS 中的任何应用程序： macOSpilot 不依赖于特定的应用程序，当您触发助手时，它只会截取当前活动窗口的屏幕截图。
• 通过键盘快捷键触发，直接提问： 无需在多个窗口之间切换，只需按下快捷键并说出您的问题即可。如果您更喜欢打字，也可以直接输入。
• 情境化且语音化的回答： 您的问题答案会以一个小窗口的形式叠加在您当前活动的窗口之上显示，并通过文本转语音功能以语音形式播报。

工作原理

1. macOSpilot 基于 NodeJS 和 Electron 构建。只需安装 NodeJS 项目及其依赖项（见下文），并在 index.js 中进行必要的配置。然后您可以选择在终端中运行 yarn start，或者按照以下说明使用 Electron 打包应用，添加您的 OpenAI API 密钥，并让应用程序在后台运行。
2. 当您需要使用 macOSpilot 时，按下您已配置的键盘快捷键（默认为 Command+Shift+'）。macOSpilot 将截取您当前 macOS 应用程序窗口的屏幕截图，并激活麦克风。
3. 向麦克风说出您的问题，然后再次按下相同的键盘快捷键以结束录音。如果您启用了文本输入功能，则可以直接输入问题并按 Enter 键，而无需说话。
4. macOSpilot 会将您的问题发送至 OpenAI 的 Whisper API 进行转录，并将转录结果与屏幕截图一同发送至 OpenAI 的 Vision API。
5. Vision API 返回的答案将在您当前 macOS 应用程序窗口上方显示在一个小通知窗口中，并由 OpenAI 的 TTS（文本转语音）API 处理后朗读出来。
6. 当前会话中您提出的所有问题及其答案的历史记录都会保存在另一个窗口中，您可以将其隐藏或最小化。

最近一次的屏幕截图、音频录音和 TTS 回答会被存储在您的设备上，部分用于调试目的。每次都会使用相同的文件名覆盖这些文件，但关闭或删除应用程序并不会自动删除它们。

快速入门

视频教程

如果您更喜欢视频，请前往 YouTube 观看关于如何开始使用、应用程序的工作原理以及其底层机制的简要说明。

安装

请确保您的设备上已安装 NodeJS。然后克隆仓库并按照以下步骤操作。

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

进入该文件夹，在终端中运行 yarn install 或 npm install。这将安装所有依赖项。 接着运行 yarn start 或 npm start。由于应用程序需要访问您的屏幕、麦克风、读写文件等权限，您可能需要授予这些权限，并重新启动终端。

配置

请务必在主窗口右上角的设置图标中添加您的 OpenAI API 密钥。（请注意，该密钥并未加密存储！）

如果您想更改默认值，可以考虑修改以下内容，所有更改均需在 index.js 中进行：

• 键盘快捷键： 默认的键盘快捷键 keyboardShortcut 设置为 “CommandOrControl+Shift+'”（因为这个组合很少被其他应用程序使用）。
• OpenAI Vision 提示词： conversationHistory 中的 OpenAI Vision API 系统提示词目前仅设置为 “您正在根据屏幕截图帮助用户解答关于 macOS 应用程序的问题，回答应尽量控制在一句话以内。”
• VisionAPI 图像尺寸： 为了节省成本，我在 callVisionAPI() 中提供了一个调整图像大小的示例（我发现使用该功能后效果反而变差）。
• 应用程序窗口尺寸及设置： 主窗口的宽度和高度：mainWindowWidth 和 mainWindowHeight。始终置顶的通知窗口的宽度和高度：notificationWidth 和 notificationHeight。
• 更多通知窗口设置： 通知窗口的透明度：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 文件。双击即可打开应用，首次启动可能需要几秒钟，请耐心等待。 应用打开后，按下您设置的键盘快捷键。系统会提示您授予隐私和安全权限。您可能需要重复一两次此操作，以确保所有权限正常生效，并重启应用。

改进建议：

以下是一些我希望改进的功能，不分先后顺序：

• 实现会话之间的对话状态保存功能（即打开/关闭应用程序时仍能保持上下文）。
• 使用缓冲区代替将屏幕截图和音频文件写入/读取磁盘的操作。
• 在 UI 中增加对助手语音的自定义选项（例如语速调节、是否启用播放等功能）。
• 在 UI 中增加对始终置顶窗口的自定义选项（例如切换固定位置、启用/禁用功能）。
• 在 UI 中增加对截图区域的自定义选项（例如选择特定区域或截取整个屏幕）。
• 修复作为 .app 文件时麦克风无法正常工作的问题 已经由 @claar 解决。
• 支持文本输入而非仅限语音输入

关于/联系

我是一名自学成才的开发者，非常喜欢动手拼凑各种有趣的项目。我编写的代码功能实用，但可能既不美观也不高效，我还是愿意分享出来，希望能对其他人有所帮助。

你可以在 Twitter/X 上找到我：@ralfelfving。如果你喜欢这个项目，不妨去看看我在 YouTube 频道 @ralfelfving 上的教程吧。

macOSpilot AI 助手快速上手指南

macOSpilot 是一款运行在 macOS 上的个人 AI 助手。它能在任何应用程序中通过快捷键唤醒，截取当前屏幕画面并结合你的语音或文字提问，利用 OpenAI GPT-4 Vision 和 TTS 技术，在几秒钟内以图文和音频形式提供上下文相关的解答。

环境准备

• 操作系统：macOS（已在 Apple Silicon 和 Intel 芯片上测试）。
• 前置依赖：
  • 已安装 Node.js。
  • 已安装 yarn 或 npm 包管理器。
  • OpenAI API Key：你需要拥有可用的 OpenAI 账户及 API 密钥（需支持 Whisper、GPT-4 Vision 和 TTS 接口）。
  • 网络环境：由于需要连接 OpenAI 服务，请确保你的网络环境能够稳定访问相关 API。

安装步骤

1. 克隆项目仓库 在终端中执行以下命令下载源码：

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

2. 进入目录并安装依赖 进入项目文件夹并安装所需依赖包：

   cd macOSpilot-ai-assistant
   yarn install
   # 或者使用 npm
   # npm install
   

3. 配置 API 密钥

   • 运行应用后，在主窗口右上角点击设置图标。
   • 输入你的 OpenAI API Key。
   • 注意：根据开发者说明，该密钥未加密存储，请妥善保管。

4. 授予系统权限 首次运行时，macOS 会提示你授予以下权限，请务必在“系统设置”->“隐私与安全性”中允许：

   • 屏幕录制（用于截取当前窗口）
   • 麦克风（用于语音输入）
   • 辅助功能（用于模拟键盘操作等）
   • 提示：可能需要重启终端或应用多次以生效所有权限。

基本使用

1. 启动应用

在终端中运行以下命令启动开发版：

yarn start
# 或者
# npm start

(可选：若想打包成 .app 独立应用，请参考原文 "Turn it into an .app with Electron" 章节修改 index.js 并运行 npm run package-mac)

2. 唤起助手

确保当前处于任意你想要询问的应用窗口中，按下默认快捷键：

Command + Shift + ' (单引号)

3. 提问与获取答案

• 语音模式（默认）：
  1. 按下快捷键后，对着麦克风说出你的问题（例如：“这个报错是什么意思？”或“如何在这个界面导出数据？”）。
  2. 说完后，再次按下相同的快捷键 (Command + Shift + ') 结束录音。
• 文本模式： 如果在配置中启用了文本输入，按下快捷键后可直接打字提问并按回车。

4. 查看结果

• 视觉反馈：一个小型的通知窗口将悬浮在当前应用上方，显示 AI 的文字回答。
• 听觉反馈：系统将自动朗读回答内容（基于 OpenAI TTS）。
• 历史记录：你可以最小化主窗口，其中保留了当前会话的问答历史。

---

提示：默认的截图和提示词配置位于 index.js 文件中，高级用户可根据需要修改快捷键、Prompt 内容或窗口尺寸。