Photo Cinematic Grade

把摄影者已拍下的像素调成克制的电影感，不替摄影者换掉画面。 脚本负责像素、参数和数值，摄影者决定氛围与是否接受。

当前能力与未完成项

当前完成 render 基础、候选小样、前后对比，以及供后续管线使用的浮点色彩内核。新内核尚未接管 CLI render，不代表整个 skill 已验收完成。

• 已实现：scripts/cinegrade.py render、looks、candidates（中性基线 + 两个风格的固定三选小样）、compare（左原图、右调色的原尺寸并排）、确定性整数调色、三份基础配方、独立 image_io.py、数值 QA、隐私边车、原件与已有输出保护。
• 尚未实现：card、lut 命令，以及相应的集成测试；计划中的 analyze/sheet、浮点线性光与 OkLCh 的端到端管线、六个规定风格、完整 QA、JPEG/16 位输出仍待补齐。不得暗示它们已经可用，不能用生成图或口头描述冒充实际小样。候选固定列出而不自动排名或替摄影者选定。
• CLI 不提供局部蒙版、人物/肤色识别、白平衡或曝光自动矫正、颗粒、暗角、锐化、降噪、裁剪。避免把调色变成无法追溯的整图修饰。

新增浮点色彩内核（0.4.0）

scripts/color_core.py 重建计划 3.4 的基础像素运算，供六风格管线后续接入。 已实现扩展 sRGB 传递函数、线性 sRGB 与 Oklab 双向转换、OkLCh 极坐标转换，以及端点固定的 Oklab 亮度曲线。 调色阶段保持 float64，不做中间量化、不钳位色域外数值。独立终端 quantize_srgb8 显式转成 uint8， 拒绝超色域输入，只饱和处理新增噪声造成的越界。纯数值 API 不读照片、不写文件、不改 ICC。 需要 numpy，当前测试环境为 numpy 2.0.2；原有 CLI 读写仍按既有流程执行。

曲线是本轮重新设计的工程实现，历史 0.4.1 原型未找回，也未移植。 公式与标准矩阵来源见 references/grading-research.md 的浮点内核一节。 contrast、strength 都要调用者显式传入；此 API 的 strength 为 0..1，与旧 CLI 的 0..100 分开。 不增加默认配方。工程曲线尚未经摄影者视觉确认，不把数学测试当作六风格效果验收。

目前 render/candidates/compare 仍用原有整数算法和三份配方，输出像素契约不变。 亮部色度滚降、分色相变换、分离色调与减法密度均已有独立浮点实现，见下节；最终抖动量化已有独立 API，见 0.9.0 一节；色域映射与占比已有独立 API，见 0.10.0 一节；显式选区肤色限幅已有独立 API，见 0.11.0 一节；线性光 bloom 已有独立 API，见 0.12.0 一节；有色边缘光晕已有独立 API，见 0.13.0 一节；线性光单色颗粒已有独立 API，见 0.14.0 一节；自动肤色选区、暗角和六风格集成仍待完成。 此内核不恢复输入已丢失的高光，也不让当前 CLI 支持 RAW、HDR 或 16 位文件。

高光色度滚降（0.5.0）

color_core.highlight_rolloff_oklab(lab, start=..., strength=...) 补齐计划 3.4 的高光去色阶段。 将经过亮度曲线的 Oklab 送入此函数，高光的 a/b 同比例缩小，保持 L 和非零色度的色相。 低于或等于 start 的像素原样返回；strength=0 对全部像素恒等；满强度在 L=1 时色度降为零。 这一步直接计算颜色，不量化、不读写图片，不代替色域映射或肤色保护。

start 必须显式给出，范围 [0,1)；strength 必须显式给出，范围 [0,1]。 start 是曲线后 Oklab L 的起点，不能当作编码 sRGB 码值或曝光 EV。 计划未规定起点与完整配方，脚本不猜默认值，也不自动选择一组参数。 新函数的工程曲线及推导见 references/grading-research.md，尚待真实照片与摄影者确认。 它没有接管 CLI，render/candidates/compare 仍使用原有整数管线和三份配方。

16 项新增合成数学测试覆盖手算值、高光单调去色、色相/亮度不变、强度恒等、端点平滑、 极窄肩部与接近白点的数值稳定性，以及与现有浮点内核串接。测试取值仅用于数学验证， 不把通过测试当作六风格区分度、肤色或 LUT 验收；不声称移植了历史 0.4.1 原型。

分色相调色内核（0.6.0）

