Audiobook

语言切换：当前为中文｜English companion

audiobook 是一套完整的本地有声书工作流，覆盖 4 个阶段：

音色库维护：官方音色同步、用户参考音频分析、付费 clone 准备
剧本准备：txt -> structured-script
角色选角：structured-script -> casting-review -> casting-plan
合成导出：casting-plan -> tts-requests -> segments -> final audio

它面向两类调用者：

人类用户：按步骤查看和修改中间产物
程序调用：读取各脚本的 JSON stdout，以及统一的 artifacts.json

audiobook 不只是“把小说读出来”的 TTS 工具，而是一套围绕音色资产、结构化剧本、角色选角、可重放 TTS 请求和最终音频导出的完整本地工作流。

它的设计原则是：

Step 专属能力继续使用 Step 的原生接口，例如 step-audio-r1.1、官方音色接口、音色复刻接口、stepaudio-2.5-tts
需要长文本理解、角色分析、选角推理的部分，默认使用 step-3.5
当前默认的 step-3.5 调用走的是 Step 的 step_plan reasoning 接口，默认 endpoint 为 https://api.stepfun.com/step_plan/v1
上述 LLM 理解层尽量通过可配置的兼容层实现，便于后续按需替换为其他兼容的 LLM
各阶段中间产物默认落盘，既方便人工审阅和修改，也方便程序按阶段接续执行

能力范围

audiobook 当前覆盖以下能力：

用户可以自行准备一批待克隆音色参考音频；skill 会调用 step-audio-r1.1 对这些音频做声音特点分析，沉淀成后续角色选角可用的基础画像。
用户可以在分析结果基础上，挑选自己认可的候选音色，显式决定是否在 StepFun 开放平台上执行真正的音色复刻；这一步属于付费动作，不会在默认流程中被自动触发。
skill 会自动整合 StepFun 官方系统音色、用户已经完成复刻的音色，以及用户本地维护的待确认音色分析结果，形成统一的音色库与统一音色候选池。
基于用户提供的一套原始文本文件，skill 会默认使用 step-3.5 做分块、章节感知、角色分析和结构化整理，生成一个包含旁白在内的 characters + structured-script 剧本结果；当前默认使用的就是 Step 的 step_plan 推理接口。
基于结构化剧本和统一音色库，skill 会进一步产出一套角色与音色整合后的选角方案；这类依赖语义理解和推理的环节默认使用 step-3.5，但整体实现尽量不依赖写死的 NLP 规则，而是通过可替换的 LLM 配置层完成，便于后续切换到其他兼容 LLM。
基于选角结果，skill 会生成一份符合 stepaudio-2.5-tts 调用习惯的可重放 TTS 请求清单，便于后续批量合成、局部重跑和参数调整。
skill 支持按段合成音频，并将多个 segment 进一步拼接为一个或多个最终音频文件，包括整本导出和局部试听导出。
上述各阶段的关键中间产物都允许用户人工介入修改；用户既可以按步骤审阅，也可以在修改后从某个中间阶段继续重跑，而不必每次都从头开始。

术语约定

结构化剧本：对应英文 structured script
统一音色候选池：对应英文 unified voice candidate pool
生效画像：对应英文 effective profile，即 clone 音色真正参与选角的描述集合
付费 clone：对应英文 paid clone，即真正调用 Step 音色复刻接口的动作
中间产物：对应英文 intermediate artifacts
人工确认：对应英文 human review 或 manual confirmation
ready 音色：对应英文 ready voice，表示当前已经可以直接进入下游 TTS

LLM 可替换边界

当前需要重点说明的是：并不是整个 skill 的所有能力都可以替换成别的模型。

默认可替换的部分：长文本结构化、角色提取、选角推理等 LLM 理解环节
这些环节当前默认使用 step-3.5，且默认走 https://api.stepfun.com/step_plan/v1
默认不替换的部分：step-audio-r1.1 音频分析、Step 官方音色拉取、Step 音色复刻、stepaudio-2.5-tts 合成
也就是说，audiobook 当前是“Step 音频能力 + 可替换 LLM 推理层”的组合架构，而不是把所有能力都抽象成完全可替换的通用 provider

默认路径

下面这些路径是当前 skill 的默认约定：

WORKSPACE_ROOT=~/.openclaw/workspace
SKILL_ROOT=$WORKSPACE_ROOT/skills/audiobook
EXAMPLES_ROOT=$SKILL_ROOT/examples
VOICE_LIBRARY=$WORKSPACE_ROOT/audiobook-library/voice-library.yaml
LIBRARY_ROOT=$WORKSPACE_ROOT/audiobook-library
STORY_ROOT=$WORKSPACE_ROOT/audiobook-stories          # 推荐放原始 txt / yaml / json
RUN_ROOT=$WORKSPACE_ROOT/runs/audiobook

