开源、基于 AI 的会议助手，支持实时转录与回声消除。

Raven 在会议中同时捕获系统音频和麦克风输入，通过回声消除技术防止扬声器声音串入麦克风，并借助 Deepgram 实现实时双端对话转录。此外，它还能根据上下文为您提供由 Claude 或 OpenAI 提供的 AI 辅助回复——所有这些功能均在您的本地桌面设备上运行。

下载 Raven  |  文档  |  问题反馈

---

截图

仪表盘 — 会话历史	设置 — API 密钥
隐身模式关闭 — 屏幕共享可见叠加层	隐身模式开启 — 屏幕共享不可见叠加层
设置 — 模型选择	引导流程 — 叠加层导览

完整的引导流程（6 步）

第 1 步：欢迎	第 2 步：API 密钥	第 3 步：权限

第 4 步：叠加层导览	第 5 步：快捷键	第 6 步：准备就绪

---

功能

• 双流音频采集 — 系统音频 + 麦克风，分别在 macOS（ScreenCaptureKit）和 Windows（WASAPI）上原生实现
• 回声消除 — 使用 WebRTC AEC3 引擎的 GStreamer 管道（与 Chrome 中使用的回声消除器相同）
• 实时转录 — 通过 WebSocket 连接 Deepgram Nova-3，为麦克风和系统音频分别建立独立通道
• AI 辅助 — Anthropic Claude 或 OpenAI，可通过提供者模式由用户自定义
• 隐身叠加层 — 对 Zoom、Meet、Teams 和 Discord 的屏幕共享完全透明
• 本地优先 — 您的 API 密钥和数据仅存储在本地机器上（使用 better-sqlite3 的 SQLite 数据库）
• RAG — 上传本地文档，利用 @xenova/transformers 进行嵌入，并在 AI 上下文中引用
• 会话管理 — 自动保存完整转录、AI 回答及摘要
• 模式 — 可自定义 AI 行为配置文件，包含系统提示词和快速操作
• 头像编辑器 — 裁剪、缩放和移动后保存您的头像
• 专业版功能 — 可选身份验证、计费和同步服务，适用于付费层级（连接到独立后端）

架构

工作原理

1. 用户启动录音会话
2. 原生二进制程序同时捕获系统音频和麦克风信号
   • macOS： Swift 进程使用 ScreenCaptureKit（系统音频）+ CoreAudio（麦克风）
   • Windows： Rust/NAPI-RS 模块使用 WASAPI 循环和捕获功能
3. 两条音频流被送入 GStreamer 回声消除管道（webrtcechoprobe / webrtcdsp），以避免远端发言者的语音污染麦克风信号
4. 清晰的麦克风音频和系统音频分别通过两条并行的 WebSocket 连接发送至 Deepgram Nova-3 进行转录
5. 转录内容实时显示在叠加窗口中
6. 用户可向 AI（Claude 或 OpenAI）请求帮助，并获得基于完整对话上下文的回复

项目结构

src/
├── main/                  # Electron 主进程
│   ├── audioManager.ts    #   音频采集协调
│   ├── transcriptionService.ts  #   Deepgram WebSocket 连接
│   ├── aiService.ts       #   AI 提供者抽象（Claude / OpenAI）
│   ├── sessionManager.ts  #   会话持久化与历史记录
│   ├── store.ts           #   SQLite 数据库（better-sqlite3）
│   └── index.ts           #   应用生命周期、IPC 处理程序、窗口管理
├── renderer/              # React UI（Vite + Tailwind）
│   └── src/
│       ├── components/    #   仪表盘、叠加层、设置、引导界面
│       └── ...
├── preload/               # Electron 预加载脚本（上下文桥）
└── native/
    ├── swift/             # macOS 音频采集（ScreenCaptureKit + CoreAudio）
    │   └── AudioCapture/
    ├── windows/           # Windows 音频采集（WASAPI，Rust/NAPI-RS）
    └── aec/               # GStreamer AEC C++ 插件（WebRTC AEC3）

平台支持

