Agentvibes Voice Skill

SKILL.md

---
slug: agentvibes-voice-skill
name: agentvibes-voice-skill
version: "1.0.0"
displayName: AgentVibes TTS语音
summary: 多Provider TTS语音合成,914+声音,个性风格、语速、效果、背景音乐、语言学习
license: MIT
description: |-
  AgentVibes TTS 语音合成客户端。集成 Piper TTS、macOS Say、Windows SAPI、Soprano 四种 Provider,
  覆盖 914+ 声音、30+ 语言。支持声音切换/预览/列出、个性风格（sarcastic/dramatic 等）、语速控制（0.5x-3.0x）、
  语音效果（reverb/echo/pitch/eq）、背景音乐、Verbosity 控制、Mute/Replay、语言学习双语播报、翻译播放、前缀文本等能力。
  免费离线、无需账号（Piper 声音需下载）。适用于 AI Agent 语音播报、内容创作配音、语言学习辅助等场景。
tags:
  - 研发工具
tools:
  - read
  - exec
---

# AgentVibes TTS

AgentVibes 是多 Provider 文本转语音（TTS）客户端,为 AI Agent 提供可切换、可定制、可离线运行的语音播报能力。免费、离线、无需账号（Piper 声音文件需从 HuggingFace 下载）。

**范围外**（本技能不做）: 实时语音识别（STT）、语音克隆训练、商业有声书分发。

## 依赖说明

### 运行环境
- **Agent平台**: 支持SKILL.md的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI等）
- **操作系统**: Windows / macOS / Linux

### 依赖项
| 依赖项 | 类型 | 是否必需 | 获取方式 |
|:-------|:-----|:---------|:---------|
| LLM API | API | 必需 | 由Agent内置LLM提供 |

### API Key 配置
需要配置对应API Key，详见上文环境配置章节

### 可用性分类
- **分类**: MD+EXEC（）


**API Key配置方式**:
```bash
export API_KEY="your_api_key_here"
```
配置后需重启会话或开启新终端生效。API Key应妥善保管,避免泄露到版本控制系统。

## 核心能力

### 声音命令


**输入**: 用户提供声音命令所需的指令和必要参数。
**处理**: 按照skill规范执行声音命令操作,遵循单一意图原则。
**输出**: 返回声音命令的执行结果,包含操作状态和输出数据。

- 执行`声音命令`操作，处理输入数据并返回结果
- 验证执行结果，确认输出符合预期格式
- 参考`声音命令`相关配置参数进行设置
### 切换声音
```bash
/agent-vibes:switch en_US-amy-medium
/agent-vibes:switch en_GB-alan-medium
/agent-vibes:switch fr_FR-siwis-medium
```

**输入**: 用户提供切换声音所需的指令和必要参数。
**处理**: 按照skill规范执行切换声音操作,遵循单一意图原则。
**输出**: 返回切换声音的执行结果,包含操作状态和输出数据。
### 列出声音
```bash
/agent-vibes:list                    # 列出全部声音
/

**输入**: 用户提供声音命令所需的参数和指令。
**处理**: 按照skill规范执行声音命令操作。
**输出**: 返回声音命令的执行结果,包含操作状态和输出数据。

### 个性与风格


**输入**: 用户提供个性与风格所需的指令和必要参数。
**处理**: 按照skill规范执行个性与风格操作,遵循单一意图原则。
**输出**: 返回个性与风格的执行结果,包含操作状态和输出数据。

- 执行`个性与风格`操作，处理输入数据并返回结果
- 验证执行结果，确认输出符合预期格式
- 参考`个性与风格`相关配置参数进行设置
### 个性风格
```bash
/agent-vibes:personality list          # 列出可用个性
/agent-vibes:personality sarcastic     # 切换讽刺风格
/agent-vibes:personality dramatic      # 切换戏剧风格
/agent-vibes:personality reset         

**输入**: 用户提供个性与风格所需的参数和指令。
**处理**: 按照skill规范执行个性与风格操作。
**输出**: 返回个性与风格的执行结果,包含操作状态和输出数据。

### 语速与效果


**输入**: 用户提供语速与效果所需的指令和必要参数。
**处理**: 按照skill规范执行语速与效果操作,遵循单一意图原则。
**输出**: 返回语速与效果的执行结果,包含操作状态和输出数据。

