0xsline/openchatcut

Shader-Generator

Nur zum Einreichen: Erstellt einen Backend-Generierungsauftrag und gibt jobId zurück. Verwenden Sie das track_progress-Tool für den Auftragslebenszyklus nach der Einreichung.

Verwenden Sie für neue Shader immer generate.ts. Manuelle Erstellung ist nur für die Bearbeitung von bestehendem Asset-Code vorgesehen – niemals als Fallback, wenn die Generierung fehlschlägt.

Katalog-zuerst-Regel – Vorhandene Assets vor der Generierung verwenden

Bevor Sie einen Shader generieren, rufen Sie browse_library auf, es sei denn, der Benenner nennt eine exakte Asset-ID, die bereits in read_project sichtbar ist.

browse_library ist die Quelle der Wahrheit für integrierte Effekte, integrierte Übergänge und Projekt-Effekt/Übergangs-Assets. Integrierte Effekte sind stabile globale Asset-IDs, keine projektspezifischen DB-Assets, daher erscheinen sie möglicherweise nicht in den Asset-Listen von read_project.

Wenden Sie Katalogeinträge mit edit_item an, rufen Sie nicht submit_shader auf.

Gute Katalogsuchen:

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

Generieren Sie nur, wenn kein Katalogeintrag der Absicht des Benutzers genau genug entspricht.

builtin:zoom ist nur Track-gebunden – NICHT Item-gebunden verwenden

Der Standard-Effektmodus ist "item-bound" (Anhängen an ein einzelnes Element über targetItemId). builtin:zoom rendert NICHT im Item-gebundenen Modus – der Renderer liest Zoomdaten ausschließlich von Track-gebundenen Effekt-Items. Ein Item-gebundener Zoom wird zwar in die DB eingefügt, zeigt aber in der Vorschau nichts an.

Verwenden Sie mode: "track-bound" mit trackId + trackBoundFrom + trackBoundDurationInFrames. Diese drei Felder sind erforderlich.

# Zoom auf das gesamte Videoclip
edit_item(json: '{"adds":[{"type":"effect","assetId":"builtin:zoom","mode":"track-bound","trackId":"<clip-trackId>","trackBoundFrom":<clip-fromFrame>,"trackBoundDurationInFrames":<clip-durationInFrames>,"propertyOverrides":{"magnification":1.5,"shape":"hold"}}]}')

# Zoom auf einen Teilbereich des Clips (z.B. Frames 90–150 nur, ein Punch-Zoom auf einen Beat)
edit_item(json: '{"adds":[{"type":"effect","assetId":"builtin:zoom","mode":"track-bound","trackId":"<trackId>","trackBoundFrom":90,"trackBoundDurationInFrames":60,"propertyOverrides":{"magnification":2,"shape":"punch"}}]}')

Holen Sie sich trackId / fromFrame / durationInFrames aus read_project (jedes Video-/Bild-Item listet seine TrackId und den Timeline-Frame-Bereich auf).

Key	Typ	Bereich / Werte	Standard	Anmerkungen
magnification	number	1–4	1.5	Zoomfaktor; 1 = kein Zoom, 2 = 2× hinein
focalPointX	number	0–1	0.5	Horizontaler Fokuspunkt (0 = links, 1 = rechts)
focalPointY	number	0–1	0.5	Vertikaler Fokuspunkt (0 = oben, 1 = unten)
shape	select	punch / hold / slow-push / instant	hold	Animationskurve
focalMode	select	auto / manual	auto	auto wählt Motiv; manual verwendet focalPoint
easeInFrames	number	0–60	8	Einblendungsdauer in Frames
easeOutFrames	number	0–60	8	Ausblendungsdauer in Frames

Lassen Sie propertyOverrides für den Standard-Zoom ganz weg. Senden Sie nur die Schlüssel, die Sie ändern möchten – Patch-Semantik.

Track-gebunden vs. Item-gebunden – die allgemeine Regel

Effekt-Items im Schema haben zwei Modi:

• item-bound (Standard): nur targetItemId. Der Effekt deckt die gesamte Wiedergabe des Zielelements ab. Funktioniert für Shader-Effekte, LUTs, Farbkorrekturen, Unschärfen.
• track-bound: trackId + trackBoundFrom + trackBoundDurationInFrames. Der Effekt deckt einen Timeline-Bereich auf einer Spur ab, unabhängig von einem Element. Erforderlich für builtin:zoom; auch gültig für jeden Shader-Effekt, wenn er einen bestimmten Timeline-Bereich abdecken soll (z.B. eine übergangsähnliche Farbverschiebung an der Grenze zweier Clips).

