视频调色大师（基础校正 + 风格层）
Overview
This skill is a diagnostic + direction tool for color grading, aimed at video creators who
"don't know how to grade." The creator clips a few frames from their unedited footage while
editing, hands them over, and the skill returns a clear, plain-language grading direction with exact
剪映 (Jianying/CapCut) 调节 panel slider values.
It works in two layers:
1. Base correction (universal) — fixes objective "hard defects" that hurt any look: crushed blacks,
blown highlights, dirty color casts (green/magenta), extreme exposure. Source: references/grading-guide.md.
2. Style layer (user-chosen) — decides the final aesthetic. A menu of 10 looks (清晰明亮 default,
日系小清新, 胶片复古, 电影感青橙, 黑金暗调高级, 美食暖调, INS高饱和, 莫兰迪高级灰, 港风复古,
清新自然). Source: references/styles.md.
Division of labor, on purpose: the skill points out the problem and the direction; the creator
turns the knobs. 剪映 has no open external-preset file format, so "type these numbers in" is the
most reliable, most controllable hand-off. No rewritten video, no auto-applied LUT.
Use this skill whenever a user asks how to grade / fix a dull, dark, or flat video, wants screenshot-based
color advice, or names a style (日系 / 胶片 / 电影感 / 黑金 / 美食 / INS / 莫兰迪 / 港风 / 清新自然).
When to use
- "视频有点灰/暗怎么调色" / "帮我看看这个视频怎么调色" / "截图调色建议"
- "剪映调色参数怎么拉" / "让画面清晰明亮" / "调色方向"
- 指定风格："日系调色" / "胶片风" / "电影感青橙" / "黑金高级" / "美食怎么调色" / "INS风" / "莫兰迪" / "港风"
- 用户贴来几张视频截图并问"这样要不要调、怎么调"
Pipeline (fixed order)
- 收图 (Collect) — ask for 3–5 screenshots covering bright / mid / dark scenes.
Critical rule: screenshots must come from the unedited timeline (no filter/LUT already applied).
If the user gives only 1 frame, note that the read is less reliable but proceed. - 选风格 (Pick style) — if the user already named a style, use it; otherwise offer the menu
(seereferences/styles.md风格菜单) and default to 清晰明亮 if they don't care. Confirm before grading. - 跑脚本 (Analyze) — run
scripts/analyze.pyon the provided image paths (absolute paths):
python <skill>/scripts/analyze.py "图1.png" "图2.jpg" ...
It prints JSON with per-image metrics + an aggregate. Read the JSON; do NOT eyeball numbers. - 看一眼场景 (Visual context) — also glance at the images (they are in context). Judge scene type
(indoor / outdoor / backlit), whether faces are present (skin-tone priority), and dominant subject.
Use this to calibrate the wording and any skin-tone caveat. - 读指南映射 (Map) — load
references/grading-guide.md（双向调色总纲 + 基础校正 bands）与
references/styles.md（所选风格的目标指标区间）。这两份是阈值/目标的事实来源；SKILL.md 保持精简。 - 跑推荐引擎 (Recommend) — 直接让
scripts/recommend.py算双向推荐值（它读 analyze 的 JSON、套
styles.md 目标区间、做三态判定 + 人像/曝光滑栏）：
python <skill>/scripts/recommend.py "图1.png" "图2.jpg" --style XXX
输出每个滑块的「当前指标 → 目标 → 推荐值（可 + / 0 / −）」。这是推荐值的权威来源，
不要手动给固定正数、也不要全填正数——该加加、该减减、该零零。 - 出报告 (Report) — 用 recommend 的输出填 fixed 两栏报告（见下方新格式，含三态判定）。
- 出对比预览图 (Preview) — 用 recommend 的值调
scripts/preview.py出「调前 vs 调后」对比 PNG：
python <skill>/scripts/preview.py "图1.png" --style XXX --out before-after.png --brightness 5 --contrast 0 --saturation 3 --temperature 0 --shadow 0 --highlight -8 --sharpen 12 --clarity 0 --glow 4
（数值取自第 6 步 recommend 输出；也可直接recommend.py ... --out before-after.png一步出图。）
说明：挑最具代表性的一张出预览即可；预览是 PIL 近似，非剪映精确结果。
Report format (fixed, two layers)
# 🎨 调色诊断报告（风格：XXX）
## 一、整体印象
（2–3 句：基于 N 张截图，画面整体偏 X，主要硬伤是 …，选用「XXX」风格后的调色方向是 …。友好、给信心。）
## 二、基础硬伤校正（所有风格通用，先修这些）
| 维度 | 当前状态 | 判定 | 剪映建议值 |
| 暗部 | 裁切 9%，死黑 | ⚠️ 死黑 | 阴影 +20 |
| 亮部 | 裁切 1%，安全 | ✓ | 高光 0 |
| 偏色 | 偏绿（脏） | ⚠️ 脏偏色 | 色调 +12 |
| 明暗 | 均值 110，正常 | ✓ | 亮度 0（交风格层） |
| 锐度 | 边缘偏弱 | △ | 锐化 +25 / 清晰度 +15 |
（若某项无硬伤，标 ✓ 并写"交风格层"或"0"。）
## 三、风格配方：「XXX」（剪映调节面板，基础校正后叠加，可直接照填）
> 下表数值来自 `recommend.py` 的双向推荐（当前→目标→推荐，可正可零可负）。**别手改回全正数。**
| 剪映调节项 | 当前指标 | 目标 | 推荐值 | 判定 |
|---|---|---|---|---|
| 亮度 | 均值 103 | (112,132) | **+5** | 不足→补偿 |
| 对比度 | std 66 | (38,52) | **0** | 已在区间 |
| 饱和度 | 27 | (22,34)人像 | **+3** | 不足→补偿 |
| 色温 | rb 1.33 | (1.06,1.22) | **0** | 人像不压冷 |
| 阴影 | 死黑 2.9% | <3% | **0** | 已在区间 |
| 高光 | 过曝 0.3% | <0.8% | **−8** | 过度→回收（护脸） |
| 锐化 | 7.6 | 清晰 | **+12** | 不足→补偿（护皮） |
| 清晰度 | 人像 | — | **0** | 人像压0防洗白 |
| 光感 | — | 微光感 | **+4** | 提通透 |
（数值取自 recommend.py 输出；可注明"先打底、再按对比按钮微调"。）
## 四、在剪映里怎么操作
（引用 grading-guide.md 第三节步骤，精简成 5–7 步：基础校正→叠风格层→对比→全局应用→导出复核。）
## 五、避坑提醒
（引用 grading-guide.md 第四节要点：别只看一帧 / 先修硬伤再风格化 / 别拉爆 / 肤色优先 / 锐化别过头 / 截图须原片。）
迭代优化（不满意就再来一轮）
剪映没有开放的后台 API，外部程序无法"自动在剪映里调色并导出"——最真实的成片只能由用户在剪映里手动套用数值、由剪映自己渲染。preview.py 的对比图是 PIL 近似，不是剪映真实输出。
但"二次迭代、最终给可信数值"完全可做，分两层：
1) 真·闭环（最真实，优先推荐）
- 用户按本轮给出的数值在剪映里调好 → 导出/截一帧结果发回。
- 跑
scripts/refine.py的闭环模式：python <skill>/scripts/refine.py "原图.png" --result "调后结果.png" --style 清晰明亮 --out refine.png - 脚本量这份"剪映真实结果"离所选风格目标区间的差距，给出补调增量（如"亮度再 +7 / 饱和度再 +15 / 色温再 −15"）和下次套用绝对值，并生成"补调后"预览。
- 用户照增量再调一轮，直到达标。这一环的判据来自剪映真实渲染，结论可信。
2) 内部预收敛（少来回）
- 用户不想来回试时，跑自动模式：
python <skill>/scripts/refine.py "原图.png" --style 清晰明亮 --out refine.png - 脚本在 PIL 里直接计算把指标拉到该风格目标中值所需的滑块增量（亮度≈线性、饱和≈乘性、色温≈影响 R/B 比，三者近似独立、直接解算不过冲），输出"我认为能达到效果的最终数值" + 收敛后预览。
- 说明：预收敛是 PIL 近似，仍仅供参考；色温增量封顶 ±15，避免把暖色场景压成难看蓝调。拿去剪映核对即可，若还想微调再用闭环模式。
- 审美护栏（关键）：纯数学逼指标会过冲（如把饱和度推到 +60 变糖果色、锐化过度生硬）。
refine.py对每个风格设了「可信滑块上限」（如清晰明亮饱和封顶 +35、锐化 +28、色温暖色场景只许 0 或正），收敛后用apply_aesthetic_caps强制封顶；最终仍由 agent 用肉眼/视觉复核做"拍板"，宁可指标差一点也要自然。护栏后再出"我认为能达到效果的最终数值" + 预览。
> 无论哪种，最终成片由剪映渲染；我们给的是"方向 + 可信数值 + 近似预览"，绝不声称能一键在剪映后台出片。
Core rules (always enforce)
- 只给方向，不给预设文件 — 剪映无开放外部预设格式，输出永远是"参数区间 + 怎么点"，绝不声称能导出一键套用文件。
- 对比预览是近似 —
preview.py用 PIL 近似映射剪映滑块，仅用于直观展示方向；与实际剪映效果有差异，最终以剪映里实际拉动 + 「对比」按钮核对为准，不得声称预览即最终成片。 - 客观为主、视觉为辅 — 数值来自
analyze.py的 JSON；视觉只用于场景校准与措辞，不替代数据。 - 两层分离 — 基础硬伤校正只看
grading-guide.md；美学方向只看styles.md所选风格。阈值唯一来源，不得擅自改。 - 基础优先于风格 — 先修死黑/过曝/脏偏色/极端明暗，再叠风格层；风格可反向（压暗/降饱和），但绝不能重新造出死黑或过曝。
- 截图须为原片 — 已从加过滤镜的图测出的结论无效，先确认是未调色截图。
- 友好通俗 — 用户是"不懂调色"的作者，用大白话，给信心；不堆砌专业术语。
- 自动肤色优先 & 别拉爆 —
analyze.py已自动检测人脸（skin.has_skin）；一旦为真，所有风格色温封顶 +3、饱和度更克制，报告标注「已启用肤色优先」。不必再靠肉眼判断。任何滑块都提醒"别一次性拉满"，用「对比」按钮核对。
Resources
scripts/analyze.py— 纯 Pillow 客观指标提取（亮度/对比度/饱和度/色温/偏色/裁切/锐度，含自动人脸/肤色检测与肤色区亮度/饱和），输出 JSON。scripts/recommend.py— 双向推荐引擎（核心）：读 analyze 的 JSON，套 styles.md 目标区间，做三态判定（加/零/减）+ 人像/曝光滑栏，输出每个滑块"当前→目标→推荐值(±0)"，并可一步出对比预览。推荐值的权威来源。scripts/preview.py— 按剪映推荐滑块值生成「调前 vs 调后」对比预览 PNG（PIL 近似，含清晰度中间调建模与光感建模，仅供参考）。scripts/refine.py— 迭代优化器：预收敛（调用 recommend 出最终数值）或闭环（根据用户回传的剪映结果帧给补调增量）。references/grading-guide.md— 基础硬伤校正层 + 双向调色总纲 + 人像 HSL 护肤色 + 通透控件（光感/暗角）。判读的事实来源（基础层）。references/styles.md— 风格层：10 款风格菜单 + 每款「目标指标区间」+ 人像特别处理。判读的事实来源（风格层）。
How to apply
When the user submits screenshots (or asks how to grade a video, possibly naming a style):
- Confirm the style (named by user, or offer menu / default 清晰明亮).
- Run
scripts/analyze.pyon the absolute image paths; read the JSON aggregate + per-image metrics. - Glance at the images for scene context (indoor/outdoor/backlit/faces) and note it.
- Load
references/grading-guide.md; apply base-correction bands (shadow/highlight/clipping, dirty cast, extreme exposure, gentle sharpness). - 跑推荐引擎（关键）：
python <skill>/scripts/recommend.py 图1.png ... --style XXX。它自动读
analyze 的 JSON、套 styles.md 目标区间，并自动执行曝光保护 + 肤色优先 + 人像护栏，输出每个
滑块的「当前→目标→推荐(±0)」。这一步替代了过去手动拍板的固定正增量，也替代了手动做曝光/肤色收敛。
5.5. 看一眼判据：确认输出里的has_skin与各滑块 verdict；在报告里用大白话说清关键决策，比如
"高光 −8 是护脸""色温 0 是人像不压冷""对比 0 是已够、不硬加"。 - 按 recommend 输出填报告（三态格式）。若用户给了多张图，取聚合指标最具代表性的一张出预览。
- 用 recommend 的值（或直接
recommend.py --out）调preview.py出对比图，随报告呈现。 - 结尾给避坑提醒。绝不产出预设文件或声称一键导入。
Keep the tone encouraging and the language plain — the user wants confidence and a clear next step, not a color-science lecture.