- 执行`语速与效果`操作，处理输入数据并返回结果
- 验证执行结果，确认输出符合预期格式
- 参考`语速与效果`相关配置参数进行设置
### 语速控制（0.5x - 3.0x）
```bash
/agent-vibes:set-speed 1.0             # 正常
/agent-vibes:set-speed 1.5             # 加速 50%
/agent-vibes:set-speed 0.8             # 减速
```

**输入**: 用户提供语速控制（0.5x - 3.0x）所需的指令和必要参数。
**处理**: 按照skill规范执行语速控制（0.5x - 3.0x）操作,遵循单一意图原则。
**输出**: 返回语速控制（0.5x - 3.0x）的执行结果,包含操作状态和输出数据。

- 执行`语速控制（0.5x - 3.0x）`操作,处理输入数据并返回结果
- 验证执行结果,确认输出符合预期格式
- 异常时参考错误处理章节进行恢复
- 关键参数: `语速控制（0.5x_-_3.0x）` 选项

### 语音效果
```bash
/agent-vibes

**输入**: 用户提供语速与效果所需的参数和指令。
**处理**: 按照skill规范执行语速与效果操作。
**输出**: 返回语速与效果的执行结果,包含操作状态和输出数据。

### 背景音乐

```bash
/agent-vibes:background-music on       # 启用
/agent-vibes:background-music off      # 关闭
/agent-vibes:background-music list     # 列出可用曲目
/agent-vibes:background-music switch jazz  # 切换到爵士曲目
```

**输入**: 用户提供背景音乐所需的参数和指令。
**处理**: 按照skill规范执行背景音乐操作。
**输出**: 返回背景音乐的执行结果,包含操作状态和输出数据。

### Verbosity 控制

控制 AI Agent 工作时的播报详尽度:
```bash
/agent-vibes:verbosity low             # 简短确认
/agent-vibes:verbosity medium          # 关键决策（默认）
/agent-vibes:verbosity high            # 完整推理过程
```

**输入**: 用户提供Verbosity 控制所需的参数和指令。
**处理**: 按照skill规范执行Verbosity 控制操作。
**输出**: 返回Verbosity 控制的执行结果,包含操作状态和输出数据。

### 静音与回放

```bash
/agent-vibes:mute                      # 静音（跨会话持久）
/agent-vibes:unmute                    # 取消静音
/agent-vibes:replay                    # 回放最近一次
/agent-vibes:replay 2                  # 回放倒数第二

**输入**: 用户提供静音与回放所需的参数和指令。
**处理**: 按照skill规范执行静音与回放操作。
**输出**: 返回静音与回放的执行结果,包含操作状态和输出数据。

### 语言与学习


**输入**: 用户提供语言与学习所需的指令和必要参数。
**处理**: 按照skill规范执行语言与学习操作,遵循单一意图原则。
**输出**: 返回语言与学习的执行结果,包含操作状态和输出数据。

- 执行`语言与学习`操作，处理输入数据并返回结果
- 验证执行结果，确认输出符合预期格式
- 参考`语言与学习`相关配置参数进行设置
### 设置母语
```bash
/agent-vibes:language english
/agent-vibes:language japanese
```

**输入**: 用户提供设置母语所需的指令和必要参数。
**处理**: 按照skill规范执行设置母语操作,遵循单一意图原则。
**输出**: 返回设置母语的执行结果,包含操作状态和输出数据。

- 执行`设置母语`操作,处理输入数据并返回结果
- 验证执行结果,确认输出符合预期格式
- 异常时参考错误处理章节进行恢复
- 关键参数: `设置母语` 选项

### 语言学习模式
```bash
/agent-vibes:learn on                  # 启用双语播报（母语 + 目标语言）
/agent-vibes:learn off                 

**输入**: 用户提供语言与学习所需的参数和指令。
**处理**: 按照skill规范执行语言与学习操作。
**输出**: 返回语言与学习的执行结果,包含操作状态和输出数据。

### Provider 管理

```bash
/agent-vibes:provider list             # 列出可用 Provider
/agent-vibes:provider switch piper     # 切换到 Piper（免费、离线、914+ 声音）
/agent-vibes:provider switch macos     # 切换到 macOS Say（仅 Mac）
/agent-vi

**输入**: 用户提供Provider 管理所需的参数和指令。
**处理**: 按照skill规范执行Provider 管理操作。
**输出**: 返回Provider 管理的执行结果,包含操作状态和输出数据。

### 能力覆盖范围

