Feature Guide - zkwi/VoxType GitHub Wiki

Windows 语音输入功能特性与使用优化

本页面是 GitHub Wiki Feature-Guide 的仓库内草稿镜像，用于避免线上 Wiki 与仓库文档长期漂移。

本页说明 VoxType 的 Windows 语音输入、语音转文字、可选 ASR 服务、自动粘贴、剪贴板恢复和可选 LLM 润色能力。它不是配置字段大全，而是帮助用户理解“为什么这样设计”和“怎样用得更稳、更快”。

English version: Features and Usage Optimization

1. 核心工作流

VoxType 的主链路是：

触发录音 → 麦克风采集 → 当前 ASR 服务 → 可选 LLM 润色 → 写入剪贴板 → 自动粘贴 → 恢复剪贴板 → 统计与日志

主链路保护策略：

  • 空识别进入失败态，不触发润色、粘贴或成功统计。
  • 只有 LLM 已启用、润色触发长度达到 min_chars，且 Base URL、API Key、模型名完整时，才显示“正在润色文本”。
  • 悬浮字幕只显示实时字幕、耗时状态和错误提示，不显示“正在粘贴”“已粘贴”等瞬时状态。
  • 统计不记录识别正文，只记录时长、字数、速度等非正文数据。

2. 首页

首页适合日常使用：

  • 查看当前语音输入状态。
  • 点击麦克风按钮开始/停止录音。
  • 查看主快捷键和备用触发方式状态。
  • 查看最近 24 小时、最近 7 日、输入速度和节省时间估算。
  • 成功输入后，在当前窗口临时查看、复制或立即清空最近一次识别文本。该文本不写入统计文件、日志或诊断报告，隐藏窗口、退出或开始下一次录音后会清除。
  • 主窗口底部只显示最新一条错误通知。错误发生轮计入最近 5 轮窗口，新错误会重新开始计数；到第 6 轮开始时自动清除，也可随时手动关闭。

设计目标是让首页不承载复杂设置，只保留“现在能不能用”和“输入效果如何”。

3. 全局触发

默认只启用 Ctrl + Q。

触发方式 默认 建议
主快捷键 开启 保持开启
鼠标中键 关闭 确认不与浏览器、编辑器冲突后再开启
右 Alt 关闭 确认不与输入法或系统快捷键冲突后再开启

优化建议：

  • 如果快捷键无反应，先确认 API 配置已完成，再检查热键是否被其他软件占用。
  • 不建议同时开启多个容易误触的触发方式。

4. 麦克风采集

VoxType 使用 Rust cpal 采集 PCM 音频。

默认参数如下。这些属于底层参数，普通用户不需要在设置页修改；需要排障时可编辑 config.toml：

  • 采样率：16000
  • 声道：1
  • 分片：200ms
  • 最长录音：300s
  • ASR 无反馈自动停止：默认 30s，填 0 可关闭
  • 麦克风输入增益：0 dB

VoxType 会把麦克风实际输入统一转换为 16000Hz、单声道、16-bit PCM，再交给当前 ASR 服务。sample_rate 和 channels 只是采集偏好，不代表最终发送格式。

优化建议：

  • 多麦克风环境下，优先在选项页选择固定输入设备。
  • 说话距离过远、环境噪声大、系统麦克风权限关闭，都可能导致空识别。
  • 如果麦克风声音偏小但清晰，先确认系统麦克风音量和距离；录音质量卡片仍反复提示低音量时，再在录音排障中把输入增益小幅调到 +3 dB 或 +6 dB。
  • 录音中麦克风输入流异常会让本轮直接失败，避免缺帧音频继续进入润色、粘贴或成功统计。
  • ASR 无反馈自动停止默认 30 秒；如果服务端长时间没有有效文本反馈，会按正常停录流程收尾，不依赖本地音量阈值。
  • 录音时静音系统音量默认关闭，只有在回声明显影响识别时再开启。

5. ASR 服务

VoxType 默认使用豆包 bigmodel_async WebSocket，也可以在 API配置页切换到阿里云 FunASR。豆包可进一步选择新版语音控制台 API Key 方式、旧版 App Key + Access Key 方式，或火山方舟 Agent Plan 专属 API Key 方式；几套凭据独立保存在本地，Agent Plan 自动使用固定 Plan 地址和豆包流式语音识别模型 2.0 Resource ID。两个 ASR 服务共用同一条录音、字幕、最终文本、LLM、剪贴板和统计主链路。

