Files
adminandClaude d2263b16c7 feat: 配置统一到 ~/.x/xtype/config.json,去掉 env/xop 注入
**影响**
- 配置从三处散落(~/.xtype-engine ~/ssw.ini + 运行时 env 注入)收成一个
  ~/.x/xtype/config.json:engine + llm{key,base-url,model} +
  xunfei{appid,api-secret,api-key}。手改这一个文件即可切引擎 / 换凭据。
- 凭据从「运行时经 xop run --secret 注入 env」改为「明文存 config.json」
  (目录 0700 / 文件 0600)。启动方式不再影响行为:open / 双击 / 命令行
  读同一份配置,不再依赖 xop→open→LaunchServices 这条会被截断的 env 链。
- 旧路径 ~/.xtype-engine ~/ssw.ini 一律忽略,不迁移。

**改动**
- src/xtype.swift: 删 loadINI/normINIKey 与两处 ProcessInfo.environment 读取;
  新增 XTypeConfig/parseConfig/ensureConfig(JSON 解析 + 首启写模板);
  LLMConfig.load() 与 XunfeiEngine 凭据改读 config.json。
- src/build.sh: 删全部 xop run --secret 块,改普通 open;python3 只改
  engine 字段(OrderedDict 保序,不动凭据);首启建目录 0700 / 配置 0600;
  模式名非法直接报错退出。
- src/migrate-vault-to-config.sh: 一次性把 xop vault 凭据搬进 config.json,
  用户手跑(明文不进 agent 上下文),幂等只补空缺。
- AGENTS.md 红线 5/6 重写(凭据只存 config.json、不再走 env 注入);
  docs/xtype/README.md 引擎选择章节重写;docs/xtype/GOTCHAS.md §11 改写成
  「凭据别走 env 注入,读文件」的教训。

Co-Authored-By: Claude <[email protected]>
2026-10-22 19:03:01 +08:00

6.2 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          构建+签名+安装+重启一条龙
src/migrate-vault-to-config.sh  一次性:把 xop vault 凭据搬进 config.json(用户手跑)
docs/xtype/           详细文档(用法/架构/踩坑)

常用命令

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)

一个文件装下引擎选择 + 全部凭据:

{
  "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 <mode> 会用 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。