shou0715-Arthur/pyaedt-cli

Habilidade PyAEDT CLI

Você tem acesso à CLI pyaedt para interagir com o ANSYS Electronics Desktop (AEDT). Esta skill ensina como usá-la de forma eficaz.

Verificação pré-voo (execute primeiro)

Antes de qualquer comando CLI, verifique se o pyaedt está instalado:

pyaedt --json version

Se o comando falhar, pare e instrua o usuário a instalá-lo primeiro usando o alvo de instalação all para habilitar todos os recursos.

pip install pyaedt[all]

---

Invocando a CLI

Antes de executar qualquer comando, resolva o binário pyaedt uma vez:

1. Tente pyaedt diretamente. Se estiver no PATH do sistema, use-o como está.
2. Se não for encontrado, recorra ao binário local do ambiente virtual no diretório de trabalho atual:
   • Windows: .venv\Scripts\pyaedt
   • Linux/macOS: .venv/bin/pyaedt

Todos os exemplos usam pyaedt por brevidade. Substitua pelo caminho resolvido, se necessário.

Diretório de trabalho para artefatos gerados

Use diretórios temporários para todas as exportações e arquivos gerados, a menos que o usuário especifique o contrário.

Regras:

• Crie um subdiretório específico para a tarefa sob o diretório temporário do sistema operacional
• Use tempfile.mkdtemp(prefix="pyaedt-skill-") (Python), $env:TEMP (Windows) ou ${TMPDIR:-/tmp} (Linux/macOS)
• Não escreva no repositório ou em pastas arbitrárias, a menos que seja explicitamente solicitado
• Mova artefatos do diretório temporário somente após exportação bem-sucedida, se o usuário quiser mantê-los

Referência rápida:

import tempfile

temp_dir = tempfile.mkdtemp(prefix="pyaedt-skill-")

Passe este caminho para --path ou --output em comandos de exportação.

Use --json para comandos não interativos

Use --json para cada comando não interativo para que a saída permaneça estruturada e analisável por máquina.

A saída JSON retorna: {"status": "ok", "data": {...}} ou {"status": "error", "error": "message"}

Sempre analise o campo status antes de usar data. Nunca confie em saída legível por humanos.

Exceções:

• session attach abre um console interativo, então o modo humano é aceitável.
• Comandos doc abrem páginas do navegador e geralmente não são consumidos como saída de automação estruturada.

Forma atual da CLI

Os comandos são organizados como:

pyaedt [--json] <grupo> <comando> [opções]

Grupos disponíveis na CLI atual:

• session
• project
• script
• export
• test-config
• panels
• doc

Comandos de nível superior:

• version
• aedt-versions

Não invente outros grupos de comando ou comandos que não existam na CLI atual. Se uma operação necessária não for suportada pela CLI, relate isso ao usuário em vez de tentar contornar.

Modelo baseado em porta

A CLI atual é baseada principalmente em porta.

• session start inicia uma nova instância do AEDT e retorna sua porta gRPC.
• session list descobre instâncias do AEDT em execução.
• A maioria dos comandos operacionais requer --port explicitamente.
• session attach também pode ser usado para selecionar uma sessão AEDT existente, inclusive por --project ou --design, portanto, nem todo fluxo de trabalho começa com uma porta conhecida.
• Não há estado persistido de session connect para reutilizar posteriormente.

Implicação prática:

# Descobrir ou iniciar AEDT
pyaedt --json session list
pyaedt --json session start --version 2026.1 --non-graphical

# Em seguida, passe --port para o comando desejado
pyaedt --json project list --port 50051
pyaedt --json run my_script.py --port 50051

Regras de resolução de projeto e design

Comandos com escopo de design usam um conjunto de regras de resolução compartilhado. Isso é importante e deve ser aplicado de forma consistente nas orientações e exemplos.

Comandos afetados:

• export screenshot
• export config
• session attach quando usado com --project ou --design

Regras de resolução:

• Se ambos --project e --design forem fornecidos, use-os diretamente.
• Se apenas --project for fornecido, esse projeto deve conter exatamente um design.
• Se apenas --design for fornecido, exatamente um projeto deve estar aberto.
• Se nenhum for fornecido, deve haver exatamente um projeto aberto e exatamente um design nele.
• Se a seleção for ambígua, o comando falha e o seletor ausente deve ser fornecido.

Ao ajudar um usuário, não descreva esse comportamento como fallback de "projeto ativo" ou "design ativo", a menos que o comando realmente use esse comportamento. O comportamento pretendido é a resolução baseada em exclusividade.

Referência de comando

Comandos de nível superior

Comando	Descrição
pyaedt --json version	Exibe a versão do PyAEDT
pyaedt --json aedt-versions	Lista as versões instaladas do AEDT na máquina

Gerenciamento de sessão