color_core.hue_band_adjust_oklch 实现计划 3.4 的分色相调整。在调用者明确给出的 环形色相窗口内旋转 hue、缩放 chroma，保持 Oklab L；窗口外和恰好中性的像素不动。 窗口跨越 0°/360° 时仍连续，中心与两端的权重斜率为零。没有中间量化或 RGB 钳位。 这使后续风格能够分别处理蓝、绿、红等色相，而不必对整幅照片统一染色。

所有创意参数均为必填：center 是窗口中心角，width 是支撑半宽 (0,180]°， hue_shift 是 [-180,180]° 的转角，chroma_scale 为非负倍率，strength 为 [0,1]。 强度为零或转角零且倍率一时精确恒等；C=0 不染色。只改色度时保持输入 hue 表示， 发生旋转时将 hue 归一到 [0,360)。色度变成零后 hue 无物理定义，不要求数值为零。 多次调用依次作用于上一次输出的色相，顺序可能影响重叠窗口。

这是依据计划重新实现的工程曲线，参数没有默认值，未找回或移植历史 0.4.1 原型。 21 项新增测试使用明确标注的合成数学输入，只验证数值契约，不代表摄影者确认配方。 窗口外的暖色能保持原值；脚本仍不识别人脸或肤色，不能据此承诺肤色护栏已通过。 函数尚未接管 CLI；六风格配方、真实照片与完整管线验收仍待完成。 推导、串接方式与边界见 references/grading-research.md 的同名一节。

分离色调内核（0.7.0）

color_core.split_tone_oklab 补齐计划 3.4 的分离色调像素运算。按显式给定的 Oklab 亮度分界 balance，把暗部和亮部推向各自的色相；保持 L，不量化、不钳位 RGB。 每区的色度增量在区间中点最大，向黑点、分界和白点平滑降到零，因此中性黑白不被染色。 区间内部的中性灰可以染色。新增量以 a/b 向量相加，原有彩色像素也可能改变色相。

六个参数全部必填，没有默认配方：shadow_hue、highlight_hue 为周期角度， shadow_chroma、highlight_chroma 为非负的峰值新增 Oklab 色度，balance 为 (0,1) 内的 Oklab L，strength 为 [0,1]。色度参数是增量，不是目标饱和度；balance 不是 EV 或像素百分位。 strength=0 或两个色度增量都为零时返回精确副本，输入验证仍执行。

这是按计划重新实现的工程变换。四次包络系数由端点与斜率约束推导，细节见 references/grading-research.md。它没有恢复历史 0.4.1 原型或复现原型配方/评分。 20 项新增合成数学测试只验证像素数学，测试参数未获确认为摄影配方。 函数不自动识别人脸或保护暖色主体；真实肤色护栏、六风格及完整管线仍须单独验收。 原 CLI、输入/输出格式和三份整数配方不变；没有向原片应用测试参数。

减法密度内核（0.8.0）

color_core.subtractive_density_oklch(lch, density=..., strength=...) 推进计划 3.4 的 减法密度像素运算。正 density 让有色像素变深，负 density 让它变亮；C 与原 hue 表示不变。 黑白端点、恰好中性、density=0 或 strength=0 保持原坐标，返回独立 float64 数组。 参数全部必填，没有默认摄影配方。density 是每单位 OkLCh 色度对应的亮度 log-odds 减量， strength 为 [0,1]；它不代表曝光 EV、测得的胶片光学密度或最终饱和度。

本函数按计划重新实现，数学定义与数值稳定分支见 references/grading-research.md。 历史 0.4.1 原型未找回，未移植其公式或复现其成绩；新公式尚待真实照片与摄影者确认。 20 项新增合成数学测试覆盖正负密度、强度、恒等、端点、色相/色度保持、独立高精度参考、 极端数值、微小负密度不能反向压暗的回归，以及已有色彩路径串接。测试参数不作为已确认配方。 函数尚未接管 CLI，不做肤色识别、RGB 色域映射或量化；保持 C 的同时降低 L 仍可能超出 sRGB。 真实照片、六风格完整配方与端到端验收仍待完成。

sRGB 三角抖动与最终量化（0.9.0）

color_core.quantize_srgb8(encoded, amplitude_lsb=..., seed=...) 补齐计划 3.4 的 编码 sRGB 域三角分布抖动与最终 8-bit 量化。它把已经完成色域处理的浮点 RGB 转成 uint8， 不会接管现有 CLI，不在中间调色阶段提前量化。历史 0.4.1 原型未找回，此函数为重新实现。

