# OSGKeyboard

> 按住说话，松开即得 AI 润色文字，插入任意 App 的光标处。
> 一款源码可见的 iOS 自定义键盘语音输入工具，灵感来自 [Typeless](https://typeless.com) 和 [OpenLess](https://github.com/Open-Less/openless)。

![Platform](https://img.shields.io/badge/platform-iOS%2026%2B-0078D4?logo=apple)
![Swift](https://img.shields.io/badge/Swift-6.0-FA7343?logo=swift)
![License](https://img.shields.io/badge/license-Source%20Available-blue)

[English README](./README.md)

---

> ⚠️ **2026-06-24**: Default branch renamed from `main` to `0.2`. Old `main` is now `0.1`; `refactor/drop-qwen3-coreml` is now `0.2`. See CHANGELOG for details.

## Build Setup

This project uses [XcodeGen](https://github.com/yonaskolb/XcodeGen) — `project.yml`
is the source of truth, and `OSGKeyboard.xcodeproj` is **regenerated, not committed**
(it's in `.gitignore`). New clones must generate the Xcode project before opening
in Xcode, otherwise Xcode will show an empty project with no source files.

### Prerequisites

- macOS with **Xcode 26** (matches `project.yml` deployment target iOS 26)
- [Homebrew](https://brew.sh)

### One-time setup

```bash
brew install xcodegen
```

### Generate `OSGKeyboard.xcodeproj`

From the repository root:

```bash
./Scripts/generate-xcodeproj.sh
```

This script:

1. Runs `xcodegen generate` to produce `OSGKeyboard.xcodeproj` from `project.yml`.
2. Calls `Scripts/patch-icon-composer.sh` to patch the generated project for
   Xcode 26 Icon Composer bundles — `OSGKeyboard/AppIcon.icon` is treated as
   a single `folder.iconcomposer.icon` reference (see `project.yml` note on
   XcodeGen `fileTypes.icon`).

Then open the project:

```bash
open OSGKeyboard.xcodeproj
```

> **Troubleshooting**: If Xcode shows an empty project, re-run
> `./Scripts/generate-xcodeproj.sh`. If the build fails on icon assets,
> make sure `OSGKeyboard/AppIcon.icon/` exists with `Assets/` and `icon.json`
> inside (do not expand the folder manually).

### Re-running

Run `./Scripts/generate-xcodeproj.sh` any time `project.yml` changes
(e.g. after `git pull`).

---

## 这是什么？

OSGKeyboard 是商业语音输入工具的免费、源码可见替代方案。它以 **iOS 自定义键盘扩展** 的形式运行，所以你可以在 **任何 App** 里使用 —— 微信、备忘录、邮件、ChatGPT、Claude、Cursor，无所不能。

1. 长按麦克风键
2. 自由说话
3. 松开 —— AI 帮你整理成干净的文字，自动插入光标处

**音频始终在设备本地转写**（iOS 26+ 使用 `SpeechAnalyzer` + `DictationTranscriber`），**只有润色后的文本** 会发到你选择的云端 LLM。**音频永不离开你的手机。**

---

## 特性

- 🎙 **按住说话**，Typeless 风格的圆形麦克风按钮
- 🧠 **端侧 ASR**（iOS 26+ `SpeechAnalyzer` + `DictationTranscriber`）
- ✍️ **AI 润色** —— 自动加结构、补标点、修正语法、可生成列表
- 🧩 **本地 + 云端润色开关** —— 本地模式默认仅在设备上识别；若 iOS 语音识别效果不理想(远场、噪声、方言)，可开启「识别后云端润色」，默认走 DeepSeek
- 🔌 **自带 API 接入** —— 兼容任何 OpenAI 兼容协议端点（OpenAI / DeepSeek / Qwen DashScope / 自建服务器 ……）
- 🔒 **隐私优先** —— 音频不离开设备；只有润色文本会发给你选择的 LLM
- 🎨 **原生 SwiftUI** —— 暗色主题、毛玻璃、约 2000 行 Swift
- 🪶 **零依赖** —— 无 SwiftPM 包、无 CocoaPods、无 Carthage

---

## 快速开始

### 环境要求

- macOS + **Xcode 16+**（推荐 Xcode 26）
- iPhone 运行 **iOS 26.0+**
- [XcodeGen](https://github.com/yonaskolb/XcodeGen)：`brew install xcodegen`
- 一个 OpenAI 兼容 API Key（[OpenAI](https://platform.openai.com/api-keys) / [DeepSeek](https://platform.deepseek.com/api_keys) / [Qwen DashScope](https://dashscope.console.aliyun.com/apiKey) 任一）

### 编译与运行

```bash
git clone https://github.com/hkgood/OSGKeyboard.git
cd OSGKeyboard
xcodegen generate          # 生成 OSGKeyboard.xcodeproj
open OSGKeyboard.xcodeproj # 或命令行编译：
xcodebuild -project OSGKeyboard.xcodeproj -scheme OSGKeyboard \
  -destination 'generic/platform=iOS Simulator' build
```

### 在 iOS 中启用键盘

1. 在真机/模拟器上运行 App。
2. 按 3 步引导：**启用键盘** → **允许完全访问**（麦克风 + LLM 调用必须） → **粘贴 API Key**。
3. 在任意输入框，点 🌐 切换到 **OSGKeyboard**。
4. 长按麦克风键 → 说话 → 松开。✨

> **"允许完全访问"是必须的。** 没有它，iOS 会阻止键盘使用麦克风与网络。我们**绝不记录、存储或上传你的击键** —— 见 [`PrivacyInfo.xcprivacy`](./OSGKeyboard/PrivacyInfo.xcprivacy)。

---

## 架构

```
OSGKeyboard/
├── OSGKeyboard/                 # 主 iOS App（设置、Onboarding）
│   ├── Views/                   # SwiftUI 屏幕
│   ├── OSGKeyboardApp.swift     # @main 入口
│   ├── PrivacyInfo.xcprivacy    # 隐私清单
│   └── OSGKeyboard.entitlements # App Group 声明
├── OSGKeyboardExt/              # 自定义键盘扩展
│   ├── KeyboardViewController.swift   # 主体类
│   ├── Services/
│   │   ├── AudioCaptureService.swift  # AVAudioEngine → 16kHz PCM
│   │   ├── ASRService.swift           # iOS 26 SpeechAnalyzer ASR
│   │   └── PolishingService.swift     # LLM 调用（带超时）
│   └── Views/                   # 录音按钮、波形、键盘主视图
├── OSGKeyboardShared/           # 主 App + 键盘共享 framework
│   ├── Models/                  # ProviderConfig、LLMRequest、LLMProvider
│   ├── Services/                # LLMClient（OpenAI 兼容）
│   └── Constants/               # App Group ID
├── OSGKeyboardTests/            # XCTest 单元测试
├── project.yml                  # XcodeGen 工程定义
└── .github/workflows/ci.yml     # Lint + 编译 CI
```

### 数据流

```
[长按麦克风] → AudioCaptureService → AudioBufferSnapshot (16kHz mono)
                                        ↓
                                ASRService.transcribe()
                                        ↓
                          ASREvent.final(原始转写文本)
                                        ↓
                          PolishingService.polish()
                                        ↓
                        LLMClient（OpenAI 兼容协议）
                                        ↓
                   textDocumentProxy.insertText(润色后文本)
```

**引擎模式：**

- `cloud`（默认）：本地 `SpeechAnalyzer` 识别，文本发到云端 LLM 润色。
- `local`：本地 `SpeechAnalyzer` 识别，原始文本直接插入，不联网。
- `local` + 「识别后云端润色」开关（设置 → 本地模型）：与 `cloud` 类似，但使用本地引擎流程，识别完成后送 LLM 润色后再插入。需在 Keychain 中提前填好 DeepSeek（或任意 OpenAI 兼容提供方）API Key。

---

## 新增 LLM 提供商

打开 `OSGKeyboardShared/Models/LLMProvider.swift`，在 `presets` 数组里追加一条 `LLMProvider` 即可。默认的 `OpenAICompatibleClient` 处理任何实现了 `POST /chat/completions` 的端点。

```swift
LLMProvider(
    id: "groq",
    name: "Groq",
    defaultBaseURL: "https://api.groq.com/openai/v1",
    defaultModel: "llama-3.1-70b-versatile",
    apiKeyURL: URL(string: "https://console.groq.com/keys")
)
```

仅此而已，**无需改动其他代码**。

---

## 限制

- iOS 沙盒：键盘扩展 ~60 MB 内存上限，必须开完全访问
- 密码框与部分 `WKWebView` 输入框不可用（iOS 限制）
- 仅支持 iOS 26+；更早的 iOS 版本不在支持范围内。

---

## 许可

[OSGKeyboard 源码可见许可协议](./LICENSE) —— 仅限个人学习与非商用本地使用；禁止商用、再分发及公开 fork。商业授权请联系 [rocky.hk@gmail.com](mailto:rocky.hk@gmail.com)。

---

## 致谢

- 灵感来源：[Typeless](https://typeless.com) 与桌面端开源版 [OpenLess](https://github.com/Open-Less/openless)
- 工程脚手架：[XcodeGen](https://github.com/yonaskolb/XcodeGen)
- 端侧 ASR：Apple [SpeechAnalyzer](https://developer.apple.com/documentation/speech/speechanalyzer) / [SFSpeechRecognizer](https://developer.apple.com/documentation/speech/sfspeechrecognizer)

---

**说明**：本项目发布仓库为 [`hkgood/OSGKeyboard`](https://github.com/hkgood/OSGKeyboard)。