用Claude Code和FFmpeg实现一句话AI视频编辑-平芜编程栈

为什么“一句话剪视频”值得被认真对待

最近海外开发圈有一个项目标题很有吸引力：We built a tool that lets Claude edit videos in one prompt。翻译过来就是“我们做了一个工具，让 Claude 只靠一句提示词就能编辑视频”。在很多人的认知里，AI 写写文案、改改代码已经见怪不怪了，但视频剪辑一直是重人工、重流程的领域——素材筛选、片段剪切、字幕生成、转场拼接、导出压缩，每一步都可能要打开好几个专业软件。现在突然有人说“一句话全包”，第一反应是怀疑：这真的能做到吗？还是只是 Demo 阶段的花架子？

我的判断是：这句话不应该从字面理解成“Claude 学会了剪视频”，而应该理解成“我们把视频编辑任务拆成了 AI 可以规划、工具可以执行的自动化流程”。换句话说，Claude 不直接碰像素，它负责理解需求、拆分步骤、生成命令和脚本，最终由 FFmpeg 这类底层工具真正完成任务。这个思路并不是什么玄学，它和我们这几年一直在聊的 Agent、Prompt Engineering、工具调用（Function Calling）是一脉相承的。

这篇文章不会只停留在对这个项目本身的复述上。我会把它放到一个更大的背景下：如果你想在本地搭一套类似的“AI 视频编辑工作流”，应该怎么设计 Prompt，怎么准备环境，怎么拆任务，怎么让 Claude 或者其他大模型模型调用具体工具，以及真正容易踩坑的地方在哪里。读完以后，你不仅能理解这个项目做了什么，还能自己动手实现一个最小可用版本。

无论你是刚接触 AI 编程的开发者，还是已经用过 Claude Code、GitHub Copilot 这类工具的老手，这篇文章都会有参考价值。我们先把概念讲清楚，再进入具体的代码和配置。

1. 这篇文章真正要解决的问题

刚开始看到“one prompt”这个说法时，很多人的直觉是：是不是只要写“帮我把这段视频剪成 30 秒，加上字幕，换背景音乐”，Claude 就会自动完成全部工作？如果是这个期待，那么大概率会失望。因为当前大模型的能力边界决定了它擅长的是“理解意图”和“生成中间产物”，而不是直接操作视频编码、解码、渲染这类底层计算。

所以这篇文章要解决的核心问题有三个。

第一个问题是“理解边界”。你需要搞清楚 Claude 在视频编辑流程中到底承担什么角色，哪些环节是它直接出力的，哪些环节是它通过调用外部工具完成的。不把这条边界搞清楚，你会觉得这个工具很神奇；搞清楚了，你会觉得这个方案其实非常合理，而且可以举一反三。

第二个问题是“流程设计”。既然 Claude 不直接处理视频，那一个真正的“一句话视频编辑”任务，需要被拆成哪些步骤？素材列表怎么给、需求描述怎么解析、命令怎么生成、错误怎么处理、结果怎么验证？这些都是工程问题，不是单纯靠“提示词写得好”就能解决的。

第三个问题是“落地实现”。从环境准备到 Prompt 模板，从运行命令到结果验证，我希望给你一套可以照着操作的最小示例。哪怕你暂时不会马上做一个完整产品，至少可以把核心链路跑通，理解其中的设计思路。

这篇文章适合谁？适合三类读者：

对 AI Agent 和 Prompt Engineering 感兴趣，想找一个真实场景练手的开发者。
经常和视频素材打交道，希望用自动化减少重复劳动的从业者。
在思考“大模型 + 工具调用”怎么落地到业务系统里的架构师或技术负责人。

如果你只是单纯想找一个现成的软件“傻瓜式剪视频”，这篇文章可能不那么适合你。我们侧重的不是点鼠标，而是理解原理和写代码。

2. Prompt Engineering、Claude Code 与 AI 视频编辑的关系

在进入实操之前，先把几个关键概念讲清楚。这些概念在后续内容里会反复出现，而且它们之间的边界很容易被混淆。

2.1 什么是 Prompt Engineering