amplitude_lsb 和 seed 都必填。幅度以 8-bit 码值为单位，范围 [0,1]，表示三角噪声峰值； 0 表示关闭抖动。没有默认摄影配方，也不把测试幅度当成摄影者已确认的设置。 种子为非负整数，使用独立 PCG64，不影响 NumPy 全局随机状态。 同一输入形状、参数和 NumPy 环境下返回相同像素字节；不承诺任意分块后仍与整图相同。

输入必须是已编码且落在 [0,1] 的 sRGB，包括一 ULP 越界也拒绝，不暗中裁掉调色色域损失。 仅饱和处理由新增噪声引起的端点越界，再最近整数舍入，半整数向上。输入不变、返回独立数组。 开启抖动可使纯黑或纯白向内改变一码；强度零或原图恒等路径须明确使用 amplitude_lsb=0。 不保证端点附近的无偏性，不把抖动当作胶片颗粒，也不凭本测试承诺断层护栏已经通过。

20 项新增合成测试覆盖手算舍入与半码边界、全部 256 个码值恒等、局部随机流、三角分布概率、 幅度和越界拒绝、重复像素字节、只读/非连续输入，以及已有浮点颜色路径串接。 完整套件共 181 项独立测试；重复入口不重复计数。数学夹具不代表真实照片或完整六风格验收。 色域映射、肤色保护、空间纹理、六风格配方与 CLI 集成、真实照片和 LUT 仍待完成。

线性 sRGB 色域映射与占比（0.10.0）

color_core.gamut_map_linear_srgb(linear) 返回映射后的独立 float64 RGB 数组及 QA 字典， 补上计划 3.5 的色域映射像素占比能力，也让已有浮点调色结果可以显式进入最终量化阶段。 它接受有限的线性 sRGB D65 三元组或图像数组，保留所有已在 [0,1] 内的像素。 超色域像素向相同相对亮度 Y 的中性灰收缩，取射线与 sRGB 立方体的首个交点。 Y 超出 [0,1] 时整次调用拒绝，要求上游明确处理明暗，不悄悄改曝光。

这是依据标准亮度系数与几何约束重新实现的工程方法，无默认摄影配方。 历史 0.4.1 原型未找回，未移植或复现其成绩。该方法在浮点误差内保持线性相对亮度与 RGB 色差向量方向，不保证 Oklab L/h 恒定；视觉效果与肤色仍须验证。 解析压缩后的浮点端点修正会单独报告通道样本数与最大修正量，不能把原始越界直接裁掉后报零。

QA 按像素计数，每个像素最多一次，包含一 ULP 的越界。返回 pixels_total、pixels_mapped、 mapped_fraction 及端点修正统计。占比严格大于 10% 时警告，恰为 10% 不警告，阈值来自计划 3.5。 统计只覆盖本次映射，不追溯 ICC 阶段的损失，不生成整项验收通过结论。 该纯数值函数不读写照片、不做 gamma/ICC 隐式转换、不使用随机数、不接管旧 CLI。

21 项新增合成测试使用精确有理数参考、RGB 网格和浮点边界验证映射与占比，完整套件 202 项通过。 测试过程中发现 Fortran/转置图像展平后写入副本、返回数组未映射的问题，补充失败回归后以连续独立 工作数组修复；原断言未削弱。测试材料与参数均非真实照片或已确认配方。 肤色保护、空间纹理、六风格与 CLI 集成、真实照片和 LUT 仍需按计划继续，整个 skill 尚未验收。

显式选区肤色保护（0.11.0）

color_core.protect_skin_oklch(original, graded, skin_mask) 实际限制调色后的颜色， 推进计划 3.3、3.5 的肤色保护能力。输入为对齐的原始与调后 OkLCh，以及调用者明确提供的 布尔选区。保持调后 L 和选区外像素，只限制选区内的色相漂移与色度增加。

阈值直接取计划的 6° 与 1.15 倍，工程实现保守地逐像素限制；不会把所有肤色拉成同一种颜色。 原色度为零时去掉新增染色，色相保持未定义；调后已经去色时不强行上色。空选区明确警告。 无近中性色阈值、肤色推断或检测器，调用者须提供选区依据，不能把合成选区当成人脸检测结果。 返回独立 float64 数组与阶段计数，受影响像素按并集统计，QA 不含整体通过结论。

这是重新实现的限幅方法，未找回或移植历史 0.4.1 原型。21 项合成测试验证手算边界、环形色相、 零色度、选区/亮度保持、非连续数组、重复性及分离色调到量化的串接。测试参数和选区未获确认为 摄影配方，真实肤色、选区边缘与视觉效果仍须验证。本函数不改旧 CLI、不读写照片。 后续色域映射和量化可能再改变色相/色度，必须对最终输出重算护栏；不能用本阶段限幅冒充成片验收。 自动肤色选区、六风格集成、真实照片、完整 QA、card 和 LUT 仍待完成。

