# xtype / XType macOS 工具:**长按鼠标左键 → 说话 → 松开自动粘贴到光标处**(任意 app 输入框;微信窗口内自动放行给微信自己的语音输入)。 ## 布局 ``` src/xtype.swift 全部源码(主程序) src/ObjCBridge.h ObjC NSException 桥接头(供 xtype.swift -import-objc-header) src/ObjCBridge.m ObjC @try/@catch 实现,必须 swiftc 一同编译 src/Info.plist app 包描述(权限声明) src/build.sh 构建+签名+安装+重启一条龙 src/migrate-vault-to-config.sh 一次性:把 xop vault 凭据搬进 config.json(用户手跑) docs/xtype/ 详细文档(用法/架构/踩坑) ``` ## 常用命令 ```bash src/build.sh # 编译 → 签名 → 装到 /Applications → apple-llm 启动 → 打日志(默认) src/build.sh apple # 纯端侧(无 LLM 精修) src/build.sh apple-llm # 端侧 + LLM 异步精修 src/build.sh xunfei # 讯飞 IAT v2 WebSocket 引擎 src/build.sh dual # apple + xunfei 并行 + LLM 精修 tail -f /tmp/xtype.log # 看判定/识别/粘贴日志 killall XType # 停止 ``` ## 配置(全在 `~/.x/xtype/config.json`) 一个文件装下引擎选择 + 全部凭据: ```json { "engine": "apple-llm", "llm": { "key": "sk_xxx", "base-url": "https://your-llm-proxy/v1", "model": "GLM-5.3-Flash" }, "xunfei": { "appid": "xxx", "api-secret": "xxx", "api-key": "xxx" } } ``` - **目录 `~/.x/xtype` 0700、文件 `config.json` 0600**(明文凭据)。 - **引擎切换 = 改 `engine` 字段**:`src/build.sh ` 会用 python3 只改这一个字段(保序,不动凭据);手改文件也行,任意方式启动都生效。 - **`engine` 取值**:`apple` / `apple-llm` / `xunfei` / `dual`。 - **LLM**(`apple-llm` / `dual` 需要):`llm.key` + `llm.base-url` + `llm.model` 三者齐全才启用;缺任一 → 静默回退 Apple 原文。引擎请求时强制带 `thinking: {type: "disabled"`,绕过 GLM 推理模式(7s → 1s)。 - **讯飞**(`xunfei` / `dual` 需要):`xunfei.appid` + `xunfei.api-secret` + `xunfei.api-key` 三者齐全才工作;缺任一 → 明确报错退出,不静默回退 apple(避免"以为用了讯飞结果识别差"的误判)。 - 文件不存在时 app / build.sh 自动写模板(`engine: apple` + 空凭据)。 - **从 xop vault 一次性迁入凭据**(用户手跑,明文不进 agent 上下文):`src/migrate-vault-to-config.sh` —— 幂等,只补空缺不覆盖已填值,跑完只打印字段名不打印值。 ## 红线(违反必翻车) 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. **凭据只存 `~/.x/xtype/config.json` 一处**:源码/git/日志/argv/历史都不出现 APPID/APISecret/APIKey/LLM key 明文。运行时从 `config.json` 读(明文,用户偏好),**不再走 env 注入、不再依赖 xop**。讯飞三件套缺任一 → 引擎直接报错退出,不静默回退 apple。 6. **LLM 失败/超时/未配 `llm.*` → 保留 Apple 原文**,不静默丢弃。`llm.key` 不进源码/git/日志。 7. **Swift 不接 ObjC NSException**:所有可能抛 NSException 的 ObjC API 必须经 `src/ObjCBridge.h/.m` 桥接(`XTObjCTryInstallTap` / `XTObjCRun`)。Swift 直接调会 SIGSEGV(EXC_BAD_ACCESS 0xD,`_Unwind_RaiseException`)。**已观测抛点**:`installTapOnBus` / `webSocketTask(with:)` / `recognitionTask(with:)` / `SFSpeechAudioBufferRecognitionRequest()` init。**XunfeiEngine.session 必须用 lazy var 同生命周期复用**,反复 `invalidateAndCancel` + 新建会让 self delegate 同时关联 invalidated 旧 session + 新 session,`webSocketTask(with:)` 抛 `INVALIDATED_SESSION`。新引入 ObjC API 也要先过 `XTObjCRun`。 ## 核心设计(为什么这么做) - **鼠标左键轮询零权限可用**(`CGEventSource.buttonState`),Fn/Globe 键则轮询不可见——所以触发方式选左键而不是 Fn(实验证据见 GOTCHAS §1)。 - **判定用"光标下最顶层窗口归属"**(CGWindowList z 序),不用 `frontmostApplication`——微信悬浮窗会霸占键盘焦点导致误判(踩坑见 GOTCHAS §5)。 - **判定三层**:AX 焦点角色严格判断 → `AXManualAccessibility` 强开 Chromium 系 AX 再查 → 完全不透明则 app 级兜底放行。 - **注入 = 写剪贴板 + 合成 ⌘V**,1.5s 后恢复原剪贴板(与微信同款)。 - **识别引擎可插拔**:`protocol ASREngine` + `pickEngine()` 读 `~/.x/xtype/config.json` 的 `engine` 字段。默认 **Apple 端侧 SFSpeechRecognizer**(zh-CN,离线流式);备选 **讯飞 IAT v2 流式 WebSocket**(端点 `wss://iat-api.xfyun.cn/v2/iat`,HMAC-SHA256 鉴权,40ms 切片推送,服务端逐条返回拼接)。微信自家 ASR 是私有鉴权协议,外部不可用。 - **ObjCBridge 通用 helper**:`XTObjCRun(void (^)(void))` 接受任意 Swift block,在 ObjC 端 `@try/@catch (NSException *)` 跑,失败 NSLog reason 并返回 1。`XTObjCTryInstallTap` 是 installTap 特化版(只需把参数列清楚,block 内逻辑一致)。Swift 端用 `if XTObjCRun({ ... }) != 0 { ... return }` 优雅降级——不抛也能用,抛了不崩。 - **Dual 模式 AVAudioEngine 共享**:AppleEngine / XunfeiEngine 各自 `let engine = AVAudioEngine()`(独立实例,但底层 inputNode 同源)。macOS AVAudioSession.input 同一进程只能一个 stream,**DualEngine 让 xunfei 接管 tap,tap 回调里把同一份 PCM 转发给 `apple.request?.append(buf)`**——单一 tap 槽 + 双消费者,既不撞 bus 0 也不让 apple 收不到音频。AppleEngine 加 `useSharedTap` flag 区分 single / dual 模式路径。 详细原理与全部踩坑:`docs/xtype/README.md`、`docs/xtype/GOTCHAS.md`。 详细原理与全部踩坑:`docs/xtype/README.md`、`docs/xtype/GOTCHAS.md`。