# IndexTTS2 WorkBuddy 技能 保姆级使用教程

> 💡 本教程面向完全新手，每一步都写得很详细，跟着做就能用！

---

## 📋 前置准备（必须先完成）

### 第一步：确认你有 Python 环境
IndexTTS2 技能需要 Python 3.6 以上版本运行。

**检查是否安装了Python：**
1. 按下 `Win + R`，输入 `cmd` 回车，打开命令提示符
2. 输入 `py --version` 回车
   - 如果显示类似 `Python 3.10.0` 这样的版本号，说明已经安装，可以跳过这一步
   - 如果提示"不是内部或外部命令"，说明没安装，继续往下看

**安装Python（没装的话）：**
1. 打开 Python 官网下载页面：https://www.python.org/downloads/windows/
2. 下载最新版本的 Python（选 "Download Windows installer (64-bit)"）
3. 运行安装包，**非常重要：一定要勾选最下面的 "Add Python to PATH"**
4. 点击 "Install Now" 等待安装完成
5. 重新打开命令提示符，输入 `py --version` 确认能显示版本号

---

### 第二步：确认你有 IndexTTS2 企业会员 API Key
- 本技能需要企业会员才能使用，官网：https://indextts.xin
- 如果还不是企业会员，请联系官网客服购买开通，获取你的 API Key
- API Key 是一串类似 `abc123def456ghi789jkl012mno345pqr` 这样的字符串，请保存好

---

## 🚀 方法一：ZIP 一键安装（推荐，最简单）

1. 打开下载页面：**https://6e7aa5252293420e9557e44fe033365a.app.codebuddy.work**
2. 点击页面上的「**下载技能包**」按钮，下载 `indextts2-tts.zip`
3. 打开 WorkBuddy，在对话框中输入：
   ```
   /install-skill
   ```
4. 在弹出的窗口中选择「**导入 ZIP 文件**」
5. 选择刚才下载的 `indextts2-tts.zip`
6. 安装完成！

> 💡 如果下载页面打不开，也可以直接找技能发布者索要 ZIP 压缩包。

---

## 🚀 方法二：ClawHub 技能市场安装（即将上线）

等技能通过 ClawHub 审核上线后，直接在 WorkBuddy 侧边栏搜索安装：

1. 打开 WorkBuddy → 左侧边栏点击「**Skill**」
2. 在搜索框输入 `IndexTTS2` 或 `语音合成`
3. 点击安装

> 📌 ClawHub 版本上线后会在下载页面更新通知。

---

## 🚀 方法三：手动安装（如果上面方式不行）

