How OpenWhispr/openwhispr Works

核心听写流程（本地处理）

此流程是用户最核心、最高频的使用场景，体现了产品“即时、私密、高效”的核心价值。用户在处理敏感信息或网络不佳时，通过全局热键唤醒应用，进行语音输入。整个过程从音频捕获到文本输出完全在本地设备完成，语音数据不会上传到任何云端服务器，确保了隐私安全。最终，转录完成的文本会自动粘贴到用户当前工作的应用程序中，实现无缝的工作流整合，并自动存入本地历史记录以备查阅。

1. 用户按下全局热键，触发录音
2. 系统捕获麦克风音频，并通过音效和UI动画给予反馈
3. 用户再次按下热键，停止录音
4. 系统路由音频至本地引擎（如Whisper.cpp）进行转录
5. 转录结果自动粘贴到当前光标位置，并保存到本地历史记录

AI指令处理流程（云端）

此流程展示了产品从“听写工具”到“AI助手”的能力跃迁。用户在完成一段听写后，可以紧接着通过自然语言（如“嘿 贾维斯，总结一下”）调用强大的云端大语言模型对文本进行二次处理。系统会自动识别指令意图，将文本和指令发送给用户配置的AI服务（如OpenAI GPT-4），并将处理后的结果返回并粘贴。这极大地扩展了产品的应用场景，使其能够胜任起草邮件、整理纪要、润色文稿等更复杂的任务。

1. 用户进行一次常规听写，内容为“会议要点是...”
2. 用户紧接着说出AI指令：“嘿 贾维斯，把这些整理成项目列表”
3. 系统识别到“嘿 贾维斯”唤醒词，判定为AI指令
4. 系统调用配置的云端AI引擎（如Claude）处理文本和指令
5. AI返回格式化后的项目列表，并自动粘贴替换原始内容

新用户注册并开通云服务

该流程描绘了一个新用户如何从零开始注册账户、体验并最终付费订阅云服务。它始于用户决定使用需要联网的云端AI功能，系统会引导其通过Google或邮箱进行注册。登录后，用户将获得一定额度的免费用量和限时Pro版试用。当用量耗尽或试用期结束，系统会清晰地展示升级选项，并引导用户通过集成的Stripe支付页面完成订阅。这套闭环的商业化流程，是产品实现可持续发展的关键。

1. 用户在设置中选择“OpenWhispr Cloud”模式，UI提示需要登录
2. 用户选择“使用Google登录”，在系统浏览器中完成授权
3. 应用通过自定义协议被唤醒，自动完成登录，会话刷新机制确保登录状态稳定
4. 用户开始使用云端听写，系统后台记录用量。当用量耗尽时，UI弹出升级提示
5. 用户点击“升级”，跳转到Stripe支付页面完成Pro版订阅

配置和管理本地模型

此流程服务于希望完全离线使用或自定义AI能力的高级用户。用户可以在控制面板的模型市场中，浏览所有支持的本地语音识别或语言模型。他们可以根据自己的硬件配置和需求（例如，追求速度选择小模型，追求质量选择大模型），一键下载所需模型。下载过程提供实时进度反馈，且下载后的模型可以随时被激活使用或删除以释放磁盘空间。这个流程让普通用户也能轻松驾驭复杂的本地AI模型，是产品“隐私优先”和“高度可定制”理念的具体体现。

1. 用户进入“控制面板”的“模型管理”页面
2. 用户在模型列表中选择一个未下载的模型（如whisper-base），点击“下载”
3. 系统开始下载模型，UI实时显示进度。下载完成后自动安装
4. 用户进入“设置”页面，在“本地处理”选项中，激活刚刚下载的whisper-base模型
5. 用户后续使用本地听写时，将默认使用新配置的whisper-base模型

核心听写引擎

该模块构成了产品的核心用户体验闭环。它提供一个可悬浮、可拖动、自动显隐的极简听写面板，用户通过全局热键随时唤起。系统负责从麦克风采集音频，根据用户选择将音频送至本地或云端引擎进行转录，最后将文本结果自动粘贴到光标所在位置，并存入本地历史记录。整个过程配有音效提示，旨在提供“即按即说、即松即得”的无缝听写体验。