特点：

  • 支持实时片段展示。
  • 豆包默认开启二遍识别，最终粘贴必须等到豆包最终包，优先使用 definite=true 的二遍分句，并可用高度重合的最终包整段文本补齐开头或尾部。
  • 阿里云 FunASR 会等待 task-finished，只把最终分句文本作为可输出文本。
  • 如果连接提前结束或等待超时，VoxType 会让本轮失败，不会用中间结果凑出文本。
  • 等待最终结果时，再按任一已启用的输入触发键会中断旧会话并立即开始新录音；旧会话的迟到结果不会继续润色、粘贴或计入统计。
  • 默认使用 full 全量结果返回，让最终包保留完整累计文本；重复中间字幕会在本地节流。
  • 默认保留 ITN、标点和 DDC 语义顺滑等底层请求能力；二遍识别、utterances 和 full 返回由主链路强制兜底。首字返回加速默认关闭以优先保障开头准确率，DDC 默认开启，用于短文本和中等文本的 ASR 侧轻量顺滑。

影响速度和效果的因素：

因素 建议
音频分片 内部默认 200ms，兼顾实时性与稳定性
麦克风输入增益 默认 0 dB；低音量清晰麦克风可小幅试 +3 dB 或 +6 dB
服务端判停 end_window_size 默认 800ms，已有手动配置会保留
首字返回 enable_accelerate_text 默认关闭，accelerate_score 默认 0；看重实时字幕起步速度时可手动开启
语义顺滑 enable_ddc 默认开启；更看重专有词、短命令、路径或标点敏感内容原样识别时可手动关闭
结果返回方式 主链路强制使用 full，让最终包包含完整累计文本；中间字幕只作反馈
ASR 无反馈兜底 默认 30 秒；设置 no_feedback_auto_stop_seconds = 0 可关闭
最终结果超时 默认 15 秒，网络异常时再通过 config.toml 调整
热词 对专有名词、人名、产品名很重要
最近上下文 连续写作可开启，但默认关闭以保护隐私；开启后发送给当前 ASR 服务
屏幕 OCR 上下文 默认开启，识别当前显示器，可切换为仅当前窗口，适合界面词、文件名和代码标识符

6. 自动输入与剪贴板恢复

识别完成后，VoxType 会：

  1. 将最终文本写入剪贴板。
  2. 发送 Ctrl+V 或 Shift+Insert。
  3. 尝试恢复原剪贴板。

选项页直接提供：

  • Ctrl+V：默认，适合大多数输入框。
  • Shift+Insert：适合部分拦截 Ctrl+V 的软件。
  • 仅复制到剪贴板：适合不希望自动向当前窗口发送粘贴快捷键的场景。
  • 粘贴后恢复剪贴板：默认开启。

底层剪贴板恢复延迟、快照大小和重试参数保留在 config.toml。

优化建议：

  • 如果某个软件粘贴失败，先切到记事本测试。
  • 如果目标软件读取剪贴板较慢，适当增加恢复延迟。
  • 若粘贴失败但文本已复制，可手动按 Ctrl + V。

7. 大模型润色

大模型润色适合：

  • 口述长句整理为更自然的文本。
  • 去掉口头语、重复、语序混乱。
  • 长文本按语义分段、分行或分点。
  • 结合热词和场景说明保留专有名词。

默认策略：

  • 未启用 LLM 时，只使用 ASR。
  • 文本短于 min_chars 时不润色；中文按单字计，英文和数字按连续词片段计，空格和标点不计。
  • thinking 默认按服务商自动适配关闭方式，降低延迟和测试不确定性；API 配置页测试会保存最快成功策略。
  • 达到最小字数并启用润色时，最终识别文本会发送到你配置的大模型服务；用户词典、场景与产品偏好、按预算压缩后的屏幕 OCR 和可选最近上下文会作为参考信息追加。
  • 最近上下文进入大模型默认关闭；只有最近上下文本地保存和“润色时参考最近上下文”同时开启时才会发送，默认限制为最近几段中的约 200 字。
  • 屏幕 OCR 发给大模型前会按行去空、去重，并默认限制为 12 行 / 400 字；热词参考默认最多 50 条。