Prompt Engineering 中文常翻译为“提示词工程”。它做的事情是：通过设计输入给大模型的文本，让模型更稳定、更准确地输出你想要的结果。你可能已经发现，同一件事用不同问法，得到的答案质量可能差别很大。比如直接问“怎么剪视频”，模型可能给你一堆泛泛的建议；但如果你说“你是一名视频剪辑助手，请按步骤分析这段视频的剪辑需求，并生成 FFmpeg 命令”，它输出的内容会更具体、更可操作。

Prompt Engineering 不只是“把问题写清楚”，它还包括约束输出格式、提供上下文示例、拆分复杂任务、设计多轮对话逻辑等。在 AI 视频编辑场景里，Prompt 的质量直接影响工作流能否跑通。如果需求描述太模糊，模型可能生成错误的命令；如果输出格式不固定，后续解析程序就会出问题。

2.2 Claude Code 是什么

Claude Code 是 Anthropic 推出的编程智能体工具。简单说，它把 Claude 和终端、代码仓库、开发工具连接起来，让 Claude 能读代码、改文件、运行命令、检查结果。它不是传统意义上的“对话机器人”，而是更接近一个“住在开发环境里的 AI 工程师助理”。

这和视频编辑有什么关系？关系在于能力的复用。Claude Code 的核心能力是“让大模型通过工具调用完成具体任务”。如果你能用 Claude Code 完成代码修改和命令执行，那同样的机制也可以用来生成 FFmpeg 命令、运行视频处理脚本、检查输出文件。换句话说，Claude Code 是一个很好的基础设施，我们的视频编辑工具可以搭建在这种基础设施之上。

搜索热词里频繁出现“claude code 安装”“claude code 使用教程”“claude code + cc switch + ollama”，说明确实有大量开发者在尝试用 Claude Code 构建端到端的自动化流程。这正是这篇文章要展开的方向。

2.3 工具调用：Claude 与 FFmpeg 的桥梁

什么是工具调用？你可以把它理解为：大模型在生成文本的同时，还可以输出一个结构化的“调用指令”，比如“调用名为 execute_command 的函数，参数是 ffmpeg -i input.mp4 ...”。然后由外部程序截获这个指令，真正去执行命令，再把执行结果反馈给模型。这样，大模型不需要自己做数学运算、文件读写或视频编码，它只需要“规划”和“判断”，剩下的脏活累活交给专门工具。

在视频编辑场景里，FFmpeg 就是那个最重要的底层工具。FFmpeg 是一个跨平台的音视频处理库和命令行工具，支持视频剪切、合并、转码、添加字幕、调整音量、抽取帧等海量操作。它是一个极其强大但学习曲线很陡的工具。Claude 的一大优势就是记住了大量 FFmpeg 的参数和用法，能够根据自然语言需求生成对应的命令。

于是整个链路就清晰了：

用户在 Prompt 里提出视频编辑需求。
Claude 理解需求，把它拆成多个子任务。
Claude 为每个子任务生成 FFmpeg 命令或调用脚本。
外部执行器运行这些命令，操作真实视频文件。
执行结果返回给 Claude，Claude 判断是否继续调整或结束。

这个思路本质上是“大模型负责脑力，工具负责体力”。

3. 环境准备与前置条件

考虑到读者中有人可能在 Windows 上开发，有人在 macOS 或 Linux 上开发，下面的环境准备部分会尽量给通用方案，同时指出各平台的差异。版本号这类信息变化比较快，所以不会写死某个具体版本，而是给出版本选择和验证思路。

3.1 基础环境：Python 与 Node.js

这个视频编辑工作流的核心控制逻辑可以写在 Python 或 Node.js 里，哪个熟悉用哪个。Python 的优势是生态成熟，写脚本方便，OpenCV、json、subprocess 等库直接可用；Node.js 的优势是和前端工具链天然衔接，如果你后面想做 Web 界面，切换成本会低很多。

无论选哪种，先确认环境里有可用的解释器或运行时：

# Python python3 --version # Node.js node --version npm --version

如果提示找不到命令，需要先到官网下载对应安装包完成安装。安装完成之后再次验证版本信息，确认能正常运行。

3.2 安装 FFmpeg

FFmpeg 是这个流程里的关键执行工具，必须提前安装。

Windows 用户可以下载官方编译版本，把 bin 目录添加到系统 PATH 中；macOS 用户如果有 Homebrew，可以直接通过包管理器安装；Linux 用户可以用系统自带的包管理器安装。