• 全局热键激活与听写模式 — 【用户价值】让用户在任何应用中都能一键启动或停止听写，无需切换窗口或点击鼠标，实现真正的全局可用性。 【设计策略】采用“分层+原生”的热键注册策略，兼容多操作系统特性。提供“点按切换”和“按住说话”两种模式，满足不同用户习惯。 【业务逻辑】 - **1. 模式选择**：用户可在设置中选择“点按模式”（Tap Mode）或“按住模式”（Push Mode）。 - **2. 热键注册**： - **默认热键**：macOS为`Fn/Globe`键，Windows/Linux为`Control+Super`。 - **跨平台策略**：优先使用原生二进制工具（Swift for macOS Globe key, C for Windows低级键盘钩子）实现对特殊键和“按住”模式的精确检测（包括按键抬起事件）。对于标准组合键，则使用Electron的`globalShortcut` API。在GNOME Wayland环境下，通过D-Bus注册系统级快捷键。 - **冲突处理**：当首选热键注册失败时（例如被系统或其他应用占用），系统会向用户推荐备用热键（如`F8`, `F9`），并引导用户重新设置。 - **3. 交互逻辑**： - **点按模式**：第一次按下热键开始录音，第二次按下停止录音并开始处理。 - **按住模式**：按住热键时持续录音，松开按键后立即停止录音并开始处理。为防止误触，设置了150毫秒的最短按住时间。为防止意外长时间录音，单次录音最长不超过5分钟。 - **4. 防抖与冷却**：注册的热键有150毫秒的防抖，防止快速连按。录音停止后有300毫秒的冷却时间，防止立即意外重启。
• 极简悬浮听写面板 — 【用户价值】在不干扰当前工作的情况下，提供一个直观、轻量、即时响应的听写状态指示器。 【设计策略】采用一个无边框、可拖拽的“ हमेशा-on-top”窗口，并根据听写状态和用户交互动态调整其大小、交互性和可见性。 【业务逻辑】 - **1. 状态机驱动视觉**：面板UI根据4种核心状态变化： - **空闲 (Idle)**：显示待机图标。 - **悬停 (Hover)**：光标悬停时，图标变化并显示取消按钮（如果正在录音或处理中）。 - **录音中 (Recording)**：显示录音动画（如跳动的点）和脉冲边框。 - **处理中 (Processing)**：显示处理动画（如声波指示器），且按钮不可点击。 - **2. 自动隐藏**：用户可开启“自动隐藏”功能。当满足“未录音、未处理、无弹出消息”的条件时，面板会在延迟500毫秒后自动隐藏。任何状态变化（如开始录音、弹出提示）都会中断隐藏计时，确保关键信息不被错过。 - **3. 拖拽移动**：用户可以按住面板拖动到屏幕任意位置。为防止误操作，拖动超过5像素才被识别为拖拽行为，否则视为单击。程序会自动确保面板不会被拖出屏幕边界。 - **4. 动态交互性**：默认情况下，面板“忽略”鼠标点击，允许用户操作面板下方的应用。仅当用户悬停在面板上、或有菜单/弹窗出现时，面板才变为可交互，接收点击事件。
• 智能文本粘贴 — 【用户价值】将转录完成的文本自动、准确地粘贴到用户当前工作的应用和光标位置，省去手动复制粘贴的步骤。 【设计策略】构建一个跨平台的粘贴管理器，它能识别目标应用的类型（尤其是终端），并采用最优的粘贴策略（原生二进制工具 > 系统脚本 > 标准剪贴板API），同时提供明确的失败指引。 【业务逻辑】 - **1. 优先级策略**： - **macOS**：优先使用定制的Swift原生二进制工具(`macos-fast-paste`)，利用辅助功能API进行粘贴，延迟约120毫秒。失败则回退到AppleScript。 - **Windows**：优先使用捆绑的`nircmd.exe`工具模拟键盘输入，延迟10毫秒。失败则回退到PowerShell脚本。 - **Linux**：自动检测桌面环境。在Wayland下使用`wl-copy`，在X11下使用`xdotool`。最终回退方案是标准的`navigator.clipboard`API。 - **2. 终端环境识别**：在Windows和Linux上，粘贴工具能识别当前活动窗口是否为终端模拟器（如Windows Terminal, Alacritty, GNOME Terminal等）。如果是，则自动模拟`Ctrl+Shift+V`进行粘贴，而非标准的`Ctrl+V`。 - **3. 权限与错误处理**： - 如果因缺少辅助功能权限导致粘贴失败，系统会弹出明确提示，引导用户前往系统设置开启权限。 - 权限状态会被缓存（允许状态缓存24小时，拒绝状态缓存5秒），避免重复打扰用户。 - 即使自动粘贴失败，文本也始终会被复制到系统剪贴板，用户可以手动粘贴作为最后的保障。
• 听写状态音效提示 — 【用户价值】为听写开始和结束提供非视觉的音频反馈，让用户在不看屏幕的情况下也能确认操作成功，提升盲操作的信心和效率。 【设计策略】使用Web Audio API生成两种简短、悦耳的提示音，分别对应录音开始和结束。音调和增益经过精心设计，以确保清晰可辨且不刺耳。 【业务逻辑】 - **1. 触发时机**：成功开始录音时播放“开始”提示音，成功停止录音时播放“结束”提示音。 - **2. 音效设计**： - **开始音**：播放两个连续的上升音符（C5 -> E5）。 - **结束音**：播放两个连续的下降音符（D5 -> A4）。 - **3. 技术实现**：每个音符时长90毫秒，并带有15毫秒的攻击包络，以避免产生突兀的爆音。用户可以在设置中关闭此功能。

