miaoermua/artcraft-cli

ArtCraft Automatisierung: Steuerungskanal, CLI und MCP

Erklärung

Dieses Skill ist ein Agent-Skill für die ArtCraft-Softwaresuite und kein offizielles Repositorium von ArtCraft. Die Urheberrechte und die offizielle Dokumentation von ArtCraft / LightCraft / FilmCraft / PhotoCraft liegen bei storyteller (github.com/storytold); dieses Repositorium fasst lediglich die öffentlich zugänglichen Protokolle und CLI-Befehle in einem Benutzerhandbuch und Skripten für KI-Agenten zusammen und steht in keinem Abhängigkeits- oder Unterstützungsverhältnis zum offiziellen Projekt. Bei Widersprüchen zwischen den Upstream-Dokumenten und dem Inhalt dieses Repositoriums gilt der offizielle Stand.

Offizielle Repositorien: lightcraft · filmcraft · photocraft

Was ist das?

Jede Desktop-Anwendung der ArtCraft-Suite (github.com/storytold) implementiert jeden Menüpunkt, Schieberegler und Pinselstrich im UI als Befehl mit stabiler ID und JSON-Parametern und stellt diese über drei äquivalente Einstiegspunkte zur Verfügung:

Einstiegspunkt	Wie sieht es aus	Wofür geeignet
Steuerungskanal	Die App öffnet einen TCP-Port und kommuniziert über JSON-Zeilen	Steuerung des aktuell sichtbaren Fensters des Benutzers
CLI	lightcraft-cli / filmcraft-cli / photocraft-cli	Unbeaufsichtigte Stapelverarbeitung ohne GUI
MCP	xxx-cli mcp	Einbindung von Claude und anderen Clients

Alle drei nutzen dieselbe Befehlsregistrierung, sodass Skripte und Agenten genau wie ein menschlicher Benutzer interagieren können und Bearbeitungen rückgängig machbar sind.

Vier Grundregeln (Merken Sie sich diese zuerst)

1. Laufzeit-Erkennung hat Vorrang. Die Referenzdokumente in diesem Skill sind Schnappschüsse eines bestimmten Versionszeitpunkts und dienen nur zur Navigation und als Fallback; maßgeblich ist die aktuelle laufende Instanz: engine.commands (Befehlsregistrierung), methods (Methodentabelle), CLI --help / commands / controls. Befehls-IDs niemals aus dem Gedächtnis aufschreiben – die Registrierungen variieren zwischen den Anwendungen und Versionen.
2. Authentifizierung unterscheidet sich pro Anwendung und kann sich ändern. Führen Sie vor dem Handeln immer scripts/craft_env.py aus, um das lokale auth-Feld zu sehen. Kopieren Sie keine Port-Befehle aus irgendwelchen Blogbeiträgen. Bekannte Zustände:
   • LightCraft: Kanal ohne Authentifizierung (jeder lokale Prozess kann steuern, nach Gebrauch schließen)
   • FilmCraft: Anmeldedaten werden im oberen token-Feld jeder Anfrage übergeben (neuere Versionen erzwingen dies; die veröffentlichte 0.9.0 erzwingt es laut Tests nicht)
   • PhotoCraft: Jede Verbindung muss als erstes Frame eine auth-Nachricht senden; Dateizugriffe sind durch die fail-closed-Automatisierung auf Lese-/Schreibwurzelverzeichnisse beschränkt scripts/craft_ctl.py --app <light|film|photo> wendet automatisch die entsprechende Methode an. Fehlt die Berechtigung, schlägt das Skript nicht automatisch fehl, sondern delegiert die Entscheidung an den Server und gibt den Fehler unverändert aus.
