Voxlert：基于LLM与TTS的AI编程助手语音通知系统-深圳市維司達科技有限公司

1. 项目概述

如果你和我一样，同时开着好几个AI编程助手窗口——比如Claude Code在重构一个模块，Cursor在写单元测试，pi在生成文档——那你肯定经历过这种场景：某个窗口“叮”的一声提示音响起，你不得不停下手里的事，挨个Alt+Tab切换过去，看看究竟是哪个助手完成了任务，或者哪个遇到了错误在等你。这种频繁的上下文切换，对专注力是种巨大的消耗。更别提有时候你戴着耳机，听到的只是千篇一律的“叮咚”声，根本分不清声音来自哪个应用。

Voxlert就是为了解决这个痛点而生的。它不是一个简单的提示音替换工具，而是一个基于LLM生成、带有鲜明角色语音的通知系统。它的核心逻辑是：为每个AI助手会话赋予一个独特的游戏角色声音（比如《星际争霸》的副官、《半条命》的HEV防护服），当特定事件发生时（如任务完成、工具调用失败），系统会调用LLM生成一句符合该角色性格和语境的短语（例如“任务序列已执行完毕，指挥官”或“检测到异常，需要人工干预”），再通过本地TTS（文本转语音）引擎合成语音播放出来。

这样一来，你听到的就不再是单调的“叮”，而是“代码编译通过，系统效能提升12%”或“警告：依赖解析失败，建议检查网络连接”。通过语音内容和音色的差异，你甚至不用看屏幕，就能瞬间判断出是哪个助手、发生了什么事。这对于需要并行处理多个AI会话的开发者来说，效率提升是立竿见影的。

1.1 核心需求解析

Voxlert的设计目标非常明确：在复杂的多任务并行编程环境中，提供一种无需视觉交互、即可清晰区分和识别不同AI助手状态变更的音频反馈机制。为了实现这个目标，它需要解决几个关键问题：

事件捕获的通用性：必须能无缝接入主流的AI编程助手（Claude Code, Cursor, OpenAI Codex, pi, OpenClaw），监听它们内部的各种生命周期事件（会话开始/结束、任务完成、错误等）。
通知内容的动态性与个性化：通知内容不能是固定的几句话，否则很快就会听腻（“语音墙纸化”）。必须结合事件上下文，动态生成符合预设角色设定的、不重复的、有信息量的短语。
极低的感知与操作成本：作为辅助工具，它本身不能成为负担。安装配置要简单，运行时资源占用要低，延迟要小，不能干扰主工作流。
隐私与成本可控：理想情况下，所有处理（尤其是语音生成）应在本地完成，避免敏感代码上下文上传云端。即使使用云服务，成本也应极低或可预测。

Voxlert的架构正是围绕这些需求构建的。它采用“本地优先”的混合架构：事件捕获和音频播放完全在本地；语音生成（LLM）可根据需要选择云端廉价小模型或完全本地的Ollama/LM Studio；语音合成（TTS）则强力推荐本地GPU方案。这种设计在功能、成本和隐私之间取得了很好的平衡。

1.2 目标用户与适用场景

Voxlert并非适合所有人。它的价值与你的工作流复杂度正相关。

核心用户：同时运行两个或以上AI编程助手会话的开发者。例如，前端用Cursor写UI，后端用Claude Code设计API，同时用pi生成测试数据。Voxlert能让你在听到语音的瞬间就知道是哪个环节出了结果或问题。
次要用户：追求个性化与沉浸式工作环境的极客玩家。即使只用一个助手，为它配上《系统震撼》里SHODAN那种带着嘲讽的合成音来汇报工作，也能给枯燥的编程增添不少乐趣。
不适用的情况：如果你始终只在一个全屏的IDE窗口中工作，且很少被后台通知打断，那么Voxlert带来的效用提升有限，它更像一个有趣的“皮肤”或增强体验的插件。

从技术门槛看，你需要对命令行有基本了解，能够完成Node.js、Python环境以及可能需要的音频工具（如FFmpeg）的安装。如果你追求完全离线的体验，还需要一张性能尚可的显卡（用于本地TTS）和一定的动手能力来部署本地LLM。不过，项目提供了从简到繁的多种配置路径，你可以从最简单的“仅文本通知+云端LLM”开始，再逐步升级到“全本地化”方案。

2. 核心架构与工作流拆解

要理解Voxlert如何运作，我们可以把它想象成一个高度自动化的“广播电台”。不同的AI助手是新闻来源（记者），Voxlert是电台制作中心，而你的耳朵就是听众。整个工作流可以分为四个核心阶段：信号采集、内容编排、语音合成、音频播出。