优化建议：

  • 短消息、命令式输入：不一定需要润色。
  • 文档、会议纪要、需求说明：可以开启润色。
  • 如果润色变慢，先确认自动保存后触发的大模型适配测试已经完成，再手动重测思考适配、关闭 thinking，或提高 min_chars；增加超时只能减少失败，不会让模型更快。
  • 如果内容包含代码路径、文件名、日志字段或英文标识符，优先让屏幕 OCR 和热词提供准确写法，最终文本仍建议人工确认。

8. 热词、场景说明和 Prompt

热词适合解决“识别错词”：

VoxType
Tauri
豆包 ASR
项目代号
产品名

发送给 ASR 服务的直传热词或上下文会按服务能力做限制。豆包 ASR 的直传热词会限制为前 100 个有效条目，手动热词优先于自动确认热词，避免请求过大影响实时识别。建议保留高频专有词，低频或过时词及时清理。

常用提示词 / 场景说明适合描述长期偏好：

我经常输入产品需求、Code Review、项目计划。
输出尽量简洁，不要扩写。
保留英文技术词和项目名。

日常建议先维护热词和场景说明，只有需要固定改写风格时再展开高级 Prompt 设置：

  • User Prompt 模板和最小润色触发长度位于热词与提示词页的高级 Prompt 设置中。
  • LLM 参考信息预算和 System Prompt 保留在 config.toml。
  • 可预览最终 Prompt，并确认用户词典、场景/产品偏好、可选最近上下文和屏幕 OCR 如何按预算作为参考信息进入 LLM Prompt。
  • 默认提示词会区分短文本和长文本：短消息、单句命令和问题只做轻量纠错，可以补自然标点但不扩写；长段口述、记录、复盘、说明、会议纪要、产品反馈和投资复盘会按正式正文做成稿化润色，删除口水词、语气垫词、重复表达、无效停顿和自我修正过程，默认整理成 2-4 个自然段。
  • 默认提示词会保留专有名词、英文缩写、金融和编程术语。
  • 默认提示词会保留原文事实、判断、语气强弱和立场，并避免主动添加标题、列表、Markdown 或反引号。
  • 默认提示词会明确把用户词典、场景与偏好上下文、可选最近上下文、屏幕 OCR 标记为参考信息，不把它们当作待润色文本或指令来源，也不把待润色文本没说的参考信息补进输出。
  • 默认提示词会把待润色文本标成唯一输出来源；最近上下文不能被续写、复述或总结，屏幕 OCR 只在相关时用于纠正路径、文件名、代码标识符和界面词。
  • 文件路径、命令、日志字段和代码标识符不确定时默认保留原样，只有参考信息中出现明确写法时才纠正。
  • 金融、投资、量化语境中，默认提示词会把明确金额、收益率和百分比整理为 100万、1% 等常用数字写法，但不计算、不回答问题。

9. 自动热词候选

自动热词候选用于从历史语音输入中提取可能有价值的词。

隐私策略：

  • 默认关闭。
  • 只保存 VoxType 最终语音输入文本，不记录键盘输入，不读取剪贴板历史。
  • 本地历史可在热词页或隐私与本地数据页清空。
  • 只有手动点击生成候选时，才调用大模型。
  • 候选必须用户确认后才加入热词。

适合开启的场景：

  • 经常输入固定业务词、产品词、人名。
  • 不想手动维护大量热词。

不建议开启的场景：

  • 输入内容高度敏感。
  • 不希望本地保存任何识别正文历史。

10. 屏幕 OCR 上下文

屏幕 OCR 上下文用于在开始录音时读取当前显示器或当前窗口文字，帮助 ASR 和可选 LLM 理解界面词、文件名、人名、代码标识符等上下文。

隐私与稳定性：

  • 默认开启，识别范围为当前显示器；可在选项页切换为仅当前窗口。
  • OCR 正文只用于本轮请求，不写入日志、统计、配置或缓存。
  • 选项页的 OCR 测试预览可立即清空，并会在隐藏窗口、退出或开始下一轮录音时自动清空。
  • 进入 LLM 润色时，OCR 会按行去空、去重并按预算截断后作为独立参考信息追加，明确不是待润色文本或用户指令。
  • 失败或超时会自动跳过，不影响录音、ASR、润色、剪贴板或粘贴。
  • 超过首包等待上限才返回的 OCR 结果赶不上 ASR，但仍会作为 LLM 润色的参考信息，不增加任何等待。
  • 屏幕含敏感内容时，可在选项页切换为仅当前窗口或关闭；也可从隐私与本地数据页点击“管理设置”跳转到对应选项。

