shader-gen

着色器生成器

如果 submit_shader 或 inspect_item 尚未加载，请先使用 ToolSearch 加载它们，再调用；这样就能使用它们的实际参数，而不是猜测。

仅负责提交：创建后端生成任务并返回 jobId。提交后，使用 track_progress 工具跟踪任务生命周期。

生成新的着色器时，始终使用 generate.ts。 仅在编辑现有资源代码时手动编写——生成失败时绝不能将手动编写作为兜底方案。

优先查找目录——生成前先尝试使用现有资源

生成着色器前，请调用 browse_library，除非用户指定的确切资源 ID 已在 browse_assets 中可见。

browse_library 是内置效果、内置转场以及项目效果／转场资源的权威来源。内置资源使用稳定的全局资源 ID，而非项目专属的数据库资源，因此它们可能不会出现在 browse_assets 中。

使用 edit_item 应用目录条目，不要调用 submit_shader。

适合目录搜索的示例：

browse_library(query: "zoom")
browse_library(category: "transitions", query: "dissolve")
browse_library(category: "audio-fx")

只有当目录中没有与用户意图足够匹配的条目时，才生成着色器。

builtin:zoom 与所有效果一样，使用绑定到轨道的位置

效果始终具有时间线几何信息。对于整段片段的效果，请提供 targetItemId；ChatCut 会将其解析为锚定到片段且覆盖整段片段的范围。对于明确指定的时间线范围，请提供 trackId + trackBoundFrom + trackBoundDurationInFrames。

# Zoom on the entire video clip
edit_item(json: '{"adds":[{"type":"effect","assetId":"builtin:zoom","targetItemId":"<clip-id>","propertyOverrides":{"magnification":1.5,"shape":"hold"}}]}')

# Zoom on a sub-range of the clip (e.g. frames 90–150 only, a punch zoom on a beat)
edit_item(json: '{"adds":[{"type":"effect","assetId":"builtin:zoom","mode":"track-bound","trackId":"<trackId>","trackBoundFrom":90,"trackBoundDurationInFrames":60,"propertyOverrides":{"magnification":2,"shape":"punch"}}]}')

使用 preview_timeline({views:["timeline"],tracks:["V1"]}) 获取轨道项目 ID 和时间线帧范围。需要精确的项目详情时，使用 inspect_item({itemId:"..."})。

键	类型	范围／取值	默认值	说明
magnification	number	1–4	1.5	缩放倍数；1 = 不缩放，2 = 放大 2 倍
focalPointX	number	0–1	0.5	水平焦点（0 = 左侧，1 = 右侧）
focalPointY	number	0–1	0.5	垂直焦点（0 = 顶部，1 = 底部）
shape	select	punch / hold / slow-push / instant	hold	动画曲线
focalMode	select	auto / manual	auto	auto 选择主体；manual 使用 focalPoint
easeInFrames	number	0–60	8	渐入帧数
easeOutFrames	number	0–60	8	渐出帧数

默认缩放时，完全省略 propertyOverrides。只发送需要更改的键——采用补丁语义。

锚定到片段与调整轨道

效果项目有两种放置方式，且都具有明确的时间范围：

• 锚定到片段：为整段片段提供 targetItemId，或指定与片段相交的明确范围。存储的范围相对于该片段，因此片段移动时，范围也会随之移动。
• 调整轨道：为覆盖轨道空白区域的范围提供 trackId + trackBoundFrom + trackBoundDurationInFrames。该范围在时间线上为绝对位置。

整段片段的效果使用 targetItemId。只有当所需范围与片段的完整时长不同时，才指定明确的轨道几何信息。

内置 LUT 属性

edit_item(json: '{"adds":[{"type":"effect","targetItemId":"<clip-id>","assetId":"builtin:slog3-s709","propertyOverrides":{"intensity":1}}]}')

键	类型	范围	默认值	说明
intensity	number	0–1	1	LUT 强度；1 = 完全应用

要替换：删除该效果，然后使用不同的 assetId 重新添加。要移除：删除该效果项。

用户上传的 .cube LUT 资源格式完全相同，只有 assetId 不同。请参阅下方的“应用现有 LUT 资源”。

支持的目标

效果和转场可应用于 video、image 和 gif 项目。

类型路由

生成任何内容之前，先检查以下两个非生成路径：

1. 目录条目 — 使用 browse_library 查找内置效果、转场和项目效果、转场。
2. 项目库中已存在的用户上传 .cube LUT 资源 — 绑定该资源，而不是生成。请参阅下方的“应用现有 LUT 资源”。它会在 browse_assets 中显示为 type: effect，且 editableProperties 中包含 lut 类型条目。

用户需求	--type
视频外观（颜色、模糊、辉光、颗粒、扭曲）	effect
调色 / 风格（青橙色调、电影感、复古、LUT 风格）	effect
可见性控制（遮罩、显现、擦除、形状裁切、渐变淡化）	effect
在片段之间混合（交叉淡化、溶解、滑动、3D 立方体 / 翻页）	transition

表格中的“LUT 风格”是指生成类似 LUT 的全新 GLSL 调色效果——仅在用户想要新效果时才这样做。如果他们想应用库中已有的 .cube 文件，不要生成；应改为绑定现有资源。

生成路径没有单独的 LUT 或遮罩生成器——它们都属于 effect。

应用现有 LUT 资源

默认目标是时间线。“应用此 LUT”表示在片段上添加 edit_item 效果。只有当用户要求在资源出现的所有位置应用到源资源本身时，才使用 edit_asset sourceLut——例如从该资源剪辑出的每个片段，或将素材从 log 规范化为 Rec.709，因为这会更改每条时间线上的该资源实例。

