独立的 Linux GTK4 语音输入应用，支持 Hyprland / Wayland 和原生 X11。默认使用豆包网页账号识别，也可选择 火山引擎官方 Seed ASR 2.0 API，也可使用 Deepgram Nova-3 做英语听写。 默认英文，设置提供 System（跟随系统）/ English / 简体中文，选择后自动保存并立即生效。 System 读取桌面会话的语言偏好，中文区域使用简体中文，其他不支持的语言回退为英文。 可选的 Omarchy 集成管理的是同一个应用，不是另一套语音引擎。
使用 dist/ 中的应用或 Omarchy 插件安装包，内含离线安装器及 Python 依赖 wheel，
适用平台以文件名为准。GTK、WebKit、PipeWire 和剪贴板等系统库不会打进安装包。
详见安装、升级和卸载说明。
解压后运行 ./install.sh：它会检测缺少的 Arch／Omarchy 系统包，列出清单并经确认后
安装，同时校验安装包并安装随包 Python 依赖。./install.sh --check 只检查、不修改系统。
通过市场或 Git 安装时，按安装说明中的 Git / marketplace installation 操作： 先添加但不启用，运行安装器，检查运行环境，再完成引导。其卸载方式与离线包不同，不要混装。
从应用菜单打开豆包说（Doubao Say）：
- 语音识别：使用默认的豆包网页登录，或在设置中选择火山引擎官方 API、 **Deepgram Nova-3（英语）**并填写自己的语音 API Key；凭证均保存在本机。
- 麦克风：选择 PipeWire 输入设备，再进行三秒的本机检测；此步骤不上传音频，切换设备后立即保存。
- 快捷键：选择 Fn、Ctrl、Alt 或功能键预设后立即生效；也可选择下拉框最后一项 录制快捷键…，录制出的组合键会完整替换当前快捷键。
- 试说：真实调用语音识别引擎，结果只显示在软件内及悬浮窗，不执行粘贴或回车。 通过后点击完成设置，即可在其他应用中使用触发键。
触发键按下后会立即在本地保存一小段预录音，避免遗漏第一个字；只有单击或长按手势被确认后， 音频才会交给所选识别服务。双击、Esc 或取消手势会直接丢弃尚未确认的本地音频。
打开设置 → 语音识别服务，选择火山引擎官方 API，填写火山引擎语音识别控制台
签发的 API Key。修改会自动保存，建议先点击测试 API Key，再进行试说。该后端使用
Seed ASR 2.0 双向流式接口和小时版资源 volc.seedasr.sauc.duration：说话时上传 PCM
音频并实时返回增量识别文字，录音结束后返回最终结果；用量由火山引擎向你的账号计费。
API Key 保存在 ~/.config/doubao-say/volcengine_api_key（或对应的
XDG_CONFIG_HOME 路径），权限仅限当前用户读取；不会进入设置文件、诊断信息、日志、
安装包或测试报告。清除凭证会删除该 Key。服务开通和项目权限需在火山引擎控制台管理；
若“测试 API Key”返回 HTTP 401，通常表示账号侧访问权限尚未就绪。
两种识别方式的区别、新版控制台开通步骤、双向流式限制与排障方法见 豆包与火山引擎官方语音识别。
打开设置 → 语音识别服务，选择 Deepgram Nova-3（英语），填写 Deepgram 控制台签发的 API Key。建议先点击测试 API Key，再进行试说。应用会把 16 kHz 单声道 PCM 音频流式发送到 Deepgram Nova-3 实时接口，固定使用美式英语，并启用 中间结果、标点和智能格式化。说话时会显示增量文字，录音结束后返回最终结果；用量由 Deepgram 向你的账号计费。
API Key 保存在 ~/.config/doubao-say/deepgram_api_key（或对应的
XDG_CONFIG_HOME 路径），权限仅限当前用户读取；不会进入设置文件、诊断信息、日志、
安装包或测试报告。目前界面还没有开放 Deepgram 的其他语言和多语种模式。
选择 Voxtype（本地） 后，麦克风采集和转写由正在运行的 Voxtype daemon 负责。
豆包说要求 Voxtype 1.0.0 或更高版本，并使用它稳定的文件输出完成接口。请单独安装
Voxtype，运行 voxtype setup --download，启动 daemon，再在首次设置中点击
刷新 Voxtype 状态。引擎、模型、语言、音频设备和加速方式仍在 Voxtype 中配置；
该接入不会改写 Voxtype 配置。
设置窗口会读取 Voxtype 的版本化 Schema 和扩展状态，显示 daemon 版本、状态、引擎、
模型、音频设备、计算后端、Schema 版本和配置文件路径。点击打开 Voxtype 配置后，
应用会在可用终端里启动 voxtype configure，所有配置仍由 Voxtype 自己校验和写入。
每次听写手势确认后，豆包说会让 Voxtype 把一份转写写入当前用户的私有 runtime 目录，
等待 .done 完成信号，读取原子写入的最终文字，然后删除这两个文件。若 Voxtype 已在
录音或转写，豆包说不会接管；取消操作也只针对本应用启动的录音。Voxtype 1.0.1 及更高
版本可以在本次会话中关闭自带 OSD；1.0.0 也能使用，但可能同时显示两套悬浮窗。
当前接入只能取得最终转写，Voxtype 没有把麦克风音频和实时音量交给豆包说，因此本地 预录音和实时波形不可用。使用长按说话时，请看到“正在聆听”后再开口，以免句首被截断。 Voxtype 本地引擎不会上传音频；如果你在 Voxtype 内配置了云端引擎，则适用对应服务条款。
润色时，独立状态栏和缓慢闪烁的星星位于正文上方；等待三秒后显示快捷键提示。 开启减少动态效果时，星星保持静止。
在“快捷键”页面打开语音润色 · 实验特性开关，可配置 OpenAI 兼容的 Base URL、API Key、模型和 中文与英文 Prompt；应用会根据每次转写的主要语言自动选择。内置 Prompt 会去除口水词、重复和口误，改善标点与结构，同时保留原意；用户可 自行修改，也可一键恢复默认内容。
优先选择小型、低延迟模型，并关闭思考。 润色只需要轻量文字修正，不需要深度推理。 不建议默认使用大型推理模型：润色总共只有五秒，超过上限就会使用原文。 小模型也可能开启思考，名称带 Flash/Lite 不代表思考已经关闭，也不代表支持关闭。
建议从以下官方接口配置开始：
| 模型 | Base URL | 自动思考控制 |
|---|---|---|
DeepSeek Flash（deepseek-flash） |
https://api.deepseek.com |
请求 thinking: {"type": "disabled"} |
Gemini 2.5 Flash-Lite（gemini-2.5-flash-lite） |
https://generativelanguage.googleapis.com/v1beta/openai |
请求 reasoning_effort: "none" |
Gemini 2.5 Flash 也已适配自动关闭思考。参数说明见 DeepSeek 思考模式文档和 Gemini OpenAI 兼容文档。 以上是配置建议，不是实测延迟保证；网络、服务负载和文本长度都会影响速度。 先用“测试接口”检查连通性，再通过一段简短录音判断实际润色速度和质量。
设置页会显示当前接口和模型的思考策略。自动适配依赖官方域名，而不只是模型名称。 使用中转接口或尚未适配思考控制的服务商（包括 OpenAI、Claude、Grok）时， 请在服务商配置中确认关闭思考，或选择非推理模型；否则应用会沿用服务商默认值。 当前 OpenAI 兼容客户端不支持 Claude 原生 API。
智谱（open.bigmodel.cn）标准 API 和 Coding Plan 接口会请求关闭思考，
但 GLM-5.3 和 GLM-5.3-Flash 不允许关闭，因此改为请求 reasoning_effort: "low"。
低推理强度仍然是思考模式，不作为五秒润色场景的首选。详情见
智谱深度思考文档。
开启后，识别文本稳定且静音 1.2 秒会启动预润色；再次说话会立即让旧请求失效并回到聆听状态。 悬浮窗独立显示润色状态和流式文字。润色结合本次整段上下文，只修明显口误与识别错误， 不推断或过度改写。停顿只生成预览，不会自动结束录音或上屏； 短按启动后再次短按结束，长按松开结束，随后才一次上屏。识别文字变化才废弃旧请求， 麦克风噪声不会反复触发。润色最多占用五秒（包含排队）；超时使用原文，迟到结果不再上屏。 短按模式再次短按结束录音，长按模式松开结束。最终润色期间再次按当前触发键 会立即使用原文；接口失败时同样安全回退，不会丢失识别结果。
API Key 通过仅限当前用户读取的独立文件保存，不进入诊断信息。建议开启前先点击“测试接口”。
| 桌面会话 | 自动剪贴板粘贴 | 直接输入 |
|---|---|---|
| Hyprland / Wayland | 使用 wl-copy，要求目标窗口已知且未变化 |
可选 wtype |
| 原生 X11 | 可选使用 xclip 和 xdotool，要求目标窗口及 PID 已知且未变化 |
不支持，请选择剪贴板粘贴 |
| 其他 Wayland 桌面 | 无法确认焦点时保留结果供手动复制 | 暂无支持的自动输入路径 |
原生 X11 使用 Ctrl+V；识别到终端窗口时使用 Ctrl+Shift+V。悬浮窗不主动请求焦点，
位置由窗口管理器决定。Hyprland 保留底部 layer-shell 悬浮窗。
两个桌面都通过 pw-record 使用所选 PipeWire 麦克风。XWayland 不会被当作原生 X11 会话。
程序会在运行时探测 X11 辅助工具；缺少任一工具都不影响安装和识别，结果会保留供手动复制。
设置 → 输入 → 文字输入方式，默认使用剪贴板粘贴，已有配置也保持此默认值。
剪贴板粘贴会替换当前剪贴板内容，剪贴板管理器可能将识别文字存入历史。
此功能不依赖 CopyQ，也不会恢复剪贴板或排除历史记录。
Hyprland 下可选择直接输入以保持剪贴板不变。此模式需要另行安装 wtype，并使用支持
Wayland 虚拟键盘的桌面，已在 Hyprland 验证。
直接输入会逐字发送，本机测试 1,760 字约需 8 秒。换行和制表符相当于回车和 Tab，
可能发送消息、执行终端命令或切换焦点。输入期间请保持目标窗口聚焦并避免同时打字。
Esc 可停止后续输入，但不能撤回已输入的文字；焦点变化时也会尽力停止输入。
若直接输入失败或未安装 wtype，识别结果保留在应用中，不会自动转为剪贴板粘贴。
重试前请检查是否已有部分文字输入。
默认触发键为 Fn，可改为 Ctrl、Shift、Alt、Meta、F8、F9 或禁用。 修饰键不区分左右，实际按任意一侧都能触发。 如果键盘没有向 Linux 上报 Fn 按键，请选择其他键。
- 短按开始，再按一次结束并粘贴。
- 长按超过阈值开始说话，松开结束并粘贴。
- 可直接选择一个预设，或选择**录制快捷键…**来录制 Ctrl+Alt+Space 这样的组合键；任何时候只会生效一个快捷键。
- 连续按两次当前触发快捷键会在不听写的情况下发送回车，可能发送消息或执行终端命令。
- 长按阈值、双击间隔、双击回车开关和自启动均可设置。
底部悬浮窗显示声音驱动的波纹和实时文字。 在「设置 → 外观 → 聆听波纹样式」中，可切换经典声柱、柔和声浪、同心涟漪和 「篮球律动」。篮球主题由细密声波隐约拼出人形和橙色球，人物尺寸固定、双脚站稳，随运球节奏向右顶肩再收回，手提前下压再回收，并带有触地涟漪。动作按「屈膝蓄力 → 拍球 → 触地压扁 → 顶肩、头部滞后 → 短暂停顿 → 收回」循环。拍球速度由声音起伏估计的说话节奏控制（不是音量，也不是识别后的每分钟字数）；停顿时定格，音量只影响明暗，不绘制实心人物或球的轮廓。 更改自动保存，可点击「预览外观」查看；默认仍为经典声柱。 开启「减少波形更新」后，新样式会停止行进和弹跳动画，保留音量反馈。 最终文字在录音结束后粘贴，目标输入框不会边说边更新。没有绿色音量条或进度条。 单击系统托盘的波形图标会打开已有应用窗口：就绪时蓝色、录音时红色、转写时黄色。 部分桌面会将托盘图标收纳在可展开的区域中。
应用会在启动时和运行期间检查仓库最新的稳定版 GitHub Release，网络检查最多每 24 小时一次。 发现新版本后，录音悬浮窗右上角会显示一个红色小圆点，悬停或点击可查看版本信息。 结束听写后，可点击控制中心的红色更新按钮打开发布页面，避免打断粘贴目标。 软件不会自动下载或安装更新。
问题和建议统一通过 GitHub Issues 提交。 请附上版本、桌面环境、复现步骤、预期与实际行为。附件中请移除 API Key、登录 Cookie 和私人转写文本。
控制中心只保留四个设置步骤，不再单独设置首页或完成页。 需要重新检查或修改时，可从托盘再次打开。托盘的复制最近结果 可恢复内存中的最近一次结果。Escape 可取消录音或待发送的输入。 在使用 Lua 配置的 Hyprland 上，录音、润色和等待粘贴时会临时拦截 Esc，避免同时退出前台 TUI； 空闲时恢复正常。已有的全局 Esc 绑定不会被覆盖，无法启用拦截时会显示提示。 其他桌面目前只能监听 Esc，无法阻止它传到前台。 粘贴和回车由后台工作线程串行执行，等待剪贴板不会阻塞 GTK 界面。粘贴前会保存一份主要 MIME 内容；仅当剪贴板仍是本次识别文字时，才按原始字节恢复。用户在输入期间复制的新内容 不会被旧内容覆盖。取消会停止后续输入，但无法撤回已经发送的文字。 识别失败时可能保留已收到的部分文字，粘贴失败时会保留结果。 这里只在内存中保留一次结果，不是转写历史；退出应用会丢失该结果。
自动粘贴要求能确认 Hyprland 或原生 X11 的目标窗口未变化。 X11 窗口信息缺失、窗口关闭或焦点在本应用窗口时，均不自动粘贴。 未支持的桌面或无法确认目标时，保留结果供手动复制。 软件会在粘贴和回车前检查焦点，但焦点检查与输入发送无法成为一个不可分割的操作； 同一窗口内移动光标也无法检测。发出粘贴快捷键不等于能确认目标应用已收到文字。
设置支持按键捕获（超时与取消）、PipeWire 麦克风选择、降低波形更新频率、账户管理， 以及仅包含允许字段的诊断信息预览与复制。选择按键期间会暂停正常的输入触发。 按键录制支持普通键盘按键和修饰键组合；Ctrl、Shift、Alt、Meta 均不区分左右。 软件不能自动检测所有桌面快捷键冲突。
录音手势确认后，默认的非官方后端会把本地预录音和后续实时音频上传到豆包，并依赖豆包 网页协议；可选的 API 后端会按用户的账号和服务条款向火山引擎或 Deepgram 上传音频。 Voxtype 后端把麦克风采集交给 Voxtype，是否上传取决于其中配置的引擎。双击、取消和 单独的麦克风检测不会经由豆包说上传音频；登录网页的语言由豆包网站决定。 开启可选润色后，识别文字（包括停顿后用于预润色的临时文字）会发送到用户配置的 OpenAI 兼容接口，并适用该接口运营方的数据留存、训练及隐私政策。 更新检查最多每天向 GitHub 发起一次标准 HTTPS 请求，GitHub 会收到常规连接元数据； 本地只缓存检查时间和版本标签，不包含账号、转写文字或设备标识。
需要读取键盘设备及写入 /dev/uinput 的权限。不要以 root 身份运行软件。
Vibekey 支持默认关闭，可在设置中启用；三个发射器按键分别用于录音、回车确认和取消。
旋钮右转、左转、按下默认分别发送下方向键、上方向键和 Meta+Backspace；这三个旋钮动作
以及前三个按键都可以保留默认功能或重新录制任意键盘快捷键。关闭 Vibekey 支持时，
这些映射设置会隐藏。
它只需要安装说明中的精确 udev 规则，不新增软件依赖。
设置和登录信息与安装文件分开保存。不要发布凭证、个人转写文字、录音或日志。
发布构建使用明确的文件白名单，不包含开发环境和验收产物。
只选择一种自启动管理方式：独立应用的桌面自启动或 Omarchy 插件。 卸载会保留设置和登录信息。插件生命周期和恢复行为见安装说明。
用户要求安装豆包说时，请按本节执行。独立应用和 Omarchy 插件使用同一套豆包云端引擎， 只选择一种安装路径，不要安装本地识别引擎或修改其他语音软件的快捷键。
- 检查系统和已有安装。 执行
uname -m、python3 --version、id -nG和command -v omarchy。检查${XDG_CONFIG_HOME:-$HOME/.config}/omarchy/plugins/md.lifeos.doubao-say、${XDG_DATA_HOME:-$HOME/.local/share}/doubao-say/app，以及 XDG applications 目录下的doubao-say.desktop。已有安装应沿用原路径；同时包含bundle.json和.doubao-managed.json的是安装包版本，Git 工作区使用源码安装路径。 升级前结束录音，并禁用插件或退出独立应用。 - 选择可访问的安装来源。 优先使用用户提供的源码目录或匹配的安装包。目标仓库为
https://github.com/quanru/doubao-say。无法访问时说明原因并使用用户提供的本地源码； 不要编造下载地址，也不要把上游项目 的安装包当成豆包说。 - 从下面选择一种方式安装。 保留源码或解压后的安装器路径。以正常桌面用户运行， 系统依赖安装可能需要管理员认证。
从 Git／源码安装 Omarchy 插件：
omarchy plugin add https://github.com/quanru/doubao-say.git
# 如提示启用，先选择不启用；已有插件跳过 plugin add。
cd "${XDG_CONFIG_HOME:-$HOME/.config}/omarchy/plugins/md.lifeos.doubao-say"
./install.sh
./start.sh不要在已安装的插件目录中创建 .venv，Omarchy 不允许其中存在符号链接。
用户完成引导并退出前台应用后，执行
omarchy plugin enable md.lifeos.doubao-say。
已有 Git 插件需先禁用，再执行 omarchy plugin update md.lifeos.doubao-say，
重新执行依赖安装和检查后启用。
在 Arch／Omarchy 上从已有源码目录安装独立应用：
在源码目录执行以下命令。安装器优先使用 omarchy pkg add，普通 Arch 则使用
sudo pacman -S --needed。
./install.sh
./start.sh保留源码目录，桌面入口会指向它。只有 Omarchy 插件已禁用时，才在设置中开启独立应用 自启动。其他发行版需先安装对应系统依赖；自动粘贴支持 Hyprland 和原生 X11。 请在实际使用的桌面会话中执行安装检查，以便选择对应的剪贴板及 GTK 后端依赖。
使用独立应用或插件安装包：
选择 CPU 架构、Python 版本匹配的 app 或 plugin 包；在安装包与校验文件所在目录执行
sha256sum -c SHA256SUMS --ignore-missing，确认选中的文件校验成功。解压至新目录，
进入解压后的目录执行：
./install.sh --check
./install.sh安装器会先展示缺失的 Arch／Omarchy 系统依赖，并在确认后安装。安装包包含离线 Python wheel，
源码路径使用系统包。插件安装包也应在完成引导后才启用。安装包版本通过新版匹配安装包
覆盖升级，不使用 omarchy plugin update。卸载时使用解压目录里的
./install.sh --uninstall；Git 插件则使用
omarchy plugin remove md.lifeos.doubao-say。
- 与用户完成权限和首次引导。 在本 Omarchy 环境缺少键盘或
/dev/uinput权限时， 解释input组要求，在获得授权后执行sudo usermod -aG input "$(id -un)"，随后 注销并重新登录。用户完成豆包网页登录、麦克风检查、触发键选择和试说。 不要输出凭证或将凭证复制进仓库。 - 验证实际使用并交付结果。
--check仅验证运行前提。在临时文本编辑器文档中， 验证短按开始／再次短按结束、长按／松开、只有一个悬浮窗，以及结束后只粘贴一次。 双击回车仅在这个文档里测试。启用润色时，检查停顿预览、结束后上屏及超时使用原文。 向用户报告安装版本、路径、自启动管理方式、通过的检查和仍需用户完成的步骤。 不要仅凭单元测试就宣称实体按键或登录验收通过。
升级保留用户设置和登录数据，再分发时保留 LICENSE 和 NOTICE。
完整生命周期和恢复方法见安装说明。
开发与 AI 辅助协作遵循 DEVELOPMENT.md 和 贡献指南。Bug 修复需可复现验证，每轮界面验证保存修复前后截图； 截图无法证明的行为需补充测试或日志证据，并明确尚未验证的范围。
贡献流程和统一检查命令 make check 见贡献指南，
另见安全报告流程和变更记录。
旧 Debian 打包脚本不属于本次候选版的发布路径，尚未完成新版安装验收。
make test
.venv/bin/python -m compileall -q src/doubao_input packaging
.venv/bin/python -m pip wheel -w dist/wheelhouse -r packaging/runtime-requirements.txt
python3 packaging/build-release.py原生 X11 的可选桌面测试会创建独立 Xephyr/XFWM 会话，检查中文、多行粘贴、终端快捷键、 取消、焦点变化及悬浮窗焦点。测试使用独立剪贴板，不依赖 CopyQ；安装 PyQt6 和 Electron 后 还会检查这两种界面。运行期间请勿打字：
timeout --kill-after=5s 50s env PYTHONPATH=src python3 tests/manual/x11.py --run需要 Xephyr、xfwm4、xfce4-terminal、xdotool、xclip 和 /dev/uinput 权限。
真实麦克风听写、其他窗口管理器及 Hyprland 仍需分别验收。
安装包目前是本地产物，不是已发布版本。分发前需验证安装流程及真实桌面使用流程。 构建和安装脚本都不会自动上传 GitHub。
每次推送和 Pull Request 都会在 Python 3.11–3.14 上测试核心逻辑，并运行完整的 GTK 测试、代码检查、编译、包元数据校验和密钥扫描。覆盖率按整个源码包的分支覆盖率 计算，当前真实门槛为 55%；GTK 界面、WebKit 和实体设备路径没有从分母中排除。
当前发布版本为 1.2.0。只有 v1.2.0 标签与所有内置版本完全一致时，CI 才能发布。
标签发布会为 Python 3.11–3.14 分别构建独立应用与 Omarchy 插件离线包，并附带 SHA-256
校验文件。手动启动发布工作流只构建供检查的产物，不会公开发布。真实登录、麦克风、
全局按键及桌面行为仍需按人工验收清单检查。
豆包说使用独立的 Git 历史；继承代码的上游署名和许可声明仍予保留。
豆包说基于 wurong98/doubao-input-for-linux 开发。 该项目继承的署名说明将 ASR 和登录组件的来源标注为 lilong7676/doubao-murmur。感谢两个项目及其贡献者。 LICENSE 保留原有版权署名和 MIT 许可全文。 NOTICE 记录已知的代码来源、继承的 MIT 署名，以及软件许可与豆包服务条款之间的区别。 随包依赖见依赖清单。