AI 驱动的桌面端智能语音输入工具 —— 说出来，它替你整理成可直接发送的文字。
VoKiKi 通过系统级语音键盘，让你在任意应用的任意文本框中，按住热键说话即可完成输入。后端会实时把口语化的内容整理为精炼、通顺、可直接发送的书面文本；LLM 整理失败时会自动降级为原始识别文本，保证输入不中断。
- 🎙️ 全局语音输入 —— 按住热键（默认
Fn）录音，松开即完成识别与整理 - 🤖 ASR + LLM 双引擎 —— 语音转文字后自动润色，可按场景调整语气
- 🔌 多服务商可切换 —— ASR / LLM 均抽象为 Provider，可在设置中切换或使用本地模型
- 🔒 本地优先 —— 音频默认不落盘；历史记录仅保存在本地 SQLite
- 📋 无侵入插入 —— 通过剪贴板粘贴写入文本，兼容任意输入框
- 🪟 悬浮字幕 —— 录音时实时显示识别结果，位置可调
| 层 | 技术 |
|---|---|
| 桌面框架 | Tauri v2（Rust + WebView） |
| 前端 | React 19 · TypeScript · Vite 5 · Tailwind CSS v4 · Zustand · React Router 7 |
| 后端 | Rust（cpal 音频采集 · rdev 全局热键 · rusqlite 存储 · reqwest 网络请求） |
| 包管理 | yarn（请勿使用 pnpm） |
本地开发前请先安装以下依赖（macOS 为主要支持平台）：
- Node.js ≥ 18，随附 npm
- yarn（
npm i -g yarn） - Rust（stable 工具链，建议通过 rustup 安装）
- Xcode Command Line Tools（
xcode-select --install） - CMake（编译
whisper-rs依赖所需，brew install cmake）
项目依赖
rusqlite（bundled SQLite）、whisper-rs（whisper.cpp）、vosk等本地 crate，首次cargo build会从源码编译它们，耗时较长属正常现象。
# 1. 克隆仓库
git clone <repo-url> vokiki && cd vokiki
# 2. 安装前端依赖
yarn
# 3. 启动开发模式（前端热更新 + Rust 后端）
yarn tauri:dev启动后，应用窗口打开即进入首页。首次使用需在 设置 页填入服务商的 API Key（见下节）。
| 命令 | 说明 |
|---|---|
yarn install |
安装前端依赖 |
yarn dev |
仅启动前端（Vite，无 Tauri 后端） |
yarn tauri:dev |
启动完整应用（前端热更新 + Rust） |
yarn build |
前端生产构建 |
yarn tauri:build |
打包可发布的桌面应用（macOS 为 .dmg） |
cd src-tauri && cargo check |
仅检查 Rust 编译 |
tauri:dev/tauri:build脚本已自动把$HOME/.cargo/bin加入 PATH；如果你在终端直接运行yarn tauri dev，请确保 cargo 已在 PATH 中。
VoKiKi 不读取任何 .env 配置文件，所有配置通过应用内的 设置 页面管理，持久化到本地 SQLite（vokiki.db）。
要真正用起来语音输入，至少需要配置 ASR（语音识别） 服务商的 API Key。各 Provider 概览：
| Provider | 类型 | 内置接口地址 |
|---|---|---|
funasr |
本地（FunASR） | 无需 Key |
whisper |
本地（whisper.cpp） | 无需 Key |
vosk |
本地 | 无需 Key |
siliconflow |
云端（硅基流动） | 内置 |
custom |
自定义 | 语音识别接口（multipart/form-data 提交 file 字段，返回需含 text） |
| Provider | 类型 | 内置接口地址 |
|---|---|---|
local |
本地（candle · 纯 Rust CPU 推理；内置 Qwen3-0.6B / Qwen3-1.7B GGUF） |
无需 Key |
siliconflow |
云端（硅基流动） | 内置 |
zhipuai |
云端（智谱） | 内置 |
aliyun |
云端（阿里百炼） | 内置 |
custom |
自定义 OpenAI 兼容接口 | 用户填写 |
零成本尝鲜：ASR 选
funasr/whisper/vosk（本地运行，无需 API Key）；LLM 选local（内置 Qwen3 小参数模型，离线 CPU 推理）或关闭整理。也可使用各云端的免费额度（如智谱 GLM-4-Flash）开箱即用。
应用需要以下系统权限才能正常工作，首次启动时系统会弹窗引导授权：
| 权限 | 用途 |
|---|---|
| 辅助功能（Accessibility） | 全局热键监听（rdev）、文本插入 |
| 麦克风（Microphone） | 音频采集 |
| 输入监听（Input Monitoring） | 热键识别 |
在 系统设置 → 隐私与安全性 中确认 VoKiKi 已被勾选。
当权限异常（如热键失灵、麦克风无法录制）时，可重置后重新授权：
tccutil reset Accessibility com.vokiki.app && tccutil reset ListenEvent com.vokiki.app && tccutil reset Microphone com.vokiki.app由于 bundle identifier 为
com.vokiki.app，重置后需在 系统设置 中重新为 VoKiKi 开启对应权限，然后重启应用。
vokiki/
├── src/ # 前端
│ ├── pages/ # 页面：Home / History / Settings
│ ├── components/ # 组件：悬浮字幕、设置项
│ ├── stores/ # Zustand 状态（recording / settings）
│ ├── hooks/ # useRecording / useHistory
│ └── lib/tauri.ts # Tauri invoke/listen 封装 + Provider 配置
├── src-tauri/ # Rust 后端
│ ├── src/
│ │ ├── audio/ # 音频采集（cpal）+ WAV 编码
│ │ ├── hotkey/ # 全局热键（rdev）
│ │ ├── asr/ # ASR Provider 抽象（FunASR / Whisper / Vosk / 云端 …）
│ │ ├── llm/ # LLM Provider 抽象（本地 candle / 智谱 / 阿里 / OpenAI 兼容）
│ │ ├── pipeline/ # ASR → LLM 编排，带降级
│ │ ├── output/ # 文本插入（剪贴板 + 模拟粘贴）
│ │ ├── storage/ # SQLite 存储（history / settings）
│ │ ├── commands/ # 暴露给前端的 Tauri 命令
│ │ └── lib.rs # Tauri 入口、命令注册、托盘菜单
│ ├── icons/ # 应用图标
│ ├── Cargo.toml # Rust 依赖
│ └── tauri.conf.json # Tauri 配置（窗口 / identifier / bundle）
├── docs/ # 产品文档
│ ├── PRD/v1.md
│ └── DESIGN/v1.md
└── package.json
- Provider 抽象：ASR 与 LLM 均定义 trait，新增服务商只需实现 trait 并在设置中注册。
- 管线编排：
src-tauri/src/pipeline/orchestrator.rs负责完整的「采集 → 识别 → 整理 → 插入」流程；LLM 失败会自动降级为原始 ASR 文本，不影响输入。 - 数据与隐私：音频默认不写入磁盘；仅在设置中开启「保存音频」时，按
audio_save_path（默认~/Music/VoKiKi）保存。历史记录与设置全部存在本地vokiki.db。 - 文本插入：通过写入剪贴板再模拟粘贴实现，不依赖逐字符模拟，兼容性更好。
关键文件索引：
- src-tauri/src/lib.rs — Tauri 应用入口、命令注册、托盘菜单
- src-tauri/src/pipeline/orchestrator.rs — ASR → LLM 核心编排
- src-tauri/src/asr/provider.rs — ASR Provider trait
- src-tauri/src/llm/provider.rs — LLM Provider trait
- src-tauri/src/audio/capture.rs — 麦克风采集 + WAV 编码
- src/lib/tauri.ts — 前端 TS API 层与 Provider 配置
启动 yarn tauri:dev 报 Rust / cargo 相关错误
确认 Rust 已安装（rustc --version），且 ~/.cargo/bin 在 PATH 中。脚本 tauri:dev 已自动补 PATH，若仍失败可手动 source "$HOME/.cargo/env" 后重试。
首次编译 cargo check 很慢或报错
依赖 whisper-rs 需通过 CMake 编译 whisper.cpp，请确认已安装：brew install cmake，并已装好 Xcode Command Line Tools（xcode-select --install）。
热键无反应 / 无法在其它 App 中输入
通常是 macOS 权限问题。确认 VoKiKi 已获「辅助功能」「输入监听」权限；必要时执行上文的「重置授权」命令后重新授权并重启应用。
切换 bundle identifier 后历史记录 / 设置丢失
数据按 app_data_dir 隔离，identifier 变更会导致数据目录变化，属预期行为。开发期可通过设置页重新配置。
MacOS上提示已损坏无法打开怎么办？
sudo xattr -rd com.apple.quarantine /Applications/VoKiKi.app
VoKiKi 采用 AGPL-3.0-or-later + 商用授权 的双授权模型，详见 LICENSE 与 LICENSE-COMMERCIAL.md。
- 开源使用（AGPL-3.0）：个人 / 团队自身使用、学习、二次开发均免费。但 AGPL-3.0 有强传染性——一旦你把 VoKiKi 或其衍生作品分发给第三方，或通过网络对外提供服务，必须按 AGPL-3.0 公开你整个产品的源代码。
- 商用授权：如果你需要把 VoKiKi 集成进闭源商业产品、二次开发后对外销售、或在企业内部部署修改版却不愿公开源码，请购买商用授权以免除 AGPL 义务。洽谈方式见
LICENSE-COMMERCIAL.md。
简单判断：个人自用或开源项目 → 免费用；要把 VoKiKi 拿去做成闭源商业产品 → 需购买商用授权。
⚠️ 本项目不使用 MIT，不可在闭源商业产品中免费使用。
「VoKiKi」名称与标识相关权益由作者保留。
- 产品需求文档：docs/PRD/v1.md
- 技术设计文档：docs/DESIGN/v1.md
- 用户使用文档：官网文档（或仓库
landing/docs.html） - 项目指引（给 AI 协作者）：CLAUDE.md