Omi 朗读小助手

有温度的文本朗读小助手

macOS 源码构建版 · Developer Preview · BYOK

一个以 Codex 为首个场景的 macOS 云端朗读伴随工具。复制需要理解的 AI 回答或其他文本，可直接朗读中文，也可先把英文翻译为中文再自动朗读。

当前版本为 v0.2.0：保留 ⌥⇧Q 直接朗读，并新增 ⌥⇧W 英译中后自动朗读。两个入口都只在用户主动触发后读取本次剪贴板，不会自动读取完整对话。

快速概览

项目	说明
工具名称	Omi 朗读小助手（`omi-read-aloud`）
适配平台	Apple Silicon Mac，macOS 13+；当前为源码构建版
解决的问题	在 Codex、Kimi Work、豆包等 macOS 桌面 AI 中，把用户主动复制的长回复或其他文本转为可控制的自然中文语音
工作方式	`⌘C` 复制后按 `⌥⇧Q` 直接朗读，或按 `⌥⇧W` 将英文翻译为中文并自动朗读
语音能力	豆包 TTS 1.0、V3 HTTP 单向流式播放，支持 `1.0×–2.0×` 离散语速
文本预览	设置页内临时查看手动粘贴的纯文本；只保留在当前 Omi 进程内，不触发朗读
隐私特性	API Key 存入 macOS Keychain；不保存用户文本、音频或朗读历史，音频仅在内存中流式播放
开源协议	MIT License
当前源码	`v0.2.0` Developer Preview

v0.2.0 重点更新

英文翻译朗读：复制英文后按 ⌥⇧W，使用 doubao-seed-2-0-lite-260428 生成简体中文译文，并自动调用现有豆包语音合成 1.0。
复用朗读面板：同一窗口显示英文、中文译文和一个任务状态；翻译中、译文朗读中、暂停与完成不会重复展示。
独立凭据：翻译与语音合成分别配置 API Key，并保存到不同的 macOS Keychain 条目。
可选自动朗读：翻译配置可关闭“自动朗读译文”；关闭后停在翻译结果页，不自动产生语音合成用量。
重复翻译缓存：当前进程内缓存上一条成功译文；原文、模型和 API 地址一致时直接复用，不重复消耗翻译 Token。
进程内文本：英文和译文不写入文件、历史或日志，退出 Omi 后清空。

v0.1.3 重点更新

开机启动：设置页新增“应用偏好 > 开机启动”开关，可直接管理 macOS 登录项。
记住语速：首次启动默认 1.2×；之后自动恢复上次选择的有效倍率。
更清晰的播放状态：朗读中使用四条细线波形反馈播放状态；暂停时使用中性扬声器图标，状态文字与图标按同一基线对齐。
命名统一：应用名称更新为“Omi 朗读小助手”，菜单退出项简化为“退出 Omi”。

v0.1.2 重点更新

临时文本预览：在设置中切换到“文本预览”，手动粘贴需要对照的纯文本；支持滚动、选择、系统复制和清空。
进程内隔离：预览内容不进入 currentText、TTS、PCM 队列或朗读缓存，退出 Omi 后自动清空。
朗读成本保护：在本地过滤高置信度 Markdown、HTML 和制表符表格；纯表格及无有效文字内容不会请求豆包。
长文本安全分段：按句子或自然停顿边界分段并顺序朗读，降低单次请求过长造成的失败风险。

三步开始朗读

打开 Omi；首次使用时在设置页配置自己的豆包 TTS。
在 Codex、Kimi Work、豆包或其他桌面应用中选中文本，按 ⌘C。
按全局快捷键 ⌥⇧Q，Omi 自动读取当前剪贴板并朗读。

flowchart LR
    A[选中文本] --> B[⌘C 复制]
    B --> C[⌥⇧Q]
    C --> D[Omi 读取剪贴板纯文本]
    D --> E[豆包 TTS 1.0]
    E --> F[本机流式播放]

也可以点击菜单栏的朗读图标，选择“朗读剪贴板内容”或“翻译并朗读剪贴板”。

控制器挡住内容时，点击窗口左上角红色按钮即可隐藏；当前朗读和后台服务不会因此退出。隐藏后再次按 ⌥⇧Q 会启动朗读但保持面板隐藏；点击 Omi 菜单栏图标或重新打开已运行的 App 才会恢复控制器。只有选择“退出 Omi”才会终止后台服务。

Codex 当前不可靠地支持 macOS Services，因此右键“朗读选中内容”不是 Codex 主入口。原生文本应用仍可使用 Services 兼容入口。

桌面应用兼容性

Omi 的主链路只依赖 macOS 系统剪贴板中的纯文本，不依赖 Codex、Kimi 或豆包的内部接口。只要桌面应用能把选中文本复制到系统剪贴板，就可以使用 ⌘C → ⌥⇧Q 发起朗读。

2026-07-29 已完成人工验证：

Codex 桌面端
Kimi Work 桌面端
豆包桌面端

