企业官网建设流程全解析

拆开video-use：四个专业Agent加EDL，模块化剪辑设计妙在哪

【免费下载链接】video-useEdit videos with coding agents项目地址: https://gitcode.com/GitHub_Trending/vid/video-use

对话式剪视频正在从"演示"走向"日常"。GitHub 上已经出现了一批让 AI Agent 直接操作浏览器、操作电脑的工具，而 video-use 的选择是回到最重的素材——视频本身：把原始素材丢进一个文件夹，对 Claude Code 说一句"edit these into a launch video"，几个小时后拿到带调色、字幕、动画叠加的成片。社区报道显示它上线不久即收获超过 1.2 万星标，被反复讨论的不仅是"能剪"，更是"怎么剪的"：不依赖任何预设模板，不吃下数万帧画面，而是靠四个专业 Agent 角色 + 一份 EDL 契约完成了从感知到交付的整条流水线。

这篇文章不从使用教程切入，而是直接拆开本地仓库的源码与技能文档，还原这套"LLM 思考 + Python 编排 + 专业工具执行"的模块化剪辑设计：感知层如何把视频压成 12KB 文本，决策层如何产出 EDL，执行层如何把 EDL 变成无损可交付的成片，以及这套抽象对其他视频 Agent 到底意味着什么。

一、最难的素材：为什么 Agent 不能"看"视频

视频是 Agent 领域里最尴尬的输入。一张图可以交给多模态模型直接理解，但一段几分钟的 talking head 意味着 3 万帧画面；即便按每帧 1500 token 折算，也是 4500 万 token 的"噪声"，既读不完，也读不起。video-use 的仓库在 README 里给出了它的反直觉答案：LLM 从来不"看"视频，它"读"视频——通过两层感知，把视频压缩成它真正需要的东西。

第一层是始终加载的音频转录。每个源文件调用一次 ElevenLabs Scribe（见 transcribe.py，timestamps_granularity="word"、diarize=true、tag_audio_events=true），拿到词级时间戳、说话人分离和(laughter)、(applause)这类音频事件；随后 pack_transcripts.py 把所有 take 打包成一份约 12KB 的takes_packed.md。第二层是按需生成的视觉合成图。timeline_view.py 接受video start end三个参数，产出"胶片条 + 波形 + 词级标签 + 静音缺口着色"的合成 PNG——它明确被标注为决策点钻取工具，而不是扫描工具，只在有歧义的停顿、补拍取舍、切点复核时调用。

## C0103 (duration: 43.0s, 8 phrases) [002.52-005.36] S0 Ninety percent of what a web agent does is completely wasted. [006.08-006.74] S0 We fixed this.

这个思路与 browser-use 把网页结构化 DOM 交给 LLM 而非截图如出一辙——README 原话："Same idea as browser-use giving an LLM a structured DOM instead of a screenshot — but for video." 只不过 video-use 的"结构化 DOM"是一份带时间轴的词级转录稿。这直接决定了后面所有 Agent 的工作方式。

二、四个专业角色：主 Agent 编排下的分工

严格说，video-use 仓库里并不存在四个可独立启动的 Agent 进程，它定义的是四个专业角色，由一个拥有 Shell 权限的编码 Agent（Claude Code / Codex / Hermes / Openclaw 均可）统一编排，每个角色手里握着各自的确定性工具（helpers/ 下的 Python 脚本）。SKILL.md 的 The process 一节把这套协作写成了 8 个步骤，拆开来看恰好是四条专业生产线。

角色一：感知分析。负责ffprobe盘点所有源文件、transcribe_batch.py四线程并行转录（transcribe_batch.py 默认--workers 4）、pack_transcripts.py生成短语级转录稿，并抽样一两个timeline_view建立视觉第一印象。它的产出不是"分析报告"，而是一份可寻址的文本索引：每句话都有[start-end]时间范围，说话人编号 S0/S1 区分谁在说。

角色二：编辑决策。这是唯一的"纯思考"角色。仓库为它准备了一份结构化的 sub-agent brief（SKILL.md 的 Editor sub-agent brief）：输入takes_packed.md、叙事上下文、预期结构原型（Tech launch / Tutorial / Interview / Documentary……）、需要回避的口误清单与目标时长，输出一份 JSON 数组——每个元素是一次剪辑决策，附beat（叙事段落，如 HOOK / SOLUTION）和reason（选这段的理由）。它的输入输出全部是文本与 JSON，不碰任何帧。