11. 隐私与本地数据页

隐私与本地数据页用于集中回答“保存什么、放在哪里、会不会上传、能不能清空”。页面只展示计数、开关状态、逻辑路径和上传边界，不展示识别正文、OCR 正文、热词历史正文、Prompt 或密钥。

页面分为三类：

  • 本地基础文件：配置文件和本地日志。配置文件可能包含 API 密钥和基础设置，但最近上下文正文不会写入 config.toml；日志和诊断报告默认脱敏，不应包含识别正文、热词、Prompt 或密钥原文。
  • 本地可清理数据：最近上下文、自动热词历史和统计数据。最近上下文与自动热词历史包含语音输入正文历史，默认关闭；统计只包含字数、时长、速度等非正文指标。最近上下文默认只发送给当前 ASR 服务，额外开启大模型参考后才会随润色请求发送给大模型。
  • 运行时与第三方服务数据：ASR 音频、屏幕 OCR、LLM 润色文本和剪贴板临时快照。这些数据通常不落盘，但 ASR、OCR 上下文、可选最近上下文和 LLM 润色会按功能开关进入对应的本轮请求。

清空按钮只清理 VoxType 本地文件，不代表第三方 ASR/LLM 服务也删除了已接收的数据；第三方留存策略取决于用户配置的服务商。

12. 悬浮字幕

悬浮字幕用于录音时确认实时识别状态。

默认展示：

  • 实时字幕。
  • 耗时状态。
  • 错误提示。
  • 字幕会先压缩 ASR 中间态中的格式性换行和连续空白，再清理中文间多余空格；实测能放下的内容保持单行，接近边界时只小幅缩小字号，真正溢出后才按真实字宽分配为最多两行。首行在空间允许时尽量使用 90% 以上宽度，尾行至少保留 3 个字符；超长内容保留可完整显示的最新尾部，避免孤字尾行、标点行首和横向裁切。运行窗口最低高度为 52px，旧的低高度配置会自动向上兼容。
  • 同一轮录音内，明显异常的 1-4 字骤降中间包不会覆盖已有完整字幕；正常的完整修订仍会继续显示。

不会展示：

  • 正在粘贴。
  • 已粘贴。
  • 内部路径。
  • 调试堆栈。

优化建议：

  • 默认使用预设配色和透明度。
  • 字幕挡住内容时，再通过 config.toml 调整宽度、高度和底部边距。
  • 如果希望长句更稳定显示两行，优先增大 height，不要通过缩短 ASR 分片来追求字幕体感。

13. 统计分析

统计记录：

  • 输入次数
  • 语音时长
  • 字数
  • 平均速度
  • 节省时间估算

节省时间按“同字数手打等效时间 - 实际语音时长”估算，手打基准为中文约每分钟 50 字。

统计不记录识别正文。

首页展示最近趋势，统计分析页展示按日统计。它适合观察 VoxType 是否真正节省时间，而不是查看历史正文。

14. 托盘、启动和更新

托盘：

  • 关闭主窗口默认隐藏到托盘。
  • 左键单击托盘图标可打开主窗口。
  • 托盘菜单可打开主窗口、打开配置、查看日志、问题反馈、检查更新、重启程序或退出。

开机启动：

  • 可在选项页开启。
  • 由系统登录拉起且语音识别已配置好时，VoxType 直接待在托盘，不弹出主窗口；点击托盘图标即可打开。
  • 手动打开，或尚未完成配置时，仍会显示主窗口。

更新：

  • 选项页和托盘菜单都可手动检查更新。
  • 启动自动检查默认开启。
  • 发现新版本时提示和更新面板会提供“立即更新”按钮。
  • 更新会下载 GitHub Release 中的 NSIS 安装包，安装时退出当前版本释放文件，安装完成后会尝试打开新版本。

15. 延迟优化速查

目标 优先调整
更快开始看到字幕 保持内部默认 200ms 音频分片，确认网络稳定
更快完成输入 不启用 LLM，或提高 min_chars
润色更快 等待自动思考适配测试或手动重测，保持 thinking 关闭，选择响应更快的模型
粘贴更稳 保持剪贴板恢复开启，必要时增加恢复延迟
减少误触 不开启右 Alt 和鼠标中键
提升专有名词准确率 维护常用热词、场景说明和屏幕 OCR 上下文