Skills Atlas — 使用說明書 把自然語言變成影片解說生產線。 narrator-ai-cli-skill 完整拆解。

target_mode="1" 熱門影視：純解說，需 confirmed_movie_json，無需上傳字幕。target_mode="2" 原聲混剪：需 confirmed_movie_json + episodes_data（含 SRT）。target_mode="3" 冷門／新劇：需 episodes_data，confirmed_movie_json 可選。SKILL.md 規定路徑與模式不能寫在同一輪訊息，避免兩層決策被混淆。

底層 narrator-ai-cli（Python，MIT）內建涵蓋 11 個語系的配音與 12 種解說題材的範本（learning_model_id）。SKILL.md 要求代理在會話開場就告知使用者素材庫存在，並提供「直接給片名 ／ 列出內建 ／ 自己上傳」三個入口，省去無謂的檔案上傳。

管線含 popular-learning、generate-writing、fast-writing、clip-data、fast-clip-data、video-composing、magic-video。magic-video 是視覺範本層，按分鐘計費（30 pts／分鐘），依路徑接在不同 task_order_num 之後。

voice-clone 吃 audio_file_id，產出可重複使用的 voice_id；tts 吃 voice_id + audio_text，產出純音訊檔。兩者都接受可選的 clone_model（預設 pro），可在不啟動完整影片合成的情況下用於 podcast、有聲書等場景。

README 提供逐平台的安裝指引。OpenClaw 範例：mkdir -p ~/.openclaw/skills 後 git clone https://github.com/NarratorAI-Studio/narrator-ai-cli-skill.git ~/.openclaw/skills/narrator-ai-cli。對 Claude Code 而言，把整個 repo clone 到 ~/.claude/skills/ 即可載入。

底層 API 為 https://openapi.jieshuo.cn。檔案上傳走預簽 URL → OSS PUT → callback 三步驟，產出 file_id 後綁定到帳號。金鑰存於 ~/.narrator-ai/config.yaml，列入 .gitignore 是基本紀律。

素材：narrator-ai-cli material list --json --page 1 --size 100，必要時用 task search-movie "<title>" --json 查找未在內建庫的片名。BGM 用 bgm list --search "<keyword>"；配音用 dubbing list --lang "<language>"；解說範本用 task narration-styles --genre "<genre>" --json。SKILL.md 強調全部需窮盡分頁、程式化搜尋 JSON，不要靠終端機輸出截斷的結果判斷。

narrator-ai-cli user balance 查帳戶餘額；task budget 對待提交的任務做成本估算；task verify 確認 payload 結構正確再提交。SKILL.md 將「提交前檢查」列為強制流程，特別是 magic-video 必須先把完整 request body 給使用者看過再 submit。

task_id 為 32-char hex，僅供 task query ／ task polling 使用。串接 video-composing 等下游任務必須用建立後回傳的 task_order_num（如 generate_writing_xxxxx 或 fast_writing_clip_data_xxxxx）。代理錯把 hex 丟進 order_num 是最常見的失敗模式。

SKILL.md 規定使用標準 while 迴圈、5 秒間隔進行 task polling，禁用 for i in range(N) 之類的固定上限。video-composing 與 magic-video 的耗時依素材長度差異甚大，固定迴圈幾乎必定錯過完成事件。

writing 任務的 language 參數、dubbing list --lang 篩出的 voice_id、以及 magic-video 內所有文字欄位，必須使用同一語系。SKILL.md 將語言錯位列為禁止行為 — 英文解說配中文視覺範本會被靜默套用預設值，產出無法使用的成片。

material list --json --page 1 --size 100 才能讓代理程式化搜尋。SKILL.md 明確要求窮盡分頁後再對 JSON 結構做篩選 — 直接讀終端機文字會漏掉超過視窗的素材。task create 系列也都用 -d '<params>' --json 取得結構化回傳。

magic-video 為 30 pts／分鐘，且文字欄位若用錯語系會被靜默替換為預設。SKILL.md 將「未顯示完整 payload 直接提交」列為禁止行為 — 代理必須印出組好的 JSON，等使用者顯式 confirm 才執行 task create magic-video。

適合對台詞、節奏要求高的內容。需提供 confirmed_movie_json + episodes_data（包含 SRT），讓 fast-clip-data 在原聲節點切出片段。fast-clip-data 在混剪模式下計費為 40 pts／1k chars，明顯高於純解說 — SKILL.md 要求代理在路徑展示完整成本估算。

走自上傳流程：narrator-ai-cli file upload <path> 取得 file_id 後組出 episodes_data。confirmed_movie_json 此時為可選 — 若代理沒有可信片名資訊，不應該硬填。SKILL.md 的禁止項就包含「在沒有確定來源時偽造 confirmed_movie_json」。

走 popular-learning → generate-writing → clip-data → video-composing。代理需先選一支熱門解說作為風格樣本，generate-writing 會產生 task_order_num，下游 video-composing 鎖在這個 order_num（不是 clip-data 的）。適合 MCN、品牌頻道對品質要求高、願意多花一輪計費的場景。

task create voice-clone --json -d '{"audio_file_id":"<id>"}' 將 30 秒參考音檔產出 voice_id；接著用 task create tts --json -d '{"voice_id":"<id>","audio_text":"…"}' 批量輸出旁白檔。適用於 podcast、有聲書、IVR、品牌語音 — 與影片管線完全解耦，無需任何素材。