2.1 信号采集：无处不在的“钩子”

Voxlert本身不主动监控AI助手，而是通过“钩子”被动接收事件。这就像在每个助手内部安装了一个触发器，当特定事件发生时，助手会主动调用Voxlert并告知：“我这边发生了一件事。”

graph TD subgraph “AI 助手” A1[Claude Code] -->|生命周期事件| H1[Hook 脚本] A2[Cursor IDE] -->|Hook 事件| H2[Hooks.json 配置] A3[OpenAI Codex] -->|Notify 配置| H3[CLI 调用] A4[pi] -->|扩展事件| H4[TypeScript 扩展] A5[OpenClaw] -->|插件事件| H5[独立插件] end subgraph “Voxlert 核心” H1 --> B[统一事件接收器 voxlert hook] H2 --> B H3 --> B H4 --> B H5 --> B B --> C{事件分类与路由} end

为什么采用钩子模式？这是侵入性最小、兼容性最好的方案。每个AI助手都提供了官方的扩展点（如Claude Code的postMessage钩子、Cursor的hooks.json）。Voxlert只需要在这些点上注册一个简单的命令行调用，就能获取到结构化的事件数据。这避免了去解析IDE的日志文件或进程状态，后者不稳定且容易随版本更新而失效。voxlert setup命令的核心工作之一，就是帮你自动在支持的平台写入这些钩子配置。

事件标准化：不同助手的事件名称和数据结构各异。Voxlert在内部做了一个标准化映射，将五花八门的原始事件（如Cursor的postToolUseFailure、pi的tool_result (error)）统一归类到几个抽象的“事件类别”下，例如task.error。这样，后续的处理逻辑只需要关心类别，而不必为每个平台写适配代码，大大简化了系统复杂度。

2.2 内容编排：LLM作为“编剧”

收到一个标准化事件后，Voxlert需要决定播放什么内容。这里有两种路径：

上下文事件：对于task.complete（任务完成）、task.error（工具调用失败）等富含上下文信息的事件，Voxlert会请出“编剧”——LLM。它会将当前事件类别、活跃的语音包角色设定（如“你是《星际争霸》中的副官，语气专业、冷静、略带电子音”）作为提示词，要求LLM生成一句简短（通常10-20个单词）、符合角色性格的短语。例如，对于一次成功的代码生成，LLM可能会生成“编译序列已优化，执行效率在预期参数内”。
常规事件：对于session.start（会话开始）、session.end（会话结束）等上下文较少的事件，则直接从当前语音包的预置短语库中随机选取一句。例如，副官语音包的session.start备用短语可能是“系统连线，待命”。

LLM选型与成本控制：这是Voxlert设计精妙之处。它不需要也不推荐使用Claude-3 Opus或GPT-4这类大型、昂贵的模型。生成一句通知短语是典型的“小任务”，对逻辑和创意要求不高，但对速度和成本极其敏感。因此，它默认使用OpenRouter上的廉价小模型（如qwen2.5:7b、gemma2:9b），单次调用成本通常低于0.1美分。如果你一天收到上百次通知，总成本可能也就几美分。更激进一点，你可以配置本地的Ollama服务，使用完全免费的本地小模型，实现零成本运行。

实操心得：提示词工程Voxlert内置的LLM提示词经过了精心调校，核心是“简短、角色化、信息明确”。它会告诉模型：“你是一个[角色名]，用第一人称说话，语气[描述]。针对[事件类型]事件，生成一句10-15个单词的短语。不要使用Markdown，不要添加额外解释。” 如果你自行创建语音包，编写角色设定时也应遵循这个原则：用一两句话清晰定义角色的身份、性格和说话方式，这比罗列大量背景故事更有效。

2.3 语音合成：让角色“开口说话”

得到文本短语后，下一步就是将其转化为音频。Voxlert支持两种本地TTS后端，它们共同的特点是高质量、可定制、完全离线运行。

Qwen3-TTS（推荐）：通义千问团队开源的TTS模型。它的优势在于声音自然度极高，支持多种语言和情感风格，并且对硬件要求相对友好。在Apple Silicon Mac或拥有8GB以上显存的NVIDIA GPU上，它可以达到实时的合成速度。你需要运行一个独立的Python服务（qwen3-tts-server）来提供API。
Chatterbox：另一个功能强大的本地TTS解决方案。它可能在某些特定音色或功能上（如更精细的语音克隆）有优势，但通常对GPU资源要求更高一些。

为什么坚持本地TTS？