3. Anmeldedaten gehören nicht in die Befehlszeile, in Logs oder ins Repository. Verwenden Sie Token-Dateien (Unix-Modus 0600) oder Umgebungsvariablen; übergeben Sie Token nicht im Klartext an Prozesse auf gemeinsam genutzten Maschinen.
4. Sagen Sie vor dem Bearbeiten, was passiert. Bevor Sie die tatsächliche Bibliothek/das Projekt des Benutzers ändern, erklären Sie klar, was geändert wird, ob es rückgängig gemacht werden kann, wohin exportiert wird; fragen Sie bei Unklarheit nach.

Erste Schritte: Führen Sie zuerst eine Umgebungsprüfung durch

python3 scripts/craft_env.py --table     # Zeigt: installierte Versionen, CLI-Pfade, offene Kanäle, Token-Speicherorte
python3 scripts/craft_env.py             # Gleicher Inhalt als JSON

Dieser Schritt ersetzt die Annahme „Ich glaube, ich habe Version X installiert“. Er ist rein lesend.

Entscheidungshilfe für den Einstieg

Was der Benutzer will	Wählen Sie	Grund
„Ich habe die Software geöffnet, hilf mir, darauf zu klicken/etwas zu sehen“	Steuerungskanal	Einziger Einstiegspunkt, der den tatsächlichen Fensterzustand sehen kann
„Verarbeite diese 200 Dateien im Stapel“	CLI headless	Unabhängig von der Fensterdarstellung, schneller und stabiler
„Ich möchte das später direkt über KI sagen“	MCP	Einmal eingerichtet, dauerhaft nutzbar
„Welche Befehle kann ich gerade ausführen?“	engine.commands / command_list eines beliebigen Einstiegspunkts	Einzige maßgebliche Liste

A. Steuerungskanal

Start

Alle drei Anwendungen öffnen den Kanal mit --control PORT, aber die Start-Flags und Authentifizierungsanforderungen sind unterschiedlich. Überprüfen Sie zuerst craft_env.py und references/app-matrix.md:

# LightCraft: Einmalige In-Memory-Sitzung, erste Wahl für Tests, schreibt nichts auf die Festplatte
nohup "/Applications/LightCraft.app/Contents/MacOS/LightCraft" --control 7980 --memory > /tmp/lc.log 2>&1 & disown

# FilmCraft: Zuerst Token exportieren, sonst wird nicht gelauscht
export FILMCRAFT_CONTROL_TOKEN="$(python3 -c 'import secrets; print(secrets.token_hex(32))')"
nohup "/Applications/FilmCraft.app/Contents/MacOS/FilmCraft" --control 9876 > /tmp/fc.log 2>&1 & disown

# PhotoCraft: Token-Datei (wird beim ersten Start der App automatisch erstellt, Modus 0600)
nohup "/Applications/PhotoCraft.app/Contents/MacOS/PhotoCraft" --control 7878 \
      --control-token-file ~/.photocraft/control.token > /tmp/pc.log 2>&1 & disown

Prozess am Leben erhalten: Eine mit bloßem & gestartete GUI wird beim Beenden der Start-Shell bereinigt, und alle folgenden Verbindungen werden abgelehnt. Verwenden Sie nohup ... & disown oder fassen Sie „Start → Steuerung → Beenden“ in einem einzigen Befehl zusammen.

Steuerung

Verwenden Sie das mitgelieferte Client-Skript, schreiben Sie nicht jedes Mal eigenen Socket-Code:

# Allgemeine Form: --app bestimmt die Authentifizierung, --port den Port
python3 scripts/craft_ctl.py --app light --port 7980 engine.commands
python3 scripts/craft_ctl.py --app film  --port 9876 --method engine.execute --params '{"command":"sequence.inspect"}'
python3 scripts/craft_ctl.py --app photo --port 7878 --token-file ~/.photocraft/control.token '{"method":"ui.inspect"}'

# Bedingte Erkennung: Kurzform der Befehlsregistrierung (--filter zum Filtern, vermeidet tausende Zeilen)
python3 scripts/craft_ctl.py --app light --port 7980 --discover --filter develop

# Skriptmodus: stdin mit einer Anfrage pro Zeile, '#' am Zeilenanfang ist ein Kommentar
echo '{"method":"engine.commands"}' | python3 scripts/craft_ctl.py --app light --port 7980