用户上传的 .cube 文件会成为**category: "lut" 的效果资源**。将其应用到片段不属于生成——其 edit_item 效果格式与内置 LUT 完全相同，只需将该资源自己的 ID 设为 assetId：

edit_item(json: '{"adds":[{"type":"effect","targetItemId":"<clip-id>","assetId":"<lut-effect-asset-id>","propertyOverrides":{"intensity":1}}]}')

要点：

• assetId 是 LUT 效果资源的真实 ID。不存在字面值 "lut" 作为 assetId，也不存在嵌套在 propertyOverrides 中的 LUT 绑定。
• propertyOverrides 仅包含 intensity（0–1，默认值为 1）。.cube 绑定存储在资源上，而不是效果项上。
• 使用 browse_assets type:"effect" 查找 ID：editableProperties 中包含 lut 类型键的资源就是 LUT 资源。内置 LUT 可通过 browse_library category:"luts" 获取。
• targetItemType 默认为 video；也支持 image、gif。
• 要替换：删除该效果，然后使用另一个 LUT 的 assetId 重新添加。要移除：删除该效果项。
• 如果要对源片段的所有出现位置进行调色，而不是只调色时间线中的某个项目，请对 video/image/gif 资源使用 edit_asset 更新，并传入 {"sourceLut":{"assetId":"<lut-effect-asset-id>"}}；传入 {"sourceLut":null} 可移除该设置。
• 如果项目中尚无该 .cube 文件，则无法通过此界面导入：此界面没有 LUT 导入路径，.cube 也不是可接受的聊天附件，因此绝不要要求用户发送文件。请他们将文件拖入编辑器的媒体池；编辑器会将其注册为 LUT 资源，随后便会显示在 browse_assets 中。不要告诉他们 ChatCut 无法处理 .cube；编辑器可以处理。

此路径不要调用 submit_shader。

应用后，使用 preview_timeline 确认该效果已列在目标片段的轨道上。不要仅根据 edit_item 的响应报告成功。

用法

调用 submit_shader 前，用一句具体的话重述用户的意图，然后立即继续。track_progress 返回后，用一行说明生成了什么——不要询问“保留还是重新生成？”。

submit_shader({
  type: "effect",
  prompt: "Chromatic aberration with RGB split",
  name: "Chromatic Aberration",
});

submit_shader({
  type: "transition",
  prompt: "Smooth crossfade with soft edge",
  name: "Crossfade",
});

submit_shader({
  type: "effect",
  prompt: "Cinematic teal-orange color grade",
});

submit_shader({
  type: "effect",
  prompt: "Stronger version",
  referenceAssetIds: ["effect_asset_id"],
});

策略

• 提交后停止。告知用户任务已创建。
• 提交后使用 track_progress 工具查看状态或等待。
• 生成始终会创建一个库资源——不要因为时间线尚未就绪而拒绝。
• 应用是独立且可选的。 只有在用户明确提出要求（“加到视频”“apply”“用到第一段”）时才应用。意图不明确时，默认仅添加到库中。

编辑现有属性

每当你准备编辑 shader asset.properties、已应用效果/转场的 item.propertyOverrides，或提升硬编码的 shader 值时，都要先阅读 references/property-changes.md。

该文档再次强调，shader properties 是一个数组，但允许的 shader 属性类型仅有 number、boolean、color、select 和 vec2。动态图形属性也使用数组，但类型集合不同。

参数

参数	说明	默认值
type	"effect" 或 "transition"（必填）	—
prompt	shader 的描述（必填）	—
name	在库中显示的资源名称	—
referenceAssetIds	资源 ID。图像 ID → 模型会参考其视觉风格。效果/转场 ID → 将其代码用作风格锚点（每次提交最多 1 个，且类型必须与 type 匹配）。	—

输出

返回 { success, job: { jobId, status }, manage: { status, wait, watch }}。

应用到时间线

仅在用户明确提出要求时应用。使用 view:"timeline" 刷新受影响的时间线；适当时传入 track 以缩小读取范围。

效果

edit_item(json: '{"adds":[{"type":"effect","targetItemId":"<id>","assetId":"<id>","enabled":true,"propertyOverrides":{}}]}')

转场

需要同一轨道上两个相邻的端点。edit_item 会验证实时接缝的可行性，并拒绝需要冻结帧或与相邻转场重叠的时长。如果添加失败，请使用建议的 durationInFrames 重试、修剪片段以露出余量、删除或缩短相邻转场，或保留硬切。

edit_item(json: '{"adds":[{"type":"transition","assetId":"<id>","outgoingItemId":"<id1>","incomingItemId":"<id2>","durationInFrames":30}]}')

验证与核验

后端验证

通过 generate.ts 生成时，后端会自动处理验证（转译、AST 安全检查、类结构检查，以及失败时重试）。

手动代码核验

绝不要从头编写 shader 代码。 新 shader 始终使用 generate.ts。本节仅适用于修改已生成的现有 shader 代码。

手动编写 shader 代码时，请先阅读 ${CLAUDE_SKILL_DIR}/references/design-principles.md。如果更改涉及可编辑属性，还要阅读 ${CLAUDE_SKILL_DIR}/references/property-changes.md。

典型工作流：

1. 使用 shader assetId 和 includeCode: true 调用 inspect_asset——读取当前源代码。
2. 在自己的上下文中编辑源代码。
3. 使用 action=update、相同的 assetId，并在 json.code 中内联提供完整的替换源代码，调用 edit_asset。更新时会自动运行验证——如果代码无效，更新会被拒绝并返回错误详情。