本skill还覆盖以下能力场景: TTS、语音合成、AgentVibes、语音合成客户端、Windows、SAPI、Soprano、支持声音切换、reverb、echo、pitch、语言学习双语播报、翻译播放、前缀文本等能力、免费离线、无需账号、声音需下载、适用于、语音播报、内容创作配音、语言学习辅助等场。这些能力在上述核心功能中均有对应处理逻辑。
## Provider 概览

| Provider | 平台 | 成本 | 声音数量 | 特点 |
| --- | --- | --- | --- | --- |
| **Piper TTS** | 全平台 | 免费、离线 | 914+,30+ 语言 | 推荐,声音多样 |
| **macOS Say** | 仅 macOS | 免费（内置） | 100+ 系统声音 | 零安装 |
| **Windows SAPI** | 仅 Windows | 免费（内置） | 系统声音 | 零配置 |
| **Soprano** | 全平台 | 免费 | 神经声音 | 高质量 |

## 声音命令

### 切换声音
```bash
/agent-vibes:switch en_US-amy-medium
/agent-vibes:switch en_GB-alan-medium
/agent-vibes:switch fr_FR-siwis-medium
```

### 列出声音
```bash
/agent-vibes:list                    # 列出全部声音
/agent-vibes:list first 5            # 前 5 个
/agent-vibes:list last 3             # 后 3 个
```

### 预览声音
```bash
/agent-vibes:preview                 # 预览前 3 个
/agent-vibes:preview 5               # 预览前 5 个
/agent-vibes:preview last 5          # 预览后 5 个
```

### 单声音采样
```bash
/agent-vibes:sample en_US-ryan-high
```

### 当前声音与收藏
```bash
/agent-vibes:get                     # 显示当前声音
/agent-vibes:set-favorite-voice      # 标记当前声音为收藏
```

## 个性与风格

### 个性风格
```bash
/agent-vibes:personality list          # 列出可用个性
/agent-vibes:personality sarcastic     # 切换讽刺风格
/agent-vibes:personality dramatic      # 切换戏剧风格
/agent-vibes:personality reset         # 恢复默认
```

### 前缀文本
```bash
/agent-vibes:set-pretext "AgentVibes"  # 每条 TTS 前播报 "AgentVibes"
/agent-vibes:set-pretext ""            # 清空前缀
```

## 语速与效果

### 语速控制（0.5x - 3.0x）
```bash
/agent-vibes:set-speed 1.0             # 正常
/agent-vibes:set-speed 1.5             # 加速 50%
/agent-vibes:set-speed 0.8             # 减速
```

### 语音效果
```bash
/agent-vibes:effects reverb hall       # 大厅混响
/agent-vibes:effects reverb none       # 关闭混响
/agent-vibes:effects reset             # 清空全部效果
```

支持效果: `reverb`（混响）、`echo`（回声）、`pitch`（音调）、`eq`（均衡器）。

## 背景音乐

```bash
/agent-vibes:background-music on       # 启用
/agent-vibes:background-music off      # 关闭
/agent-vibes:background-music list     # 列出可用曲目
/agent-vibes:background-music switch jazz  # 切换到爵士曲目
```

## Verbosity 控制

控制 AI Agent 工作时的播报详尽度:
```bash
/agent-vibes:verbosity low             # 简短确认
/agent-vibes:verbosity medium          # 关键决策（默认）
/agent-vibes:verbosity high            # 完整推理过程
```

## 静音与回放

```bash
/agent-vibes:mute                      # 静音（跨会话持久）
/agent-vibes:unmute                    # 取消静音
/agent-vibes:replay                    # 回放最近一次
/agent-vibes:replay 2                  # 回放倒数第二次
```

回放缓存保留最近 10 条音频。

## 语言与学习

### 设置母语
```bash
/agent-vibes:language english
/agent-vibes:language japanese
```

### 语言学习模式
```bash
/agent-vibes:learn on                  # 启用双语播报（母语 + 目标语言）
/agent-vibes:learn off                 # 关闭
```

### 翻译并播放
```bash
/agent-vibes:translate "Hello, how are you?"
```

## Provider 管理

```bash
/agent-vibes:provider list             # 列出可用 Provider
/agent-vibes:provider switch piper     # 切换到 Piper（免费、离线、914+ 声音）
/agent-vibes:provider switch macos     # 切换到 macOS Say（仅 Mac）
/agent-vibes:provider switch sapi      # 切换到 Windows SAPI（仅 Windows）
/agent-vibes:provider switch soprano   # 切换到 Soprano（神经声音）
```

## 默认声音（Piper TTS - 免费离线）