下面所有命令示例默认都在 "$SKILL_ROOT" 目录里执行。也就是说，推荐先：

cd "$SKILL_ROOT"

如果你不想切换目录，请把文档里的 scripts/<name>.py 改成对应脚本的绝对路径。

关键位置：

音色库入口：$VOICE_LIBRARY
用户待分析音频投递区：$LIBRARY_ROOT/voices/inbox/
长期参考音频目录：$LIBRARY_ROOT/voices/references/<asset_id>/
音色分析 / cache / 统一音色候选池：$LIBRARY_ROOT/.audiobook/
每本书的中间产物与最终产物：$RUN_ROOT/<slug>/
轻量参考示例：$EXAMPLES_ROOT/

推荐但不强制：把原始小说文件统一放在 ~/.openclaw/workspace/audiobook-stories/。脚本支持任意绝对路径输入，但统一目录更方便程序化管理。

运行前准备

在执行任何主流程前，确保：

环境里有 STEP_API_KEY
系统已安装 ffmpeg
最终导出或时长探测时，系统已安装 ffprobe

安全与付费提示

audiobook 现在建议显式调用，不建议依赖隐式注入；这是一个会读写本地文件、并可能访问外部 API 的工作流型 skill。
默认的音频分析、官方音色、音色复刻、TTS 合成都会访问 Step 相关接口；长文本理解层如果你改了 voice-library.yaml -> llm.*.base_url，则会访问你自己配置的兼容 LLM endpoint。
建议优先使用测试 key、受限 key，或至少在第一次运行后做轮换；如果你不完全信任当前配置，先在隔离环境或沙箱里跑一遍。
ffmpeg / ffprobe 请只从可信来源安装。
真正可能触发付费的只有 clone_selected_voices.py；而且现在除了 selected_for_clone=true 之外，还必须显式传入 --confirm-paid-action 才会执行正式 clone。
run_audiobook.py 默认只会对 clone 阶段做 --dry-run 预览，不会自动代替你执行正式付费 clone。
如果你在做安全审查，或想确认默认会访问哪些 endpoint、会读取哪些环境变量，直接看 references/security.md。

如果本地还没有 voice-library.yaml，先用模板初始化：

mkdir -p "$LIBRARY_ROOT"
cp \
  "$SKILL_ROOT/assets/voice-library.template.yaml" \
  "$VOICE_LIBRARY"

如果你希望在第一次 ingest 前就看到带注释的人工审核骨架，也可以顺手初始化：

cp \
  "$SKILL_ROOT/assets/voice-reviews.template.yaml" \
  "$LIBRARY_ROOT/voice-reviews.yaml"

最小示例

examples/ 目录现在提供 7 个轻量示例，适合先理解结构，再复制到自己的工作区继续改：

examples/story-minimal.txt：最小原始小说文本
examples/story-minimal.structured-script.yaml：对应的最小结构化剧本
examples/voice-library.minimal.yaml：最小音色库配置示例
examples/voice-reviews.minimal.yaml：最小人工审核示例
examples/story-minimal.casting-plan.yaml：最小可下游继续的选角结果示例
examples/story-minimal.tts-requests.json：最小可 replay 的 TTS 请求示例
examples/story-minimal.script-runtime.json：由 build_tts_requests.py 生成的规范化剧本 companion

使用原则：

