VoiceKey — 語音轉文字

按熱鍵 → 錄音 → API 辨識 → 自動貼上文字到游標位置

三層架構：Grok STT（第一層）→ Cerebras LLM 修正（第二層）→ 拼音詞彙精修（第三層），解決繁簡混用、標點遺漏、人名術語辨識問題。

文件索引：僅本檔（根目錄）使用 README.md；各子資料夾以 INDEX.md 為入口（見 docs/INDEX.md）。
Agent 開工先讀 AGENTS.md。

現況（2026-07-22）：本機路徑 A 部署完成（VoiceKey-macOS-20260712.dmg → /Applications/VoiceKey.app）；煙測通過；部署後驗證 #1 多 App 貼上、#2 模式切換 已確認。#3–#7 待測見 todo.md。approach-3 與 approach-6 原始碼已移除，歷史摘要見 Windows 方案 與 macOS Python 方案。分發腳本與 INSTALL-zh-TW.md 已就緒；zip/dmg 不進 git，需本機 package 後另傳。

• 完整 Xcode（非僅 Command Line Tools）
• xcodegen：brew install xcodegen
• API keys：XAI_API_KEY（Grok STT）、CEREBRAS_API_KEY（LLM 修正）

cd voicekey
bash setup-signing-cert.sh   # 建立 "VoiceKey Self-Signed"

固定 identity 後，rebuild 不會每次掉「輔助使用」授權（ad-hoc 會掉）。詳見 TROUBLESHOOTING-xcode.md。

cd voicekey
./test.sh       # 單元測試
./package.sh    # Release + self-signed → ~/Library/Developer/VoiceKey-DD/.../VoiceKey.app
# 拖進 /Applications，或 ditto 覆蓋

mkdir -p "$HOME/Library/Application Support/VoiceKey"
# 編輯 env.local（chmod 600），至少：
# XAI_API_KEY=...
# CEREBRAS_API_KEY=...

Key 讀取順序：環境變數 → App Support env.local → Keychain → bundle config.json。
絕不把 key 提交 git 或打包進 .app。

首次需允許：麥克風、輔助使用（不需「輸入監控」）。

1. 在開發機產出分發包：

cd voicekey
./package.sh && ./make-distribution.sh
# → voicekey/dist/VoiceKey-macOS-YYYYMMDD.zip 與 .dmg

2. 把 zip 或 dmg 拷到目標機（AirDrop / USB / 內網）。

   • 二進位不在 git（clone 後沒有 .app）；只有安裝說明在 repo
   • 說明：voicekey/dist/INSTALL-zh-TW.md

3. 目標機步驟摘要：

   • 拖 VoiceKey.app → /Applications
   • 右鍵「開啟」（未 notarize，Gatekeeper 提示屬正常）或 xattr -dr com.apple.quarantine /Applications/VoiceKey.app
   • 各機自備 ~/Library/Application Support/VoiceKey/env.local（API keys，chmod 600）
   • （選配）config.local.json 指定 recording.input_device
   • 允許 麥克風 + 輔助使用；Ctrl+F1 煙測
   • Log：~/Library/Logs/VoiceKey/app.log

也可請目標機上的 AI agent 執行安裝（需你提供 zip/dmg 路徑與 API keys）。

python scripts/test_api_key.py    # OpenAI / xAI / Groq
python scripts/test_cerebras.py   # Cerebras

Ctrl+F1
  → Carbon 熱鍵 → AVAudioEngine 錄音（16k mono PCM16）
  → Grok STT（keyterm hint）
  → Cerebras LLM 修正（失敗則用 raw STT）
  → 拼音詞彙 fuzzy（user_vocab.json）
  → NSPasteboard + CGEvent Cmd+V
  → SQLite session log（~/.voicekey_log.db）

本專案供學習與個人使用。各 API 使用需遵守對應服務條款（OpenAI / xAI / Cerebras / Groq）。