技能介绍

在需要给 Agent 加语音输出时，常见路径是调云端 TTS API。这条路虽然成熟，但伴随隐私外发、按字数计费、需要维护 API Key，以及网络往返带来的延迟。对于想在本地跑通语音输出的开发者来说，这些 friction 并不总是必要的。

Piper TTS 这个 skill 提供了一个更直接的方案：把 Piper 本地推理接入 Agent 工作流，生成可直接投递的语音文件，不用离开本机，也不用处理密钥。

核心能力是：根据文本，在本地用 Piper 合成语音，并通过标准占位符把结果当作语音消息投递到支持的渠道。

关键步骤分三层：

环境准备：首次使用时，如果没有检测到 Piper，会先跑一遍 setup 脚本。这一步通过 pip 安装 piper-tts，并拉取一个默认英文男声模型 en_US-kusal-medium。
合成与投递：日常调用走 scripts/piper-speak.sh。需要提供 text（要播报的文本）和可选的 voice（Piper voice name，不传则用默认值）。脚本执行后会输出一个 MP3 文件路径，同时约定用 [[audio_as_voice]] 加上 MEDIA: 前缀作为回复格式，让 Telegram、Discord 这类渠道能识别为原生语音消息。
音色扩展：setup 完成后，可以按需下载更多 voice，例如音色更清晰的 en_US-ryan-high，或英式男声 en_GB-northern_english_male-medium。

适用场景是那些"帮我把这段话读出来""用语音回复我"的请求，尤其是对隐私、成本、调用链长度比较敏感的本地工作流。合成过程在本地完成，单次生成耗时约 0.5 到 1 秒，不需要任何 API Key。

需要注意的限制：

平台支持：目前面向 macOS（Apple Silicon 与 Intel）和 Linux，依赖 Python 3.9+。Windows 原生环境不在支持列表里。
仅本地运行：合成与文件产出都留在本机，不支持跨设备同步。
别开全局自动 TTS：在 Agent 平台配置里，不要把 messages.tts.auto 设成 "always"。这会让所有响应都被走一遍语音合成，明显拖慢整体交互节奏。正确做法是把 TTS 当作按需触发的功能。