OpenWhispr

一款结合AI智能体、会议转录、笔记记录以及本地/云端语音识别功能的语音转文字听写与效率提升应用。
以隐私为先，跨平台可用。

星标历史

许可证

本项目采用 MIT 许可证授权——详情请参阅 LICENSE 文件。这意味着您可以自由地将此软件用于个人或商业用途，并对其进行修改和分发。

功能特性

听写与转录

• 🎤 全局热键：可在任意位置通过自定义热键启动或停止听写（默认为反引号 `）
• ⚡ 自动粘贴：转录文本会自动粘贴到光标位置（可切换关闭）
• 🔒 隐私优先：本地处理确保您的语音数据完全私密
• ⚡ NVIDIA Parakeet：通过 sherpa-onnx 实现快速本地转录（多语言支持，涵盖25种语言）
• 🔧 模型管理：下载并管理本地 Whisper 模型（tiny、base、small、medium、large、turbo）
• 📖 自定义词典：添加词汇、人名和技术术语以提高转录准确度；具备自动学习功能，能检测您的修正并自动更新词典
• 🗄️ 转录历史：SQLite 数据库本地存储所有转录内容，支持音频保留与重试
• 🎵 媒体自动暂停：听写时自动暂停媒体播放（如 Spotify、Apple Music 等），结束后恢复播放

AI 智能体模式

• 🤖 智能体悬浮窗：玻璃质感聊天悬浮窗，支持实时 AI 流式交互、窗口大小调整及对话历史记录
• 🎯 自定义智能体名称：为您的 AI 助手命名——只需说“Hey [AgentName]”即可下达指令
• 🧠 多提供商 AI 支持：
  • OpenAI：GPT-5、GPT-4.1、o-series 推理模型
  • Anthropic：Claude Opus 4.6、Claude Sonnet 4.6
  • Google：Gemini 3.1 Pro、Gemini 3 Flash、Gemini 2.5 Flash Lite
  • Groq：使用 Llama 和 Mixtral 模型实现超高速推理
  • 本地：通过 llama.cpp 支持 Qwen、LLaMA、Mistral、Gemma 等模型
• 🛠️ 智能体工具调用：提供搜索、创建和更新笔记等代理工具——本地模型支持 RAG 上下文注入
• 🤖 AI 动作：对笔记应用 AI 驱动的操作，支持自定义处理模板

会议转录

• 📅 Google 日历集成：连接多个 Google 账户，在侧边栏查看即将举行的会议，并接收自动检测提示
• 🎙️ 实时会议转录：通过 OpenAI Realtime API 实时录制并转录会议内容，支持自动检测会议场景（Zoom、Teams、FaceTime 等）
• ⚡ BYOK WebSocket 流式传输：不仅适用于会议转录，标准听写模式也可使用实时 OpenAI Realtime API 流式传输——统一的转录流路径
• ⌨️ 会议专用热键：独立于常规听写模式，专为会议转录设计的热键
• 🔍 智能检测：结合进程监控、持续音频检测和日历信息，自动识别会议场景

笔记功能

• 📝 笔记系统：创建、编辑和整理笔记，支持文件夹管理、音频上传及实时听写
• 🔎 全文搜索：基于 FTS5 的搜索功能，可通过 Cmd+K 快捷键访问命令面板，实现全笔记内容搜索
• 🧠 本地语义搜索：始终运行的 Qdrant 向量数据库，配合 MiniLM 嵌入技术，可在离线状态下进行基于语义的笔记搜索
• ☁️ 云同步：本地优先存储，同时支持云端备份与语义搜索
• 💬 嵌入式聊天：笔记编辑器中内置聊天面板，支持浮动与侧边栏两种模式
• 📁 文件夹组织：通过拖放方式将笔记归类到自定义文件夹中
• 💾 导出笔记为文件：可将笔记以 Markdown 格式导出至本地文件系统，保持与文件夹结构一致

云端与账户

• ☁️ OpenWhispr 云服务：登录后即可立即开始转录，无需 API 密钥，提供免费版和专业版两种方案
• 🔐 账户体系：支持 Google OAuth 以及邮箱/密码登录，并需完成邮箱验证
• 💳 订阅管理：免费版（每周2,000字）、专业版（无限制），提供7天免费试用
• 🔗 推荐计划：邀请好友可获得免费的专业版使用月数，分享专属推荐卡片即可参与

平台与界面

• 🌐 跨平台支持：适用于 macOS、Windows 和 Linux
• 🎨 现代 UI：基于 React 19、TypeScript 和 Tailwind CSS v4 构建
• 📱 响应式设置：设置对话框可根据窗口宽度调整布局，提供可折叠图标侧边栏和堆叠式布局
• 🖱️ 可拖动界面：听写面板可在屏幕上任意位置移动，支持自定义起始位置
• 🌐 Globe 键切换（macOS）：可选 Fn/Globe 键监听功能，作为硬件级别的听写触发机制——无需输入监控权限
• ⌨️ 复合热键：支持多键组合，例如 Cmd+Shift+K
• 🎙️ Windows 端推挽式通话：原生低级键盘钩子实现真正的推挽式通话，同时支持复合热键
• 🐧 GNOME Wayland 支持：通过 D-Bus 提供原生全局快捷键，适用于 GNOME Wayland 用户
• 🐧 KDE Wayland 支持：通过 D-Bus 提供原生全局快捷键，适用于 KDE Plasma on Wayland
• 🐧 Hyprland Wayland 支持：通过 hyprctl 键位绑定 + D-Bus 提供原生全局快捷键，适用于 Hyprland 用户
• 🖥️ 多显示器支持：浮动听写图标会跟随光标在不同显示器间移动
• 🧹 模型清理：一键清除缓存模型，并配备卸载钩子以保持磁盘整洁

系统要求

• Node.js 22+ 和 npm（从 nodejs.org 下载）
• macOS 12+、Windows 10+ 或 Linux
• 在 macOS 上，若需 Globe 键支持，必须安装 Xcode 命令行工具（运行 xcode-select --install），以便捆绑的 Swift 辅助程序能够正常运行

快速入门

用于个人使用（推荐）

1. 克隆仓库：

   git clone https://github.com/OpenWhispr/openwhispr.git
   cd openwhispr
   

2. 安装依赖：

   npm install
   

3. 可选：设置 API 密钥（仅在使用云端处理时需要）：

   方法 A - 环境文件：

   cp .env.example .env
   # 编辑 .env 文件并添加您的 API 密钥：
   # OPENAI_API_KEY=your_openai_key
   # ANTHROPIC_API_KEY=your_anthropic_key
   # GEMINI_API_KEY=your_gemini_key
   # GROQ_API_KEY=your_groq_key
   # MISTRAL_API_KEY=your_mistral_key
   

   方法 B - 应用内配置：

   • 运行应用并通过控制面板配置 API 密钥。
   • 密钥会自动保存，并在应用重启后仍然有效。

4. 构建应用程序：

   npm run build
   

5. 运行应用程序：

   npm run dev  # 开发模式，支持热重载
   # 或者
   npm start    # 生产模式
   

6. 可选：从源代码本地下载 Whisper（仅在需要本地处理时才需执行）：

   npm run download:whisper-cpp
   

   此命令会将适用于您当前操作系统的 whisper.cpp 二进制文件下载到 resources/bin/ 目录下。

为个人使用构建（可选）

如果您希望构建一个独立的应用程序供个人使用：

# 不进行代码签名的构建（无需证书）
npm run pack

# 未签名的应用程序将位于：dist/mac-arm64/OpenWhispr.app（macOS）
# 或 dist/win-unpacked/OpenWhispr.exe（Windows）
# 或 dist/linux-unpacked/open-whispr（Linux）

注意：在 macOS 上，首次打开未签名的应用程序时可能会出现安全警告。请右键单击并选择“打开”以绕过该警告。

Windows

原生粘贴二进制文件 (windows-fast-paste)：

OpenWhispr 在 Windows 上提供了一个原生 C 语言编写的二进制文件，用于通过 Win32 的 SendInput API 实现文本粘贴功能。这是主要的粘贴机制——nircmd 和 PowerShell 只是在原生二进制失败时作为备用方案。

工作原理如下：

• 普通应用程序：通过 SendInput 模拟 Ctrl+V，使用虚拟键码组合（VK_CONTROL + V）。
• 终端模拟器：检测前台窗口的类名，并模拟 Ctrl+Shift+V。
• 终端检测：识别 Windows Terminal、cmd.exe、PowerShell、mintty（Git Bash）、PuTTY、Alacritty、WezTerm、kitty、Hyper、MobaXterm 以及 ConEmu/Cmder 等终端。
• 仅检测模式：支持 --detect-only 标志，用于报告前台窗口的类名而不发送按键。

编译过程（由构建系统自动完成）：

# MSVC
cl /O2 windows-fast-paste.c /Fe:windows-fast-paste.exe user32.lib

# MinGW
gcc -O2 windows-fast-paste.c -o windows-fast-paste.exe -luser32

构建脚本（scripts/build-windows-fast-paste.js）首先尝试从 GitHub 发布页面下载预编译的二进制文件。如果无法获取，则使用 MSVC、MinGW-w64 或 Clang 从源代码编译。若以上两种方式均不可行，则回退到 nircmd 或 PowerShell 的 SendKeys 方法。

ℹ️ 注：CASCADIA_HOSTING_WINDOW_CLASS 覆盖了所有在 Windows Terminal 内运行的 Shell（PowerShell、CMD、WSL 等），因此大多数现代 Windows 终端的使用场景都可通过这一单一的类名条目来覆盖。

Linux（多种软件包格式）

OpenWhispr 现在支持多种 Linux 软件包格式，以实现最大的兼容性：

可用格式：

• .deb - Debian、Ubuntu、Linux Mint、Pop!_OS
• .rpm - Fedora、Red Hat、CentOS、openSUSE
• .tar.gz - 通用归档文件（适用于任何发行版）
• .flatpak - 沙盒化的跨发行版软件包
• AppImage - 可移植的单文件可执行程序

构建 Linux 软件包：

# 构建默认的 Linux 软件包格式（AppImage、deb、rpm、tar.gz）
npm run build:linux

# 软件包位于 dist/ 目录下：
# - OpenWhispr-x.x.x-linux-x64.AppImage
# - OpenWhispr-x.x.x-linux-x64.deb
# - OpenWhispr-x.x.x-linux-x64.rpm
# - OpenWhispr-x.x.x-linux-x64.tar.gz

可选：构建 Flatpak（需要额外设置）：

# 安装 Flatpak 构建工具
sudo apt install flatpak flatpak-builder  # Debian/Ubuntu
# 或者
sudo dnf install flatpak flatpak-builder  # Fedora/RHEL

# 添加 Flathub 仓库并安装运行时
flatpak remote-add --user --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
flatpak install --user -y flathub org.freedesktop.Platform//24.08 org.freedesktop.Sdk//24.08

# 将 "flatpak" 添加到 electron-builder.json 中的 linux.target，然后进行构建
npm run build:linux

安装示例：

# Debian/Ubuntu
sudo apt install ./dist/OpenWhispr-*-linux-x64.deb

# Fedora/RHEL
sudo dnf install ./dist/OpenWhispr-*-linux-x64.rpm

# 通用 tar.gz 包（无需 root 权限）
tar -xzf dist/OpenWhispr-*-linux-x64.tar.gz
cd OpenWhispr-*/
./openwhispr

# Flatpak
flatpak install --user ./dist/OpenWhispr-*-linux-x64.flatpak

# AppImage（现有方法）
chmod +x dist/OpenWhispr-*.AppImage
./dist/OpenWhispr-*.AppImage

原生粘贴二进制文件 (linux-fast-paste)：

OpenWhispr 提供了一个原生 C 语言编写的二进制文件，用于在 Linux 上实现文本粘贴功能，该文件会在构建时自动编译。这是主要的粘贴机制——外部工具如 xdotool 和 wtype 仅在原生二进制失败时才会被用作备份。

工作原理如下：

• X11：使用 XTest 扩展直接合成 Ctrl+V（或在终端中合成 Ctrl+Shift+V），除了 X11 之外没有任何其他依赖。
• Wayland：利用 Linux 的 uinput 子系统创建虚拟键盘并注入按键。如果 uinput 不可用，则会通过 XWayland 回退到 XTest。
• 终端检测：能够识别 20 多种终端模拟器（kitty、alacritty、gnome-terminal、wezterm、ghostty 等），并在终端中自动使用 Ctrl+Shift+V 而不是 Ctrl+V。
• 窗口目标定位：可以通过 --window 参数指定特定的窗口 ID，以确保按键输入到达正确的应用程序。

编译所需的依赖项：

# Debian/Ubuntu
sudo apt install gcc libx11-dev libxtst-dev

# Fedora/RHEL
sudo dnf install gcc libX11-devel libXtst-devel

# Arch
sudo pacman -S gcc libx11 libxtst

构建脚本（scripts/build-linux-fast-paste.js）会在执行 npm run compile:linux-paste 时运行，并完成以下步骤：

1. 检测是否可以找到 linux/uinput.h 头文件；
2. 如果可以，则编译时加入 -DHAVE_UINPUT 标志（启用 Wayland 的 uinput 支持）；
3. 缓存生成的二进制文件，除非源代码或编译选项发生变化，否则不会重新编译；
4. 如果编译失败，会优雅地回退到系统自带的工具。

如果原生二进制文件不可用，OpenWhispr 会按照以下顺序回退到外部粘贴工具：

自动粘贴的备用依赖项：

当原生粘贴二进制文件不可用或失效时，将按以下顺序使用这些工具作为备用方案：

X11（传统 Linux 桌面环境）：

# Debian/Ubuntu
sudo apt install xdotool

# Fedora/RHEL
sudo dnf install xdotool

# Arch
sudo pacman -S xdotool

Wayland（现代 Linux 桌面）：

推荐：安装 wl-clipboard 以实现 Wayland 应用程序之间可靠的剪贴板共享：

sudo apt install wl-clipboard    # Debian/Ubuntu
sudo dnf install wl-clipboard    # Fedora/RHEL
sudo pacman -S wl-clipboard      # Arch

从以下粘贴工具中选择一个：

选项 1：wtype（需要虚拟键盘协议支持）

# Debian/Ubuntu
sudo apt install wtype

# Fedora/RHEL
sudo dnf install wtype

# Arch
sudo pacman -S wtype

选项 2：ydotool（适用于更多窗口管理器，需运行守护进程）

# Debian/Ubuntu
sudo apt install ydotool
sudo systemctl enable --now ydotoold

# Fedora/RHEL
sudo dnf install ydotool
sudo systemctl enable --now ydotoold

# Arch
sudo pacman -S ydotool
sudo systemctl enable --now ydotoold

终端检测（可选——适用于 KDE Wayland 用户）：

# 在 KDE Wayland 上，kdotool 可启用自动终端检测，
# 从而使用 Ctrl+Shift+V 而不是 Ctrl+V 进行粘贴。
sudo apt install kdotool  # Debian/Ubuntu
sudo dnf install kdotool  # Fedora/RHEL
sudo pacman -S kdotool    # Arch

ℹ️ 注意：OpenWhispr 会自动按以下顺序尝试粘贴方法：原生 linux-fast-paste 二进制文件（XTest 或 uinput）→ wtype → ydotool → xdotool（用于 XWayland 应用程序）。如果所有粘贴方法均无效，文本仍会被复制到剪贴板——您只需手动使用 Ctrl+V 进行粘贴。

⚠️ ydotool 要求：ydotoold 守护进程必须运行才能使 ydotool 正常工作。您可以使用 sudo ydotoold & 手动启动，或按照上述说明启用 systemd 服务。

GNOME Wayland 全局快捷键：

在 GNOME Wayland 上，由于 Wayland 的安全模型限制，Electron 的标准全局快捷键无法正常工作。OpenWhispr 会自动通过 D-Bus 和 gsettings 使用 GNOME 原生键盘快捷键：

• 快捷键将注册为 GNOME 自定义快捷键（可在“设置”→“键盘”→“快捷键”中查看）。
• 默认快捷键为 Alt+R（GNOME Wayland 不支持反引号）。
• GNOME Wayland 上不支持按住说话模式（仅支持点击说话）。
• 如果 GNOME 集成失败，则回退到 X11/XWayland 快捷键。
• 无需额外依赖——使用 dbus-next npm 包。

ℹ️ GNOME Wayland 局限性：GNOME 系统快捷键仅触发一次切换事件（无法检测按键释放），因此按住说话模式无法实现。该应用会在 GNOME Wayland 上自动切换为点击说话模式。

🔒 Flatpak 安全性：Flatpak 软件包包含沙盒机制，并明确授予了麦克风、剪贴板和文件访问权限。完整权限列表请参阅 electron-builder.json。

分发版构建

对于需要分发签名构建的维护者：

# 需要代码签名证书和公证设置
npm run build:mac    # macOS（需要 Apple 开发者账号）
npm run build:win    # Windows（需要代码签名证书）
npm run build:linux  # Linux

首次设置

1. 选择处理方式：

   • OpenWhispr 云：登录即可享受即时云端转录服务，提供免费和 Pro 版本。
   • 自备密钥：使用您自己的 OpenAI/Groq/AssemblyAI API 密钥。
   • 本地处理：下载 Whisper 或 Parakeet 模型，实现完全私密的转录。

2. 授予权限：

   • 麦克风访问权限：录制语音所必需。
   • 辅助功能权限：自动粘贴文本所必需（macOS）。
   • 屏幕录制权限（可选，macOS）：录制会议音频所必需——如果您希望使用会议功能，将在引导过程中提示您。

3. 命名您的代理：为您的 AI 助手取一个个性化名称（例如，“助理”、“贾维斯”、“亚历克斯”）。

   • 使交互更加自然和对话化。
   • 有助于区分发出指令与普通听写。
   • 您可以随时在设置中更改名称。

4. 配置全局快捷键：默认为反引号 (`)，但可自定义。