多引擎处理与AI能力

这是产品的“大脑”，负责执行语音转文本（STT）和后续的AI文本处理。其核心设计在于高度的灵活性和可扩展性，允许用户在多种处理引擎之间自由选择，以平衡隐私、速度、成本和功能强大性。用户既可以选择完全离线的本地引擎，也可以接入多种主流云端AI服务。

• 混合式语音识别引擎路由 — 【用户价值】让用户根据不同场景需求，自由选择最合适的语音识别方案：追求隐私和零成本时使用本地模式，追求最高准确率或特定语种支持时使用云端模式。 【设计策略】设计一个基于用户配置的动态路由机制。在音频处理流程的入口，根据用户的设置（如“使用本地Whisper”、“云端转录模式”）决定将音频数据分发给哪个后端引擎。 【业务逻辑】 - **1. 引擎选项**：用户可在设置中选择： - **本地引擎**： - **Whisper.cpp**：高性能C++版Whisper，提供从`tiny`到`large`的多种模型，平衡速度与质量。 - **NVIDIA Parakeet**：基于sherpa-onnx，为NVIDIA GPU优化，提供极快的转录速度。 - **云端引擎**： - **OpenWhispr Cloud**：官方提供的集成云服务。 - **自带密钥(BYOK)**：支持用户填入自己的OpenAI、Groq、Mistral等API密钥。 - **流式识别**：支持Deepgram和AssemblyAI，实现低延迟实时反馈。 - **2. 路由逻辑**：当录音结束后，系统会检查用户的配置，按顺序决策： - Step 1: 如果“使用本地处理”开启，则根据选择的本地引擎（Whisper或Parakeet）将音频文件发送给本地服务进程。 - Step 2: 如果使用云端模式，则根据选择的云服务商（OpenWhispr官方、BYOK等）将音频数据（经过优化压缩）发送到相应的API端点。 - **3. 智能回退**：用户可选择开启“本地失败时自动回退到OpenAI”功能。当本地引擎处理失败或返回无意义结果（如静音标识）时，系统会自动使用OpenAI API重试一次，提升了识别的成功率。
• AI智能指令识别与处理 — 【用户价值】将听写工具从单纯的“打字机”升级为“AI助手”，用户可以通过自然语言指令，对听写内容进行格式化、改写、总结等二次处理。 【设计策略】通过“唤醒词”（代理名称）机制区分普通听写和AI指令。一旦识别到指令，就调用一个可插拔的、支持多供应商的AI推理服务来执行任务。 【业务逻辑】 - **1. 代理命名**：首次使用时，用户需要为AI助手设定一个名字（如“贾维斯”、“星期五”）。 - **2. 指令识别**：在每次转录完成后，系统会检查文本是否以“嘿 [代理名称]”或类似格式开头。 - **是**：判定为AI指令。系统会剥离唤醒词，将剩余部分作为指令和上下文，传递给AI推理模块。 - **否**：判定为普通听写，直接输出转录文本。 - **3. 多供应商推理**：用户可以配置使用哪个大语言模型来处理指令： - **云端**：OpenAI (GPT系列), Anthropic (Claude系列), Google (Gemini系列), Groq (Llama/Mixtral)。 - **本地**：支持通过llama.cpp运行的本地模型（如Qwen, LLaMA, Mistral）。 - **4. 指令示例**： - “嘿 贾维斯，把刚才说的内容整理成要点列表。” - “嘿 贾维斯，将这段话的语气改得更专业一些。” - **5. 结果交付**：AI处理完成后的文本，会替换原始听写内容，并自动粘贴到光标位置。
• 自定义词典 — 【用户价值】解决语音识别中常见的人名、地名、技术术语或品牌名识别不准的问题，显著提升特定领域听写的准确率。 【设计策略】提供一个简单的界面，让用户可以添加自定义词汇。在调用语音识别引擎时，将这些词汇作为“上下文提示”一同提交，引导模型向正确的结果上偏置。 【业务逻辑】 - **1. 添加词汇**：用户在设置的“自定义词典”页面，可以添加或删除单词、短语。例如“Sergey”、“Kubernetes”、“OpenWhispr”。 - **2. 应用机制**：当进行语音转录时，无论使用本地还是云端引擎，系统都会将完整的自定义词典列表作为额外参数（通常是`prompt`或`context`）提交给语音识别模型。 - **3. 效果**：模型在解码时会更倾向于生成在自定义词典中出现过的词汇，从而有效纠正冷门词或特定术语的识别错误。
• 低延迟流式听写 — 【用户价值】在用户说话的同时，实时显示转录结果，提供即时反馈，极大降低了长段落听写的心理等待成本，适合会议记录、实时字幕等场景。 【设计策略】采用专用的流式语音识别服务（如Deepgram），并建立一个包含连接预热、断线重连和批处理回退的复杂管道，以确保低延迟和高可用性。 【业务逻辑】 - **1. 连接预热 (Warmup)**：为了消除首次连接的延迟，系统会在空闲时提前与流式服务提供商建立一个“热”WebSocket连接，并每隔8秒发送一个静音数据包来维持连接活性。 - **2. 开始录音**：当用户开始以流式模式录音时，系统会立即采用这个“热”连接。音频数据通过`AudioWorklet`以16kHz的PCM格式实时捕获并发送。 - **3. 实时反馈**：服务器会实时返回中间和最终的转录结果，UI同步更新显示的文本。 - **4. 容错与回退**： - **冷启动缓冲**：如果在建立连接时用户已开始说话，音频数据会被临时缓冲，连接成功后立即发送，避免数据丢失。 - **批处理回退**：系统在流式录音的同时，也会在本地进行一次完整的录音。如果流式会话结束时没有返回任何有效文本（例如网络中断），系统会自动将本地录制的完整音频发送到常规的云端批处理API进行转录，确保用户输入不丢失。

