前导检查（先执行）

_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
[ -x "$_ROOT/skill/bin/baiyin-skill-update-check" ] && _UPD=$(bash "$_ROOT/skill/bin/baiyin-skill-update-check" "$_ROOT/skill/baiyin-voice-generate-skill" 2>/dev/null || true)
[ -n "${_UPD:-}" ] && echo "$_UPD"

如果输出 UPGRADE_AVAILABLE <old> <new> <slug>：

读取 skill/baiyin-skills-upgrade/SKILL.md，执行其中的「内联升级流程」。
如果宿主支持 AskUserQuestion，使用中文四选一：立即更新 / 以后自动更新 / 暂不更新 / 不再提醒。
如果宿主不支持 AskUserQuestion（例如 OpenClaw 当前会话），直接询问用户： 检测到百音技能 <slug> 有新版本（当前 v<old>，最新 v<new>）。请回复：1 立即更新 / 2 以后自动更新 / 3 暂不更新 / 4 不再提醒。

如果输出 JUST_UPGRADED <old> <new> <slug>：

告诉用户：百音技能 <slug> 已更新到 v<new>，继续处理你的请求。

如果输出 UP_TO_DATE、SNOOZED、CHECK_DISABLED 或 CHECK_FAILED：

不打断当前任务，直接继续。

百音 AI 语音

把自然语言请求稳定映射为百音开放平台的语音任务请求。不要猜模型、不要猜字段类型、不要猜边界值；只使用本文明确列出的模型、枚举和规则。

前置要求

BAIYIN_API_KEY

运行时配置

BASE_URL 固定使用 https://ai.hikoon.com
只有 BAIYIN_API_KEY 缺失时，才向用户索要 API Key。

公网地址处理

当语音生成需要公网音频 URL，而用户提供的是本地文件路径、聊天附件、网盘私链或其他不可直接访问的地址时，不要只提示"需要公网 URL"。
直接指导用户先使用百音开放平台文件上传接口上传文件，拿到公网地址后再继续当前流程。
上传接口：POST {BASE_URL}/api/open/v1/file/upload
认证方式：Authorization: Bearer <API_KEY>，Content-Type: multipart/form-data
表单字段：file 必填，filename 选填，dir 选填
成功后从返回的 data.url 取公网地址，填入 voice_url 等需要 URL 的字段
不要求用户自行准备 OSS、CDN 或其他外部存储；优先提示百音开放平台上传能力

接口地址

获取音色列表：GET {BASE_URL}/api/open/v1/voice/tones
获取语音模型列表：GET {BASE_URL}/api/open/v1/models?modelType=voice&status=1
创建任务：POST {BASE_URL}/api/open/v1/voice/generate
查询任务：GET {BASE_URL}/api/open/v1/tasks/{taskId}

强约束

prompt 必须是非空字符串。空字符串或缺失都会触发 400。
数值字段必须传 number，不要传 string。
voice_url 只接受可访问的 http:// 或 https:// 公网链接。不要传本地路径、file://、../ 这类路径。
音色列表必须静默获取，用户完全不可感知。

字段清单

顶层字段

| 字段 | 类型 | 是否必填 | 允许值 / 边界 | 说明 | |---|---|---|---|---| | prompt | string | 是 | 非空字符串 | 要合成的文本内容 | | modelCode | string | 是 | 来自模型列表接口 | 语音模型标识 |

`params` 对象字段

| 字段 | 类型 | 是否必填 | 允许值 / 边界 | 说明 | |---|---|---|---|---| | params.voice_url | string | 是 | 可访问的 http/https 链接 | 参考音频 URL，用于音色克隆 | | params.speed_level | number | 是 | 整数 1-5 | 语速级别 | | params.pitch_level | number | 是 | 整数 1-5 | 音调级别 | | params.emotion | string | 是 | 开朗、沉稳、温柔、严肃、活泼、冷静、治愈 | 情感风格 |

字段组装规则

`prompt`

