Setup Guide - zkwi/VoxType GitHub Wiki

声写 VoxType 用户配置指南：Windows 语音输入、可选 ASR 与 LLM 润色

本页面是 GitHub Wiki Setup-Guide 的仓库内草稿镜像，用于避免线上 Wiki 与仓库文档长期漂移。更新线上 Wiki 时，应同步检查本文件。

这份指南面向第一次安装和日常使用 VoxType 的用户，覆盖 Windows 语音输入、语音转文字、豆包流式 ASR 或阿里云 FunASR、可选 OpenAI 兼容大模型润色、自动粘贴、剪贴板恢复、热词和排障。建议先完成“能用”的最小配置，再按需开启输出质量、触发方式、字幕、更新和高级隐私功能。

English version: User Configuration Guide

1. 安装与运行环境

VoxType 仅面向 Windows 10/11。

推荐从 GitHub Release 下载 Windows 安装包：

https://github.com/zkwi/VoxType/releases

安装版会内置 Microsoft Edge WebView2 Bootstrapper。干净电脑缺少 WebView2 Runtime 时，安装器会自动安装运行时。

运行前请确认 Windows 允许桌面应用访问麦克风：

Windows 设置 → 隐私和安全性 → 麦克风 → 允许桌面应用访问麦克风

2. 首次打开后的页面分工

VoxType 保留六个主页面：

页面 用途
首页 查看当前状态、开始/停止语音输入，并在顶部语音卡片查看启动方式
热词与提示词 管理常用热词、常用场景说明、大模型提示词和自动热词候选
API配置 选择并配置 ASR 服务认证和可选大模型 API
选项 设置快捷键、粘贴方式、麦克风、悬浮字幕、开机启动和关闭行为
隐私与本地数据 查看保存位置、上传边界并清空本地上下文、候选生成历史和统计
统计分析 查看最近 24 小时、最近 7 日和按日统计

设置页按两层组织：

  • 界面直接展示：普通用户必须知道、经常修改和偶尔排障会用到的设置。
  • config.toml only：底层实现参数，界面不展示，但仍可手动编辑。

首页顶部语音卡片同时展示空闲/录音状态和三种启动方式（主快捷键、鼠标中键、右 Alt），三种入口使用单行紧凑标签；最近输入和输入表现放在下方，避免首页重复分区。

当前界面参考

首页识别完成后会提示“已完成本次输入”，说明文本已复制并尝试粘贴。若目标输入框没有出现文字，可直接按 Ctrl + V，也可以在首页临时复制或查看本次识别文本；这份文本只保留在当前窗口内。

API配置页在当前 ASR 服务认证缺失时会先显示三步首次配置引导：选择服务并填写密钥、测试连接、回首页开始输入。其下方是配置健康检查：ASR 密钥、麦克风、粘贴方式、触发方式和隐私设置分开展示。只有真正阻断录音、识别或粘贴主流程的问题才应作为明显警告；右 Alt、鼠标中键、最近上下文和自动热词这类可选项只作为弱提醒。公开截图时请像下图一样隐藏真实 App Key、Access Key、阿里云 API Key 和其他密钥。

隐私与本地数据页会把最近上下文、候选生成历史、统计数据、ASR 音频、屏幕 OCR、LLM 润色文本和剪贴板快照的保存/上传边界集中展示，也提供清空本地上下文、候选生成历史和统计数据的入口。

3. 必填：配置 ASR 服务

VoxType 的主链路依赖一个可用的流式 ASR 服务。默认仍使用豆包 ASR；也可以在 API配置页切换到阿里云 FunASR。没有当前 ASR 服务认证时，录音、识别和粘贴入口会被锁定。

先记住最小配置原则：只要当前 ASR 服务测试通过，就可以回首页开始语音输入；大模型、热词、屏幕 OCR 都是后续提升质量的可选项。

豆包 ASR 配置

进入 API配置 → 语音识别服务 选择“豆包 ASR”，再选择接入方式：

接入方式 必填字段 说明
语音控制台 API Key（推荐） API Key 新版豆包语音控制台「API Key 管理」创建的密钥，走标准端点，Resource ID 默认小时版；全新安装默认就是这一项
App Key + Access Key App Key、Access Key 旧版控制台接入方式，Resource ID 可按账号已开通资源配置
火山方舟 Agent Plan Agent Plan API Key 使用方舟专属 X-Api-Key；模型和超额后付费需先在方舟控制台配置

