*本文适合谁： *正在用 QClaw、WorkBuddy、小龙虾 OpenClaw 等 AI Agent 工具的开发者和内容创作者；想把电影解说能力接进自动化工作流、不想每次手动操作的运营团队；对"Agent + Skill"架构感兴趣、想找一个真实可跑的接入案例的技术用户。
一、WebUI 工具为什么进不了 Agent 工作流
Agent 调用一个外部能力，需要的是可编程接口：一条命令、一个 API、或者一份告诉它"什么时候调什么、参数怎么传"的 Skill 文件。
streamlit WebUI 的交互单元是鼠标点击，不是命令调用。Agent 没有鼠标，它没有办法点开浏览器、找到上传按钮、把文件拖进去。Docker 容器里跑的 Web 服务理论上可以通过 API 接入，但没有现成的 Skill 编排文件，Agent 不知道面对"帮我做一条电影解说"这句话，应该按什么顺序调哪些接口、中间结果怎么处理、出错了怎么重试。
这就是为什么 NarratoAI、MoneyPrinterTurbo 这类 WebUI 工具，虽然功能完整，但始终停留在"人工操作"的使用模式里，无法作为能力模块挂到任何 Agent 上。
narrator-ai-cli 的架构是反过来设计的。CLI 是执行层，负责接收命令、处理文件、调用后端接口；SKILL.md 是编排层，用自然语言加结构化指令写清楚每个子命令的使用逻辑。两者组合，就是一个 Agent 可以直接挂载的解说能力模块。
把电影解说能力变成 Agent 的一部分，不需要改任何代码，只需要装一个 CLI、加载一份 Skill 文件。
二、narrator-ai-cli-skill 架构解析：CLI 与 Skill 各自做什么
在动手配置之前，先把两个仓库的分工搞清楚，后面的步骤会更容易理解。
narrator-ai-cli（执行层）
Python 命令行工具，负责本地文件处理和后端通信。具体来说：从本地视频里提取字幕、抽取关键帧、把轻量载荷发给 AI解说大师开放接口（docs.jieshuo.cn）、拿回生成好的文案和配音、最后用本地 FFmpeg 合成成片。Agent 通过它把每一步操作转化成实际执行。
narrator-ai-cli-skill（编排层）
一份 SKILL.md 文件。它用自然语言加结构化指令写清楚：每个子命令什么时候用、参数怎么传、前置依赖是什么、拿到返回结果之后怎么接着走、遇到点数不足或文件找不到这类错误怎么处理。Agent 读懂它之后，就知道面对用户的一句话，应该按什么顺序调哪些命令。
两者的关系可以这样理解：CLI 是工具箱，Skill 是说明书。Agent 拿着说明书操作工具箱，用户只需要说一句话。
本地优先架构值得单独说一下：原片始终待在你的本地硬盘上，只有字幕文本（几十KB的SRT）、关键帧序列（几 MB的JPEG）、生成好的配音（几MB的MP3）这些轻量载荷跟云端往返。一部 90 分钟 1080P 的电影大约 2 到 4 GB，全程不上传，4G 信号都能稳定跑完整条流程。
三、前置准备：安装 CLI 并配置 API Key
仓库地址：
- CLI 仓库：github.com/jieshuo-ai/…
- Skill 仓库：github.com/jieshuo-ai/…
Skill 接入的前提是 CLI 已经装好并且 API Key 已经配置。
安装 CLI
pip install narrator-ai-cli
配置 APPKey
narrator-ai-cli config set app_key 你的APP_Key
验证链路
narrator-ai-cli user balance
看到账户余额返回，说明 CLI 和后端链路都通了，可以进入 Agent 配置步骤。
四、小龙虾 OpenClaw 接入：Skill 加载与调用演示
Step 1：克隆 Skill 仓库
git clone github.com/jieshuo-ai/…
Step 2：把 SKILL.md 放到小龙虾的 Skill 目录
mkdir -p ~/.openclaw/skills/narrator-ai-cli
cp narrator-ai-cli-skill/SKILL.md ~/.openclaw/skills/narrator-ai-cli/SKILL.md
Step 3：重启小龙虾，验证加载
在对话框输入 /skills，看到列表里出现 narrator-ai-cli 即加载成功。
调用效果演示：
💬 用户： 帮我做一个飞驰人生的电影解说，爆笑喜剧风格，输出到同目录
🦞 小龙虾：
正在读取视频元信息...
提取字幕中（本地处理，原片不上传）...
匹配爆笑喜剧风格学习模型...
预估消耗：文案生成：140.00 点
视频合成：165.55 点
合计：305.55 点
当前余额：XXXX.XX 点
是否继续？
💬 用户： 确认
🦞 小龙虾：
文案生成中...
配音合成中...
本地 FFmpeg 合成视频...
✅ 成片已输出：飞驰人生-解说.mp4
整个过程用户只说了两句话，Agent 自动完成了字幕提取、风格匹配、文案生成、配音合成、本地视频合成的全流程。
五、QClaw 接入：通过技能管理界面上传 Skill
QClaw 不需要命令行操作，通过界面上传 SKILL.md 文件即可。
配置步骤：
- 打开 QClaw，进入 设置 → 技能管理
- 点击 上传技能文件，选择本地的
SKILL.md（从上一步克隆的仓库里找） - 上传完成后在对话框输入
/reload skills刷新技能列表 - 看到
narrator-ai-cli出现在技能列表里即配置完成
调用效果演示：
💬 用户： 用悬疑风格给《消失的她》做一条3分钟解说，发抖音用
🦞 QClaw：
正在分析素材...
选择悬疑沉稳风格学习模型...
平台参数：抖音（前3秒钩子优化，语速偏快）
预估消耗：280.00 点，是否继续？
💬 用户： 继续
🦞 QClaw：
文案生成完成，时长预估：3分08秒
配音合成中...
✅ 成片已输出，实际时长：3分12秒
六、WorkBuddy 接入：从 GitHub 直接拉取 Skill
WorkBuddy 支持直接输入 GitHub 仓库地址加载 Skill，不需要手动下载文件。
配置步骤：
- 打开 WorkBuddy，进入 工作流 → 添加技能
- 选择 从仓库导入，输入仓库地址：
- WorkBuddy 自动读取仓库根目录的 SKILL.md，加载完成后显示技能卡片
- 在对话框输入
/skills确认narrator-ai-cli已出现
调用效果演示（批量场景）：
💬 用户： 批量处理 ~/Videos/ 目录下所有 mp4，每个都做一条抖音风格解说
🦞 WorkBuddy：
检测到 5 个视频文件：
feichi.mp4 / nezha.mp4 / wandering.mp4 / ...
预估总消耗：1527.75 点，是否继续？
💬 用户： 确认
🦞 WorkBuddy：
[1/5] feichi.mp4 → ✅ 完成
[2/5] nezha.mp4 → ✅ 完成
[3/5] wandering.mp4 → ✅ 完成
[4/5] ...
[5/5] ...
✅ 全部完成，成片已输出到 ~/Videos/output/
批量场景是 WorkBuddy 接入最典型的使用方式。账号矩阵运营团队可以把一批素材丢进去，WorkBuddy 按顺序跑完，早上起来看结果。
七、多 Agent 并行实测：同一部电影，三个风格同时出片
这是单独用任何一款 WebUI 工具都做不到的场景。
场景设定： 同一部电影，三个 Agent 同时接到指令，分别生成不同风格的解说版本，用于同一账号的 A/B 测试或三个矩阵账号的差异化内容。
为什么能并行： 每个 Agent 调用的是独立的 CLI 进程，后端任务互相隔离，账号配额独立计算，三个任务同时提交到云端并行处理。
实测执行方式：
三个终端窗口（或三个 Agent 对话框）同时发出指令：
终端1 / 小龙虾
narrator-ai-cli commentary create-movie \
--movie-file ~/Videos/feichi.mp4 \
--platform "抖音" --dubbing male \
--learning-model-id narrator-comedy-001 \
--output ~/Videos/feichi_喜剧版.mp4
终端2 / QClaw
narrator-ai-cli commentary create-movie \
--movie-file ~/Videos/feichi.mp4 \
--platform "抖音" --dubbing female \
--learning-model-id narrator-suspense-001 \
--output ~/Videos/feichi_悬疑版.mp4
终端3 / WorkBuddy
narrator-ai-cli commentary create-movie \
--movie-file ~/Videos/feichi.mp4 \
--platform "抖音" --dubbing male \
--learning-model-id narrator-emotion-001 \
--output ~/Videos/feichi_情感版.mp4
三个任务同时提交，总耗时约等于单个任务耗时，不是三倍叠加。云端并行处理，本地只等最后的合成步骤。
对做账号矩阵的团队来说，这个场景的意义是：一次操作，三个账号的差异化内容同时产出，内容不重复，风格各自独立。
八、Agent 接入常见问题排查
- Skill 加载后 Agent 没有任何反应
检查 SKILL.md 是否放在了正确的目录路径下。小龙虾的路径是 ~/.openclaw/skills/narrator-ai-cli/SKILL.md，路径层级不对 Agent 读不到文件。放好之后完全退出 Agent 重启，不是刷新，是完全退出重开。
- Agent 执行到一半停住不动了
大概率是点数不足。Agent 在消耗预估确认之后才开始扣费，如果中途停住，执行 narrator-ai-cli user balance 查一下余额
- 多个 Agent 同时调用会不会互相冲突
不会。每个 CLI 进程独立运行，后端任务通过任务 ID 隔离，三个 Agent 同时跑不会互相干扰，也不会重复扣费。
- 不同 Agent 平台需要分别维护不同版本的 Skill 文件吗
不需要。同一份 SKILL.md 文件，所有支持 Markdown Skill 格式的 Agent 均可直接使用。小龙虾、QClaw、WorkBuddy 用的是同一个文件，仓库更新后各平台重新加载一次即可同步。
- Agent 说"找不到 narrator-ai-cli 命令"
CLI 没有安装，或者安装后 PATH 没有刷新。执行 narrator-ai-cli --version 验证。
