本文適合誰：想做電影解說但不想一直在多個(gè)軟件之間來回切換的內(nèi)容創(chuàng)作者；習(xí)慣用命令行或腳本批量處理任務(wù)的技術(shù)用戶；正在用小龍蝦、Windsurf、QClaw 等 AI Agent、想把電影解說能力直接接進(jìn)工作流的開發(fā)者。
一、AI 電影解說的工序痛點(diǎn)：為什么你需要一個(gè)命令行方案
做過電影解說的人都經(jīng)歷過同一種崩潰：素材在剪映里，文案要去大模型對(duì)話框里改，字幕要開另一款軟件壓，改完時(shí)間軸又對(duì)不上。每個(gè)工具單獨(dú)用都挺順手，但工具和工具之間沒有打通，每次切換都在漏時(shí)間。
NarratoAI 是目前做得比較完整的解決方案之一，把解說流水線打包進(jìn)了 streamlit WebUI。但 WebUI 有 WebUI 的局限：必須本地跑 Web 服務(wù)、必須開瀏覽器操作、沒辦法寫成腳本批量跑、也沒辦法接進(jìn)任何 Agent 工作流。
narrator-ai-cli 走的是另一條路——命令行原生，一條命令驅(qū)動(dòng)從字幕提取到成片輸出的整條流水線。配套的 SKILL.md 讓小龍蝦、Windsurf、QClaw 等 Agent 直接讀懂怎么調(diào)用它，你在對(duì)話框里說一句話，Agent 把后面的事做完。
本文是這套工具鏈從安裝到出片的完整記錄。
二、narrator-ai-cli 架構(gòu)解析：CLI、Skill 與本地優(yōu)先設(shè)計(jì)
narrator-ai-cli 背后有兩個(gè)開源倉庫，分工不同，配合使用：
narrator-ai-cli（https://github.com/jieshuo-ai/narrator-ai-cli）是 Python 命令行工具，負(fù)責(zé)本地文件處理、素材調(diào)度、以及跟 AI 解說大師開放接口（docs.jieshuo.cn）的通信。你在終端里敲的每一條命令，最終都通過它轉(zhuǎn)化成對(duì)后端 40 多個(gè)開放端點(diǎn)的 HTTP 調(diào)用。
narrator-ai-cli-skill（https://github.com/jieshuo-ai/narrator-ai-cli-skill）是一份 SKILL.md 文件，用自然語言加結(jié)構(gòu)化指令寫清了每個(gè) CLI 子命令什么時(shí)候用、參數(shù)怎么傳、前置依賴是什么。這份文件是寫給 Agent 讀的——Agent 加載它之后，就知道在什么情況下調(diào)哪條命令、拿到返回結(jié)果之后怎么接著走。
兩者的關(guān)系可以這樣理解：CLI 是手，Skill 是腦。
這套工具鏈在工程設(shè)計(jì)上有一個(gè)值得單獨(dú)說的特點(diǎn)：本地優(yōu)先（local-first）架構(gòu)。傳統(tǒng) SaaS 視頻處理產(chǎn)品的流程是把視頻上傳到云端、云端處理、再把結(jié)果鏈接返回給你。narrator-ai-cli 反過來——原片始終待在你的本地硬盤上，只有字幕文本（幾十 KB 的 SRT）、關(guān)鍵幀序列（幾 MB 的 JPEG）、生成好的配音（幾 MB 的 MP3）這些輕量載荷跟云端往返。一部 90 分鐘 1080P 的電影大約 2 到 4 GB，全程不上傳，帶寬要求極低，4G 信號(hào)都能穩(wěn)定跑完整條流程。
根據(jù)使用場(chǎng)景不同，這套工具鏈有三條調(diào)用路徑可以選：
直接調(diào) API：適合要把解說能力嵌入自己產(chǎn)品的開發(fā)團(tuán)隊(duì)，最靈活，也最重，需要自己處理文件上傳、輪詢、錯(cuò)誤處理
用 CLI：適合命令行熟悉的個(gè)人創(chuàng)作者和運(yùn)營團(tuán)隊(duì)，一條命令完成一類任務(wù)，可以嵌進(jìn) bash 腳本批量跑
用 Skill + Agent：適合不想碰命令行的內(nèi)容創(chuàng)作者，自然語言表達(dá)意圖，Agent 自己完成規(guī)劃和執(zhí)行
三條路徑共用同一套賬號(hào)和配額，互不干擾。一個(gè)團(tuán)隊(duì)里完全可以技術(shù)同事用 API 做產(chǎn)品集成、運(yùn)營同事用 CLI 跑腳本、內(nèi)容團(tuán)隊(duì)用 Skill 驅(qū)動(dòng)日常創(chuàng)作。
三、系統(tǒng)要求與環(huán)境依賴：Python 3.10+、Git、無需 GPU
先把環(huán)境要求列清楚，省得裝到一半發(fā)現(xiàn)缺東西。
必須有的：
Python 3.10 或更高版本
Git 最新版
操作系統(tǒng)：Windows 10/11 或 macOS 11 及以上
硬件最低配置：
CPU 4 核、內(nèi)存 8G、磁盤預(yù)留 5G（用于 CLI 本體和臨時(shí)文件）
網(wǎng)絡(luò)：
國內(nèi)用戶建議提前準(zhǔn)備好 GitHub 加速鏡像的訪問方式，安裝步驟里會(huì)給出具體鏡像前綴
不需要的（這一條值得單獨(dú)說）：
不需要 GPU
不需要本地部署任何大模型
不需要安裝 streamlit
不需要跑 Docker
不需要 CUDA 或 pytorch
對(duì)比 NarratoAI 的依賴清單（pytorch、CUDA、streamlit、ffmpeg-python、各類模型權(quán)重文件），narrator-ai-cli 的環(huán)境要求輕得多。模型計(jì)算全部在云端完成，本地只做文件處理和最終合成。
四、narrator-ai-cli 安裝教程：Windows / macOS 全平臺(tái)部署指南
Windows 安裝
第一步：裝 Python
打開 python.org，點(diǎn)頁面頂部黃色的 Download Python 按鈕下載安裝包。安裝程序啟動(dòng)后，首屏最下方有一個(gè)小復(fù)選框，務(wù)必勾上 Add python.exe to PATH。這一步很多人第一次裝會(huì)跳過，跳過之后后面所有終端命令都會(huì)提示"不是內(nèi)部或外部命令"，是最高頻的報(bào)錯(cuò)來源。勾好之后點(diǎn) Install Now 等它跑完。
裝完之后，把所有已經(jīng)開著的命令提示符窗口全部關(guān)掉，重開一個(gè)新窗口，輸入驗(yàn)證：
python --version
看到
Python 3.10.x或更高版本號(hào)就 OK。
第二步：裝 Git
去 git-scm.com/download/win 下載安裝包，安裝過程一路 Next，默認(rèn)設(shè)置不需要改。裝完同樣關(guān)終端重開，輸入：
git --version
看到
git version 2.x.x說明成功。
第三步：裝 CLI
主路徑，一條命令搞定：
python -c "import urllib.request; exec(urllib.request.urlopen('https://raw.githubusercontent.com/jieshuo-ai/narrator-ai-cli/main/install.py').read())"
正常情況下 1 到 3 分鐘跑完，看到 successfully installed 的提示就完成了。
如果 30 秒之內(nèi)屏幕沒有任何反應(yīng)，大概率是國內(nèi)訪問 GitHub 受限。按 Ctrl+C 終止，改走手動(dòng)方案：
git clone https://ghfast.top/https://github.com/jieshuo-ai/narrator-ai-cli.git
cd narrator-ai-cli
pip install -e .
https://ghfast.top/是 GitHub 鏡像加速前綴，如果它也打不開，把前綴換成https://mirror.ghproxy.com/再試一次。驗(yàn)證安裝：
narrator-ai-cli --version
看到版本號(hào)輸出，全部搞定。
macOS 安裝
第一步：裝 Python
兩種方式都可以。一是去 python.org 下 .pkg 雙擊安裝；二是通過 Homebrew 執(zhí)行：
brew install python@3.10
驗(yàn)證時(shí)注意用
python3，不要用python——macOS 自帶的python可能指向系統(tǒng)老版本：python3 --version
第二步：裝 Git
最省事的方式是在終端執(zhí)行：
xcode-select --install
系統(tǒng)會(huì)彈出對(duì)話框，點(diǎn)"安裝"等它跑完。如果磁盤空間緊張（Xcode 命令行工具約占 17G），改用：
brew install git
只占幾百兆。
第三步：裝 CLI
curl -fsSL https://raw.githubusercontent.com/jieshuo-ai/narrator-ai-cli/main/install.py | python3
GitHub 訪問受限時(shí)同樣用鏡像前綴手動(dòng) clone：
git clone https://ghfast.top/https://github.com/jieshuo-ai/narrator-ai-cli.git
cd narrator-ai-cli
pip3 install -e .
驗(yàn)證安裝：
narrator-ai-cli --version
如果提示
command not found，先執(zhí)行：source ~/.zshrc
刷新 shell 環(huán)境變量再試，通常就通了。
五、API Key 配置與鑒權(quán)：narrator-ai-cli 接入 AI 解說大師開放接口
CLI 裝完之后還不知道你的賬戶信息。你需要先拿到一把 APP Key，按照github里的appkey獲取方式，發(fā)送郵件獲取key。
拿到之后在終端輸入：
narrator-ai-cli config set app_key 你的API_Key
這條命令會(huì)把 Key 寫入本地配置文件（默認(rèn)在用戶目錄下的 .narrator-ai-cli 隱藏目錄）。驗(yàn)證是否成功：
narrator-ai-cli user balance
看到賬戶余額返回，說明鏈路打通，可以開始用了。
配置文件完整字段參考：
~/.narrator-ai-cli/config.toml
app_key ? ? ? ?= "your_api_key_here"
default_platform = "抖音"
default_dubbing ?= "male"
default_bgm ? ? ?= "輕快節(jié)奏"
output_dir ? ? ? = "~/Videos/output"
default_platform 會(huì)影響文案生成的節(jié)奏和用詞風(fēng)格——發(fā)抖音的解說需要前三秒出鉤子、語速偏快；發(fā) B 站的可以更慢、更注重信息密度。這不是噱頭，是后端模型真實(shí)的參數(shù)級(jí)控制。
如果你在團(tuán)隊(duì)里用，還有一套子 Key 體系值得了解：主賬號(hào)可以創(chuàng)建多個(gè)子 Key、給每把子 Key 單獨(dú)配置額度。MCN 團(tuán)隊(duì)里三個(gè)賬號(hào)運(yùn)營各用一把子 Key，用完互不干擾，主賬號(hào)統(tǒng)一結(jié)算。
六、三種調(diào)用模式實(shí)戰(zhàn)：一次性出片、分步接口與 Agent Skill 驅(qū)動(dòng)
模式一：一條命令出片
最快的路徑。對(duì)應(yīng)后端的"通用爆款解說（電影）"一次性調(diào)用：
narrator-ai-cli commentary create-movie \
?--movie-file ~/Videos/feichi.mp4 \
?--platform "抖音" \
?--dubbing male \
?--bgm "輕快節(jié)奏" \
?--task-count 1 \
?--output ~/Videos/feichi_解說.mp4
命令回車之后，CLI 會(huì)先做本地預(yù)處理（字幕提取、關(guān)鍵幀抽取），然后在正式扣費(fèi)之前顯示一次點(diǎn)數(shù)消耗預(yù)估：
預(yù)估消耗：爆款學(xué)習(xí)點(diǎn)數(shù)：0.00
?文案生成點(diǎn)數(shù)：140.00
?視頻合成點(diǎn)數(shù)：165.55
?總計(jì)：305.55 點(diǎn)
當(dāng)前余額：XXXX.XX 點(diǎn)
是否繼續(xù)？(y/N)
這組數(shù)字是后端接口真實(shí)返回的，不是估算。你可以在任務(wù)啟動(dòng)之前精確知道要花多少，回復(fù) y 確認(rèn)之后才開始扣費(fèi)。
--task-count 參數(shù)值得單獨(dú)說一下。傳 3 的話，后端會(huì)用同一組素材生成 3 個(gè)不同變體，方便你在幾個(gè)候選里挑一個(gè)發(fā)布。做 A/B 測(cè)試或者賬號(hào)矩陣的人幾乎必用這個(gè)參數(shù)。
任務(wù)跑完后 CLI 拉回生成好的文案與配音，在本地完成最終合成，成片路徑直接打印出來。
模式二：分步接口（可介入中間環(huán)節(jié)）
一次性調(diào)用的問題是你沒法干預(yù)文案。分步接口把整條流水線拆成獨(dú)立的幾步，每步都有獨(dú)立任務(wù)號(hào)和中間產(chǎn)物，你可以在任意一步暫停、審閱、修改，再繼續(xù)往下走。
Step 1：爆款風(fēng)格學(xué)習(xí)
找一段你想模仿風(fēng)格的參考視頻（30 秒到幾分鐘都行），讓 CLI 從中學(xué)習(xí)它的句式節(jié)奏和鉤子結(jié)構(gòu)：
narrator-ai-cli commentary learn \
?--reference-file ~/Videos/reference_clip.mp4 \
?--narrator-type 電影 \
?--model-version advanced
返回一個(gè) learning_model_id，形如 narrator-20250929163803-MSBmuw。這一步本身不消耗點(diǎn)數(shù)，相當(dāng)于"試學(xué)免費(fèi)"，你可以先拿參考素材學(xué)一下看適不適合這個(gè)風(fēng)格，適合再往下跑。
Step 2：生成解說文案
narrator-ai-cli commentary generate \
?--movie-file ~/Videos/feichi.mp4 \
?--learning-model-id narrator-20250929163803-MSBmuw \
?--platform "抖音" \
?--task-count 1
CLI 輪詢后端任務(wù)狀態(tài)，完成后把生成好的文案稿輸出到終端或本地文件。
Step 3：人工審閱（這一步是手動(dòng)的）
這是分步調(diào)用相對(duì)一次性調(diào)用最大的優(yōu)勢(shì)所在。你可以在這里讀文案、改措辭、調(diào)節(jié)奏，甚至完全重寫某幾段，滿意之后再往下走。
Step 4：合成最終視頻
narrator-ai-cli commentary compose \
?--task-id 6daeda059326491d996cac6396e8a4dc \
?--output ~/Videos/feichi_解說.mp4
CLI 拿著審閱后的文案調(diào)配音合成，再用本地 FFmpeg 把原片畫面、配音、BGM、字幕疊在一起，輸出成片。
模式三：Agent 對(duì)話驅(qū)動(dòng)（Skill 模式）
如果你已經(jīng)在用小龍蝦 OpenClaw、Windsurf、QClaw 或者 WorkBuddy，可以把 narrator-ai-cli-skill 倉庫里的 SKILL.md 裝進(jìn)去，之后直接用自然語言驅(qū)動(dòng)整條流水線。
加載方式以小龍蝦為例：
mkdir -p ~/.openclaw/skills/narrator-ai-cli
cp SKILL.md ~/.openclaw/skills/narrator-ai-cli/SKILL.md
Windsurf 把 SKILL.md 放到項(xiàng)目的 .skills/narrator-ai-cli/ 目錄下，IDE 啟動(dòng)時(shí)自動(dòng)讀取。QClaw 和 WorkBuddy 在技能管理界面直接上傳文件即可。
加載完成后，在對(duì)話框里說：
幫我把 ~/Videos/feichi.mp4 做成爆笑喜劇風(fēng)格的電影解說，輸出到同目錄。
Agent 接到指令后會(huì)自動(dòng)完成：讀取本地視頻元信息 → 字幕提取與關(guān)鍵幀抽取 → 篩選爆笑喜劇風(fēng)格學(xué)習(xí)模型 → 選配音角色和 BGM → 向你確認(rèn)點(diǎn)數(shù)消耗 → 文案生成與配音合成 → 本地 FFmpeg 最終合成 → 輸出成片。
你唯一需要做的，是在它問"本次消耗 X 點(diǎn)數(shù)，是否繼續(xù)"時(shí)回復(fù)一個(gè)"確認(rèn)"。
相關(guān)鏈接
七、常見報(bào)錯(cuò)排查：command not found、401、無聲音等問題解決方案
按照實(shí)際使用中出現(xiàn)頻率從高到低，把常見問題逐條說清楚。
narrator-ai-cli: command not found
這是安裝后最常見的第一個(gè)問題，原因是 shell 的環(huán)境變量還沒刷新，新裝的命令還沒被系統(tǒng)識(shí)別到。macOS 用戶執(zhí)行 source ~/.zshrc，Windows 用戶關(guān)掉當(dāng)前終端窗口重開一個(gè)新的，再試一次基本就解決了。如果還不行，檢查 pip 的安裝路徑是否在系統(tǒng) PATH 里。
Windows 上 python: command not found
安裝 Python 時(shí)首屏沒有勾選 Add python.exe to PATH。解決方法是重新運(yùn)行 Python 安裝包，選"Modify"，在 Optional Features 頁面確認(rèn)勾選了 PATH 選項(xiàng)，或者直接卸載重裝，這次記得勾。
安裝命令執(zhí)行后 30 秒內(nèi)屏幕沒有任何反應(yīng)
國內(nèi)訪問 GitHub 受限導(dǎo)致的。按 Ctrl+C 終止，改用鏡像前綴手動(dòng) clone：
git clone https://ghfast.top/https://github.com/jieshuo-ai/narrator-ai-cli.git
cd narrator-ai-cli
pip install -e .
如果 ghfast.top 也不通，把前綴換成 https://mirror.ghproxy.com/ 再試。
narrator-ai-cli user balance 返回 401
API Key 沒有配置，或者配置時(shí)寫錯(cuò)了。重新執(zhí)行一次：
narrator-ai-cli config set app_key 你的API_Key
注意 Key 前后不要有多余的空格，復(fù)制粘貼時(shí)有時(shí)會(huì)帶上。
合成出來的視頻沒有聲音
本地沒有安裝 FFmpeg，或者 FFmpeg 沒有加入系統(tǒng) PATH。macOS 執(zhí)行 brew install ffmpeg；Windows 去 ffmpeg.org 下載，解壓后把 bin 目錄路徑加進(jìn)系統(tǒng)環(huán)境變量，關(guān)終端重開驗(yàn)證 ffmpeg -version。
點(diǎn)數(shù)不足提示
執(zhí)行 narrator-ai-cli user balance 查當(dāng)前余額，余額不足時(shí)聯(lián)系商務(wù)充值。如果余額顯示正常但仍然報(bào)點(diǎn)數(shù)不足，檢查是否在用子 Key，子 Key 有單獨(dú)的額度上限，可能是子 Key 額度耗盡而主賬號(hào)余額還有。
八、narrator-ai-cli 能力全景：語音克隆、Remotion 渲染與批量生產(chǎn)實(shí)踐
narrator-ai-cli 目前覆蓋的能力，遠(yuǎn)不止"生成一條電影解說"這一件事。完整的后端接口圖譜包括：資源檢索與項(xiàng)目管理、爆款解說一次性調(diào)用與分步接口、多模態(tài)視頻理解、TTS 語音合成（63 個(gè)角色、11 種語言）、語音克隆、字幕擦除與壓制、Remotion 模板渲染、智能封面生成。這些能力都掛在 CLI 子命令下，narrator-ai-cli --help 是最新可用命令的真實(shí)來源。
如果你已經(jīng)跑通了第一條電影解說，下面幾件事值得接著試：
試試語音克隆加停頓語法的組合。 錄一段你欣賞的博主的 30 秒清晰音頻，通過 CLI 的語音克隆子命令完成克隆。然后在解說文案的關(guān)鍵節(jié)奏點(diǎn)插入 <#0.5#> 停頓語法，用克隆模型做 TTS 合成。效果跟"直接讓大模型念出來"完全是兩個(gè)層次。
試試兩個(gè)不同風(fēng)格的學(xué)習(xí)模型對(duì)比。 找兩段風(fēng)格完全不同的爆款解說短視頻（比如一段"懸疑沉穩(wěn)"、一段"爆笑吐槽"），分別創(chuàng)建兩個(gè) learning_model，用同一部電影分別生成兩份文案對(duì)比。你會(huì)直觀看到"風(fēng)格模板"這個(gè)參數(shù)在后端到底做了多少事。
試試 --task-count 3 的 A/B 測(cè)試用法。 同一部電影一次生成 3 個(gè)變體，發(fā)到不同賬號(hào)或者同賬號(hào)不同時(shí)段，看哪個(gè)版本的完播率和互動(dòng)數(shù)據(jù)更好，下次生產(chǎn)就往那個(gè)方向靠。
試試把 CLI 嵌進(jìn) bash 腳本做批量生產(chǎn)。 如果你手里有一批待解說的素材，寫一個(gè)簡(jiǎn)單的循環(huán)腳本，讓 CLI 跑一晚上，早上起來看結(jié)果。本地優(yōu)先架構(gòu)的好處在這里體現(xiàn)得最明顯——網(wǎng)絡(luò)抖動(dòng)最多影響當(dāng)次 API 調(diào)用，重試一下就過，不會(huì)因?yàn)榇笪募鬏斨袛嗲肮ΡM棄。
#電影解說#github開源#skill#cli#多模態(tài)視頻理解#tts語音合成#語音克隆#視頻剪輯#AI解說大師