三套凭据分别存放在 console_api_key、api_key 和 app_key/access_key，会独立保存在本地配置文件，切换后只使用当前接入方式，不需要反复覆盖另一套 Key。语音控制台 API Key 与方舟 Agent Plan 密钥不通用，填错会直接返回 401。Agent Plan 固定使用豆包流式语音识别模型 2.0 的 Resource ID volc.seedasr.sauc.duration，并自动连接 wss://openspeech.bytedance.com/api/v3/plan/sauc/bigmodel_async；该模式不使用 [request].ws_url。切换到 Agent Plan 时，设置页会自动校正 Resource ID。本版本只接入 ASR，不包含 Agent Plan TTS。

语音控制台 API Key 方式发送 X-Api-Key、X-Api-Resource-Id 和 X-Api-Request-Id；旧版标准方式发送 X-Api-App-Key、X-Api-Access-Key 和 X-Api-Resource-Id；Agent Plan 发送方舟专属 X-Api-Key 和固定 Resource ID。不要把百炼大模型 Key、GitHub Token 或火山引擎 IAM Secret 填到 ASR 认证里。豆包认证区域会根据当前接入方式打开对应官方文档。

填写后点击 测试。该连接测试会使用当前真实凭据向所选 ASR 服务发送程序生成的短静音包，用来验证认证、TLS 和服务权限；它不会开启麦克风，也不能替代真实录音、最终包和粘贴回归。测试通过后即可返回首页使用语音输入。

豆包模式下，API配置页日常只需要服务商和认证字段。识别语言 收在“高级连接与语言设置”里，默认选择“自动 / 服务默认”，会省略请求里的 language 参数；当前主链路使用 bigmodel_async + enable_nonstream 二遍识别，豆包文档说明二遍不支持 language，留空更适合中文、英文、方言和混合输入。中文普通话无需设置，旧配置里的 zh-CN 会自动迁移为空；只有明确要排查非默认语种时，再切换为 en-US、ja-JP、yue-CN 等代码。

阿里云 FunASR 配置

进入 API配置 → 语音识别服务 选择“阿里云 FunASR”，再填写：

字段 是否必填 说明
API Key 是 阿里云百炼 / DashScope API Key，按 WebSocket Bearer 认证使用
Workspace ID 是，除非填写自定义 WebSocket URL 百炼工作空间 ID，用于拼接实时语音识别 WebSocket 地址
高级连接与语言设置 通常不用改 地域、模型、自定义 WebSocket URL 和语言提示；仅在切换地域、固定语种或官方要求自定义 endpoint 时展开

阿里云模式会在连接后发送 run-task，等待 task-started 后上传 16kHz 单声道 PCM，停止录音时发送 finish-task，最终只接受 task-finished 前确认的最终分句文本。FunASR 实时字幕会把已确认分句与当前未完成分句合并显示；result-generated 中间文本仍只用于悬浮字幕反馈，不进入润色、粘贴、最近上下文、自动热词历史或成功统计。

阿里云模式下的语言提示使用 FunASR 的 language_hints，默认留空表示自动识别；需要排查非默认语种时再到高级区选择中文、英文、日文、韩文或粤语。

ASR 测试失败时

现象 优先检查
豆包认证或权限失败 接入方式是否选对；标准方式检查 App Key/Access Key/资源，Agent Plan 检查专属 API Key、模型配置与超额后付费
阿里云认证或权限失败 API Key、Workspace ID、地域和模型权限是否属于同一个百炼工作空间
提示连接失败或超时 网络、代理、防火墙是否允许访问当前 ASR 服务域名
改语言后失败 把识别语言改回“自动 / 服务默认”，再重新测试
测试通过但录音没字 Windows 麦克风权限、输入设备、麦克风音量、是否真的说话

正式录音链路同样会区分连接超时、连接失败、等待最终结果超时和连接提前关闭。本轮失败后会进入失败态并短暂提示错误，下一次按快捷键会重新开始一轮识别，不会一直停在“等待最终结果”。

仍无法定位时，到 选项 → 软件更新与诊断 → 复制诊断报告，把脱敏后的错误码和状态发到 Issue。不要贴真实 Key、完整日志或识别正文。

