miaoermua/artcraft-cli

Automação ArtCraft: Canal de Controle, CLI e MCP

Declaração

Este skill é um skill de agente para a série de software ArtCraft, não é o repositório oficial da ArtCraft. Os direitos autorais e a documentação oficial do ArtCraft / LightCraft / FilmCraft / PhotoCraft pertencem a storyteller (github.com/storytold); este repositório apenas organiza os protocolos e CLIs publicados oficialmente em um manual de operação e scripts de ferramentas para agentes de IA, sem afiliação ou endosso com o oficial. Em caso de conflito entre a documentação upstream e o conteúdo deste repositório, prevalece a documentação oficial.

Repositórios oficiais: lightcraft · filmcraft · photocraft

O que é isso

Cada aplicativo desktop do conjunto ArtCraft (github.com/storytold) implementa cada item de menu, controle deslizante e pincelada que pode ser clicada na UI como comandos com ids estáveis e parâmetros JSON, e os expõe através de três portas de entrada equivalentes:

Entrada	Como é	Para que serve
Canal de controle	O aplicativo abre uma porta TCP, falando linhas JSON	Conduzir a janela que o usuário está vendo
CLI	lightcraft-cli / filmcraft-cli / photocraft-cli	Processamento headless em lote
MCP	xxx-cli mcp	Deixar clientes como o Claude comandarem

Os três despacham o mesmo registro de comandos, então scripts e agentes podem operar como uma pessoa, e as edições podem ser desfeitas.

Quatro Regras de Ouro (Primeiro Grave Estas Quatro, Depois Veja o Resto)

1. Descoberta em tempo de execução primeiro. Os documentos de referência neste skill são instantâneos de uma versão específica, usados apenas para navegação e fallback; a fonte da verdade é a instância em execução: engine.commands (registro de comandos), methods (tabela de métodos), --help / commands / controls do CLI. É proibido escrever ids de comando de memória – cada versão de cada aplicativo tem um registro diferente.
2. A autenticação é diferente para os três e pode mudar. Antes de agir, execute scripts/craft_env.py para ver o campo auth da máquina local, não copie comandos de porta de nenhum blog. Três estados conhecidos:
   • LightCraft: Canal sem autenticação (qualquer processo local pode conduzir, feche após o uso)
   • FilmCraft: Credenciais colocadas no campo token de nível superior de cada requisição (versões mais recentes obrigam; a versão 0.9.0 publicada, testada, não obriga)
   • PhotoCraft: O primeiro frame de cada conexão deve ser auth; o acesso a arquivos é limitado por um escopo de automação fail-closed de leitura/escrita raiz scripts/craft_ctl.py --app <light|film|photo> aplica automaticamente o método correspondente; quando faltam credenciais, ele não falha por conta própria, mas delega a decisão ao servidor e lê o erro original.
3. Credenciais não entram em linha de comando, logs ou repositório. Use arquivos de token (Unix mode 0600) ou variáveis de ambiente; não passe tokens em texto claro para processos em máquinas compartilhadas.
4. Antes de editar, diga o impacto. Antes de mexer na biblioteca de fotos/projetos reais do usuário, explique claramente o que será alterado, se é desfeito, para onde será exportado; se não tiver certeza do escopo, pergunte.

Primeiros Passos: Faça a Autoverificação do Ambiente

python3 scripts/craft_env.py --table     # Quais versões instaladas, onde está o CLI, se o canal está aberto, onde estão as credenciais
python3 scripts/craft_env.py             # Mesmo conteúdo em JSON

Este passo substitui "Acho que instalei a versão X". Ele só lê, não escreve.

Decisão de Entrada

O usuário quer	Escolha	Justificativa em uma frase
"Este software está aberto agora, me ajude a clicar/ver"	Canal de controle	A única entrada que pode ver o estado real da janela
"Processe esses 200 arquivos em lote"	CLI headless	Não depende da renderização da janela, executa mais rápido e estável
"A partir de agora, eu só falo com a IA sobre isso"	MCP	Uma vez conectado, uso a longo prazo
"Quais comandos posso executar agora"	engine.commands / command_list de qualquer entrada	A única lista oficial

A. Canal de Controle

Inicialização

Os três aplicativos usam --control PORT para abrir o canal, mas as flags de inicialização e os requisitos de credenciais são diferentes, primeiro consulte craft_env.py e references/app-matrix.md:

# LightCraft: Sessão única na memória, preferido para testes, não escreve em disco
nohup "/Applications/LightCraft.app/Contents/MacOS/LightCraft" --control 7980 --memory > /tmp/lc.log 2>&1 & disown

# FilmCraft: Precisa exportar credenciais primeiro, caso contrário não escuta
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: arquivo de token (criado automaticamente na primeira inicialização do aplicativo, mode 0600)
nohup "/Applications/PhotoCraft.app/Contents/MacOS/PhotoCraft" --control 7878 \
      --control-token-file ~/.photocraft/control.token > /tmp/pc.log 2>&1 & disown

Manter o processo ativo: A GUI iniciada com & simples será recuperada quando o shell que a iniciou sair, e todas as conexões subsequentes serão rejeitadas. Use nohup ... & disown, ou coloque a sequência "iniciar → conduzir → sair" no mesmo comando.

Condução

Use o cliente fornecido, não reescreva o código socket toda vez:

# Forma genérica: --app determina o método de autenticação, --port dá a porta
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"}'

# Descoberta condicional: Tabela resumida do registro de comandos (--filter para filtrar, evita milhares de linhas)
python3 scripts/craft_ctl.py --app light --port 7980 --discover --filter develop