线性光高光 bloom（0.12.0）

color_core.bloom_linear_srgb(linear, threshold=..., sigma_fraction=..., truncate=..., strength=...) 实现计划 3.4 的空间 bloom。先按线性 sRGB 相对亮度提取超过阈值的光，再用归一高斯核扩散， 最后把扩散光加回原像素。保留光源本来的 RGB 颜色，不预设暖色染色；模糊半径按当前图像短边计算。

四个参数全部必填，没有默认摄影配方。threshold 为 [0,1] 的线性相对亮度；sigma_fraction 为 (0,1] 的短边比例，代表高斯标准差；truncate 为正的标准差倍数，决定有限核支撑；strength 为 [0,1] 的新增光倍率。核半径向上取整且至少 1 像素，超过短边时拒绝，这是资源限制，不静默缩核。

输入只接受 H×W×3、[0,1] 内的有限线性 sRGB，须先完成明确的颜色归一与色域处理。 输出为独立 float64 数组及阶段统计。零强度或没有超过阈值的像素时精确恒等；使用 reflect101 边界，不循环绕回画面另一端、不混合 RGB 通道、不量化。实际模糊使用本机 OpenCV，不自动安装， 不修改全局 OpenCV 设置。相同环境与参数可重复；分块或不同分辨率不保证相同像素。

新增光可能使输出超过 1，函数保留并逐像素计数、警告，后续必须明确处理亮度；不能直接裁掉 或把它送进拒绝亮度越界的色域映射器来冒充通过。bloom 会改变附近皮肤颜色，最终肤色护栏须重算。 本实现没有红色胶片卤化层光晕、颗粒或暗角，也不恢复源图已丢失的高光。

此方法为重新实现，未找回或移植历史 0.4.1 原型。23 项新增合成测试覆盖独立标量卷积、 亮度阈值、短边缩放、RGB 顺序、边界与有限支撑、零强度、越界不裁切、缺依赖和最终量化串接。 测试参数未获确认为摄影配方，真实照片、视觉效果、六风格与端到端 CLI 仍待验收；原 CLI 不变。 数学定义及证据边界见 references/grading-research.md 的同名一节。

线性光有色边缘光晕（0.13.0）

color_core.halation_linear_srgb 补齐计划 3.4 的另一项空间像素变换。按线性亮度提取高光， 高斯扩散后减去本地高光，只把正的扩散余量按显式 RGB 色彩加回。孤立光源中心保持原值， 周围较暗位置形成有色光晕。均匀亮场保持恒等，避免给整幅图叠加染色雾。

threshold、sigma_fraction、truncate、strength 与 tint_linear_rgb 全部必填。前四项的单位 和资源边界与 bloom 相同；tint_linear_rgb 为三个 [0,1] 内的线性 RGB 通道增益，不归一化， 不把编码 sRGB 数字或测试中的红品色向量当成已确认配方。尺度按当前短边计算。

输出独立 float64 数组及阶段 QA。零强度、零 tint、均匀高光提取图精确恒等；越过 1 的输出 保留并按像素计数，要求后续明确处理亮度和色域。采用本机 OpenCV 的 reflect101 高斯卷积， 不安装依赖、不读写照片、不改全局状态。缺少依赖时仅实际需要模糊的路径报错。

这是按计划重新实现的工程效果，未移植历史 0.4.1 原型，也未模拟真实胶片层或复现其评分。 23 项合成测试覆盖独立标量卷积、手算邻域、色彩增益、光源中心、恒等、边界、资源限制、 重复性与 bloom 到最终量化的串接。测试参数未经摄影者确认为配方，真实夜景和肤色待验收。

该变换不能写进逐像素 LUT；最终肤色与剪切必须重新检查。旧 CLI 保持不变，颗粒、暗角、 六风格配方、CLI 集成、card/LUT、16 位和真实成片仍待按计划推进。详细公式见调色研究参考。

线性光单色颗粒（0.14.0）

color_core.grain_linear_srgb 实现计划 3.4 的空间颗粒。使用显式种子的单色随机场，按当前 短边比例作高斯相关，再以同一个增益乘在线性 RGB 三通道上。只平滑噪声，不模糊原照片。 黑色与零通道保持零，RGB 通道比例在浮点误差内保持；亮度与绝对色度仍会改变。