豆包标准接入说明：

https://www.volcengine.com/docs/6561/1354869?lang=zh

火山方舟 Agent Plan 接入说明：

https://www.volcengine.com/docs/82379/2516286?lang=zh

阿里云 FunASR 官方接入说明：

https://help.aliyun.com/zh/model-studio/fun-asr-realtime-websocket-api

请不要把真实密钥提交到 GitHub，也不要把本地 config.toml 分享给他人。

配置和日志在哪里

开发运行时，VoxType 继续使用仓库根目录的 config.toml 和 voice_input.log。安装版默认使用 Windows 用户数据目录：

  • 配置文件：%APPDATA%\VoxType\config.toml
  • 日志文件：%LOCALAPPDATA%\VoxType\logs\voice_input.log

如果安装版启动时发现旧位置已有 VoxType config.toml，且新默认位置还没有配置文件，主窗口会提示是否迁移。确认后只复制一次旧配置到新位置，不做复杂备份，也不会删除旧文件。隐私与本地数据页会显示当前实际配置和日志路径。

4. 可选：配置大模型润色 API

大模型 API 用于：

  • 轻度润色识别文本。
  • 按常用场景整理长文本。
  • 为自动热词候选生成候选词。

进入 API配置 → 大模型 API：

字段 说明
启用润色 关闭时只使用 ASR，不调用 LLM
Base URL OpenAI 兼容接口地址，可填服务根地址、/v1 地址或完整 /chat/completions 地址
API Key 对应大模型服务商的 Key，必须和 Base URL 来自同一平台/地域
模型 例如 qwen3.5-plus，必须是当前账号可调用的模型名
高级兼容性设置 思考适配默认自动；OpenRouter 优先使用 reasoning.effort=none 关闭推理，测试连接会保存最快的可用策略

密钥输入默认隐藏，可用输入框右侧按钮临时显示或复制。建议配置后点击 测试，也可以等待自动保存后自动测试。测试会使用一段示例文本和正式大模型提示词发起调用，成功时会显示本次延迟，并在自动模式下保存最快的思考/推理适配策略，但不会读取剪贴板、实时屏幕 OCR 或本地最近上下文正文。页面会在本机保留最近 5 次测试的成功率、成功请求平均延迟和最近一次结果；只保存测试时间、结果和延迟，不保存密钥、模型名或测试文本。修改 Base URL、API Key、模型名或 thinking 开关并自动保存后，VoxType 会自动从 auto 候选重新测速并保存最快成功策略。如果只是语音识别，不需要开启大模型润色。开启润色后，达到最小字数的最终识别文本会发送到你配置的大模型服务；用户词典、场景与产品偏好、按预算压缩后的屏幕 OCR 和可选最近上下文会作为参考信息追加。最近上下文进入大模型默认关闭，只有最近上下文和“润色时参考最近上下文”同时开启时才会发送，默认只发送最近几段中的约 200 字；屏幕 OCR 默认按行去空、去重后最多发送 12 行 / 400 字，热词默认最多 50 条。LLM 参考预算属于低频参数，保留在 config.toml，普通界面不再日常展示。

默认示例使用阿里云百炼/DashScope 的 OpenAI 兼容接口。北京地域 Base URL 是 https://dashscope.aliyuncs.com/compatible-mode/v1；如果使用新加坡、美国或其他地域，需要同步更换 Base URL、API Key 和模型权限，不要只改其中一个字段。DeepSeek 等标准 OpenAI 兼容服务可填写服务根地址、/v1 地址或完整 /chat/completions 地址，例如 https://api.deepseek.com、https://api.deepseek.com/v1/、https://api.deepseek.com/v1/chat/completions 会作为等价地址处理。

DashScope 关闭 thinking 时必须显式发送 enable_thinking=false，省略字段不代表关闭。OpenRouter 模型在支持时会发送 reasoning.effort=none；如果模型强制思考，测试会继续尝试低档 reasoning。仅返回思考内容、没有最终正文的响应不会被判定为润色可用。qwen3.7-max-preview 和 qwen3.7-max-2026-05-17 属于仅思考模型，无法关闭思考；VoxType 会阻止这类慢请求并提示改用 qwen3.7-max、qwen3.7-max-2026-05-20 或 qwen3.7-max-2026-06-08。

