0xsline/openchatcut

著色器產生器

僅提交：建立一個後端產生工作，回傳 jobId。提交後請使用 track_progress 工具追蹤工作生命週期。

一律使用 generate.ts 來產生新的著色器。 手動編寫僅限於編輯現有資源的程式碼——絕不能作為產生失敗時的備用方案。

目錄優先規則——在產生之前先嘗試現有資源

在產生著色器之前，請先呼叫 browse_library，除非使用者直接指定了已在 read_project 中顯示的確切資源 ID。

browse_library 是內建特效、內建轉場以及專案特效/轉場資源的唯一真實來源。內建資源是穩定的全域資源 ID，而非專案專屬的資料庫資源，因此它們可能不會出現在 read_project 的資源列表中。

使用 edit_item 套用目錄中的項目，請勿呼叫 submit_shader。

良好的目錄搜尋範例：

browse_library(query: "縮放")
browse_library(category: "轉場", query: "溶解")
browse_library(category: "音訊特效")

只有當目錄中沒有任何項目能足夠貼合使用者意圖時，才進行產生。

builtin:zoom 僅限軌道綁定——請勿使用項目綁定

預設的特效模式是 "item-bound"（透過 targetItemId 附加到單一項目）。builtin:zoom 在項目綁定模式下無法渲染——渲染器只會從軌道綁定的特效項目中讀取縮放資料。項目綁定的縮放會在資料庫中默默新增項目，但在預覽中卻毫無顯示。

請使用 mode: "track-bound"，並搭配 trackId、trackBoundFrom 和 trackBoundDurationInFrames。這三個欄位是必填的。

# 在整個影片片段上縮放
edit_item(json: '{"adds":[{"type":"effect","assetId":"builtin:zoom","mode":"track-bound","trackId":"<片段-trackId>","trackBoundFrom":<片段-fromFrame>,"trackBoundDurationInFrames":<片段-durationInFrames>,"propertyOverrides":{"magnification":1.5,"shape":"hold"}}]}')

# 在片段的子範圍內縮放（例如僅第 90–150 影格，在節拍上做一個衝擊縮放）
edti_item(json: '{"adds":[{"type":"effect","assetId":"builtin:zoom","mode":"track-bound","trackId":"<trackId>","trackBoundFrom":90,"trackBoundDurationInFrames":60,"propertyOverrides":{"magnification":2,"shape":"punch"}}]}')

從 read_project 取得 trackId / fromFrame / durationInFrames（每個影片/圖片項目都會列出其 trackId 和時間軸影格範圍）。

鍵值	型別	範圍/值	預設值	說明
magnification	數值	1–4	1.5	縮放倍率；1 = 無縮放，2 = 2 倍放大
focalPointX	數值	0–1	0.5	水平對焦點（0 = 左，1 = 右）
focalPointY	數值	0–1	0.5	垂直對焦點（0 = 上，1 = 下）
shape	選擇	punch / hold / slow-push / instant	hold	動畫曲線
focalMode	選擇	auto / manual	auto	auto 自動選取主體；manual 使用 focalPoint
easeInFrames	數值	0–60	8	淡入影格數
easeOutFrames	數值	0–60	8	淡出影格數

若要使用預設縮放，請完全省略 propertyOverrides。只傳送你想要更改的鍵值——採用部分更新語義。

軌道綁定 vs 項目綁定——通則

結構中的特效項目有兩種模式：

• item-bound（預設）：僅需 targetItemId。特效涵蓋整個目標項目的播放時間。適用於著色器特效、LUT、調色、模糊。
• track-bound：需要 trackId + trackBoundFrom + trackBoundDurationInFrames。特效涵蓋軌道上的某個時間軸範圍，與任何項目無關。builtin:zoom 需要此模式；當你想要讓任何著色器特效涵蓋特定時間軸範圍時（例如，跨越兩個片段邊界的過渡色彩變化），此模式也同樣有效。

對於著色器特效，預設使用項目綁定。當 (a) 資源要求使用軌道綁定（如縮放），或 (b) 特效應涵蓋一個不符合單一項目的時間軸範圍時，才使用軌道綁定。

內建 LUT 屬性

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

鍵值	型別	範圍	預設值	說明
intensity	數值	0–1	1	LUT 強度；1 = 完全套用

若要更換：刪除該特效，然後用不同的 assetId 重新加入。若要移除：刪除該特效項目。

這些與使用者上傳的 .cube LUT 資源不同（請參閱下文「套用現有 LUT 資源」）——那些使用不同的程式碼路徑，其 assetId 為 "lut"。

Beta 狀態門檻

新的著色器產生功能目前處於 beta 階段。在產生之前，請警告使用者並等待明確確認。

請使用使用者的語言。繁體中文：「新的特效/轉場生成目前還是 beta 階段，可能會有功能不穩定的問題。若您仍希望繼續，我可以為您實現。」如果使用者已經在同一請求中確認過，則可跳過此步驟。

支援的目標

特效和轉場適用於 video、image 和 gif 項目。

類型路由

在產生任何內容之前，請先檢查兩個非產生路徑：