用户说"帮我把这段话转成语音""朗读这段文字""配个音"时，从用户消息中提取需要合成的文本
如果用户没有给出具体文本内容，必须追问
不允许传空字符串

`modelCode`

从模型列表接口 GET {BASE_URL}/api/open/v1/models?modelType=voice&status=1 获取
向用户只展示 modelName，不展示 modelCode
用户选择后，将对应 modelCode 作为请求参数传入
如果用户在消息里直接说了模型关键词，可以与接口返回的 modelName 做模糊匹配，自动映射到对应 modelCode
如果接口调用失败或返回为空，明确告知用户当前无法获取模型列表，不要使用任何兜底的固定模型数据
在用户未选定 modelCode 前，不要继续进入参数收集步骤

`params.voice_url`

静默调用 GET {BASE_URL}/api/open/v1/voice/tones 获取音色列表，取第一条的 audioUrl 作为默认值
用户通过名称指定音色时（如"用知性女声"），从音色列表按 name 匹配并使用对应 audioUrl
用户说"用这个声音""参考这段音频""克隆这个音色"并提供了自定义 URL 时，使用用户提供的 URL
必须为可公网访问的音频文件链接

音色列表静默规则（重要）

获取音色列表必须静默进行，用户完全不可感知
不要在调用前、调用中、调用后向用户输出任何与"获取音色列表""查询音色""加载音色"相关的文字、提示、进度、状态或解释
不要把音色列表的原始数据、字段、条数暴露给用户
除非用户主动询问，否则最终回复中也不要主动提及本次使用的音色名称或 voice_url
音色列表调用失败时，也不要向用户报告"音色列表获取失败"

`params.pitch_level`

必填，音调级别，整数 1-5
用户说"声音高一点""低沉一点"时映射：
- "低沉"/"低音"→1
- "正常"/"中音"→3
- "高一点"/"高音"→5
用户未指定时默认填 3

`params.emotion`

必填，情感风格
可选值仅限于：开朗、沉稳、温柔、严肃、活泼、冷静、治愈
用户未指定时默认填"冷静"
用户提到类似情感时映射到最接近的选项

`params.speed_level`

必填，语速级别，整数 1-5
用户说"快一点""慢一点""正常语速"时映射：
- "很慢"/"缓慢"→1
- "慢速"→2
- "正常"/"默认"/"中速"→3
- "快一点"/"偏快"→4
- "很快"/"快速"→5
用户未指定时默认填 3

默认值

除非用户明确指定，否则使用：

{
  "params": {
    "voice_url": "<音色列表第一条的 audioUrl>",
    "speed_level": 3,
    "pitch_level": 3,
    "emotion": "冷静"
  }
}

最小安全请求体

{
  "prompt": "<非空字符串>",
  "modelCode": "<来自模型列表>",
  "params": {
    "voice_url": "<可访问的音频 URL>",
    "speed_level": 3,
    "pitch_level": 3,
    "emotion": "冷静"
  }
}

完整请求示例：

{
  "prompt": "我每天都很开心",
  "modelCode": "VoiceClone",
  "params": {
    "voice_url": "https://example.com/reference-voice.mp3",
    "speed_level": 5,
    "pitch_level": 1,
    "emotion": "治愈"
  }
}

明确的校验规则

prompt
- 必填
- 非空字符串
modelCode
- 必填
- 必须来自模型列表接口
params.voice_url
- 必填
- 必须是可访问的 http/https 链接
params.speed_level
- 必填
- 类型：number
- 范围：整数 1-5
params.pitch_level
- 必填
- 类型：number
- 范围：整数 1-5
params.emotion
- 必填
- 只能是：开朗、沉稳、温柔、严肃、活泼、冷静、治愈

模式判定

创建模式

适用：

"帮我生成一段语音"
"把这段话转成语音"
"用这个声音朗读"

请求特征：

需要提供 prompt 和 modelCode
可选提供 params 中的音色、语速、音调、情感等参数

状态模式

适用：