云服务与商业化体系

该模块为OpenWhispr提供了可选的云端增值服务和商业化能力。它基于Neon Auth构建了一套完整的账户系统，支持多种登录方式，并集成了Stripe用于处理订阅和支付。用户通过免费账户即可体验云服务，并通过付费升级解除用量限制，这为开源项目探索了可持续盈利的模式。

• 多模式账户系统 — 【用户价值】用户可以选择用自己熟悉的谷歌账户快速登录，或使用传统的邮箱密码方式注册，同时支持密码找回，保障了账户的可访问性和安全性。 【设计策略】集成Neon Auth SDK，并针对Electron桌面应用的特性优化了OAuth流程。通过外部浏览器完成认证，再利用自定义协议（Deep Link）将认证结果安全地传回应用。 【业务逻辑】 - **1. 登录方式**： - **Google OAuth**：点击后，应用会调用系统默认浏览器打开Google的授权页面。授权成功后，浏览器通过`openwhispr://`自定义协议链接唤醒应用，并传递认证令牌。 - **邮箱/密码**：传统的注册和登录流程，包含邮箱格式验证和邮件发送验证。 - **2. 密码找回**：用户输入邮箱后，系统会发送一封包含重置链接的邮件。点击链接会打开应用并跳转到密码重置界面，用户输入新密码即可完成重置。 - **3. 会话管理**：登录成功后，会话信息（Cookies）保存在Electron的会话存储中。所有后续的云端API请求都会自动携带这些Cookies进行鉴权。
• 分层订阅与用量管理 — 【用户价值】提供明确的免费和付费权益，让用户可以无门槛试用云服务，并根据自己的用量需求决定是否付费升级，同时清晰地展示当前用量和剩余额度。 【设计策略】采用经典的免费增值（Freemium）模型，通过后端API管理用量额度，客户端定期查询并根据用量情况引导用户升级。 【业务逻辑】 - **1. 订阅层级**： - **免费版 (Free)**：每周提供2,000单词的云端转录额度。新用户注册后自动获得7天的Pro版免费试用。 - **专业版 (Pro)**：提供无限制的云端转录额度。 - **2. 用量跟踪与提醒**： - 应用会定期向云端API查询当前用户的已用单词数和总额度。 - 当用量达到总额度的80%时，UI会显示“接近限额”的提示。 - 当用量超过100%时，云端服务会拒绝新的转录请求，并返回“超出限额”的错误，UI会弹出升级提示。 - **3. 状态缓存**：为避免频繁请求，用量数据在客户端会缓存1小时。
• Stripe支付与账单管理集成 — 【用户价值】提供一站式的升级和账单管理体验。用户可以直接在应用内发起升级，并跳转到安全的Stripe页面完成支付或管理自己的订阅信息（如更换信用卡、查看历史账单）。 【设计策略】客户端不直接与Stripe交互，而是通过调用后端API获取一次性的Stripe Checkout（支付）或Billing Portal（账单中心）链接，然后在浏览器中打开，确保了支付流程的安全合规。 【业务逻辑】 - **1. 升级流程**：用户在应用内点击“升级”按钮，应用会向后端`/api/stripe/checkout`接口发起请求。后端生成一个Stripe Checkout会话链接并返回，应用随即在外部浏览器中打开此链接，用户完成支付。 - **2. 账单管理**：用户在设置中点击“管理账单”，应用会请求后端的`/api/stripe/portal`接口，获取一个Stripe Billing Portal的会话链接，用户可以在打开的页面中管理自己的订阅和支付方式。 - **3. 支付状态处理**：如果用户的Pro订阅支付失败（如信用卡过期），用量查询接口会返回`past_due`状态，UI会显示相应提示并引导用户进入账单管理页面解决问题。 - **4. 并发控制**：为防止用户重复点击，在打开一个Stripe链接后，短时间内会锁定按钮，避免发起多个支付或管理会话。
• 会话刷新与重试机制 — 【用户价值】提升云端功能的稳定性。即使用户长时间挂机导致会话过期，或刚完成OAuth登录网络有延迟，应用也能自动尝试恢复会话，避免不必要的操作失败和重新登录。 【设计策略】通过一个高阶函数`withSessionRefresh`包裹所有需要鉴权的云端API调用。该函数能捕获特定的认证失败错误，并根据情况自动执行会话刷新或延时重试。 【业务逻辑】 - **1. 错误捕获**：所有API调用被包裹。如果API返回认证失败错误（如HTTP 401或特定的错误码`AUTH_EXPIRED`），则触发恢复逻辑。 - **2. 刷新策略**： - **常规刷新**：对于普通会话过期，系统会尝试调用Neon Auth的`getSession()`方法静默刷新一次会话。如果刷新后仍然未登录，则判定为真正登出，并引导用户重新登录。 - **3. 登录宽限期重试**： - **场景**：特别针对刚完成OAuth登录的场景，由于网络和重定向延迟，客户端SDK可能还未完全同步会话。 - **策略**：在登录后的60秒“宽限期”内，如果发生认证失败，系统不会立即放弃，而是会进行最多6次的重试，重试间隔采用指数退避策略（从500毫秒开始，每次翻倍），以等待会话最终建立。

