rename: voicetype → xtype (bundle id, paths, xop vault refs)

- 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]>
This commit is contained in:
adminandClaude Code committed 2026-10-07 11:01:09 +08:00
1 parent 6b88844d1b
commit 63b41c9750
6 files changed
+68 -68

No files matched your search

+13 -13
View File
@@ -1,14 +1,14 @@
# voicetype / VoiceType
# xtype / XType
macOS 工具:**长按鼠标左键 → 说话 → 松开自动粘贴到光标处**(任意 app 输入框;微信窗口内自动放行给微信自己的语音输入)。
## 布局
```
src/voicetype.swift 全部源码(单文件探针,~330 行)
src/xtype.swift 全部源码(单文件探针,~330 行)
src/Info.plist app 包描述(权限声明)
src/build.sh 构建+签名+安装+重启一条龙
docs/voicetype/ 详细文档(用法/架构/踩坑)
docs/xtype/ 详细文档(用法/架构/踩坑)
```
## 常用命令
@@ -19,20 +19,20 @@ 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/voicetype.log # 看判定/识别/粘贴日志
killall VoiceType # 停止
tail -f /tmp/xtype.log # 看判定/识别/粘贴日志
killall XType # 停止
```
## 引擎切换(两个互不重叠的层面)
1. **持久切换**:`echo apple|apple-llm|xunfei|dual > ~/.voicetype-engine`,任意方式启动都生效。
1. **持久切换**:`echo apple|apple-llm|xunfei|dual > ~/.xtype-engine`,任意方式启动都生效。
2. **启动方式注入**:`src/build.sh xunfei` 用 `xop run --secret ... -- open ...` 临时把讯飞凭据塞进进程环境变量,**只对当次启动有效**,不会写到磁盘/源码。
讯飞凭据一次性入库(从 TTY 读值,源码/git/日志都不出现):
```bash
xop set xf_vt_APPID # APPID
xop set xf_vt_APISecret # APISecret
xop set xf_vt_APIKey # APIKey
xop set xf_xt_APPID # APPID
xop set xf_xt_APISecret # APISecret
xop set xf_xt_APIKey # APIKey
```
LLM 配置(`apple-llm` / `dual` 需要;无 INI 则静默回退 apple 原文):
@@ -51,7 +51,7 @@ model=GLM-5.3-Flash
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_vt_* -- open ...` 注入到 `ProcessInfo.processInfo.environment["XUNFEI_*"]`。引擎拿到空 env 时**直接报错退出**,不静默回退 apple(避免"以为用了讯飞结果识别差"的误判)。
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 原文,不静默丢弃。
## 核心设计(为什么这么做)
@@ -60,8 +60,8 @@ model=GLM-5.3-Flash
- **判定用"光标下最顶层窗口归属"**(CGWindowList z 序),不用 `frontmostApplication`——微信悬浮窗会霸占键盘焦点导致误判(踩坑见 GOTCHAS §5)。
- **判定三层**:AX 焦点角色严格判断 → `AXManualAccessibility` 强开 Chromium 系 AX 再查 → 完全不透明则 app 级兜底放行。
- **注入 = 写剪贴板 + 合成 ⌘V**,1.5s 后恢复原剪贴板(与微信同款)。
- **识别引擎可插拔**:`protocol ASREngine` + `pickEngine()` 读 `~/.voicetype-engine`。默认 **Apple 端侧 SFSpeechRecognizer**(zh-CN,离线流式);备选 **讯飞 IAT v2 流式 WebSocket**(端点 `wss://iat-api.xfyun.cn/v2/iat`,HMAC-SHA256 鉴权,40ms 切片推送,服务端逐条返回拼接)。微信自家 ASR 是私有鉴权协议,外部不可用。
- **识别引擎可插拔**:`protocol ASREngine` + `pickEngine()` 读 `~/.xtype-engine`。默认 **Apple 端侧 SFSpeechRecognizer**(zh-CN,离线流式);备选 **讯飞 IAT v2 流式 WebSocket**(端点 `wss://iat-api.xfyun.cn/v2/iat`,HMAC-SHA256 鉴权,40ms 切片推送,服务端逐条返回拼接)。微信自家 ASR 是私有鉴权协议,外部不可用。
详细原理与全部踩坑:`docs/voicetype/README.md`、`docs/voicetype/GOTCHAS.md`。
详细原理与全部踩坑:`docs/xtype/README.md`、`docs/xtype/GOTCHAS.md`。
详细原理与全部踩坑:`docs/voicetype/README.md`、`docs/voicetype/GOTCHAS.md`。
详细原理与全部踩坑:`docs/xtype/README.md`、`docs/xtype/GOTCHAS.md`。
@@ -1,4 +1,4 @@
# GOTCHAS — VoiceType 踩坑全记录(2026-10-02 spike)
# GOTCHAS — XType 踩坑全记录(2026-10-02 spike)
## 1. Fn(🌐) 键轮询不可见;鼠标左键零权限可见
@@ -59,8 +59,8 @@ v1 在激活(350ms)后才启动录音引擎,用户按下即开口,前几百毫
## 11. xop 注入 env 经 `open` 传递到 .app
`xop run --secret X=xf_vt_X -- open /Applications/VoiceType.app` 时,env 经 `xop → open → LaunchServices → app` 这条链路一直传到底,`ProcessInfo.processInfo.environment["XUNFEI_X"]` 在 app 内能拿到。但有几种场景会丢:
- macOS 14+ 的 `open --new` 在某些沙盒场景下被 launchd 接管,env 被截断 → 备用 `xop run --secret ... -- /Applications/VoiceType.app/Contents/MacOS/VoiceType`(直接执行二进制,TCC 仍生效,因为同一 .app bundle)
`xop run --secret X=xf_xt_X -- open /Applications/XType.app` 时,env 经 `xop → open → LaunchServices → app` 这条链路一直传到底,`ProcessInfo.processInfo.environment["XUNFEI_X"]` 在 app 内能拿到。但有几种场景会丢:
- macOS 14+ 的 `open --new` 在某些沙盒场景下被 launchd 接管,env 被截断 → 备用 `xop run --secret ... -- /Applications/XType.app/Contents/MacOS/XType`(直接执行二进制,TCC 仍生效,因为同一 .app bundle)
- 用户从 Finder 双击 .app:不走 xop,env 没有,引擎立刻报错退出
## 复现/验证工具
@@ -1,18 +1,18 @@
# VoiceType — 长按左键语音输入(原型文档)
# XType — 长按左键语音输入(原型文档)
灵感来自微信 Mac 版的"按住说话":在**任意 app 的输入框**长按鼠标左键说话,松开文字自动出现在光标处。本工具把它做成全局的,且微信窗口内自动放行。
## 使用
1. `src/build.sh` 构建安装(首次需手动开「系统设置 → 隐私与安全性 → 辅助功能 → VoiceType」,麦克风/语音识别弹窗点允许)
1. `src/build.sh` 构建安装(首次需手动开「系统设置 → 隐私与安全性 → 辅助功能 → XType」,麦克风/语音识别弹窗点允许)
2. 点击输入框定位光标 → **按住左键 ≥0.35s**(哔一声开始)→ 说话 → **松开** → 出字
3. 位移超过 10px 视为拖选,不触发;微信窗口内长按交给微信自己的语音输入
日志:`/tmp/voicetype.log`(每次判定都记录走了哪条路径、看到什么角色、识别文本、粘贴结果)。
日志:`/tmp/xtype.log`(每次判定都记录走了哪条路径、看到什么角色、识别文本、粘贴结果)。
## 引擎选择
`~/.voicetype-engine` 文件内容决定用哪个 ASR 引擎(空文件 = `apple-llm`):
`~/.xtype-engine` 文件内容决定用哪个 ASR 引擎(空文件 = `apple-llm`):
| 值 | 引擎 | 备注 |
|---|---|---|
@@ -43,9 +43,9 @@ model=GLM-5.3-Flash
凭据**只**从 TTY 读取,不会出现在源码/git/日志/argv/历史里。`xop set <name>` 然后回车输入值。
```bash
xop set xf_vt_APPID # APPID
xop set xf_vt_APISecret # APISecret
xop set xf_vt_APIKey # APIKey
xop set xf_xt_APPID # APPID
xop set xf_xt_APISecret # APISecret
xop set xf_xt_APIKey # APIKey
```
### 启动对应引擎
@@ -59,8 +59,8 @@ src/build.sh dual # 双引擎(需 xop 注入)
```
这一步做三件事:
1. 把 `~/.voicetype-engine` 写成对应模式(持久切换)
2. `xunfei` / `dual` 模式会 `xop run --secret XUNFEI_APPID=xf_vt_APPID --secret ... -- open /Applications/VoiceType.app` —— 凭据仅在子进程 env 里存在
1. 把 `~/.xtype-engine` 写成对应模式(持久切换)
2. `xunfei` / `dual` 模式会 `xop run --secret XUNFEI_APPID=xf_xt_APPID --secret ... -- open /Applications/XType.app` —— 凭据仅在子进程 env 里存在
3. 引擎读 `ProcessInfo.processInfo.environment["XUNFEI_*"]`,**任一缺失则报错并丢弃本次录音**(不静默回退 apple,避免你以为用了讯飞但实际是 apple 给你识别差)。
## 判定流程(按住 350ms 时触发一次)
@@ -85,7 +85,7 @@ src/build.sh dual # 双引擎(需 xop 注入)
| `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()` | 读 `~/.voicetype-engine`,默认 `apple-llm` | — |
| `pickEngine()` | 读 `~/.xtype-engine`,默认 `apple-llm` | — |
| 注入 | 写剪贴板 → 合成 ⌘V → 1.5s 后恢复原剪贴板 | 辅助功能 |
| 拖选抑制 tap | 录音期间吞掉 leftMouseDragged,防拖选文字 | 辅助功能 |
| 聚焦查询 | AX 系统级/per-app `kAXFocusedUIElementAttribute` + 角色 | 辅助功能 |
+3 -3
View File
@@ -2,9 +2,9 @@
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>CFBundleIdentifier</key><string>com.xs.voicetype</string>
<key>CFBundleName</key><string>VoiceType</string>
<key>CFBundleExecutable</key><string>VoiceType</string>
<key>CFBundleIdentifier</key><string>com.xs.xtype</string>
<key>CFBundleName</key><string>XType</string>
<key>CFBundleExecutable</key><string>XType</string>
<key>CFBundlePackageType</key><string>APPL</string>
<key>CFBundleShortVersionString</key><string>0.1</string>
<key>LSMinimumSystemVersion</key><string>14.0</string>
+33 -33
View File
@@ -1,5 +1,5 @@
#!/bin/bash
# 构建 VoiceType.app 并安装到 /Applications
# 构建 XType.app 并安装到 /Applications
# 红线: 必须用固定 Apple Development 证书签名 —— ad-hoc(-s -) 每次重编译身份都变,
# TCC 会当成新 app,麦克风/语音/辅助功能授权全部作废
#
@@ -11,15 +11,15 @@
# src/build.sh dual apple + xunfei 并行 + LLM 精修(xunfei 覆盖后)
#
# 引擎持久切换(两种启动方式之外):
# echo apple > ~/.voicetype-engine
# echo apple-llm > ~/.voicetype-engine
# echo xunfei > ~/.voicetype-engine
# echo dual > ~/.voicetype-engine
# echo apple > ~/.xtype-engine
# echo apple-llm > ~/.xtype-engine
# echo xunfei > ~/.xtype-engine
# echo dual > ~/.xtype-engine
#
# 凭据(讯飞,一次性,只需跑一次,xop 从 TTY 读值):
# xop set xf_vt_APPID # APPID
# xop set xf_vt_APISecret # APISecret
# xop set xf_vt_APIKey # APIKey
# xop set xf_xt_APPID # APPID
# xop set xf_xt_APISecret # APISecret
# xop set xf_xt_APIKey # APIKey
#
# LLM(apple-llm/dual 需要,否则静默回退到 apple 原文):
# ~/ssw.ini → [llm-api] key=… base-url=… model=…
@@ -28,59 +28,59 @@ set -e
cd "$(dirname "$0")"
IDENT="Apple Development: [email protected] (Y4AJXC7Q9S)"
APP=/Applications/VoiceType.app
BIN=/tmp/voicetype-build
APP=/Applications/XType.app
BIN=/tmp/xtype-build
MODE="${1:-apple-llm}"
swiftc -O voicetype.swift -o "$BIN"
swiftc -O xtype.swift -o "$BIN"
mkdir -p "$APP/Contents/MacOS"
cp "$BIN" "$APP/Contents/MacOS/VoiceType"
cp "$BIN" "$APP/Contents/MacOS/XType"
cp Info.plist "$APP/Contents/Info.plist"
codesign --force --sign "$IDENT" "$APP"
killall VoiceType 2>/dev/null || true
killall XType 2>/dev/null || true
sleep 0.3
: > /tmp/voicetype.log
: > /tmp/xtype.log
case "$MODE" in
xunfei)
# 把 ~/.voicetype-engine 也设上,使得日后 `open /Applications/VoiceType.app`
# 把 ~/.xtype-engine 也设上,使得日后 `open /Applications/XType.app`
# 直接双击也能继续用 xunfei。凭据永远只走 xop 注入,不落盘不传 argv。
current="$( [ -f ~/.voicetype-engine ] && tr -d '[:space:]' < ~/.voicetype-engine || echo '' )"
[ "$current" != "xunfei" ] && echo xunfei > ~/.voicetype-engine
current="$( [ -f ~/.xtype-engine ] && tr -d '[:space:]' < ~/.xtype-engine || echo '' )"
[ "$current" != "xunfei" ] && echo xunfei > ~/.xtype-engine
xop run \
--secret XUNFEI_APPID=xf_vt_APPID \
--secret XUNFEI_API_SECRET=xf_vt_APISecret \
--secret XUNFEI_API_KEY=xf_vt_APIKey \
--secret XUNFEI_APPID=xf_xt_APPID \
--secret XUNFEI_API_SECRET=xf_xt_APISecret \
--secret XUNFEI_API_KEY=xf_xt_APIKey \
-- open "$APP"
;;
dual)
current="$( [ -f ~/.voicetype-engine ] && tr -d '[:space:]' < ~/.voicetype-engine || echo '' )"
[ "$current" != "dual" ] && echo dual > ~/.voicetype-engine
current="$( [ -f ~/.xtype-engine ] && tr -d '[:space:]' < ~/.xtype-engine || echo '' )"
[ "$current" != "dual" ] && echo dual > ~/.xtype-engine
xop run \
--secret XUNFEI_APPID=xf_vt_APPID \
--secret XUNFEI_API_SECRET=xf_vt_APISecret \
--secret XUNFEI_API_KEY=xf_vt_APIKey \
--secret XUNFEI_APPID=xf_xt_APPID \
--secret XUNFEI_API_SECRET=xf_xt_APISecret \
--secret XUNFEI_API_KEY=xf_xt_APIKey \
-- open "$APP"
;;
apple)
current="$( [ -f ~/.voicetype-engine ] && tr -d '[:space:]' < ~/.voicetype-engine || echo '' )"
[ -n "$current" ] && [ "$current" != "apple" ] && echo apple > ~/.voicetype-engine
current="$( [ -f ~/.xtype-engine ] && tr -d '[:space:]' < ~/.xtype-engine || echo '' )"
[ -n "$current" ] && [ "$current" != "apple" ] && echo apple > ~/.xtype-engine
open "$APP"
;;
apple-llm|*)
current="$( [ -f ~/.voicetype-engine ] && tr -d '[:space:]' < ~/.voicetype-engine || echo '' )"
[ -n "$current" ] && [ "$current" != "apple-llm" ] && echo apple-llm > ~/.voicetype-engine
[ -z "$current" ] && echo apple-llm > ~/.voicetype-engine
current="$( [ -f ~/.xtype-engine ] && tr -d '[:space:]' < ~/.xtype-engine || echo '' )"
[ -n "$current" ] && [ "$current" != "apple-llm" ] && echo apple-llm > ~/.xtype-engine
[ -z "$current" ] && echo apple-llm > ~/.xtype-engine
open "$APP"
;;
esac
sleep 2
cat /tmp/voicetype.log
cat /tmp/xtype.log
echo
echo "installed: $APP (pid $(pgrep -f VoiceType)) engine=$MODE"
[ "$MODE" = "xunfei" ] || [ "$MODE" = "dual" ] && echo "vault used: xf_vt_APPID / xf_vt_APISecret / xf_vt_APIKey (no values in logs/argv)"
echo "installed: $APP (pid $(pgrep -f XType)) engine=$MODE"
[ "$MODE" = "xunfei" ] || [ "$MODE" = "dual" ] && echo "vault used: xf_xt_APPID / xf_xt_APISecret / xf_xt_APIKey (no values in logs/argv)"
[ "$MODE" = "apple-llm" ] && grep -q '\[llm-api\]' ~/ssw.ini 2>/dev/null && echo "llm: ~/ssw.ini [llm-api] 已配 → LLM 异步精修生效;否则回退 apple 原文"
+6 -6
View File
@@ -1,4 +1,4 @@
// voicetype: 长按鼠标左键 → 说话 → 松开自动粘贴到光标处
// xtype: 长按鼠标左键 → 说话 → 松开自动粘贴到光标处
// 引擎可选: apple / xunfei / dual(apple+xunfei 并行,apple 先贴)
// 凭据(仅 xunfei 需要): 经 xop run --secret 注入到环境变量,源码/git/日志绝不出现
// LLM 清洗(可选): ~/ssw.ini 的 [llm-api] 段,key/base-url/model;无配置则跳过
@@ -16,7 +16,7 @@ let movePx: CGFloat = 10 // 位移超过此值视为拖选,不激活
let maxRecSec: Double = 60 // 最长录音(到点直接贴当前已识别部分,不继续等)
let pollUs: UInt32 = 8_000 // 轮询周期 8ms (~125Hz)
let weChatPrefix = "com.tencent.xinWeChat"
let engineConfigPath = NSHomeDirectory() + "/.voicetype-engine"
let engineConfigPath = NSHomeDirectory() + "/.xtype-engine"
let llmIniPath = NSHomeDirectory() + "/ssw.ini"
// ---------- INI 读取(仅支持 section/key=value 简单格式) ----------
@@ -112,7 +112,7 @@ final class Engine {
// ---------- Apple 端侧 SFSpeechRecognizer ----------
final class AppleEngine: ASREngine {
static let q = DispatchQueue(label: "voice.apple.rec")
static let q = DispatchQueue(label: "xtype.apple.rec")
let engine = AVAudioEngine()
var request: SFSpeechAudioBufferRecognitionRequest?
var task: SFSpeechRecognitionTask?
@@ -244,7 +244,7 @@ final class AppleLLMEngine: ASREngine {
// 凭据来自环境变量(XUNFEI_APPID / XUNFEI_API_SECRET / XUNFEI_API_KEY),
// 由 xop run --secret 在启动前注入。引擎自身不读配置文件、不打 fallback —— 安静回退会让用户误以为"用了讯飞识别差"。
final class XunfeiEngine: NSObject, ASREngine {
let q = DispatchQueue(label: "voice.xunfei")
let q = DispatchQueue(label: "xtype.xunfei")
let engine = AVAudioEngine()
var session: URLSession?
var wsTask: URLSessionWebSocketTask?
@@ -904,12 +904,12 @@ Thread.detachNewThread {
}
// ---------- 启动自检 + 权限请求 ----------
freopen("/tmp/voicetype.log", "a", stdout)
freopen("/tmp/xtype.log", "a", stdout)
setbuf(stdout, nil)
log("process=\(ProcessInfo.processInfo.processName) bundle=\(Bundle.main.bundleIdentifier ?? "nil")")
log("Accessibility trusted: \(AXIsProcessTrusted())")
if !AXIsProcessTrusted() {
log(">>> 系统设置 → 隐私与安全性 → 辅助功能 → 勾选 VoiceType <<<")
log(">>> 系统设置 → 隐私与安全性 → 辅助功能 → 勾选 XType <<<")
}
AVCaptureDevice.requestAccess(for: .audio) { ok in log("mic granted: \(ok)") }
SFSpeechRecognizer.requestAuthorization { st in log("speech auth: \(st.rawValue) (1=authorized)") }