### 手动安装步骤：
1. 下载好 ZIP 压缩包后解压
2. 找到你的 WorkBuddy 技能目录，一般在：
   ```
   C:\Users\你的用户名\.workbuddy\skills\
   ```
   （把"你的用户名"换成你电脑的用户名，比如 `C:\Users\yanyu\.workbuddy\skills\`）
3. 在 `skills` 文件夹里新建一个文件夹，名字叫 `indextts2-tts`
4. 把解压出来的文件全部复制到 `indextts2-tts` 文件夹里
5. 复制完后，文件夹结构应该是这样的：
   ```
   skills/
   └── indextts2-tts/
       ├── SKILL.md
       └── scripts/
           └── tts.py
   ```
6. 重启 WorkBuddy，技能就会被自动识别了

---

## 🔑 配置 API Key（非常重要！）

安装完技能后，必须配置你自己的 API Key 才能使用。配置方式二选一：

### 方式A：永久配置（一次设置，以后不用再输）⭐ 推荐
1. 右键点击「此电脑」→「属性」→「高级系统设置」→「环境变量」
2. 在"用户变量"下面点击"新建"
3. 变量名填：`INDEKTTS2_API_KEY`
4. 变量值填：你的 API Key
5. 点击确定保存，重启 WorkBuddy 就生效了

### 方式B：不设环境变量（首次使用时会提示输入）
如果你不想设环境变量也没关系，第一次使用技能时脚本会自动提示你输入 API Key，输入一次即可。

> 💡 兼容说明：如果你之前用过 LipVoice 旧版本，设置过 `LIPVOICE_API_KEY` 环境变量，不用重新设置，新版本会自动兼容。

### 临时使用（每次打开终端都要设置）：
**Windows CMD（命令提示符）：**
```cmd
set INDEKTTS2_API_KEY=你的API Key
```

**Windows PowerShell：**
```powershell
$env:INDEKTTS2_API_KEY='你的API Key'
```

**Linux/macOS：**
```bash
export INDEKTTS2_API_KEY='你的API Key'
```

---

## 🎯 开始使用

### 方式1：在 WorkBuddy 对话中直接用（最方便）⭐ 推荐
配置好 Key 之后，你直接和 WorkBuddy 助手说就行了，比如：

> "合成语音，文本是：今天天气真好，我们一起出去玩吧！"
> "帮我把这段文字配音：欢迎使用 IndexTTS2 语音合成"
> "列出我所有的声音模型"

助手会自动调用技能完成操作，合成完直接把音频文件的路径返回给你。

**支持的触发词（说任意一个都行）：**
- 合成语音
- 生成语音
- 配音
- TTS
- 语音合成
- 文字转语音
- 音色克隆

---

### 方式2：手动命令行使用

如果你想手动运行命令，先进入技能的 scripts 目录：
```cmd
cd C:\Users\你的用户名\.workbuddy\skills\indextts2-tts\scripts
```

> ⚠️ 注意：Windows 下用 `py` 开头运行 Python，Linux/macOS 用 `python3`

#### 📋 命令1：查看你所有的声音模型
```bash
py tts.py list
```
运行后会列出你账号下所有已经创建好的声音模型，每个模型都有一个 ID（audioId），合成的时候需要用到这个 ID。

---

#### 🎤 命令2：上传音频创建新的声音克隆模型
准备一段 10~60 秒的清晰人声（支持 mp3/wav/m4a 格式，建议无背景噪音），运行：
```bash
py tts.py upload --file "你的音频文件路径" --name "模型名称" --describe "模型描述（可选）"
```

**例子：**
```bash
py tts.py upload --file "C:\Users\xxx\Desktop\我的声音.wav" --name "我的声音" --describe "温暖男声"
```
运行成功后会显示新模型的 ID，记下来。

---

#### 🔊 命令3：文本转语音合成（最常用）
用指定的声音模型合成语音，自动等待合成完成并下载音频：
```bash
py tts.py tts --text "要合成的文本内容" --audio-id 模型ID [选项]
```

**所有可选参数：**
| 参数 | 说明 | 默认值 |
|------|------|--------|
| `--text` | 要合成的文本（必填，最多5000字） | 无 |
| `--audio-id` | 声音模型ID（必填，从list命令获取） | 无 |
| `--style` | 模型版本：1=基础模型，2=专业模型，3=多语言模型 | 1 |
| `--genre` | 模型类别：0=纯语音，1=情绪控制，2=参考音频模式 | 0 |
| `--speed` | 语速，范围0.5~1.5，数字越小语速越慢，越大越快 | 1.0 |
| `--emotion-path` | 参考音频URL（仅专业模型genre=2时用） | 无 |

**情绪控制参数（仅 genre=1 时有效）：**
| 参数 | 说明 | 范围 |
|------|------|------|
| `--happy` | 开心 | 0 ~ 1 |
| `--angry` | 愤怒 | 0 ~ 1 |
| `--sad` | 悲伤 | 0 ~ 1 |
| `--afraid` | 恐惧 | 0 ~ 1 |
| `--disgusted` | 厌恶 | 0 ~ 1 |
| `--melancholic` | 忧郁 | 0 ~ 1 |
| `--surprised` | 惊讶 | 0 ~ 1 |
| `--calm` | 平静 | 0 ~ 1 |

**最简单的例子（默认参数合成）：**
```bash
py tts.py tts --text "你好，欢迎使用IndexTTS2语音合成！" --audio-id ABuXqMU5ZnPCFBHtv93wmnhqLM
```

**带情绪的例子：**
```bash
py tts.py tts --text "真是太惊喜了！今天天气真好！" --audio-id ABuXqMU5ZnPCFBHtv93wmnhqLM --style 2 --genre 1 --happy 0.8 --surprised 0.5
```

**例子：自定义语速**
```bash
py tts.py tts --text "各位听众朋友们大家好" --audio-id ABuXqMU5ZnPCFBHtv93wmnhqLM --speed 0.8
```

> ⏰ 合成通常需要 5~30 秒，基础模型约 8 秒，专业模型+情绪控制约 20~30 秒。脚本会自动等待，合成完会自动下载音频到当前目录，生成文件名为 `tts_xxxx.wav`。

---

#### 📊 命令4：查询某个任务的合成结果
```bash
py tts.py query --task-id 任务ID
```

---

#### ⏳ 命令5：等待任务完成并下载
```bash
py tts.py wait --task-id 任务ID
```
默认最多等 60 秒，可通过 `--max-wait` 调整：
```bash
py tts.py wait --task-id 任务ID --max-wait 120
```

---

#### 🗑️ 命令6：删除不需要的模型
如果某个模型你不用了，可以删除：
```bash
py tts.py delete --audio-id 要删除的模型ID
```

**例子：**
```bash
py tts.py delete --audio-id ABuXqMU5ZnPCFBHtv93wmnhqLM
```
> ⚠️ 删除后无法恢复，请谨慎操作！

---

## ❓ 常见问题

### Q：运行命令提示"未配置 API Key"怎么办？
A：说明你没配置环境变量，按照上面"配置 API Key"的步骤设置一下即可。或者不设环境变量，首次运行时会交互式提示你输入。

### Q：提示"sign无效或用户未开通API"怎么办？
A：检查一下你的 API Key 有没有输错，确认你的账号已经开通了 IndexTTS2 企业会员 API 权限。

### Q：Windows 下中文显示乱码怎么办？
A：新版本已经修复了编码问题，如果还有乱码，请升级到 Python 3.7 以上版本。

### Q：合成等待很久都没完成？
A：正常情况下 30 秒内都会完成，如果超过 60 秒还没完成会超时，可以重新运行试试。也可以用 `--max-wait` 调大等待时间。

### Q：支持什么音频格式？
A：上传参考音频支持 mp3、wav、m4a 格式，合成输出是 wav 格式。

### Q：最多支持多少字？
A：单次合成最多支持 5000 个字符。

### Q：WorkBuddy 中怎么查看已安装的技能？
A：左侧边栏点击「Skill」，已安装的技能都会显示在列表中。

---

**祝你使用愉快！🎉**