oma-voice

语音技能 - 通过 Voicebox 进行本地 TTS 和 STT

调度

目标

通过 Voicebox MCP 服务驱动本地应用，让任何兼容 MCP 的 Agent 无需调用云服务商即可朗读文本（TTS）或聆听语音（STT）。此技能统一意图路由、语音配置解析、输出布局和防护措施；引擎、语音克隆 UI、录音归档和故事编辑器则由 Voicebox 自行管理。

意图特征

• 用户要求生成语音、朗读文本、制作配音，或将文本转换为 mp3 或 wav。
• 用户想把音频文件转录为文本、会议记录或文字稿。
• 用户要求在长任务完成或工作流步骤受阻时收到语音通知。
• 其他技能需要本地音频生成基础设施。

适用场景

• 为 Agent 任务完成或受阻生成简短的通知音频。
• 为应用和内容制作配音、朗读音频或音频素材（mp3 或 wav）。
• 将本地音频文件（mp3、wav、m4a、webm、flac）转录为 Markdown。
• 使用不同的配置 ID，对同一段文本重新生成语音，以比较语音配置。

不适用场景

• 云端 TTS 或高保真多语言云端语音 -> 不在范围内；未来可扩展支持多个服务商。
• 在终端中进行实时麦克风听写 -> 使用 Voicebox 应用内置的快捷键听写功能。
• 上传语音克隆样本和创建配置 -> 在 Voicebox 桌面应用 UI 中完成。
• 视频合成、音乐、声音设计 -> 不在范围内。
• 故事编辑器多语音时间线编排 -> 使用 Voicebox 应用 UI。

预期输入

• TTS：文本（每次调用 <= 5000 个字符）、可选的配置 ID、引擎、语言和输出路径。
• STT：音频文件路径（绝对路径或相对于 $CWD 的路径）、可选的语言提示。
• 通知：简短消息（<= 240 个字符），配置 ID 从配置中解析。

预期输出

• TTS：音频文件（wav — Voicebox 的原生 TTS 输出格式；可选通过本地 ffmpeg 转码为 mp3），保存至 .agents/results/voice/{timestamp}-{shortid}/output.{wav|mp3}，并附带 manifest.json。
• STT：transcript.md，保存至 .agents/results/voice/transcripts/{timestamp}-{shortid}/，并附带 manifest.json。
• 通知：通过 Voicebox 临时播放；默认不写入磁盘。

依赖项

• 已安装并在本地运行的 Voicebox 桌面应用。
• 已注册 Voicebox MCP（claude mcp add --transport http voicebox http://127.0.0.1:17493/mcp）。
• 仅 TTS：已在 Voicebox 应用 UI 中创建至少一个语音配置。
• 仅 TTS：可选，为所选配置预先下载引擎模型。

控制流特性

• 按模式（notify、asset、transcribe）、语言和配置可用性进行分支处理。
• 通过 MCP 工具调用 voicebox，并使用 REST GET /health 作为握手探测。
• 读取输入音频文件，并写入生成的音频和清单文件。
• 首次成功调用 tools/list 后，缓存已发现的 MCP 工具名称。

结构流程

入口

1. 检测请求模式：通知、资源 TTS 或转录。
2. 通过 MCP 握手或 GET /health 确认 Voicebox 可访问。
3. 仅在首次运行时调用 MCP tools/list，并缓存解析出的工具名称。
4. 对于通知或资源 TTS，解析目标语音配置 ID。对于转录，验证音频输入后继续，无需配置。

场景

1. 准备：验证文本长度、音频时长、语言、输出路径和配置 ID。
2. 获取：如果缺少必要信息，运行一次澄清流程。
3. 执行：使用解析后的参数调用相应的 MCP 工具（TTS 或 STT）。
4. 验证：确认响应包含音频输出或转录内容。验证清单字段。
5. 完成：在输出文件旁写入 manifest.json。向用户报告路径或转录内容。

状态转换

• 如果无法访问 voicebox，显示安装或启动提示，然后退出。不要尝试自动重新启动。
• 如果 TTS 请求没有可用配置，请引导用户前往 Voicebox 应用 UI 创建配置，然后退出。转录请求不需要配置。
• 如果 TTS 请求超过 5000 个字符，询问用户是截断还是拆分。v1 中不要自动分块。
• 如果 STT 输入超过 30 分钟，询问是否继续。不要自动拆分。
• 如果所选引擎模型尚未加载，在触发下载前询问用户。