使用方法

基本听写

1. 启动应用——屏幕上会出现一个小巧可拖动的面板。
2. 按下快捷键（默认：反引号 `）——开始听写（面板显示录音动画）。
3. 再次按下快捷键——停止听写并开始转录（面板显示处理动画）。
4. 文本出现——转录后的文本会自动粘贴到光标位置。
5. 拖动面板——单击并拖动可将听写面板移动到屏幕上的任意位置。

控制面板

• 访问方式：右键单击托盘图标（macOS）或通过系统菜单。
• 配置：选择本地处理或云端处理。
• 历史记录：查看、复制和删除过去的转录内容——支持音频播放及失败转录的重试。
• 笔记：创建、编辑和整理笔记，支持文件夹、AI 动作和全文搜索。
• 集成：连接 Google 日历账户，实现会议检测与转录。
• 模型：下载并管理本地的 Whisper 和 Parakeet 模型。
• 存储清理：移除缓存中的已下载模型以释放空间。
• 设置：配置 API 密钥、自定义快捷键、管理权限以及设置代理模式。
• Cmd+K 搜索：可在应用内的任何位置快速搜索笔记和转录内容。

卸载与缓存清理

• 应用内操作：使用“设置→常规→本地模型存储→移除已下载模型”来清除 ~/.cache/openwhispr/（或 Windows 上的 %USERPROFILE%\.cache\openwhispr\）中的 Whisper 和 Parakeet 缓存模型。
• 音频文件：保留的音频文件存储在应用数据目录中，会在 30 天后自动清理。如有需要，可通过设置手动清理。
• Windows 卸载：NSIS 卸载程序会自动删除缓存目录。
• Linux 软件包：deb/rpm 的卸载后脚本也会移除缓存模型。
• macOS：如果您手动卸载，可根据需要删除 ~/Library/Caches 或 ~/.cache/openwhispr/。

代理命名与 AI 处理

在设置阶段为您的代理命名后，您可以使用多种 AI 提供商与其互动：

🎯 代理指令（用于 AI 辅助）：

• “嘿[代理名]，把这个说得更专业点”
• “嘿[代理名]，把它格式化成列表”
• “嘿[代理名]，写一封感谢邮件”
• “嘿[代理名]，把这个转换成要点”

🤖 AI 提供商选项：

• OpenAI：GPT-5、GPT-4.1、o 系列推理模型。
• Anthropic：Claude Opus 4.6、Sonnet 4.6、Haiku 4.5。
• Google：Gemini 3.1 Pro、Gemini 3 Flash、Gemini 2.5 Flash Lite。
• Groq：超快速 Llama 和 Mixtral 推理。
• 本地：Qwen、LLaMA、Mistral、Gemma 模型，通过 llama.cpp 提供。

📝 普通听写（用于常规文本）：

• “这只是我想转录的普通文本”
• “会议记录：约翰提到了季度报告”
• “亲爱的莎拉，感谢你的帮助”

AI 会自动检测您是在下达指令还是进行普通听写，并在最终输出中移除代理名称引用。

自定义词典

提升特定单词、姓名或技术术语的转录准确度：

1. 访问设置：打开控制面板 → 设置 → 自定义词典
2. 添加词汇：输入经常被误识别的单词、姓名或短语
3. 工作原理：这些词汇会作为上下文提示提供给语音识别模型

建议添加的词汇示例：

• 不常见的姓名（如“Sergey”、“Xanthe”）
• 技术术语（如“Kubernetes”、“OAuth”）
• 品牌名称（如“OpenWhispr”、“whisper.cpp”）
• 领域特定术语（如“摊销”、“聚合酶”）

代理模式

代理模式会打开一个可调整大小的玻璃拟物风格聊天浮层，用于交互式AI对话：

1. 启用：前往设置 → 代理模式，并将其开启
2. 设置快捷键：分配一个专用快捷键以打开代理浮层
3. 聊天：按下快捷键打开浮层，口述你的消息，并接收流式AI回复
4. 自定义：设置自定义系统提示，选择你喜欢的AI提供商和模型
5. 历史记录：所有对话都会被保存，并可随时继续

会议转录

通过Google Calendar集成自动检测并转录会议内容：

1. 连接日历：前往集成 → Google Calendar并登录
2. 授予屏幕录制权限（macOS）：需要此权限才能捕获会议音频
3. 自动检测：当会议开始时（Zoom、Teams、FaceTime），会出现通知询问是否要录制
4. 实时转录：会议音频将通过OpenAI Realtime API进行实时转录
5. 回顾：会议转录内容会被保存为笔记，供日后查看和AI增强

处理选项

• OpenWhispr云：
  • 使用Google或邮箱登录——无需API密钥
  • 免费计划：每周2,000字，新账户可享受7天Pro试用期
  • Pro计划：无限转录量
• 自带密钥（BYOK）：
  • 使用你自己的来自OpenAI、Groq、Mistral、AssemblyAI的API密钥，或自定义端点
  • 完全掌控提供商和模型的选择
• 本地处理：
  • 通过控制面板安装Whisper或NVIDIA Parakeet
  • 下载模型：tiny（最快）、base（推荐）、small、medium、large（最佳质量）
  • 完全隐私——音频绝不会离开你的设备

项目结构

open-whispr/
├── main.js              # Electron主进程及IPC处理器
├── preload.js           # Electron预加载脚本及API桥接
├── setup.js             # 首次设置脚本
├── package.json         # 依赖项和脚本
├── env.example          # 环境变量模板
├── CHANGELOG.md         # 项目变更日志
├── src/
│   ├── App.jsx          # 主听写界面
│   ├── main.jsx         # React入口文件
│   ├── index.html       # Vite HTML模板
│   ├── index.css        # Tailwind CSS v4配置
│   ├── vite.config.js   # Vite配置
│   ├── components/
│   │   ├── ControlPanel.tsx     # 设置与历史记录UI
│   │   ├── OnboardingFlow.tsx   # 首次设置向导
│   │   ├── SettingsPage.tsx     # 设置界面
│   │   ├── AgentOverlay.tsx     # 代理模式聊天浮层
│   │   ├── CommandSearch.tsx    # Cmd+K命令面板
│   │   ├── IntegrationsView.tsx # Google Calendar及其他集成
│   │   ├── UpcomingMeetings.tsx # 侧边栏会议列表
│   │   ├── agent/               # 代理模式组件
│   │   │   ├── AgentChat.tsx
│   │   │   ├── AgentInput.tsx
│   │   │   ├── AgentMessage.tsx
│   │   │   └── AgentTitleBar.tsx
│   │   ├── notes/               # 笔记系统组件
│   │   │   ├── NoteEditor.tsx
│   │   │   ├── ActionPicker.tsx
│   │   │   ├── ActionManagerDialog.tsx
│   │   │   └……
│   │   ├── settings/            # 设置子组件
│   │   │   └── AgentModeSettings.tsx
│   │   ├── ui/                  # shadcn/ui组件
│   │   └── lib/
│   │       └── utils.ts         # 工具函数
│   ├── config/
│   │   └── prompts.ts           # 中央化AI提示定义
│   ├── services/
│   │   └── ReasoningService.ts  # 多提供商流式AI处理
│   ├── hooks/
│   │   ├── useMeetingTranscription.ts  # 会议音频捕获
│   │   ├── useUpcomingEvents.ts        # 日历事件获取
│   │   ├── useScreenRecordingPermission.ts  # macOS权限
│   │   └……
│   ├── helpers/
│   │   ├── googleCalendarManager.js    # 日历同步及事件管理
│   │   ├── googleCalendarOAuth.js      # OAuth 2.0 PKCE流程
│   │   ├── meetingDetectionEngine.js   # 智能会议检测
│   │   ├── audioStorage.js             # 音频文件存储
│   │   ├── mediaPlayer.js             # 跨平台媒体控制
│   │   └……
│   ├── utils/
│   │   └── agentName.ts         # 代理名称管理工具
│   └── components.json          # shadcn/ui配置
├── resources/
│   └── bin/                     # 原生二进制文件（whisper-cpp、sherpa-onnx等）
└── assets/                      # 应用图标及资源

技术栈

• 前端：React 19、TypeScript、Tailwind CSS v4
• 构建工具：Vite搭配优化后的Tailwind插件
• 桌面应用：Electron 39，支持上下文隔离
• UI组件：shadcn/ui结合Radix原生组件
• 数据库：better-sqlite3配合FTS5用于本地存储（转录、笔记、代理、日历）
• 语音转文字：本地使用OpenAI Whisper（whisper.cpp）+ NVIDIA Parakeet（sherpa-onnx），云端则使用OpenAI API
• 实时转录：通过WebSocket的OpenAI Realtime API实现会议转录
• AI处理：多提供商流式处理（OpenAI、Anthropic、Gemini、Groq、本地llama.cpp）
• 日历集成：Google Calendar API配合OAuth 2.0 PKCE
• 图标：Lucide React用于统一图标设计

开发

脚本

• npm run dev - 启动开发模式，支持热重载
• npm run start - 启动生产构建
• npm run setup - 首次设置（创建 .env 文件）
• npm run build:renderer - 仅构建 React 应用
• npm run download:whisper-cpp - 下载适用于当前平台的 whisper.cpp
• npm run download:whisper-cpp:all - 下载适用于所有平台的 whisper.cpp
• npm run download:llama-server - 下载用于本地 LLM 推理的 llama.cpp 服务器
• npm run download:llama-server:all - 下载适用于所有平台的 llama.cpp 服务器
• npm run download:sherpa-onnx - 下载用于 Parakeet 本地转录的 sherpa-onnx
• npm run download:sherpa-onnx:all - 下载适用于所有平台的 sherpa-onnx
• npm run compile:native - 编译原生辅助工具（macOS 上的 Globe 键盘监听器和媒体遥控器，Windows 上的键盘监听器和快速粘贴功能，Linux 上的快速粘贴功能，以及用于自动学习的文本监控工具）
• npm run build - 完整构建并签名（需要证书）
• npm run build:mac - macOS 构建并签名
• npm run build:win - Windows 构建并签名
• npm run build:linux - Linux 构建
• npm run pack - 不带签名的构建（供个人使用）
• npm run dist - 构建并打包，同时签名
• npm run lint - 运行 ESLint 检查
• npm run format - 使用 Prettier 格式化代码
• npm run clean - 清理构建产物
• npm run preview - 预览生产构建

架构

该应用由两个主要窗口组成：

1. 主窗口：用于听写控制的极简叠加层
2. 控制面板：完整的设置与历史记录界面

两者使用相同的 React 代码库，但会根据 URL 参数渲染不同的组件。

关键组件

• main.js：Electron 主进程、IPC 处理程序及数据库操作
• preload.js：主进程与渲染进程之间的安全桥接
• App.jsx：包含录音控制的主要听写界面
• ControlPanel.tsx：用于设置、历史记录、笔记、集成及模型管理
• AgentOverlay.tsx：代理模式下的聊天叠加层，支持流式 AI 回答
• CommandSearch.tsx：Cmd+K 命令面板，用于搜索笔记和转录内容
• IntegrationsView.tsx：Google 日历连接及会议设置
• src/helpers/whisper.js：whisper.cpp 集成，用于本地处理
• src/helpers/googleCalendarManager.js：日历同步与事件管理
• src/helpers/meetingDetectionEngine.js：智能会议检测引擎
• src/helpers/audioStorage.js：音频文件的存储与管理
• src/helpers/mediaPlayer.js：跨平台的媒体暂停/恢复功能
• src/services/ReasoningService.ts：多提供商的 AI 处理服务，支持流式处理
• better-sqlite3：用于存储转录、笔记、代理数据及日历信息的本地数据库

Tailwind CSS v4 设置

该项目使用最新的 Tailwind CSS v4，配置包括：

• 基于 @theme 指令的 CSS 优先配置
• Vite 插件以优化性能
• 自定义设计令牌，实现一致的主题风格
• 支持深色模式，通过 @variant 实现

构建

构建过程会为您的平台生成一个单独的可执行文件：

# 开发构建
npm run pack

# 生产构建
npm run dist           # 当前平台
npm run build:mac      # macOS DMG + ZIP
npm run build:win      # Windows NSIS + 便携版
npm run build:linux    # AppImage + DEB

注意：build/pack/dist 脚本会自动下载适用于当前平台的 whisper.cpp、llama-server 和 sherpa-onnx。若需从同一台主机打包多个平台版本，请先运行 :all 变体脚本（npm run download:whisper-cpp:all、npm run download:llama-server:all、npm run download:sherpa-onnx:all）。

配置

环境变量

在项目根目录下创建 .env 文件（或使用 npm run setup）：

# OpenAI API 配置（可选，仅在使用云端处理时需要）
OPENAI_API_KEY=your_openai_api_key_here

# 可选：自定义 Whisper 模型
WHISPER_MODEL=whisper-1

# 可选：设置语言以提高转录准确度
LANGUAGE=

# 可选：Anthropic API 配置
ANTHROPIC_API_KEY=your_anthropic_api_key_here

# 可选：Google Gemini API 配置
GEMINI_API_KEY=your_gemini_api_key_here

# 可选：Groq API 配置（超高速推理）
GROQ_API_KEY=your_groq_api_key_here

# 可选：Mistral API 配置（Voxtral 转录）
MISTRAL_API_KEY=your_mistral_api_key_here

# 可选：调试模式
DEBUG=false

本地 Whisper 设置

对于本地处理，OpenWhispr 使用 OpenAI 的 Whisper 模型，通过高性能 C++ 实现 whisper.cpp：

1. 内置二进制文件：whisper.cpp 已随应用打包，适用于所有平台
2. GGML 模型：首次使用时会下载优化后的 GGML 模型，并存储到 ~/.cache/openwhispr/whisper-models/
3. 无依赖：无需 Python 或其他运行时环境

系统回退：若内置二进制文件无法正常工作，可通过包管理器安装：

• macOS：brew install whisper-cpp
• Linux：从 https://github.com/ggml-org/whisper.cpp 源码编译

从源码安装：在本地运行（而非打包构建）时，需使用 npm run download:whisper-cpp 下载二进制文件，确保 resources/bin/ 目录下有适用于您平台的可执行文件。

要求：

• 充足的磁盘空间以存储模型（75MB 至 3GB，视模型大小而定）

从基于 Python 的版本升级：如果您之前使用的是基于 Python 的 Whisper，则需要重新下载 GGML 格式的模型。您可以安全地删除旧的 Python 环境（~/.openwhispr/python/）以及 PyTorch 模型（~/.cache/whisper/），以释放磁盘空间。

本地 Parakeet 设置（替代方案）

OpenWhispr 还支持通过 sherpa-onnx 使用 NVIDIA Parakeet 模型——这是 Whisper 的快速替代方案：

1. 内置二进制文件：sherpa-onnx 已随应用打包，适用于所有平台
2. INT8 量化模型：高效 CPU 推理
3. 模型存储位置：~/.cache/openwhispr/parakeet-models/

可用模型：

• parakeet-tdt-0.6b-v3：多语言支持（25 种语言），约 680MB

何时选择 Parakeet 或 Whisper：

• Parakeet：最适合对速度要求较高的场景或硬件配置较低的情况
• Whisper：更适合对质量要求较高的场景，或需要特定模型尺寸时

自定义选项

• 快捷键：可在控制面板中更改，默认为反引号 `，且完全可自定义
• 面板位置：可将听写面板拖动至屏幕上的任意位置
• 处理方式：在控制面板中选择本地或云端处理
• Whisper 模型：在控制面板中根据需求选择质量或速度
• UI 主题：可通过编辑 src/index.css 中的 CSS 变量进行调整
• 窗口大小：可在 main.js 中调整窗口尺寸
• 数据库：转录内容存储在用户数据目录中