Standardmäßig für Shader-Effekte item-bound verwenden. track-bound verwenden, wenn (a) das Asset es erfordert (Zoom) oder (b) der Effekt einen Timeline-Bereich abdecken soll, der nicht mit einem einzelnen Element übereinstimmt.

Integrierte LUT-Eigenschaften

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

Key	Typ	Bereich	Standard	Anmerkungen
intensity	number	0–1	1	LUT-Stärke; 1 = vollständig angewendet

Zum Austauschen: Löschen Sie den Effekt und fügen Sie ihn mit einer anderen assetId erneut hinzu. Zum Entfernen: Löschen Sie das Effekt-Item.

Diese sind getrennt von benutzerhochgeladenen .cube LUT-Assets (siehe unten „Anwenden eines vorhandenen LUT-Assets“) – diese verwenden einen anderen Codepfad mit assetId:"lut".

Beta-Status-Hürde

Die Generierung neuer Shader befindet sich in der Beta-Phase. Warnen Sie den Benutzer vor der Generierung und warten Sie auf eine explizite Bestätigung.

Verwenden Sie die Sprache des Benutzers. Chinesisch: "新的特效/转场生成目前还是 beta 阶段，可能会有不稳定的问题。如果你坚持要做，我可以帮你实现。" Überspringen, wenn der Benutzer dies bereits in derselben Anfrage bestätigt hat.

Unterstützte Ziele

Effekte und Übergänge gelten für video-, image- und gif-Items.

Typ-Routing

Überprüfen Sie vor der Generierung zwei Nicht-Generierungspfade:

1. Katalogeintrag – verwenden Sie browse_library für integrierte und Projekt-Effekte/Übergänge.
2. Benutzerhochgeladenes .cube LUT-Asset, das bereits in der Projektbibliothek existiert – separater Codepfad, siehe unten „Anwenden eines vorhandenen LUT-Assets“. Das Asset erscheint in read_project mit type: lut.

Benutzer möchte	--type
Videoaussehen (Farbe, Unschärfe, Glühen, Körnung, Verzerrung)	effect
Farbkorrektur / Look (Teal-Orange, cineastisch, Vintage, LUT-Stil)	effect
Sichtbarkeitssteuerung (Maske, Einblendung, Wischen, Formausschnitt, Verlaufsüberblendung)	effect
Überblendung zwischen Clips (Crossfade, Auflösung, Schieben, 3D-Würfel/Seitenumblättern)	transition

„LUT-Stil“ in der Tabelle bedeutet Generieren einer neuen GLSL-Farbkorrektur, die einer LUT ähnelt – nur, wenn der Benutzer etwas Neues möchte. Wenn er eine .cube-Datei anwenden möchte, die bereits in der Bibliothek vorhanden ist, nicht generieren; stattdessen das vorhandene Asset binden.

Es gibt keinen separaten LUT- oder Maskengenerator für den Generierungspfad – das sind alles effect.

Anwenden eines vorhandenen LUT-Assets

Vom Benutzer hochgeladene .cube-Dateien werden zu lut-Assets. Das Anwenden auf ein Clip ist keine Generierung – es ist ein einzelner edit_item-Aufruf, der ein Effekt-Item anhängt, dessen assetId der literal String "lut" ist und dessen propertyOverrides.lut die tatsächliche LUT-Asset-ID bindet. (Legacy-Vertrag; die einheitliche LUT-API bindet die LUT-Effekt-Asset-ID direkt – siehe edit_item-Beschreibung.)

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

Wichtige Punkte:

• assetId ist der literal String "lut", nicht die ID des LUT-Assets. Die tatsächliche LUT-Asset-ID kommt in propertyOverrides.lut.assetId.
• intensity ist 0–1; Standard 1 (volle Stärke).
• targetItemType standardmäßig video; unterstützt auch image, gif.
• Zum Austauschen einer LUT an einem vorhandenen Effekt: Aktualisieren Sie propertyOverrides.lut.assetId auf die neue LUT-Asset-ID.
• Zum Entfernen: Löschen Sie das Effekt-Item.

Rufen Sie für diesen Pfad nicht generate.ts auf. Übergeben Sie keine echte LUT-Asset-ID als assetId – der Editor prüft auf assetId === "lut", um in den LUT-Renderer zu leiten; die Übergabe einer UUID rendert stillschweigend nichts.

Verwendung