Exit-Codes: 0 alles ok / 1 es gab ein ok=false / 2 Verwendungs- oder Verbindungsfehler.

B. CLI (Headless-Stapelverarbeitung)

Die CLI ist ein separates Release-Artefakt, nicht in der .app enthalten und wird auch nicht vom ArtCraft Launcher installiert. Bezug und Installation finden Sie in references/cli-reference.md.

lightcraft-cli run --import in.dng develop.set control=light.exposure value=0.7 app.export path=out.jpg longEdge=2048
lightcraft-cli render in.dng -o out.jpg --set light.exposure=0.5
lightcraft-cli commands --json                 # Befehlsregistrierung (äquivalent zu engine.commands des Kanals)
lightcraft-cli controls --json                 # Entwickler-Schieberegler-IDs und -Bereiche

photocraft-cli run wave.psd --cmd filter.sharpen.smartSharpen --params '{"amount":80}' --out out.png
photocraft-cli batch --actions grade.json --in ./raw --out ./graded

filmcraft-cli commands razor                   # Befehls-ID nach Stichwort suchen
filmcraft-cli describe timeline.razor          # Menü/Tastenkombination/Parameter/aktuellen Aktivierungsstatus eines einzelnen Befehls anzeigen
filmcraft-cli --project p.fcproj --save exec timeline.razor seconds=3.5
filmcraft-cli --bridge 127.0.0.1:9876 exec window.workspace.color   # Laufende Anwendung fernsteuern

Allgemeine Regeln: Optionen können an beliebiger Position stehen; Ausgabe ist JSON; Exit-Code 0=Erfolg / 1=Befehl fehlgeschlagen / 2=Verwendungsfehler; key=value wird, wenn als JSON lesbar, als JSON geparst, sonst als String; Punkttasten bedeuten Verschachtelung (color.r=1).

C. MCP (Einbindung von Claude und anderen Clients)

claude mcp add lightcraft     -- lightcraft-cli mcp ~/Pictures/shoot
claude mcp add lightcraft-app -- lightcraft-cli mcp --connect 127.0.0.1:7980
claude mcp add filmcraft      -- filmcraft-cli mcp --bridge 127.0.0.1:9876
claude mcp add photocraft     -- photocraft-cli mcp --bridge 127.0.0.1:7878 --control-token-file /path/token

Es gibt zwei Modi: headless (Engine im Prozess, kein Fenster) und bridge (steuert eine bereits gestartete Anwendung). Die Authentifizierungsanforderungen finden Sie in references/mcp-servers.md.

Kern-Workflow: Erkennen → Ausführen → Prüfen → Rückgängig machen

1. Erkennen: engine.commands / command_list für die Registrierung, Zielbefehls-ID und Parameterdokumentation nach Label/Menü suchen.
2. Ausführen: engine.execute {command, params}. Beachten Sie den semantischen Unterschied – ui.menu.invoke ist ein „Menüklick“ (öffnet den Dialog des Befehls, wenn keine Parameter angegeben werden), engine.execute führt den Befehl direkt mit Standardparametern aus und öffnet keinen Dialog.
3. Prüfen: Den Zustand lesen, nicht raten. ui.inspect bietet einen allgemeinen UI-Status; jede Anwendung hat zusätzlich domänenspezifische Statusmethoden (LightCraft library.state / photo.inspect / develop.get, FilmCraft sequence.inspect, PhotoCraft document.inspect).
4. Ergebnisse ansehen: ui.screenshot {path} erstellt einen Screenshot des Fensters (nachdem das Rendering abgeschlossen ist; wenn das Fenster keine Frames zeichnet, headless-Screenshot verwenden).
5. Rückgängig machen: edit.undo / edit.redo. Bearbeitungen durch den Agenten landen ebenfalls im Undo-Stack.

Protokollregeln (für alle drei Anwendungen gleich):