安装完成之后，在终端执行：

ffmpeg -version

如果能看到版本信息，说明 FFmpeg 已经可用。这是整个流程里最容易出问题的一步，很多人到后面生成命令后才发现 ffmpeg 不存在，白白浪费调试时间。

3.3 Claude Code 安装与配置

从搜索热词可以看出，“claude code 安装”是很多人关注的问题。官方推荐的方式是通过 npm 全局安装：

npm install -g @anthropic-ai/claude-code

安装完成之后需要确认命令可用：

claude --version

正常情况下，第一次运行 Claude Code 时会引导你完成身份验证和 API 密钥配置。具体认证流程可能随官方产品迭代而调整，以官方文档为准。如果你在 Windows 环境遇到“claude 无法识别”的提示，大概率是 PATH 没有配置好，可以先执行npm config get prefix查看全局安装路径，再把它加入 PATH。

3.4 准备测试视频素材

不要用太复杂的视频做第一次测试。建议准备一个 10 秒到 30 秒的短视频，内容不要太花哨，方便验证剪切和转码结果。可以用手机随便拍一段，或者下载开源视频素材网站的测试短片。

把视频文件放在一个独立目录里，比如~/video-agent-project/input/，后续所有脚本都基于这个目录运行。这样能避免路径混乱，也方便清理中间产物。

到这里，环境准备的核心部分已经完成。接下来进入重头戏：怎么设计一个“一句话剪视频”的工作流。

4. 核心流程拆解：从一句话到完整执行

如果你理解了“大模型负责规划、工具负责执行”这个原则，那设计流程的思路就会很清晰。下面是一个典型的实现结构。

4.1 整体架构

整个系统由三部分组成：用户输入层、编排层、执行层。

用户输入层就是一个对话界面，用户提交自然语言需求，比如“把 input.mp4 的前 5 秒剪出来，加上一段淡入字幕，导出为 mp4”。编排层负责接收需求，通过 Prompt 模板把它转化为结构化的任务列表，然后在合适时机调用大模型生成具体命令。执行层负责真正运行这些命令，并把结果返回给编排层。

这三层不一定要做成独立服务，在当前这个阶段，用一个大模型 API 调用加一个子进程执行脚本就足够了。关键是代码结构要先想清楚，方便后续扩展。

4.2 第一步：需求解析

需求解析不是让大模型直接“听懂”自然语言就结束了，而是要让大模型输出一个结构化的 JSON，把用户需求拆成字段清晰的子任务。

比如输入是“把前 5 秒剪出来，加上字幕‘Hello’”，理想的输出可能是：

{ "tasks": [ {"action": "cut", "params": {"start": "00:00:00", "duration": "5"}}, {"action": "subtitle", "params": {"text": "Hello"}} ] }

这个步骤最大的好处是：后面的执行逻辑可以只解析 JSON，不用反复处理自由文本。大模型和程序之间的接口是结构化数据，出错概率会大大降低。

4.3 第二步：命令生成

得到结构化任务列表之后，还需要把它们转换成真正可执行的命令。这一步依然可以让大模型来干，但 Prompt 要设计得更仔细：要告诉模型视频文件的真实路径、可用的工具是什么、输出文件命名规则是什么、遇到不支持的操作该怎么办。

比如“cut”任务可能对应：

ffmpeg -i input/video.mp4 -ss 00:00:00 -t 5 -c copy output/cut.mp4

“subtitle”任务可能对应：

ffmpeg -i output/cut.mp4 -vf "drawtext=text='Hello':fontsize=24:fontcolor=white:x=(w-text_w)/2:y=h-th-50" -codec:a copy output/subtitle.mp4

命令生成的关键在于约束。如果不给模型足够的上下文和边界条件，它很容易生成一个“看起来对但实际跑不通”的命令。比如输入文件不存在、滤镜名称拼错、输出目录没创建，这些都是高频问题。

4.4 第三步：安全执行与反馈

这一步非常重要，却也最容易在教程里被忽略。用 subprocess 或类似机制执行命令时，必须要考虑安全问题、超时问题和错误处理问题。

建议的方案是：

