影响 - 鼠标按到非输入框(空白桌面 / Finder)长按时,菜单栏 mic 图标不再亮起; mic 路由只在 AX role 判定通过后(确认是输入框)才激活。 改动 - src/xtype.swift - ASREngine protocol 新增 armRecording(),prepare() 注释改为「不碰 mic 路由」 - AppleEngine.prepare() 拆走 installTap + engine.start,新方法 armRecording() 接管(单 apple 分支) - XunfeiEngine.prepare() 拆走 installTap + engine.start,新方法 armRecording() 接管 - AppleLLMEngine / DualEngine 新增 armRecording() 转发(dual 模式下 apple.useSharedTap=true 内部 no-op,xunfei 是 mic 唯一启动入口) - AppleEngine.cancel() 加 if engine.isRunning 守卫,避免 armRecording 没跑过的部分状态 stop() 打 warning - 长按 thread startRec() 在 Engine.ready check 之后插入 Engine.current.armRecording() 异步调用 - AGENTS.md - 补 line 7(已存在,随会话合入):Swift 不接 ObjC NSException,新增 ObjC API 必须经 XTObjCRun 桥接 - 核心设计 +2 条:ObjCBridge 通用 helper、Dual 模式 AVAudioEngine 共享 Co-Authored-By: Claude Code <[email protected]>
5.7 KiB
5.7 KiB
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 构建+签名+安装+重启一条龙
docs/xtype/ 详细文档(用法/架构/踩坑)
常用命令
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 # 停止
引擎切换(两个互不重叠的层面)
- 持久切换:
echo apple|apple-llm|xunfei|dual > ~/.xtype-engine,任意方式启动都生效。 - 启动方式注入:
src/build.sh xunfei用xop run --secret ... -- open ...临时把讯飞凭据塞进进程环境变量,只对当次启动有效,不会写到磁盘/源码。
讯飞凭据一次性入库(从 TTY 读值,源码/git/日志都不出现):
xop set xf_xt_APPID # APPID
xop set xf_xt_APISecret # APISecret
xop set xf_xt_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)。
红线(违反必翻车)
- 签名必须用固定 Apple Development 证书(
src/build.sh里的IDENT)。ad-hoc-s -每次重编译身份都变,TCC 当成新 app,三项授权全作废。 - 必须以 .app 形式装在 /Applications 并 LaunchServices 注册。裸 CLI 的 TCC 归属是宿主终端,行为混乱;/tmp 下的 app 进不了辅助功能列表。
- 权限三件套缺一不可:麦克风(录音)、语音识别(apple 引擎)/ 辅助功能(全模式)。日志
trusted: true+mic granted: true+speech auth: 3全绿才算就绪。 - 长按状态机:一次按下只判定一次(激活/跳过后进
.dead,松开才复位)。打回 idle 会在按住期间循环重启录音引擎(已踩过)。 - 讯飞凭据永不落盘:源码/git/日志/argv/历史都不能出现 APPID/APISecret/APIKey 明文。运行时统一经
xop run --secret KEY=xf_xt_* -- open ...注入到ProcessInfo.processInfo.environment["XUNFEI_*"]。引擎拿到空 env 时直接报错退出,不静默回退 apple(避免"以为用了讯飞结果识别差"的误判)。 - LLM 凭据明文存于
~/ssw.ini(用户偏好,不进 xop);key字段不进源码/git/日志。LLM 失败/超时/未配 → 保留 Apple 原文,不静默丢弃。 - 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()读~/.xtype-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 加useSharedTapflag 区分 single / dual 模式路径。
详细原理与全部踩坑:docs/xtype/README.md、docs/xtype/GOTCHAS.md。
详细原理与全部踩坑:docs/xtype/README.md、docs/xtype/GOTCHAS.md。