• Eine JSON-Anfrage pro Zeile, eine Antwort pro Zeile, sequentiell zugeordnet: {"id":N,"method":...,"params":{...}} → {"id":N,"ok":true,"result":...} oder {"id":N,"ok":false,"error":"..."}.
• Keine Ereignisse: Der Kanal antwortet nur auf Anfragen. Um zu erfahren, was auf der GUI-Seite passiert, fragen Sie die inspect-Methoden ab und vergleichen Sie die Schnappschüsse.
• Jede Anfrage ist ein unabhängiger Schnappschuss: Wenn das Objekt gewechselt wurde, muss der Status erneut gelesen werden; verwenden Sie keine zwischengespeicherten IDs, um den aktuellen Status abzuleiten.
• Das Server-Timeout für Antworten beträgt 60s; Befehle, die dieses Timeout überschreiten, könnten noch laufen. Prüfen Sie vor einem erneuten Versuch den Status. Verwenden Sie für lange Aufgaben wait:false und fragen Sie dann jobs.list ab.

Sicherheitsgrenzen

• Alle Kanäle lauschen nur auf 127.0.0.1, das Protokoll ist unverschlüsselt – tunneln oder proxen Sie nicht zu nicht vertrauenswürdigen Hosts. Loopback schützt nur vor entfernten Zugriffen, nicht vor anderen Prozessen auf demselben Rechner.
• LightCraft-Kanal ohne Authentifizierung: Nach Bedarf öffnen; verwenden Sie LIGHTCRAFT_CONFIG_DIR, um die Konfiguration für die Automatisierung zu isolieren, und schalten Sie ihn danach aus.
• PhotoCraft-Dateisystem fail-closed: Automatisierte Lese-/Schreibvorgänge sind auf --automation-read-root / --automation-write-root beschränkt; ohne Autorisierung wird der Zugriff verweigert; file.open / file.save werden vom Kanal abgelehnt; verwenden Sie stattdessen app.open / app.save.
• FilmCrafts FILMCRAFT_CONTROL_TOKEN gewährt vollständige Kontrolle: Geheim halten, nicht in der Befehlszeilenhistorie oder MCP-Konfiguration speichern.
• Standardmäßig werden keine vorhandenen Benutzerdaten berührt (z. B. LightCrafts ~/Pictures/LightCraft Library), es sei denn, der Benutzer fordert dies ausdrücklich.

Bei Problemen hier zuerst nachschlagen

references/known-pitfalls.md enthält die bei Tests gefundenen Fallstricke (Verbindungsabbruch, Timeout ohne Frames, PhotoCraft ohne --help, durch Systemrichtlinien blockiertes atomares Speichern beim Export, Layer-Ursprungsversatz, relative quad-Koordinaten usw.). Schlagen Sie zuerst in der Tabelle nach, wiederholen Sie keinen falschen Befehl.

Referenzdokumente – Index

Datei	Inhalt
references/app-matrix.md	Kurzübersicht über die Unterschiede der drei Anwendungen (Start-Flags, Authentifizierung, Sandbox, Statusmethoden, CLI/MCP-Einstiegspunkte) – zuerst lesen
references/control-protocols.md	Steuerungskanalprotokoll: Allgemeiner Mechanismus + Methodentabellen pro Anwendung + drei Authentifizierungszustände
references/cli-reference.md	Bezug, Unterbefehle, Parametersemantik, Exit-Codes der drei CLIs
references/mcp-servers.md	MCP-Server-Tool-Liste, zwei Modi, Einrichtungsmethode
references/known-pitfalls.md	Gemessene Fallstricke und Fehlerbehebungspfade
references/upstream-sources.md	Adressen der Upstream-Dokumente, Snapshot-Datum, wie diese Referenz aktualisiert wird
scripts/craft_ctl.py	Steuerungskanal-Client (Authentifizierungsunterschiede der drei Anwendungen enthalten)
scripts/craft_env.py	Umgebungsprüfung: Anwendung, Version, CLI, Kanal, Authentifizierung