Setup Guide
这份指南面向第一次安装和日常使用 VoxType 的用户，覆盖 Windows 语音输入、语音转文字、豆包流式 ASR、可选 OpenAI 兼容大模型润色、自动粘贴、剪贴板恢复、热词和排障。建议先完成“能用”的最小配置，再按需开启输出质量、触发方式、字幕、更新和高级隐私功能。
English version: User Configuration Guide
VoxType 仅面向 Windows 10/11。
推荐从 GitHub Release 下载 Windows 安装包：
https://github.com/zkwi/VoxType/releases
安装版会内置 Microsoft Edge WebView2 Bootstrapper。干净电脑缺少 WebView2 Runtime 时，安装器会自动安装运行时。
运行前请确认 Windows 允许桌面应用访问麦克风：
Windows 设置 → 隐私和安全性 → 麦克风 → 允许桌面应用访问麦克风
VoxType 保留五个主页面：
| 页面 | 用途 |
|---|---|
| 首页 | 查看当前状态、开始/停止语音输入，并在顶部语音卡片查看启动方式 |
| 热词与提示词 | 管理常用热词、常用场景说明、润色提示词和自动热词候选 |
| API配置 | 配置豆包 ASR 必填认证和可选大模型 API |
| 选项 | 设置快捷键、粘贴方式、麦克风、悬浮字幕、开机启动和关闭行为 |
| 统计分析 | 查看最近 24 小时、最近 7 日和按日统计 |
设置页按两层组织：
- 界面直接展示：普通用户必须知道、经常修改和偶尔排障会用到的设置。
-
config.tomlonly：底层实现参数，界面不展示，但仍可手动编辑。
首页顶部语音卡片同时展示空闲/录音状态和三种启动方式（主快捷键、鼠标中键、右 Alt），三种入口使用单行紧凑标签；最近输入和输入表现放在下方，避免首页重复分区。
首页识别完成后会提示“已完成本次输入”，说明文本已复制并尝试粘贴。若目标输入框没有出现文字，可直接按 Ctrl + V，也可以在首页临时复制或查看本次识别文本；这份文本只保留在当前窗口内。
API配置页顶部是配置健康检查：ASR 密钥、麦克风、粘贴方式、触发方式和隐私设置分开展示。只有真正阻断录音、识别或粘贴主流程的问题才应作为明显警告；右 Alt、鼠标中键、最近上下文和自动热词这类可选项只作为弱提醒。公开截图时请像下图一样隐藏真实 App Key、Access Key 和其他密钥。
VoxType 的主链路依赖豆包流式 ASR。没有 ASR 认证时，录音、识别和粘贴入口会被锁定。
进入 API配置 → 豆包认证，填写：
| 字段 | 是否必填 | 说明 |
|---|---|---|
| App Key | 是 | 火山引擎控制台获取 |
| Access Key | 是 | 火山引擎控制台获取 |
Resource ID 默认使用 volc.seedasr.sauc.duration，普通用户不需要在界面中修改；特殊场景可编辑 config.toml。
填写后点击 测试。测试通过后即可返回首页使用语音输入。
API配置页还提供 识别语言。默认值是 zh-CN；如果经常输入英文、日语、粤语或其他豆包文档支持的语言，可以在这里切换。选择“自动 / 服务默认”会省略请求里的语言参数。豆包文档提示该参数只在部分流式模式支持，如果测试失败，先改回自动/服务默认或检查当前接口模式。
豆包官方接入说明：
https://www.volcengine.com/docs/6561/1354869?lang=zh
请不要把真实密钥提交到 GitHub，也不要把本地 config.toml 分享给他人。
大模型 API 用于：
- 轻度润色识别文本。
- 按常用场景整理长文本。
- 为自动热词候选生成候选词。
进入 API配置 → 大模型 API：
| 字段 | 说明 |
|---|---|
| 启用润色 | 关闭时只使用 ASR，不调用 LLM |
| Base URL | OpenAI 兼容接口地址，例如 https://dashscope.aliyuncs.com/compatible-mode/v1
|
| API Key | 对应服务商的 Key |
| 模型 | 例如 qwen3.5-plus
|
建议配置后点击 测试。如果只是语音识别，不需要开启大模型润色。
性能建议：
- 语音输入润色通常不需要 thinking，默认关闭更快；如需修改可编辑
config.toml。 - 短文本默认低于
min_chars = 40不润色，减少延迟。 - 网络不稳定时，可在
config.toml中调整 LLM 超时时间。
进入 热词与提示词 页面。
每行一个词，适合填写：
- 人名、公司名、产品名
- 项目名、缩写、代码名
- ASR 容易识别错的技术词
这些热词会用于提升识别和润色准确性。不要填写密码、证件号、手机号或客户敏感信息。
页面默认提供润色提示词入口。即使没有开启 LLM，也可以先编辑并保存提示词；只有开启大模型润色后才会生效。
默认提示词会把识别文本视为待润色素材，而不是模型指令；即使文本中包含问题、命令或类似提示词注入的内容，也只做文本润色，不回答、不执行、不分析。
可做的事情：
- 恢复默认提示词。
- 预览最终 Prompt；预览顶部会说明场景上下文会进入 LLM Prompt，最近上下文只用于豆包 ASR 上下文。
- 编辑 User Prompt 模板。
最小润色字数位于热词与提示词页；System Prompt 保留在 config.toml，避免普通设置页过长。
最近上下文默认关闭。开启后，VoxType 会把最近几轮识别片段保存到本地 context/recent_context.jsonl，用于改善连续输入的上下文效果。
注意：
- 只保存 VoxType 识别片段，不记录键盘输入。
- 不写回
config.toml。 - 如需清理，可删除本地
context/recent_context.jsonl文件。
自动热词候选默认关闭。开启后，VoxType 会本地保存最终语音输入文本；只有用户点击“生成候选”时，才会把摘要发送到已配置的大模型服务。历史文本默认上限为 5000 字；旧版默认 10000 字会在配置加载时自动迁移为 5000 字。生成候选会使用比普通润色更高的输出长度和超时预算；如果完整历史生成返回不完整或超时，会自动缩小历史范围并减少候选数量重试一次。
候选词不会自动加入热词列表，必须由用户勾选确认。如果模型返回候选不完整，可在 config.toml 降低历史文本上限或候选数量后重试。
选项页直接展示日常高频项和常用排障入口。热词、API配置和选项页不再重复显示通用配置状态卡片，进入页面后直接看到对应设置分组和测试入口：
| 模块 | 默认展示 |
|---|---|
| 使用方式 | 主快捷键、开机启动、关闭窗口行为 |
| 输入结果 | Ctrl+V、Shift+Insert、仅复制到剪贴板、自动去掉句尾句号、粘贴后恢复剪贴板 |
| 屏幕 OCR 上下文 | 开始录音时识别当前窗口文字、测试 Windows OCR |
| 麦克风 | 输入设备 |
| 悬浮字幕外观 | 字幕预览、配色预设、透明度预设 |
| 软件更新与诊断 | 检查更新、立即更新、打开日志、复制诊断报告 |
选项页还直接展示这些低频但实用的设置：
- 备用触发方式：鼠标中键、右 Alt。
- 录音与排障：连续低音量自动停止。
屏幕 OCR 上下文默认开启。它只截取开始录音时的当前前台窗口，不截取整个屏幕；识别结果会轻量合并中文字符之间的多余空格后，作为本轮 ASR 和可选大模型请求的临时上下文，不写入日志、统计或配置，也不会缓存最近 2-3 份截图 OCR 内容。当前窗口含敏感信息时，可在选项页关闭。
Resource ID、ASR WebSocket 地址、模型名、最终结果等待超时、最长录音秒数、LLM 超时、主热键启用开关、录音时静音系统音量、屏幕 OCR 字数上限和等待时间、字幕自定义尺寸/位置/颜色、剪贴板恢复延迟、快照大小和重试参数属于底层参数，保留在 config.toml。
托盘右键菜单可打开配置、查看日志、检查更新、重启程序或退出。配置更新后需要重新加载程序状态时，可直接使用“重启程序”。
建议首次使用保持这些默认值：
| 配置 | 推荐值 | 原因 |
|---|---|---|
| 主快捷键 | Ctrl + Q |
低冲突、易记 |
| 鼠标中键 | 关闭 | 可能与浏览器或编辑器冲突 |
| 右 Alt | 关闭 | 可能与输入法或快捷键冲突 |
| 粘贴方式 | 自动粘贴 | 适合大多数输入框 |
| 剪贴板恢复 | 开启 | 粘贴后尽量恢复原剪贴板 |
| 连续低音量自动停止 | 30 秒，阈值 0.03
|
比旧版 10 秒 / 0.04 更不容易在长句口述或轻声输入时被提前截断 |
| 屏幕 OCR 上下文 | 开启 | 只识别当前窗口文字，并规整中文字符间多余空格，提升专有名词和界面词命中率；敏感窗口可关闭 |
| 最近上下文 | 关闭 | 默认更保守 |
| 自动热词候选 | 关闭 | 默认不保存正文历史 |
| 录音时静音系统音量 | 关闭 | 避免影响会议、视频和系统提示 |
| thinking | 关闭 | 语音润色通常更快 |
界面会自动保存配置。需要手动编辑时，可参考 config.example.toml。
最小 ASR 配置：
[auth]
app_key = ""
access_key = ""
resource_id = "volc.seedasr.sauc.duration"可选 LLM 配置：
[llm_post_edit]
enabled = false
base_url = "https://dashscope.aliyuncs.com/compatible-mode/v1"
api_key = ""
model = "qwen3.5-plus"
min_chars = 40
enable_thinking = false录音：
[audio]
max_record_seconds = 300
silence_auto_stop_seconds = 30
silence_level_threshold = 0.03
mute_system_volume_while_recording = false触发方式：
[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
max_chars = 1200
timeout_ms = 700更新：
[update]
auto_check_on_startup = true
github_repo = "zkwi/VoxType"- 安装并启动 VoxType。
- 进入 API配置，填写豆包 ASR 的 App Key 和 Access Key；Resource ID 使用默认值，特殊场景再改
config.toml。 - 点击豆包 ASR 的 测试。
- 回到首页，把光标放到目标输入框。
- 按
Ctrl + Q开始录音，再按一次停止录音；如果持续低音量，默认 30 秒后会按手动停止流程自动停止。 - 等待最终识别和可选润色完成。
- 如果目标输入框没有出现文字，按
Ctrl + V手动粘贴。
不必须。VoxType 的核心是 Windows 语音输入和豆包 ASR 语音转文字；大模型润色只是可选后处理，适合长句整理、标点修正和风格统一。
可以。对不希望自动粘贴的场景，可在选项页选择“仅复制到剪贴板”，识别结果会留在剪贴板中，由用户手动 Ctrl + V。
热词适合写人名、产品名、项目名、英文缩写和技术词。不要写密码、证件号、客户资料或其他敏感信息。
这两个功能会在本地保存语音输入正文历史。为了减少隐私风险，VoxType 默认关闭，需要用户明确开启后才会记录。
屏幕 OCR 上下文默认开启，但不会保存正文历史；它只在开始录音时识别当前前台窗口，轻量合并中文字符之间的多余空格，并把结果临时附加给本轮 ASR/LLM 请求。VoxType 不缓存最近几次截图 OCR，避免占用豆包 ASR 上下文预算并降低隐私风险；若窗口含敏感内容，可以在选项页关闭。