- bundle: com.xs.voicetype → com.xs.xtype;CFBundleName/Executable → XType
- 文件: src/voicetype.swift → src/xtype.swift;docs/voicetype/ → docs/xtype/
- 路径: /Applications/VoiceType.app → /Applications/XType.app;/tmp/voicetype.{log,build}
- 配置: ~/.voicetype-engine → ~/.xtype-engine
- 凭据 vault: xf_vt_{APPID,APISecret,APIKey} → xf_xt_*
- 文档: AGENTS.md / README.md / GOTCHAS.md 全量替换
- git remote: x/voicetype → x/xtype
影响 TCC:bundle id 变了,用户首次装需重新授三件套(麦/语音/辅助)。
用户操作:已 killall VoiceType + 删旧 .app + 迁 vault + remote set-url。
Co-Authored-By: Claude Code <[email protected]>
68 lines
4.2 KiB
Markdown
68 lines
4.2 KiB
Markdown
# xtype / XType
|
|
|
|
macOS 工具:**长按鼠标左键 → 说话 → 松开自动粘贴到光标处**(任意 app 输入框;微信窗口内自动放行给微信自己的语音输入)。
|
|
|
|
## 布局
|
|
|
|
```
|
|
src/xtype.swift 全部源码(单文件探针,~330 行)
|
|
src/Info.plist app 包描述(权限声明)
|
|
src/build.sh 构建+签名+安装+重启一条龙
|
|
docs/xtype/ 详细文档(用法/架构/踩坑)
|
|
```
|
|
|
|
## 常用命令
|
|
|
|
```bash
|
|
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/xtype.log # 看判定/识别/粘贴日志
|
|
killall XType # 停止
|
|
```
|
|
|
|
## 引擎切换(两个互不重叠的层面)
|
|
|
|
1. **持久切换**:`echo apple|apple-llm|xunfei|dual > ~/.xtype-engine`,任意方式启动都生效。
|
|
2. **启动方式注入**:`src/build.sh xunfei` 用 `xop run --secret ... -- open ...` 临时把讯飞凭据塞进进程环境变量,**只对当次启动有效**,不会写到磁盘/源码。
|
|
|
|
讯飞凭据一次性入库(从 TTY 读值,源码/git/日志都不出现):
|
|
```bash
|
|
xop set xf_xt_APPID # APPID
|
|
xop set xf_xt_APISecret # APISecret
|
|
xop set xf_xt_APIKey # APIKey
|
|
```
|
|
|
|
LLM 配置(`apple-llm` / `dual` 需要;无 INI 则静默回退 apple 原文):
|
|
```ini
|
|
# ~/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_xt_* -- 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()` 读 `~/.xtype-engine`。默认 **Apple 端侧 SFSpeechRecognizer**(zh-CN,离线流式);备选 **讯飞 IAT v2 流式 WebSocket**(端点 `wss://iat-api.xfyun.cn/v2/iat`,HMAC-SHA256 鉴权,40ms 切片推送,服务端逐条返回拼接)。微信自家 ASR 是私有鉴权协议,外部不可用。
|
|
|
|
详细原理与全部踩坑:`docs/xtype/README.md`、`docs/xtype/GOTCHAS.md`。
|
|
|
|
详细原理与全部踩坑:`docs/xtype/README.md`、`docs/xtype/GOTCHAS.md`。
|