故障与恢复

故障	恢复
Voicebox 应用未运行	显示安装／启动提示，退出代码为 5
TTS 没有语音配置	显示“在 Voicebox 中创建配置”提示，退出代码为 3
缺少引擎模型	在触发下载前询问
输出路径位于 $PWD 之外	使用明确请求的路径；仅当目标路径不明确或会覆盖无关数据时才询问
TTS 超过 5000 个字符	询问用户是拆分还是截断
STT 超过 30 分钟	仅当请求的时长或资源成本尚未明确时才确认
MCP 工具名称发生变化	重新运行 tools/list 并更新缓存
SIGINT	中止 MCP 调用，不写入部分输出

退出

• 成功：音频文件或转录文本已生成，清单完整，并且已报告路径。
• 部分成功：已生成输出，但触发了护栏警告（长度、磁盘、模型回退）。
• 失败：没有输出，并明确说明阻碍因素（身份验证、配置、引擎、网络）。

逻辑操作

操作

操作	SSL 原语	依据
验证模式和输入	VALIDATE	execution-protocol.md 中的澄清协议
解析 TTS 语音配置	SELECT	voicebox_list_profiles + 配置默认值
健康检查	READ	MCP 握手或 GET /health
生成语音	CALL_TOOL	MCP voicebox_speak
转录音频	CALL_TOOL	MCP voicebox_transcribe
写入输出和清单	WRITE	音频或转录文本以及 manifest.json
检查结果	VALIDATE	输出是否存在、时长、清单字段
报告结果	NOTIFY	面向用户的最终摘要

工具和手段

• http://127.0.0.1:17493/mcp 上的 Voicebox MCP 服务。
• 用于健康检查和音频检索的 REST 接口（GET /health、GET /audio/{generation_id}）。
• 资源引用：语音矩阵、提示词技巧、执行协议、检查清单。

标准命令路径

# 1. MCP handshake or REST health
GET http://127.0.0.1:17493/health  ->  200 OK

# 2. Discover tool names on first run
MCP tools/list                      ->  cache real names

# 3. TTS only: resolve profile
MCP voicebox_list_profiles          ->  pick profile by name or config default

# 4. Generate or transcribe (STT skips profile lookup and model-status check)
MCP voicebox_speak     { text, profile, language?, engine?, personality? }
MCP voicebox_transcribe { audio_path | audio_base64, language?, model? }

# 5. Fetch the generated audio (MCP has no save-to-disk; TTS output is wav)
GET http://127.0.0.1:17493/audio/{generation_id}  ->  wav bytes

# 6. Persist output + manifest
.agents/results/voice/<timestamp>-<shortid>/output.wav + manifest.json
.agents/results/voice/transcripts/<timestamp>-<shortid>/transcript.md + manifest.json

MCP 工具映射（已根据 Voicebox 0.5.0 验证）

用例	MCP 工具	REST 后端
TTS 生成	voicebox_speak	POST /speak
STT 转录	voicebox_transcribe	POST /transcribe
配置列表	voicebox_list_profiles	GET /profiles
录制内容列表	voicebox_list_captures	GET /history（录制内容视图）

MCP 未提供的工具（仅 REST）：模型状态（GET /models/status）、音频文件服务（GET /audio/{generation_id}）、按版本获取音频（GET /audio/version/{version_id}）。需要时，该技能会通过环回 HTTP 调用这些接口。

关于 voicebox_speak 的说明：

• 必填：text。可选：profile、engine、language、personality（bool）。
• 音频会通过用户的扬声器播放，并自动保存到 Captures / History 面板。MCP 工具本身没有 save_to_disk 开关；若要保存本地副本，请获取 GET /audio/{generation_id}（Voicebox TTS 始终存储 wav）。
• 如果未在 Voicebox Settings 中设置默认配置，则必须提供 profile=。

关于 voicebox_transcribe 的说明：

• 必须且只能提供 audio_base64 或 audio_path 其中之一（仅限环回）。可选：language、model。

资源范围

范围	资源目标
LOCAL_FS	输入音频、生成的音频、转录文本、清单文件
PROCESS	本地 Voicebox 应用子进程（由用户管理）
NETWORK	仅向 127.0.0.1:17493 发起环回 HTTP 请求
MEMORY	缓存的 MCP 工具名称、已解析的配置元数据
CREDENTIALS	无。Voicebox 在本地运行，无需密钥。