"查一下刚才那个语音任务"
"任务进度怎么样了"

请求特征：

复用当前会话最近一个语音 taskId

结果模式

适用：

"给我 task_xxx 的结果"
"把音频链接发我"

请求特征：

使用用户提供的 taskId 查询任务
状态为 succeeded 时返回音频链接

最少追问原则

只有这些情况才追问：

用户未提供要合成的文本（prompt 为空）
用户未选择语音模型（调用模型列表接口展示选项）
用户要查询状态或结果，但当前上下文没有明确 taskId

不要为了这些事情打断用户：

params.voice_url（未指定时默认取音色列表第一条）
params.speed_level（未指定时默认填 3）
params.pitch_level（未指定时默认填 3）
params.emotion（未指定时默认填"冷静"）

编码规则

发送包含中文的 prompt 等文本字段时，必须确保请求体使用 UTF-8 编码
不要把 ??、乱码、替代字符当作有效内容

任务状态

queued：已受理，等待执行
processing：生成中
succeeded：生成成功
failed：生成失败

轮询时回复要简短，优先返回状态。

错误处理

400：参数不合法或不完整，让用户修正相关字段
401：百音开放平台 API Key 无效或当前环境不可用
402：账户余额不足
404 查询任务：taskId 不存在，或不属于当前 API Key 所属用户
任务状态为 failed 时，优先透传后端 error 字段

示例

示例 1：基础生成

用户：帮我生成一段语音
处理：
- 调用 GET {BASE_URL}/api/open/v1/models?modelType=voice&status=1 获取可用模型列表
- 展示接口返回的模型选项，让用户选择
- 用户选择后，使用对应 modelCode
- 追问要合成的文本内容

示例 2：带模型指定

用户：帮我把"欢迎来到百音引擎"转成语音，用基础语音模型 V1
结果：
- prompt = "欢迎来到百音引擎"
- 调用模型列表接口，用"基础语音模型 V1"关键词匹配到对应 modelCode
- 必填字段齐全，直接创建任务

示例 3：完整参数

用户：生成一段治愈风格的语音，内容是"今天天气真好，适合出去走走"，语速慢一点，参考这个音频 https://example.com/voice.mp3，用情感语音模型
结果：
- prompt = "今天天气真好，适合出去走走"
- 调用模型列表接口，用"情感语音模型"关键词匹配到对应 modelCode
- params.voice_url = "https://example.com/voice.mp3"
- params.speed_level = 2（慢一点）
- params.emotion = "治愈"
- 直接创建任务

示例 4：查询状态

用户：查一下刚才那个语音任务
结果：
- 状态模式
- 复用当前会话最近一个语音 taskId

示例 5：获取结果

用户：给我 task_abc123 的结果
结果：
- 结果模式
- 查询 GET {BASE_URL}/api/open/v1/tasks/task_abc123
- 状态为 succeeded 时返回音频链接

回复约束

在任务查询结果明确为 succeeded 之前，不要声称音频已经完成
最终结果以任务查询接口返回字段为准，不要猜
如果状态还是 queued 或 processing，就如实返回，不要虚构音频结果
最终交付给用户的关键文本结果必须可读且不含乱码
不要虚构参考音频 URL

baiyin-voice-generate-skill

前导检查（先执行）

百音 AI 语音

前置要求

运行时配置

公网地址处理

接口地址

强约束

字段清单

顶层字段

params 对象字段

字段组装规则

prompt

modelCode

params.voice_url

音色列表静默规则（重要）

params.pitch_level

params.emotion

params.speed_level

默认值

最小安全请求体

明确的校验规则

模式判定

创建模式

状态模式

结果模式

最少追问原则

编码规则

任务状态

错误处理

示例

示例 1：基础生成

示例 2：带模型指定

示例 3：完整参数

示例 4：查询状态

示例 5：获取结果

回复约束

`params` 对象字段

`prompt`

`modelCode`

`params.voice_url`

`params.pitch_level`

`params.emotion`

`params.speed_level`