贡献

我们欢迎各位贡献！请按照以下步骤操作：

1. Fork 仓库
2. 创建特性分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m '添加精彩功能'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 打开 Pull Request

开发指南

• 提交代码前运行 npm run lint
• 遵循现有代码风格
• 根据需要更新文档
• 提交前在目标平台上进行测试

安全性

OpenWhispr 在设计时充分考虑了隐私与安全性：

• 本地处理选项：确保您的语音数据完全私密
• 无数据分析：我们不会收集任何使用数据或遥测信息
• 开源：所有代码均可供审查
• 安全存储：API 密钥会安全地存储在您系统的钥匙串/凭据管理器中
• 最小权限：仅请求必要的权限（麦克风、辅助功能、会议录制）
• OAuth 2.0 PKCE：Google 日历使用安全的 PKCE 流程——不存储客户端密钥
• 本地优先笔记：笔记本地存储在 SQLite 中；云同步为可选功能

故障排除

常见问题

1. 麦克风权限：请在系统偏好设置/设置中授予相关权限
2. 辅助功能权限（macOS）：自动粘贴文本需要此权限
   • 打开系统设置 → 隐私与安全性 → 辅助功能
   • 添加 OpenWhispr 并启用复选框
   • 如有需要，可在控制面板中使用“修复权限问题”功能