DashScope 模型选择可参考 2026-05-28 LLM 润色模型测试记录。其中 2026-05-30 复测修正了旧结论：日常仍优先考虑 qwen3.7-max；低延迟优先可考虑 qwen3.6-flash-2026-04-16，但它对提示词样式文本和技术路径更容易改偏；不要仅因技术文本切换到 deepseek-v4-pro，当前简化 prompt 下它也会改写代码路径。实际能否调用取决于当前账号和地域权限。

性能建议：

  • 语音输入润色通常不需要 thinking，默认会按服务商自动选择关闭方式以降低延迟；更换 Base URL、API Key、模型名或 thinking 开关后会在自动保存后自动重新测试一次。
  • 短文本默认低于 min_chars = 40 不润色，减少延迟；中文按单字计，英文和数字按连续词片段计，空格和标点不计。
  • 不同服务商的同名或近似模型延迟差异很大，优先看 API 配置页实测延迟，不要只看模型名称。
  • 代码路径、文件名和英文标识符容易被大模型“纠正”成看似合理但错误的形式，建议配合屏幕 OCR、热词或人工确认。
  • 网络不稳定时，可在 config.toml 中调整 LLM 超时时间。

大模型测试失败时

现象 优先检查
API Key 或权限失败 API Key 是否属于当前 Base URL 的服务商和地域
模型不存在或无权限 模型名是否拼写正确，账号是否已开通该模型
连接失败 Base URL 是否属于当前服务商，代理/网络是否可用
测试通过但润色没触发 是否开启润色，润色触发长度是否达到 min_chars
测试通过但实际很慢 重新测试思考适配策略，确认 thinking/reasoning 已关闭或降到最低
提示模型仅支持思考模式 改用支持关闭思考的混合思考模型；不要选择 qwen3.7-max-2026-05-17
代码路径经常被改错 开启屏幕 OCR，或把常用路径、文件名、字段名加入热词

大模型润色失败不会丢失 ASR 原文；VoxType 会保留原始识别文本并继续尝试复制/粘贴。

5. 热词与提示词

进入 热词与提示词 页面。

常用热词

每行一个词，适合填写：

  • 人名、公司名、产品名
  • 项目名、缩写、代码名
  • ASR 容易识别错的技术词

这些热词会用于提升识别和润色准确性。不要填写密码、证件号、手机号或客户敏感信息。发送给 ASR 服务的直传热词或上下文会按服务能力做限制；豆包 ASR 直传热词会限制为前 100 个有效条目，手动热词优先于自动确认热词，避免请求过大影响实时识别。

场景上下文

场景上下文适合填写当前写作场景、产品名、项目背景和常用表达。日常使用时，优先补充这里，比直接修改大模型提示词更容易维护。

最近上下文

最近上下文默认关闭。开启后，VoxType 会把最近几轮识别片段保存到本地 context/recent_context.jsonl，用于改善连续输入的上下文效果。它默认只进入当前 ASR 服务；如果希望大模型润色也参考前文，需要额外开启“润色时参考最近上下文”。

注意：

  • 只保存 VoxType 识别片段，不记录键盘输入。
  • 不写回 config.toml。
  • 可在隐私与本地数据页清空，也可手动删除本地 context/recent_context.jsonl 文件。

大模型提示词

页面默认优先展示热词、场景上下文、最近上下文和自动热词候选。大模型提示词模板和最小润色触发长度收在 高级 Prompt 设置 里；即使没有开启 LLM，也可以展开后先编辑并保存提示词，只有开启大模型润色后才会生效。

