quanru/doubao-say · 上手攻略
- 仓库：quanru/doubao-say
- 链接：https://github.com/quanru/doubao-say
- 分类：Linux 效率工具 · 语音输入
- 作者：Tom
- 更新：2026-09-18
这是什么
doubao-say 是一款面向 Linux（Hyprland/Wayland 和原生 X11） 的独立语音输入应用，基于 GTK4 构建，默认使用豆包网页账号识别（免费），也可切换到火山引擎官方 Seed ASR 2.0 API（按量付费）。核心功能是让你在任意 Linux 应用里用快捷键触发语音输入，识别结果自动粘贴或直接打字进目标窗口。
它不是一个 AI 对话工具，而是一个本地化的语音→文字管道：录音 → ASR 识别 → 文本输入，附加可选的 LLM 润色（Voice polishing）功能，可调用 OpenAI 兼容端点（推荐 DeepSeek Flash）对原始识别结果做轻度润色（去填充词、补标点、调整语序）。
解决什么问题
Linux 桌面环境下语音输入长期缺乏成熟方案： - Wayland 独占Compositor（典型如 Hyprland）下，大多数跨平台语音输入工具无法正常工作 - 剪贴板安全：许多工具要求剪贴板权限或云端处理，用户不信任 - 豆包账号能力未在 Linux 桌面端释放：豆包在移动端有语音输入，但桌面 Linux 没有官方客户端 - 触发延迟：部分方案录音后才开始处理，导致第一个字丢失
doubao-say 的设计解决了这些问题：触发键按下即开始本地预录（preroll），确保第一个字不丢失；豆包网页识别免费使用；本地离线存档，API key 不上传日志；支持 Hyprland layer-shell 浮层，不抢占窗口焦点。
快速安装
⚠️ 最低支持版本：Arch Linux / Omarchy（其他发行版按依赖手动适配）。
方式一：离线归档安装（推荐）
- 从 dist/ 目录 下载对应平台的归档文件（含离线安装脚本和 Python wheels）
- 校验 SHA256：
sha256sum -c SHA256SUMS - 解压并运行安装脚本：
# 以 Hyprland 为例（解压后进入目录）
./install.sh --check # 只检查依赖，不安装
# 确认依赖列表后
./install.sh --yes # 自动安装依赖并配置
⚠️ --check 是只读检查，不写入任何文件，确认依赖列表后再执行完整安装。
方式二：Omarchy 插件安装
omarchy plugin add https://github.com/quanru/doubao-say.git
cd ~/.config/omarchy/plugins/md.lifeos.doubao-say
./install.sh
# ⚠️ 添加时不启用（decline enablement），等依赖装完再启用
方式三：Arch Linux 手动安装依赖
Hyprland/Wayland：
sudo pacman -S --needed \
python python-gobject python-cairo \
gtk4 gtk4-layer-shell webkitgtk-6.0 \
pipewire wl-clipboard portaudio
原生 X11：
sudo pacman -S --needed \
python python-gobject python-cairo \
gtk4 webkitgtk-6.0 pipewire portaudio \
xdotool xclip # 可选：支持自动粘贴
前置权限配置（Hyprland/Omarchy）
键盘事件需要读取权限，/dev/uinput 需要写入权限：
sudo usermod -aG input "$USER"
# 然后注销并重新登录
# ⚠️ 切勿以 root 运行本应用
核心用法
首次配置（四步 onboarding）
- 选择识别服务：Settings → Recognition service - 默认：豆包网页账号（免费，需扫码登录） - 可选：火山引擎 Seed ASR 2.0 API（需自行申请 key）
- 选择麦克风：选择 PipeWire 输入设备，运行 3 秒设备检测
- 设置触发键：选择 Fn / Ctrl / Alt / 功能键预设，或选"录制快捷键…"手动录制组合键
- 语音测试：在应用内测试，确认识别正常后 Finish setup
使用方式
| 操作 | 效果 |
|---|---|
| 按下触发键（短按） | 开始录音，松开结束，粘贴识别结果 |
| 按住触发键 | 按住期间持续录音，松开后粘贴 |
| 录音中双击 / Esc / 取消手势 | 丢弃当前录音缓冲 |
| 触发键在最终润色期间再次按下 | 丢弃润色结果，使用原始识别文本 |
桌面兼容矩阵
| 桌面环境 | 自动粘贴 | 直接打字 |
|---|---|---|
| Hyprland / Wayland | wl-copy（需要已知窗口） |
可选 wtype |
| 原生 X11 | 可选 xclip+xdotool（需要已知窗口） |
不可用，选剪贴板粘贴 |
| 其他 Wayland Compositor | 保留结果供手动复制 | 不可用 |
Voice Polishing（可选 LLM 润色）
Settings → Trigger key → 开启 Voice polishing · Experimental，配置：
- Base URL（OpenAI 兼容端点）
- API Key
- Model（推荐 deepseek-v4-flash，⚠️ 关闭深度思考/推理模式）
- 中文/英文提示词模板（可编辑，可恢复默认）
润色在识别后 1.2 秒静默自动开始（检测到 1.2 秒安静且文本稳定），最终粘贴润色结果；超时 5 秒自动降级为原始识别文本。
⚠️ 深度思考必须关闭：DeepSeek Flash 等推理模型在thinking模式下延迟过高，会导致润色超时或粘贴延迟。
典型适用场景
- Linux Hyprland 用户：在没有官方桌面语音输入的情况下，用豆包账号实现免费语音输入
- 长文本录入：在终端或任意窗口中说一段话，自动转文字并粘贴，省去打字
- 键盘重度用户：保持手指在键盘上的同时，用语音输入大段内容
- API 开发者：切换到火山引擎官方 ASR，用自己的 API key 做生产级语音输入
坑与注意
⚠️ 以下为已知限制：
- 仅支持 Linux：不支持 Windows / macOS；README 明确说明项目范围仅 Linux（含 Wayland 和 X11）
- 豆包账号识别为非官方用途：豆包网页账号识别是绕过官方桌面客户端缺失的变通方案，非豆包官方功能，存在账号风险（建议使用独立的火山引擎 API key 更稳定）
- 直接打字速度有限：实测约 1760 字符需 8 秒逐步打字，新行和 Tab 会被映射为回车和 Tab 键，可提交消息或执行命令——但焦点丢失会停止输入，无法撤回已输入内容
- X11 自动粘贴依赖窗口焦点：需要提前知道目标窗口 PID/focus，窗口切换会导致粘贴到错误位置
- wtype 需要 Wayland 虚拟键盘实现：仅在 Hyprland 上测试过，其他 Wayland compositor 兼容未知
- Omarchy 插件禁止虚拟环境：
omarchy plugin树下禁止创建 venv，否则被拒绝；使用系统 Python - 安装时禁止 root：README 明确说切勿以 root 运行；键盘监控功能在 input 组权限下工作
- 与归档安装勿混用：Git 安装和归档安装插件 ID 相同，混用会导致冲突
与同类对比
| 工具 | 平台 | ASR 来源 | 润色 | 备注 |
|---|---|---|---|---|
| doubao-say | Linux (Wayland/X11) | 豆包网页/火山引擎 | 可选 LLM 润色 | Hyprland 原生支持 |
| Speech Note | Linux | 私有 ASR | 无 | 仅支持部分地区 |
| Coqui STT + say | Linux | 本地 Coqui | 无 | 需要本地模型 |
| Dragonbox | Linux | 豆包 | 无 | 非官方项目 |
| ** Voscribe** | 跨平台 | 各大 ASR | 有 | 商业闭源 |
核心差异：doubao-say 是当前 Linux Hyprland 生态下唯一基于豆包免费识别的 GTK4 语音输入，且提供可选 LLM 润色链路；竞品多为本地模型（质量低）或商业闭源（需付费）。
一句话结论
Linux Hyprland/Wayland 用户需要一款免费、免配置、基于豆包账号的语音输入工具，doubao-say 是目前最原生的选择——但它是 Linux 独占，依赖键盘权限且直接打字速度有限；生产级使用建议切换到火山引擎 Seed ASR API 获得更稳定的识别质量。