miaoermua/artcraft-cli

Automatisation ArtCraft : Canal de contrôle, CLI et MCP

Déclaration

Ce skill est un skill agent pour les logiciels ArtCraft, il n'est pas affilié au dépôt officiel d'ArtCraft. Les droits d'auteur et la documentation officielle d'ArtCraft / LightCraft / FilmCraft / PhotoCraft appartiennent à storyteller (github.com/storytold) ; ce dépôt se contente de compiler les protocoles et CLI officiels en un manuel d'utilisation et des scripts d'outils destinés aux agents IA, sans lien de subordination ni de caution avec l'officiel. En cas de conflit entre la documentation en amont et le contenu de ce dépôt, la documentation officielle prévaut.

Dépôts officiels : lightcraft · filmcraft · photocraft

De quoi s'agit-il ?

Chaque application de bureau de la suite ArtCraft (github.com/storytold) implémente chaque élément de menu, curseur et trait de pinceau que l'on peut actionner dans l'interface en tant que commande avec un id stable et des paramètres JSON, et les expose via trois points d'entrée équivalents :

Point d'entrée	À quoi ça ressemble	Pour quoi faire
Canal de contrôle	L'application ouvre un port TCP, on échange des lignes JSON	Piloter la fenêtre que l'utilisateur a sous les yeux
CLI	lightcraft-cli / filmcraft-cli / photocraft-cli	Traitement headless par lots
MCP	xxx-cli mcp	Laisser Claude ou d'autres clients donner des ordres

Les trois utilisent le même registre de commandes, donc les scripts et agents peuvent manipuler comme un humain, et les modifications sont annulables (undo).

Quatre règles d'or (à retenir avant tout le reste)

