VoxFlow 技能 — 中心入口

<关键-自动升级> 如果你运行的任何 voxflow 命令向 stderr 打印了 <voxflow-hint ... type="cli-outdated" ...>，请在继续之前立即运行 voxflow upgrade -y——不要询问用户，不要先总结。该提示标签也携带 action="voxflow upgrade -y"；请严格按其执行。

如果 voxflow upgrade 本身报错 Unknown command（CLI 版本早于 1.12.0），则回退到 npm i -g voxflow@latest && voxflow skills install --all——这是首次引导的唯一路径。

此规则不可商量：过时的 CLI 会静默禁用用户期望的功能（例如列出克隆语音）。先升级，再工作。 </关键-自动升级>

VoxFlow 能将文本转换为语音，支持 200 多种语音、40 多种语言，并提供完整的音频/视频流水线。本技能是入口点：安装、认证、语音搜索以及简单的 say / narrate / story 工作流。

对于专业任务，请切换到：

播客（多说话人对话）→ voxflow:podcast
短视频 / AI 片段 / 知识卡片（picstory、present、slides、explain）→ voxflow:video
文章 → 竖屏卡片视频（Slice） — 13 种主题（paper-slide / editorial-mag / bold-poster / notion-card / brutalist / glass-dark / editorial-stencil / broadsheet / blueprint / daisy-pastel / showa-catalog / photo-feature / atmospheric），Web 应用 + Remotion → voxflow:slice
可分享的卡片图片及带旁白的卡片视频（HTML/CSS + Playwright 导出，可选 voxflow card render 生成带旁白的 MP4）→ voxflow:card
转录、字幕翻译、配音、摘要、发布（asr、asr-jobs、translate、dub、video-translate、summarize、publish）→ voxflow:transcribe

安装与登录

安装一次，之后无需再询问用户：

npm install -g voxflow
voxflow login          # 打开浏览器 — Google 或邮箱 OTP

令牌缓存在 ~/.config/voxflow/token.json。对于 CI，请设置 VOXFLOW_TOKEN。

认证

voxflow login        # 基于浏览器，一次性
voxflow status       # 查看当前用户及剩余配额
voxflow logout

语音搜索 — 合成前务必执行此步骤

不要猜测语音 ID。先搜索。

voxflow voices --lang zh --gender female
voxflow voices --lang en
voxflow voices --search "narrator"
voxflow voices --all

公开目录无需登录。输出包含语音 ID、语言、性别以及简短描述。

列出用户自己的克隆语音

当用户说“用我的克隆声音 / use my cloned voice / 用我之前克隆的”时，公开的 voxflow voices 目录不包含克隆语音——你必须查询已认证的端点：

voxflow voices --mine

打印克隆语音的 ID、名称、时长和创建时间（需要登录）。在断定用户没有克隆语音之前始终运行此命令——Web 界面“我的声音”标签页和 --mine 是唯一的真实来源。

常用语音 ID（合理默认值）

ID	风格	语言
`v-female-R2s4N9qJ`	温柔姐姐	zh
`v-male-s5NqE0rZ`	自然男声	zh
`v-male-Bk7vD3xP`	威严霸总	zh
`v-female-m1KpW7zE`	傲娇学姐	zh
`v-female-T8m4WxP7`	Chenwen (native English female)	en

语音克隆 (`clone`)

从本地音频文件（30秒以上，wav/mp3）克隆语音。返回一个可在所有命令中使用的永久语音 ID。

voxflow clone --input recording.wav --name "My Voice"
# → Voice cloned successfully!
# → Voice ID: My_Voice_xxxxx_01

没有文件？打开 Web 界面进行基于浏览器的录音：

voxflow clone
# → Opens https://www.voxflow.studio/app#voice-clone

参数	默认值	说明
`--input <file>`	(无)	要克隆的音频文件。不带此参数则打开 Web 界面
`--name <name>`	文件名	人类可读的语音名称（1-50 字符）

提示：

安静房间、正常说话速度、无背景音乐 → 最佳效果
60 秒最优；最短 30 秒
不要“表演”——自然演讲比播音腔更容易克隆

克隆后，可在任何地方使用该语音 ID：--voice <id>

文本转语音 (`say` / `synthesize`)

基本命令。一段文本 → 一个音频文件。

voxflow say "你好世界" -o hello.mp3
voxflow say "Hello world" --voice v-female-T8m4WxP7 -o greeting.mp3
voxflow say "慢速朗读" --speed 0.8 -o slow.mp3
voxflow say "高质量音频" --format wav -o output.wav