3. API 密钥错误（仅限云端处理）：请确保您的 OpenAI API 密钥有效且账户余额充足
   • 可通过控制面板或 .env 文件设置密钥
   • 检查日志以确认“OpenAI API 密钥存在：是/否”
4. 本地 Whisper 问题：
   • whisper.cpp 已随应用打包
   • 若打包的二进制文件无法运行，请通过 brew install whisper-cpp 进行安装（macOS）
   • 请检查磁盘空间是否足以存放模型
5. 全局热键冲突：可在控制面板中更改热键——任意按键均可使用
   • GNOME Wayland：热键通过 gsettings 注册；请检查设置 → 键盘 → 快捷键是否存在冲突
6. 文本无法粘贴：
   • macOS：请检查辅助功能权限（系统设置 → 隐私与安全性 → 辅助功能）
   • Linux X11：请安装 xdotool
   • Linux Wayland：请安装 wtype 或 ydotool 来模拟粘贴操作（确保 ydotoold 守护进程正在运行）
   • 所有平台：文本始终会被复制到剪贴板——请手动使用 Ctrl+V（macOS 为 Cmd+V）进行粘贴
7. 面板位置：若面板显示在屏幕外，请重启应用以重置位置
8. 会议检测未生效：
   • macOS：请在系统设置 → 隐私与安全性 → 屏幕录制中授予屏幕录制权限
   • 确保已在集成中连接 Google 日历
   • 检查设置中是否已启用会议检测功能