隐私：你的通知文本（可能包含代码片段或错误信息）无需上传到任何云端服务。
零延迟与零成本：一旦服务启动，合成是即时的，且没有按字符或按次计费的压力。
可玩性：本地模型允许进行更深度的定制，比如调整语速、音调，甚至结合SoX工具添加混响、电台滤波等音效，让“副官”的声音听起来更像来自星际战舰的通讯系统。

音频后处理流水线：生成的原始音频通常会经过一个处理链：标准化（统一音量）、缓存（避免重复合成相同短语）、序列化播放（防止多个音频同时播放造成重叠杂音）。在macOS上，它使用系统自带的afplay；在Windows/Linux上，则依赖ffplay（FFmpeg的一部分）。如果你安装了SoX，还可以在这个链中加入额外的音效处理。

2.4 整体工作流与缓存策略

让我们串起整个流程：当你在Cursor中执行一次成功的代码生成后：

Cursor触发stop钩子，调用voxlert cursor-hook。
Voxlert将其映射为task.complete事件，并加载当前激活的“SC1 Kerrigan”语音包配置。
由于是上下文事件，Voxlert构造提示词，调用配置的LLM（例如本地Ollama的llama3.2:3b模型）。
LLM返回：“虫群的力量已注入这段代码，它现在充满活力。”
Voxlert将这段文本和当前语音包ID、音色参数组合成一个缓存键，检查本地缓存。如果未命中，则发送文本到Qwen3-TTS服务。
Qwen3-TTS合成音频，返回.wav文件。Voxlert将其存入缓存，并加入播放队列。
播放队列确保音频按序播放，通过afplay输出，你听到Kerrigan的声音：“虫群的力量已注入这段代码，它现在充满活力。”
同时，一个系统通知（或Voxlert自定义弹窗）会显示同样的文字。

缓存是性能关键：LLM生成和TTS合成是流程中最耗时的两步。Voxlert采用LRU（最近最少使用）缓存策略，为每个“短语文本+语音参数”组合缓存最终的音频文件。这意味着常用的通知短语（如各种“任务完成”的变体）在第一次生成后，后续调用几乎是瞬间播放，体验非常流畅。

3. 从零开始：详细安装与配置指南

理论讲完，我们动手把它装起来。我将以一台macOS设备为例，演示最完整的“全本地化”配置方案（本地LLM + 本地TTS），并穿插说明Windows/Linux的差异点。如果你希望从更简单的云端LLM方案开始，可以跳过相应步骤。

3.1 基础环境准备

首先，我们需要安装Voxlert赖以运行的“地基”。

安装Node.js：Voxlert CLI工具本身由Node.js编写。请确保安装Node.js 18或更高版本。
- macOS：最推荐使用Homebrew：打开终端，执行brew install node。
- Windows：从 Node.js官网下载LTS版本的安装程序，安装时务必勾选“Add to PATH”选项。
- Linux (Ubuntu/Debian)：可以使用NodeSource的PPA。
```
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs
```
安装后，在终端运行node --version和npm --version确认版本。
安装音频播放工具：
- macOS：系统自带afplay，无需额外安装。
- Windows/Linux：需要安装FFmpeg，并确保其bin目录（包含ffplay）在系统PATH环境变量中。
  - Windows：从 FFmpeg官网下载构建版本，解压后将ffmpeg-master-latest-win64-gpl\bin的完整路径添加到系统环境变量PATH中。
  - Linux (Ubuntu/Debian)：sudo apt install ffmpeg在终端运行ffplay -version(Windows/Linux) 或afplay --help(macOS) 验证。
（可选）安装SoX：如果你想要音频特效（如无线电失真、回声），可以安装SoX。macOS上使用brew install sox，其他系统请参考官方文档。

3.2 部署本地TTS后端（以Qwen3-TTS为例）

这是实现高质量离线语音的关键。我强烈推荐Qwen3-TTS，它在音质和性能上取得了很好的平衡。

确保Python环境：需要Python 3.13或更高版本。使用python3 --version检查。

克隆并安装TTS服务器：

# 克隆Voxlert仓库（其中包含TTS服务器代码） git clone https://github.com/settinghead/voxlert.git cd voxlert/qwen3-tts-server # 创建并激活Python虚拟环境（推荐，避免依赖冲突） python3 -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate # 安装依赖 pip install -r requirements.txt

下载语音模型：Qwen3-TTS需要下载特定的语音模型文件。根据你的网络环境，可以选择从Hugging Face或Modelscope下载。项目README中通常会提供下载命令，例如：
```
# 示例命令，请以实际README为准 huggingface-cli download Qwen/Qwen3-TTS-1.8B --local-dir ./models
```
启动TTS服务器：
```
python app.py --model-path ./models/Qwen3-TTS-1.8B --port 8003
```
启动成功后，你应该看到类似“Running on http://0.0.0.0:8003”的输出。让这个终端窗口保持运行。