使用一个白名单机制，只允许执行预先定义好的命令模板。
所有输出文件统一写入指定输出目录，避免命令覆盖系统文件。
设置超时时间，防止 ffmpeg 因为参数错误而无限期运行。
捕获 stdout 和 stderr，把日志返回给大模型，让它根据报错信息自动调整命令。

做到这几点，即使大模型生成了错误的命令，系统也不会对机器造成太大影响。

4.5 第四步：结果验证

命令执行完后，不能直接告诉用户“完成了”。要验证输出文件是否真实存在、文件大小是否合理、时长是否符合预期。最常见的坑是：ffmpeg 命令执行成功，退出码是 0，但输出文件是 0 字节，显然有问题。

一个好的做法是：让大模型看一眼执行日志和输出文件信息，自己判断结果是否合理。如果结果不对，它可以自动调整参数重新执行。这一步其实就是很多 Agent 产品“自动纠错”能力的来源。

5. 完整示例代码实现：让 Claude 通过 FFmpeg 编辑视频

下面我会给出一套可以直接运行的最小实现。这里不会做成完整商业产品，而是把核心链路跑通，让你理解每个环节是怎么连接起来的。

5.1 项目结构

建议按下面的目录结构组织代码：

video-agent-project/ ├── input/ │ └── demo.mp4 ├── output/ ├── prompt.py ├── executor.py └── main.py

5.2 定义 Prompt 模板

文件路径：prompt.py

SYSTEM_PROMPT = """ 你是一名视频编辑执行助手。你能使用 FFmpeg 命令完成视频剪切、转码、加字幕、调整音量等操作。 规则： 1. 用户会提供视频编辑需求和输入文件路径。 2. 你必须先输出 JSON 格式的任务列表，字段包括 action 和 params。 3. action 只允许以下取值：cut, concat, subtitle, volume, transcode。 4. 输出 JSON 后，再输出对应的 FFmpeg 命令，用 ```bash 代码块包裹。 5. 如果用户需求不明确，必须输出 error 字段说明原因。 输出格式示例： { "tasks": [{"action": "cut", "params": {"start": "00:00:00", "duration": "5"}}] } ```bash ffmpeg -i input/demo.mp4 -ss 00:00:00 -t 5 -c copy output/cut.mp4

"""

这个 Prompt 模板做了两件关键事：一是把模型输出约束为 JSON 加命令的组合，方便外部程序解析；二是明确 action 白名单，防止模型生成任意命令。实际项目里你可以根据需求不断迭代这个模板，比如增加“支持多个文件拼接”的能力。 ### 5.3 定义执行器 文件路径：`executor.py` ```python import subprocess import os # 只允许执行 ffmpeg 命令，且只能在项目目录内读写文件 ALLOWED_PREFIX = "ffmpeg" BASE_DIR = os.path.dirname(os.path.abspath(__file__)) INPUT_DIR = os.path.join(BASE_DIR, "input") OUTPUT_DIR = os.path.join(BASE_DIR, "output") def run_command(command: str, timeout: int = 120) -> dict: """执行单条 shell 命令并返回结果。""" # 安全限制：只允许以 ffmpeg 开头的命令 if not command.strip().startswith(ALLOWED_PREFIX): return { "success": False, "message": f"Command not allowed: {command}", "stdout": "", "stderr": "Security policy: only ffmpeg commands are allowed.", "returncode": -1, } os.makedirs(OUTPUT_DIR, exist_ok=True) try: result = subprocess.run( command, shell=True, capture_output=True, text=True, timeout=timeout, cwd=BASE_DIR, ) return { "success": result.returncode == 0, "message": "ok" if result.returncode == 0 else "error", "stdout": result.stdout[-2000:], "stderr": result.stderr[-2000:], "returncode": result.returncode, } except subprocess.TimeoutExpired: return { "success": False, "message": "timeout", "stdout": "", "stderr": f"Process timed out after {timeout} seconds.", "returncode": -1, }

这段代码的重点是安全边界设计。ALLOWED_PREFIX是一个最简单的白名单，只允许 ffmpeg 开头的命令。真实生产环境肯定不能这么简单，但作为最小示例已经能防止很多误操作。路径也被限制在项目目录内，避免了把系统文件覆盖掉的低级事故。

5.4 主逻辑：把 Prompt 和执行器连接起来

文件路径：main.py