真正初始化库文件时，优先复制 assets/*.template.yaml
examples/*minimal* 更适合“照着看结构”“复制局部片段”“给程序做字段对齐”
examples/*.json / *.yaml 里的路径字段已经改成 $EXAMPLES_ROOT / $RUN_ROOT 占位，不包含本机绝对路径
不建议把 examples/voice-library.minimal.yaml 直接当成长期运行时库文件

最常用的入口

一次性跑完整主流程时，优先用：

python3 scripts/run_audiobook.py --library "$VOICE_LIBRARY" --story-input /绝对路径/小说.txt

这条命令会按顺序尝试：

刷新官方音色 cache
处理 --voice-input 或 --process-inbox 指定的新音频
如果输入是 txt，先生成 structured-script
生成 casting-review、casting-plan、clone-review
预览本次哪些 clone 值得付费复刻
当角色和 clone 状态允许继续时，再进入 tts-requests -> synthesize -> finalize

如果你要分步执行，建议顺序见 references/workflows.md。

中间产物怎么查看

每本书都有一份统一清单：

~/.openclaw/workspace/runs/audiobook/<slug>/<base>.artifacts.json

它会列出：

源文本 / 结构化剧本
选角审核与生效结果
音色库侧的 voice-reviews、effective-voice-library、voice-candidate-pool、official-voices-cache
script-runtime、tts-requests
segments/
最近一次导出与最终成品

人类查看时：

python3 scripts/list_story_artifacts.py --manifest /绝对路径/<base>.artifacts.json --level review --pretty

程序调用时：直接读取 artifacts.json 即可，不需要硬编码路径推导。

如果你只想快速看音色库里还有哪些 clone 描述待人工确认，用：

python3 scripts/list_pending_reviews.py --library "$VOICE_LIBRARY" --pretty

哪些文件可以改，哪些文件不要改

建议人工编辑的文件：

voice-reviews.yaml
*.casting-review.yaml
*.clone-review.yaml
*.structured-script.yaml
*.tts-requests.json

不建议直接编辑的生成文件：

.audiobook/effective-voice-library.yaml
.audiobook/voice-candidate-pool.yaml
.audiobook/official-voices-cache.json
*.casting-plan.yaml（除非你明确知道自己在做什么）
*.script-runtime.json
*.artifacts.json

改完后的重跑命令见 references/editing.md。

两套 `.audiobook/` 的区别

这是最容易混淆的点：

~/.openclaw/workspace/audiobook-library/.audiobook/：音色库侧生成文件
~/.openclaw/workspace/runs/audiobook/<slug>/.audiobook/：某本书本次运行的 trace / debug 文件

前者服务整个音色库；后者只服务单次故事流程。

付费边界

clone_selected_voices.py 是唯一会触发付费 clone 的步骤。默认流程只会：

分析参考音频
生成 clone 候选
在 clone-review.yaml 里等待确认

真正执行前请先跑：

python3 scripts/clone_selected_voices.py --library "$VOICE_LIBRARY" --dry-run

正式执行时，现在必须额外确认：

python3 scripts/clone_selected_voices.py --library "$VOICE_LIBRARY" --confirm-paid-action

机器可读接口

下面这些脚本都输出 JSON 到 stdout，适合程序调用：

sync_voice_library.py
generate_structured_script.py
recommend_casting.py
build_tts_requests.py
synthesize_tts_requests.py
finalize_audiobook.py
run_audiobook.py

对程序来说，最稳的组合是：

调主脚本拿 stdout JSON
再读取 artifacts.json 拿完整文件清单

参考文档索引 / Reference Index

如果你是人类用户，建议优先看中文；如果你是英文环境下的 agent 或程序，可直接读对应的英文 companion 文档。

完整执行顺序 / full workflow：中文 references/workflows.md｜English references/workflows.en.md
音色库结构与字段 / voice library structure：中文 references/voice-library.md｜English references/voice-library.en.md
结构化剧本格式 / structured script format：中文 references/script-format.md｜English references/script-format.en.md
选角规则与输出 / casting rules and outputs：中文 references/casting.md｜English references/casting.en.md
TTS、replay 与最终导出 / synthesis and export：中文 references/synthesis.md｜English references/synthesis.en.md
人工修改与重跑 / manual editing and reruns：中文 references/editing.md｜English references/editing.en.md
安全与外部访问 / security and external access：中文 references/security.md｜English references/security.en.md

如果你只是想快速进入某个主题，推荐顺序是：

想看整体链路：先读 references/workflows.md
想维护音色库：再读 references/voice-library.md
想修改中间产物：直接读 references/editing.md

audiobook

Safety Notice

Copy this and send it to your AI assistant to learn

Audiobook

能力范围

术语约定

LLM 可替换边界

默认路径

运行前准备

安全与付费提示

最小示例

最常用的入口

推荐命令顺序

1. 音色库同步 / 音频分析

2. 原始小说转结构化剧本

3. 生成角色选角结果

4. 构建可重放的 TTS 请求

5. 实际合成分段音频

6. 导出整本或试听片段

中间产物怎么查看

哪些文件可以改，哪些文件不要改

两套 `.audiobook/` 的区别

付费边界

机器可读接口

参考文档索引 / Reference Index

Source Transparency

Related Skills

Batch Content Factory

Fund Analyzer Pro

FN Portrait Toolkit

流式AI检索问答技能

audiobook

Safety Notice

Copy this and send it to your AI assistant to learn

Audiobook

能力范围

术语约定

LLM 可替换边界

默认路径

运行前准备

安全与付费提示

最小示例

最常用的入口

推荐命令顺序

1. 音色库同步 / 音频分析

2. 原始小说转结构化剧本

3. 生成角色选角结果

4. 构建可重放的 TTS 请求

5. 实际合成分段音频

6. 导出整本或试听片段

中间产物怎么查看

哪些文件可以改，哪些文件不要改

两套 .audiobook/ 的区别

付费边界

机器可读接口

参考文档索引 / Reference Index

Source Transparency

Related Skills

Batch Content Factory

Fund Analyzer Pro

FN Portrait Toolkit

流式AI检索问答技能

两套 `.audiobook/` 的区别