应用升级后必须回归以上三条链路，避免后续改动把朗读入口绑定到单一应用。

适合的使用场景

听 Codex 桌面端的长方案、代码解释或调试建议，减少持续盯屏阅读。
听 Kimi Work、豆包等桌面 AI 的调研、总结或长文本结果，同时继续处理其他工作。
在任何能把选中文本复制到 macOS 系统剪贴板的桌面应用中，按需朗读用户主动选择的内容。

V1 能力

应用级全局快捷键 ⌥⇧Q
英译中并自动朗读快捷键 ⌥⇧W
菜单栏入口和独立悬浮播放器
macOS 原生关闭、最小化和缩放窗口控件
控制器可隐藏后继续后台运行，点击 Omi 菜单栏图标即可重新显示
悬浮面板支持暂停与原位置续播；菜单栏保留独立的“停止朗读”和“退出 Omi”
1.0×–2.0× 离散语速滑杆，每次调整 0.1×
24 pt 高胶囊轨道；首次启动默认语速 1.2×，之后恢复用户上次选择
设置页“应用偏好”提供开机启动开关，直接管理 macOS 登录项
新请求把当前倍率发送给豆包；准备、朗读和暂停期间禁用滑杆，结束后才能为下一次朗读选择语速
豆包 TTS 1.0、V3 HTTP 单向流式音频
完整朗读成功后，在当前 Omi 进程内缓存上一条 PCM；相同文本和配置再次朗读时直接本地重播，不重复请求豆包
API Key 保存到 macOS Keychain
标题栏原生设置入口，可统一配置模型、API Key、Resource ID 和音色 ID
API Key 不回显；模型、Resource ID、音色 ID 从下一次朗读开始生效
设置模式提供“朗读配置 / 翻译配置 / 文本预览”三个 Tab；预览只在用户聚焦文本框并执行系统粘贴后写入，退出 Omi 后清空
文本预览支持滚动、选择、系统复制和内嵌清空；数字与圆点列表保留为纯文本标记，并使用悬挂缩进对齐换行
朗读前在本地过滤高置信度 Markdown、HTML 和制表符表格；纯表格及无有效文字内容不会请求豆包
长文本按自然边界安全分段后顺序朗读，每个请求片段最多 900 UTF-8 字节
状态或错误即使只显示两行，也可通过 ⌘C 或右键“复制完整信息”复制完整内容
流式内存播放，不保存文本或音频文件

当前限制

启动前需要先按 ⌘C 复制选中文本。
长文本已在本地安全分段；尚未实现后续分段预取。
当前是本机开发包，尚未签名、公证或制作安装器。
当前只支持 Apple Silicon Mac；尚未提供 Intel 或 Universal Binary。
需要 macOS 13+ 与版本匹配的 Xcode Command Line Tools；首次构建前请确认 swift --version 和 xcrun --show-sdk-version 可正常配合。

技术参数

项目	当前值
最低系统	macOS 13
产品模型	`seed-tts-1.0`
Resource ID	`volc.service_type.10029`
默认音色	`zh_female_shuangkuaisisi_moon_bigtts`
TTS 接口	`/api/v3/tts/unidirectional`
翻译模型	`doubao-seed-2-0-lite-260428`
翻译接口	`/api/v3/responses`
音频	24 kHz、单声道 PCM

配置豆包 TTS

Omi 当前使用豆包 TTS 1.0。使用前需要在自己的火山引擎账户中开通“语音合成 1.0”，并自行承担该账户产生的费用、配额与限流。

建议按以下顺序配置：

在火山引擎控制台开通“语音合成 1.0”。
在控制台的快速 API 接入页获取自己的 API Key。
打开 Omi 设置页，填写模型、API Key、Resource ID 和音色 ID。
保存后复制一段非敏感文本，按 ⌥⇧Q 完成首次朗读验证。

点击 Omi 控制器标题栏右侧的设置按钮，可统一配置：

模型
API Key
Resource ID
音色 ID

设置页下方的“应用偏好”可单独设置开机启动。

“保存”位于音色 ID 下方。API Key 留空表示保持现有 Key；已保存的 Key 不会回显。模型、Resource ID 和音色 ID 会保存到本机偏好，并从下一次朗读开始生效。

当前 V3 接口没有独立的 model 请求字段：模型用于标识配置，实际调用哪项语音合成服务由 Resource ID 决定。

命令行配置仍作为维护回退入口。API Key 从标准输入写入 Keychain，不通过命令行参数传递：

swift run readaloud-config status
swift run readaloud-config set
swift run readaloud-config delete

set 会在终端中提示输入 API Key。不要把真实 Key 写入仓库、截图、日志、文档或聊天记录。

配置英文翻译

在 Omi 设置页切换到“翻译配置”，填写模型、Responses API 地址和翻译 API Key，并选择是否“自动朗读译文”。默认模型与地址已预填，自动朗读默认开启且开关即时保存；API Key 留空保存表示保持现有值，已保存的 Key 不回显，也不会与 TTS Key 共用。