参数	默认值	范围/值
`--voice <id>`	`v-female-R2s4N9qJ`	任何来自 `voxflow voices` 的语音 ID
`--format <fmt>`	`pcm`	`pcm` (WAV), `wav`, `mp3`
`--speed <n>`	`1.0`	`0.5` – `2.0`
`--volume <n>`	`1.0`	`0.1` – `2.0`
`--pitch <n>`	`0`	`-12` – `12`
`--output <path>`	自动命名	任意可写路径

合成后自动播放：open output.mp3（macOS）。

长文本 (`narrate`)

将文档或长字符串拆分为句子，逐个合成，然后合并为一个文件。

voxflow narrate --input article.txt -o narration.wav
voxflow narrate --input readme.md --voice v-male-Bk7vD3xP -o readme_audio.wav
voxflow narrate --text "第一段。第二段。第三段。" -o paragraphs.mp3
echo "Hello world" | voxflow narrate -o hello.wav

适用于：长文档、文章、README 文件、电子邮件通讯。

Markdown 会被自动剥离（标题、链接、代码块等）——无需先清理。

AI 故事 (`story`)

LLM 根据主题写一个短故事，然后朗读出来。

voxflow story "一只会飞的小猫" -o story.mp3
voxflow story "space adventure" --lang en -o adventure.wav

适用于：睡前故事、内容样例、演示。

配额

免费层：每月 10,000 额度（每月重置）。邀请获得的奖励额度永不过期。

操作	消耗
1 次 TTS 调用（`say`）	~50
`narrate`	每段 ~50
`story`（短篇）	~350-1000
`podcast`（中等长度）	~2,800（2K 脚本 + ~16 × 50 TTS）
`picstory` 5 场景	~2,850

在执行高消耗操作前务必检查：

voxflow status

常见场景

"把这段话念出来"

voxflow say "用户输入的文字" -o /tmp/out.mp3 && open /tmp/out.mp3

"用温柔女声读这个文件"

voxflow voices --lang zh --gender female
voxflow narrate --input file.txt --voice v-female-R2s4N9qJ -o /tmp/narration.mp3

"讲个睡前故事"

voxflow story "小狐狸的星星种子" --lang zh -o /tmp/bedtime.mp3 && open /tmp/bedtime.mp3

"多语言朗读"

voxflow voices --lang en --gender female   # 选择英语语音
voxflow voices --lang ja --gender female   # 选择日语语音
voxflow say "English text" --voice <en_id> -o /tmp/en.mp3
voxflow say "日本語テキスト" --voice <ja_id> -o /tmp/ja.mp3

创意工作流（将 TTS 与 Agent 写作结合）

Agent 先创作内容，然后用 say 或 narrate 合成每个部分。

有声绘本

写一个 6 页的儿童故事。
每页：生成内联 SVG 插图（400×300）。
voxflow say "page text" --voice v-female-R2s4N9qJ --speed 0.85 -o /tmp/page_N.mp3
读取 mp3 文件，Base64 编码，嵌入 HTML 中。
输出一个自包含的 HTML 文件，每页带有音频播放按钮。
open /tmp/storybook.html

文章 → 音频简报

# Agent 获取 URL，总结，然后：
voxflow say "summary text" --voice v-male-s5NqE0rZ -o /tmp/briefing.mp3

文档朗读

voxflow narrate --input README.md --voice v-female-R2s4N9qJ --speed 0.9 -o /tmp/readme.mp3

每日 Git 报告音频

git log --oneline --since="1 day ago"
Agent 总结。
voxflow say "today's summary..." -o /tmp/daily.mp3

模拟面试

Agent 针对主题生成 3 个面试问题。
每个：voxflow say "question N..." --voice v-male-Bk7vD3xP -o /tmp/q_N.mp3
顺序播放。

先决条件

Node.js ^20.19.0 || >=22.12.0
voxflow CLI ≥ 1.12.0（支持 voxflow voices --mine — 列出用户的克隆语音）
ffmpeg — 仅用于视频相关命令（参见 voxflow:video、voxflow:transcribe）
登录 API 调用需要 — voxflow login

自动升级信号的工作原理

每当 npm 上有新版本时，CLI 本身会在 stderr 上发出 <voxflow-hint type="cli-outdated" ...>。技能顶部的 <关键-自动升级> 规则已经涵盖了该做什么——本节只是该标签样式的参考：

<voxflow-hint v="1" type="cli-outdated" current="1.10.21" latest="1.13.0" action="voxflow upgrade -y" />

