语音助手

语音助手（VoiceAssistant）

智能语音识别与自动化规则引擎

版本：20261008

一、项目简介

------------------------------------------------------------------------

语音助手是一款基于 C++ 开发的本地离线语音识别与自动化规则引擎。

程序持续监听麦克风，经 VAD（语音活动检测）自动切分语音段，交由

语音识别引擎转写为文本，再按用户自定义规则匹配并执行相应动作，

实现"说一句话即可完成系统操作"。

整条处理链路为：

    实时监听 -> VAD 分段 -> ASR 识别 -> 文本后处理 -> 规则匹配 -> 命令执行

全部识别与推理均在本机完成，语音与文本数据不出本地，兼顾隐私与低延迟；

同时以开放接口支持插件扩展与多引擎切换，可对接本地大模型与视觉模型。

二、系统架构

------------------------------------------------------------------------

工程按职责分层解耦为四个库，采用 CMake 多 target 构建：

  audio_engines   纯引擎库：VAD / ASR / 声纹 / 规则引擎 / 语音段累积

  platform        平台抽象层（PlatformCommands）：win32 / posix 双实现

  app             UI 应用壳（opengl_ui / GLFW）：语音控制 / 规则 / 声纹 /

                  设置 / 关于等页面

  cli             命令行工具：voice_cli（wav 识别）/

                  voice_cli_regress（回归自检）

设计要点：

  - 引擎层不依赖 UI 与 Win32，平台差异统一经 PlatformCommands 抽象，

    头文件不得 include <windows.h>，保证可移植与可测试。

  - 插件采用冻结的 C-ABI 契约（plugin_sdk.h，api_version=1），

    原生 DLL/so 动态加载，能力位声明与宿主解耦。

  - 关键接口冻结在 docs/CONTRACTS.md，变更需评审登记。

三、核心功能

------------------------------------------------------------------------

1. 实时语音控制与指令执行

   - VAD 自动分段，支持灵敏度 / 短 / 正常 / 长停顿等预设档位，

     空段与过短段（< 200ms）过滤。

   - 规则匹配后执行多种动作类型，含：

     shell / open / url / keys（按键、组合键）/ text（文本粘贴）/

     mouse（鼠标点击、移动、滚轮）/ powershell / script /

     volume（音量）/ mute（扬声器静音）/ brightness（亮度）/

     lock（锁屏）/ shutdown（关机）/ hibernate（休眠）等。

   - 支持多行命令、延迟、匹配次数重复（*N）与分号复合序列。

2. 普通转录

   - 停止转录后自动保存 transcript 文件（原文 + 译文），

     transcript_<时间戳>.txt，最长录音时长可配置、到点自动停止。

   - 识别结果可直接打印/粘贴到当前光标位置。

3. 声纹识别

   - 注册说话人、实时识别，可开启"仅注册人触发"命令，

     防止他人语音误触发。

4. 识别后处理

   - 文本正则化（数字/标点恢复、规则集）、短时重复去重、

     可选自动翻译（注入式，支持本地引擎）。

5. 规则管理

   - 编辑表单（名称 / 命令 / 类型 / 参数 / 备注 / 启停 / 优先级）、

     搜索、分页、双击编辑、JSON 导入导出。

   - 支持多规则集与模式映射（语音切换规则集）、正则规则、全局热键。

6. 网络监听与报告

   - 统一事件报告入口（三重门控 + 表级路由回退全局），

     TCP / HTTP 双协议；网络指令监听接收端按 JSON 分发执行。

7. 登录与插件市场

   - 登录状态本地持久化与两态界面；插件市场页支持预览、

     启停开关与详情配置。

四、插件生态

------------------------------------------------------------------------

基于开放 C-ABI 插件体系，当前内置四个插件：

  offline_tts               离线语音合成

    识别完成后将文本合成语音（Melo / Kokoro），依赖随插件分发。

    能力：command | panel

  va_translate              翻译转录

    本地离线翻译（默认内置 llama.cpp，可切换 Ollama）。

    能力：translate | panel

  va_text_translate         文本翻译

    文本 / 文件 / 文件夹三模式翻译，内置 llama.cpp 千问模型为默认

    后端，Ollama 可切换；批处理文档（txt / docx / pdf / epub / html）

    由宿主 Python 运行时执行。

    能力：text_translate | panel

  va_screenshot_translate   截图翻译

    截屏（整屏 / 活动窗口）后经视觉大模型 OCR 并本地翻译，

    支持 一步 / 两步 模式，OCR 引擎可在 vl / paddle 间切换。

    能力：command | panel

五、技术栈

------------------------------------------------------------------------

  语言 / 构建    C++ / CMake（Release / MD 运行时）

  语音识别       SenseVoiceSmall（阿里 FunASR，经 sherpa-onnx）

  音频处理       PortAudio、sherpa-onnx

  界面           opengl_ui / GLFW

  数据库         SQLite

  本地推理       llama.cpp（GGUF，含视觉 mmproj）、Ollama

  OCR            PaddleOCR（Python 共享运行时）

  脚本运行时     Python（随宿主精简分发，第三方依赖随插件 vendor）

六、技术特点

------------------------------------------------------------------------

  - 本地离线 / 隐私安全：识别、翻译、OCR 与合成均在本机完成，

    数据不出本地。

  - 多引擎可切换：翻译 / OCR 支持多个后端按需切换与回退。

  - 开放插件体系：冻结 C-ABI 契约，原生动态库加载，能力位声明。

  - 跨平台架构：平台差异抽象为 PlatformCommands，win32 / posix 双实现。

  - 工程质量门槛：CLI 回归自检 + 文档知识图谱（graphgen）0 错 0 警门禁。

七、系统要求

------------------------------------------------------------------------

  操作系统   Windows 10 x64 及以上

  内存       4GB 及以上

八、关于

------------------------------------------------------------------------

  软件名称   语音助手

  版本       20261008

  作者       研道人-江小东

  官网       https://3daoshan.com

  B 站主页   https://space.bilibili.com/3493128858241731

  邮箱       1719262421@qq.com

  版权信息   © 2026 研道人-江小东

  版权说明   本软件仅供学习交流使用。