color-grade（LUTs via ffmpeg）是一个基于 ffmpeg 的视频调色技能，目标是用 LUT 文件完成调色，避免每次都重新推导滤镜参数。
用途
将电影感外观或 LUT 应用到视频；也可以生成并比较多个候选调色，交给用户选择。
主要能力
支持两类 LUT 格式，均为 ffmpeg 原生，无需额外依赖：
- .cube：3D LUT（调色师常用的交付格式），通过 lut3d 应用。
- .png HALD-CLUT：由滤镜链烘焙出的外观，通过 haldclut 应用。
grade 命令会根据文件扩展名自动识别格式。
使用方式
套用一个外观： uv run video-agent grade apply in.mp4 --lut luts/teal_orange.cube -o out.mp4 uv run video-agent grade apply in.mp4 --lut luts/warm.png -o out.mp4 # HALD
生成多个候选外观并让用户挑选：
先把同一帧通过多个候选外观渲染到一张带标签的对比图中，展示给用户，用户选中后再把该外观套用到整条视频：
uv run video-agent grade preview in.mp4 --at 45.0
--lut none --lut luts/warm.png --lut luts/teal_orange.cube --lut luts/punchy.png
-o looks.png
读取 looks.png → 用户选择 → 用选中的 LUT 执行 grade apply
其中 none 表示未调色的原始画面，始终应加入作为参照。选取帧（--at）时，应选包含肤色、明亮区域和暗部区域的画面，以便看出调色效果。
将外观烘焙成可复用 LUT：
先把外观写成一条调色滤镜链，再将其一次性烘焙为 HALD LUT，从而可复用且应用更快：
uv run video-agent grade gen-lut
--eq "curves=r='0/0 .5/.55 1/1':b='0/.03 1/.97',colorbalance=rs=.05:bs=-.05"
-o luts/warm.png
该命令让一个恒等 HALD-CLUT 经过滤镜链，输出 .png LUT。只能使用可用的滤镜——此 ffmpeg 为 LGPL 许可，因此没有 eq（也没有 drawtext）。调色可用的滤镜包括：curves（主力工具，逐通道色调曲线）、colorbalance（阴影/中间调/高光 RGB）、colorchannelmixer（通道混合/饱和度）、lut1d。
快速起步示例：
- warm：colorbalance=rs=.04:rm=.03:bs=-.04:bm=-.03
- teal-orange：colorbalance=rh=.06:bs=.08，同时抬升阴影蓝色、推高高光暖色
- punchy：curves=all='0/0 .25/.18 .75/.82 1/1'（S 曲线对比度）加 colorchannelmixer 轻微饱和度调整
- desaturate/filmic：用 colorchannelmixer 向灰色靠拢，或用 curves 抬升黑位
在管道中的位置
调色应放在最终编码阶段，在剪辑/重构之后、字幕与叠层之前（这样烧录的文字能保持预期颜色）。在 edl-edit 任务中，在 EDL 里设置 "grade": "luts/x.png"，它会在同一遍处理中套用到整条成片。
适用场景与限制
调色对平淡、log 或消费级设备素材帮助最大；典型的 Rec.709 录屏和网络摄像头画面只需轻微抬升。不要过度调色——细微的外观胜过厚重的滤镜。
注意事项
- .cube 与 HALD：外部调色师的 LUT 通常是 .cube（→lut3d）；在此处烘焙的外观是 .png HALD（→haldclut）。命令两者都能处理，只需保持扩展名与实际格式一致。
- HALD 级别：gen-lut 默认级别 8（64³ 网格），足以支持平滑调色；提高级别会生成更大文件，通常不必要。
- 调色一次、重复使用：把 luts/*.png（或 .cube）提交保存，使外观以纯文本/数据形式存在，从而在不同片段和重新渲染时一致地复用。