language-helper

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

触发方式

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

模式

默认模式

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

简洁模式

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

环境检查

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

首次运行前检查：

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

.env 示例：

bash
SENSEAUDIOAPIKEY=your_key

以下为飞书语音条功能（可选，不用飞书可不填）

检查 ffmpeg：

bash
which ffmpeg

若未安装：

macOS: brew install ffmpeg

Linux: sudo apt install ffmpeg

内置音色映射

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

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

• - child0001b：可爱萌娃，平稳
• male0004a：儒雅道长，平稳
• male0018a：沙哑青年，深情

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

yaml
LANGVOICEMAP:
ja: male0004a
en: male0004a
zh: male0004a
ko: male0004a
fr: male0004a
es: male0004a
de: male0004a

输入解析

从用户输入中提取：

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

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

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

语言代码映射：

执行流程

一次完成以下内容：

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

语音发送

优先发送飞书语音条：

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

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

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

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

API 请求模板

API 地址固定为：

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

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

语音生成

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

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

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

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

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

speak 命令会自动：

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

方式二：文件输入合成

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

方式三：多段合并

bash
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. 1. 先检查 baseresp.statuscode 是否为 0。
2. 若成功，读取 data.audio 并按十六进制解码为二进制音频文件。
3. 使用 extrainfo.audiolength、extrainfo.audiosamplerate 作为结果回执。
4. 若 data.audio 为空或 statuscode 非 0，直接返回 baseresp.statusmsg。

响应结构参考：

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

输出格式

默认模式

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

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

📖 重点词汇

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

简洁模式

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

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

输出要求

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

运行要求

• - 已配置 .env（含 SENSEAUDIOAPIKEY）
• 系统可用 ffmpeg
• 需要联网调用语音服务
• 飞书语音条需额外配置 FEISHUAPPID、FEISHUAPPSECRET、FEISHUCHATID

限制

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