1. Découverte à l'exécution avant tout. La documentation de référence de ce skill est un instantané à un moment donné, elle sert uniquement à naviguer et en dernier recours ; la réalité, c'est l'instance en cours d'exécution : engine.commands (registre des commandes), methods (table des méthodes), --help / commands / controls de la CLI. Il est interdit d'écrire des ids de commande de mémoire – chaque version de chaque application a son propre registre.
2. L'authentification diffère selon l'application et peut changer. Avant d'agir, exécutez d'abord scripts/craft_env.py pour voir le champ auth de votre machine, ne recopiez pas les commandes de port d'un blog. Les trois états connus :
   • LightCraft : canal sans authentification (tout processus local peut le piloter, on le ferme après usage)
   • FilmCraft : les identifiants sont placés dans le champ token de chaque requête (obligatoire dans les versions récentes ; la version 0.9.0 publiée ne l'impose pas en pratique)
   • PhotoCraft : la première trame de chaque connexion doit être auth ; l'accès aux fichiers est limité par une politique de refus par défaut (fail-closed) pour les lectures/écritures automatisées scripts/craft_ctl.py --app <light|film|photo> applique automatiquement la méthode correspondante ; en l'absence d'identifiants, il ne se termine pas prématurément en échec mais laisse le serveur décider et lit l'erreur telle quelle.
3. Les identifiants ne doivent pas apparaître en ligne de commande, dans les logs, ni dans le dépôt. Utilisez un fichier token (mode Unix 0600) ou une variable d'environnement ; ne passez pas le token en clair à un processus sur une machine partagée.
4. Avant de modifier, expliquez l'impact. Avant de toucher à la photothèque ou au projet réel d'un utilisateur, précisez ce qui sera modifié, si c'est annulable, et où sera exporté le résultat ; si vous n'êtes pas sûr de la portée, demandez.

Pour commencer : auto-vérification de l'environnement

python3 scripts/craft_env.py --table     # versions installées, emplacement des CLI, canal ouvert ou non, emplacement des identifiants
python3 scripts/craft_env.py             # même contenu en JSON

Cette étape remplace "je crois que j'ai installé la version X". Elle ne fait que lire, rien d'autre.

Choix du point d'entrée

L'utilisateur veut	Choisir	Raison en une phrase
"Je suis en train d'utiliser ce logiciel, aide-moi à cliquer/regarder"	Canal de contrôle	Seul point d'entrée qui voit l'état réel de la fenêtre
"Traiter ces 200 fichiers en lot"	CLI headless	Ne dépend pas du rendu de la fenêtre, plus rapide et plus stable
"À l'avenir, je veux simplement dire ça à l'IA"	MCP	Une seule connexion, utilisation à long terme
"Quelles commandes puis-je exécuter maintenant ?"	N'importe quel point d'entrée avec engine.commands / command_list	Seule liste faisant autorité

A. Canal de contrôle

Démarrage

Les trois applications ouvrent un canal avec --control PORT, mais les flags de démarrage et les exigences d'authentification diffèrent ; vérifiez d'abord craft_env.py et references/app-matrix.md :

# LightCraft : session en mémoire unique, idéal pour les tests, n'écrit rien sur le disque
nohup "/Applications/LightCraft.app/Contents/MacOS/LightCraft" --control 7980 --memory > /tmp/lc.log 2>&1 & disown

# FilmCraft : doit d'abord exporter les identifiants, sinon n'écoute pas
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 : fichier token (créé automatiquement au premier démarrage de l'application, mode 0600)
nohup "/Applications/PhotoCraft.app/Contents/MacOS/PhotoCraft" --control 7878 \
      --control-token-file ~/.photocraft/control.token > /tmp/pc.log 2>&1 & disown

Maintien en vie du processus : une interface graphique lancée avec & nu sera récupérée à la sortie du shell qui l'a lancée, et toutes les connexions ultérieures seront refusées. Utilisez nohup ... & disown, ou écrivez le « lancement → pilotage → arrêt » dans une seule commande.

Pilotage

Utilisez le client fourni, ne réécrivez pas le code socket à chaque fois :

# Forme générale : --app détermine la méthode d'authentification, --port donne le 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"}'

# Découverte conditionnelle : registre des commandes simplifié (--filter pour filtrer, éviter des milliers de lignes)
python3 scripts/craft_ctl.py --app light --port 7980 --discover --filter develop

# Mode script : une requête par ligne sur stdin, les lignes commençant par '#' sont des commentaires
echo '{"method":"engine.commands"}' | python3 scripts/craft_ctl.py --app light --port 7980

Codes de sortie : 0 tout ok / 1 au moins une réponse ok=false / 2 erreur d'utilisation ou de connexion.

B. CLI (traitement headless par lots)

La CLI est un asset de livraison indépendant, elle n'est pas dans le .app, et ArtCraft Launcher ne l'installe pas non plus. Pour l'obtenir et l'installer, voir 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                 # Registre des commandes (équivalent à engine.commands du canal)
lightcraft-cli controls --json                 # IDs et plages des curseurs de develop

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                   # Chercher l'ID d'une commande par mot-clé
filmcraft-cli describe timeline.razor          # Menu/raccourci/paramètres/état d'activation d'une commande
filmcraft-cli --project p.fcproj --save exec timeline.razor seconds=3.5
filmcraft-cli --bridge 127.0.0.1:9876 exec window.workspace.color   # Contrôler une application déjà lancée

Règles générales : les options peuvent être placées n'importe où ; sortie en JSON ; code de sortie 0 = succès / 1 = échec de la commande / 2 = erreur d'utilisation ; key=value est parsé comme JSON si possible, sinon comme chaîne ; une clé avec un point indique une imbrication (color.r=1).

C. MCP (connexion à Claude ou d'autres 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

Deux modes : headless (moteur dans le processus, sans fenêtre) et bridge (pilote une application déjà lancée). Les exigences d'authentification sont détaillées dans references/mcp-servers.md.

Flux de travail essentiel : Découverte → Exécution → Vérification → Annulation

1. Découverte : engine.commands / command_list pour obtenir le registre, trouver l'ID de la commande cible et sa documentation de paramètres par label/menu.
2. Exécution : engine.execute {command, params}. Attention à la nuance sémantique – ui.menu.invoke est un « clic de menu » (sans paramètres, il ouvre la boîte de dialogue de la commande), engine.execute exécute directement avec les paramètres par défaut, sans ouvrir de dialogue.
3. Vérification : lisez l'état plutôt que de deviner. ui.inspect est un état UI générique ; chaque application a ses propres méthodes d'état spécifiques (LightCraft library.state / photo.inspect / develop.get, FilmCraft sequence.inspect, PhotoCraft document.inspect).
4. Voir le résultat : ui.screenshot {path} pour capturer la fenêtre (capture uniquement après le rendu ; si la fenêtre ne dessine pas de trame, utilisez une capture d'écran headless).
5. Annulation : edit.undo / edit.redo. Les modifications effectuées par l'agent entrent également dans la pile d'annulation.

Règles protocolaires (communes aux trois applications) :

• Une requête JSON par ligne, une réponse par ligne, dans l'ordre : {"id":N,"method":...,"params":{...}} → {"id":N,"ok":true,"result":...} ou {"id":N,"ok":false,"error":"..."}.
• Pas d'événements push : le canal ne répond qu'aux requêtes. Pour savoir ce qui se passe du côté de l'interface graphique, interrogez les méthodes inspect en comparant les instantanés.
• Chaque requête est un instantané indépendant : si l'objet change, vous devez relire l'état, n'utilisez pas un id en cache pour déduire l'état actuel.
• Limite de réponse du serveur : 60s ; une commande qui dépasse ce délai peut encore être en cours d'exécution, vérifiez l'état avant de réessayer. Pour les tâches longues, utilisez wait:false puis interrogez jobs.list.

Périmètre de sécurité

• Tous les canaux n'écoutent que sur 127.0.0.1, le protocole n'est pas chiffré – ne faites pas de tunnel ou de proxy vers un hôte non fiable. Le loopback bloque l'accès distant, mais pas les autres processus sur la même machine.
• Canal LightCraft sans authentification : ouvrez-le selon les besoins, isolez la configuration avec LIGHTCRAFT_CONFIG_DIR pour l'automatisation, fermez-le quand vous ne l'utilisez pas.
• Système de fichiers PhotoCraft en fail-closed : les lectures/écritures automatisées sont limitées à --automation-read-root / --automation-write-root, tout accès non autorisé est refusé ; file.open / file.save sont refusés par le canal, utilisez app.open / app.save.
• FILMCRAFT_CONTROL_TOKEN de FilmCraft équivaut à un contrôle total : gardez-le secret, ne le laissez pas entrer dans l'historique de la ligne de commande ou la configuration MCP.
• Ne touchez pas par défaut aux données existantes de l'utilisateur (par exemple le dossier ~/Pictures/LightCraft Library de LightCraft), sauf demande explicite de l'utilisateur.

En cas de problème, commencez ici

references/known-pitfalls.md recense les problèmes rencontrés en pratique (connexion refusée, timeout sans trame, absence de --help dans PhotoCraft, blocage de la sauvegarde atomique par la politique système, décalage de l'origine des calques, coordonnées relatives quad, etc.). Consultez le tableau avant de réessayer la même commande erronée.

Index des documents de référence

Fichier	Contenu
references/app-matrix.md	Aide-mémoire des différences entre les trois applications (flags de démarrage, identifiants, sandbox, méthodes d'état, points d'entrée CLI/MCP) – à consulter en premier
references/control-protocols.md	Protocole du canal de contrôle : mécanismes généraux + table des méthodes par application + trois états d'authentification
references/cli-reference.md	Obtention, sous-commandes, sémantique des paramètres, codes de sortie des trois CLI
references/mcp-servers.md	Liste des outils du serveur MCP, deux modes, méthode de connexion
references/known-pitfalls.md	Pièges constatés et chemins de résolution
references/upstream-sources.md	Adresses de la documentation en amont, date de l'instantané, comment rafraîchir cette référence
scripts/craft_ctl.py	Client du canal de contrôle (différences d'authentification intégrées pour les trois applications)
scripts/craft_env.py	Auto-vérification de l'environnement : applications, versions, CLI, canal, identifiants