企业官网建设流程全解析

HyperFrames 媒体技能 LUT 库解析：Agent 按需解析的调色 Look 目录与.cube托管指南

【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes

skills/media-use/luts/是 HyperFrames 的 media-use 技能中面向 Agent 的调色 Look 目录（LUT library），它以index.json为唯一入口，通过「CDNurl按需下载」与「params参数化确定性生成」双通道解析，把调色外观（color-grade look）冻结成本地经过校验的.cube文件。阅读本文后，你将掌握该 LUT 库的条目数据模型、buildCube参数化生成原理、下载/校验/原子落盘的解析管线，以及作为运维者托管新 Look 的完整 S3 上传流程，并能在自己的 HyperFrames 项目中用resolve命令实际消费这些 Look。

设计动机：Agent 可消费、仓库零体积的调色目录

传统做法是把每一个 Look 的.cube文件直接提交进仓库。HyperFrames 的 LUT 库反其道而行——luts/index.json 才是唯一被提交的内容，它充当供 Agent 消费的调色外观目录（agent-consumed catalog），而所有.cube文件体都不落库：

• 每个条目携带匹配元数据与应用元数据（id、description、tags、intensity）；
• 条目可选择携带一个托管的url（指向 CDN 上的.cube），在解析时（resolve time）才下载、校验并冻结到本地，行为与 BGM/图片资产完全一致；
• 条目也可选择携带params，这是一份确定性的buildCube参数规格，用于离线（--local-only）场景，或当url下载/校验失败时作为兜底。

目录头部的notes字段（skills/media-use/luts/index.json）直接说明了这一契约："No .cube bodies are committed."。这意味着仓库始终轻量、可审计，而真实调色数据只存在于解析产物（.media/luts/）与远端 CDN 中。

index.json 条目结构：id/description/tags/intensity/url/params

每个 Look 条目（skills/media-use/luts/index.json）由以下字段组成：

约束很明确：一个条目必须至少提供url或params之一；理想情况是两者都给——CDNurl优先，params兜底，这样解析永远不会被网络阻塞。解析器在读取目录时（lut-preset-provider.mjs 的readBundledLutIndex）会对字段做防御性归一化：params必须是对象、url会被 trim、intensity非有限数字时回退为 1。

三个内置 Look 的完整规格

当前目录内置了三个可开箱即用的 Look，其params直接展示了参数化调色的表达能力：

teal-orange-blockbuster（青橙电影感，intensity: 0.85）——典型的分区调色（split tone）：

{ "contrast": 0.18, "saturation": 0.08, "vibrance": 0.12, "splitTone": { "intensity": 0.62, "balance": 0.52, "shadows": [-0.04, 0.05, 0.09], "highlights": [0.1, 0.04, -0.03] } }

bleach-bypass（漂白工艺，intensity: 0.8）——高对比、强去饱和：

{ "blacks": 0.04, "shadows": -0.08, "highlights": 0.08, "whites": 0.18, "contrast": 0.55, "temperature": -0.02, "saturation": -0.72, "vibrance": -0.25 }

film-fade（胶片褪色，intensity: 0.75）——提黑、暖调、柔化：

{ "blacks": 0.35, "shadows": 0.18, "highlights": 0.02, "whites": -0.03, "contrast": -0.28, "temperature": 0.16, "saturation": -0.12, "vibrance": -0.08 }

双通道解析管线：CDN 优先、params 兜底、绝不阻塞于网络

解析的核心实现是 lut-preset-provider.mjs 中的freezeLibraryLut，它完整实现了「url → params → 报错」的降级链：

1. CDN 通道（url+ 非--local-only）：先用freezeUrl把远端.cube下载到私有临时目录，随后通过assertValidCubeFile校验；只有校验通过的立方体才会被renameSync原子性地重命名到最终路径.media/luts/<id>.cube。注释解释了这一设计的动机：即使进程在写入与校验之间被 SIGKILL/OOM 杀死，也不会在最终路径留下未校验的孤儿.cube。
2. params 兜底通道：当url缺失、显式离线（localOnly: true），或下载/校验抛出异常且条目携带params时，调用buildCube(match.params)生成立方体文本，先写.tmp再校验、再原子改名，provenance.via会如实标记为"params-fallback"（有 url 但回退）或"params"（本来就无 url）。
3. 离线且仅 url 的条目：抛出带MEDIA_USE_LIBRARY_LUT_OFFLINE错误码（lut-preset-provider.mjs）的offlineLibraryMiss，调用方（如 resolve.mjs）通过isLibraryLutOfflineMiss识别后转为清晰的 miss 提示，而不是静默失败。

这一降级链在 lut-preset-provider.test.mjs 中有直接测试佐证：localOnly: true时teal orange blockbuster走 params 通道并冻结出可通过validateCubeFile的.cube、provenance.via === "params-fallback"（第 59-75 行）；而仅 url 的条目在localOnly下会抛--local-only相关错误且fetch调用次数为 0（第 107-132 行）。