import json import re import subprocess import sys from prompt import SYSTEM_PROMPT from executor import run_command, INPUT_DIR def ask_claude_parse_request(user_request: str) -> dict: """ 调用 Claude API，获取 JSON 任务列表。 这里的实现是伪代码，你需要填充为真实的 API 调用。 """ # 在真实项目中，你需要调用 Anthropic API 或 Claude Code SDK。 # 这里以注释代替，重点展示流程： # conversation = [{"role": "system", "content": SYSTEM_PROMPT}] # conversation.append({"role": "user", "content": user_request}) # response = anthropic_client.messages.create(...) # content = response.content[0].text # # 为了让你能本地跑通流程，这里先返回一个写死的 JSON 示例。 return { "tasks": [ {"action": "cut", "params": {"start": "00:00:00", "duration": "5"}} ] } def extract_command_from_response(content: str) -> str: """从模型输出中提取 bash 代码块。""" pattern = r"```bash\n(.*?)\n```" matches = re.findall(pattern, content, re.DOTALL) if not matches: return "" return matches[0].strip() def main(): if len(sys.argv) < 2: print("用法: python main.py \"<视频编辑需求>\"") sys.exit(1) user_request = sys.argv[1] tasks = ask_claude_parse_request(user_request) # 这一步在真实项目中，还要让 Claude 根据 tasks 生成具体命令。 # 这里为了演示，直接构造对应的 ffmpeg 命令。 for task in tasks["tasks"]: if task["action"] == "cut": params = task["params"] command = ( f"ffmpeg -i {INPUT_DIR}/demo.mp4 " f"-ss {params['start']} -t {params['duration']} " f"-c copy output/cut.mp4" ) print("执行命令:", command) result = run_command(command) print("执行结果:", json.dumps(result, ensure_ascii=False, indent=2)) else: print(f"暂不支持的任务类型: {task['action']}") if __name__ == "__main__": main()

这段代码里，ask_claude_parse_request目前是一个伪实现，直接返回写死的 JSON。原因是真实的 API 调用涉及密钥、权限、接口版本等细节，而这些内容变化较快。我在代码注释里写了接入思路，你只要把它替换成官方的 Claude API 调用即可。

为了让你能完整跑通流程，我们用写死 JSON 的方式演示后续链路：解析任务、构造命令、安全校验、执行、返回日志。等你理解了整条流水线，再补上真实 API 调用，就很容易了。

5.5 运行与验证

把测试视频放到input/目录下，命名为demo.mp4，然后在项目根目录执行：

python main.py "把视频前5秒剪出来"

预期输出类似：

执行命令: ffmpeg -i input/demo.mp4 -ss 00:00:00 -t 5 -c copy output/cut.mp4 执行结果: { "success": true, "message": "ok", "stdout": "...", "stderr": "...", "returncode": 0 }

执行完成后，检查output/cut.mp4是否存在，并用以下命令验证时长为 5 秒：

ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 output/cut.mp4

如果输出接近5.0，说明这条链路已经跑通了。你可以在output/目录里继续增加其他操作，比如拼接两个视频、添加字幕文字、调整音量等。把每一步都封装成独立的函数，然后在主流程里按任务列表依次调用。

6. 运行效果与验证方法

即使你已经成功执行了上面示例，仍然有必要把验证方法系统化。因为真实使用中，你会发现“命令执行成功”和“结果符合预期”是两件完全不同的事。

6.1 验证维度

第一个维度是命令退出码。returncode == 0只能说明 FFmpeg 没有因为语法错误中断退出，但输出文件可能没有生成，也可能只有几字节内容。

第二个维度是输出文件信息。用ffprobe检查时长、分辨率、编码格式、文件大小，看看是否符合预期。如果源视频是 1920x1080，输出结果突然变成 640x480，那说明命令里可能隐式改变了分辨率。

第三个维度是视觉验证。自动脚本无法完全代替人眼确认字幕位置是否正确、转场效果是否自然。所以在自动化流程里，可以增加“生成若干关键帧截图”的步骤，让用户或模型快速预览。

ffmpeg -i output/cut.mp4 -vf "fps=1/2" output/preview-%02d.jpg

这条命令会每 2 秒截取一帧，生成静态预览图。你可以把这些图片放到一个本地 HTML 文件里，方便人工查看。

