阶跃语音识别

StepAudio-Skills (StepFun TTS + ASR 技能)

此仓库结合了两个独立的技能：

• step-tts: 通过 StepFun TTS 进行文本转语音和声音克隆
• step-asr: 通过 StepFun ASR 流式 API 进行语音转文本

两个技能共享一个仓库布局，而它们的底层实现保持独立：

• TTS 保留在 shell 中：skills/step-tts/scripts/tts.sh
• ASR 保留在 Python 中：skills/step-asr/scripts/transcribe.py

布局

• skills/step-tts/SKILL.md: TTS/声音克隆的 Agent 面向描述、触发器和用法示例
• skills/step-tts/scripts/tts.sh: 主要 TTS CLI 入口点
• skills/step-asr/SKILL.md: ASR 的 Agent 面向描述、触发器和用法示例
• skills/step-asr/scripts/transcribe.py: 主要 ASR CLI 入口点
• tests/test_step_tts_cli.sh: TTS CLI 帮助命令的冒烟测试
• tests/test_step_asr_cli.sh: ASR CLI 帮助命令的冒烟测试

先决条件

• bash, curl, python3
• 有效的 StepFun API 密钥

共享 API 密钥设置

• 首选环境变量：STEPFUN_API_KEY
• 为兼容性仍接受旧别名：STEP_API_KEY
• step-tts 配置命令将密钥存储在 ~/.stepfun_api_key
• 如果存在，两个技能也会读取旧文件 ~/.step_api_key

基本用法

从此仓库列出技能（本地开发，从仓库根目录）：

npx skills add . --list --full-depth

OpenClaw 本地安装的注意事项：

• OpenClaw 的项目级技能目录也命名为 skills/。
• 如果您在此源仓库内部运行 npx skills add ... --agent openclaw，安装程序可能会写入仓库自己的 skills/ 目录并覆盖源布局。
• 对于 OpenClaw 验证，请使用单独的消费者项目目录，或全局安装。

仅安装 TTS 技能：

npx skills add . --full-depth --skill step-tts -y

仅安装 ASR 技能：

npx skills add . --full-depth --skill step-asr -y

从单独的消费者项目向 OpenClaw 安装两个技能：

cd /path/to/another/project
npx skills add /path/to/StepAudio-Skills --full-depth --agent openclaw -y

TTS 快速开始

配置您的 TTS API 密钥（保存到 ~/.stepfun_api_key）：

bash skills/step-tts/scripts/tts.sh config --set-api-key YOUR_STEPFUN_API_KEY

生成音频：

bash skills/step-tts/scripts/tts.sh speak \
  -t "智能阶跃，十倍每一个人的可能" \
  -o step.opus

speak 的默认值：

• --model: step-tts-2
• --voice: elegantgentle-female
• --response-format: opus

克隆声音（使用来自 StepFun Files API 的现有 file_id）：

bash skills/step-tts/scripts/tts.sh clone-voice \
  --model step-tts-mini \
  --file-id file-XXXX \
  --text "智能阶跃，十倍每一个人的可能" \
  --sample-text "今天天气不错"

file_id 必须来自官方 StepFun Files API：

• 使用 POST https://api.stepfun.com/v1/files 上传您的参考音频（5-10秒您想要克隆的声音，mp3 或 wav 格式）
• 在请求体中设置 purpose="storage"
• 响应将包含一个 File 对象，其中有一个类似 file-abc123 的 id — 将此值传递给 --file-id

ASR 快速开始

将 ASR API 密钥设置为环境变量：

export STEPFUN_API_KEY=YOUR_STEPFUN_API_KEY

如果您已经运行了 TTS config 命令，step-asr 也可以重用保存在 ~/.stepfun_api_key 中的共享密钥。

转录音频文件：

python3 skills/step-asr/scripts/transcribe.py /path/to/audio.wav

将转录结果保存到文件：

python3 skills/step-asr/scripts/transcribe.py /path/to/audio.mp3 --out /tmp/transcript.txt

以JSON格式输出：

python3 skills/step-asr/scripts/transcribe.py /path/to/audio.ogg --json

开发烟雾测试

从仓库根目录运行所有 CLI 和单元测试：

npm test