Files
xtype/docs/voicetype/README.md
T
adminandClaude Opus 5.5 b380eaf252 voicetype: Apple 端侧 + LLM 异步精修,可选 xunfei/dual
新增 apple-llm 引擎(默认):Apple SFSpeechRecognizer → 贴原文 → LLM (~1s,
thinking=disabled) → 退格覆盖精修版。LLM 走 ~/ssw.ini [llm-api],无配置
静默回退 Apple 原文。

- 删 localClean(中文无空格,正则误伤'好啊'等正常词)
- pickEngine() 默认 apple-llm
- LLMCleaner 自动带 thinking: {type: 'disabled'} (GLM 7s+ → ~1s)
- build.sh 新增 apple / apple-llm 模式,默认 apple-llm
- README + AGENTS.md 同步更新

Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
2026-10-02 19:23:47 +08:00

5.3 KiB

VoiceType — 长按左键语音输入(原型文档)

灵感来自微信 Mac 版的"按住说话":在任意 app 的输入框长按鼠标左键说话,松开文字自动出现在光标处。本工具把它做成全局的,且微信窗口内自动放行。

使用

  1. src/build.sh 构建安装(首次需手动开「系统设置 → 隐私与安全性 → 辅助功能 → VoiceType」,麦克风/语音识别弹窗点允许)
  2. 点击输入框定位光标 → 按住左键 ≥0.35s(哔一声开始)→ 说话 → 松开 → 出字
  3. 位移超过 10px 视为拖选,不触发;微信窗口内长按交给微信自己的语音输入

日志:/tmp/voicetype.log(每次判定都记录走了哪条路径、看到什么角色、识别文本、粘贴结果)。

引擎选择

~/.voicetype-engine 文件内容决定用哪个 ASR 引擎(空文件 = apple-llm):

值 引擎 备注
apple-llm (默认) Apple 端侧 + LLM 异步精修 无凭据;LLM 走 ~/ssw.ini;无 INI 则回退 Apple 原文
apple SFSpeechRecognizer 端侧 zh-CN 离线,无凭据,响应快,无 LLM 清洗
xunfei 讯飞 IAT v2 WebSocket 流式 需凭据;首次须 xop set 三个 vault 条目,启动走 src/build.sh xunfei
dual apple + xunfei 并行 + LLM 精修 苹果先贴,讯飞覆盖,LLM 再精修

apple-llm / dual 的 LLM 配置(~/ssw.ini)

LLM 走 OpenAI Chat Completions 兼容协议(任何 zhipu/openai/anthropic-compatible 代理都行)。

[llm-api]
key=sk_xxxxxxxxxxxx
base-url=https://your-llm-proxy/v1
model=GLM-5.3-Flash

容忍全角破折号 — 与半角 - 等价([llm—api] / base—url 都能识别)。

引擎会自动在请求里带 thinking: {type: "disabled",绕开 GLM 系列推理模式(7s+ → 1s,实测 thinking=disabled 后稳定 ~0.9s)。

失败兜底: 无 INI / key 错 / 网络断 / 超时 → 保留 Apple 原文,绝不静默丢内容。

一次性:把讯飞凭据放进 xop vault(仅 xunfei/dual 需要)

凭据只从 TTY 读取,不会出现在源码/git/日志/argv/历史里。xop set <name> 然后回车输入值。

xop set xf_vt_APPID        # APPID
xop set xf_vt_APISecret    # APISecret
xop set xf_vt_APIKey       # APIKey

启动对应引擎

src/build.sh                # 默认 = apple-llm
src/build.sh apple          # 纯端侧(无 LLM 精修)
src/build.sh apple-llm      # 端侧 + LLM(默认)
src/build.sh xunfei         # 讯飞(需 xop 注入)
src/build.sh dual           # 双引擎(需 xop 注入)

这一步做三件事:

  1. 把 ~/.voicetype-engine 写成对应模式(持久切换)
  2. xunfei / dual 模式会 xop run --secret XUNFEI_APPID=xf_vt_APPID --secret ... -- open /Applications/VoiceType.app —— 凭据仅在子进程 env 里存在
  3. 引擎读 ProcessInfo.processInfo.environment["XUNFEI_*"],任一缺失则报错并丢弃本次录音(不静默回退 apple,避免你以为用了讯飞但实际是 apple 给你识别差)。

判定流程(按住 350ms 时触发一次)

光标下窗口归属(CGWindowList z序)
├─ 微信(com.tencent.xinWeChat*) → 放行,静默
└─ 其他 app:
   ① AX 聚焦元素角色 ∈ {AXTextField, AXTextArea, AXComboBox, AXSearchField} → 激活
   ② 查不到 → 设置 AXManualAccessibility + AXEnhancedUserInterface,250ms 后重查 → 同①
   ③ 仍查不到(AX 完全不透明,如 HexHub) → app 级兜底放行

架构(单文件)

组件 职责 权限
轮询线程(~125Hz) CGEventSource.buttonState 检测左键,状态机 idle→press→recording/dead 无
预卷录音 鼠标按下瞬间就开始收音(AVAudioEngine tap),激活时才挂识别任务——短句不丢头 麦克风
AppleEngine SFSpeechRecognizer(zh-CN) 流式,requiresOnDeviceRecognition = true,松开 ~70ms 出结果 语音识别
AppleLLMEngine 包 AppleEngine + LLMCleaner;Apple 出文立刻贴,LLM 异步 ~1s 后回来若非空且不同则退格再贴 语音识别 + LLM
XunfeiEngine URLSessionWebSocketTask → wss://iat-api.xfyun.cn/v2/iat,HMAC-SHA256 鉴权 URL,系统原生 PCM → 16k/16bit/mono 后 1280 字节/帧推送,逐条收 data_status 拼结果 麦克风(无语音识别权限要求)
DualEngine apple + xunfei 并行,apple 先贴 → xunfei 覆盖 → LLM 异步精修再覆盖(可关) 语音识别 + 麦克风 + LLM
LLMCleaner OpenAI Chat Completions 兼容;强制带 thinking: disabled;refine() 异步回调,clean() 同步 1.5s 兜底 —
pickEngine() 读 ~/.voicetype-engine,默认 apple-llm —
注入 写剪贴板 → 合成 ⌘V → 1.5s 后恢复原剪贴板 辅助功能
拖选抑制 tap 录音期间吞掉 leftMouseDragged,防拖选文字 辅助功能
聚焦查询 AX 系统级/per-app kAXFocusedUIElementAttribute + 角色 辅助功能

已知边界(探针范围外)

  • AX 完全不透明的 app 里是 app 级兜底:长按它任何位置都触发,不只输入框
  • 剪贴板恢复只管文本(图片/文件内容不还原)
  • 录音上限 60s;350ms 内慢速起步(<10px)的拖选理论可能误判
  • LSUIElement 无界面:无菜单栏开关、无开机自启、无常量配置面板(阈值都是源码顶部常量)
  • 讯飞 IAT v2 单次请求 60s 上限(服务端);长语音会被截断
  • 讯飞计费按调用次数+音频时长,开发期注意用量