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]>
This commit is contained in:
adminandClaude Opus 5.5 committed 2026-10-02 19:23:47 +08:00
commit b380eaf252
7 files changed
+1252

No files matched your search

+70
View File
@@ -0,0 +1,70 @@
# GOTCHAS — VoiceType 踩坑全记录(2026-10-02 spike)
## 1. Fn(🌐) 键轮询不可见;鼠标左键零权限可见
写了 `CGEventSource.flagsState` 双视图(combinedSessionState + hidSystemState)轮询探针,用户两轮实按 **8ms 采样粒度下一个翻转都抓不到**——Apple Silicon 的 Globe 键在更底层被系统消费,只有 Fn+字母组合时修饰标志才出现。而 `CGEventSource.buttonState(.combinedSessionState, .left)` 一次就干净抓到左键 DOWN/UP,**不需要任何权限**。→ 这就是触发方式选左键不选 Fn 的实验依据;若将来要做 Fn 触发,必须走辅助功能 CGEventTap(flagsChanged/keycode 63)。
## 2. 微信的"长按 Fn/鼠标说话"是微信自己的全局劫持
- 不是 macOS 系统功能;4.1.7+ 加入,授权「控制你的 Mac」后在微信外生效,结果走**剪贴板渠道**注入,可在微信 设置→快捷键 关闭。
- 二进制证据(热更新副本 `~/Library/Containers/com.tencent.xinWeChat/Data/Documents/app_data/xplugin/plugins/Magicdy/<ver>/extracted/wechat.dylib` 的导入符号):`mmui::VoiceInputKeyboardListener / VoiceInputMouseListener / VoiceInputMouseSessionController / VoiceInputFocusListener` + `AXIsProcessTrusted` + `CGEventTapCreateForPid`(按前台 app 建 tap,所以不出现在 CGGetEventTapList 全局列表) + `CGEventSourceButtonState/FlagsState`(轮询兜底) + `NSPasteboard`/`CGEventPost`。ASR 走自家 CGI(`voicetrans`/`uploadvoice`),私有鉴权协议,外部不可用 → 本工具用 Apple 端侧识别。
- 包内 grep 中文字符串全空:微信 UI 串打包时不可直接 strings,要靠符号表和 `mmui::` 类名。
## 3. TCC 权限:裸 CLI 归属混乱,必须打包 .app + 固定签名
- 裸 CLI 从终端跑:麦克风 requestAccess 直接 false,授权对象是"责任进程"(宿主终端),行为不可预期。
- 打包最小 .app(Info.plist 带 NSMicrophoneUsageDescription/NSSpeechRecognitionUsageDescription)+ `open` 启动 → TCC 弹窗正常附着,授权立即可用。
- **ad-hoc 签名(-s -)每次重编译 cdhash 都变 → TCC 当成新 app,授权作废**。用钥匙串里已有的 Apple Development 证书签名,身份锚定证书,重编译授权保留。
- /tmp 下的 app 不进「辅助功能」列表(未注册 LaunchServices)→ 装到 /Applications + `lsregister -f`。
## 4. AX API 三连坑
- 新 SDK 把 `AXUIElementCopyAttributeValue` 导入成 **3 参数版**(没有 error 出参):`(AXUIElement, CFString, UnsafeMutablePointer<CFTypeRef?>) -> AXError`。写 4 参报"extra argument in call",用小文件穷举签名确认。
- 常量 `kAXFocusedUIElementAttribute` 是 String,要 `as CFString` 传。
- 查询失败码要打出来看:`-25204`(CannotComplete)/`-25212`(NoValue=app 没暴露聚焦元素)是完全不同的病因。
## 5. 判定"长按发生在哪个 app":用光标下窗口,别用 frontmostApplication
用户在备忘录长按,日志却显示 frontmost=微信——微信悬浮窗/语音面板会**霸占键盘焦点**,`NSWorkspace.frontmostApplication` 跟着错。改为 `CGWindowListCopyWindowInfo(optionOnScreenOnly)` 按 z 序找包含光标点的第一个 layer-0 窗口的 owner pid,所见即所得。
## 6. Chromium/Electron app 的 AX 树默认不建
`kAXFocusedUIElementAttribute` 返回 -25212。对 app 元素设置 `AXManualAccessibility` 和 `AXEnhancedUserInterface` = true,~250ms 后重查,多数 Chromium 系会建树。仍不行的(HexHub 实测)只能 app 级兜底放行。
## 7. 状态机 flap 循环
按下→判定失败→打回 `.idle`→下一轮询周期又当新按下→重启录音引擎……按住期间每 ~350ms 循环一次,表现为菜单栏录音图标狂闪、永远到不了激活。修法:**一次按下只判定一次**,判定完进 `.dead`,左键抬起才回 `.idle`。
## 8. 短句丢头 → 预卷录音
v1 在激活(350ms)后才启动录音引擎,用户按下即开口,前几百毫秒语音丢失 → ASR 报 `No speech detected (1110)`。修法:**鼠标按下瞬间**就启动引擎收缓冲,激活时才挂识别任务(`SFSpeechAudioBufferRecognitionRequest` 允许先 append 后建 task),普通点击抬起则丢弃。
## 9. 讯飞 IAT v2 鉴权在 URL query 里,不在 header
`URLSessionWebSocketTask` 用 `webSocketTask(with: URL)` 时**所有参数都得到 URL 上**,没有 header 钩子(Authorization 不能直接挂)。所以讯飞的鉴权模式:
1. RFC1123 GMT 时间串 `date`
2. 拼接 `host: iat-api.xfyun.cn\ndate: <date>\nGET /v2/iat HTTP/1.1` → HMAC-SHA256(secret) → base64 → `signature`
3. 拼 `api_key="...", algorithm="hmac-sha256", headers="host date request-line", signature="..."` → 再 base64 → `authorization`
4. URL = `wss://iat-api.xfyun.cn/v2/iat?authorization=<>&date=<>&host=iat-api.xfyun.cn`
注意 URL 里的日期**不能跨分钟**:同一连接生命周期里服务端会校验(签名原始串里的 date 与请求 URL 里的 date 一致)。长会话需要周期重连(本工具单次录音 ≤60s,无此问题)。
## 10. AVAudioConverter 系统原生 PCM → 16k Int16 mono
`AVAudioEngine.inputNode.outputFormat(forBus: 0)` 出来通常是 48k 或 44.1k Float32。讯飞要 16k/16bit/mono PCM,所以:
- `AVAudioConverter(from: inputFmt, to: targetFmt)` 直接搭好
- `convert(to:from:error:)` 一行转完(回调式只用于压缩输入的流式场景,我们用不上)
- 输出 `AVAudioPCMBuffer.int16ChannelData[0]` → `UnsafeRawBufferPointer(start:count:)` → `Data.append(contentsOf:)`
- 注意 `Int16` 指针不能直接喂 `Data.append(_:count:)`,必须先按字节重解释
## 11. xop 注入 env 经 `open` 传递到 .app
`xop run --secret X=xf_vt_X -- open /Applications/VoiceType.app` 时,env 经 `xop → open → LaunchServices → app` 这条链路一直传到底,`ProcessInfo.processInfo.environment["XUNFEI_X"]` 在 app 内能拿到。但有几种场景会丢:
- macOS 14+ 的 `open --new` 在某些沙盒场景下被 launchd 接管,env 被截断 → 备用 `xop run --secret ... -- /Applications/VoiceType.app/Contents/MacOS/VoiceType`(直接执行二进制,TCC 仍生效,因为同一 .app bundle)
- 用户从 Finder 双击 .app:不走 xop,env 没有,引擎立刻报错退出
## 复现/验证工具
- 事件 tap 全列表:`CGGetEventTapList`(源码曾存 /tmp/taplist.swift,随 /tmp 已失传,可按 GOTCHAS §2 结论重写)
- Fn/左键轮询探针:`CGEventSource.flagsState/.buttonState` + 8ms 循环
- 日志判据:每次判定一行 `activate/skip/allow`,带 app bundle id + AX 角色/错误码
+100
View File
@@ -0,0 +1,100 @@
# 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 代理都行)。
```ini
[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>` 然后回车输入值。
```bash
xop set xf_vt_APPID # APPID
xop set xf_vt_APISecret # APISecret
xop set xf_vt_APIKey # APIKey
```
### 启动对应引擎
```bash
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 上限(服务端);长语音会被截断
- 讯飞计费按调用次数+音频时长,开发期注意用量