| 语言 | 推荐声音 |
| --- | --- |
| English (US) | en_US-lessac-medium · en_US-amy-medium · en_US-ryan-high · en_US-libritts-high（914 说话人） |
| English (UK) | en_GB-alan-medium · en_GB-jenny_dioco-medium |
| French | fr_FR-siwis-medium · fr_FR-gilles-low |
| German | de_DE-thorsten-medium · de_DE-eva_k-x_low |
| Spanish | es_ES-davefx-medium · es_MX-clau-high |
| Japanese | ja_JP-ayanami-medium |
| Chinese | zh_CN-huayan-x_low |
| Korean | ko_KR-kss-medium |

另有 900+ 声音覆盖 30+ 语言,均从 HuggingFace 下载,无需账号。

## 其他命令

```bash
/agent-vibes:whoami                    # 显示当前 AgentVibes 配置
/agent-vibes:version                   # 显示已安装版本
/agent-vibes:update                    # 更新到最新版本
/agent-vibes:show / /agent-vibes:hide  # 显示/隐藏状态指示器
/agent-vibes:cleanup / /agent-vibes:clean  # 清除缓存音频文件
```

## 适用场景

| 场景 | 典型输入 | 输出内容 | 涉及命令 |
| --- | --- | --- | --- |
| 多语言声音切换与预览 | "切换到法语女声并预览" | 切换声音 + 播放采样 | switch + sample |
| 个性化语音角色定制 | "设置戏剧化风格,加混响,语速 0.9" | 应用个性+效果+语速 | personality + effects + set-speed |
| 语言学习双语播报 | "启用日语学习模式" | 母语+目标语言交替播报 | language + learn |
| 背景音乐配音制作 | "启用爵士背景音乐" | TTS 叠加背景音乐 | background-music |

**不适用于**: 实时语音识别（STT）、语音克隆训练、商业有声书分发。

## 使用流程

### Step 1: 检查 Provider 可用性
```bash
/agent-vibes:provider list
```

### Step 2: 首次使用拉取声音
- Piper: 首次切换某声音时自动从 HuggingFace 下载
- macOS Say / Windows SAPI: 系统自带,零配置
- Soprano: 自动安装

### Step 3: 选择并预览声音
```bash
/agent-vibes:list first 10
/agent-vibes:preview 5
/agent-vibes:sample en_US-amy-medium
```

### Step 4: 切换并定制
```bash
/agent-vibes:switch en_US-amy-medium
/agent-vibes:set-speed 1.0
/agent-vibes:personality dramatic
```

### Step 5: 按需启用高级能力
- 背景音乐: `/agent-vibes:background-music on`
- 语言学习: `/agent-vibes:learn on`
- 翻译播放: `/agent-vibes:translate "text"`

### 命令参数说明

- `-pretext`: 命令参数,用于指定操作选项
- `-favorite-voice`: 命令参数,用于指定操作选项

**结果处理**: 执行完成后,查看输出结果确认操作状态。成功时输出包含处理摘要和结果数据;失败时根据错误信息排查问题,参考错误处理章节获取恢复步骤。


## 案例展示

### 案例1: 英语女声切换 + 戏剧化风格
**场景**: 内容创作者需要为视频配音,要求英语女声 + 戏剧化风格 + 大厅混响

```bash
# 切换到英语女声
/agent-vibes:switch en_US-amy-medium

# 设置戏剧化个性
/agent-vibes:personality dramatic

# 应用大厅混响
/agent-vibes:effects reverb hall

# 调整语速为 0.9（略慢,增强戏剧感）
/agent-vibes:set-speed 0.9

# 播放采样验证
/agent-vibes:sample en_US-amy-medium
```

**输出**: 切换后的声音采样,带戏剧化风格与大厅混响效果

**说明**: 组合 `personality` + `effects` + `set-speed` 可打造完全自定义的 TTS 角色。建议先 `sample` 验证再正式使用。

### 案例2: 日语学习模式双语播放
**场景**: 日语学习者希望 AI Agent 在工作时用日语+母语交替播报

```bash
# 设置母语为日语
/agent-vibes:language japanese

# 启用语言学习模式
/agent-vibes:learn on

# 切换到日语声音
/agent-vibes:switch ja_JP-ayanami-medium

# 翻译并播放一段文本
/agent-vibes:translate "Hello, how are you today?"
```

**输出**: 日语+目标语言交替播报,翻译后的文本以日语声音播放

**说明**: `language` + `learn` 组合实现双语播报,适合语言学习场景。`translate` 命令将输入文本翻译为目标语言并播放。

