# 声悦 v0.4.6 · Agent 与 CLI 使用说明

本文对应官网 v0.4.6 安装包。使用前通过 `describe` 获取本机实际协议；网页预存试听不等于开放自定义生成试用。

## 入口与授权

桌面安装包内置无窗口 CLI，无需另装 Node.js，也不需要先打开桌面窗口。

```sh
# macOS：直接调用应用内的可执行文件，不使用 open -a
"/Applications/声悦.app/Contents/MacOS/声悦" --cli describe
"/Applications/声悦.app/Contents/MacOS/声悦" --cli status
```

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

以下示例中的 `shengyue` 表示已注册的源码 CLI。使用安装包时，替换为以上可执行文件加 `--cli`；源码版需要 Node.js 22.12+，可运行 `node /absolute/path/local-voice-studio/cli/studio.cjs`，或在源码项目执行 `npm link` 注册 `shengyue`。安装桌面应用不会自动注册该命令。

未激活时可使用 help、version、describe、status、license 及购前检测。catalog、setup、自定义生成、历史和参考声音操作需要激活。未激活的 status 不启动配音引擎，也不返回作品、参考声音和任务数据。

## 先检测电脑，再购买激活

```sh
shengyue preflight --package standard --network
# 仅在用户明确同意下载资源并运行固定兼容性试音后执行
shengyue preflight prepare --package standard --timeout 3600
# 用户实际听完检测音频、接受音质与速度后，才可确认；不得代替用户确认
shengyue preflight confirm --heard
```

`--package` 支持 light、standard、character、reference、all。检测会检查本机资源并运行固定文稿，不能自由输入内容或导出为作品。人物定声检测会同时准备声音复用资源。网络检查与准备下载需要联网；硬件检查通过不代表所有功能已通过真实推理验收。

通过原销售渠道购买后，发送软件设备码和订单信息，获取当前设备的专用 SY2 激活码。官网未提供在线下单入口。

```sh
shengyue license status
# license.json 内容为 {"code":"SY2.…"}，文件应妥善保管
shengyue license activate --input /absolute/path/license.json
shengyue status
shengyue catalog
# 用户同意下载后，显式准备所需资源；已有完整资源会复用
shengyue setup --package standard --timeout 3600
```

激活码绑定设备，可离线验证；激活后不按生成次数扣额度。当前 SY2 激活码为 90 个字符，不兼容旧 SY1 码。不要把激活码写入公开文档或命令历史；建议用文件或 stdin 传入。购买、补发和换机由原销售渠道处理。

## 输入、输出与限制

```sh
shengyue generate --text "沿着小巷往前走，拐角是一家刚开门的面包店。" \
  --speaker Vivian --engine standard --sample-rate 48000 \
  --output /absolute/path/narration.wav --timeout 600

shengyue generate --input /absolute/path/script.json \
  --output-dir /absolute/path/audio --format mp3 --timeout 1800
```

输入三选一：`--text`、`--text-file`、`--input`。UTF-8 文本文件配合 `--batch` 按非空行生成；JSON 可用 `--input -` 从 stdin 读取，文本可用 `--text-file -`。单批最多 5000 字、100 条，每条最多 600 字，输入文件或 stdin 最多 2 MB。CLI 不会像桌面配音项目那样自动拆分长台词，长稿需先拆段并分批调用。

JSON 示例：

```json
{
  "engine": "standard",
  "language": "Chinese",
  "sampleRate": 48000,
  "project": "冒险对白",
  "rows": [
    {"text":"我们终于到了！","speaker":"Vivian","emotion":"happy","filename":"girl-01"},
    {"text":"大家先休息一下。","speaker":"Uncle_Fu","emotion":"natural","filename":"male-01"}
  ]
}
```

每行覆盖顶层默认值，显式 CLI 参数覆盖 JSON 顶层参数。JSON 使用 camelCase，如 sampleRate、voiceDescription、referenceId；命令行使用 `--sample-rate`、`--voice-description`、`--reference-id`。桌面导出的项目文件包含编辑器状态，不能直接传给 `generate --input`，应转换为上面的请求结构。DOCX / PPTX 导入由桌面配音项目提供，CLI 的 `--text-file` 读取纯文本，不解析 Office 文件或 PDF。

普通操作成功时 stdout 为一行 JSON：

```json
{"ok":true,"command":"generate","result":{"items":[{"id":"<clip-id>","paths":{"wav":"/absolute/path/voice.wav","mp3":"/absolute/path/voice.mp3"},"exportPath":"/absolute/path/narration.wav"}]}}
```

