前言¶
在 Cursor、Claude Code 等 AI 编程助手里，需求往往很长：函数名、路径、约束条件混在一起，键盘输入成本高。常见做法是外接云端语音识别或单独开录音工具再复制粘贴，前者有隐私与网络依赖，后者步骤多、容易打断编码节奏。VoiceTranser 面向 macOS，用「按住说话、松手出字并粘贴到光标处」的方式，把本地 STT 和系统粘贴串成一条链路；同时，该仓库声明为 DeepSeek Harness（DSH）插件，安装后 agent 可借助 voicetranser 技能协助完成环境、launchd 与热键配置。
下面介绍插件定位、核心能力、在 DSH 中的启用方式，以及守护进程与热键的典型用法。
这是什么¶
VoiceTranser 由维护者 Lumos-789 发布，在 SkillHub 目录中归类为客户端插件，当前 package 版本为 1.0.1，许可证 MIT，GitHub 仓库为 Lumos-789/VoiceTranser。
一句话定位：全局热键触发录音 → 本地语音转写 → 自动粘贴到当前应用，专为 AI 编程助手场景设计，转写过程不依赖外部 API。仓库内 dsh.bundle 通过 cordis.patch.yml 挂载 agent 技能，用于安装、launchd、Karabiner 热键与排障，而非替代本机 Python 守护进程本身。
核心功能¶
本地 STT 与三引擎切换¶
默认使用 Qwen3-ASR 0.6B 4bit（MLX/Metal，Apple Silicon 上为主力）；Intel 或需要 CPU 路径时可切 SenseVoice Small int8；英文或小语种可切 mlx-whisper large-v3。模型均在本地推理。
通过环境变量临时切换引擎：
STT_ENGINE=sensevoice uv run python -m voicetranser
STT_ENGINE=mlx-whisper uv run python -m voicetranser
HTTP 守护与热键¶
守护模式启动后提供 HTTP 接口，供 Karabiner-Elements、Raycast 或 Hammerspoon 在按住/松开时请求 /start 与 /stop（亦支持 /toggle、/status）。推荐做法：例如 right_option 按下请求 localhost:9877/start，松开请求 /stop。
默认监听地址为 http://127.0.0.1:9876；通过 install_launchd.py 安装的 launchd 实例常用端口 9877。
输出与纠错¶
转写结果写入剪贴板并触发 macOS 粘贴；整词误识可在 corrections.json 中维护，改后重启生效。各阶段可通过系统通知反馈进度。
自愈与自检¶
支持 launchd KeepAlive、CoreAudio 看门狗，以及 tests/diagnose.py 八项链路自检：
uv run python tests/diagnose.py
在 DSH 中安装与启用¶
DSH 生态采用「一切皆插件」的思路；SkillHub（skillhub.cn）是社区目录站点，与 DeepSeek / 幻方无官方从属关系。VoiceTranser 目录页：Lumos-789/VoiceTranser。
启用步骤建议如下：
- 在 SkillHub 该插件页使用「发送给 DeepSeek Harness 安装」中的说明，让 DSH 安装 Lumos-789/VoiceTranser 插件（安装前请自行审阅仓库源码与 MIT 许可证；插件以当前 DSH 进程权限运行）。
- 安装完成后，agent 侧会获得 voicetranser 相关技能，可代你完成本机 Python 环境（需 Python 3.11+ 与 uv）、模型下载、launchd 与 Karabiner 配置及排障。
- 本机仍需满足 macOS 要求：MLX 主力引擎面向 Apple Silicon；Intel 可走 SenseVoice CPU 引擎。首次自动粘贴需在 系统设置 → 隐私与安全性 → 辅助功能 中为终端授权。
底层工具依赖与 README 一致：SenseVoice fallback 可通过 uv run python download_model.py 拉取（约 228MB）；Qwen3-ASR 主力模型首次运行会从 hf-mirror 自动拉取。PyPI 较慢时可使用镜像：
UV_DEFAULT_INDEX=https://pypi.tuna.tsinghua.edu.cn/simple uv sync
典型用法¶
守护模式¶
uv run python -m voicetranser
仅转写文件、不粘贴（对比引擎）¶
uv run python -m voicetranser --file recording.wav --no-paste
常驻后台（launchd）¶
uv run python install_launchd.py
curl -s localhost:9877/status
install_launchd.py 会按当前 checkout 的绝对路径生成 ~/Library/LaunchAgents/com.voicetranser-sense.plist 并加载；需要改端口或引擎时使用 --port / --engine，仅生成 plist 不加载时用 --no-load。服务启动时会后台预热模型。
HTTP 端点一览¶
| 端点 | 说明 |
|---|---|
GET /toggle |
切换录音（idle → recording → processing） |
GET /start |
开始录音 |
GET /stop |
停止录音并处理 |
GET /status |
当前状态 |
适用场景与注意¶
适合谁： 在 macOS 上长期使用 AI 编程助手、希望口述长 prompt 且要求数据留在本机的开发者。
环境与性能： README 给出 Apple Silicon 上约 16.5 秒中文样本的实测：Qwen3-ASR MLX 默认 RTF 约 0.015；SenseVoice CPU 约 0.033；mlx-whisper 英文/小语种 fallback RTF 约 0.07。Intel 机型应预期以 CPU 引擎为主。
安全与审查： 安装 DSH 插件前请阅读 GitHub 源码与依赖（sounddevice、mlx-audio、sherpa-onnx 等）。插件技能会指导在本机执行命令与写 launchd 配置，权限范围与当前 DSH 会话一致。
平台限制： 深度集成（菜单粘贴、launchd、Karabiner 示例）面向 macOS；非 macOS 环境不适用。
结尾¶
VoiceTranser 把本地 STT、误识词表和自动粘贴合成一条 push-to-talk 链路；作为 DSH 客户端插件，它把同一套能力封装成 agent 可执行的安装与排障技能，降低 launchd 与热键接入成本。
- 目录页：https://www.skillhub.cn/plugins/Lumos-789/VoiceTranser
- 源码与文档：https://github.com/Lumos-789/VoiceTranser
