language-helper（语言助手）

language-helper

将中文句子翻译为目标语言，并提供发音语音、简要语法说明和重点词汇。

触发方式

• 【日语】我今天很累
• 【英语】这个说法太生硬了
• 【简洁】【韩语】谢谢你的帮助
• "用日语怎么说……"
• "翻译成英语并朗读"

模式

默认模式

返回：

• 翻译结果
• 发音语音
• 简要语法说明
• 重点词汇
• 可选替代表达

简洁模式

当用户添加 【简洁】 时，仅返回：

• 翻译结果
• 发音语音
• 关键词注释

环境检查

先检查环境变量 SENSEAUDIO_API_KEY。如果已经存在，直接使用；如果不存在，再提示用户提供 API Key 或先在终端设置环境变量。不要把密钥写进 SKILL.md、脚本源码或提交记录。

首次运行前检查：

1. 首次运行时 skill 会自动创建 skills/language-helper/.env 模板，用户需填写对应的值
2. 确认 ffmpeg 已安装

.env 示例：

SENSEAUDIO_API_KEY=your_key

# 以下为飞书语音条功能（可选，不用飞书可不填）
FEISHU_APP_ID=cli_xxx
FEISHU_APP_SECRET=xxx
FEISHU_CHAT_ID=oc_xxx

检查 ffmpeg：

which ffmpeg
# 若未安装：
# macOS: brew install ffmpeg
# Linux: sudo apt install ffmpeg

内置音色映射

始终优先使用用户显式指定的 voice_id。未指定时，根据目标语言选择默认音色。

在当前 SenseAudio key 权限有限时，仅默认使用已确认可用的以下音色：

• child_0001_b：可爱萌娃，平稳
• male_0004_a：儒雅道长，平稳
• male_0018_a：沙哑青年，深情

不要默认选择未确认授权的 VIP / SVIP 音色。若接口返回 403 no access to the specified voice，优先回退到 child_0001_b，而不是重复尝试未授权音色。

LANG_VOICE_MAP:
  ja: male_0004_a
  en: male_0004_a
  zh: male_0004_a
  ko: male_0004_a
  fr: male_0004_a
  es: male_0004_a
  de: male_0004_a

输入解析

从用户输入中提取：

• 目标语言
• 是否为 【简洁】 模式
• 待翻译文本
• 解释语言

解释语言默认跟随用户输入语言：

• 用户用中文提问 → 中文解释
• 用户用英文提问 → 英文解释

语言代码映射：

执行流程

一次完成以下内容：

1. 翻译文本
2. 生成并发送语音
3. 输出文字讲解

语音发送

优先发送飞书语音条：

python3 skills/language-helper/scripts/main.py send-voice \
  --text "{translated_text}" \
  --lang {lang_code}

若飞书配置缺失，则降级为本地播报：

python3 skills/language-helper/scripts/main.py speak \
  --text "{translated_text}" \
  --lang {lang_code}

若 TTS 失败，继续返回纯文本结果，并说明语音不可用。

API 请求模板

API 地址固定为：

https://api.senseaudio.cn/v1/t2a_v2

重要：先按最小请求体调用官方接口，不要一开始就附带全部可选字段。若接口返回 400 input content type is not supported，优先怀疑请求体结构与官方当前协议不一致，而不是继续切换音色。

语音生成

使用 helper.py synthesize 发送 TTS 请求并把 hex 音频保存到本地。

helper.py 内置以下健壮机制（参考 VoiceMaster 模式）：

1. 文本变体：自动对输入文本生成多种规范化变体（去角色前缀、标点规范化、去特殊标点、纯文本等），依次尝试直到成功。
2. 请求体变体：对每种文本变体，依次尝试 full → no-audio-setting → no-speed-pitch → minimal 四种请求体。
3. 自动重试：对 5xx 及网络错误自动重试最多 3 次，带指数退避。
4. 音色降级：若 403 no access to the specified voice，自动回退到 child_0001_b / male_0004_a / male_0018_a。
5. 调试日志：仅在显式传入 --debug-log 参数时才生成 .debug.json，默认不写入任何日志文件。

方式一：直接文本播报（推荐）

python3 skills/language-helper/scripts/main.py speak \
  --text "{translated_text}" \
  --lang {lang_code} \
  --speed 1.0 \
  --pitch 0

speak 命令会自动：

1. 将文本写入临时文件
2. 调用 helper.py synthesize 生成音频
3. 使用系统播放器（macOS afplay / ffplay）播放

方式二：文件输入合成

python3 skills/language-helper/scripts/main.py synthesize \
  --text-file segment.txt \
  --voice-id male_0004_a \
  --speed 1.0 \
  --pitch 0 \
  --format wav \
  --sample-rate 24000 \
  --output outputs/reply.wav

方式三：多段合并

python3 skills/language-helper/scripts/main.py concat \
  --output outputs/final.wav \
  outputs/segment-01.wav outputs/segment-02.wav

SenseAudio 响应处理

SenseAudio 非流式 TTS 的成功响应为 JSON，其中 data.audio 是 hex 编码的音频数据。处理规则如下：

1. 先检查 base_resp.status_code 是否为 0。
2. 若成功，读取 data.audio 并按十六进制解码为二进制音频文件。
3. 使用 extra_info.audio_length、extra_info.audio_sample_rate 作为结果回执。
4. 若 data.audio 为空或 status_code 非 0，直接返回 base_resp.status_msg。

响应结构参考：

{
  "data": {
    "audio": "hex编码音频",
    "status": 2
  },
  "extra_info": {
    "audio_length": 3500,
    "audio_sample_rate": 44100
  },
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  }
}

输出格式

默认模式

🗣 {翻译结果}（{发音}）

📝 语法解析
• {语法点1}
• {语法点2}

📖 重点词汇
| 单词 | 读音 | 词性 | 释义 |
|------|------|------|------|
| ... | ... | ... | ... |

💡 其他表达
• {替代表达}

简洁模式

🗣 {翻译结果}（{发音}）

📖 {词1}={含义} | {词2}={含义}

输出要求

• 翻译应自然、口语化
• 保留原句语气和语域
• 日语可附罗马音
• 韩语可附罗马字
• 说明语言默认跟随用户输入语言
• 不展示本地文件路径
• 若 TTS 失败，继续返回纯文本结果，并说明语音不可用
• 如果因为套餐权限限制降级到授权音色，明确写出降级原因与最终使用的 voice_id

运行要求

• 已配置 .env（含 SENSEAUDIO_API_KEY）
• 系统可用 ffmpeg
• 需要联网调用语音服务
• 飞书语音条需额外配置 FEISHU_APP_ID、FEISHU_APP_SECRET、FEISHU_CHAT_ID

限制

• 当前默认使用单一音色
• 专业或冷门表达可能不够完全地道
• 飞书语音条依赖机器人权限