Voquill 语音听写工具架构深度剖析：为什么“Rust是API，TypeScript是大脑”是最佳设计-平芜编程栈

【免费下载链接】voquill

Open source voice dictation technology

项目地址：https://gitcode.com/gh_mirrors/vo/voquill

🎙️ 本文深度剖析开源语音听写工具 Voquill 的桌面架构：它为什么坚持“Rust 只当 API、TypeScript 掌管大脑”，以及这套设计如何让一个跨平台语音输入工具既快又好维护。读完你会获得一份清晰的 Tauri 桌面应用分层指南。

Voquill 是一款开源的语音听写（voice dictation）工具：按住快捷键说话，松手后文字就直接“打”进你当前正在用的任何应用里——编辑器、浏览器、聊天软件，甚至还能让 AI 帮你润色措辞。它基于 Tauri 构建，由 Rust 原生层 + TypeScript/React 前端组成。

真正有趣的是它的架构哲学，官方在 docs/desktop-architecture.md 中只用一句话概括：

Rust is the API, TypeScript is the Brain.Rust 是 API，TypeScript 是大脑。

这句话说起来轻描淡写，但背后是一个相当反直觉的决策：明明 Rust 又强又快，为什么把所有业务逻辑都交给 TypeScript？下面拆开看。

先看 Voquill 能做什么：一个“无感”的系统级输入设备

理解架构前，先感受它的使用场景。Voquill 把自己伪装成一个“更快的键盘”：

🗣️ 系统级听写：全局热键触发录音，转录结果自动粘贴到光标所在处，无需切换窗口；
✨ AI 助手模式：对着 Finder 之类的应用口述，由 Agent 策略解析意图并执行动作，而不仅仅是转文字；
📚 本地/云端双模转录：可以用本地 Whisper（Rust sidecar 进程，支持 GPU），也可以调用 Deepgram、AssemblyAI、Azure、ElevenLabs 等云端服务；
🖥️ 全平台覆盖：macOS、Windows、Linux 的音频、热键、粘贴、悬浮窗（pill overlay）全部有原生实现。

注意最后一点：音频采集、全局热键、模拟粘贴、系统权限请求，这些恰恰是网页技术（前端）做不了的事，必须由 Rust 原生层完成。而“说话 → 决策 → 粘贴”这条链路上的所有判断——存不存、发给哪个模型、要不要 AI 润色、贴到哪个应用——又都是纯业务逻辑。

两类需求的分界线，就是“API / 大脑”分层的依据。

为什么不全用 Rust？三层职责一目了然

如果让 Rust 同时承担业务逻辑，就会遇到桌面应用最常见的痛点：

状态分裂：Rust 侧一份状态、TS 侧一份状态，两边同步是噩梦；
业务改动要重编 Rust：改一个“保存策略”都得等原生编译，开发循环从秒级退化到分钟级；
换后端要动两层：想从本地 SQLite 切到云同步，Rust 和 TS 都要改。

Voquill 的解法是给每一层“立军令状”，官方文档将其职责划得非常死（见 CLAUDE.md 中写明的项目铁律）：

层	技术栈	职责	禁止事项
Rust 层	`src-tauri/src/`	平台能力（音频/热键/托盘/粘贴）、SQLite 持久化、原生事件上报	❌ 不做任何业务决策
Tauri 命令	commands.rs	两层之间的 API 契约，共 114 个`#[tauri::command]`	只做“收参数 → 执行 → 返回”
TypeScript 层	`apps/desktop/src/`	全部状态（Zustand + Immer）、全部业务逻辑、UI 渲染	—

Rust 侧的命令函数刻意写得“呆”。以保存一条听写记录为例（commands.rs）：