amount、sigma_fraction、truncate、strength、seed 全部必填。amount 为 [0,1] 的平滑前 相对增益最大偏移，strength 为 [0,1] 倍率；amount 不代表平滑后的 RMS、EV 或量化码值。 高斯 σ 按短边计算，支撑与 bloom 相同。增大 σ 会降低实际噪声方差，不自动重新归一强度。 局部 PCG64 随机流不改变 NumPy 全局状态；相同形状、值、参数及依赖环境得到相同像素字节。 分块、不同分辨率或不同依赖版本不保证同字节，随机空间纹理不能装进逐像素 .cube。

输入为 H×W×3、[0,1] 的有限线性 sRGB。返回独立 float64 数组与阶段 QA，统计变化、变亮、 变暗和超过 1 的像素，每个像素只计一次。零 amount、零 strength 或全黑精确恒等；参数仍 全部验证，不生成噪声或导入 OpenCV。实际需要模糊而缺 OpenCV 时拒绝，不自动安装。 输出超过 1 时保留并警告，后续须明确处理亮度，再重算成片肤色和剪切，不能裁掉后报通过。

本方法为重新实现的工程纹理，未移植历史 0.4.1 原型，不模拟胶片乳剂，也未获真实照片 视觉确认。25 项新增测试采用明确标注的合成输入和参数，只验证像素数学、随机流、边界和 最终量化串接。测试设置未经摄影者确认为配方；此处不提供默认六风格参数。 旧 CLI 仍不加颗粒，暗角、自动肤色选区、六风格与 CLI 集成、完整 QA、card/LUT、16 位及 真实照片验收仍待完成。数学定义、参数来源与限制见调色研究参考的同名一节。

触发与分流

适用：“把这张照片调成电影感”“想要低饱和、暖亮部、冷暗部”“保留原片，给我一个可复现的调色版”。

• 只写图注：photo-caption-writer；加 EXIF 信息带：photo-exif-frame。
• 排多张成组：photo-series-layout；拼出版式跨页：photo-spread-composer。
• 社交尺寸、压缩、PPI、冲印 ICC 等交付准备不在本增量内。photo-export-prep 尚在开发队列，不能声称已可调用。
• RAW、HEIC、HDR、16-bit、CMYK、透明图、调色后输出某个打印机色域：停止，要求先由合适的色彩管理工具导出一份 新的 8-bit SDR sRGB JPEG/PNG。不要覆盖或强制改标签。

开始前：只问会改变输出的内容

1. 确认有权处理的原图、输出位置与用途，是否为需要忠实色彩的记录、产品、艺术品或新闻图片。此类图片先建议 neutral，不默认风格化。
2. 摄影者想要的方向，以及必须保持的颜色（肤色、衣服、品牌色等）。没有回答时先提议 warm-muted、强度 60，而不是当作已确认。
3. 是否已转成 SDR sRGB、有没有 ICC。没有 ICC 就追问，不能为了让脚本跑通擅加 --assume-srgb。 有 ICC 时总是实际转换，坏 ICC 必须拒绝，不允许改为“假定 sRGB”继续。

不从照片推断人的身份、真实情绪、地点或拍摄动机。处理只在本地；不得为分析或调色而上传照片。

运行条件

Python 3.10+、Pillow 11.3+（含 LittleCMS；已实测 Pillow 11.3.0 / LittleCMS 2.17）。 本增量不自动安装依赖或调用云端服务。运行前检查运行环境；缺依赖就说明未执行，按用户授权在合适环境补齐后再试。

只接受不超过 64 MiB、2400 万像素的单帧、8-bit、不透明 RGB/L JPEG/PNG。 这是避免内存与运行时间失控的工程上限，不是画质门槛。 拒绝 palette、alpha/tRNS、多帧、PNG 高位深及 cICP/HDR 信号，不静默降位深或丢透明层。 JPEG HDR/增益图没有全面自动识别能力，输入必须由用户确认为 SDR。

在 skill 目录下执行；路径由用户指定，不要扫描整个人的照片库：

python3 scripts/cinegrade.py --help
python3 scripts/cinegrade.py looks

# 有有效嵌入 ICC 的原图：run-warm-01 必须不存在，父目录必须已存在。
python3 scripts/cinegrade.py render source.jpg \
  --output run-warm-01 --look warm-muted --strength 60

# 仅在用户明确确认无 ICC 的输入确实是 sRGB 后：
python3 scripts/cinegrade.py render source.png \
  --output run-neutral-01 --look neutral --strength 0 --assume-srgb

render 输出目录中只有：