上例省略其他元数据。WAV 和 MP3 同时保存在本机；`--output` 另存单条音频，`--format mp3` 选择 MP3，默认 WAV。`--output-dir` 按音频 ID 和文件名另存批量结果。两种输出参数二选一，已有同名目标不会覆盖，会返回 OUTPUT_EXISTS。

stderr 为 JSON Lines 进度，`--quiet` 可关闭进度。`--help` 为纯文本；`--version` 与 `describe` 返回独立 JSON，不使用普通操作的 ok/result 包装。生成不会自动下载资源，缺少组件时先告知用户，再按授权显式执行 setup。

## 人物定声和参考声音

```sh
shengyue setup --package character
shengyue setup --package reference
shengyue generate --mode design --character teacher-female \
  --voice-scope-id course-01 --voice-id teacher --voice-revision v1 \
  --text "先观察图形的长和宽，再列出面积算式。"
```

人物声音默认先生成并保存定声样本，再用于台词；需要人物创作包和声音复用包。跨批次、单句重做和失败续做时，保持 voiceScopeId、voiceId、voiceRevision 及声音设置一致，避免重新定声。没有指定身份时，相同人物或描述在本机默认共享样本；作品名称、文件名和台词不作为声音身份。

定声后继承样本表达，逐句 emotion、pace、instruction 不会重新定声。需要明确换声时使用新的 voiceRevision；可通过返回的 voiceAnchorId 与 synthesisMode 核对复用结果。`--free-voice` 或 JSON `lockVoice:false` 才会逐句自由设计，音色可能变化。轻量音色只支持自然配音；标准日常音色支持语气和表演要求。

```sh
# 用户明确授权后，导入有权使用的 3–30 秒清晰人声并准确填写原话
shengyue references import --file /absolute/path/reference.wav \
  --text "录音中准确的原话。" --name "讲师声音" --consent
shengyue references list
shengyue references capture --id <clip-id> --name "已确定的声音"
shengyue generate --mode clone --reference-id <reference-id> \
  --text "接下来，请完成这道练习。"
```

v0.4.6 的参考声音复用沿用录音表达，不额外支持情绪和表演指令。网页未承诺尚未包含在当前安装包中的可选情绪资源。桌面可从较长录音中裁取 3–30 秒，或使用麦克风录音；CLI 导入的文件应事先裁好，不提供这些交互式裁剪步骤。

## 历史、导出与离线边界

```sh
shengyue history
shengyue export --ids <id1>,<id2> --format mp3 --output /absolute/path/voices.zip
```

CLI 普通 ZIP 附带清单和 SHA-256，只打包分段音频。项目历史版本选择、波形编辑、背景音乐与合并成品从桌面管理；CLI history 和普通 ZIP 使用已经保存的波形编辑结果，不会自动进行项目混音、合并或生成 SRT。桌面成品导出可包含合并 WAV、MP3 和按片段时长排列的 SRT；字幕不是逐字识别对齐。

首次联网准备运行组件与所需资源后，配音、声音复用与授权验证在本机完成。录音、文稿与音频不会由声悦上传；调用它的外部 Agent 如何处理台词，仍取决于该 Agent 的设置。默认数据目录为 macOS `~/Library/Application Support/Voice Studio` 或 Windows `%APPDATA%\Voice Studio`；`--data-dir` 或 `VOICE_STUDIO_DATA` 可指定独立目录。`VOICE_STUDIO_PYTHON` 仅适用于源码开发版，发行版忽略外部解释器注入并使用准备流程安装的组件。

## 错误、并发与取消

| 退出码 | 含义 | 建议 |
| --- | --- | --- |
| 0 | 成功 | 解析返回 JSON |
| 1 | 后端、文件、授权或导出错误 | 查看 error.code / message 和本机 studio.log |
| 2 | 参数或请求格式错误 | 修正输入后重试 |
| 3 | BUSY | 等待后有限次重试 |
| 4 | RUNTIME_NOT_READY | 经用户同意后显式准备资源 |
| 5 | LICENSE_REQUIRED | 告知需购买授权并激活 |
| 124 | 超时 | 查询 history 找回已完成条目 |
| 130 / 143 | 取消 | 查询 history，避免重复整批任务 |

桌面端与 CLI 共用数据目录锁，不应对同一目录并行运行多个生成、下载或修改操作。进程退出后引擎不常驻，批量 rows 可在一次调用中复用模型。Windows 推荐通过 `--timeout` 取消。检测、生成速度及音质须在用户自己的电脑上验证，Windows 和 Intel 的完整功能仍待相应实机验收。

具备本地命令执行能力的 Agent 可调用这些命令，不需要专用 MCP 服务。Agent 本身的写作和推理按其服务规则计费；不要承诺固定的 token 节省比例，也不要在用户未授权时自动下载模型、激活授权或导入参考声音。