miaoermua/artcraft-cli

Automatización ArtCraft: Canal de Control, CLI y MCP

Declaración

Este skill es un skill de agente para el software de la serie ArtCraft, no es un repositorio oficial de ArtCraft. Los derechos de autor y la documentación oficial de ArtCraft / LightCraft / FilmCraft / PhotoCraft pertenecen a storyteller (github.com/storytold); este repositorio solo organiza los protocolos públicos y CLI en un manual de operación y scripts de herramientas para agentes de IA, sin afiliación ni respaldo oficial. En caso de conflicto entre la documentación upstream y el contenido de este repositorio, prevalece la oficial.

Repositorios oficiales: lightcraft · filmcraft · photocraft

¿Qué es esto?

Cada aplicación de escritorio de la suite ArtCraft (github.com/storytold) implementa cada elemento del menú, control deslizante y trazo del pincel de la interfaz de usuario como un comando con un ID estable y parámetros JSON, y los expone a través de tres puntos de entrada equivalentes:

Entrada	Aspecto	Adecuado para
Canal de control	La aplicación abre un puerto TCP, envía líneas JSON	Controlar la ventana que el usuario está viendo
CLI	lightcraft-cli / filmcraft-cli / photocraft-cli	Procesamiento por lotes sin interfaz
MCP	xxx-cli mcp	Permitir que clientes como Claude lo utilicen

Los tres utilizan el mismo registro de comandos, por lo que los scripts y agentes pueden operar como humanos, y las ediciones se pueden deshacer.

Cuatro reglas de oro (recuerda estas cuatro primero, luego mira lo demás)

1. Prioridad de descubrimiento en tiempo de ejecución. Los documentos de referencia en este skill son instantáneas de una versión específica, solo para navegación y respaldo; la realidad se basa en la instancia en ejecución: engine.commands (registro de comandos), methods (tabla de métodos), --help/commands/controls del CLI. Prohibido escribir IDs de comando de memoria — cada versión de cada aplicación tiene su propio registro.
2. La autenticación varía entre las tres aplicaciones y puede cambiar. Antes de actuar, ejecuta scripts/craft_env.py para ver el campo auth de tu máquina, no copies ciegamente comandos de puerto de ningún blog. Tres estados conocidos:
   • LightCraft: el canal no requiere autenticación (cualquier proceso local puede controlarlo, se cierra al terminar)
   • FilmCraft: las credenciales se colocan en el campo token de nivel superior de cada solicitud (versiones más recientes lo exigen; la versión 0.9.0 publicada no lo exige en la práctica)
   • PhotoCraft: el primer mensaje de cada conexión debe ser auth; el acceso a archivos está restringido por el alcance de lectura/escritura de automatización con fail-closed scripts/craft_ctl.py --app <light|film|photo> aplica automáticamente el método correspondiente; si faltan credenciales, no falla por sí mismo, sino que delega la decisión al servidor y lee el error tal cual.
3. Las credenciales no van en la línea de comandos, ni en los registros, ni en el repositorio. Usa archivos de token (modo Unix 0600) o variables de entorno; no pases el token en texto plano a un proceso en máquinas compartidas.
4. Antes de editar, explica el impacto. Antes de tocar la biblioteca de imágenes/proyectos real del usuario, explica qué se va a cambiar, si se puede deshacer, dónde se exporta; si no estás seguro del alcance, pregunta.

Primeros pasos: Autocomprobación del entorno

python3 scripts/craft_env.py --table     # Qué versión está instalada, dónde está el CLI, si el canal está abierto, dónde están las credenciales
python3 scripts/craft_env.py             # Mismo contenido en JSON

Este paso reemplaza "recuerdo que instalé la versión X". Solo lee, no escribe.

Decisión de entrada