Comando	Descrição
pyaedt --json session start --version 2026.1 [--port 50051] [--non-graphical]	Inicia uma nova instância do AEDT
pyaedt --json session list	Lista instâncias do AEDT em execução com PID, versão e porta
pyaedt --json session stop --port 50051	Para uma instância específica do AEDT pela porta
pyaedt --json session stop --all	Fecha todas as instâncias do AEDT
pyaedt session attach [--port 50051] [--project NAME] [--design NAME]	Inicia um console interativo do PyAEDT conectado a uma instância em execução

Notas:

• session attach pode funcionar interativamente se --port for omitido e o usuário selecionar uma instância.
• --project ou --design com session attach funciona apenas para instâncias gRPC com uma porta utilizável.

Comandos de projeto

A porta é necessária para todos os comandos de projeto para especificar qual instância do AEDT direcionar.

Comando	Descrição
pyaedt --json project list --port 50051	Lista todos os projetos abertos e seus designs
pyaedt --json project open "C:/caminho/para/arquivo.aedt" --port 50051 [--non-graphical]	Abre um arquivo de projeto do AEDT
pyaedt --json project save --port 50051 [--path "C:/novo/arquivo.aedt"]	Salva o projeto ativo, opcionalmente como um novo arquivo
pyaedt --json project create --name ProjetoA --port 50051	Cria um projeto. Use --name.
pyaedt --json project create --project ProjetoA --design Design1 --type Hfss --port 50051	Cria um design dentro de um projeto existente. Use --project + --design + --type.
pyaedt --json project close --port 50051 [--project ProjetoA]	Fecha um projeto, ou o projeto ativo se omitido

Comportamento de project create:

• --name é para criação de projeto.
• --project + --design + --type é para criação de design.
• Não misture --name com --design / --type.

Valores suportados para --type:

• Hfss
• Maxwell2d
• Maxwell3d
• Q3d
• Q2d
• Icepak
• Circuit
• TwinBuilder
• Mechanical
• Emit
• Rmxprt
• Hfss3dLayout
• MaxwellCircuit

Comandos de script

Comando	Descrição
pyaedt --json run "caminho/para/script.py" --port 50051	Executa um script Python dentro do AEDT

Comandos de exportação

Comando	Descrição
pyaedt --json export screenshot --port 50051 [--path preview.jpg] [--project NOME] [--design NOME]	Captura uma captura de tela para um design resolvido
pyaedt --json export config --port 50051 [--output config.json] [--project NOME] [--design NOME] [--overwrite]	Exporta um JSON de configuração de design

Ambos os comandos têm escopo de design e, portanto, seguem as regras de resolução de projeto/design compartilhadas acima.

Documentação

Comando	Descrição
pyaedt doc	Abre a página inicial da documentação e exibe ajuda
pyaedt doc examples	Abre a seção de exemplos
pyaedt doc github	Abre o repositório do GitHub
pyaedt doc user-guide	Abre o guia do usuário
pyaedt doc getting-started	Abre a documentação de primeiros passos
pyaedt doc installation	Abre a documentação de instalação
pyaedt doc api	Abre a referência da API
pyaedt doc changelog [VERSAO]	Abre o changelog
pyaedt doc issues	Abre a página de problemas
pyaedt doc search <palavras-chave>	Pesquisa na documentação online

Fluxos de trabalho comuns

Fluxo de trabalho 1: Descobrir ou iniciar AEDT

# Verificar instâncias em execução
pyaedt --json session list

# Se nenhuma estiver em execução, iniciar uma
pyaedt --json session start --version 2026.1 --non-graphical

Regra de decisão:

• Se session list não retornar processos, inicie o AEDT.
• Se retornar um processo, reutilize essa porta.
• Se retornar vários processos, pergunte ao usuário qual porta usar.

Fluxo de trabalho 2: Inspecionar projetos em uma porta

pyaedt --json project list --port 50051

Use isso primeiro quando precisar entender quais seletores de projeto e design são necessários.

Fluxo de trabalho 3: Criar um projeto ou um design

# Criar um projeto. Use --name APENAS (NÃO adicione --design ou --type)
pyaedt --json project create --name "PatchAntenna" --port 50051

# Criar um design em um projeto existente. Use --project + --design + --type APENAS (NÃO adicione --name)
pyaedt --json project create --project "PatchAntenna" --design "HFSSDesign1" --type Hfss --port 50051

Fluxo de trabalho 4: Exploração interativa com session attach

Use session attach como primeira escolha quando o usuário quiser explorar, depurar ou iterar em um design interativamente. Ele abre um console Python interativo que já está conectado à sessão AEDT alvo. desktop é pré-injetado, então comandos PyAEDT podem ser emitidos um por um sem escrever um script completo.

# Conectar a uma instância em execução (porta opcional; pergunta se omitida)
pyaedt session attach --port 50051

