前言¶
在 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
