项目概览
Narrator AI CLI Skill 是一个 AI Agent 技能描述文件，教会 AI Agent（如 OpenClaw、Claude Code、Cursor、Windsurf 等）如何调用 narrator-ai-cli 命令行工具，完成电影/短剧解说视频的全自动化生产。它解决的核心问题是让不懂视频剪辑、命令行和 API 调用的普通用户，通过自然语言对话就能完成从搜片、选模板、选 BGM、选配音、生成文案到合成视频的完整流水线。项目采用 SKILL.md 主文件加 references/ 子目录的结构化行为规范，将 CLI 的调用顺序、参数依赖、错误处理和决策逻辑编码为机器可读的说明书，并定义了 Fast Path（原创文案）和 Standard Path（二创文案）两条工作流路径。内置约 100 部电影素材、146 首 BGM、63 个配音音色（11 种语言）和 90+ 解说模板，支持多语种出海场景。项目采用积分计费模式，MIT 开源协议，版本 v1.0.5，已在 9 个 AI Agent 平台验证。
解决什么问题
Narrator AI CLI Skill 解决的核心问题是让不懂视频剪辑、不懂命令行、不懂 API 调用的普通用户，通过自然语言对话就完成专业级电影解说视频制作。在传统方案中，制作一个电影解说视频需要经过内容准备（下载电影素材、编写解说文案、找配音员录制旁白）和技术处理（剪辑软件对齐画面与旁白、添加 BGM 和音效、导出上传）的六步手工链路，存在工具碎片化、爆款风格难模仿、多语种配音壁垒、素材管理混乱、AI Agent 无从下手、API 调用复杂度高等六大痛点。项目出现的背景是 AI Agent 生态爆发，但 Agent 缺的不是"手"（CLI/API），而是"脑"（知道怎么用）——narrator-ai-cli 提供了完整的命令行能力，但 SKILL.md 解决的是"怎么做"的问题，把 API 的调用顺序、参数依赖、错误处理、决策逻辑全部写成结构化的行为规范。
工作方式
项目采用三层架构：用户自然语言输入 → AI Agent（读取 SKILL.md）→ CLI 命令执行 → Narrator AI API → 视频生成。CLI 层是基于 typer 框架的 Python 命令行工具，封装了 Narrator AI 后端 API 的全部能力，包括素材管理（material）、背景音乐（bgm）、配音管理（dubbing）、解说模板（narration-styles）、任务创建与查询（task create/query）、文件管理（file upload/transfer）和账户管理（user balance）。Skill 层是 SKILL.md 主文件加 references/ 子目录（resources.md、workflows.md、operations.md、magic-video.md），遵循五个核心原则：显式决策链（Agent 不能跳步、不能合并决策）、语言链一致性（配音语言=文案语言=magic-video 文本语言）、数据流精确映射（每个任务步骤的输出字段到下一步输入参数的映射关系被显式定义）、5 秒轮询+绝对上限（连续 12 次解析失败或总计 720 次迭代自动退出）、前置确认+成本预估（高成本操作必须展示完整请求体并等待用户确认）。API 层使用 app_key 签名鉴权，积分计费。
核心能力
- 全流程自动化：从搜片到成片，一句话触发，无需手动拼接工具
- 跨平台兼容：9 个 AI Agent 平台已验证，一份文件多处使用
- 内置丰富资源：约 100 部电影、146 首 BGM、63 个配音音色、90+ 解说模板
- 多语种支持：11 种语言配音，支持出海场景
- 防错设计细致：18 个错误码全覆盖、路径不对称性多次强调、语言链一致性检查
- 成本可控：task budget 预估 + task verify 校验，避免盲目消耗积分
- 自然语言入口：用户不需要懂 CLI 或 API，对话即可
- MIT 开源协议：Skill 文件完全开源，可自由修改和分发
- 支持自定义扩展：可通过 popular-learning 学习自定义风格、voice-clone 克隆声音、TTS 独立使用
使用前需要了解
- AI 整理 · 本地测试，未经人工复核；依据历史报告节选，不代表当前产品状态。
- 项目不支持非解说类视频，只能做电影/短剧解说，不能做 Vlog、教程、宣传片等。视觉模板 magic-video 是可选附加功能，不能替代专业视频编辑软件。项目依赖后端 API 可用性，API 宕机或维护期间无法使用。输出格式固定为 MP4 视频 + TXT 文案，不支持自定义分辨率、码率等参数。积分计费模式下，大量生产需要持续充值，成本可能高于手工方案。素材库约 100 部电影，覆盖面有限，冷门内容需自备素材。Skill 文件复杂度较高，SKILL.md 加 4 个 references 文件，对新 Agent 平台的适配需要仔细处理目录结构。search-movie 依赖 Gradio 后端，搜索电影可能耗时 60+ 秒，且结果缓存 24 小时。需要精细剪辑控制（精确到帧的剪辑、特效、转场）的场景、需要原创 AI 视频（非解说类）的场景、素材库外的超冷门内容且无 SRT 的场景、对成本极度敏感的个人用户，均不建议使用本项目。