配置与管理中心

这是产品的“神经中枢”，为用户提供了一个统一的图形化界面来管理应用的所有方面。用户可以在这里配置API密钥、管理和下载本地AI模型、回顾和检索听写历史、自定义热键和AI指令等。它将复杂的配置项和强大的功能以直观、易于操作的方式呈现给用户。

• 本地AI模型管理器 — 【用户价值】让非技术用户也能轻松地为本地处理模式下载、管理和删除不同大小和类型的AI模型，实现离线使用和个性化配置。 【设计策略】提供一个卡片式的模型市场界面。通过一个状态管理器协调模型的下载、安装和删除过程，提供清晰的进度反馈，并防止并发下载引发的冲突。 【业务逻辑】 - **1. 模型展示**：在“模型”页面以卡片列表形式展示所有支持的本地模型（如Whisper的tiny, base, small等），并标注模型大小、状态（未下载、已下载、下载中）。 - **2. 下载流程**： - 用户点击“下载”后，系统开始从指定的GitHub Releases地址下载模型文件。 - UI上会实时显示下载进度条、速度和预计剩余时间。 - **并发控制**：系统只允许同时下载一个模型。如果用户在A模型下载过程中尝试下载B模型，系统会弹出提示并阻止操作。 - **断点续传**：不支持。下载失败需要从头开始。 - **3. 安装与删除**： - 模型文件会先下载到临时目录，下载完成后再移动到正式的模型缓存目录(`~/.cache/openwhispr/models`)。 - 如果下载的是压缩包，系统会自动完成解压。 - 用户可以随时点击“删除”按钮一键清除已下载的模型文件，释放磁盘空间。 - **4. 错误处理**：下载或解压失败时，UI会显示明确的错误信息（如“网络超时”、“磁盘空间不足”、“解压失败”）。
• 听写历史记录 — 【用户价值】自动保存每一次的听写结果，用户可以随时回顾、复制或删除历史记录，确保重要信息不会因粘贴失败或误操作而丢失。 【设计策略】使用本地SQLite数据库持久化存储所有转录文本。在UI层面，采用一个与数据库同步的内存缓存来快速展示最近的记录，保证界面的响应速度。 【业务逻辑】 - **1. 自动保存**：每次转录成功后，文本内容、时间戳等信息会自动保存到本地的`transcriptions.db`数据库文件中。 - **2. 历史展示**：在控制面板的“历史”标签页中，按时间倒序展示所有听写记录。为性能考虑，默认加载最近的50条记录。 - **3. 交互操作**：用户可以对单条记录进行操作： - **复制**：一键将文本复制到剪贴板。 - **删除**：从数据库中永久删除该条记录。 - **清空**：提供一键清空所有历史记录的功能。 - **4. 数据同步**：UI展示的数据源于一个内存中的`transcriptionStore`。该Store通过Electron的IPC机制与主进程的数据库操作保持同步。例如，当一次新的听写被保存到数据库后，主进程会广播一个`transcription-added`事件，内存Store收到后会更新自身，从而触发UI刷新。
• AI指令工作室 (Prompt Studio) — 【用户价值】为高级用户提供一个无需修改代码即可调试和自定义AI指令（Prompts）的强大工具，让用户可以根据个人需求定制AI的输出风格和行为。 【设计策略】提供一个集编辑、测试、保存于一体的界面。用户修改后的Prompt保存在本地存储中，测试功能则直接调用AI推理服务，形成快速的“编辑-测试”迭代闭环。 【业务逻辑】 - **1. Prompt编辑**：用户可以在一个文本区域内编辑系统的“统一Prompt”或自定义的特定任务Prompt。 - **2. 一键测试**： - 用户输入一段测试文本，点击“测试”按钮。 - 系统会读取用户当前的AI引擎配置（如使用OpenAI GPT-4、本地Llama等），并使用编辑器中当前的Prompt内容来调用AI推理服务。 - AI返回的结果会直接显示在界面上，供用户评估效果。 - **3. 保存与持久化**：用户满意的Prompt可以被保存。系统会将Prompt内容以JSON格式存储在浏览器的LocalStorage中。下次进行AI推理时，会优先使用用户保存的自定义Prompt。 - **4. 安全性**：为了防止测试时意外覆盖用户的稳定版Prompt，测试功能会先临时保存用户当前的Prompt，测试后再恢复。