6.2 如果失败，第一步看哪里

很多人遇到 FFmpeg 执行失败时，习惯先看退出码，然后疯狂搜索。但其实最直接的信息在stderr里。FFmpeg 执行失败时，通常会在标准错误输出里写明具体原因，比如“No such file or directory”“Invalid filter name”等。

建议在 executor 的返回结果里，把stderr完整打印出来。我们的示例代码已经截取了最后 2000 个字符，正常情况下足够定位问题。如果 2000 个字符不够，可以调大截取长度。

如果stderr显示的是权限问题，检查输出目录是否存在、是否有写权限。如果显示的是参数错误，大概率是 Prompt 生成的命令和当前 FFmpeg 版本不兼容。你可以先手动执行一次命令，把报错信息粘回给 Claude，让它根据报错调整写法。

6.3 自动纠错的循环

更成熟的工作流，应该是“执行-反馈-调整”的循环。当第一次命令执行失败时，不要急着把错误抛给用户，而是把 stderr 信息作为上下文，再次调用 Claude，要求它分析原因并输出修正后的命令。这里有一个度的问题：最多重试 2 到 3 次，超过之后必须停下来，防止无限循环消耗 tokens。

7. 常见问题与排查方法

基于搜索热词和实际使用经验，下面把高频问题列出来。

问题现象	可能原因	排查方式	解决方案
`claude`命令无法识别	npm 全局路径未加入 PATH	执行`npm config get prefix`查看全局目录	把 prefix 路径的 bin 目录加入 PATH
Claude Code 首次认证失败	API 密钥未配置或权限不足	查看 Claude Code 启动日志	按官方文档重新认证，检查密钥权限
FFmpeg 命令执行成功但输出文件为空	命令中`-ss`、`-t`位置错误	用`ffprobe`检查输出时长和编码	把`-ss`放在`-i`之前，`-t`放在`-i`之后
Prompt 生成的命令包含不支持的操作	Prompt 白名单不够完善	检查模型输出 JSON 是否存在未知 action	在 Prompt 中加强 action 枚举限制
执行超时	转码或剪切耗时过长	查看执行日志中的 time consumed	增加 timeout，或对长视频做分段处理
输出视频没有字幕	drawtext 滤镜依赖字体文件	查看 stderr 中的 fontconfig 报错	指定系统已存在的字体路径，比如`fontfile=/usr/share/fonts/...`
多任务连续执行时互相覆盖文件	输出文件命名冲突	检查每次命令的输出路径	使用时间戳或任务 ID 命名中间文件
模型生成的命令中路径有空格报错	shell 转义问题	查看命令字符串和 stderr 信息	统一用绝对路径，并对路径做引号包裹

这些问题的共同点是：光看现象很难猜到根因，必须结合日志和上下文逐步排查。所以在设计系统时，日志记录要比功能开发早一步进行。每一条命令执行前后都记录输入输出，能帮你快速回放整个流程。

8. 最佳实践与工程建议

当你理解了核心链路并决定在真实项目中使用时，下面的建议可以帮你避开不少坑。

8.1 Prompt 设计要做到“稳定优先”

不要期待大模型每次都能输出完美结果，而是要通过 Prompt 设计把这个风险降到最低。实际项目里推荐的做法是：

把 System Prompt 写长、写细，明确所有约束条件。
给模型提供输入文件信息，包括视频路径、分辨率、时长、编码格式。
提供一两个完整的输入输出示例，让模型照着格式输出。
明确要求“如果需求不明确，先提问，不要瞎猜”。

做到这几点之后，模型的输出稳定性会有明显提升。稳定的意思不是“每次结果都最好”，而是“每次格式都可以被程序正确解析”。

8.2 安全边界不是小事

很多人写 Demo 时喜欢把所有权限放开，比如直接用shell=True执行任意命令，觉得反正只是自己机器。但在真实项目里，这条边界必须非常严格。我见过一个内部工具因为执行了未经过滤的命令，把某个目录下的历史素材全部覆盖掉，教训很深刻。

至少要做三件事：

命令白名单：只允许ffmpeg、ffprobe等预定义命令。
路径隔离：输入输出都限制在项目目录，禁止使用绝对路径访问系统敏感目录。
超时限制：每条命令最多运行 N 秒，防止僵尸进程拖垮服务器。