平台	系统音频	麦克风	回声消除	状态
macOS 12+	ScreenCaptureKit	CoreAudio	GStreamer AEC3	主要平台，已全面测试
Windows 10/11	WASAPI Loopback	WASAPI Capture	GStreamer AEC3	支持
Linux	—	—	—	尚未支持

入门指南

本节提供从零开始到应用运行的完整线性教程。请选择您的平台，按顺序执行每个编号步骤，并在继续下一步之前逐一验证。

API 密钥（首次启动时在应用内输入，无需提前配置）：

• Deepgram — 实时转录（提供免费套餐）
• Anthropic 或 OpenAI — AI 辅助

本指南介绍的是开源版本的应用程序。如需了解高级/专业模式的设置，请参阅 docs/REPO_STRUCTURE.md。

---

macOS 设置

已在 macOS 12（Monterey）至 macOS 15（Sequoia）上测试，涵盖 Intel 和 Apple Silicon 架构。

第 1 步 — 安装 Xcode 命令行工具

xcode-select --install

系统将弹出一个对话框，点击 安装 并等待完成（约 2 分钟）。

验证：

xcode-select -p
# 预期输出：/Library/Developer/CommandLineTools  （或 Xcode.app 路径）

若出现提示 xcode-select: error: command line tools are already installed — 表示您已完成此步骤，可继续。

---

第 2 步 — 安装 Node.js 22

建议通过 nvm 安装。如果您已经拥有 nvm，则可跳过 curl 命令。

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

关闭并重新打开终端，然后执行：

nvm install 22
nvm use 22

验证：

node -v

# 预期：v22.x.x（任意 22+ 版本）

如果出现 nvm: command not found 错误： 请关闭终端并重新打开一个新终端——nvm 的安装脚本会将其自身添加到你的 shell 配置文件中，但只有新的 shell 才能加载它。

---

步骤 3 — 安装 GStreamer

brew install gstreamer gst-plugins-base gst-plugins-good gst-plugins-bad

如果你还没有 Homebrew，请先从 brew.sh 安装。

验证：

pkg-config --modversion gstreamer-1.0
# 预期：1.24.x（或类似版本）

如果出现 Package gstreamer-1.0 was not found 错误： 这是因为 Homebrew 的 pkg-config 路径未正确设置。请将以下行添加到你的 ~/.zshrc 文件，并重启终端：

# Apple Silicon（M1/M2/M3/M4）：
echo 'export PKG_CONFIG_PATH="/opt/homebrew/lib/pkgconfig:$PKG_CONFIG_PATH"' >> ~/.zshrc

# Intel Mac：
echo 'export PKG_CONFIG_PATH="/usr/local/lib/pkgconfig:$PKG_CONFIG_PATH"' >> ~/.zshrc

---

步骤 4 — 克隆仓库并安装依赖

git clone https://github.com/Laxcorp-Research/project-raven.git
cd project-raven
npm install

npm install 需要几分钟时间。它会通过 postinstall 脚本自动为 Electron 重新构建 better-sqlite3——在最后你会看到 @electron/rebuild 的输出。

验证：

ls node_modules/.package-lock.json && echo "OK"
# 预期：OK

如果 npm install 因 node-gyp 错误而失败： 请确保在步骤 1 中已成功安装 Xcode 命令行工具。运行 xcode-select -p 来确认。

---

步骤 5 — 构建 GStreamer 回声消除插件

cd src/native/aec
npm install
./build-deps.sh
npx cmake-js compile
cd ../../..

具体操作：

1. 安装插件的构建工具（cmake-js、node-addon-api）
2. 验证所有 GStreamer 库，并从源代码编译 WebRTC DSP 插件（Homebrew 不提供该插件）
3. 编译 C++ 回声消除原生模块

验证：

ls src/native/aec/build/Release/raven-aec.node && echo "OK"
# 预期：OK

如果 build-deps.sh 因“gstreamer-1.0 未找到”而失败： 请返回步骤 3，确保 pkg-config --modversion gstreamer-1.0 可以正常工作。

如果 cmake-js compile 因“cmake 未找到”而失败： cmake 已经捆绑在 cmake-js 中。运行 npx cmake-js --version——如果仍然失败，请删除 src/native/aec/ 目录下的 node_modules，然后重新运行 npm install。

---