• render.png：EXIF 转正后的原分辨率、不透明 8-bit RGB、嵌入 sRGB ICC；不复制来源 EXIF、XMP、GPS、文本或缩略图。
• report.json：完整性收据与数值 QA，最后写入。包括输入内容 SHA-256、尺寸、原 Orientation、ICC 处理动作/散列、技术 EXIF 白名单、配方与强度、输出像素/文件散列、依赖版本。

边车白名单只有曝光秒数、f-number、ISO、焦距；缺失就省略，不补造。不保存原始路径、原文件名、GPS、拍摄时间、相机/镜头型号、设备序列号、作者、原始 ICC 文本或完整 EXIF。 内容散列和技术参数仍可关联原片，边车默认私用；对外分享前询问是否需要附带。 去掉元数据不等于视觉匿名，画面内的人脸、地址、车牌等仍需人工检查。

输出必须是一个全新的目录；已有文件、空目录、链接都拒绝，不提供 --force。 脚本先在内存中完成解码、调色、编码，再原子占用新目录。写盘失败可能留部分文件，保留现场，用新目录重试；不要删旧目录或改写原片。 只有命令有可靠的成功退出记录，同时 report.json 可解析、status 为 complete 且每个输出的 png_sha256 与实际文件一致才视为完成（render/compare 检查 output；candidates 检查 candidates 中全部三项；compare 另按 panels 的矩形裁出两幅核验像素散列）。退出码 0 为成功，2 为输入/写盘拒绝；未通过时不能宣称已交付。

候选小样：先看方向，不自动选片

用户同意比较方向后，运行 candidates。源图的权限、SDR、ICC 与隐私要求和 render 完全相同； 没有 ICC 仍要先确认，不为了生成小样绕过颜色管理。忠实色彩用途仍优先中性，不默认推荐风格化。

# 有有效嵌入 ICC 的原图；run-candidates-01 必须不存在。
python3 scripts/cinegrade.py candidates source.jpg --output run-candidates-01

# 可显式改变两个风格共同的强度和预览长边；不会放大原图。
python3 scripts/cinegrade.py candidates source.jpg \
  --output run-candidates-02 --strength 40 --max-edge 768

固定顺序与文件名，不由图像内容或模型随机决定：

文件	配方	强度
01-neutral.png	neutral	永远 0，作为小样尺寸的中性基线
02-warm-muted.png	warm-muted	--strength，默认 60
03-cool-muted.png	cool-muted	同上

• 一次读取输入快照，一次 EXIF 转正/ICC 归一；先缩小，再将同一份小样像素送入三份配方。
• --max-edge 为 1..2048 整数，默认 1024。长边不超过该值；较小图片不放大、不裁切。 缩小时每条边按 max(1, floor((原边长 × max_edge + floor(原长边/2)) / 原长边)) 求整， 即最近整数、半整数向上、至少 1 像素。比例只受整像素取整影响，极细长图片可能有较明显的取整偏差。
• 缩放固定用 Pillow LANCZOS，reducing_gap=None，在编码 sRGB 上执行；不是线性光缩放。 报告记录处理顺序、缩放参数与实际尺寸；未缩放时 resampling 为 none。
• --strength 为 0..100 整数，只作用于两个风格。设为 0 时三张小样像素相同，仍保留固定三项，不冒充三种不同效果。
• 三张 PNG 都重新嵌入 sRGB ICC，不复制来源元数据；所有图像编码完成后才占用一个全新目录。 最后写入唯一 report.json：输入溯源、缩放契约、逐张完整配方/强度、文件与像素散列、依赖版本及数值 QA。 任一写入失败，保留部分文件，不宣称完成、不补写收据、不重用目录。
• 顶层 qa.before 对应缩放后、调色前基线，各候选 qa.after 与越界计数只针对该小样。 selection.automatic_selection=false、selected_look=null：脚本没有选择赢家。

小样不是最终交付图。 先缩后调与先全尺寸调色再缩小的像素一般不同，不能承诺两者散列相同。 小样 QA 不能证明全尺寸高光/暗部细节、肤色或色带已通过。请摄影者明确选择配方和强度，再对原始输入 运行 render 到另一个新目录并做全尺寸 QA；不要把候选 PNG 当原片再次调色，也不要直接放大小样交付。 显示环境不可用时，如实写“已生成三张候选，视觉未验收”，不代用户选定或声称好看。 本命令只输出独立 PNG 与收据，不生成拼卡、滑块对比、LUT，也不扩展到社交/冲印导出。

前后对比：原尺寸像素并排

摄影者已选定方向与强度后，使用原始输入运行 compare。这一步对应计划 3.2 的前后对比交付。 本版从现有安全读写和调色函数重新实现，没有移植历史 0.4.1 原型的对比排版，也没有复现其视觉评分。