1. 目錄條目——使用 browse_library 來尋找內建和專案的特效/轉場。
2. 使用者上傳且已存在於專案庫中的 .cube LUT 資源——屬於不同的程式碼路徑，請參閱下文「套用現有 LUT 資源」。此資源在 read_project 中會以 type: lut 顯示。

使用者想要	--type
影片外觀（色彩、模糊、光暈、顆粒、變形）	effect
色彩分級 / 色調（青橙、電影感、復古、LUT 風格）	effect
可見度控制（遮罩、揭露、擦除、形狀裁切、漸變淡出）	effect
片段間的混和（交叉淡出、溶解、滑動、3D 立方體/翻頁）	transition

表格中的「LUT 風格」是指產生一個類似 LUT 的新 GLSL 色彩分級——僅在使用者想要新東西時才這麼做。如果他們想要套用已在庫中的 .cube 檔案，請不要產生；而是直接繫結現有資源。

對於產生路徑，沒有獨立的 LUT 或遮罩產生器——這些都是 effect。

套用現有 LUT 資源

使用者上傳的 .cube 檔案會成為 lut 資源。將其套用到片段上並非產生動作——只需要單次 edit_item 呼叫，附加一個特效項目，其 assetId 為字串 "lut"，並在 propertyOverrides.lut 中繫結真實的 LUT 資源 ID。（舊有合約；統一的 LUT API 會直接繫結 LUT 特效資源 ID——請參閱 edit_item 說明。）

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

重點：

• assetId 是字串 "lut"，而非 LUT 資源的 ID。真實的 LUT 資源 ID 放在 propertyOverrides.lut.assetId 中。
• intensity 範圍為 0–1；預設值為 1（完全強度）。
• targetItemType 預設為 video；也支援 image、gif。
• 若要在現有效果上更換 LUT：將 propertyOverrides.lut.assetId 更新為新的 LUT 資源 ID。
• 若要移除：刪除該特效項目。

請勿為此路徑呼叫 generate.ts。請勿將真實的 LUT 資源 ID 作為 assetId 傳入——編輯器會檢查 assetId === "lut" 以路由到 LUT 渲染器；傳入 UUID 會導致渲染無聲失敗。

使用方式

在呼叫 submit_shader 之前，請用一句具體的話重申使用者的意圖，然後立即繼續。在 track_progress 回傳後，用一行說明產生的內容——請勿問「要保留還是重新產生」。

submit_shader({
  type: "effect",
  prompt: "帶有 RGB 分離的色差效果",
  name: "色差",
});

submit_shader({
  type: "transition",
  prompt: "帶有柔和邊緣的平滑交叉淡出",
  name: "交叉淡出",
});

submit_shader({
  type: "effect",
  prompt: "電影感青橙色調",
});

submit_shader({
  type: "effect",
  prompt: "更強烈的版本",
  referenceAssetIds: ["effect_asset_id"],
});

策略

• 提交，然後停止。告知使用者工作已建立。
• 提交後使用 track_progress 工具來檢查狀態/等待。
• 產生動作總是會產生一個庫資源——永遠不要因為時間軸尚未就緒而拒絕產生。
• 套用是獨立且可選的動作。 僅在使用者明確要求時才進行套用（「加到影片」、「apply」、「用於第一段」）。當意義不明時，預設僅加入庫中。

編輯現有屬性

每當你要編輯著色器 asset.properties、已套用的特效/轉場 item.propertyOverrides，或提升一個寫死的著色器值時，請先閱讀 references/property-changes.md。

它會強調著色器 properties 是一個陣列，但允許的著色器屬性類型只有 number、boolean、color、select 和 vec2。動態圖形屬性同樣是陣列，但使用一套不同的類型。

參數

參數	說明	預設值
type	"effect" 或 "transition"（必填）	—
prompt	著色器描述（必填）	—
name	在庫中顯示的資源名稱	—
referenceAssetIds	資源 ID。圖片 ID → 模型會參考它作為視覺靈感。特效/轉場 ID → 重用其程式碼作為風格錨點（每次提交最多 1 個，類型必須與 type 相符）。	—

輸出

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

套用到時間軸

僅在使用者明確要求時才進行。請先呼叫 read_project 以取得最新的時間軸狀態。

特效

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 安全性、類別結構、失敗時重試）。

手動程式碼驗證

絕對不要從頭編寫著色器程式碼。 一律使用 generate.ts 來產生新的著色器。本節僅適用於修改已經產生的現有著色器程式碼。

在手動編寫著色器程式碼時，請先閱讀 ${CLAUDE_SKILL_DIR}/references/design-principles.md。如果修改涉及可編輯的屬性，也請一併閱讀 ${CLAUDE_SKILL_DIR}/references/property-changes.md。

典型工作流程：

1. 使用著色器的 assetId 並設定 code: true 來執行 read_project——讀取目前的原始碼。
2. 在你自己的上下文中編輯原始碼。
3. 使用 action=update、相同的 assetId 以及內嵌在 json.code 中的完整取代原始碼來執行 edit_asset。更新時會自動執行驗證——如果程式碼無效，更新將被拒絕並附帶錯誤詳細資訊。