跨平台桌面应用框架

这是构建OpenWhispr桌面应用的底层基础。它基于Electron框架，处理应用的生命周期、窗口管理、进程间通信（IPC）、自动更新以及与操作系统的深度集成。该模块的目标是屏蔽各操作系统间的差异，为上层功能提供一个稳定、安全、高效的运行环境，并确保应用在macOS、Windows和Linux上都能有一致且可靠的表现。

• 统一应用入口与单实例锁定 — 【用户价值】确保用户在任何时候都只运行一个OpenWhispr实例，避免资源浪费和状态冲突。同时，支持通过自定义URL协议（如处理OAuth回调）来唤醒和与正在运行的应用进行通信。 【设计策略】在应用启动的最开始阶段，通过`requestSingleInstanceLock`获取一个系统级的锁。如果获取失败，则判定为已有实例在运行，并将启动参数（如URL）传递给已有实例后退出。 【业务逻辑】 - **1. 启动锁定**：应用启动时立即尝试获取单实例锁。如果成功，则继续正常初始化；如果失败，则将命令行参数（特别是以`openwhispr://`开头的URL）发送给第一个实例，然后当前进程立即退出。 - **2. 协议处理**：应用注册了`openwhispr://`作为自定义协议。当用户在浏览器中点击此类链接（如OAuth登录成功后的回调），操作系统会唤醒OpenWhispr应用，并将该URL作为启动参数传入。 - **3. 跨平台隔离**：为了方便开发和测试，开发版、预览版和正式版会使用不同的应用数据路径（`userData`）和协议名称（如`openwhispr-dev://`），实现环境间的安全隔离。
• 双窗口架构 — 【用户价值】将核心的听写功能与复杂的设置管理功能分离到两个独立的窗口中，既保证了听写操作的轻量、无干扰，又提供了功能全面的管理后台。 【设计策略】创建两个不同配置的Electron `BrowserWindow`实例，它们共享同一套React前端代码，通过URL的查询参数来决定渲染哪个界面。 【业务逻辑】 - **1. 听写面板窗口 (mainWindow)**： - **配置**：无边框、背景透明、始终置顶、任务栏中不可见。 - **用途**：专用于显示悬浮的听写图标，提供最核心的交互。 - **2. 控制面板窗口 (controlPanelWindow)**： - **配置**：标准的带标题栏和边框的窗口，在任务栏中可见。 - **用途**：承载设置、历史记录、模型管理等所有复杂UI。 - **3. 代码复用**：两个窗口都加载相同的HTML文件。通过在URL中附加不同的参数（例如`/`用于听写面板，`/?panel=true`用于控制面板），React应用路由到不同的顶层组件进行渲染。
• 安全进程间通信(IPC)桥 — 【用户价值】在保证安全的前提下，让运行在沙箱环境中的UI界面（渲染进程）能够调用主进程提供的系统级功能（如读写文件、操作数据库、调用原生模块）。 【设计策略】采用Electron推荐的`contextBridge`模式，在预加载脚本（preload.js）中定义一个明确的API对象（`electronAPI`），并将其安全地暴露给渲染进程的`window`对象。所有敏感操作都在主进程中实现，通过IPC通道响应来自渲染进程的调用。 【业务逻辑】 - **1. API契约**：定义了一个包含超过100个方法的`electronAPI`对象，涵盖了窗口管理、数据库操作、剪贴板、本地/云端转录、设置读写、系统信息查询等所有需要原生能力的功能。 - **2. 安全边界**：渲染进程只能调用`electronAPI`上暴露的方法，无法直接访问Node.js或Electron主进程的任何其他模块，有效防止了潜在的XSS攻击升级为远程代码执行。 - **3. 调用流程**：当UI需要执行一个原生操作时（如保存转录），它会调用`window.electronAPI.saveTranscription(text)`。这个调用通过`contextBridge`被路由到主进程的`ipcMain.handle('db-save-transcription', ...)`处理器，执行完毕后再将结果返回给UI。
• 应用卸载与缓存清理 — 【用户价值】当用户卸载应用时，能够干净、彻底地移除所有相关文件，包括下载的AI模型等大文件，避免留下垃圾文件占用大量磁盘空间。 【设计策略】利用不同平台安装包的特性，在卸载流程中执行自定义的清理脚本。 【业务逻辑】 - **1. Windows (NSIS 安装包)**：在NSIS卸载脚本中，集成了一个宏命令，用于删除用户的模型缓存目录（`%USERPROFILE%\.cache\openwhispr`）。 - **2. Linux (deb/rpm 包)**：在包的`post-uninstall`脚本中，执行`rm -rf`命令来清理用户主目录下的缓存文件夹（`$HOME/.cache/openwhispr`）。 - **3. macOS**：虽然macOS没有标准的卸载钩子，但应用内提供了“移除已下载模型”的按钮，让用户可以在卸载前手动清理。 - **4. 统一清理入口**：应用内“设置”->“通用”->“本地模型存储”下也提供了一个“移除已下载的模型”按钮，作为跨平台的统一手动清理入口。