# Modo script: uma requisição por linha no stdin, linhas com '#' são comentários
echo '{"method":"engine.commands"}' | python3 scripts/craft_ctl.py --app light --port 7980

Códigos de saída: 0 tudo ok / 1 houve ok=false / 2 erro de uso ou conexão.

B. CLI (Processamento Headless em Lote)

O CLI é um ativo de release independente, não está dentro do .app, e o ArtCraft Launcher também não o instala. Para obter e instalar, veja 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 do canal)
lightcraft-cli controls --json                 # Ids e faixas dos 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                   # Encontre ids de comando por palavra-chave
filmcraft-cli describe timeline.razor          # Menu/atalho de teclado/parâmetros/estado atual de um único comando
filmcraft-cli --project p.fcproj --save exec timeline.razor seconds=3.5
filmcraft-cli --bridge 127.0.0.1:9876 exec window.workspace.color   # Controle reverso de um aplicativo em execução

Regras gerais: Opções em qualquer ordem; saída JSON; código de saída 0=sucesso / 1=comando falhou / 2=erro de uso; key=value é analisado como JSON se possível, caso contrário é tratado como string; chaves com ponto indicam aninhamento (color.r=1).

C. MCP (Integração com 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

Dois modos: headless (engine interno ao processo, sem janela) e bridge (conduz um aplicativo já iniciado). Requisitos de credenciais em references/mcp-servers.md.

Fluxo de Trabalho Principal: Descobrir → Executar → Verificar → Desfazer

1. Descobrir: engine.commands / command_list para obter o registro, encontrar o id do comando alvo e a documentação dos parâmetros por label/menu.
2. Executar: engine.execute {command, params}. Observe a diferença semântica – ui.menu.invoke é "clique no menu" (se não tiver parâmetros, abre a caixa de diálogo do comando), engine.execute executa com parâmetros padrão, sem abrir diálogo.
3. Verificar: Leia o estado, não adivinhe. ui.inspect é o estado genérico da UI; cada aplicativo tem métodos de estado de domínio específicos (LightCraft library.state / photo.inspect / develop.get, FilmCraft sequence.inspect, PhotoCraft document.inspect).
4. Ver o resultado: ui.screenshot {path} captura a janela (captura só depois que a renderização é concluída; se a janela não desenhar quadros, use captura headless).
5. Desfazer: edit.undo / edit.redo. As edições do agente também entram na pilha de desfazer.

Regras rígidas do protocolo (partes consistentes entre os três):

• Uma requisição JSON por linha, uma resposta por linha, correspondentes em ordem: {"id":N,"method":...,"params":{...}} → {"id":N,"ok":true,"result":...} ou {"id":N,"ok":false,"error":"..."}.
• Nenhum evento push: O canal só responde a requisições. Para saber o que aconteceu no lado da GUI, faça polling de métodos inspect e compare instantâneos.
• Cada requisição é um instantâneo independente: Se o objeto mudou, você deve reler o estado, não use ids em cache para inferir o estado atual.
• Timeout de resposta do servidor de 60s; comandos que excederam o tempo podem ainda estar em execução, verifique o estado antes de tentar novamente. Para tarefas longas, use wait:false e depois faça polling de jobs.list.

Limites de Segurança

• Todos os canais escutam apenas em 127.0.0.1, o protocolo não é criptografado – não faça túnel ou proxy para hosts não confiáveis. Loopback bloqueia apenas remoto, não impede outros processos na mesma máquina.
• Canal LightCraft sem autenticação: Ative conforme necessário, use LIGHTCRAFT_CONFIG_DIR para isolar a configuração para automação, desligue quando não estiver em uso.
• Sistema de arquivos PhotoCraft fail-closed: O acesso de leitura/escrita da automação é limitado a --automation-read-root / --automation-write-root, não autorizado é recusado; file.open / file.save são recusados pelo canal, use app.open / app.save.
• FILMCRAFT_CONTROL_TOKEN do FilmCraft equivale a controle total: Mantenha em segredo, não coloque no histórico de comandos ou configuração MCP.
• Por padrão, não toque nos dados existentes do usuário (por exemplo, ~/Pictures/LightCraft Library do LightCraft), a menos que o usuário solicite explicitamente.

Se Houver Problemas, Consulte Primeiro Aqui

references/known-pitfalls.md contém armadilhas reais encontradas em testes (conexão recusada, timeout sem quadro, PhotoCraft sem --help, salvamento atômico bloqueado por política do sistema, deslocamento de origem de camada, coordenadas relativas quad, etc.). Consulte a tabela primeiro, não tente o mesmo comando de erro repetidamente.

Índice de Documentos de Referência

Arquivo	Conteúdo
references/app-matrix.md	Referência rápida de diferenças entre os três aplicativos (flags de inicialização, credenciais, sandbox, métodos de estado, entradas CLI/MCP) – Veja este primeiro
references/control-protocols.md	Protocolo do canal de controle: Mecanismos gerais + tabela de métodos de cada um + três estados de autenticação
references/cli-reference.md	Como obter, subcomandos, semântica de parâmetros, códigos de saída dos três CLIs
references/mcp-servers.md	Lista de ferramentas do servidor MCP, dois modos, método de integração
references/known-pitfalls.md	Armadilhas reais e caminhos de solução de problemas
references/upstream-sources.md	Endereços de documentação upstream, data do instantâneo, como atualizar esta referência
scripts/craft_ctl.py	Cliente do canal de controle (diferenças de autenticação dos três aplicativos já incorporadas)
scripts/craft_env.py	Autoverificação do ambiente: Aplicativos, versões, CLIs, canais, credenciais