*本文适合谁： *想做电影解说但不想一直在多个软件之间来回切换的内容创作者；习惯用命令行或脚本批量处理任务的技术用户；正在用小龙虾、Windsurf、QClaw 等 AI Agent、想把电影解说能力直接接进工作流的开发者。
一、AI 电影解说的工序痛点：为什么你需要一个命令行方案
做过电影解说的人都经历过同一种崩溃：素材在剪映里，文案要去大模型对话框里改，字幕要开另一款软件压，改完时间轴又对不上。每个工具单独用都挺顺手，但工具和工具之间没有打通，每次切换都在漏时间。
NarratoAI 是目前做得比较完整的解决方案之一，把解说流水线打包进了 streamlit WebUI。但 WebUI 有 WebUI 的局限：必须本地跑 Web 服务、必须开浏览器操作、没办法写成脚本批量跑、也没办法接进任何 Agent 工作流。
narrator-ai-cli 走的是另一条路——命令行原生，一条命令驱动从字幕提取到成片输出的整条流水线。配套的 SKILL.md 让小龙虾、Windsurf、QClaw 等 Agent 直接读懂怎么调用它，你在对话框里说一句话，Agent 把后面的事做完。
本文是这套工具链从安装到出片的完整记录。
二、narrator-ai-cli 架构解析：CLI、Skill 与本地优先设计
narrator-ai-cli 背后有两个开源仓库，分工不同，配合使用：
narrator-ai-cli（github.com/jieshuo-ai/… Python 命令行工具，负责本地文件处理、素材调度、以及跟 AI 解说大师开放接口（docs.jieshuo.cn）的通信。你在终端里敲的每一条命令，最终都通过它转化成对后端 40 多个开放端点的 HTTP 调用。
narrator-ai-cli-skill（github.com/jieshuo-ai/… SKILL.md 文件，用自然语言加结构化指令写清了每个 CLI 子命令什么时候用、参数怎么传、前置依赖是什么。这份文件是写给 Agent 读的——Agent 加载它之后，就知道在什么情况下调哪条命令、拿到返回结果之后怎么接着走。
两者的关系可以这样理解：CLI 是手，Skill 是脑。
这套工具链在工程设计上有一个值得单独说的特点：本地优先（local-first）架构。传统 SaaS 视频处理产品的流程是把视频上传到云端、云端处理、再把结果链接返回给你。narrator-ai-cli 反过来——原片始终待在你的本地硬盘上，只有字幕文本（几十 KB 的 SRT）、关键帧序列（几 MB 的 JPEG）、生成好的配音（几 MB 的 MP3）这些轻量载荷跟云端往返。一部 90 分钟 1080P 的电影大约 2 到 4 GB，全程不上传，带宽要求极低，4G 信号都能稳定跑完整条流程。
根据使用场景不同，这套工具链有三条调用路径可以选：
- 直接调 API：适合要把解说能力嵌入自己产品的开发团队，最灵活，也最重，需要自己处理文件上传、轮询、错误处理
- 用 CLI：适合命令行熟悉的个人创作者和运营团队，一条命令完成一类任务，可以嵌进 bash 脚本批量跑
- 用 Skill + Agent：适合不想碰命令行的内容创作者，自然语言表达意图，Agent 自己完成规划和执行
三条路径共用同一套账号和配额，互不干扰。一个团队里完全可以技术同事用 API 做产品集成、运营同事用 CLI 跑脚本、内容团队用 Skill 驱动日常创作。
三、系统要求与环境依赖：Python 3.10+、Git、无需 GPU
先把环境要求列清楚，省得装到一半发现缺东西。
必须有的：
- Python 3.10 或更高版本
- Git 最新版
- 操作系统：Windows 10/11 或 macOS 11 及以上
硬件最低配置：
- CPU 4 核、内存 8G、磁盘预留 5G（用于 CLI 本体和临时文件）
网络：
- 国内用户建议提前准备好 GitHub 加速镜像的访问方式，安装步骤里会给出具体镜像前缀
不需要的（这一条值得单独说）：
- 不需要 GPU
- 不需要本地部署任何大模型
- 不需要安装 streamlit
- 不需要跑 Docker
- 不需要 CUDA 或 pytorch
对比 NarratoAI 的依赖清单（pytorch、CUDA、streamlit、ffmpeg-python、各类模型权重文件），narrator-ai-cli 的环境要求轻得多。模型计算全部在云端完成，本地只做文件处理和最终合成。
四、narrator-ai-cli 安装教程：Windows / macOS 全平台部署指南
Windows 安装
第一步：装 Python
打开 python.org，点页面顶部黄色的 Download Python 按钮下载安装包。安装程序启动后，首屏最下方有一个小复选框，务必勾上 Add python.exe to PATH。这一步很多人第一次装会跳过，跳过之后后面所有终端命令都会提示"不是内部或外部命令"，是最高频的报错来源。勾好之后点 Install Now 等它跑完。
装完之后，把所有已经开着的命令提示符窗口全部关掉，重开一个新窗口，输入验证：
python --version
看到
Python 3.10.x或更高版本号就 OK。
第二步：装 Git
去 git-scm.com/download/win 下载安装包，安装过程一路 Next，默认设置不需要改。装完同样关终端重开，输入：
git --version
看到
git version 2.x.x说明成功。
第三步：装 CLI
主路径，一条命令搞定：
python -c "import urllib.request; exec(urllib.request.urlopen('raw.githubusercontent.com/jieshuo-ai/…)"
正常情况下 1 到 3 分钟跑完，看到 successfully installed 的提示就完成了。
如果 30 秒之内屏幕没有任何反应，大概率是国内访问 GitHub 受限。按 Ctrl+C 终止，改走手动方案：
git clone ghfast.top/https://git…
cd narrator-ai-cli
pip install -e .
https://ghfast.top/是 GitHub 镜像加速前缀，如果它也打不开，把前缀换成https://mirror.ghproxy.com/再试一次。验证安装：
narrator-ai-cli --version
看到版本号输出，全部搞定。
macOS 安装
第一步：装 Python
两种方式都可以。一是去 python.org 下 .pkg 双击安装；二是通过 Homebrew 执行：
brew install python@3.10
验证时注意用
python3，不要用python——macOS 自带的python可能指向系统老版本：python3 --version
第二步：装 Git
最省事的方式是在终端执行：
xcode-select --install
系统会弹出对话框，点"安装"等它跑完。如果磁盘空间紧张（Xcode 命令行工具约占 17G），改用：
brew install git
只占几百兆。
第三步：装 CLI
curl -fsSL raw.githubusercontent.com/jieshuo-ai/… | python3
GitHub 访问受限时同样用镜像前缀手动 clone：
git clone ghfast.top/https://git…
cd narrator-ai-cli
pip3 install -e .
验证安装：
narrator-ai-cli --version
如果提示
command not found，先执行：source ~/.zshrc
刷新 shell 环境变量再试，通常就通了。
五、API Key 配置与鉴权：narrator-ai-cli 接入 AI 解说大师开放接口
CLI 装完之后还不知道你的账户信息。你需要先拿到一把 APP Key，按照github里的appkey获取方式，发送邮件获取key。
拿到之后在终端输入：
narrator-ai-cli config set app_key 你的API_Key
这条命令会把 Key 写入本地配置文件（默认在用户目录下的 .narrator-ai-cli 隐藏目录）。验证是否成功：
narrator-ai-cli user balance
看到账户余额返回，说明链路打通，可以开始用了。
配置文件完整字段参考：
~/.narrator-ai-cli/config.toml
app_key = "your_api_key_here"
default_platform = "抖音"
default_dubbing = "male"
default_bgm = "轻快节奏"
output_dir = "~/Videos/output"
default_platform 会影响文案生成的节奏和用词风格——发抖音的解说需要前三秒出钩子、语速偏快；发 B 站的可以更慢、更注重信息密度。这不是噱头，是后端模型真实的参数级控制。
如果你在团队里用，还有一套子 Key 体系值得了解：主账号可以创建多个子 Key、给每把子 Key 单独配置额度。MCN 团队里三个账号运营各用一把子 Key，用完互不干扰，主账号统一结算。
六、三种调用模式实战：一次性出片、分步接口与 Agent Skill 驱动
模式一：一条命令出片
最快的路径。对应后端的"通用爆款解说（电影）"一次性调用：
narrator-ai-cli commentary create-movie \
--movie-file ~/Videos/feichi.mp4 \
--platform "抖音" \
--dubbing male \
--bgm "轻快节奏" \
--task-count 1 \
--output ~/Videos/feichi_解说.mp4
命令回车之后，CLI 会先做本地预处理（字幕提取、关键帧抽取），然后在正式扣费之前显示一次点数消耗预估：
预估消耗：爆款学习点数：0.00
文案生成点数：140.00
视频合成点数：165.55
总计：305.55 点
当前余额：XXXX.XX 点
是否继续？(y/N)
这组数字是后端接口真实返回的，不是估算。你可以在任务启动之前精确知道要花多少，回复 y 确认之后才开始扣费。
--task-count 参数值得单独说一下。传 3 的话，后端会用同一组素材生成 3 个不同变体，方便你在几个候选里挑一个发布。做 A/B 测试或者账号矩阵的人几乎必用这个参数。
任务跑完后 CLI 拉回生成好的文案与配音，在本地完成最终合成，成片路径直接打印出来。
模式二：分步接口（可介入中间环节）
一次性调用的问题是你没法干预文案。分步接口把整条流水线拆成独立的几步，每步都有独立任务号和中间产物，你可以在任意一步暂停、审阅、修改，再继续往下走。
Step 1：爆款风格学习
找一段你想模仿风格的参考视频（30 秒到几分钟都行），让 CLI 从中学习它的句式节奏和钩子结构：
narrator-ai-cli commentary learn \
--reference-file ~/Videos/reference_clip.mp4 \
--narrator-type 电影 \
--model-version advanced
返回一个 learning_model_id，形如 narrator-20250929163803-MSBmuw。这一步本身不消耗点数，相当于"试学免费"，你可以先拿参考素材学一下看适不适合这个风格，适合再往下跑。
Step 2：生成解说文案
narrator-ai-cli commentary generate \
--movie-file ~/Videos/feichi.mp4 \
--learning-model-id narrator-20250929163803-MSBmuw \
--platform "抖音" \
--task-count 1
CLI 轮询后端任务状态，完成后把生成好的文案稿输出到终端或本地文件。
Step 3：人工审阅（这一步是手动的）
这是分步调用相对一次性调用最大的优势所在。你可以在这里读文案、改措辞、调节奏，甚至完全重写某几段，满意之后再往下走。
Step 4：合成最终视频
narrator-ai-cli commentary compose \
--task-id 6daeda059326491d996cac6396e8a4dc \
--output ~/Videos/feichi_解说.mp4
CLI 拿着审阅后的文案调配音合成，再用本地 FFmpeg 把原片画面、配音、BGM、字幕叠在一起，输出成片。
模式三：Agent 对话驱动（Skill 模式）
如果你已经在用小龙虾 OpenClaw、Windsurf、QClaw 或者 WorkBuddy，可以把 narrator-ai-cli-skill 仓库里的 SKILL.md 装进去，之后直接用自然语言驱动整条流水线。
加载方式以小龙虾为例：
mkdir -p ~/.openclaw/skills/narrator-ai-cli
cp SKILL.md ~/.openclaw/skills/narrator-ai-cli/SKILL.md
Windsurf 把 SKILL.md 放到项目的 .skills/narrator-ai-cli/ 目录下，IDE 启动时自动读取。QClaw 和 WorkBuddy 在技能管理界面直接上传文件即可。
加载完成后，在对话框里说：
帮我把 ~/Videos/feichi.mp4 做成爆笑喜剧风格的电影解说，输出到同目录。
Agent 接到指令后会自动完成：读取本地视频元信息 → 字幕提取与关键帧抽取 → 筛选爆笑喜剧风格学习模型 → 选配音角色和 BGM → 向你确认点数消耗 → 文案生成与配音合成 → 本地 FFmpeg 最终合成 → 输出成片。
你唯一需要做的，是在它问"本次消耗 X 点数，是否继续"时回复一个"确认"。
相关链接
- CLI 仓库：github.com/jieshuo-ai/…
- Skill 仓库：github.com/jieshuo-ai/…
七、常见报错排查：command not found、401、无声音等问题解决方案
按照实际使用中出现频率从高到低，把常见问题逐条说清楚。
narrator-ai-cli: command not found
这是安装后最常见的第一个问题，原因是 shell 的环境变量还没刷新，新装的命令还没被系统识别到。macOS 用户执行 source ~/.zshrc，Windows 用户关掉当前终端窗口重开一个新的，再试一次基本就解决了。如果还不行，检查 pip 的安装路径是否在系统 PATH 里。
Windows 上 python: command not found
安装 Python 时首屏没有勾选 Add python.exe to PATH。解决方法是重新运行 Python 安装包，选"Modify"，在 Optional Features 页面确认勾选了 PATH 选项，或者直接卸载重装，这次记得勾。
- 安装命令执行后 30 秒内屏幕没有任何反应
国内访问 GitHub 受限导致的。按 Ctrl+C 终止，改用镜像前缀手动 clone：
git clone ghfast.top/https://git…
cd narrator-ai-cli
pip install -e .
如果 ghfast.top 也不通，把前缀换成 https://mirror.ghproxy.com/ 再试。
narrator-ai-cli user balance 返回 401
API Key 没有配置，或者配置时写错了。重新执行一次：
narrator-ai-cli config set app_key 你的API_Key
注意 Key 前后不要有多余的空格，复制粘贴时有时会带上。
- 合成出来的视频没有声音
本地没有安装 FFmpeg，或者 FFmpeg 没有加入系统 PATH。macOS 执行 brew install ffmpeg；Windows 去 ffmpeg.org 下载，解压后把 bin 目录路径加进系统环境变量，关终端重开验证 ffmpeg -version。
- 点数不足提示
执行 narrator-ai-cli user balance 查当前余额，余额不足时联系商务充值。如果余额显示正常但仍然报点数不足，检查是否在用子 Key，子 Key 有单独的额度上限，可能是子 Key 额度耗尽而主账号余额还有。
八、narrator-ai-cli 能力全景：语音克隆、Remotion 渲染与批量生产实践
narrator-ai-cli 目前覆盖的能力，远不止"生成一条电影解说"这一件事。完整的后端接口图谱包括：资源检索与项目管理、爆款解说一次性调用与分步接口、多模态视频理解、TTS 语音合成（63 个角色、11 种语言）、语音克隆、字幕擦除与压制、Remotion 模板渲染、智能封面生成。这些能力都挂在 CLI 子命令下，narrator-ai-cli --help 是最新可用命令的真实来源。
如果你已经跑通了第一条电影解说，下面几件事值得接着试：
试试语音克隆加停顿语法的组合。 录一段你欣赏的博主的 30 秒清晰音频，通过 CLI 的语音克隆子命令完成克隆。然后在解说文案的关键节奏点插入 <#0.5#> 停顿语法，用克隆模型做 TTS 合成。效果跟"直接让大模型念出来"完全是两个层次。
试试两个不同风格的学习模型对比。 找两段风格完全不同的爆款解说短视频（比如一段"悬疑沉稳"、一段"爆笑吐槽"），分别创建两个 learning_model，用同一部电影分别生成两份文案对比。你会直观看到"风格模板"这个参数在后端到底做了多少事。
试试 --task-count 3 的 A/B 测试用法。 同一部电影一次生成 3 个变体，发到不同账号或者同账号不同时段，看哪个版本的完播率和互动数据更好，下次生产就往那个方向靠。
试试把 CLI 嵌进 bash 脚本做批量生产。 如果你手里有一批待解说的素材，写一个简单的循环脚本，让 CLI 跑一晚上，早上起来看结果。本地优先架构的好处在这里体现得最明显——网络抖动最多影响当次 API 调用，重试一下就过，不会因为大文件传输中断前功尽弃。
#电影解说#github开源#skill#cli#多模态视频理解#tts语音合成#语音克隆#视频剪辑#AI解说大师