角色三：动画创作。按 Hard Rule 10，多个动画必须并行生成："Spawn N at once via the Agent tool; total wall time ≈ slowest one"。每个动画是一个自包含的 sub-agent 提示词（子代理没有父上下文，所以 brief 里必须写全目标、绝对输出路径、分辨率/帧率/编码/CRF、调色板的具体 RGB 值、字体路径、逐帧时间线、反清单、交付检查项），每个动画 slot 一个唯一文件名，互不覆盖。引擎可以选 HyperFrames（HTML/CSS/GSAP）、Remotion（React）、Manim（数学/示意动画）或 PIL 逐帧合成——按需懒安装，绝不在安装阶段全局装齐。

角色四：渲染执行与质检。render.py 是整条流水线的"手"，SKILL.md 的 12 条 Hard Rules 有一半是为它写的：字幕最后叠加、逐段抽取后无损 concat、每个切点 30ms 音频淡入淡出、overlay 用setpts=PTS-STARTPTS+T/TB对齐时间窗、字幕用输出时间轴偏移……渲染完成后，主 Agent 对渲染产物（而非源素材）在每个切点 ±1.5s 窗口跑timeline_view自检，检查视觉跳变、波形尖峰（漏网的爆音）、被 overlay 遮挡的字幕、错位的动画，且自检最多 3 轮，超过就如实向用户报障而不是无限循环。

四个角色的协作关系是：感知分析提供索引 → 编辑决策产出 EDL → 动画创作并行产出 overlay 素材 → 渲染执行按 EDL 消费一切并自检。而把它们串起来的那根轴，正是 EDL。

三、EDL：把"思考"和"动手"焊死的契约

EDL（Edit Decision List，编辑决策列表）不是新概念，非线性剪辑软件用了几十年；video-use 的巧思在于把它做成了 LLM 与工具之间唯一的、可验证的契约。仓库在 SKILL.md 里给出了完整格式：

{ "version": 1, "sources": {"C0103": "/abs/path/C0103.MP4", "C0108": "/abs/path/C0108.MP4"}, "ranges": [ {"source": "C0103", "start": 2.42, "end": 6.85, "beat": "HOOK", "quote": "...", "reason": "Cleanest delivery, stops before slip at 38.46."} ], "grade": "warm_cinematic", "overlays": [ {"file": "edit/animations/slot_1/render.mp4", "start_in_output": 0.0, "duration": 5.0} ], "subtitles": "edit/master.srt", "total_duration_s": 87.4 }

这份 JSON 的每个字段都精确对应 render.py 的一段确定性逻辑：ranges喂给extract_all_segments，grade可以是预设名、原始 ffmpeg filter 或auto，overlays进入最终的 filter_complex，subtitles被强制放在滤镜链最后。LLM 只负责在 EDL 里做取舍决策（选哪段、为什么、放哪个叙事位置），一切具体的编码行为都由脚本执行——思考层永远不拼 ffmpeg 命令行，执行层永远不替模型做审美判断。

EDL 还承担了跨时间轴的"翻译"职责。源素材切出来后拼进了新的时间线，字幕时间戳必须跟着重映射。render.py 的build_master_srt严格按 Hard Rule 5 实现：

out_start = word.start - segment_start + seg_offset

即"输出时间 = 词在源片段内的相对时间 + 该片段在成片中的偏移"。这条规则如果写错，字幕会在拼接后整体错位——而它只是 12 条 Hard Rules 里的一条。EDL 的存在让这类正确性约束可以集中、反复、低成本地验证：渲染一次、自检一次、不行就改 EDL 重渲，最多三轮。

四、解耦的细节：思考层不写滤镜，执行层不做判断

"LLM 思考 + 工具执行"的解耦，最值得看的是几个把判断权让渡给算法的设计，它们共同保证了模型永远在低成本区间做决策。

