技能介绍

Grade Images 是一个面向 Codex 的确定性照片调色技能，支持曝光与白平衡校正、参考图匹配、创意调色、批量风格统一，以及经用户明确许可的原生高光扩散。它不调用生成式图像编辑器——核心设计很简单：让 AI 理解意图并审阅预览，再由一个受约束的本地渲染器执行版本化的 JSON 配方。

它存在的原因是：很多修图工作流把「色彩决策」和「生成式重建」混在一起，这会悄悄改变人物五官、物体、纹理或几何结构。这个技能改用操作白名单 + 一个不含裁剪、变形、修补、平滑、降噪、修复与合成算子的引擎，唯一的纹理算子是用户明确请求、且受边界约束的输出锐化。

技能以保护原图内容为核心：不会改变尺寸、几何结构、人物五官、物体、文字或纹理，也不会凭空合成光源、光束、镜头光斑等效果。即使选择强烈调色，仍会将色彩强度与光效权限分开；只有在用户明确同意后，才允许从原图真实高光中提取并生成受控的柔和扩散。

严格模式下保证流水线不会有意：改变图像尺寸或 alpha 拓扑；重塑人脸或物体；增加、删除或重新生成画面内容；默认改动纹理、模糊原图、降噪、平滑皮肤、修复细节或合成纹理；合成或叠加太阳、灯、反射、光斑、星芒、光晕、光束、轮廓光或画上去的高光；执行未知的配方算子。

需要注意：调色必然改变像素值，JPEG 重编码也有损。这个技能保证的是「受约束的操作 + 结构保持」，不是逐字节一致的输出。

适用场景

技能支持五种工作流：audit、correct、look、match、batch。典型需求包括：

  • 校正这张照片的曝光和白平衡，不改变原图的纹理和人物五官特征。
  • 按照参考图给照片匹配色彩，不改变原图的内容和结构。
  • 给这张 RAW 照片做创意调色，生成保守、标准、强烈三档方案供选择。
  • 给一组照片做统一、克制的电影感调色。
  • 审计照片是否存在剪切（clipping）与色偏问题。
  • 低光场景（可从 assets/recipes/low-light-cinematic.json 起步）、无人物场景，或启发式蒙版明显过宽时关闭肤色保护。

核心能力

  • 线性光下的曝光与白平衡校正，与审美强度分离。
  • 明确的强度策略：conservative、standard、bold、transformative；主观需求未指定强度时 standard 作为兜底。natural、cinematic 这类风格词不代表要降饱和；transformative 只在明确要求大幅改动或用户直接选择时启用。
  • 可复现的创意风格：单调曲线、ASC-CDL 风格控制、饱和度与克制的分离色调（split toning）。
  • Schema 1.1 的 vibrance：做强烈色彩变化时，避免把本已饱和的区域统一推爆。
  • Schema 1.2 平滑色相范围重映射：依据源像素的色相、饱和度与明度门限，不使用语义分割或生成式蒙版。例如把暖白樱花推向浅紫，同时压低环境黄橙。
  • 侘寂深灰风格：以沥青炭灰为基底、克制的冷色、相对突出的暖色焦点与受控高光，不含真实叠加图层也不做锐化（assets/recipes/wabi-sabi-deep-gray.json）。
  • 参考图派生匹配，不用神经风格迁移；参考报告会分别呈现色调、色彩浓度、全局色偏与亮度分区色彩的匹配进度，并给出下一项可执行的调整建议。
  • 带标注的多方案预览：保留每个独立结果与配方，并从单一基础配方自动派生保守/标准/强烈/变革四档，只缩放创意部分。
  • 单次通过的预览命令：一次渲染、评估、标注并记录耗时，不重复解码图像、也不写临时拼图脚本。
  • 批量处理：逐图归一化后再套一份共享的创意风格。
  • 可选的羽化肤色保护，并明确给出不确定性告警。
  • ICC 转换到 sRGB 工作空间与输出空间。
  • 可选 RAW / DNG 开发：显式锁定 AHD 去马赛克、相机/日光白平衡路由、关闭细节处理（降噪、坏点修复、中值滤波、色差校正、锐化等），并记录位深、色彩空间、方向与解码器设置。
  • 机器可读产物：配方、渲染清单、质量报告。
  • 结构告警：尺寸变化、alpha 拓扑、边缘方向、新增边缘、剪切与极端饱和度。
  • 可选的原生高光扩散：需明确同意，严格拒绝合成光源。

版本沿革：v0.2.1 引入多方案预览与带原图的标注对比图，参考匹配细分为阴影/中间调/高光与不同色彩浓度区间，并可在选定强度内搜索多个安全候选。v0.3.0 加入「变革型」调色（schema 1.2 平滑色相范围重映射，仍不用语义分割、生成式蒙版或合成光效）。v0.3.1 聚焦稳定性、速度、RAW 开发与风格语言扩展：同源不可变颜色状态下顺序无关合成、更快的无损 PNG 编码预览、RAW 路径锁定 AHD 与相机白平衡，并新增「侘寂深灰」。v0.3.2 是 RAW 优化版本：相机白平衡不再只按「系数为正」判定，缺失/非法/可疑系数会被分别记录并按固定规则回退；raw_check.py --require-camera-wb 可在严格工作流中拒绝任何回退；真实 NEF、ARW 与 DNG 纳入本地回归。v0.3.3 新增严格的胶片色彩路由（route_film.py，拆成经典负片、日光一次性胶片与电影印片三种方向）与纪实扩展（route_documentary.py，含生动纪实与档案纪实两条基线，来自八组本地 Before/After 研究对照）。v0.3.4 保持普通配方与 v0.3.3 像素兼容，新增 schema 1.3 精修路径用于明确的输出锐化请求：唯一新算子是在缩放之后、有边界且源自原图亮度细节的锐化，带肤色/噪点保护与纹理告警。