Stellen Sie vor dem Aufruf von submit_shader die Absicht des Benutzers in einem konkreten Satz dar und fahren Sie dann sofort fort. Nachdem track_progress zurückgekehrt ist, geben Sie in einer Zeile an, was erzeugt wurde – fragen Sie NICHT „behalten oder neu generieren“.

submit_shader({
  type: "effect",
  prompt: "Chromatische Aberration mit RGB-Aufteilung",
  name: "Chromatische Aberration",
});

submit_shader({
  type: "transition",
  prompt: "Sanfte Überblendung mit weicher Kante",
  name: "Überblendung",
});

submit_shader({
  type: "effect",
  prompt: "Cineastische Teal-Orange-Farbkorrektur",
});

submit_shader({
  type: "effect",
  prompt: "Stärkere Version",
  referenceAssetIds: ["effect_asset_id"],
});

Strategie

• Einreichen, dann anhalten. Teilen Sie dem Benutzer mit, dass der Auftrag erstellt wurde.
• Verwenden Sie das track_progress-Tool für den Status/das Warten nach der Einreichung.
• Die Generierung erzeugt immer ein Bibliotheks-Asset – verweigern Sie nicht, weil die Timeline noch nicht bereit ist.
• Anwenden ist separat und optional. Nur anwenden, wenn der Benutzer explizit darum bittet („加到视频“, „apply“, „auf das erste Segment anwenden“). Bei Uneindeutigkeit standardmäßig nur Bibliothek.

Bearbeiten vorhandener Eigenschaften

Jedes Mal, wenn Sie asset.properties, item.propertyOverrides eines angewendeten Effekts/Übergangs bearbeiten oder einen fest codierten Shader-Wert nach außen sichtbar machen möchten, lesen Sie zuerst references/property-changes.md.

Es bekräftigt, dass Shader-properties ein Array sind, aber die zulässigen Shader-Eigenschaftstypen sind nur number, boolean, color, select und vec2. Motion-Graphic-Eigenschaften sind ebenfalls Arrays, verwenden aber einen anderen Typsatz.

Parameter

Parameter	Beschreibung	Standard
type	"effect" oder "transition" (erforderlich)	—
prompt	Beschreibung des Shaders (erforderlich)	—
name	In der Bibliothek angezeigter Asset-Name	—
referenceAssetIds	Asset-IDs. Bild-ID → Modell SCHAUT es sich zur visuellen Inspiration an. Effekt/Übergang-ID → Code als Stilanker wiederverwenden (≤1 pro Einreichung, Typ muss mit type übereinstimmen).	—

Ausgabe

Gibt { success, job: { jobId, status }, manage: { status, wait, watch } } zurück.

Auf Timeline anwenden

Nur, wenn der Benutzer explizit darum bittet. Rufen Sie zuerst read_project für den aktuellen Timeline-Zustand auf.

Effekt

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

Übergang

Erfordert zwei benachbarte Endpunkte auf derselben Spur. edit_item validiert die Live-Naht-Machbarkeit und lehnt Dauern ab, die Standbilder oder überlappende benachbarte Übergänge erfordern würden. Wenn das Hinzufügen fehlschlägt, wiederholen Sie es mit der vorgeschlagenen durationInFrames, kürzen Sie die Clips, um Griffe freizulegen, löschen/verkürzen Sie benachbarte Übergänge oder behalten Sie einen harten Schnitt bei.

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

Validierung & Überprüfung

Backend-Validierung

Bei der Generierung über generate.ts übernimmt das Backend die Validierung automatisch (Transpilieren, AST-Sicherheit, Klassenstruktur, Wiederholung bei Fehlschlag).

Manuelle Code-Überprüfung

Schreiben Sie Shader-Code niemals von Grund auf neu. Verwenden Sie für neue Shader immer generate.ts. Dieser Abschnitt ist NUR für die Änderung von vorhandenem Shader-Code, der bereits generiert wurde.

Wenn Sie Shader-Code manuell schreiben, lesen Sie zuerst ${CLAUDE_SKILL_DIR}/references/design-principles.md. Wenn die Änderung bearbeitbare Eigenschaften betrifft, lesen Sie auch ${CLAUDE_SKILL_DIR}/references/property-changes.md.

Typischer Arbeitsablauf:

1. read_project mit der Shader-assetId und code: true – lesen Sie den aktuellen Quellcode.
2. Bearbeiten Sie den Quellcode in Ihrem eigenen Kontext.
3. edit_asset mit action=update, derselben assetId und dem vollständigen Ersatz-Quellcode inline in json.code. Beim Update wird automatisch validiert – wenn der Code ungültig ist, wird das Update mit Fehlerdetails abgelehnt.