python3 scripts/cinegrade.py compare source.jpg \
  --output run-compare-01 --look warm-muted --strength 60

--look 与 --strength 都必填，不隐式替摄影者选定方向。无 ICC 时仍须先确认，才能加 --assume-srgb。

• 输出 compare.png 与 report.json，目录必须全新。只读一次原片快照，先转正并归一 sRGB，再调色。
• 左边为归一后的原图，右边为同一原图的调色结果。每幅保持 W×H，整图为 2W×H。 不缩放、不放大、不裁切、不加间隔或文字，不需要系统字体。左右含义写在收据与交付说明中。
• 右边与同一输入快照、配方、强度及解码/ICC 环境下 render 的输出像素逐字节一致。 左边用于隔离创意调色的差别，无法展示 ICC 转换之前的宽色域源像素。
• 收据 panels 按 before、after 排列，逐项给出 box_xywh（左上 x、y、宽、高）及像素 SHA-256； output 记录整图的像素与文件散列。比较的是像素，PNG 文件字节不作跨运行恒等保证。
• qa.scope=full_resolution_panels。before/after 端点计数、通道样本数各按一幅原尺寸图计算， 不把两幅重复计数。完整配方与现有护栏限制保留。
• 复用隐私白名单、ICC 编码、全新目录占用和最终收据发布。编码先于写盘；失败保留现场。 对比图最多为输入像素上限的两倍，内存用量高于单幅 render。查看器可能自动缩小，请按 1:1 检查细节。

此版本是无装饰的像素对比，不提供 2.39:1 剧照卡、中文标题或滑块。合成像素测试用于检查结构和对应关系， 不能据此宣称真实照片肤色、电影感或整项 skill 验收通过。

调色契约

配方在 references/look-library.json，选择说明见 references/look-library.md。

1. 对输入读一次快照；内容散列与解码使用同一批字节。
2. 应用 EXIF Orientation，绝不通过丢 EXIF 假装转正。
3. 嵌入 ICC → LittleCMS 相对色度转换到 sRGB，无隐式感知映射；无 ICC 必须显式确认 sRGB。带冲突 gamma/chromaticity 的未标记 PNG 拒绝。
4. 在编码 sRGB 值上做整数分段曲线 → 冷暖偏移 → 饱和度 → 钳位 → 与原像素按强度混合。顺序固定，不使用随机数、生成模型、外部网络或隐式自动增强。
5. neutral 对归一后的像素恒等；任何配方强度 0 也恒等。注意“归一后恒等”不等于保留 JPEG 字节、宽色域源像素或 EXIF 旋转前的排列。

确定性承诺是：同一解码/ICC 环境、同一输入、配方与强度，输出像素一致。 跨 Pillow/LittleCMS 版本可能不同；PNG 文件字节不作跨运行恒等承诺（ICC/编码器可能变化）。报告记录环境及实际散列。 本变换不是线性光处理、胶片物理仿真或特定电影的精确复刻，8-bit 调色有色带风险。 具体数学与规范参考见 references/grading-research.md，其中工程参数与来源规则明确分开。

QA 与交付

脚本自动报告：

• 输入与输出每个通道处在 0 / 255 的像素数；以及总像素数。
• 满强度配方在最终钳位之前超出 0..255 的通道样本数。强度 0 不执行配方，此项为 0；其他强度时这个数反映满强度配方，不是实际输出的剪切像素数。
• 明确要求人工检查的项目及数值警告。

端点数不是“已剪切”的证明，也不是“细节完好”的证明；真正的细节可能在相机或 ICC 归一时已经丢失。 数值 QA 不检测宽色域源的色域损失，不会判断肤色自然、审美成功、印刷可用或屏幕颜色准确。

交付前在能显示图像的环境中检查：肤色与记忆色、云/灯的高光细节、暗部层次、平滑渐变色带。不能查看图像时，只报告“脚本与数值已检查，视觉未验收”，不评价好看与否。 如果用户认为太强，保留当前结果，降低强度写入另一个新目录，不覆盖上一版。

简短交付单：

• 用途与用户确认的方向；配方 / 强度。
• ICC 处理动作、是否用了明确的 sRGB 假设。
• 新输出图与边车；原片未改写。
• QA 警告、实际完成的视觉检查、未验证项。

测试

PYTHONDONTWRITEBYTECODE=1 python3 scripts/cinegrade.py --selftest
PYTHONDONTWRITEBYTECODE=1 python3 scripts/image_io.py --selftest
PYTHONDONTWRITEBYTECODE=1 python3 scripts/test_cinegrade.py