默认提示词会把“待润色文本”标成唯一需要改写并输出的内容，而不是模型指令；即使文本中包含问题、命令或类似提示词注入的内容，也只做文本润色，不回答、不执行、不分析。短消息、单句命令和问题只做轻量纠错，可以补自然标点但不扩写；长段口述、记录、复盘、说明、会议纪要、产品反馈和投资复盘会按正式正文做成稿化润色，删除口水词、语气垫词、重复表达、无效停顿和自我修正过程，必要时调整语序、拆分句子和补足连接词，默认整理成 2-4 个自然段。它会保留原文事实、判断、语气强弱和立场，保留专有名词、英文缩写、金融和编程术语，并避免主动添加标题、列表、Markdown 或反引号。用户词典、场景与产品偏好、可选最近上下文、屏幕 OCR 会作为参考信息分区追加，只用于纠正术语、称谓、界面词、上下文承接、路径、文件名和代码标识符，不作为待润色文本或指令来源，也不能把待润色文本没说的参考信息补进输出。最近上下文不能被续写、复述或总结；屏幕 OCR 只在与待润色文本相关时用于纠错。文件路径、命令、日志字段和代码标识符不确定时会要求模型保留原样，只有参考信息中出现明确写法时才纠正。金融、投资、量化语境中，默认提示词会把明确金额、收益率和百分比整理为常用数字写法，例如 100万、1%，但不会计算收益或回答问题。

可做的事情：

  • 恢复默认提示词。
  • 预览最终 Prompt；预览会说明参考信息拼接规则、屏幕 OCR 当前开关策略和 LLM 预算，以及最近上下文是否进入大模型提示词。
  • 在高级 Prompt 设置中编辑 User Prompt 模板和最小润色触发长度。

最小润色触发长度支持 0 到 10000；中文按单字计，英文和数字按连续词片段计。LLM 参考信息预算和 System Prompt 保留在 config.toml，避免普通设置页过长。

自动热词候选

自动热词候选默认关闭。开启后，VoxType 会本地保存最终语音输入文本；只有用户点击“生成候选”时，才会把摘要发送到已配置的大模型服务。本地历史可在热词页或隐私与本地数据页清空。历史文本默认上限为 5000 字；已保存的上限会按用户配置保留，不再按旧默认值自动改写。生成候选会使用比普通润色更高的输出长度和超时预算；如果完整历史生成返回不完整或超时，会自动缩小历史范围并减少候选数量重试一次。

候选词不会自动加入热词列表，必须由用户勾选确认。如果模型返回候选不完整，可在 config.toml 降低历史文本上限或候选数量后重试。

6. 选项页日常设置

选项页按“常用设置、体验增强、应用维护”组织，日常高频项在前，体验增强和维护入口分层展示。热词与提示词、API配置和选项页不再重复显示通用配置状态卡片，进入页面后直接看到对应设置分组和测试入口：

模块 默认展示
常用设置 主快捷键、麦克风、粘贴方式、自动去掉句尾句号、粘贴后恢复剪贴板
体验增强 屏幕 OCR 上下文、测试 Windows OCR、字幕预览、配色预设、透明度预设
应用维护 开机启动、关闭窗口行为、检查更新、立即更新、打开日志、复制诊断报告
低频录音排障 默认折叠；只有非默认或校验错误时展开，包含 ASR 无反馈自动停止和输入增益
备用触发方式 默认折叠；只有已开启时展开，包含鼠标中键、右 Alt

如需查看或清理本地数据，请从左侧导航进入“隐私与本地数据”页。

屏幕 OCR 上下文默认开启。默认识别当前显示器，适合参考一个文档并在另一个窗口输入；也可在选项页切换为仅当前窗口。识别结果会轻量合并中文字符之间的多余空格后，作为本轮 ASR 和可选大模型请求的临时上下文，不写入日志、统计或配置，也不会缓存最近 2-3 份截图 OCR 内容。发给 ASR 的 OCR 受屏幕 OCR 字数上限控制；发给大模型润色的 OCR 会另按 LLM 预算压缩。屏幕含敏感信息时，可切换为仅当前窗口或关闭。

Resource ID、ASR WebSocket 地址、模型名、最终结果等待超时、最长录音秒数、尾音保留毫秒、LLM 超时、主热键启用开关、录音时静音系统音量、屏幕 OCR 字数上限和等待时间、字幕自定义尺寸/位置/颜色、剪贴板恢复延迟、快照大小和重试参数属于底层参数，保留在 config.toml。LLM 最小润色触发长度在热词与提示词页的高级 Prompt 设置中调整；LLM 参考信息预算保留在 config.toml。

左键单击托盘图标可打开主窗口；托盘右键菜单可打开配置、查看日志、问题反馈、检查更新、重启程序或退出。配置更新后需要重新加载程序状态时，可直接使用“重启程序”。

7. 推荐默认值