9. 代理模式问题：
   • 确保已在设置 → 代理模式中启用该功能
   • 验证您是否拥有所选 AI 提供商的有效 API 密钥
   • 检查代理模式热键是否与其他快捷键冲突

获取帮助

• 请查看 Issues 页面
• 查看控制台日志以获取调试信息
• 对于本地处理：请确保 whisper.cpp 可用且模型已下载
• 对于云端处理：请验证您的 OpenAI API 密钥及账单状态
• 检查控制面板中的系统状态和诊断信息

性能提示

• 本地处理：建议使用 “base” 模型，以获得速度与准确性的最佳平衡
• 云端处理：通常速度更快，但需要互联网连接
• 模型选择：tiny（最快）→ base（推荐）→ small → medium → large（最佳质量）
• 权限：请确保所有必要权限均已授予，以保证流畅运行

常见问题解答

问：OpenWhispr 真的是免费的吗？ 答：是的！OpenWhispr 是开源且免费使用的。免费计划包含每周 2,000 字的云端转录服务，而本地处理则完全免费且无限制。付费计划低至每月 8 美元。

问：我应该使用哪种处理方式？ 答：如果您注重隐私且需要离线使用，请选择本地处理；若您追求速度与便利，则可以选择云端处理。

问：我可以将它用于商业用途吗？ 答：可以！MIT 许可证允许商业使用。

