Files
xtype/docs/xtype/README.md
T
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.0 KiB

XType — 长按左键语音输入(原型文档)

灵感来自微信 Mac 版的"按住说话":在任意 app 的输入框长按鼠标左键说话,松开文字自动出现在光标处。本工具把它做成全局的,且微信窗口内自动放行。

使用

  1. src/build.sh 构建安装(首次需手动开「系统设置 → 隐私与安全性 → 辅助功能 → XType」,麦克风/语音识别弹窗点允许)
  2. 点击输入框定位光标 → 按住左键 ≥0.35s(哔一声开始)→ 说话 → 松开 → 出字
  3. 位移超过 10px 视为拖选,不触发;微信窗口内长按交给微信自己的语音输入

日志:/tmp/xtype.log(每次判定都记录走了哪条路径、看到什么角色、识别文本、粘贴结果)。

配置(全在 ~/.x/xtype/config.json)

引擎选择 + 全部凭据装在一个 JSON 文件里(目录 ~/.x/xtype 0700、文件 0600):

{
  "engine": "apple-llm",
  "llm":    { "key": "sk_xxxxxxxxxxxx", "base-url": "https://your-llm-proxy/v1", "model": "GLM-5.3-Flash" },
  "xunfei": { "appid": "xxxxxxxx", "api-secret": "xxxxxxxx", "api-key": "xxxxxxxx" }
}

文件不存在时 src/build.sh 或 app 首次启动会自动写模板(engine: apple + 空凭据)。

engine 字段决定用哪个 ASR 引擎:

值 引擎 备注
apple-llm (build.sh 默认) Apple 端侧 + LLM 异步精修 需 llm.* 三项齐全;缺任一 → 回退 Apple 原文
apple (模板默认) SFSpeechRecognizer 端侧 zh-CN 离线,无凭据,响应快,无 LLM 清洗
xunfei 讯飞 IAT v2 WebSocket 流式 需 xunfei.* 三项齐全;缺任一 → 明确报错,丢弃本次录音
dual apple + xunfei 并行 + LLM 精修 苹果先贴,讯飞覆盖,LLM 再精修

apple-llm / dual 的 LLM 配置

LLM 走 OpenAI Chat Completions 兼容协议(任何 zhipu/openai/anthropic-compatible 代理都行)——填 llm.key / llm.base-url / llm.model 三项即可。

引擎会自动在请求里带 thinking: {type: "disabled",绕开 GLM 系列推理模式(7s+ → 1s,实测 thinking=disabled 后稳定 ~0.9s)。

失败兜底: 缺 llm.* / key 错 / 网络断 / 超时 → 保留 Apple 原文,绝不静默丢内容。

讯飞凭据

填 xunfei.appid / xunfei.api-secret / xunfei.api-key 三项。任一缺失则引擎报错并丢弃本次录音(不静默回退 apple,避免你以为用了讯飞但实际是 apple 给你识别差)。

凭据只存这一个文件 —— 源码/git/日志/argv/历史里都不出现明文。

从 xop vault 一次性迁入凭据

以前凭据放在 xop vault(运行时经 xop run --secret 注入 env),现在改成直接读文件。一次性搬过去:

src/migrate-vault-to-config.sh

明文经 xop → 子进程 env → 文件,不进任何命令行参数或日志;脚本只打印字段名(如 filled: llm.key, xunfei.appid, ...),不打印值。幂等 —— 已填的字段不会被覆盖,只补空缺。

跑完后 config.json 里就有 llm.* 和 xunfei.* 的真实值,xunfei / dual 模式即可用。

启动对应引擎

src/build.sh                # 默认 = apple-llm
src/build.sh apple          # 纯端侧(无 LLM 精修)
src/build.sh apple-llm      # 端侧 + LLM(默认)
src/build.sh xunfei         # 讯飞
src/build.sh dual           # 双引擎

这一步做两件事:

  1. 用 python3 只改 config.json 的 engine 字段(保序,不动 llm/xunfei 凭据)
  2. open /Applications/XType.app 启动(不再注入任何环境变量)

手改 config.json 的 engine 同样生效 —— open /Applications/XType.app 直接启动也读同一份配置。

判定流程(按住 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 无
预连接 鼠标按下瞬间就建 WS / 建识别请求(不碰 mic 路由),激活判定通过后才 armRecording() 装 tap + 启 engine 麦克风(仅录音期)
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() 读 ~/.x/xtype/config.json 的 engine,默认 apple —
注入 写剪贴板 → 合成 ⌘V → 1.5s 后恢复原剪贴板 辅助功能
拖选抑制 tap 录音期间吞掉 leftMouseDragged,防拖选文字 辅助功能
聚焦查询 AX 系统级/per-app kAXFocusedUIElementAttribute + 角色 辅助功能

已知边界(探针范围外)

  • AX 完全不透明的 app 里是 app 级兜底:长按它任何位置都触发,不只输入框
  • 剪贴板恢复只管文本(图片/文件内容不还原)
  • 录音上限 60s;350ms 内慢速起步(<10px)的拖选理论可能误判
  • LSUIElement 无界面:无菜单栏开关、无开机自启、无常量配置面板(阈值都是源码顶部常量)
  • 讯飞 IAT v2 单次请求 60s 上限(服务端);长语音会被截断
  • 讯飞计费按调用次数+音频时长,开发期注意用量