支持范围与限制（v0.3.4）：接受单帧 8 位 JPEG、PNG，以及已安装 rawpy/LibRaw 后端支持的相机 RAW 与 DNG。RAW 支持是可选的，解码用 16 位中间结果完成完整开发，目前导出 8 位 PNG 或 JPEG 派生文件，绝不改写相机 RAW。视频、动态图、编码的 16 位栅格输入、修图、几何变换、颗粒、降噪、去模糊、修复、合成光照与生成式编辑都不支持；输出锐化只能通过明确的 schema 1.3 精修请求获得。已完全剪切的高光或阴影在编码后的 JPEG/PNG 中无法恢复。

效果预览

确定性照片调色与RAW开发

一次完成的渲染会产出：调色后的图像、JSON 配方的精确副本、包含源与输出哈希的清单，以及运行对比时生成的机器可读质量报告。输入文件永远不会被覆盖。需要无损调色母版时优先用 PNG，仅在必要时生成 JPEG 派生文件。

工作方式

  • 先声明再渲染：主观渲染之前，Codex 会简要说明预期的色调方向、色彩方向、强度、保护选择与光效状态。若仍有多种合理解释，variants 命令会分别产出单独预览，并生成一张带原图的标注对比图。
  • 强度选择：主观风格需在 conservative / standard / bold / transformative 中选一档；提示词没有暗示时，技能会在渲染前询问，问不到就用 standard，而不是悄悄弱化调色。
  • 快速路径：单个主观结果推荐用 preview.py，一个进程内产出预览图、配方副本、质量报告、标注对比图、清单与各阶段耗时。
  • 先预设后自造：有匹配的内置预设会先渲染；质量阈值不能通过乱改曝光或颜色轴去凑。
  • 参考匹配：先看阴影/中间调/高光分区的诊断，再在用户选定强度内部做安全候选搜索（search_match.py）。
  • 效果与强度分离：梦幻、柔光、神圣光、雾气这类需求，强度不代表获得了光效权限——技能会先问是否允许受约束的原生高光扩散，明确同意后才可用 assets/recipes/soft-dream-source-glow.json 起步；该效果只能扩散原图已有的光，不能加光源、光斑、光束、星芒或新画面内容。

你需要提供

  • Python 3.10 或更新版本、Pillow、NumPy。
  • 相机 RAW 还需要额外安装 rawpy/LibRaw。
  • 一张（或一批）单帧 8 位 JPEG/PNG，或 rawpy/LibRaw 支持的 RAW/DNG 文件。
  • 安装运行依赖并拷贝技能目录，然后重启 Codex：
python -m pip install -r requirements.txt
python -m pip install -r requirements-raw.txt

技能要拷贝到 Codex 技能目录，通常是 $CODEX_HOME/skills/grade-images；未设置 CODEX_HOME 时用 ~/.codex/skills/grade-images。

macOS 或 Linux：

mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
cp -R skills/grade-images "${CODEX_HOME:-$HOME/.codex}/skills/grade-images"

Windows PowerShell：

$codexRoot = if ($env:CODEX_HOME) { $env:CODEX_HOME } else { Join-Path $env:USERPROFILE '.codex' }
New-Item -ItemType Directory -Force (Join-Path $codexRoot 'skills') | Out-Null
Copy-Item -Recurse -Force 'skills\grade-images' (Join-Path $codexRoot 'skills\grade-images')

你会获得

  • 调色后的图像文件。
  • 该次渲染所用 JSON 配方的精确副本。
  • 含源文件与输出哈希的渲染清单。
  • 运行对比时生成的机器可读质量报告（色调、色彩浓度、全局色偏、亮度分区色彩分项进度与下一步建议）。
  • 多方案预览图与带原图的标注对比图。

使用示例

自然语言触发即可，例如：「Correct the exposure and white balance without changing texture or facial features.」「Match this photo to the reference image's color treatment.」「Give this set a cohesive restrained cinematic grade.」「Audit these photos for clipping and color-cast problems.」

也可以直接调用脚本：

python scripts/analyze.py input.jpg --output analysis.json
python scripts/raw_check.py input.nef --output raw-check.json --full-decode
python scripts/raw_check.py input.nef --output raw-check.json --require-camera-wb
python scripts/grade.py validate assets/recipes/neutral-correction.json
python scripts/grade.py render input.jpg --recipe assets/recipes/muted-cinematic.json --output preview.png --max-size 1600
python scripts/compare.py input.jpg preview.png --recipe assets/recipes/muted-cinematic.json --output quality.json
python scripts/compare.py input.jpg preview.png --recipe match.json --reference reference.jpg --output quality.json
python scripts/preview.py input.jpg --recipe assets/recipes/transformative-cool-violet.json --output-dir previews --max-size 1200
python scripts/route_film.py "标准强度胶片感" --output film-route.json
python scripts/route_documentary.py "经典纪实摄影调色" --output documentary-route.json
python scripts/variants.py input.jpg --variant conservative=a.json --variant standard=b.json --variant bold=c.json --variant transformative=d.json --output-dir previews
python scripts/variants.py input.jpg --base-recipe base.json --output-dir previews
python scripts/search_match.py input.jpg reference.jpg --template assets/recipes/neutral-correction.json --intensity bold --output-dir match-search
python scripts/regress.py private-cases.json --output-dir regression-results

开发与发布：

python -m pip install -r requirements-dev.txt
python -m unittest discover -s tests -v
python -m compileall -q skills/grade-images/scripts
python tools/package_skill.py --output dist/grade-images.zip