El usuario quiere	Elige	Razón en una frase
"Tengo este software abierto, ayúdame a hacer clic/ver algo"	Canal de control	La única entrada que puede ver el estado real de la ventana
"Procesa estos 200 archivos por lotes"	CLI headless	No depende de la renderización de la ventana, más rápido y estable
"A partir de ahora, solo le digo esto a la IA"	MCP	Una sola conexión, uso a largo plazo
"¿Qué comandos hay disponibles ahora?"	engine.commands / command_list de cualquier entrada	La única lista autorizada

A. Canal de control

Inicio

Las tres aplicaciones abren un canal con --control PORT, pero las banderas de inicio y los requisitos de credenciales son diferentes, consulta primero craft_env.py y references/app-matrix.md:

# LightCraft: sesión en memoria única, preferido para pruebas, no escribe en disco
nohup "/Applications/LightCraft.app/Contents/MacOS/LightCraft" --control 7980 --memory > /tmp/lc.log 2>&1 & disown

# FilmCraft: necesita exportar credenciales primero, de lo contrario no escucha
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: archivo de token (creado automáticamente en el primer inicio de la aplicación, modo 0600)
nohup "/Applications/PhotoCraft.app/Contents/MacOS/PhotoCraft" --control 7878 \
      --control-token-file ~/.photocraft/control.token > /tmp/pc.log 2>&1 & disown

Mantener el proceso vivo: la GUI iniciada con & simple se recicla cuando el shell que la inició sale, y todas las conexiones posteriores serán rechazadas. Usa nohup ... & disown, o escribe «inicio → control → salida» en el mismo comando.

Control

Usa el cliente incluido, no reescribas el código del socket cada vez:

# Forma genérica: --app determina el método de autenticación, --port da el puerto
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"}'

# Descubrimiento condicional: tabla resumida del registro de comandos (--filter filtra, evitando miles de líneas)
python3 scripts/craft_ctl.py --app light --port 7980 --discover --filter develop

# Modo script: stdin, una solicitud por línea, '#' al inicio es un comentario
echo '{"method":"engine.commands"}' | python3 scripts/craft_ctl.py --app light --port 7980

Códigos de salida: 0 todo ok / 1 hay ok=false / 2 error de uso o conexión.

B. CLI (procesamiento por lotes headless)

El CLI es un recurso de lanzamiento independiente, no está dentro de .app, y el ArtCraft Launcher tampoco lo instala. Para obtenerlo e instalarlo, consulta 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                 # Registro de comandos (equivalente a engine.commands del canal)
lightcraft-cli controls --json                 # IDs y rangos de controles deslizantes 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                   # Buscar ID de comando por palabra clave
filmcraft-cli describe timeline.razor          # Menú/atajo/parámetros/estado de habilitación de un comando individual
filmcraft-cli --project p.fcproj --save exec timeline.razor seconds=3.5
filmcraft-cli --bridge 127.0.0.1:9876 exec window.workspace.color   # Controlar una aplicación en ejecución

Reglas generales: las opciones pueden estar en cualquier orden; salida JSON; código de salida 0=éxito / 1=comando fallido / 2=error de uso; key=value se analiza como JSON si es posible, de lo contrario como cadena; las claves con puntos indican anidación (color.r=1).

C. MCP (conexión con clientes como Claude)

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

Modos headless (motor en proceso, sin ventana) y bridge (controlar una aplicación ya iniciada). Los requisitos de credenciales se encuentran en references/mcp-servers.md.

Flujo de trabajo principal: Descubrir → Ejecutar → Verificar → Revertir

