version: "1.0.0" name: color-grading description: 在剪辑或图片编辑里调色时使用：校正曝光与白平衡、统一镜头颜色、套用电影感/日系/胶片等风格、调肤色与天空、检查调色结果。时间线其他操作用 video-edit-workbench，修图与选区用 image-edit-workbench。

全能调色：先读数，再调参，调完再读数

铁律

1. 偏色和曝光看读数，不看截图。 视觉模型对细微色偏、曝光判断不准。剪辑用 observe_video_edit_color，图片用 observe_image_edit_color，读中灰偏差（EV）、高光/暗部溢出、估计光源色温与可信度、肤色候选。截图只用来判断内容和风格。
2. 参数写入走通用属性。 剪辑写 video_edit.effect.parameters（片段下 definition_id=effect:color_grade 的效果），图片写 image_edit.layer.params（definition_id=color_grade 的调整层）。写入是整个对象替换：先读现有参数，合并后再写；一次写入就是一步撤销。没有“设置色温”之类的专用工具。
3. 分析与匹配是建议。 analyze_video_edit_color（自动校色、参考镜头匹配）和 analyze_image_edit_color（图片自动校色）只返回绝对建议值，不改作品；合并进参数后写入。
4. 调完再读一次。 写入后用同一个 observe 工具读 after 读数，对照下面的验收数值；不达标就再调，达标后再给用户看结果。

工具按需加载：内置 Pi 用 load_application_tools({names:[...]})，只加载这一步要用的。剪辑：observe_video_edit_color、analyze_video_edit_color；图片：observe_image_edit_color、analyze_image_edit_color。

固定顺序

1. 观察：读调色前读数（剪辑 stage=before_grade 或片段还没有全能调色时的 after_grade；图片 stage=before_grade 配合调整层引用）。记下画面基调：key=low 是低调画面（夜景、舞台），high 是高调画面（雪景、白底），不要把它们硬拉到中灰。
2. 一级校正：先白平衡和曝光，再黑白点与反差，最后饱和度。可以先调 analyze 拿建议；白平衡可信度低于 0.4 时画面可能是有意偏色（日落、霓虹），只做部分校正或保留。
3. 镜头匹配（剪辑）：analyze_video_edit_color 传 referenceClipRef（同序列已调好的参考镜头），默认 matchMethod=mkl，返回可直接微调的滑块值；整体替换参数，并在同一事务把被替换参数的 frame_curves 清掉。多个镜头逐个对同一参考匹配。
4. 风格：从风格词典选最接近用户描述的配方，按强度（0–1）缩放后合并写入；风格不包含白平衡和曝光，不会覆盖一级校正。用户描述模糊时提出 2–3 个候选配方（名称 + 一句话效果），让用户选。
5. 二级：肤色、天空、单一颜色用混色器（8 色 × 色相/饱和度/明亮度）；需要精确选区时用 HSL 辅助，先开蒙版观察再校正，完成后关闭蒙版。
6. 检查：读 after 读数和画面，写明哪些已验证、哪些只是建议。

验收数值（起点，按用途突破）

参数速查

曲线控制点、LUT、HSL 辅助与晕影的字段契约以 describe 返回的参数 schema 为准。