建议首次使用保持这些默认值：

配置 推荐值 原因
主快捷键 Ctrl + Q 低冲突、易记
鼠标中键 关闭 可能与浏览器或编辑器冲突
右 Alt 关闭 可能与输入法或快捷键冲突
粘贴方式 自动粘贴 适合大多数输入框
剪贴板恢复 开启 粘贴后尽量恢复原剪贴板
ASR 无反馈自动停止 默认 30 秒；填 0 可关闭 ASR 服务长时间没有有效文本反馈时，按正常停录流程收尾
屏幕 OCR 上下文 开启，范围为当前显示器 规整中文字符间多余空格，提升专有名词和界面词命中率；敏感场景可切换为仅当前窗口或关闭
最近上下文 关闭 默认更保守；大模型参考前文也需要额外开启
自动热词候选 关闭 默认不保存正文历史
录音时静音系统音量 关闭 避免影响会议、视频和系统提示
thinking 关闭 语音润色通常更快

8. config.toml 关键字段

界面会自动保存配置，标题栏会短暂显示待保存、保存中和已保存状态。需要手动编辑时，可参考 config.example.toml。

最小豆包 ASR 配置：

[asr]
provider = "doubao"

[auth]
app_key = ""
access_key = ""
resource_id = "volc.seedasr.sauc.duration"

最小阿里云 FunASR 配置：

[asr]
provider = "aliyun_fun"

[aliyun_asr]
api_key = ""
workspace_id = ""
region = "cn-beijing"
model = "fun-asr-realtime"
language_hint = ""

可选 LLM 配置：

[llm_post_edit]
enabled = false
use_recent_context = false
base_url = "https://dashscope.aliyuncs.com/compatible-mode/v1"
api_key = ""
model = "qwen3.5-plus"
min_chars = 40
screen_context_max_chars = 400
screen_context_max_lines = 12
recent_context_max_chars = 200
reference_hotwords_limit = 50
enable_thinking = false
thinking_strategy = "auto"

录音：

[asr]
no_feedback_auto_stop_seconds = 30

[audio]
max_record_seconds = 300
stop_grace_ms = 250
input_gain_db = 0.0
mute_system_volume_while_recording = false
# 可选：优先按设备名称匹配；旧 input_device index 仅用于兼容旧配置
# input_device_name = "Microphone Array"
# input_device = 1

在选项页选择麦克风后，VoxType 会同时保存设备名称和旧版数字 index；下次启动录音时优先按名称匹配，蓝牙耳机重连或设备枚举顺序变化时更不容易选错。若保存的麦克风已不可用，会自动回退系统默认输入设备并显示非阻塞提示。

豆包模式下，VoxType 会把 ASR 实际发送分片限制在豆包建议的 100-200ms，默认 200ms。约 50ms 头部静音会并入第一包真实音频，但第一包总时长仍按当前分片配置发送，默认约 200ms，帮助豆包稳定识别开头几个字，同时避免发送独立 50ms 小包；如果没有采集到真实音频，则不会额外发送静音包。阿里云 FunASR 模式同样发送 16000Hz 单声道 PCM，并按服务端 task-finished 事件确认最终文本。

VoxType 默认保持 input_gain_db = 0.0，不额外放大麦克风音频。只有当录音质量卡片反复提示音量偏小、且系统麦克风音量和距离已确认正常时，才建议在录音排障中手动小幅提高输入增益，例如先试 +3 dB 或 +6 dB；避免过高增益造成削波或放大环境噪声。录音结束后，首页会按需显示一张轻量的录音质量卡片，展示最近一轮的 RMS、峰值、有效语音比例和建议；如果本轮已经成功识别并输出文本，低有效语音占比提示会被隐藏，避免把可用结果误报为问题。这些指标不包含正文，也不会写入主统计表。