自动调色的数据驱动。grade.py 的默认模式是auto：用 ffmpeg 的signalstats采样 10 帧，算出平均亮度y_mean、动态范围y_range、平均饱和度sat_mean，再套一组带硬边界的决策规则——对比度、伽马、饱和度的修正全部钳制在 ±8% 以内，目标是"看起来干净但不显得被调过"。模型要做的事只有一件：在 EDL 里写"grade": "auto"或者点选warm_cinematic这类创作预设。真正决定滤镜参数的是统计信号，不是 LLM 的想象力。

HDR 源片的自动兜底。render.py 用ffprobe检测color_transfer（smpte2084为 PQ、arib-std-b67为 HLG），一旦发现 iPhone 默认输出的 HLG 素材，就自动前置zscale + tonemap链，把 HDR 转成干净的 Rec.709 SDR——否则 8bit 重编码后仍携带 HDR 传递元数据，上传到社交平台会过曝。这是模型根本不需要知道的底层正确性。

平台安全区写进代码。字幕的MarginV=90不是审美，注释里写得很清楚：TikTok / Reels / Shorts 的 UI（标题、用户名、音乐、右侧操作条）会遮住画面底部约 25–30%，MarginV=90配合 libass 的PlayResY=288相对缩放，把字幕基线抬到任何竖屏平台的安全区之上。规则级正确性与品味级自由在仓库里被刻意分开：12 条 Hard Rules "non-negotiable"，其余全是"worked example，可随意偏离"。

记忆与缓存。转录结果按源文件缓存（Hard Rule 9：源文件不变就不重转录）；每次会话的决策追加到<videos_dir>/edit/project.md，下次启动先总结上一次会话再问是否继续。整个流程是 "Ask → confirm → execute → iterate → persist"，主 Agent 在动刀之前必须先拿到用户用自然语言确认的策略。

五、这套架构对其他视频 Agent 的启发

video-use 值钱的地方不在某个滤镜多好看，而在它对"Agent 处理高维非结构化输入"给出了一个可复制的范式。

第一，感知接口先行。视频的默认感知形态不应该是"喂帧"，而是"喂带时间轴的文本 + 决策点按需看图"。12KB 转录稿对 4500 万 token 的对比不是营销数字，是 token 经济学：模型只在最便宜的表征上做推理，昂贵的视觉信号留到真正有歧义的那几个决策点。任何想把 Agent 引入视频域的团队，第一步都该问"它的结构化索引是什么"，而不是"怎么让它看懂画面"。

第二，用中间产物切割 LLM 与工具。EDL 之所以是好抽象，是因为它同时满足三个性质：人类可读、机器可执行、可反复重放。思考层产出的每一行决策都带reason，执行层按同一份 JSON 重渲无数次结果都一致。对比直接让模型拼 ffmpeg 命令的做法，EDL 把"决策"从"执行"里剥了出来，也让错误定位变得简单——是选段错了（改 EDL），还是合成错了（改 render.py），一目了然。

第三，并行子代理 + 自检上限。动画这类重活按 slot 拆给并行 sub-agent，墙钟时间只受最慢的一个约束；自检在交付前自动执行但设置 3 轮上限，避免 Agent 陷入无限自我修正。这给了"Agent 干活的可控性"一个工程答案：用并行摊平成本，用上限兜住失控。

第四，正确性规则化。12 条 Hard Rules 每一句都对应一种"静默失败"——字幕被 overlay 遮住、拼接处爆音、字幕时间轴错位、动画显示到中段画面。把这类失败写进文档并由脚本强制，模型才敢在其余空间里自由发挥品味。反过来说，如果一套 Agent 系统连"哪些地方不能错"都没定义清楚，它的自由创作就是给观众埋雷。

当然，这套设计也有明确的边界：它需要 Claude Code / Codex 这类 Shell 级 Agent 环境，没有 GUI，Ask → Confirm 的人机协同意味着它天然不适合纯无人值守的批处理流水线。但这恰恰是它的取舍——把"对话式剪辑"体验做透，而不是强行追求全自动。对正在构建视频 Agent 的开发者而言，video-use 给出的不是一套可以照抄的代码，而是一份值得借鉴的模块化蓝图：四个专业角色各司其职，一份 EDL 契约贯穿始终，思考与执行在各自的边界内做到极致。

【免费下载链接】video-useEdit videos with coding agents项目地址: https://gitcode.com/GitHub_Trending/vid/video-use