# 豆包语音插件 - 开发状态

**更新时间**: 2026-02-07
**版本**: 1.0.0

---

## ✅ 已完成功能

### 1. TTS (文字转语音) - 完全可用 ✅

**测试状态**: 通过
**API版本**: V1
**可用音色**:
- BV700_V2_streaming (通用女声)
- BV701_V2_streaming (通用男声)
- BV406_streaming (温柔女声)
- BV158_streaming (活泼女声)
- BV115_streaming (磁性男声)

**测试命令**:
```bash
source scripts/setup_env.sh
python3 scripts/voice_converter.py tts "你好世界" -o hello.mp3
```

**测试结果**:
- ✅ HTTP 200 OK
- ✅ Code 3000 Success
- ✅ 成功生成 MP3 文件
- ✅ 音质正常

---

## ⚠️ 待完成功能

### 2. ASR (语音转文字) - 待启用服务

**问题**: Code 1001 - "requested resource not granted"

**原因**: ASR 服务未在火山引擎控制台正确启用

**解决步骤**:
1. 访问: https://console.volcengine.com/speech/service
2. 找到 "语音识别 (ASR)" 服务
3. 确保服务已启用并勾选必要选项
4. 等待服务生效（可能需要几分钟）
5. 重新测试

**测试命令** (服务启用后):
```bash
python3 scripts/voice_converter.py asr audio.mp3
```

---

### 3. V3 API / 豆包2.0音色 - 调试中

**问题**: Code 45000000 - "get resource id empty"

**已尝试的方法**:
- [x] Resource-Id header
- [x] X-Resource-Id header
- [x] resource_id query parameter
- [x] resource_id in app config
- [x] 多种 resource_id 值: volc.bigmodel.tts, volc.seed-tts.default, volc.tts.default

**当前状态**: 所有方法均返回相同错误

**可能原因**:
1. V3 API 可能需要不同的认证方式 (IAM签名)
2. 需要特殊的服务实例配置
3. Resource-Id 的获取或配置方法不正确

**建议**:
- 联系火山引擎技术支持获取 V3 API 正确配置方法
- 或继续使用 V1 API (已满足基本需求)

---

## 📁 项目文件结构

```
plugins/doubao-voice-plugin/
├── .claude-plugin/
│   └── plugin.json                    # 插件元数据
├── skills/
│   └── SKILL.md                       # 技能定义和文档
├── scripts/
│   ├── voice_converter.py             # 主转换工具 (V1 API, 可用)
│   ├── voice_converter_v2.py          # 手动签名版本 (待测试)
│   ├── voice_converter_sdk.py         # SDK版本 (待测试)
│   ├── check_credentials.py           # 凭证检查工具
│   ├── test_services.py               # 服务状态测试
│   ├── test_v3_debug.py               # V3 API 调试脚本
│   ├── setup_env.sh                   # 环境变量配置脚本
│   └── README_TEST.md                 # 测试报告
├── README.md                          # 用户文档
└── STATUS.md                          # 本文件 (开发状态)
```

---

## 🔧 诊断工具

### 检查凭证配置
```bash
python3 scripts/check_credentials.py
```
显示当前环境变量配置状态

### 测试服务状态
```bash
python3 scripts/test_services.py
```
测试 TTS 和 ASR 服务是否可用

### V3 API 调试
```bash
python3 scripts/test_v3_debug.py
```
测试多种 V3 API 配置方式

---

## 📊 当前凭证配置

```bash
DOUBAO_APP_ID="your_app_id"
DOUBAO_ACCESS_TOKEN="your_access_token"

# V3 可选配置 (暂不可用)
# DOUBAO_USE_V3="true"
# DOUBAO_RESOURCE_ID="volc.bigmodel.tts"
```

**Access Key 信息** (用于签名认证，暂未使用):
- Access Key ID: your_access_key_id
- Secret Access Key: your_secret_access_key

---

## 🎯 下一步计划

### 立即可用
1. ✅ **使用 TTS 功能**
   - 集成到应用中
   - 测试不同音色
   - 生产环境部署

### 短期目标 (1-3天)
2. ⚠️ **启用 ASR 服务**
   - 在控制台启用服务
   - 测试语音识别功能
   - 完善错误处理

### 长期目标 (可选)
3. 🔄 **V3 API 支持**
   - 联系火山引擎技术支持
   - 获取正确的 Resource-Id 配置方法
   - 支持豆包2.0高级音色

---

## 📞 技术支持

### 火山引擎
- 文档: https://www.volcengine.com/docs/6561/1329505
- 控制台: https://console.volcengine.com/speech/app
- 服务管理: https://console.volcengine.com/speech/service

### 常见问题解决
1. **TTS 可用但 ASR 不可用**
   - 检查控制台 ASR 服务是否启用
   - 确认勾选了"语音识别"选项

2. **V3 API 持续报错**
   - 暂时使用 V1 API
   - 联系火山引擎技术支持

3. **认证失败**
   - 检查环境变量是否正确设置
   - 确认 Access Token 格式正确
   - 注意 Authorization header 使用 `Bearer;{token}` (有分号)

---

## ✨ 总结

**当前可用**: TTS (文字转语音) 功能完全可用，可以投入使用

**待解决**:
1. 在控制台启用 ASR 服务
2. (可选) 解决 V3 API 配置问题

**建议**: 先使用 V1 API 的 TTS 功能，满足基本语音合成需求。ASR 功能在控制台启用服务后即可使用。V3 API 的豆包2.0音色为可选功能，可以后续再解决。

---

*Generated by Claude Code on 2026-02-07*