豆包返回的中间文本会用更短的本地节流尽快显示在悬浮字幕中，过快的新字幕会合并最新文本并按时补发；同一轮录音内，明显异常的 1-4 字骤降中间包不会覆盖已有完整字幕。同一响应里如果分句累计文本比 result.text 更完整，字幕优先显示更完整的累计文本，但最终粘贴仍必须等待最终包。阿里云返回的中间文本同样只作字幕反馈，最终粘贴等待 task-finished。悬浮字幕运行窗口最低高度为 52px，旧的低高度配置会自动向上兼容。stop_grace_ms 表示停录后固定保留的真实尾音等待时间，默认约 250ms，不再依赖本地音量检测判断是否延长；低音量麦克风不会因为音量阈值误判而提前切断尾音。不足一片的尾部音频会在关闭麦克风前补发给 ASR。ASR 无反馈自动停止默认 30 秒，只在服务端没有返回有效文本反馈时按正常停录流程收尾；填 0 可关闭。

豆包模式近期实测较稳定的组合是：保留默认 200ms ASR 分片，把体感速度优化放在 20ms 响应轮询、50ms 字幕节流和 500ms OCR 上下文等待上；首字返回加速默认关闭，优先保障开头准确率。豆包最终文本仍只接受最终包，并优先使用最终包里的 result.text 整段文本。definite=true 分句用于稳定最终结果，但最终包与分句高度重合且补齐开头或尾字时，即使最终包对前文有轻微缩写，也应优先保留最终包整段文本。

首字返回加速默认关闭，enable_accelerate_text = false 且 accelerate_score = 0；已保存的显式取值会保留。如果特别看重实时字幕起步速度，可在 config.toml 中手动开启，但首字准确率可能下降。

语义顺滑 enable_ddc 默认开启，用于短文本和中等文本的 ASR 侧轻量顺滑，减少短文本依赖 LLM 润色带来的等待；已保存的显式取值会保留。之后如果更看重专有词、短命令、路径或标点敏感内容的原样识别，可以手动关闭。

触发方式：

[triggers]
hotkey_enabled = true
middle_mouse_enabled = false
right_alt_enabled = false

输出方式：

[typing]
paste_method = "ctrl_v"
remove_trailing_period = true
restore_clipboard_after_paste = true
clipboard_restore_delay_ms = 800

屏幕 OCR 上下文：

[screen_context]
enabled = true
capture_scope = "screen"  # screen = 当前显示器，window = 仅当前窗口
max_chars = 1200
timeout_ms = 500

更新：

[update]
auto_check_on_startup = true
github_repo = "zkwi/VoxType"

9. 第一次使用流程

  1. 安装并启动 VoxType。
  2. 进入 API配置，选择豆包 ASR 或阿里云 FunASR，并填写当前服务的认证字段。
  3. 点击当前 ASR 服务的 测试。
  4. 回到首页，把光标放到目标输入框。
  5. 按 Ctrl + Q 开始录音，再按一次停止录音；ASR 无反馈自动停止默认 30 秒，需要更长等待或关闭时可在选项页设置。
  6. 等待最终识别和可选润色完成。
  7. 如果目标输入框没有出现文字，按 Ctrl + V 手动粘贴。

10. 下一步

11. 配置常见问题

必须配置大模型 API 吗？

不必须。VoxType 的核心是 Windows 语音输入和当前 ASR 服务语音转文字；大模型润色只是可选后处理，适合长句整理、标点修正和风格统一。

只复制到剪贴板还能用吗？

可以。对不希望自动粘贴的场景，可在选项页选择“仅复制到剪贴板”，识别结果会留在剪贴板中，由用户手动 Ctrl + V。

热词应该怎么写？

热词适合写人名、产品名、项目名、英文缩写和技术词。不要写密码、证件号、客户资料或其他敏感信息。

为什么默认关闭最近上下文和自动热词候选？

这两个功能会在本地保存语音输入正文历史。为了减少隐私风险，VoxType 默认关闭，需要用户明确开启后才会记录。

最近上下文包含真实语音输入正文，所以默认不保存、不发送给大模型。开启最近上下文后，它会用于当前 ASR 服务连续识别；只有额外开启“润色时参考最近上下文”并实际触发大模型润色时，才会把受限前文发送给大模型。

屏幕 OCR 上下文默认开启，但不会保存正文历史；它默认在开始录音时识别当前显示器，轻量合并中文字符之间的多余空格，并把结果临时附加给本轮 ASR/LLM 请求。VoxType 不缓存最近几次截图 OCR，避免占用当前 ASR 服务上下文预算并降低隐私风险；发给 LLM 的 OCR 会按预算压缩。若屏幕含敏感内容，可以在选项页切换为仅当前窗口或关闭。