Files
xtype/AGENTS.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

4.2 KiB

voicetype / VoiceType

macOS 工具:长按鼠标左键 → 说话 → 松开自动粘贴到光标处(任意 app 输入框;微信窗口内自动放行给微信自己的语音输入)。

布局

src/voicetype.swift   全部源码(单文件探针,~330 行)
src/Info.plist        app 包描述(权限声明)
src/build.sh          构建+签名+安装+重启一条龙
docs/voicetype/       详细文档(用法/架构/踩坑)

常用命令

src/build.sh                # 编译 → 签名 → 装到 /Applications → apple-llm 启动 → 打日志(默认)
src/build.sh apple          # 纯端侧(无 LLM 精修)
src/build.sh apple-llm      # 端侧 + LLM 异步精修
src/build.sh xunfei         # 同上,但经 xop 注入讯飞凭据 → 讯飞 IAT v2 WebSocket 引擎
src/build.sh dual           # apple + xunfei 并行 + LLM 精修(需 xop 注入)
tail -f /tmp/voicetype.log  # 看判定/识别/粘贴日志
killall VoiceType           # 停止

引擎切换(两个互不重叠的层面)

  1. 持久切换:echo apple|apple-llm|xunfei|dual > ~/.voicetype-engine,任意方式启动都生效。
  2. 启动方式注入:src/build.sh xunfei 用 xop run --secret ... -- open ... 临时把讯飞凭据塞进进程环境变量,只对当次启动有效,不会写到磁盘/源码。

讯飞凭据一次性入库(从 TTY 读值,源码/git/日志都不出现):

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

LLM 配置(apple-llm / dual 需要;无 INI 则静默回退 apple 原文):

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

容忍全角破折号 — 与半角 - 等价。引擎请求时强制带 thinking: {type: "disabled",绕过 GLM 推理模式(7s → 1s)。

红线(违反必翻车)

  1. 签名必须用固定 Apple Development 证书(src/build.sh 里的 IDENT)。ad-hoc -s - 每次重编译身份都变,TCC 当成新 app,三项授权全作废。
  2. 必须以 .app 形式装在 /Applications 并 LaunchServices 注册。裸 CLI 的 TCC 归属是宿主终端,行为混乱;/tmp 下的 app 进不了辅助功能列表。
  3. 权限三件套缺一不可:麦克风(录音)、语音识别(apple 引擎)/ 辅助功能(全模式)。日志 trusted: true + mic granted: true + speech auth: 3 全绿才算就绪。
  4. 长按状态机:一次按下只判定一次(激活/跳过后进 .dead,松开才复位)。打回 idle 会在按住期间循环重启录音引擎(已踩过)。
  5. 讯飞凭据永不落盘:源码/git/日志/argv/历史都不能出现 APPID/APISecret/APIKey 明文。运行时统一经 xop run --secret KEY=xf_vt_* -- open ... 注入到 ProcessInfo.processInfo.environment["XUNFEI_*"]。引擎拿到空 env 时直接报错退出,不静默回退 apple(避免"以为用了讯飞结果识别差"的误判)。
  6. LLM 凭据明文存于 ~/ssw.ini(用户偏好,不进 xop);key 字段不进源码/git/日志。LLM 失败/超时/未配 → 保留 Apple 原文,不静默丢弃。

核心设计(为什么这么做)

  • 鼠标左键轮询零权限可用(CGEventSource.buttonState),Fn/Globe 键则轮询不可见——所以触发方式选左键而不是 Fn(实验证据见 GOTCHAS §1)。
  • 判定用"光标下最顶层窗口归属"(CGWindowList z 序),不用 frontmostApplication——微信悬浮窗会霸占键盘焦点导致误判(踩坑见 GOTCHAS §5)。
  • 判定三层:AX 焦点角色严格判断 → AXManualAccessibility 强开 Chromium 系 AX 再查 → 完全不透明则 app 级兜底放行。
  • 注入 = 写剪贴板 + 合成 ⌘V,1.5s 后恢复原剪贴板(与微信同款)。
  • 识别引擎可插拔:protocol ASREngine + pickEngine() 读 ~/.voicetype-engine。默认 Apple 端侧 SFSpeechRecognizer(zh-CN,离线流式);备选 讯飞 IAT v2 流式 WebSocket(端点 wss://iat-api.xfyun.cn/v2/iat,HMAC-SHA256 鉴权,40ms 切片推送,服务端逐条返回拼接)。微信自家 ASR 是私有鉴权协议,外部不可用。

详细原理与全部踩坑:docs/voicetype/README.md、docs/voicetype/GOTCHAS.md。

详细原理与全部踩坑:docs/voicetype/README.md、docs/voicetype/GOTCHAS.md。