pub async fn transcription_create( transcription: crate::domain::Transcription, database: State<'_, crate::state::OptionKeyDatabase>, ) -> Result<crate::domain::Transcription, String> { // 就是插入数据库，仅此而已 crate::db::transcription_queries::insert_transcription(database.pool(), &transcription).await .map_err(|err| err.to_string()) }

没有任何“该不该存”“存哪里”的判断——那些决策全部发生在 TypeScript 侧。

单向数据流：一次听写的完整旅程

所有数据沿同一条单向流水线流动，官方架构图（desktop-architecture.md）：

用户交互 / 原生事件 ↓ TypeScript 业务逻辑 ↓ Repo 层（决定走本地还是云端） ↓ Rust API（Tauri 命令） ↓ SQLite / 远程后端

对应到代码里，一次语音输入会经过 5 步：

原生事件：Rust 捕获到录音开始/停止、音量电平，通过 Tauri 事件系统抛出；
TS 接管：会话层（sessions/ 下有 Deepgram、AssemblyAI、本地 Whisper 等 7 种TranscriptionSession实现）收到文本片段，决定如何处理；
策略决策：strategies/ 中的DictationStrategy或AgentStrategy判断——要不要后处理、要不要过 AI、要不要落盘；
Repo 选择后端：调用getTranscriptionRepo()等方法，由工厂决定是Local*Repo还是Cloud*Repo；
Rust 执行：本地持久化时invoke("transcription_create")，Rust 写 SQLite 完事。

这种“事件只上报、决策都在上”的模式，让 Rust 层保持无状态——它更像一组忠实的“手脚”，而“大脑”（store/index.ts 中的全局 Zustand store）始终只有一个。

Repo 层：同一套大脑，随时换“存储器官”

这套架构最实际的收益体现在 repos/index.ts 的工厂函数上。每个数据域都有Base*Repo抽象接口 + 多个实现，运行时按需切换：

用户数据：未登录走本地，登录后切云端，企业版再走企业网关——isLoggedIn() ? new CloudUserRepo() : new LocalUserRepo()（repos/index.ts）；
写作风格（Tone）、词典（Term）：同样本地/云端/企业三态可切换；
文本生成：支持云模型、自建 API Key、Ollama 本地模型等多种模式。

上层业务代码只面向Base*Repo接口编程，完全不知道数据最终躺在本地 SQLite 还是云端。以会话仓库为例，TS 侧封装后发起命令（conversation.repo.ts）：

const created = await invoke<LocalConversation>("conversation_create", { conversation: toLocalConversation(conversation), }); return fromLocalConversation(created);

边界处的toLocalXxx()/fromLocalXxx()转换函数负责两种表示的互转，把 Rust 的数据结构锁死在桥的另一边。

Rust 的真正主场：平台能力与本地转录

把业务逻辑抽走后，Rust 层反而更聚焦，集中在三件事上：

① 平台差异抹平音频采集就是一个典型：platform/audio.rs 中，Linux 走 PulseAudio 实现，macOS/Windows 走 cpal，对外只暴露同一个Recorder接口。热键、模拟粘贴、屏幕区域获取也按platform/macos|windows|linux/分别实现。

② 数据持久化SQLite 查询按领域拆成 db/ 下的 12 个 query 模块，数据库迁移以NNN_description.sql规范存放在 db/migrations，新增 Tauri 命令的流程在 CLAUDE.md 中固化为三步：定义命令 → 注册 handler → 写 repo。

③ 本地 Whisper 的 sidecar 协作最复杂的本地转录能力被拆成了一个独立的 Rust sidecar 进程（packages/rust_transcription，支持模型下载、GPU 设备选择、流式会话）。TypeScript 侧的 sidecars/ 负责进程生命周期管理，LocalTranscriptionSession 则把 sidecar 的事件流编织进统一的转录会话体系——和 7 种云端方案共用同一套接口。

这套架构到底好在哪

回到开头的“为什么是最佳设计”，官方文档总结了五点，结合源码看全部成立：

🧠 单一事实来源：状态永远只在 TypeScript 的 Zustand store 里，Rust 不复制状态，从根上消灭了“两边不一致”；
⚡ 迭代速度：改业务逻辑只需 Vite 热更新，秒级生效，不用等 Rust 编译；
🧪 可测试性：核心逻辑是纯 TypeScript，可以直接用 vitest 测（如 new-server-transcription-session.test.ts），无需搭 Rust 环境；
🔀 后端弹性：本地 / 云 / 企业网关 / Ollama 私有模型，靠 Repo 工厂透明切换；
📐 边界清晰：114 个 Tauri 命令就是两层之间的全部契约，接口面小到一眼可查。

反过来说，如果哪天 Rust 层开始出现if 用户是付费会员就...这样的代码，就说明架构腐化了——CLAUDE.md 把这条规则写成了团队铁律，apps/desktop/CONTEXT.md 则连“三种语言配置”这类易混淆概念都做了显式区分，可见对“状态归属唯一”的执念。

想深入源码？从这几个入口开始

🏛️ 架构总纲：docs/desktop-architecture.md（含数据流图与分层职责）
📜 Rust ↔ TS 契约：apps/desktop/src-tauri/src/commands.rs（114 个命令定义）
🧩 后端切换工厂：apps/desktop/src/repos/index.ts
🎧 会话层（7 种转录方案）：apps/desktop/src/sessions/
🤖 策略层（听写 vs Agent）：apps/desktop/src/strategies/
💾 本地 Whisper sidecar：packages/rust_transcription

一句话总结：Voquill 的架构本质是“让每种语言只做它最擅长的事”——Rust 做系统的手脚，TypeScript 做思考的大脑，中间用一条薄而清晰的 Tauri 命令桥连接。对于正在做 Tauri（或 Electron）桌面应用的开发者来说，这套“Rust 无状态 API + 前端统一大脑”的分层方案，值得直接抄作业。