问：如何更改热键？ 答：右键点击托盘图标打开控制面板，进入设置即可。您可以将任意按键设为热键。

问：我的数据安全吗？ 答：使用本地处理时，您的音频绝不会离开设备。而使用云端处理时，音频会发送到 OpenAI 的服务器（请参阅其隐私政策）。

问：支持哪些语言？ 答：OpenWhispr 支持 58 种语言，包括英语、西班牙语、法语、德语、中文、日语等。您可以在 .env 文件中设置首选语言，或使用自动检测功能。

问：什么是代理模式？ 答：代理模式会打开一个聊天浮层，您可以通过语音与 AI 进行交互式对话。它支持来自所有提供商（OpenAI、Anthropic、Gemini、Groq、本地模型）的流式响应，并保存对话历史。

问：会议转录是如何工作的？ 答：在集成中连接您的 Google 日历。当会议开始时（Zoom、Teams、FaceTime），OpenWhispr 会检测到并提供录音选项。音频将通过 OpenAI Realtime API 实时转录。在 macOS 上，需要屏幕录制权限才能捕获会议音频。

问：我的笔记存储在哪里？ 答：笔记本地存储在 SQLite 中，支持可选的云同步。它们具备全文搜索（FTS5）、文件夹组织以及 AI 驱动的增强功能。

