yb2460/cli-anything-photoshop

CLI-Anything Photoshop

Ferramenta de linha de comando para controlar o Adobe Photoshop via interface de automação COM do Windows.

Pré-requisitos

• Windows 10/11
• Adobe Photoshop 2023+ (com interface COM registrada)
• Python 3.10+ e pacote pywin32

Instalação

cd photoshop-harness/agent-harness
pip install -e .

Após a instalação, o comando cli-anything-photoshop estará disponível.

Estrutura de comandos

cli-anything-photoshop [--json] [--project <caminho>] [--dry-run] <grupo-comando> <comando> [opções]

Opções globais

Opção	Descrição
--json	Saída em formato JSON (para interpretação por agente de IA)
--project <caminho>	Abrir ou criar automaticamente um arquivo PSD
--dry-run	Executar o comando sem salvar no disco

Grupos de comandos

project — Gerenciamento de projetos

Comando	Opções	Descrição
new <caminho>	-w largura, -h altura, -r resolução, -m modo, -b cor-fundo	Criar novo PSD
open <caminho>		Abrir arquivo PSD
save [caminho]		Salvar documento
close	--no-save	Fechar documento

document — Operações de documento

Comando	Opções	Descrição
info		Informações do documento
resize	-w largura, -h altura, -r resolução	Redimensionar
canvas	-w largura, -h altura, -a âncora	Redimensionar tela
crop	--left --top --right --bottom	Cortar
rotate	-a ângulo	Rotacionar tela
flip	-d direção	Inverter tela
mode	-m modo	Alterar modo de cor
trim	-t tipo	Aparar bordas

layer — Manipulação de camadas

Comando	Opções	Descrição
add	-n nome, -t tipo, -o opacidade, -b mesclagem	Adicionar camada
delete	-n nome	Excluir camada
duplicate	-n nome, --new-name nome	Duplicar camada
rename	--old nome, --new nome	Renomear
show / hide	-n nome	Mostrar/ocultar
opacity	-n nome, -o opacidade	Definir opacidade
blend	-n nome, -m modo	Definir modo de mesclagem
list		Listar todas as camadas
reorder	-n nome, -p posição	Reordenar
merge	-n nome, --with-layer nome	Mesclar camadas

selection — Operações de seleção

Comando	Opções	Descrição
all		Selecionar tudo
none		Desmarcar
invert		Inverter seleção
feather	-r raio	Suavizar borda
expand	-p pixels	Expandir
contract	-p pixels	Contrair
border	-w largura	Borda da seleção
rect	--left --top --right --bottom	Seleção retangular
fill	-c cor, -o opacidade	Preencher seleção

text — Operações de texto

Comando	Opções	Descrição
add	-t texto, -f fonte, -s tamanho, -c cor	Adicionar texto
edit	-n nome, -t texto, -f fonte, -s tamanho, -c cor	Editar texto
info	-n nome	Informações do texto

export — Exportação

Comando	Opções	Descrição
save <caminho>	-f formato, -q qualidade, -w largura, -h altura	Exportar arquivo

repl

Comando	Descrição
repl	Iniciar modo REPL interativo

Exemplos de uso

Uso com agente de IA (modo --json)

# Criar novo projeto e obter saída JSON
cli-anything-photoshop --json project new -w 800 -h 600 poster.psd

# Adicionar camada de texto
cli-anything-photoshop --json --project poster.psd text add -t "Hello World" -f Arial -s 48 -c "#FF0000"

# Listar todas as camadas (formato JSON)
cli-anything-photoshop --json --project poster.psd layer list

# Exportar como PNG
cli-anything-photoshop --json --project poster.psd export save -f png output.png

# Visualizar (sem salvar)
cli-anything-photoshop --dry-run --project poster.psd layer add -n "rascunho" --type text

Uso manual

# Abrir PSD e editar interativamente
cli-anything-photoshop --project trabalho.psd layer list

# Iniciar REPL
cli-anything-photoshop repl

Guia de uso para agentes

1. Sempre use a flag --json para obter saída estruturada
2. Use --dry-run para visualizar antes de confirmar as alterações
3. Tratamento de erros: quando o código de saída for diferente de zero, verifique stderr para o objeto JSON de erro
4. Estado do projeto: use --project para gerenciar automaticamente abertura/salvamento de arquivos
5. Modo REPL: ideal para operações interativas de múltiplas etapas, reduzindo a sobrecarga de iniciar o processo do Photoshop

Arquitetura COM do Photoshop

Comando CLI → Click CLI → Módulo Core → ComBridge (singleton) → Photoshop.Application COM → Mecanismo Photoshop

O Photoshop expõe todas as capacidades de edição por meio da interface COM do Windows. Esta ferramenta encapsula as operações mais comuns. Para estender, consulte a documentação oficial do COM do Photoshop e adicione novos métodos em utils/com_bridge.py.