用 CLI 把本地 AI 配音接入智能体工作流

1. 找到入口，读取当前协议

macOS 直接调用应用内部可执行文件；Windows PowerShell 使用实际安装路径。桌面安装不会自动注册 shengyue 命令。下面两组分别适用于 macOS 和 Windows。

"/Applications/声悦.app/Contents/MacOS/声悦" --cli describe
"/Applications/声悦.app/Contents/MacOS/声悦" --cli status

# Windows PowerShell：替换为实际安装路径
& "C:\实际安装目录\声悦.exe" --cli describe | Out-String
& "C:\实际安装目录\声悦.exe" --cli status | Out-String

2. 检测、激活，再准备所需资源

未激活时可以查看协议、状态、授权和购前检测；catalog、setup 与自定义生成需要激活。先在软件中检测电脑并亲自听完固定试音，再经原销售渠道购买、获得设备绑定的 SY2 激活码。

智能体应先检查资源状态；资源缺失时，说明下载内容并获得用户同意后再显式执行准备操作。生成命令不会自动下载模型。不要将激活码写进公开脚本或日志。完整命令与错误处理见下方 CLI 文档。

3. 用 JSON 表达多角色脚本

激活后使用 catalog 获取本机可用的声音 ID。将以下内容保存为 UTF-8 的 script.json；顶层设置默认值，每行可以指定自己的声音与文件名。

{
  "engine": "standard",
  "language": "Chinese",
  "sampleRate": 48000,
  "project": "课程开场",
  "rows": [
    {
      "text": "先观察图形的长和宽，再列出面积算式。",
      "speaker": "Vivian",
      "emotion": "natural",
      "filename": "lesson-01"
    },
    {
      "text": "接下来，请完成这道练习。",
      "speaker": "Uncle_Fu",
      "emotion": "natural",
      "filename": "lesson-02"
    }
  ]
}

4. 调用生成，解析本地文件路径

普通生成成功时，stdout 返回一行带 ok / result 的 JSON，从 result.items[].paths.wav 或 paths.mp3 获取本地文件路径；stderr 为进度信息。describe 和 version 使用独立 JSON，help 为纯文本，不能都当成同一种返回格式处理。

单批最多 5000 字、100 条，每条最多 600 字；输入文件或 stdin 最多 2 MB。CLI 不会自动拆分长台词，也不会解析 DOCX、PPTX 或 PDF。Office 文稿可先从桌面配音项目导入，CLI 请求则要转换成规定的 JSON 或纯文本格式。

"/Applications/声悦.app/Contents/MacOS/声悦" --cli generate --input script.json --output-dir ./audio

5. 长任务保持声音一致，逐批处理

人物声音默认先确定样本，再复用于台词。跨批次与单句重做时，保持 voiceScopeId、voiceId、voiceRevision 以及声音设置一致；需要换声时再使用新的 voiceRevision。当前安装包中，定声和参考声音沿用样本表达，逐句情绪指令不会重新定声。

同一数据目录由桌面端与 CLI 共用锁，不应并行启动多个生成、下载或修改操作。收到 BUSY 时等待并有限次重试；任务超时或取消后先查询历史，避免把已经完成的片段全部重复生成。

导出、隐私与智能体费用

CLI 普通 ZIP 只打包分段音频，不会自动进行项目混音、合并音频或生成字幕。历史版本选择、波形编辑、背景音乐与合并 WAV / MP3 / SRT 从桌面项目管理。

准备好资源后，声悦的生成与授权验证在本机完成。外部智能体的写作、推理、联网和文本处理仍由其设置决定，服务费用按其规则计算。当前通过本地 CLI 接入，没有专用 MCP 服务，也不承诺固定的 token 节省比例。

文档与示例下载

• 下载完整 CLI 文档（Markdown）
• 下载可编辑的 JSON 脚本示例