平台原生级系统集成引擎

Problem: 如何让一个基于Web技术（Electron）的应用，在不同操作系统上都能实现可靠的系统级交互（如全局热键、后台粘贴），从而提供与原生应用无异的流畅体验？标准Electron API在处理特殊按键（如macOS Globe键）、Wayland快捷键以及向终端粘贴文本时存在诸多限制。

Solution: 该方案采用“分层+专有”的策略，为每个平台的特性定制解决方案： - **Step 1: 全局热键分层处理**：以Electron的`globalShortcut`为基础，覆盖大部分标准组合键。对于特殊情况，则调用原生代码：在macOS上，编译一个独立的Swift程序来监听`Fn/Globe`键的按下和抬起；在Windows上，用C语言编写一个使用低级键盘钩子的程序来实现可靠的“按住说话”；在GNOME Wayland上，则通过D-Bus接口注册系统级快捷键。 - **Step 2: 智能粘贴上下文感知**：创建一个原生的粘贴辅助程序，它在执行粘贴前会先检测当前活动窗口的类型。如果识别出是终端（如Windows Terminal、Alacritty等），就自动发送`Ctrl+Shift+V`，否则发送常规的`Ctrl+V`。 - **Step 3: 多策略粘贴回退**：为每个平台建立一个包含多种粘贴方式的优先级列表。例如，在Windows上优先尝试捆绑的`nircmd.exe`，失败则回退到执行PowerShell脚本，确保在各种环境下都能成功粘贴。

Technologies: Native Binaries (Swift, C), Electron globalShortcut, D-Bus (Linux), Low-level Keyboard Hooks (Windows), AppleScript, nircmd

Boundaries & Risks: 该方案高度依赖于平台特性和外部工具。开发者在没有安装相应编译环境（如Xcode、MSVC）的机器上构建项目时，原生辅助程序可能编译失败，导致部分高级功能（如按住说话）降级或不可用。在用户的系统上，如果连回退所需的工具（如`xdotool`）都没有安装，粘贴功能可能会彻底失效。

混合式多引擎处理管道

Problem: 如何在单一产品中同时满足用户对“极致隐私”和“顶尖性能”的矛盾需求？用户既希望能在离线时安全地处理敏感语音，又希望能随时调用云端最强大的AI模型来获取最佳识别效果或执行复杂指令。

Solution: 该方案构建了一个可动态路由的“处理管道”，核心思路是在任务执行前基于用户配置进行决策： - **Step 1: 用户配置中心化**：将所有引擎选择（如“使用本地Whisper”、“云端AI模型提供商”）集中在统一的设置中，作为路由决策的唯一依据。 - **Step 2: 入口动态路由**：在音频或文本处理任务的入口，设计一个路由函数。该函数首先检查“是否启用本地模式”的开关。如果开启，则将任务分发给本地服务进程（如Whisper.cpp Server）；如果关闭，则根据具体的云端服务商配置，将任务打包并发送到对应的云API。 - **Step 3: 容错回退机制**：为本地处理模式设计一个可选的“云端回退”开关。当本地引擎处理失败或效果不佳（例如，识别结果是完全静音），如果此开关打开，系统会自动捕获失败状态，并使用预设的云端引擎（如OpenAI）对原始任务进行重试，从而在保障隐私优先的同时提升整体成功率。