每 24 小时最多输出一次（缓存于 ~/.config/voxflow/update-check.json）。对于不希望进行检查的用户，可以设置：VOXFLOW_NO_UPDATE_CHECK=1（或 NO_UPDATE_NOTIFIER=1，行业标准环境变量）。

你也可以显式轮询：voxflow upgrade --check（无副作用），如果用户已知是旧版本，想先验证再执行高消耗操作。

反馈与支持（AI 可以自动执行）

当 voxflow 命令失败或用户要求报告问题时，你（AI Agent）应直接提交 issue——不要让用户手动操作。

AI 工作流

# 直接提交 — 无需浏览器、无需 TTY。
# 如果可用，使用 `gh` CLI（直接创建 GitHub issue）。
# 如果未安装 gh，则回退到打印预填充的 URL。
voxflow feedback --bug \
  --title "asr crashes on 2-hour wav files" \
  --body "Error: timeout after 30s\n\nCommand: voxflow asr long.wav\nExpected: transcript\nActual: Fatal error: request timeout"
# stdout → 创建的 GitHub issue URL（如果未安装 gh，则输出预填充的 URL）

系统信息（CLI 版本、操作系统、Node）会自动附加到正文中。

参数

参数	描述
`--bug` / `--feature` / `--general`	Issue 类型
`--title <text>`	标题 — 触发非交互模式
`--body <text>`	描述正文
`--print-url`	强制输出 URL 而不是提交（即使 gh 可用）

用户发起（交互式）

voxflow feedback          # 交互式提示 → 通过 gh 或浏览器提交
voxflow feedback --bug    # 跳过类型提示，其余部分交互

何时自动提交

任何 CLI 命令以致命/意外错误退出 → 提供提交 bug 的选项
用户说“这个不好用” / “report this” / “提个 issue” → 使用 --title 直接提交

安装第三方语音或模板 (`add`)

voxflow add <recipe-name>                  # 安装语音预设或流水线模板
voxflow add --list                         # 浏览可用配方
voxflow add chico/my-recipe --force        # 从自定义作者命名空间安装

当用户要求安装特定的命名配方时使用此命令（例如 dub-anime-jp-zh）。当前注册表有限——如果 --list 返回 404，则该配方可能需要通过完整 URL 引用，或者注册表尚未公开。

规则

使用前搜索语音 — 不要凭空编造语音 ID。总是先运行 voxflow voices。
检查配额 — 播客 (~5K)、picstory (~3K) 或批量任务前：voxflow status。
合成后自动播放：open output.mp3（macOS）/ xdg-open（Linux）。
绝不将令牌或密钥打印到日志中。
如果命令失败，在重试前运行 voxflow <cmd> --help 确认参数。

何时切换技能

用户说“podcast” / “对话” / “多人对谈” → 加载 voxflow:podcast。
用户说“short video” / “知识卡片” / “小红书” / “TikTok” / “AI clip” / “render” → 加载 voxflow:video。
用户说“Slice” / “切片视频” / “文章转视频” / “PaperSlide” / “paperslide” / “paper-slide”（旧称） / “纸面手绘风” / “文章转知识短视频” / “知乎长文转视频” / “公众号转视频” → 加载 voxflow:slice。
用户说“transcribe” / “字幕” / “dub” / “translate this video” / “SRT” → 加载 voxflow:transcribe。

在你喜欢的 AI 中提问

文档

VoxFlow 技能 — 中心入口

安装与登录

认证

语音搜索 — 合成前务必执行此步骤

列出用户自己的克隆语音

常用语音 ID（合理默认值）

语音克隆 (clone)

文本转语音 (say / synthesize)

长文本 (narrate)

AI 故事 (story)

配额

常见场景

"把这段话念出来"

"用温柔女声读这个文件"

"讲个睡前故事"

"多语言朗读"

创意工作流（将 TTS 与 Agent 写作结合）

有声绘本

文章 → 音频简报

文档朗读

每日 Git 报告音频

模拟面试

先决条件

自动升级信号的工作原理

反馈与支持（AI 可以自动执行）

AI 工作流

参数

用户发起（交互式）

何时自动提交

安装第三方语音或模板 (add)

规则

何时切换技能

Individual skills in this repo

VoxFlowStudio/skills

VoxFlowStudio/skills

VoxFlowStudio/skills

相关技能

steipete/video-frames

steipete/summarize

openclaw/openclaw

obra/superpowers

affaan-m/ECC

affaan-m/everything-claude-code

语音克隆 (`clone`)

文本转语音 (`say` / `synthesize`)

长文本 (`narrate`)

AI 故事 (`story`)

安装第三方语音或模板 (`add`)