注意事项：GPU与内存Qwen3-TTS在GPU上运行速度远快于CPU。如果你有NVIDIA GPU，确保PyTorch安装了CUDA版本。Apple Silicon Mac可以使用MPS后端（通常自动启用）。模型加载需要约2-3GB GPU显存和额外的系统内存。如果合成速度慢，可以尝试在启动命令中添加--half参数使用半精度浮点数，或使用更小的模型变体。

3.3 部署本地LLM服务（以Ollama为例）

为了实现完全离线，我们还需要一个本地LLM服务来生成短语。

安装Ollama：前往 Ollama官网下载并安装。
拉取一个小型语言模型：我们需要一个速度快、体积小的模型。llama3.2:3b或qwen2.5:7b都是不错的选择。
```
ollama pull llama3.2:3b
```
启动Ollama服务：Ollama安装后通常会自动以服务形式运行。你可以通过ollama serve命令在前台启动，或访问http://localhost:11434查看API状态。

3.4 安装与配置Voxlert CLI

基础服务就绪，现在来安装主角。

全局安装CLI工具：
```
npm install -g @settinghead/voxlert
```
安装完成后，在终端输入voxlert --version应能显示版本号。
运行初始化向导：这是最关键的一步，交互式配置所有环节。
```
voxlert --onboard # 或者 voxlert setup
```
向导会一步步引导你：
- 选择LLM后端：选择local。
- 配置LLM API：URL填写http://localhost:11434/v1（Ollama默认），模型填写你拉取的模型名，如llama3.2:3b。API密钥留空。
- 选择TTS后端：选择qwen。
- 配置TTS服务器：URL填写http://localhost:8003（即你启动Qwen3-TTS的地址和端口）。
- 选择语音包：从列表中选择一个你喜欢的角色，比如sc1-adjutant（星际争霸1副官）。
- 安装平台钩子：向导会检测你系统上已安装的AI助手（如Claude Code、Cursor），并询问你是否为其安装钩子。建议全部选择“是”。
测试安装：
```
voxlert test "初始化测试，所有系统在线"
```
如果一切正常，你将听到选择的角色用对应的声音读出这句话，并看到一个系统通知。

3.5 配置AI助手集成

初始化向导通常已经帮你配置好了钩子。但了解其原理有助于排查问题。

Cursor：检查~/.cursor/hooks.json文件，应该包含了对voxlert cursor-hook的调用。
Claude Code：Voxlert会通过Claude Code的插件系统注册一个技能。
pi：如果通过向导安装，会在~/.pi/agent/extensions/下生成一个TypeScript扩展文件。
OpenClaw：需要单独安装插件，请参考项目文档中docs/openclaw.md的说明。

验证集成：打开你配置好的AI助手（如Cursor），执行一个会让助手“思考”并完成的任务。当任务结束时，你应该能听到角色语音通知。

4. 高级配置、管理与问题排查

系统运行起来后，你可以根据个人喜好进行深度定制，并学会如何解决常见问题。

4.1 语音包管理与自定义

Voxlert的魅力之一在于丰富的角色语音。管理它们非常简单：

列出所有可用语音包：voxlert pack list
查看当前使用包详情：voxlert pack show
切换语音包：voxlert pack use <pack-id>，例如voxlert pack use hl-hev-suit切换到《半条命》HEV防护服音效。
语音包目录：下载的语音包资源存储在~/.voxlert/packs/目录下，里面包含角色设定、备用短语和图标等。

创建自定义语音包：如果你对现有角色不满意，可以创建自己的语音包。这需要一些编辑工作：

在~/.voxlert/packs/下创建一个新目录，如my-custom-voice。
创建pack.json文件，定义包ID、名称、描述、作者等元数据。
创建phrases.json文件，为每个事件类别（session.start,task.complete等）定义一组备用的固定短语数组。
最关键的是character.txt文件，用一段文字精确描述角色的声音、性格和说话方式。这将作为LLM生成动态短语的提示词基础。
将包目录路径告知Voxlert，或打包后通过社区分享。

4.2 精细化的通知控制

你可能不希望所有事件都“开口说话”。Voxlert提供了细粒度的控制。