步骤 6 — 构建 Swift 音频捕获二进制文件

cd src/native/swift/AudioCapture
swift build -c release
cd ../../../..

验证：

ls src/native/swift/AudioCapture/.build/release/audiocapture && echo "OK"
# 预期：OK

如果 swift build 因未解析的导入而失败： 你的 Swift 工具链可能太旧了（需要 5.9 或更高版本）。请使用 swift --version 检查版本。同时更新 Xcode 命令行工具：

sudo rm -rf /Library/Developer/CommandLineTools && xcode-select --install

---

步骤 7 — 运行应用

npm run dev

Electron 应用程序将会打开。首次启动时，系统会提示你在设置中输入 API 密钥。

如果应用程序启动但音频捕获无法工作： macOS 需要显式权限。前往 系统设置 → 隐私与安全性，授予应用程序（或开发期间的终端模拟器）麦克风和屏幕录制访问权限。

---

Windows 系统设置

经过 Windows 10（21H2+）和 Windows 11 测试。所有命令均适用于 PowerShell。每次安装完成后，请打开一个 新终端以使 PATH 变量生效。

步骤 1 — 安装 Visual Studio Build Tools

下载并运行 Visual Studio Build Tools 安装程序。

在安装程序中，勾选 “使用 C++ 的桌面开发” 工作负载，然后点击安装。确保选择以下可选组件（默认应已选中）：

• MSVC 构建工具（适用于 x64/x86，最新版本）
• Windows 10/11 SDK
• Windows 专用的 C++ CMake 工具

验证：

& "${env:ProgramFiles(x86)}\Microsoft Visual Studio\Installer\vswhere.exe" -products * -requires Microsoft.VisualStudio.Workload.VCTools -property displayName
# 预期：Visual Studio Build Tools 2022

如果你已经拥有完整的 Visual Studio（而不仅仅是 Build Tools），并且安装了 C++ 工作负载，也可以使用。

---

步骤 2 — 安装 Node.js（LTS）

选项 A — 使用 nvm-windows（推荐）：

下载并运行最新的 nvm-setup.exe 文件，然后打开一个 新终端：

nvm install 22
nvm use 22

选项 B — 直接从 nodejs.org 下载 LTS 22.x 的 MSI 安装程序。

验证（在 新终端中）：

node -v
# 预期：v22.x.x

为什么特别选择 Node 22？ 该项目要求 node >= 22.12.0（参见 package.json 中的 engines 字段）。如果使用 nvm install lts，可能会安装尚未经过测试的新大版本。

---

步骤 3 — 安装 Python

Python 是 node-gyp 编译原生 Node.js 模块（better-sqlite3、bufferutil 等）所必需的。

选项 A — 使用 winget：

winget install Python.Python.3.12 --source winget

选项 B — 从 python.org 下载。安装时请确保勾选“将 Python 添加到 PATH”。

验证（在 新终端中）：

python --version
# 预期：Python 3.x.x

---

步骤 4 — 安装 Rust 工具链

下载并运行 rustup-init.exe。接受默认设置（安装 stable-msvc）。

验证（在 新终端中）：

rustc --version
# 预期：rustc 1.xx.x (...)
rustup default stable-msvc

---

步骤 5 — 安装 GStreamer（MSVC）

从 gstreamer.freedesktop.org/download 下载 MSVC x86_64 安装程序——点击 Windows → MSVC x86_64（VS 2022，Release CRT）。

对于 GStreamer 1.28+，有一个合并的安装包（运行时 + 开发环境）。对于较旧的版本，则需要分别下载运行时和开发环境的 MSI 文件。

按照默认设置运行安装程序。通常安装路径为 C:\gstreamer\ 或 C:\Program Files\gstreamer\。

安装完成后，在 新终端中验证环境变量是否已设置：

echo $env:GSTREAMER_1_0_ROOT_MSVC_X86_64

# 预期：C:\gstreamer\1.0\msvc_x86_64\（或 C:\Program Files\gstreamer\1.0\msvc_x86_64\）

同时，请确保 GStreamer 的 bin 目录已添加到你的 PATH 环境变量中：

