ai-proj-helper/skills-integration/doubao-voice-plugin/DEPLOY.md

部署指南

在另一台电脑上使用这个 Skill

✅ 可以直接使用吗？

大部分功能可以直接使用！ 但需要做一些简单的配置。

---

📋 部署步骤

1️⃣ 将插件复制到新电脑

# 方式1: 从Git克隆
git clone <repo-url> doubao-voice-plugin

# 方式2: 复制文件夹
cp -r doubao-voice-plugin /path/to/new/location

2️⃣ 安装依赖

核心依赖 (必需):

pip3 install requests

可选依赖 (仅用voice_converter_sdk.py时需要):

pip3 install volcengine

检查是否安装成功:

python3 -c "import requests; print('✅ requests 已安装')"

3️⃣ 配置凭证

创建本地配置文件:

cd scripts
cp setup_env.local.sh.example setup_env.local.sh

编辑 setup_env.local.sh，填入您的火山引擎凭证:

export DOUBAO_APP_ID="your_app_id"
export DOUBAO_ACCESS_TOKEN="your_access_token"

4️⃣ 使用

# 加载环境变量
source scripts/setup_env.local.sh

# 文字转语音
python3 scripts/voice_converter.py tts "你好世界" -o hello.mp3

# 语音转文字（需先启用ASR服务）
python3 scripts/voice_converter.py asr audio.mp3

---

🔧 系统要求

需求	版本	状态
Python	3.6+	✅ 必需
requests	任意版本	✅ 必需
volcengine	任意版本	⚠️ 可选
操作系统	Linux/Mac/Windows	✅ 都支持

---

🚨 常见问题

Q: 错误 "ModuleNotFoundError: No module named 'requests'"

解决:

pip3 install requests

Q: 错误 "DOUBAO_APP_ID not found"

解决:

# 检查环境变量
echo $DOUBAO_APP_ID

# 如果为空，重新加载配置
source setup_env.local.sh

Q: 为什么 ASR 不工作？

原因: 需要在火山引擎控制台启用 ASR 服务 解决: 访问 https://console.volcengine.com/speech/service，启用语音识别服务

Q: 可以在 Windows 上使用吗？

可以！ 但环境变量设置方式不同：

REM Windows CMD
set DOUBAO_APP_ID=your_app_id
set DOUBAO_ACCESS_TOKEN=your_access_token
python scripts\voice_converter.py tts "你好" -o hello.mp3

或在 PowerShell：

$env:DOUBAO_APP_ID="your_app_id"
$env:DOUBAO_ACCESS_TOKEN="your_access_token"
python scripts/voice_converter.py tts "你好" -o hello.mp3

Q: 如何在 Docker 中使用？

Dockerfile 示例:

FROM python:3.9-slim

WORKDIR /app
COPY . .

RUN pip install requests

ENV DOUBAO_APP_ID=${DOUBAO_APP_ID}
ENV DOUBAO_ACCESS_TOKEN=${DOUBAO_ACCESS_TOKEN}

ENTRYPOINT ["python", "scripts/voice_converter.py"]

运行:

docker build -t doubao-voice .
docker run -e DOUBAO_APP_ID=xxx -e DOUBAO_ACCESS_TOKEN=xxx doubao-voice tts "你好"

---

📦 三种使用方式

方式 1: 命令行 (推荐简单使用)

python3 scripts/voice_converter.py tts "文本" -o output.mp3

方式 2: Python 模块导入

import sys
sys.path.insert(0, 'scripts')
from voice_converter import DoubaoVoiceConverter

converter = DoubaoVoiceConverter()
converter.text_to_speech("你好世界", output_file="hello.mp3")

方式 3: Claude Code Skill (自动)

如果安装在 Claude Code 的 plugins 目录，会自动识别为 Skill：

# 用户说: "把这段话转成语音：你好世界"
# → 自动调用 TTS API

---

🔐 安全提示

✅ 推荐做法:

• 凭证存储在 .local 文件中（不在 Git 中）
• 使用环境变量而不是硬编码
• 定期更新 Access Token

❌ 不要做:

• 不要把凭证提交到 Git
• 不要在脚本中硬编码凭证
• 不要分享包含凭证的配置文件

---

📝 最小化部署清单

✅ 复制文件夹
✅ pip install requests
✅ 复制并编辑 setup_env.local.sh
✅ source setup_env.local.sh
✅ python3 scripts/voice_converter.py tts "测试"
✅ 成功！

---

🆘 如需帮助

1. 检查 README.md (用户文档)
2. 查看 skills/SKILL.md (API 文档)
3. 查看 STATUS.md (开发状态)