如果未来接入更多工具，比如图像处理、音频分析，也要同样遵循“最小权限”原则。

8.3 日志和中间产物管理

视频处理的中间产物可能非常大。比如一个 10 分钟的视频，如果中间步骤生成了未压缩的音频或多张预览图，磁盘占用会很快膨胀。建议在流程结束之后，用脚本清理临时文件，只保留最终输出和必要日志。

日志本身建议按照时间戳组织：

logs/ ├── 2025-01-01-10-00-00/ │ ├── request.json │ ├── response.json │ ├── command.log │ └── output.mp4.meta.json

这样做的好处是，如果用户后来反馈“这个结果不是我想要的”，你可以完整回溯当时的输入、模型输出、命令和文件信息。

8.4 成本控制：别让自动纠错变成无底洞

大模型 API 是按 token 计费的，视频任务往往需要多轮交互，成本会比普通聊天任务高不少。你可以在编排层加一个“最大重试次数”和“最大 token 预算”控制。每次调用大模型前先估算命令是否合理，如果连续两次执行结果都不对，就交给人工处理。

另外一个技巧是：把常见的视频处理操作封装成预设模板，不要让模型每次从零生成命令。比如“截取前 N 秒”“拼接两个视频”“加文字水印”这类高频操作，直接匹配模板，只有模板覆盖不到的需求才调用大模型。这样既省钱又稳定。

8.5 异步化：长任务不要阻塞请求

视频转码不是秒级操作。一个 5 分钟的视频做完整转码，可能耗时几十秒甚至几分钟。如果你在 Web 应用里采用同步调用，用户会一直等待，体验很差。

更好的设计是：

用户提交需求后，立即返回一个任务 ID。
后台任务队列负责执行完整的 AI 视频编辑流程。
前端通过轮询或 WebSocket 展示进度。
任务完成后通知用户查看输出文件。

这个架构和你做过的任何异步任务系统没有本质区别，但它把 AI 生成的“不稳定延迟”纳入了工程考虑范围。

8.6 模型选择：不是越强越好

如果只是做简单的轨迹编辑，完全可以使用成本更低的模型。但如果需求很复杂，比如“把这段采访视频剪成一个 30 秒的预告片，保留最有张力的部分，加上文案字幕”，这时才需要更强大的模型来理解语义。实际项目中可以做“路由”策略：先用低成本模型做结构化解拆，遇到困难需求再“升级”到更强的模型。

9. 总结与后续学习方向

回到文章开头那个项目标题：We built a tool that lets Claude edit videos in one prompt。看到这句话，真正值得记住的不是“一句话剪视频”的表象，而是背后的方法论：用大模型做需求理解和任务拆解，用工具调用完成底层操作，用结构化 JSON 作为模型和程序之间的接口。这个方法不限于视频编辑，你把它换成“一句话处理 Excel”“一句话整理图片”“一句话生成报表”，核心逻辑都是通用的。

如果你希望自己动手实践，建议按下面的路径推进：

先把本地链路跑通：装好 FFmpeg、Claude Code，用我们给出的最小示例完成一次“剪切视频”操作。
再尝试扩展新操作：给 Prompt 增加新的 action，比如“提取音频”“加字幕”“改变分辨率”，在 executor.py 里补上对应分支。
然后接入真实的 Claude API：把伪代码改成真实调用，让模型直接生成 JSON 和命令，而不是写死。
最后做工程化改造：增加任务队列、日志系统、安全校验、成本预算和前端界面。

只能说“一个 Prompt 搞定视频编辑”还为时过早，但把大部分重复性剪辑工作交给 AI Agent 去执行，已经在今天的技术能力范围内。这个领域接下来值得关注的有几个方向：多模态模型进一步理解画面内容，让 AI 能根据镜头语义而不是单纯时间轴来做选择；更完善的视频编辑工具链，让大模型能调用更复杂的非线性编辑器能力；以及更强的工作流编排框架，让“一句话生成完整短视频”真正趋近于可商用水平。对开发者来说，现在就是入场学习的最佳时间点。

不要被“one prompt”这个词迷惑，真正花时间去理解的是“模型如何规划，工具如何执行，错误如何修正”。把这套思路跑通了，你会发现它能用的场景远比视频编辑更广。