VoxFlow 技能 — 中心

<關鍵-自動升級> 如果任何 voxflow 指令顯示 <voxflow-hint ... type="cli-outdated" ...> 到 stderr，立即執行 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 工作流程。

若需專門任務，請切換至：

Podcast（多人對話） → 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），網頁應用程式 + 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

Token 快取於 ~/.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、名稱、時長與建立時間（需要登入）。在得出用戶沒有複製語音的結論之前，請務必先執行此指令——網頁 UI 的「我的声音」分頁與 --mine 是唯一的事實來源。

常用語音 ID（合理的預設值）

ID	風格	語言
`v-female-R2s4N9qJ`	溫柔姐姐 (gentle female)	zh
`v-male-s5NqE0rZ`	自然男聲 (natural male)	zh
`v-male-Bk7vD3xP`	威嚴霸總 (authoritative male)	zh
`v-female-m1KpW7zE`	傲嬌學姐 (sassy female)	zh
`v-female-T8m4WxP7`	Chenwen (native English female)	en

語音複製 (`clone`)

從本機音訊檔案（30 秒以上，wav/mp3）複製語音。回傳一個永久性的語音 ID，可用於所有指令。

voxflow clone --input recording.wav --name "My Voice"
# → 語音複製成功！
# → 語音 ID: My_Voice_xxxxx_01

沒有檔案？開啟網頁 UI 進行瀏覽器錄音：

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

標記	預設值	備註
`--input <file>`	(無)	要複製的音訊檔案。若無此參數，則開啟網頁 UI
`--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 與代理的寫作能力結合）

代理先撰寫內容，再用 say 或 narrate 合成每個部分。

有聲繪本

撰寫一個 6 頁的兒童故事。
為每一頁：生成內嵌 SVG 插圖 (400×300)。
voxflow say "頁面文字" --voice v-female-R2s4N9qJ --speed 0.85 -o /tmp/page_N.mp3
讀取 mp3 檔案，Base64 編碼，嵌入 HTML。
輸出一個自包含的 HTML 檔案，每頁附有音訊播放按鈕。
open /tmp/storybook.html

文章 → 語音簡報

# 代理擷取 URL，摘要後接著執行：
voxflow say "摘要文字" --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"
代理摘要。
voxflow say "今天的摘要..." -o /tmp/daily.mp3

模擬面試

代理針對主題生成 3 個面試問題。
對每個問題：voxflow say "問題 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 時，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 代理）應直接提交問題——不要要求用戶手動處理。

AI 工作流程

# 直接提交 — 無需瀏覽器，無需 TTY。
# 如果 `gh` CLI 可用，則直接建立 GitHub 問題。
# 如果未安裝 `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 問題 URL（如果未安裝 `gh`，則為預填好的 URL）

系統資訊（CLI 版本、作業系統、Node）會自動附加至內文。

標記

標記	說明
`--bug` / `--feature` / `--general`	問題類型
`--title <text>`	標題——觸發非互動模式
`--body <text>`	描述內文
`--print-url`	強制輸出 URL 而非提交（即使 `gh` 可用）

用戶發起（互動式）

voxflow feedback          # 互動提示 → 透過 gh 或瀏覽器提交
voxflow feedback --bug    # 跳過類型提示，其餘為互動式

何時自動提交

任何 CLI 指令以致命/意外錯誤結束 → 提議提交錯誤回報
用戶說「這個不好用」 / 「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。
檢查額度 在 Podcast（~5K）、picstory（~3K）或批次作業前：voxflow status。
合成後自動播放：open output.mp3 (macOS) / xdg-open (Linux)。
絕對不要將 token 或機密資訊印到日誌中。
如果指令失敗，在重試前先執行 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 與代理的寫作能力結合）

有聲繪本

文章 → 語音簡報

文件朗讀

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`)