全局开关：voxlert config set enabled false可以完全静默Voxlert。
按事件类别禁用：这是最常用的控制方式。例如，你觉得每次提交提示词（task.acknowledge）都说话太吵，可以关闭它：
```
voxlert config set categories.task.acknowledge false
```
同时，保留任务完成和错误通知：
```
voxlert config set categories.task.complete true voxlert config set categories.task.error true
```
调整音量：voxlert volume交互式调整，或voxlert volume 70直接设置百分比。
更改通知样式：voxlert notification命令可以在“系统原生通知”、“Voxlert简约弹窗”和“完全关闭视觉通知”之间切换。

4.3 常见问题与排查实录

即使按照指南操作，也可能会遇到问题。以下是我在实测中遇到的一些典型情况及其解决方法。

问题1：运行voxlert test能听到声音，但AI助手工作时没有通知。

排查思路：这几乎总是钩子集成的问题。
- 检查钩子是否安装：运行voxlert setup查看各平台集成状态，并重新安装。
- 检查AI助手配置：以Cursor为例，确认~/.cursor/hooks.json文件存在且内容正确。可以尝试手动添加一个简单的测试钩子，看Cursor是否会执行。
- 重启AI助手：修改钩子配置后，必须完全重启Cursor、Claude Code等应用，新的钩子才会生效。
- 查看调试日志：Voxlert会生成详细的钩子调试日志~/.voxlert/hook-debug.log。在AI助手触发事件时，查看这个日志文件，看是否收到了事件，以及事件数据是什么。

问题2：语音播放卡顿、延迟高，或TTS合成失败。

排查思路：聚焦于TTS后端和网络。
- 确认TTS服务运行：检查运行Qwen3-TTS或Chatterbox的终端，看是否有错误输出。尝试用curl直接测试TTS API：
```
curl -X POST http://localhost:8003/tts \ -H "Content-Type: application/json" \ -d '{"text": "测试", "voice": "default"}' \ --output test.wav
```
  如果能生成test.wav并播放，说明TTS服务正常。
- 检查Voxlert配置：运行voxlert config，确认tts_backend和chatterbox_url（或Qwen的配置）正确指向了你的本地服务地址和端口。
- 资源瓶颈：本地TTS是计算密集型任务。打开系统活动监视器，查看CPU/GPU和内存使用情况。如果资源吃紧，合成自然会慢。考虑关闭其他占用GPU的大型应用。

问题3：LLM生成的短语不理想，或不符合角色性格。

排查思路：问题出在提示词或模型上。
- 检查角色设定：运行voxlert pack show，查看当前语音包的character.txt内容。角色描述是否清晰、具体？尝试修改它，使其更强调你想要的语气（例如，更严肃、更幽默、更简洁）。
- 切换LLM模型：如果你使用本地Ollama，尝试换一个更大的或专门在指令遵循上表现更好的模型，例如qwen2.5:14b。小模型虽然快，但创造力和对指令的遵循能力可能有限。
- 启用错误日志：运行voxlert log error on，然后触发几次通知。查看~/.voxlert/fallback.log，里面会记录LLM调用失败或返回异常时使用的备用短语。这能帮你判断是否是LLM服务本身出了问题。

问题4：在Windows上，安装后voxlert命令无法识别。

排查思路：这是典型的PATH环境变量问题。
- npm全局安装的包，其可执行文件通常位于%APPDATA%\npm目录。请确保此目录已添加到系统的PATH环境变量中。
- 添加后，需要关闭并重新打开终端（或重启电脑）才能使新的PATH生效。
- 也可以尝试使用npx voxlert ...来临时运行命令。

问题5：想彻底卸载Voxlert。

标准流程：
1. 运行voxlert uninstall。这会移除所有AI助手中的钩子配置。
2. 运行npm uninstall -g @settinghead/voxlert卸载CLI工具。
3. （可选）手动删除配置和缓存目录~/.voxlert（Windows为%USERPROFILE%\.voxlert）。
4. 停止并移除你手动启动的TTS服务（如Qwen3-TTS）和LLM服务（如Ollama）。

4.4 成本监控与优化

如果你使用云LLM服务（如OpenRouter），成本是需要关注的。

查看使用量：运行voxlert cost可以估算当前会话的token消耗和对应费用。这个数据是基于本地计数，并非实时账单。
重置计数器：voxlert cost reset。
降低成本的核心策略：
1. 使用更便宜的模型：在voxlert config set llm_model中指定OpenRouter上更经济的小模型。
2. 减少不必要的通知：如前所述，关闭task.acknowledge等非关键事件类别。
3. 拥抱本地LLM：这是终极解决方案。一台16GB内存的普通电脑就能流畅运行7B级别的模型，完全零成本，且隐私性最佳。