问：OpenWhispr 在 macOS 上是否需要输入监控权限？ 答：不需要。自 v1.6.0 起，OpenWhispr 使用 NSEvent 监视器代替 CGEvent 拦截，从而不再需要输入监控权限。仅需麦克风和辅助功能权限（加上会议功能所需的屏幕录制权限）。

项目状态

OpenWhispr 目前处于积极维护状态，已准备好投入生产使用。当前版本：1.6.7

• ✅ 核心听写功能，支持本地与云端处理
• ✅ 跨平台支持（macOS、Windows、Linux）
• ✅ OpenWhispr 云服务，配备账户系统、使用情况追踪及 Stripe 支付功能
• ✅ 多家 AI 提供商支持（OpenAI、Anthropic、Gemini、Groq、Mistral、本地模型）
• ✅ 代理模式，支持流式聊天浮层及对话历史记录
• ✅ Google 日历集成，支持自动会议检测
• ✅ 通过 OpenAI Realtime API 实现会议实时转录
• ✅ 笔记系统，支持 FTS5 搜索、云同步、文件夹管理及 AI 动作
• ✅ 音频保留功能，支持失败转录的回放与重试
• ✅ Cmd+K 命令搜索，可跨笔记与转录内容查找
• ✅ 听写过程中自动暂停媒体播放
• ✅ 自定义词典，支持自动学习纠正功能
• ✅ 通过 sherpa-onnx 支持 NVIDIA Parakeet
• ✅ 复合热键及 Windows 按住说话功能
• ✅ GNOME Wayland 和 Hyprland 原生全局快捷键
• ✅ 推荐计划，支持分享邀请卡
• ✅ 专用会议模式热键
• ✅ CodeQL 静态分析及 Dependabot 依赖项更新