测试只使用合成小图、合成数学网格与可核对的标准色彩向量，临时文件局限本 skill 的 scripts/ 内，结束清理自己创建的夹具；不读取真实照片、系统字体或其他技能。 交互验收场景位于仓库的 tests/cases/photo-cinematic-grade.md。 实测范围是合成 RGB/L、sRGB ICC 与模拟 ICC 调用；真实 Display P3/Adobe RGB 照片与跨平台视觉验收尚未完成。

后续验收顺序

以下为本 skill 尚未完成的功能；实际开发顺序以每轮同步后只读的 AUDIT-AND-IDEAS.md 时间表为准，不在本文件固定全仓项目顺序：

1. card 与对应可视校验，复用已完成的候选参数和像素收据；compare 已具备无装饰的原尺寸并排输出。
2. 再做 lut、LUT 与 render 数值对账、综合色彩/隐私/QA 验收。

变更记录

版本	日期	变更	类型
0.14.0	2026-10-16	新增显式种子线性光单色颗粒、短边高斯相关、增益与超范围阶段 QA；25 项合成测试，旧 CLI 和真实照片未接管或验收	minor
0.13.0	2026-10-16	新增显式参数线性光有色边缘光晕、短边高斯正余量与阶段 QA；23 项合成测试，原 CLI 与真实效果仍待集成验收	minor
0.12.0	2026-10-14	新增显式参数线性光高光 bloom、短边高斯扩散、超范围保留与统计；23 项合成测试，原 CLI 与真实效果仍待集成验收	minor
0.11.0	2026-10-14	新增显式布尔选区 OkLCh 肤色保护，按计划 6°/1.15 倍限幅、保持调后亮度及选区外像素；21 项合成测试，自动选区与成片验收待完成	minor
0.10.0	2026-10-13	新增保持线性相对亮度的 sRGB 色域映射、逐像素占比与 >10% 警告、21 项合成测试；修复非连续图像写回，CLI 与真实效果待集成验收	minor
0.9.0	2026-10-13	新增编码 sRGB 三角抖动与最终 RGB8 量化、显式幅度/种子、20 项合成测试；CLI 未切换，真实断层与六风格待验收	minor
0.8.0	2026-10-13	新增 OkLCh 减法密度，显式正负密度与强度、端点/中性保持、20 项合成测试及微小负密度舍入修复；CLI 与配方未切换，真实效果待验收	minor
0.7.0	2026-10-12	新增 Oklab 分离色调，暗部/亮部独立色相与色度增量、端点平滑包络、20 项合成测试；CLI 与配方未切换，真实效果待验收	minor
0.6.0	2026-10-10	新增 OkLCh 环形分色相调色，显式窗口/转角/色度/强度、21 项合成测试；保持既有 CLI，真实效果与六风格待验收	minor
0.5.0	2026-10-10	新增高光色度滚降浮点阶段，显式起点/强度、保持亮度与色相、16 项合成测试；CLI 与配方未切换，真实效果待验收	minor
0.4.0	2026-10-09	新增 float64 sRGB/Oklab/OkLCh 内核及端点固定亮度曲线，新增 22 项数学测试；未接管 CLI、未复现历史原型或完成六风格视觉验收	minor
0.3.0	2026-10-08	新增 compare：显式配方/强度、原尺寸左右像素对账、单幅 QA 计数、隐私与失败保护；新增 13 项合成测试；核心六风格管线及真实效果仍未验收	minor
0.2.0	2026-10-07	新增 candidates 固定三选小样：一次颜色归一、确定性限边缩放、逐图配方/散列/QA、整组新目录保护及隐私/失败测试；card/compare/lut 仍待实现	minor
0.1.0	2026-10-07	首个独立增量：确定性 render、三份基础配方、安全 I/O、技术 EXIF 白名单边车与数值 QA；小样/card/compare/lut 待后续	minor

收据发布与文件系统边界

PNG 写完后，先将报告写为 .report.pending，成功 flush/fsync/close 后，以同目录硬链接、不覆盖的方式发布 report.json。此前任一步失败均保留现场，不发布最终收据。若文件系统不支持硬链接则安全失败，不改用会覆盖目标的发布方式。发布成功后尝试移除临时别名；此可选清理失败时可能多留 .report.pending，但最终收据与本次 PNG 仍有效。

只在可信、不会被其他进程并发替换的输出父目录运行；这不是恶意路径替换防护，也不承诺任意断电后的目录持久性。恢复时必须同时核对成功退出、最终收据和全部输出散列，不能凭孤立的 complete 字段判定成功。