1. Descubrir: engine.commands / command_list para obtener el registro, busca el ID del comando objetivo y los parámetros por label/menu.
2. Ejecutar: engine.execute {command, params}. Nota la diferencia semántica: ui.menu.invoke es "clic en menú" (si no tiene parámetros, abre el cuadro de diálogo del comando), engine.execute ejecuta directamente con los parámetros por defecto, sin abrir cuadros de diálogo.
3. Verificar: Lee el estado, no adivines. ui.inspect es el estado genérico de la UI; cada aplicación tiene sus propios métodos de estado de dominio (LightCraft library.state / photo.inspect / develop.get, FilmCraft sequence.inspect, PhotoCraft document.inspect).
4. Ver resultado: ui.screenshot {path} captura la ventana (captura después de que la renderización esté completa; si la ventana no dibuja fotogramas, usa captura de pantalla headless).
5. Revertir: edit.undo / edit.redo. Las ediciones del agente también entran en la pila de deshacer.

Reglas del protocolo (consistentes entre las tres aplicaciones):

• Una solicitud JSON por línea, una respuesta por línea, en orden correspondiente: {"id":N,"method":...,"params":{...}} → {"id":N,"ok":true,"result":...} o {"id":N,"ok":false,"error":"..."}.
• Sin eventos push: el canal solo responde a las solicitudes. Para saber qué sucede en el lado de la GUI, sondea los métodos inspect y compara las instantáneas.
• Cada solicitud es una instantánea independiente: si cambias de objeto, debes volver a leer el estado, no uses IDs almacenados en caché para inferir el estado actual.
• El tiempo de respuesta máximo del servidor es de 60 segundos; los comandos que exceden el tiempo de espera pueden seguir ejecutándose, consulta el estado antes de reintentar. Para tareas largas, usa wait:false y luego sondea jobs.list.

Límites de seguridad

• Todos los canales solo escuchan en 127.0.0.1, el protocolo no está cifrado — no hagas túnel ni proxies a hosts no confiables. Loopback solo bloquea hosts remotos, no bloquea otros procesos en la misma máquina.
• Canal de LightCraft sin autenticación: abre según sea necesario, usa LIGHTCRAFT_CONFIG_DIR para aislar la configuración para la automatización, ciérralo cuando no lo uses.
• Sistema de archivos de PhotoCraft con fail-closed: la lectura/escritura de automatización está restringida a --automation-read-root / --automation-write-root, cualquier acceso no autorizado es rechazado; file.open / file.save son rechazados por el canal, usa app.open / app.save.
• FILMCRAFT_CONTROL_TOKEN de FilmCraft equivale a control total: mantenlo en secreto, no lo pongas en el historial de la línea de comandos ni en la configuración de MCP.
• Por defecto, no se tocan los datos existentes del usuario (por ejemplo, la biblioteca ~/Pictures/LightCraft Library de LightCraft), a menos que el usuario lo solicite explícitamente.

Si hay problemas, consulta primero aquí

references/known-pitfalls.md contiene los problemas reales encontrados (conexión rechazada, tiempo de espera sin fotogramas, PhotoCraft sin --help, guardado atómico de exportación bloqueado por la política del sistema, desplazamiento del origen de la capa, coordenadas relativas quad, etc.). Consulta la tabla primero, no repitas el mismo comando incorrecto.

Índice de documentos de referencia

Archivo	Contenido
references/app-matrix.md	Diferencias rápidas entre las tres aplicaciones (banderas de inicio, credenciales, sandbox, métodos de estado, entradas CLI/MCP) — mira esto primero
references/control-protocols.md	Protocolo del canal de control: mecanismo general + tabla de métodos de cada aplicación + tres estados de autenticación
references/cli-reference.md	Obtención de los tres CLI, subcomandos, semántica de parámetros, códigos de salida
references/mcp-servers.md	Lista de herramientas del servidor MCP, dos modos, métodos de conexión
references/known-pitfalls.md	Problemas reales y rutas de solución
references/upstream-sources.md	Direcciones de documentación upstream, fecha de la instantánea, cómo actualizar esta referencia
scripts/craft_ctl.py	Cliente del canal de control (las diferencias de autenticación entre las tres aplicaciones ya están integradas)
scripts/craft_env.py	Autocomprobación del entorno: aplicaciones, versiones, CLI, canal, credenciales