$gstRoot = $env:GSTREAMER_1_0_ROOT_MSVC_X86_64
if ($gstRoot) { echo "GStreamer 根目录：$gstRoot" } else { echo "未设置 - 请参阅下方" }

如果该变量为空： 安装程序未设置它。请找到 GStreamer 的安装位置并手动设置：

# 请根据您的安装路径调整以下路径
[Environment]::SetEnvironmentVariable("GSTREAMER_1_0_ROOT_MSVC_X86_64", "C:\Program Files\gstreamer\1.0\msvc_x86_64\", "User")

然后 重启终端。

如果 GStreamer 安装到了 C:\Program Files\gstreamer\ 而不是 C:\gstreamer\： 这没有问题 — 只需确保环境变量指向正确的路径（例如 C:\Program Files\gstreamer\1.0\msvc_x86_64\）。

---

步骤 6 — 安装 CMake

编译 GStreamer 回声消除插件需要 CMake。

winget install Kitware.CMake --source winget

或者从 cmake.org/download 下载。请确保勾选“添加到 PATH”。

在 新终端 中验证：

cmake --version
# 预期：cmake version 3.x.x

---

步骤 7 — 克隆仓库并安装依赖

git clone https://github.com/Laxcorp-Research/project-raven.git
cd project-raven
npm install

npm install 需要几分钟时间。它会通过 postinstall 脚本自动为 Electron 重新构建 better-sqlite3。

验证：

Test-Path node_modules\.package-lock.json
# 预期：True

如果 npm install 报错“无法找到任何 Python 安装”： 请返回步骤 3 — 必须安装 Python 并将其添加到 PATH。

如果 npm install 报错“无法找到任何 Visual Studio 安装”： node-gyp 无法自动检测你的 Build Tools。请按顺序尝试以下修复方法：

# 修复 1：为 node-gyp 设置版本提示
npm config set msvs_version 2022
Remove-Item -Recurse -Force node_modules
npm install

如果较新的 npm 版本对 npm config set msvs_version 报错，可以改用环境变量：

# 修复 2：环境变量（适用于所有 npm 版本）
$env:GYP_MSVS_VERSION = "2022"
Remove-Item -Recurse -Force node_modules
npm install

---

步骤 8 — 构建 GStreamer 回声消除插件

首先，检查项目使用的 Electron 版本：

node -e "console.log(require('./node_modules/electron/package.json').version)"
# 记下版本号（例如 40.4.1）

然后针对该版本构建插件：

cd src\native\aec
npm install
npx cmake-js compile --runtime electron --runtime-version <ELECTRON_VERSION>
cd ..\..\..

将 <ELECTRON_VERSION> 替换为上一条命令中的版本号（例如 40.4.1）。

重要提示： --runtime electron --runtime-version 标志是必需的。如果没有这些标志，插件将被编译为 Node.js 版本而非 Electron 版本，并且在加载时会 崩溃。如果你后续升级了 Electron，必须使用新版本重新构建此插件。

注意： build-deps.sh 脚本仅适用于 macOS。在 Windows 上，GStreamer MSVC 安装程序已经包含了所有必要的插件（包括 WebRTC DSP）。

验证：

Test-Path src\native\aec\build\Release\raven-aec.node
# 预期：True

如果 cmake-js 报错“未安装 CMake”： 请返回步骤 6。

如果 cmake-js 报错“未找到 GStreamer”： GSTREAMER_1_0_ROOT_MSVC_X86_64 环境变量未设置。请返回步骤 5。

如果构建成功但链接失败，出现“未解析的外部符号 g_object_set / g_type_check_instance_cast”错误： 链接步骤中缺少 GLib/GObject 库。这应由 CMakeLists.txt 自动处理 — 如果遇到此错误，请提交 bug 报告。

---

步骤 9 — 构建 Windows 音频捕获模块

cd src\native\windows
npm install
npx napi build --platform --release
cd ..\..\..

验证：

Test-Path src\native\windows\raven-windows-audio.win32-x64-msvc.node
# 预期：True

如果构建因链接器错误而失败： 确保 Rust 使用 MSVC 目标：rustup default stable-msvc。

如果因“未找到 Windows SDK”而失败： 打开 Visual Studio Installer → 修改 → 个别组件，并安装最新的“Windows 10 SDK”或“Windows 11 SDK”。

---

步骤 10 — 运行应用

npm run dev

Electron 应用将打开。首次启动时，你将看到一个包含 6 个步骤的引导流程 — 请输入你的 API 密钥（Deepgram 用于转录，Claude 或 OpenAI 用于 AI 辅助）。

如果应用启动但音频捕获不起作用： 检查 设置 → 声音，确保已将正确的播放和录音设备设置为默认设备。WASAPI 会从默认设备捕获音频。

---

设置故障排除快速参考

症状	可能原因	解决方法
无法找到任何 Python 安装	未安装 Python	安装 Python 3.x 并将其添加到 PATH（Windows 步骤 3）
无法找到可用的 Visual Studio 安装	node-gyp 无法自动检测 Build Tools	设置 $env:GYP_MSVS_VERSION = "2022"，删除 node_modules，重新运行 npm install
npm install 因 node-gyp 错误而失败	缺少 C/C++ 构建工具	macOS： xcode-select --install Windows： 安装 VS Build Tools “桌面开发 with C++”工作负载
运行时出现 NODE_MODULE_VERSION 不匹配	原生模块为错误的 Electron 版本构建	在项目根目录运行 npx @electron/rebuild -f -w better-sqlite3
build-deps.sh：“未找到 gstreamer-1.0”	GStreamer 未安装或 pkg-config 无法找到它	macOS： 通过 Homebrew 安装并检查 PKG_CONFIG_PATH（参见 macOS 步骤 3）
cmake-js：“未安装 CMake”	CMake 未在 PATH 中	安装 CMake（Windows 步骤 6）
cmake-js：“未找到 GStreamer”（Windows）	GSTREAMER_1_0_ROOT_MSVC_X86_64 未设置	手动设置环境变量并重启终端（参见 Windows 步骤 5）
AEC 插件在 Electron 启动时崩溃	为 Node.js 而非 Electron 构建	使用 --runtime electron --runtime-version <your-electron-version> 重新构建（Windows 步骤 8）
swift build 失败	Swift 工具链版本过低（需 5.9+）	sudo rm -rf /Library/Developer/CommandLineTools && xcode-select --install
Windows 上 napi build 出现链接器错误	Rust 目标错误或缺少 Windows SDK	rustup default stable-msvc，并确保已安装 VS Build Tools C++ 工作负载
应用启动但 macOS 上无音频	缺少系统权限	系统设置 → 隐私与安全性：授予 麦克风 和 屏幕录制 权限
应用启动但 Windows 上无音频	默认音频设备设置错误	设置 → 声音：设置正确的默认播放/录音设备

键盘快捷键

操作	快捷键
切换叠加层	Cmd + \
开始/停止录制	Cmd + R
获取 AI 建议	Cmd + Enter
清除对话	Cmd + Shift + R
移动叠加层	Cmd + 方向键
滚动叠加层	Cmd + Shift + 上/下

在 Windows 系统上，请将 Cmd 替换为 Ctrl。

测试

npm test              # 单元测试 + 集成测试
npm run test:coverage # 包含覆盖率报告
npm run test:e2e      # 端到端测试（需先运行 npm run build）
npm run test:all      # 运行所有测试

故障排除

better-sqlite3 原生模块错误：

postinstall 脚本会自动处理此问题。如果仍然出现 NODE_MODULE_VERSION 不匹配的错误：

npx @electron/rebuild -f -w better-sqlite3

重置所有数据（全新启动）：

# macOS
rm -rf ~/Library/Application\ Support/project-raven/

# Windows
rmdir /s /q "%APPDATA%\project-raven"

参与贡献

欢迎提交问题和拉取请求。该项目目前处于积极开发中。

1. 克隆仓库并创建分支
2. 创建你的功能分支 (git checkout -b feature/my-feature)
3. 提交更改 (git commit -m '添加我的功能')
4. 推送到分支 (git push origin feature/my-feature)
5. 打开拉取请求

许可证

MIT

Project Raven 快速上手指南

Project Raven 是一款开源的 AI 会议助手，支持实时转录、回声消除和本地运行的 AI 辅助功能。它能在 macOS 和 Windows 上捕获系统音频与麦克风音频，并通过 Deepgram 进行实时转录，结合 Claude 或 OpenAI 提供上下文感知的智能回复。

环境准备

系统要求

• macOS: 12 (Monterey) 至 15 (Sequoia)，支持 Intel 和 Apple Silicon (M1/M2/M3/M4)
• Windows: 10 (21H2+) 或 11
• Linux: 暂不支持

前置依赖

在开始之前，请确保准备好以下 API Key（首次启动应用时输入即可）：

• Deepgram: 用于实时转录（提供免费额度）
• Anthropic (Claude) 或 OpenAI: 用于 AI 智能辅助

---

安装步骤

🍎 macOS 安装流程

1. 安装 Xcode 命令行工具

xcode-select --install

验证: xcode-select -p 应返回路径。

2. 安装 Node.js 22 推荐使用 nvm 管理版本：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

关闭并重新打开终端后执行：

nvm install 22
nvm use 22

验证: node -v 应显示 v22.x.x。

3. 安装 GStreamer

brew install gstreamer gst-plugins-base gst-plugins-good gst-plugins-bad

注意: 若使用 Apple Silicon，可能需要配置 PKG_CONFIG_PATH：

echo 'export PKG_CONFIG_PATH="/opt/homebrew/lib/pkgconfig:$PKG_CONFIG_PATH"' >> ~/.zshrc
source ~/.zshrc

4. 克隆项目并安装依赖

git clone https://github.com/Laxcorp-Research/project-raven.git
cd project-raven
npm install

5. 构建回声消除 (AEC) 原生模块

cd src/native/aec
npm install
./build-deps.sh
npx cmake-js compile
cd ../../..

6. 构建 Swift 音频捕获二进制文件

cd src/native/swift/AudioCapture
swift build -c release
cd ../../../..

7. 启动应用

npm run dev

重要: 首次运行时，需在 系统设置 -> 隐私与安全性 中授予应用 麦克风 和 屏幕录制 权限。

---

🪟 Windows 安装流程

所有命令请在 PowerShell 中运行，每步安装后建议重启终端以刷新环境变量。

1. 安装 Visual Studio Build Tools 下载并运行 Visual Studio Build Tools 安装程序。

• 勾选 "使用 C++ 的桌面开发" 工作负载。
• 确保包含：MSVC 生成工具、Windows 10/11 SDK、C++ CMake 工具。

2. 安装 Node.js 22 推荐使用 nvm-windows： 下载 nvm-setup.exe 安装后，在新终端执行：

nvm install 22
nvm use 22

验证: node -v 应显示 v22.x.x。

3. 安装 Python Node 原生模块编译需要 Python 3.x。

winget install Python.Python.3.12 --source winget

注意: 安装时务必勾选 "Add to PATH"。

4. 安装 Rust 工具链 下载并运行 rustup-init.exe，保持默认设置安装。 验证: rustc --version 应输出版本号。

5. 克隆项目并安装依赖

git clone https://github.com/Laxcorp-Research/project-raven.git
cd project-raven
npm install

6. 构建回声消除 (AEC) 原生模块

cd src/native/aec
npm install
# Windows 下通常不需要运行 build-deps.sh，直接编译
npx cmake-js compile
cd ../../..

7. 启动应用

npm run dev

---

基本使用

1. 配置密钥：应用启动后，进入设置页面，依次填入 Deepgram、Anthropic (或 OpenAI) 的 API Key。
2. 开始会议：点击主界面的 "Start Session" 按钮。Raven 将自动捕获系统声音（对方发言）和麦克风声音（你的发言）。
3. 实时交互：
   • 屏幕上将显示半透明悬浮窗，实时展示双方对话转录文本。
   • 在悬浮窗中输入问题，AI 将基于当前会议上下文提供即时回答或建议。
4. 隐身模式：在设置中开启 "Stealth Mode"，悬浮窗在进行屏幕共享（如 Zoom、Teams）时将对他不可见，仅你自己可见。
5. 查看历史：会议结束后，数据自动保存至本地数据库。可在 Dashboard 中查看完整的转录记录、AI 回复及会议摘要。