### 案例3: Windows SAPI 零配置快速使用
**场景**: Windows 用户希望零安装快速启用 TTS

```bash
# 列出可用 Provider
/agent-vibes:provider list

# 切换到 Windows SAPI（系统自带,零配置）
/agent-vibes:provider switch sapi

# 列出系统声音
/agent-vibes:list

# 切换到某个系统声音
/agent-vibes:switch Microsoft David Desktop

# 预览
/agent-vibes:preview 3
```

**输出**: Windows SAPI 系统声音列表与采样

**说明**: Windows SAPI 无需安装额外组件,适合快速试用。如需更多声音与离线能力,推荐切换回 Piper。

## 错误处理


| 错误场景 | 错误信息 | 原因分析 | 处理方式 |
|---------|---------|---------|---------|
| piper_voice_not_downloaded | `voice file not found: en_US-amy-medium` | Piper 声音文件未下载 | 自动触发下载,或引导用户手动从 HuggingFace 拉取 |
| macos_say_unavailable | `say command not found` | 在非 macOS 系统调用 macOS Say | 不执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令,提示用户切换到 Piper 或 Soprano |
| sapi_unavailable | `SAPI not available on this platform` | 在非 Windows 系统调用 Windows SAPI | 不执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令,提示用户切换到 Piper 或 Soprano |
| invalid_speed | `speed must be between 0.5 and 3.0` | set-speed 参数超出范围 | 不执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令,提示用户使用 0.5-3.0 之间的值 |
| personality_not_found | `personality 'xyz' not found` | personality 名称不存在 | 不执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令,引导用户 `personality list` 查看可用项 |
| bgm_track_not_found | `track 'xyz' not found` | background-music 曲目名不存在 | 不执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令,引导用户 `background-music list` 查看可用曲目 |
| replay_out_of_range | `replay index out of range (max 10)` | replay 索引超过缓存上限 | 不执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令,提示用户回放最近 10 条之内的音频 |
| provider_switch_failed | `failed to switch provider` | Provider 未安装或平台不支持 | 不执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令,引导用户 `provider list` 查看可用项 |

## 常见问题

### Q1: AgentVibes 真的免费且离线吗?
A: Piper TTS 完全免费且离线运行,声音文件从 HuggingFace 下载（无需账号）后本地缓存。macOS Say 与 Windows SAPI 为系统内置,同样免费。Soprano 神经声音也免费。仅首次下载声音文件需要网络。

### Q2: 如何添加新的 Piper 声音?
A: Piper 声音文件托管在 HuggingFace 的 rhasspy/piper-voices 仓库。首次切换到某声音时会自动下载。如需手动添加,将 `.onnx` 与 `.onnx.json` 文件放入 Piper 声音目录即可。

### Q3: 四个 Provider 有什么区别?
A: Piper TTS（全平台、914+ 声音、离线、推荐）;macOS Say（仅 macOS、系统内置、100+ 声音、零安装）;Windows SAPI（仅 Windows、系统内置、零配置、适合快速试用）;Soprano（全平台、神经声音、高质量）。

### Q4: 语言学习模式如何工作?
A: 启用 `learn on` 后,AI Agent 播报时会先用母语播报,再用目标语言播报,适合语言学习场景。配合 `translate` 命令可将任意文本翻译并播放。

### Q5: 如何清除音频缓存?
A: 使用 `/agent-vibes:cleanup`（或 `/agent-vibes:clean`）移除缓存的音频文件。回放缓存仅保留最近 10 条,超出自动淘汰最早的一条。

### Q6: 多 Agent 场景如何配置不同声音?
A: BMAD 多 Agent 模式下,每个 Agent 可独立配置声音、个性、背景音乐。通过 `switch`、`personality`、`background-music` 命令为每个 Agent 设置差异化配置,实现多角色语音协作。

## 已知限制

1. **Piper 需下载声音文件**: 首次使用某声音需从 HuggingFace 下载,网络较慢时可能耗时
2. **macOS Say 仅 Mac 可用**: 在 Windows/Linux 调用会返回 `say command not found`
3. **Windows SAPI 仅 Windows 可用**: 在 macOS/Linux 调用会返回平台不支持
4. **replay 缓存上限 10 条**: 仅保留最近 10 条音频,超出自动淘汰
5. **语速范围 0.5-3.0**: 超出范围会被拒绝
6. **Soprano 神经声音质量取决于模型**: 不同声音质量有差异,建议预览后选择