Technologies: Whisper.cpp, sherpa-onnx (NVIDIA Parakeet), llama.cpp, Cloud APIs (OpenAI, Deepgram, Groq), Dynamic Routing

Boundaries & Risks: 灵活性带来了配置的复杂性，用户可能因为不理解各类引擎的差异而做出次优选择。本地模型需要用户自行下载和管理，占用大量磁盘空间，且对硬件有一定要求。云端回退机制可能在用户不知情的情况下产生API调用费用，需要有清晰的UI提示和授权。

韧性云会话管理框架

Problem: 桌面应用通常会长时间运行，而云服务的会话（Session）是短暂的，如何处理这种生命周期不匹配导致的用户认证频繁失效问题？特别是在OAuth登录后的瞬间，网络延迟可能导致客户端的登录状态与实际不符，造成操作失败。

Solution: 此框架通过一个名为`withSessionRefresh`的高阶函数（装饰器）来包裹所有需要认证的云端API调用，实现自动化的会话恢复： - **Step 1: 捕获认证错误**：该函数会监控其包裹的API调用的返回结果。一旦捕获到特定的认证失败错误（如HTTP 401），它会阻止错误立即抛给用户，并启动内部的恢复逻辑。 - **Step 2: 静默会话刷新**：在常规情况下，它会尝试调用认证服务提供商（Neon Auth）的“刷新会话”接口。如果刷新成功，它会使用新的会话凭证自动重试刚才失败的API调用。整个过程对用户是透明的。 - **Step 3: 登录宽限期指数退避**：特别地，如果在用户刚登录后的60秒“宽限期”内发生认证失败，系统会认为这很可能是网络延迟所致。此时它不会立即放弃，而是会以指数退避的方式（500ms, 1s, 2s...）进行最多6次重试，以等待最终的会话同步完成。

Technologies: Session Token Refresh, Exponential Backoff Retry, Stateful Wrappers (Higher-Order Functions)

Boundaries & Risks: 该框架依赖于API返回明确且一致的认证失败错误码。如果后端API在认证失败时返回了通用的错误（如HTTP 500），框架将无法触发恢复逻辑。指数退避重试会增加操作的最终响应时间，在网络极差的情况下，用户可能会感到明显的卡顿。

自动化跨平台构建与分发系统

Problem: 如何将一个包含原生代码（C, Swift）、需要下载大型AI模型、且面向三大操作系统（macOS, Windows, Linux）的复杂应用，可靠地打包成分发给最终用户的一键安装包？手动处理编译、签名、公证和打包极其繁琐且容易出错。

Solution: 建立了一套全自动化的CI/CD流程，将复杂的构建过程脚本化： - **Step 1: 统一打包配置**：使用`electron-builder`作为核心打包工具，在一个配置文件(`electron-builder.json`)中定义所有平台的输出格式（如macOS的`.dmg`，Windows的`.exe`，Linux的`.deb`/`.rpm`/`AppImage`）、图标、应用元数据等。 - **Step 2: 依赖预处理脚本化**：在正式打包前，通过npm脚本链式执行一系列预处理任务。包括： - **原生助手编译**：为当前平台编译所需的C/Swift原生辅助程序。脚本会优先尝试从GitHub Releases下载预编译好的二进制文件，失败再尝试本地编译，再失败则带警告继续（功能降级），保证流水线不断裂。 - **AI模型二进制文件下载**：执行脚本从上游项目（如whisper.cpp）的GitHub Releases下载对应平台的AI引擎可执行文件。 - **Step 3: CI/CD自动化**：在GitHub Actions中定义工作流。当代码推送到特定分支或打上标签时，自动在云端的macOS、Windows、Linux虚拟环境中并行执行上述构建流程。流程中包含使用保存在Secrets中的证书进行代码签名和苹果公证的步骤。 - **Step 4: 自动发布**：构建和签名成功后，工作流会自动创建一个新的GitHub Release，并将所有平台的安装包作为附件上传，完成从代码到发布的全自动化。

Technologies: Electron Builder, GitHub Actions (CI/CD), Apple Notarization, Code Signing, NSIS (Windows), Shell Scripting

Boundaries & Risks: 此系统强依赖于GitHub Actions和上游项目的GitHub Releases。如果GitHub服务中断，或上游项目更改了其发布资产的命名或结构，下载脚本会失败，导致构建中断。代码签名和公证所需的证书和密钥需要严格的安全管理，泄露风险高。本地开发者若无完整的编译环境和证书，将无法复现官方的构建结果。