1. 项目概述与核心价值如果你和我一样每天大部分时间都泡在 Cursor 编辑器里让 AI 智能体Agent帮你写代码、重构项目那你肯定遇到过这个场景你给 Agent 下达了一个复杂的任务比如“重构整个用户认证模块”然后你就切到浏览器去查资料或者去泡杯咖啡。过一会儿回来你盯着屏幕心里嘀咕“它到底干完了没有” 你得手动滚动代码检查终端输出或者看那个小小的生成图标是不是还在转。这种不确定的等待其实挺打断心流的。cursorfinishsound这个项目就是为了解决这个“最后一公里”的痛点而生的。它是一个轻量级的 Python 包核心功能就两个第一在 Cursor 的 AI Agent 完成任务后播放一个温和的提示音第二更酷的是它可以用文本转语音TTS直接“念”出当前项目文件夹的名字。想象一下你正在另一个窗口工作耳边突然传来一个清晰的机器人声音“backend-api”你就立刻知道那个负责后端 API 的 Agent 已经完工了无缝切换回去 review 代码。这不仅仅是增加了一个声音提醒更是将异步协作的反馈闭环做得更加优雅和自动化。这个工具特别适合重度依赖 Cursor AI 进行开发的工程师无论是独立开发者同时推进多个微服务还是团队中需要频繁与 Agent 交互的成员。它把原本需要视觉确认的“完成状态”变成了一个无需打断当前注意力的听觉信号极大地提升了多任务并行下的开发效率。接下来我会详细拆解它的实现原理、如何深度集成到你的工作流中以及我在实际使用中踩过的坑和优化技巧。2. 核心原理与技术栈拆解这个项目的技术栈非常精简但每一部分的选择都体现了“够用且优雅”的设计哲学。我们来深入看看它的核心构成。2.1 声音播放为何选择simpleaudio与wavio项目通过sound.py模块来处理提示音的播放。它依赖两个库simpleaudio和wavio。这里有个值得深究的点为什么不直接用 Python 标准库的winsoundWindows或os.system(‘aplay’…)Linux首先跨平台兼容性是首要考量。winsound仅限 Windows而直接调用系统命令如aplay,afplay虽然简单但命令参数和可用性在不同系统上差异很大封装和维护成本高。simpleaudio是一个底层基于 C 库如 PortAudio的 Python 封装它提供了统一的、高性能的音频播放接口在 Windows、macOS 和 Linux 上都能稳定工作真正做到了“写一次到处跑”。其次对音频数据的精细控制。wavio库的作用是读取 WAV 文件。你可能会问Python 不是有wave标准库吗没错但wavio的 API 对新手更友好它能直接将 WAV 文件数据读入 NumPy 数组。simpleaudio恰好可以直接播放 NumPy 数组格式的音频数据。这个组合使得从文件加载到播放的流程非常清晰import wavio import simpleaudio as sa # wavio 读取直接得到 numpy 数组和数据参数 wav_obj wavio.read(‘notification.wav’) audio_data wav_obj.data.astype(np.int16) # 确保数据类型 playback sa.play_buffer(audio_data, num_channelswav_obj.data.shape[1], bytes_per_sample2, sample_ratewav_obj.rate) playback.wait_done() # 阻塞等待播放完成这种基于数组的播放方式未来如果你想动态生成或修改音效比如根据任务耗时调整音调会非常方便。注意原项目requirements.txt中只列出了simpleaudio。在实际部署中特别是在纯净的系统上simpleaudio可能需要系统级的音频开发库。在 Ubuntu/Debian 上你可能需要先运行sudo apt-get install libasound2-dev才能顺利通过 pip 安装simpleaudio。这是第一个容易踩的坑。2.2 文本转语音espeak的轻量级哲学项目的第二个核心模块soundname.py负责“报幕”——念出文件夹名。它没有选择像pyttsx3或gTTS这类纯 Python 的 TTS 库而是通过subprocess调用了系统命令espeak。这个选择非常巧妙体现了 Unix 哲学“一个工具只做好一件事”。espeak是一个开源、离线的语音合成系统虽然声音是经典的“机器人音”不那么自然但它有不可替代的优势零网络依赖绝对隐私所有语音合成都在本地完成不会将你的项目名称可能包含敏感信息发送到任何云端服务。启动速度极快调用espeak进程几乎无延迟比初始化一个完整的 Python TTS 引擎要快得多。系统级集成资源消耗低espeak作为独立进程运行播放完毕后资源立即释放不会在 Python 运行时中残留任何对象。它的实现简洁到极致import subprocess import os parent_folder os.path.basename(os.getcwd()) # 获取当前目录名 subprocess.run([‘espeak’, ‘-a’, ‘50’, parent_folder], checkTrue)这里的-a 50参数表示音量amplitude范围是 0 到 200。你可以根据环境噪音大小调整。实操心得在 macOS 上espeak的声音引擎可能听起来特别“脆”甚至刺耳。我个人的优化方案是通过 Homebrew 安装espeak时连带安装mbrola语音库brew install espeak --with-mbrola并使用-v mb-en1参数指定一个稍好听的英语语音命令会变成[‘espeak’, ‘-v’, ‘mb-en1’, ‘-a’, ‘50’, parent_folder]。虽然还是机器音但听感会柔和不少。2.3 与 Cursor AI Agent 的集成机制这是整个项目最精髓的部分。它并没有修改 Cursor 本身而是巧妙地利用了 Cursor 的一个功能“Rules for AI”。你可以在 Cursor 设置的 “Rules for AI” 板块中添加一条自然语言指令要求 AI Agent 在完成任务前执行一段特定的 Python 代码。原项目的指令是Always play cursorfinishsound/soundname.py when you have finished the last job, before you stop generating.这条指令会被 Cursor 的底层模型理解并遵循。当 Agent 完成你要求的最后一项代码生成或修改后在它即将结束“思考”和“输出”状态之前它会自动执行你指定的 Python 脚本。这就相当于给 Agent 的“工作流”挂上了一个“后置钩子”post-hook。为什么这种集成方式很聪明非侵入式不需要 Cursor 提供官方插件 API利用现有功能即可实现。基于语义指令是自然语言模型能理解“finished the last job”这个上下文确保在真正结束时才触发。灵活可配置你可以轻松修改这条规则比如换成sound.py只播放提示音或者甚至指向你自己编写的、更复杂的日志脚本。3. 从安装到深度集成的完整实操指南知道了原理我们来一步步把它用起来。我会补充很多原 README 中省略的细节和最佳实践。3.1 环境准备与依赖安装假设你使用的是 Ubuntu 22.04 或类似的 Linux 发行版。Windows 和 macOS 的步骤在依赖安装上略有不同我会分别说明。第一步克隆项目不要随意克隆到任何地方。我建议在你的用户目录下创建一个专门的tools或scripts文件夹来管理这类开发小工具。mkdir -p ~/dev-tools cd ~/dev-tools git clone https://github.com/eliaspfeffer/cursorfinishsound.git cd cursorfinishsound这样管理的好处是所有项目都可以通过相对路径如~/dev-tools/cursorfinishsound/soundname.py来引用不会污染各个业务项目的代码库。第二步安装系统依赖对于Ubuntu/Debiansudo apt-get update sudo apt-get install espeak python3-pip libasound2-dev -y这里比原文档多了一个libasound2-dev这是simpleaudio在 Linux 上编译所必需的开发库能避免后续 pip 安装报错。对于macOS使用 Homebrewbrew install espeak # 音频库通常已内置无需额外安装对于Windows 访问 espeak 项目页面 下载安装包并安装确保espeak命令能被系统识别即其安装目录已添加到系统的 PATH 环境变量中。Windows 上的simpleaudio通常可以直接 pip 安装无需额外步骤。第三步创建并激活 Python 虚拟环境这是极其重要的一步原文档只是一笔带过。为这个工具单独创建虚拟环境可以避免污染你的全局 Python 环境也便于管理依赖。python3 -m venv venv source venv/bin/activate # Linux/macOS # 在 Windows 上使用venv\Scripts\activate第四步安装 Python 包依赖在激活的虚拟环境中安装pip install -r requirements.txt如果requirements.txt只包含simpleaudio而你需要用到wavio和numpysound.py需要那么你需要手动安装它们pip install simpleaudio wavio numpy我建议你创建一个更完整的requirements.txtsimpleaudio1.0.4 wavio0.0.4 numpy1.21.03.2 配置 Cursor Rules for AI这是集成的关键一步操作虽简单但有细节。打开 Cursor 编辑器。点击左下角的“设置”齿轮图标。在设置面板中找到“Rules for AI”选项。它可能位于 “Editor” 或 “AI” 分类下。在规则输入框中你需要添加的完整路径。如果你按照我的建议将工具克隆在~/dev-tools那么规则应该是Always play /home/你的用户名/dev-tools/cursorfinishsound/soundname.py when you have finished the last job, before you stop generating.注意你必须使用绝对路径。因为 Cursor Agent 在执行脚本时其当前工作目录os.getcwd()是你正在开发的那个项目目录而不是工具所在的目录。如果只用相对路径cursorfinishsound/soundname.pyAgent 会在你的项目目录里找不到这个文件导致规则静默失败。保存设置。如何验证规则是否生效你可以创建一个简单的测试。新建一个 Python 文件用 Cursor Agent 让它写一个简单的函数比如一个计算斐波那契数列的函数。在 Agent 生成完代码后仔细听。如果集成成功你应该能听到机器人念出你当前项目文件夹的名字。3.3 高级用法与自定义原项目提供了两个基础脚本但我们可以玩出更多花样。自定义提示音sound.py播放的是项目自带的notification.wav。如果你觉得这个声音不够有辨识度或者想为不同类型的任务设置不同的提示音完全可以自定义。准备一个简短的.wav格式音频文件建议时长 1-2 秒音量适中。你可以在 Freesound 这类网站寻找。替换cursorfinishsound目录下的notification.wav文件或者修改sound.py中的文件路径指向你自己的音频文件。确保音频格式是标准的 PCM WAV采样率适中如 44100 Hz以避免播放问题。创建复合提醒脚本也许你想要“先响铃后报名”。我们可以创建一个新的脚本比如compound_notify.py# compound_notify.py import sys sys.path.insert(0, ‘/绝对路径/to/dev-tools/cursorfinishsound’) try: from cursorfinishsound import sound, soundname sound.play_gentle_notification() soundname.say_folder_name() except Exception as e: # 静默失败避免干扰 Agent 主任务 pass然后在 Cursor Rules 里指向这个新脚本。sys.path.insert是为了确保 Python 能找到我们的工具包。根据任务类型动态提醒进阶思路你可以通过环境变量或一个简单的配置文件让脚本发出不同的声音。例如在启动 Cursor 前设置环境变量TASK_TYPE“urgent”然后在你的脚本中读取这个变量决定是播放急促的提示音还是舒缓的音乐。这需要更复杂的脚本逻辑但思路是相通的。4. 常见问题排查与实战经验在实际使用中你可能会遇到一些问题。下面是我和社区里其他开发者遇到的一些典型情况及其解决方案。4.1 问题一规则添加了但完全没有声音这是最常见的问题。请按照以下步骤排查检查路径确认 Cursor Rules 中填写的 Python 脚本路径是绝对路径并且路径完全正确没有拼写错误。在 Linux/macOS 上你可以打开终端输入ls -la 你填写的路径来验证文件是否存在。检查 Python 解释器Cursor Agent 使用哪个 Python 环境通常它会使用你系统默认的python命令所指向的环境。在终端输入which python和python --version查看。确保这个环境里安装了必要的包simpleaudio, wavio, numpy。最稳妥的方法是在 Rules 中使用虚拟环境下的 Python 绝对路径来执行脚本Always run /home/你的用户名/dev-tools/cursorfinishsound/venv/bin/python /home.../soundname.py when you have finished the last job...检查音频输出设备系统音量是否打开是否被静音对于 Linux 桌面用户有时会遇到 PulseAudio 权限或配置问题。可以尝试在终端直接运行python -c “from cursorfinishsound import sound; sound.play_gentle_notification()”看是否有错误输出。查看 Cursor 日志Cursor 有时会在后台输出 Agent 的执行日志。打开 Cursor 的“View” - “Output”面板选择“Cursor Agent”或类似的日志通道查看执行你的脚本时是否有报错信息。4.2 问题二espeak命令未找到Windows/macOS 特定Windows你需要将espeak的安装目录例如C:\Program Files (x86)\eSpeak\command_line添加到系统的 PATH 环境变量中然后重启 Cursor。macOS如果你通过 Homebrew 安装espeak通常位于/usr/local/bin这个路径应该在 PATH 里。如果不行在脚本中可以使用绝对路径subprocess.run([‘/usr/local/bin/espeak’, …])。4.3 问题三声音播放卡顿、爆音或与系统其他声音冲突这通常与simpleaudio的音频缓冲区或系统音频驱动有关。尝试降低音频质量用音频编辑软件如 Audacity将notification.wav的采样率从 44100 Hz 降低到 22050 Hz 或 16000 Hz并转换为单声道。更小的文件和数据流能减少播放问题。在脚本中增加微小延迟在sound.py的play_gentle_notification函数中在sa.play_buffer之后playback.wait_done()之前可以加入time.sleep(0.05)给音频系统一点初始化时间。检查系统音频驱动尤其是在 Linux 上尝试切换音频后端如从 PulseAudio 到 ALSA。但这属于比较深入的调试对于提示音这种简单需求方案1通常就能解决。4.4 问题四Agent 执行脚本后偶尔会“卡住”不结束这是一个非常罕见但需要注意的边缘情况。理论上playback.wait_done()和subprocess.run(…, checkTrue)都是阻塞调用完成后脚本就结束了。但如果音频系统出现异常这些调用可能会挂起。解决方案设置超时。我们可以修改脚本为其添加超时机制。对于soundname.py可以这样改import subprocess import os import sys parent_folder os.path.basename(os.getcwd()) try: # 设置5秒超时 subprocess.run([‘espeak’, ‘-a’, ‘50’, parent_folder], checkTrue, timeout5) except subprocess.TimeoutExpired: sys.exit(1) # 超时则静默退出 except Exception: sys.exit(1) # 其他异常也静默退出对于sound.pysimpleaudio没有内置超时但你可以将其放在一个线程中运行主线程等待一段时间后无论完成与否都退出。4.5 性能与资源考量你可能会担心这个工具会不会拖慢 Agent 的速度。完全不必。播放一个短 WAV 文件和调用一次espeak进程其开销对于现代计算机来说微乎其微通常小于 100 毫秒相比于 Agent 生成代码所需的数秒甚至数十秒这个开销可以忽略不计。它带来的上下文切换效率提升远远大于其本身的性能成本。5. 扩展思路打造你的智能开发环境cursorfinishsound是一个完美的起点它揭示了一种模式利用自然语言指令让 AI Agent 自动执行本地脚本从而扩展编辑器本身的功能。基于这个模式我们可以构想更多提升开发体验的“智能钩子”自动生成提交信息规则可以修改为“当你完成一个功能模块后运行脚本分析变动的文件并生成一条语义化的 Git commit message 建议。”运行微型测试规则“在修改任何以_test.py结尾的文件后自动运行该测试文件并将结果摘要用语音读出来。”代码复杂度提醒规则“当你生成或修改一个函数后如果其圈复杂度超过 10播放一个不同的警告音。”多项目状态面板结合一个常驻的轻量级 HTTP 服务各个项目的 Agent 完成工作后通过调用本地 API 端点在一个统一的网页仪表板上更新状态。这样你可以在一个屏幕上监控所有并行开发项目的 Agent 进度。实现这些想法的技术栈依然是简单的Python 脚本处理逻辑subprocess调用系统工具或执行命令最后通过 Cursor Rules 将其与 AI 工作流绑定。关键在于你将从一个被动的代码接收者转变为主动设计自动化流程的“开发环境架构师”。我个人使用cursorfinishsound已经几个月了它已经成了我肌肉记忆的一部分。最开始我只是想要一个提醒但现在它带来的是一种“后台任务完成”的确定性。这种确定性让我能更放心地把重构、代码生成等耗时任务交给 Agent自己则能更专注地进行高层的设计和思考。它很小但就像机械键盘的清脆按键声一样这种即时、清晰的反馈能实实在在地提升工作的愉悦感和效率。如果你也厌倦了不断回头确认 Agent 是否完工不妨花十分钟把它配置起来这个小小的投资回报会超乎你的想象。
Cursor AI Agent 任务完成语音提醒：提升开发效率的轻量级解决方案
发布时间：2026/7/8 10:29:06
1. 项目概述与核心价值如果你和我一样每天大部分时间都泡在 Cursor 编辑器里让 AI 智能体Agent帮你写代码、重构项目那你肯定遇到过这个场景你给 Agent 下达了一个复杂的任务比如“重构整个用户认证模块”然后你就切到浏览器去查资料或者去泡杯咖啡。过一会儿回来你盯着屏幕心里嘀咕“它到底干完了没有” 你得手动滚动代码检查终端输出或者看那个小小的生成图标是不是还在转。这种不确定的等待其实挺打断心流的。cursorfinishsound这个项目就是为了解决这个“最后一公里”的痛点而生的。它是一个轻量级的 Python 包核心功能就两个第一在 Cursor 的 AI Agent 完成任务后播放一个温和的提示音第二更酷的是它可以用文本转语音TTS直接“念”出当前项目文件夹的名字。想象一下你正在另一个窗口工作耳边突然传来一个清晰的机器人声音“backend-api”你就立刻知道那个负责后端 API 的 Agent 已经完工了无缝切换回去 review 代码。这不仅仅是增加了一个声音提醒更是将异步协作的反馈闭环做得更加优雅和自动化。这个工具特别适合重度依赖 Cursor AI 进行开发的工程师无论是独立开发者同时推进多个微服务还是团队中需要频繁与 Agent 交互的成员。它把原本需要视觉确认的“完成状态”变成了一个无需打断当前注意力的听觉信号极大地提升了多任务并行下的开发效率。接下来我会详细拆解它的实现原理、如何深度集成到你的工作流中以及我在实际使用中踩过的坑和优化技巧。2. 核心原理与技术栈拆解这个项目的技术栈非常精简但每一部分的选择都体现了“够用且优雅”的设计哲学。我们来深入看看它的核心构成。2.1 声音播放为何选择simpleaudio与wavio项目通过sound.py模块来处理提示音的播放。它依赖两个库simpleaudio和wavio。这里有个值得深究的点为什么不直接用 Python 标准库的winsoundWindows或os.system(‘aplay’…)Linux首先跨平台兼容性是首要考量。winsound仅限 Windows而直接调用系统命令如aplay,afplay虽然简单但命令参数和可用性在不同系统上差异很大封装和维护成本高。simpleaudio是一个底层基于 C 库如 PortAudio的 Python 封装它提供了统一的、高性能的音频播放接口在 Windows、macOS 和 Linux 上都能稳定工作真正做到了“写一次到处跑”。其次对音频数据的精细控制。wavio库的作用是读取 WAV 文件。你可能会问Python 不是有wave标准库吗没错但wavio的 API 对新手更友好它能直接将 WAV 文件数据读入 NumPy 数组。simpleaudio恰好可以直接播放 NumPy 数组格式的音频数据。这个组合使得从文件加载到播放的流程非常清晰import wavio import simpleaudio as sa # wavio 读取直接得到 numpy 数组和数据参数 wav_obj wavio.read(‘notification.wav’) audio_data wav_obj.data.astype(np.int16) # 确保数据类型 playback sa.play_buffer(audio_data, num_channelswav_obj.data.shape[1], bytes_per_sample2, sample_ratewav_obj.rate) playback.wait_done() # 阻塞等待播放完成这种基于数组的播放方式未来如果你想动态生成或修改音效比如根据任务耗时调整音调会非常方便。注意原项目requirements.txt中只列出了simpleaudio。在实际部署中特别是在纯净的系统上simpleaudio可能需要系统级的音频开发库。在 Ubuntu/Debian 上你可能需要先运行sudo apt-get install libasound2-dev才能顺利通过 pip 安装simpleaudio。这是第一个容易踩的坑。2.2 文本转语音espeak的轻量级哲学项目的第二个核心模块soundname.py负责“报幕”——念出文件夹名。它没有选择像pyttsx3或gTTS这类纯 Python 的 TTS 库而是通过subprocess调用了系统命令espeak。这个选择非常巧妙体现了 Unix 哲学“一个工具只做好一件事”。espeak是一个开源、离线的语音合成系统虽然声音是经典的“机器人音”不那么自然但它有不可替代的优势零网络依赖绝对隐私所有语音合成都在本地完成不会将你的项目名称可能包含敏感信息发送到任何云端服务。启动速度极快调用espeak进程几乎无延迟比初始化一个完整的 Python TTS 引擎要快得多。系统级集成资源消耗低espeak作为独立进程运行播放完毕后资源立即释放不会在 Python 运行时中残留任何对象。它的实现简洁到极致import subprocess import os parent_folder os.path.basename(os.getcwd()) # 获取当前目录名 subprocess.run([‘espeak’, ‘-a’, ‘50’, parent_folder], checkTrue)这里的-a 50参数表示音量amplitude范围是 0 到 200。你可以根据环境噪音大小调整。实操心得在 macOS 上espeak的声音引擎可能听起来特别“脆”甚至刺耳。我个人的优化方案是通过 Homebrew 安装espeak时连带安装mbrola语音库brew install espeak --with-mbrola并使用-v mb-en1参数指定一个稍好听的英语语音命令会变成[‘espeak’, ‘-v’, ‘mb-en1’, ‘-a’, ‘50’, parent_folder]。虽然还是机器音但听感会柔和不少。2.3 与 Cursor AI Agent 的集成机制这是整个项目最精髓的部分。它并没有修改 Cursor 本身而是巧妙地利用了 Cursor 的一个功能“Rules for AI”。你可以在 Cursor 设置的 “Rules for AI” 板块中添加一条自然语言指令要求 AI Agent 在完成任务前执行一段特定的 Python 代码。原项目的指令是Always play cursorfinishsound/soundname.py when you have finished the last job, before you stop generating.这条指令会被 Cursor 的底层模型理解并遵循。当 Agent 完成你要求的最后一项代码生成或修改后在它即将结束“思考”和“输出”状态之前它会自动执行你指定的 Python 脚本。这就相当于给 Agent 的“工作流”挂上了一个“后置钩子”post-hook。为什么这种集成方式很聪明非侵入式不需要 Cursor 提供官方插件 API利用现有功能即可实现。基于语义指令是自然语言模型能理解“finished the last job”这个上下文确保在真正结束时才触发。灵活可配置你可以轻松修改这条规则比如换成sound.py只播放提示音或者甚至指向你自己编写的、更复杂的日志脚本。3. 从安装到深度集成的完整实操指南知道了原理我们来一步步把它用起来。我会补充很多原 README 中省略的细节和最佳实践。3.1 环境准备与依赖安装假设你使用的是 Ubuntu 22.04 或类似的 Linux 发行版。Windows 和 macOS 的步骤在依赖安装上略有不同我会分别说明。第一步克隆项目不要随意克隆到任何地方。我建议在你的用户目录下创建一个专门的tools或scripts文件夹来管理这类开发小工具。mkdir -p ~/dev-tools cd ~/dev-tools git clone https://github.com/eliaspfeffer/cursorfinishsound.git cd cursorfinishsound这样管理的好处是所有项目都可以通过相对路径如~/dev-tools/cursorfinishsound/soundname.py来引用不会污染各个业务项目的代码库。第二步安装系统依赖对于Ubuntu/Debiansudo apt-get update sudo apt-get install espeak python3-pip libasound2-dev -y这里比原文档多了一个libasound2-dev这是simpleaudio在 Linux 上编译所必需的开发库能避免后续 pip 安装报错。对于macOS使用 Homebrewbrew install espeak # 音频库通常已内置无需额外安装对于Windows 访问 espeak 项目页面 下载安装包并安装确保espeak命令能被系统识别即其安装目录已添加到系统的 PATH 环境变量中。Windows 上的simpleaudio通常可以直接 pip 安装无需额外步骤。第三步创建并激活 Python 虚拟环境这是极其重要的一步原文档只是一笔带过。为这个工具单独创建虚拟环境可以避免污染你的全局 Python 环境也便于管理依赖。python3 -m venv venv source venv/bin/activate # Linux/macOS # 在 Windows 上使用venv\Scripts\activate第四步安装 Python 包依赖在激活的虚拟环境中安装pip install -r requirements.txt如果requirements.txt只包含simpleaudio而你需要用到wavio和numpysound.py需要那么你需要手动安装它们pip install simpleaudio wavio numpy我建议你创建一个更完整的requirements.txtsimpleaudio1.0.4 wavio0.0.4 numpy1.21.03.2 配置 Cursor Rules for AI这是集成的关键一步操作虽简单但有细节。打开 Cursor 编辑器。点击左下角的“设置”齿轮图标。在设置面板中找到“Rules for AI”选项。它可能位于 “Editor” 或 “AI” 分类下。在规则输入框中你需要添加的完整路径。如果你按照我的建议将工具克隆在~/dev-tools那么规则应该是Always play /home/你的用户名/dev-tools/cursorfinishsound/soundname.py when you have finished the last job, before you stop generating.注意你必须使用绝对路径。因为 Cursor Agent 在执行脚本时其当前工作目录os.getcwd()是你正在开发的那个项目目录而不是工具所在的目录。如果只用相对路径cursorfinishsound/soundname.pyAgent 会在你的项目目录里找不到这个文件导致规则静默失败。保存设置。如何验证规则是否生效你可以创建一个简单的测试。新建一个 Python 文件用 Cursor Agent 让它写一个简单的函数比如一个计算斐波那契数列的函数。在 Agent 生成完代码后仔细听。如果集成成功你应该能听到机器人念出你当前项目文件夹的名字。3.3 高级用法与自定义原项目提供了两个基础脚本但我们可以玩出更多花样。自定义提示音sound.py播放的是项目自带的notification.wav。如果你觉得这个声音不够有辨识度或者想为不同类型的任务设置不同的提示音完全可以自定义。准备一个简短的.wav格式音频文件建议时长 1-2 秒音量适中。你可以在 Freesound 这类网站寻找。替换cursorfinishsound目录下的notification.wav文件或者修改sound.py中的文件路径指向你自己的音频文件。确保音频格式是标准的 PCM WAV采样率适中如 44100 Hz以避免播放问题。创建复合提醒脚本也许你想要“先响铃后报名”。我们可以创建一个新的脚本比如compound_notify.py# compound_notify.py import sys sys.path.insert(0, ‘/绝对路径/to/dev-tools/cursorfinishsound’) try: from cursorfinishsound import sound, soundname sound.play_gentle_notification() soundname.say_folder_name() except Exception as e: # 静默失败避免干扰 Agent 主任务 pass然后在 Cursor Rules 里指向这个新脚本。sys.path.insert是为了确保 Python 能找到我们的工具包。根据任务类型动态提醒进阶思路你可以通过环境变量或一个简单的配置文件让脚本发出不同的声音。例如在启动 Cursor 前设置环境变量TASK_TYPE“urgent”然后在你的脚本中读取这个变量决定是播放急促的提示音还是舒缓的音乐。这需要更复杂的脚本逻辑但思路是相通的。4. 常见问题排查与实战经验在实际使用中你可能会遇到一些问题。下面是我和社区里其他开发者遇到的一些典型情况及其解决方案。4.1 问题一规则添加了但完全没有声音这是最常见的问题。请按照以下步骤排查检查路径确认 Cursor Rules 中填写的 Python 脚本路径是绝对路径并且路径完全正确没有拼写错误。在 Linux/macOS 上你可以打开终端输入ls -la 你填写的路径来验证文件是否存在。检查 Python 解释器Cursor Agent 使用哪个 Python 环境通常它会使用你系统默认的python命令所指向的环境。在终端输入which python和python --version查看。确保这个环境里安装了必要的包simpleaudio, wavio, numpy。最稳妥的方法是在 Rules 中使用虚拟环境下的 Python 绝对路径来执行脚本Always run /home/你的用户名/dev-tools/cursorfinishsound/venv/bin/python /home.../soundname.py when you have finished the last job...检查音频输出设备系统音量是否打开是否被静音对于 Linux 桌面用户有时会遇到 PulseAudio 权限或配置问题。可以尝试在终端直接运行python -c “from cursorfinishsound import sound; sound.play_gentle_notification()”看是否有错误输出。查看 Cursor 日志Cursor 有时会在后台输出 Agent 的执行日志。打开 Cursor 的“View” - “Output”面板选择“Cursor Agent”或类似的日志通道查看执行你的脚本时是否有报错信息。4.2 问题二espeak命令未找到Windows/macOS 特定Windows你需要将espeak的安装目录例如C:\Program Files (x86)\eSpeak\command_line添加到系统的 PATH 环境变量中然后重启 Cursor。macOS如果你通过 Homebrew 安装espeak通常位于/usr/local/bin这个路径应该在 PATH 里。如果不行在脚本中可以使用绝对路径subprocess.run([‘/usr/local/bin/espeak’, …])。4.3 问题三声音播放卡顿、爆音或与系统其他声音冲突这通常与simpleaudio的音频缓冲区或系统音频驱动有关。尝试降低音频质量用音频编辑软件如 Audacity将notification.wav的采样率从 44100 Hz 降低到 22050 Hz 或 16000 Hz并转换为单声道。更小的文件和数据流能减少播放问题。在脚本中增加微小延迟在sound.py的play_gentle_notification函数中在sa.play_buffer之后playback.wait_done()之前可以加入time.sleep(0.05)给音频系统一点初始化时间。检查系统音频驱动尤其是在 Linux 上尝试切换音频后端如从 PulseAudio 到 ALSA。但这属于比较深入的调试对于提示音这种简单需求方案1通常就能解决。4.4 问题四Agent 执行脚本后偶尔会“卡住”不结束这是一个非常罕见但需要注意的边缘情况。理论上playback.wait_done()和subprocess.run(…, checkTrue)都是阻塞调用完成后脚本就结束了。但如果音频系统出现异常这些调用可能会挂起。解决方案设置超时。我们可以修改脚本为其添加超时机制。对于soundname.py可以这样改import subprocess import os import sys parent_folder os.path.basename(os.getcwd()) try: # 设置5秒超时 subprocess.run([‘espeak’, ‘-a’, ‘50’, parent_folder], checkTrue, timeout5) except subprocess.TimeoutExpired: sys.exit(1) # 超时则静默退出 except Exception: sys.exit(1) # 其他异常也静默退出对于sound.pysimpleaudio没有内置超时但你可以将其放在一个线程中运行主线程等待一段时间后无论完成与否都退出。4.5 性能与资源考量你可能会担心这个工具会不会拖慢 Agent 的速度。完全不必。播放一个短 WAV 文件和调用一次espeak进程其开销对于现代计算机来说微乎其微通常小于 100 毫秒相比于 Agent 生成代码所需的数秒甚至数十秒这个开销可以忽略不计。它带来的上下文切换效率提升远远大于其本身的性能成本。5. 扩展思路打造你的智能开发环境cursorfinishsound是一个完美的起点它揭示了一种模式利用自然语言指令让 AI Agent 自动执行本地脚本从而扩展编辑器本身的功能。基于这个模式我们可以构想更多提升开发体验的“智能钩子”自动生成提交信息规则可以修改为“当你完成一个功能模块后运行脚本分析变动的文件并生成一条语义化的 Git commit message 建议。”运行微型测试规则“在修改任何以_test.py结尾的文件后自动运行该测试文件并将结果摘要用语音读出来。”代码复杂度提醒规则“当你生成或修改一个函数后如果其圈复杂度超过 10播放一个不同的警告音。”多项目状态面板结合一个常驻的轻量级 HTTP 服务各个项目的 Agent 完成工作后通过调用本地 API 端点在一个统一的网页仪表板上更新状态。这样你可以在一个屏幕上监控所有并行开发项目的 Agent 进度。实现这些想法的技术栈依然是简单的Python 脚本处理逻辑subprocess调用系统工具或执行命令最后通过 Cursor Rules 将其与 AI 工作流绑定。关键在于你将从一个被动的代码接收者转变为主动设计自动化流程的“开发环境架构师”。我个人使用cursorfinishsound已经几个月了它已经成了我肌肉记忆的一部分。最开始我只是想要一个提醒但现在它带来的是一种“后台任务完成”的确定性。这种确定性让我能更放心地把重构、代码生成等耗时任务交给 Agent自己则能更专注地进行高层的设计和思考。它很小但就像机械键盘的清脆按键声一样这种即时、清晰的反馈能实实在在地提升工作的愉悦感和效率。如果你也厌倦了不断回头确认 Agent 是否完工不妨花十分钟把它配置起来这个小小的投资回报会超乎你的想象。