致谢

• OpenAI Whisper - 为本地和云端转录提供支持的语音识别模型
• whisper.cpp - 高性能的 Whisper C++ 实现，用于本地处理
• NVIDIA Parakeet - 适用于高效本地转录的快速 ASR 模型
• sherpa-onnx - 用于 Parakeet 模型推理的跨平台 ONNX 运行时
• Electron - 跨平台桌面应用框架
• React - UI 组件库
• shadcn/ui - 基于 Radix 原语构建的精美 UI 组件
• Hugging Face - 我们本地语音识别和语言模型的模型托管平台
• llama.cpp - 用于 AI 驱动文本处理的本地 LLM 推理

OpenWhispr 快速上手指南

OpenWhispr 是一款跨平台的语音转文字（Dictation）与 AI 助手应用，支持本地隐私优先的语音识别、会议转录、笔记管理及多模型 AI 代理。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统：
  • macOS 12+
  • Windows 10+
  • Linux (支持 GNOME/KDE/Hyprland Wayland)
• 核心依赖：
  • Node.js 22+ 及 npm (推荐从 nodejs.org 下载，国内用户可使用淘宝镜像或 nvm 管理版本)
• macOS 额外要求：
  • 若需使用 Globe 键（地球仪键）触发功能，需安装 Xcode 命令行工具：

    xcode-select --install
    

安装步骤

1. 克隆项目

将代码仓库克隆到本地并进入目录：

git clone https://github.com/OpenWhispr/openwhispr.git
cd openwhispr

2. 安装依赖

安装项目所需的 Node.js 依赖包：

npm install

提示：国内网络环境下，建议配置 npm 镜像源以加速下载：

npm config set registry https://registry.npmmirror.com

3. 配置 API 密钥（可选）

如果您计划使用云端 AI 处理（如 OpenAI, Claude, Gemini 等），有两种配置方式：

方式 A：环境变量文件 复制示例文件并编辑：

cp .env.example .env

在 .env 文件中填入您的密钥：

OPENAI_API_KEY=your_openai_key
ANTHROPIC_API_KEY=your_anthropic_key
GEMINI_API_KEY=your_gemini_key
GROQ_API_KEY=your_groq_key
MISTRAL_API_KEY=your_mistral_key

方式 B：应用内配置 跳过此步，启动应用后在控制面板（Control Panel）中直接输入密钥，系统将自动保存。

4. 构建与运行

开发模式运行（支持热重载）：

npm run dev

生产模式运行：

npm start

5. 启用本地语音识别（可选）

若希望完全在本地进行语音转录（保护隐私，无需联网），需下载 whisper.cpp 二进制文件：

npm run download:whisper-cpp

该命令会自动下载适合当前平台的二进制文件至 resources/bin/ 目录。

基本使用

启动应用后，您即可通过以下方式快速体验核心功能：

1. 开始听写 (Dictation)

   • 按下全局快捷键 ` (反引号键) 开始录音。
   • 再次按下该键停止录音。
   • 转录后的文本将自动粘贴到您当前的光标位置。
   • 注：可在设置中自定义快捷键或关闭自动粘贴功能。

2. 使用 AI 助手 (Agent Mode)

   • 呼出玻璃拟态风格的 AI 悬浮窗。
   • 说出 "Hey [您的助手名称]" 或直接输入指令。
   • 支持实时流式对话、笔记创建及上下文检索（RAG）。

3. 会议转录

   • 使用独立的会议快捷键启动录制。
   • 应用会自动检测 Zoom、Teams 等会议软件音频，或通过 Google 日历同步会议安排。

4. 管理笔记

   • 在应用内创建笔记文件夹，支持全文搜索和语义搜索（基于本地 Qdrant 向量库）。
   • 笔记可导出为 Markdown 文件保存到本地文件系统。