前提条件

• Voicebox 应用正在运行，且 MCP 握手成功。
• 仅限 TTS：至少存在一个语音配置。
• 仅限 TTS：已加载所选引擎模型，或用户批准下载。
• 除非明确允许，否则输出目录必须位于 $PWD 内。

影响和副作用

• 在 .agents/results/voice/ 下创建音频文件、转录文本和清单文件。
• 触发本地 Voicebox 生成任务，消耗 CPU 或 GPU 资源。
• 用户批准后，可能会触发引擎模型下载。
• 不会调用任何云服务，也不会产生外部网络流量。

防护措施

1. 必须使用 Voicebox：如果 MCP 握手或 GET /health 失败，则退出并提供一次性安装或启动提示。不要重试，也不要自动重新启动。
2. 仅 TTS 需要配置：仅在通知模式或资产模式下解析配置并检查 TTS 引擎。只要音频输入有效且 STT 模型可选，即使不存在配置，也可以继续转录。
3. 发现工具名称：首次调用时，调用 MCP tools/list 并缓存已解析的名称。同一会话中的后续调用复用该缓存。
4. 长度限制：每次 TTS 调用最多 5000 个字符；达到 2000 个字符时发出警告。STT 输入最长 30 分钟。v1 不会自动分块或拆分。
5. 自动调用透明度：仅当当前任务超过 auto_notify_after_sec（默认值为 60s）时，才自动触发通知。此阈值由 Agent 根据指导自行判断——没有钩子会测量任务时长——因此应在长任务完成或受阻时酌情应用。生成音频前，始终用一行简短文字说明意图。
6. 路径安全：明确指定的输出路径即表示授权写入该路径。执行依赖于该路径的写入前，先厘清歧义或是否会替换不相关的数据；保留必需的 CLI 路径标志。
7. 取消：SIGINT 会中止 MCP 调用，且不会写入任何部分输出。
8. 持久化输出必须包含清单：资产 TTS 模式和转录模式会写入 manifest.json，至少包含：skill、mode、voicebox_generation_id、text（或 transcript_preview）、profile、engine、language、format（仅限 TTS）、created_at。通知模式不受此要求限制，因为 Voicebox Captures 是其记录系统，且默认不会写入磁盘输出。
9. 不在范围内：语音克隆 UI、录音归档、故事编辑器、麦克风听写循环和云服务商均不会开放。
10. 无费用限制：Voicebox 免费。oma-image 的费用防护措施不适用。

澄清流程

调用 TTS 或 STT 前，Agent 会检查以下事项。如果缺少任何必需信息，请先向用户澄清。

TTS（资产模式）必需信息：

• 是否提供了文本内容？
• 是否提供了语音配置 ID 或语气描述？

强烈建议提供的 TTS 信息：

• 是否明确指定语言，或能否从文本中检测语言？
• 是否指定输出格式（默认 wav；mp3 需要使用本地 ffmpeg 转码）？

STT 必需信息：

• 是否提供了音频路径，且文件存在？
• 时长是否在 30 分钟以内，或用户是否批准拆分？

通知模式无需澄清。 它使用配置中的 notification_profile，并自动检测消息语言。

调用

独立使用

/oma-voice "build succeeded, 4 minor warnings"
/oma-voice transcribe ~/Downloads/standup.m4a
/oma-voice --profile prof_warm_korean "다음 단계 진행 준비됐어요"

共享基础设施（其他技能）

其他技能可以直接调用相同的 MCP 工具来请求音频输出，也可以使用文本调用 /oma-voice。没有单独的 CLI；此技能原生支持 MCP。

参考资料

• 语音引擎矩阵：resources/voice-matrix.md
• 提示词编写规则：resources/prompt-tips.md
• 执行协议：resources/execution-protocol.md
• 执行前检查清单：resources/checklist.md
• 配置：先读取 .agents/oma-config.yaml 的 voice: 部分，然后对其中未设置的键使用 config/voice-config.yaml 中的值。两个配置文件的配置项初始值均为 null，必须针对每台机器进行设置 — 请将配置写入 .agents/oma-config.yaml，因为 oma update 会覆盖技能配置。
• 上下文加载：../_shared/core/context-loading.md
• 质量原则：../_shared/core/quality-principles.md
• 设计参考：../../../docs/plans/designs/012-oma-voice.md（仅存在于源代码仓库中；全局模式安装中不包含）