# Dentro do console Python interativo, a sessão já está ativa:
# >>> import ansys.aedt.core as aedt
# >>> hfss = aedt.Hfss(new_desktop=False, port=50051)
# >>> box = hfss.modeler.create_box([0, 0, 0], [10, 10, 10], name="MyBox")
# >>> hfss.modeler["MyBox"].color = (255, 0, 0)

Enviando código multilinha para o console Python interativo

Quando o agente envia código para o console Python interativo que abrange mais de uma linha (loops, condicionais, definições de função, etc.), colá-lo diretamente causa um IndentationError ou SyntaxError porque o console trata cada linha como uma entrada separada.

Sempre envolva blocos multilinha em exec(), codificando todas as quebras de linha como \n dentro de uma única string:

# Falha porque o console quebra no corpo do loop
for i in range(3):
    print(i)

# Correto: enviar como uma única chamada exec()
exec("for i in range(3):\n    print(i)")

Regras:

• Use exec() para qualquer bloco que contenha código indentado (loops, if, with, definições de função ou classe).
• Linhas de instrução única (imports, atribuições, chamadas de função) não precisam de exec().
• Escape todas as aspas duplas internas como \" se o delimitador externo for ", ou use literais de string concatenados como mostrado acima.
• Mantenha as chamadas exec() o mais curtas possível; se o bloco crescer além de ~10 linhas, prefira salvar um script temporário e usar run.

Quando preferir o comando session attach ao comando run:

Situação	Abordagem preferida
Explorar estado do design, objetivo desconhecido	session attach
Depurar uma etapa com falha interativamente	session attach
Ajustes pontuais de geometria / parâmetros	session attach
Iterar rapidamente em alguns comandos	session attach
Fluxo de trabalho definido, repetível e com várias etapas	run
CI / headless / pipeline automatizado	run
Fluxo de trabalho com mais de ~5 etapas	run
Rastreabilidade e registro necessários	run

Prefira session attach primeiro. Graduado a run somente quando o fluxo de trabalho for conhecido e precisar ser repetível ou automatizado.

Trabalhando com vários designs simultaneamente

Quando o usuário precisar trabalhar em mais de um design ao mesmo tempo, abra um console Python interativo separado para cada design em vez de alternar designs dentro de um único console. Isso mantém cada design ativo e editável sem fechar ou liberar nenhum deles.

# Terminal 1: console para Design A
pyaedt session attach --port 50051 --project "ProjetoA" --design "DesignA"

# Terminal 2: console para Design B (mesmo projeto ou diferente)
pyaedt session attach --port 50051 --project "ProjetoA" --design "DesignB"

# Terminal 3: console para um design em um projeto diferente
pyaedt session attach --port 50051 --project "ProjetoB" --design "DesignC"

Regras:

• Cada console mantém seu próprio objeto PyAEDT vinculado a um design específico. Fechar um console não fecha os outros.
• Todos os consoles compartilham a mesma instância AEDT (mesmo --port), portanto as alterações feitas em um são visíveis no AEDT imediatamente.
• Não chame desktop.release_desktop() ou aedt_app.release_desktop() dentro de nenhum desses consoles, a menos que você queira intencionalmente desligar o AEDT para todos os consoles abertos.
• Se os designs residirem em instâncias AEDT diferentes, use o --port correspondente para cada console.

Fluxo de trabalho 5: Executar automação

pyaedt --json run "<diretório-temp>/setup_antenna.py" --port 50051

Fluxo de trabalho 6: Execução de script gerado

Use este fluxo de trabalho sempre que um script tiver sido gerado e precisar ser executado automaticamente.

# Passo 1: descobrir instâncias
pyaedt --json session list

# Passo 2: se necessário, iniciar uma
pyaedt --json session start --version 2026.1 --non-graphical

# Passo 3: executar o script na porta escolhida
pyaedt --json run "<diretório-temp>/generated_script.py" --port 50051

Regras:

• Sempre determine a porta alvo primeiro.
• Se várias instâncias estiverem em execução, apresente a lista completa e pergunte qual porta usar.
• Não diga ao usuário para executar o script gerado manualmente se o fluxo de trabalho exigir execução automática.
• Scripts gerados destinados a uma instância AEDT existente devem usar new_desktop=False.

Fluxo de trabalho 7: Exportar dados do design

# Se a instância tiver exatamente um projeto e um design, os seletores podem ser omitidos
pyaedt --json export screenshot --port 50051 --path "<diretório-temp>/preview.jpg"
pyaedt --json export config --port 50051 --output "<diretório-temp>/config.json" --overwrite

# Se ambíguo, especifique o(s) seletor(es) ausente(s)
pyaedt --json export screenshot --port 50051 --project "PatchAntenna" --design "H

…

[truncado para tradução]