保存后复制一段非敏感英文，按 ⌥⇧W 验证“正在翻译 → 译文朗读中 → 译文朗读完成”链路。该操作会产生大模型翻译和语音合成两部分用量。

构建与安装

前置条件：

Apple Silicon Mac
macOS 13+
Xcode Command Line Tools（与当前 macOS SDK 匹配）
已开通豆包 TTS 服务的个人账户（仅在实际朗读时需要）

当前源码已使用 Xcode 26.6、Swift 6.3.3 和 macOS 26.5 SDK 完成构建验证。若系统仍默认使用独立的 Command Line Tools，可在当前终端会话显式选择完整 Xcode，不需要修改系统全局设置：

export DEVELOPER_DIR="/Applications/Xcode.app/Contents/Developer"

在项目根目录执行：

./build/build-service.sh
mkdir -p "$HOME/Applications"
ditto build/ReadAloudService.app "$HOME/Applications/ReadAloudService.app"
open "$HOME/Applications/ReadAloudService.app"

构建产物已内置 Omi 应用图标。若希望在系统“应用程序”目录中直接双击 Omi，可继续构建并安装独立启动器：

./build/build-launcher.sh
ditto build/Omi.app /Applications/Omi.app

启动器只负责打开个人 Applications 目录中的安装版，使用独立 Bundle ID，不接触 API Key。安装后也可通过 Spotlight 或 Dock 打开，无需每次通过终端启动。

只运行 Applications 目录中的安装版。不要同时打开项目 build 目录中的 App，否则同一 Bundle ID 可能被 macOS 注册两次，导致服务或快捷键命中旧版本。

让桌面 AI 协助安装

如果你使用的桌面 AI 具备终端操作能力，可复制以下提示词，让它先阅读本仓库的安装说明，再在你的 Mac 上协助完成操作：

请从 https://github.com/PolinniZhong/omi-read-aloud 安装 Omi：按 README 在我的 macOS 上完成环境检查、源码构建、安装和启动；不要读取或输出任何 API Key，遇到系统权限、覆盖安装或其他需要确认的操作时先询问我。

不同桌面 AI 的终端与系统权限能力不同；请在它请求权限时自行确认，并在安装后按“最短验证”检查本机环境。

最短验证

以下命令不需要真实 API Key，也不会发起网络请求：

swift run readaloud-config protocol-test
swift run readaloud-config payload-test
swift run readaloud-config translation-payload-test
swift run readaloud-config translation-cache-test
swift run readaloud-config settings-test
swift run readaloud-config preview-paste-test
swift run readaloud-config reading-text-test
swift run readaloud-config diagnostics-test
swift run readaloud-config session-test
swift run readaloud-config cache-test

protocol-test：验证二进制协议解析。
payload-test：离线验证 HTTP 与 WebSocket 请求默认发送 speech_rate=20（1.2×）。
translation-payload-test：离线验证 Responses API 的模型、纯文本输入、Bearer Header 与 output_text 解析。
translation-cache-test：离线验证相同翻译命中，以及原文或模型变化时缓存失效。
settings-test：离线验证本机非敏感配置读写，以及上次有效语速的恢复。
preview-paste-test：离线验证 HTML 数字/圆点列表只恢复为普通纯文本标记。
reading-text-test：离线验证表格过滤、无有效文字拦截和长文本安全分段。
diagnostics-test：离线验证日志脱敏与结构化服务错误输出。
session-test：离线验证零 PCM、播放后流失败、连续请求隔离、硬停止、暂停/续播和播放 drain 状态。
cache-test：离线验证完整音频写入内存缓存、相同请求重播、配置隔离，以及失败或超限音频不缓存。

audio-test 依赖本机可用的音频设备。http-smoke 会读取 Keychain 中已保存的 Key 并向豆包发送固定测试文本；仅在你自行完成配置后手动运行。

常见问题 FAQ

如何在 Codex 桌面端朗读复制的 AI 回复？

在 Codex 桌面端选中需要收听的文本，按 ⌘C，再按 ⌥⇧Q。Omi 读取本次主动复制到 macOS 系统剪贴板的文本并发起朗读；若同时存在 HTML 表示，只在本地用于识别表格，不依赖 Codex 的内部接口或 macOS Services 作为主入口。

Mac 上有什么工具可以朗读 AI 回复或长文本？

Omi 是一个 macOS AI 朗读工具，面向 Codex、Kimi Work、豆包及其他可复制纯文本的桌面应用。它使用你自行配置的豆包 TTS 1.0，以流式方式播放自然中文语音，并提供 1.0×–2.0× 的离散语速控制。

浏览器朗读插件无法处理桌面 App 的文本怎么办？

浏览器插件通常依赖网页内容。Omi 使用系统剪贴板：只要桌面 App 能将选中文本复制到 macOS 系统剪贴板，就可以通过 ⌘C → ⌥⇧Q 发起朗读；无需读取应用窗口、完整对话或内部页面结构。