buildCube：确定性参数化 LUT 生成器

当走 params 通道时，cube-build.mjs 的buildCube(params, size)会在内存中生成标准 ASCII.cube文本：TITLE "media-use parametric grade"、DOMAIN_MIN 0 0 0、DOMAIN_MAX 1 1 1、LUT_3D_SIZE <size>，随后按 B→G→R 三重循环枚举size³个采样点，对每个归一化坐标运行applyParams（cube-build.mjs）输出三通道值（保留 6 位小数）。

关键约束与特性：

• 默认尺寸为 33（33³ ≈ 35,937 行），上限 64；size必须是 2~64 的整数，否则抛错；
• 输出是完全确定性的：同一份params两次调用产生字节级相同的结果（测试见 cube-build.test.mjs）；
• 全零参数近似单位 LUT（identity），测试用 3³ 立方体逐点断言误差小于 1e-6（cube-build.test.mjs）。

参数语义与底层实现

applyParams依次串接六个处理阶段，每个阶段的参数都有明确的取值范围（越界会被 clamp）：

此外，paramsFromIntent 支持从自然语言意图直接生成初始参数：例如出现warm/golden/sunlit映射temperature: 0.18，cinematic/film/movie映射contrast: 0.08 + saturation: 0.04，punchy/contrast/dramatic推高 contrast，vibrant/colorful提升 saturation 与 vibrance 等；零命中时返回null（测试见 cube-build.test.mjs）。需要强调的是，grading.md 明确指出：参数化数学无法复现真实胶片质感或乳剂转换，这类需求应使用 CDN 扫描.cube条目或通过--from摄入真实扫描文件。

.cube校验规则：解析器与核心的防漂移镜像

所有进入.media/luts/的立方体——无论来自下载还是buildCube生成——都必须通过 cube-validate.mjs 的严格校验（assertValidCubeText/assertValidCubeFile）。该文件自称是 packages/core/src/colorLuts.ts 的独立镜像（media-use 运行时无法直接 import TypeScript 源码），其测试用例镜像了核心解析器，以捕捉可接受.cube集合的漂移。核心规则包括：

• 支持TITLE、DOMAIN_MIN/DOMAIN_MAX、LUT_3D_INPUT_RANGE、LUT_3D_SIZE关键字，忽略注释（引号感知的#剥离）与 BOM；
• LUT_3D_SIZE必须是大于 1 的整数且不超过DEFAULT_MAX_CUBE_LUT_SIZE = 64（cube-validate.mjs）；
• 数据行必须恰好三个有限数字，行数必须精确等于size³（cube-validate.mjs）；
• 当前不支持 1D cube 与混合 1D/3D，遇到会明确报错。

它也可作为独立命令行工具使用：node skills/media-use/scripts/lib/cube-validate.mjs <file.cube>会输出一行ok: LUT_3D_SIZE <size>或带行号的错误信息。

匹配机制：预设优先、词元重叠打分

matchColorLook(intent)（lut-preset-provider.mjs）负责把一段调色意图解析成具体 Look：

1. 若意图恰好等于 18 个内置预设之一（如neutral、warm-daylight、vhs-playback、home-movie-8mm等，见 lut-preset-provider.mjs），直接以 99 分命中；
2. 否则把「预设 + 各自同义词表」与「库内 Look 条目（id/description/tags 拼接文本）」合并成候选集，用tokenOverlap计算词元重叠分数，过滤掉分数 < 2 的候选，按分数降序（同分按原顺序）取最优；
3. 零重叠的意图返回null（测试断言"zqxv imaginary neutron look"无匹配，lut-preset-provider.test.mjs）。

测试还保证了解析器声明的每个预设都真实存在于核心的colorGrading.ts中，且index.json的每个条目都满足「params 或 url 至少其一」且params生成结果可通过校验（lut-preset-provider.test.mjs）。

在项目中消费 LUT 库

通过 media-use 的resolve命令即可按意图消费库内 Look（详见 SKILL.md 与 grading.md）：

# 作为 grade 解析（附带>aws s3 cp <id>.cube s3://heygen-public/luts/<id>.cube

上传后即通过 CloudFront 在https://static.heygen.ai/luts/<id>.cube对外提供服务；

新增条目后，目录的notes字段也可同步说明新 Look 的来源与解析方式。核心红线始终是：不要把.cube文件体提交进仓库——解析器会在冻结时实时完成下载/生成与校验。

小结

HyperFrames 的 LUT 库用一份轻量index.json完成了「Agent 可检索、可匹配、可离线兜底」的调色资产治理：buildCube提供确定性的参数化生成，freezeLibraryLut提供 CDN 优先的原子化冻结，cube-validate提供与核心解析器对齐的严格校验，三者共同保证了无论在线还是离线，解析都不会被网络阻塞，且provenance.via永远诚实记录 Look 的来源通道。对开发 Agent 工作流的团队而言，这是一个可直接借鉴的「元数据即目录、数据按需物化」的资产分发范式。

【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes