shou0715-Arthur/pyaedt-cli

Habilidad de la CLI de PyAEDT

Tienes acceso a la CLI pyaedt para interactuar con ANSYS Electronics Desktop (AEDT). Esta habilidad te enseña cómo usarla de manera efectiva.

Verificación previa (ejecutar primero)

Antes de cualquier comando de la CLI, verifica que pyaedt esté instalado:

pyaedt --json version

Si el comando falla, detente e indica al usuario que lo instale primero usando el objetivo de instalación all para habilitar todas las capacidades.

pip install pyaedt[all]

---

Invocar la CLI

Antes de ejecutar cualquier comando, resuelve el binario pyaedt una vez:

1. Intenta pyaedt directamente. Si está en el PATH del sistema, úsalo tal cual.
2. Si no se encuentra, recurre al binario local del entorno virtual en el directorio de trabajo actual:
   • Windows: .venv\Scripts\pyaedt
   • Linux/macOS: .venv/bin/pyaedt

Todos los ejemplos usan pyaedt por brevedad. Reemplázalo con la ruta resuelta si es necesario.

Directorio de trabajo para artefactos generados

Usa directorios temporales para todas las exportaciones y archivos generados a menos que el usuario especifique lo contrario.

Reglas:

• Crea un subdirectorio específico para la tarea bajo el directorio temporal del sistema operativo
• Usa tempfile.mkdtemp(prefix="pyaedt-skill-") (Python), $env:TEMP (Windows), o ${TMPDIR:-/tmp} (Linux/macOS)
• No escribas en el repositorio o carpetas arbitrarias a menos que se solicite explícitamente
• Mueve los artefactos desde el directorio temporal solo después de una exportación exitosa si el usuario desea conservarlos

Referencia rápida:

import tempfile

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

Pasa esta ruta a --path o --output en los comandos de exportación.

Usa --json para comandos no interactivos

Usa --json para cada comando no interactivo para que la salida se mantenga estructurada y analizable por máquina.

La salida JSON devuelve: {"status": "ok", "data": {...}} o {"status": "error", "error": "message"}

Siempre analiza el campo status antes de usar data. Nunca confíes en la salida legible por humanos.

Excepciones:

• session attach lanza una consola interactiva, por lo que el modo humano es aceptable.
• Los comandos doc abren páginas del navegador y generalmente no se consumen como salida de automatización estructurada.

Forma actual de la CLI

Los comandos están organizados como:

pyaedt [--json] <grupo> <comando> [opciones]

Grupos disponibles en la CLI actual:

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

Comandos de nivel superior:

• version
• aedt-versions

No inventes otros grupos de comandos o comandos que no existan en la CLI actual. Si una operación requerida no es compatible con la CLI, informa al usuario en lugar de intentar solucionarlo.

Modelo basado en puertos

La CLI actual está principalmente basada en puertos.

• session start lanza una nueva instancia de AEDT y devuelve su puerto gRPC.
• session list descubre las instancias de AEDT en ejecución.
• La mayoría de los comandos operativos requieren --port explícitamente.
• session attach también se puede usar para seleccionar una sesión AEDT existente, incluso mediante --project o --design, por lo que no todos los flujos de trabajo comienzan desde un puerto conocido.
• No hay un estado session connect persistido para reutilizar más adelante.

Implicación práctica:

# Descubrir o iniciar AEDT
pyaedt --json session list
pyaedt --json session start --version 2026.1 --non-graphical

# Luego pasa --port al comando que desees
pyaedt --json project list --port 50051
pyaedt --json run my_script.py --port 50051

Reglas de resolución de proyectos y diseños

Los comandos con ámbito de diseño usan un conjunto de reglas de resolución compartido. Esto es importante y debe aplicarse de manera consistente en las guías y ejemplos.

Comandos afectados:

• export screenshot
• export config
• session attach cuando se usa con --project o --design

Reglas de resolución:

• Si se proporcionan tanto --project como --design, úsalos directamente.
• Si solo se proporciona --project, ese proyecto debe contener exactamente un diseño.
• Si solo se proporciona --design, debe haber exactamente un proyecto abierto.
• Si no se proporciona ninguno, debe haber exactamente un proyecto abierto y exactamente un diseño en él.
• Si la selección es ambigua, el comando falla y se debe proporcionar el selector faltante.

Al ayudar a un usuario, no describas este comportamiento como una alternativa de "proyecto activo" o "diseño activo" a menos que el comando realmente use ese comportamiento. El comportamiento previsto es la resolución basada en unicidad.

Referencia de comandos

Comandos de nivel superior

Comando	Descripción
pyaedt --json version	Muestra la versión de PyAEDT
pyaedt --json aedt-versions	Lista las versiones de AEDT instaladas en la máquina

Gestión de sesiones

Comando	Descripción
pyaedt --json session start --version 2026.1 [--port 50051] [--non-graphical]	Inicia una nueva instancia de AEDT
pyaedt --json session list	Lista las instancias de AEDT en ejecución con PID, versión y puerto
pyaedt --json session stop --port 50051	Detiene una instancia específica de AEDT por puerto
pyaedt --json session stop --all	Cierra todas las instancias de AEDT.
pyaedt session attach [--port 50051] [--project NOMBRE] [--design NOMBRE]	Lanza una consola interactiva de PyAEDT conectada a una instancia en ejecución

Notas:

• session attach puede funcionar de forma interactiva si se omite --port y el usuario selecciona una instancia.
• --project o --design con session attach solo funciona para instancias gRPC con un puerto utilizable.

Comandos de proyecto

Se requiere puerto para todos los comandos de proyecto para especificar a qué instancia de AEDT apuntar.

Comando	Descripción
pyaedt --json project list --port 50051	Lista todos los proyectos abiertos y sus diseños
pyaedt --json project open "C:/ruta/al/archivo.aedt" --port 50051 [--non-graphical]	Abre un archivo de proyecto AEDT
pyaedt --json project save --port 50051 [--path "C:/nuevo/archivo.aedt"]	Guarda el proyecto activo, opcionalmente como un nuevo archivo
pyaedt --json project create --name ProyectoA --port 50051	Crea un proyecto. Usa --name.
pyaedt --json project create --project ProyectoA --design Diseno1 --type Hfss --port 50051	Crea un diseño dentro de un proyecto existente. Usa --project + --design + --type.
pyaedt --json project close --port 50051 [--project ProyectoA]	Cierra un proyecto, o el proyecto activo si se omite

Comportamiento de project create:

• --name es para la creación de proyectos.
• --project + --design + --type es para la creación de diseños.
• No mezcles --name con --design / --type.

Valores compatibles de --type:

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

Comandos de script

Comando	Descripción
pyaedt --json run "ruta/al/script.py" --port 50051	Ejecuta un script de Python dentro de AEDT

Comandos de exportación

Comando	Descripción
pyaedt --json export screenshot --port 50051 [--path preview.jpg] [--project NOMBRE] [--design NOMBRE]	Captura una captura de pantalla para un diseño resuelto
pyaedt --json export config --port 50051 [--output config.json] [--project NOMBRE] [--design NOMBRE] [--overwrite]	Exporta un JSON de configuración de diseño

Ambos comandos tienen ámbito de diseño y, por lo tanto, siguen las reglas de resolución de proyecto/diseño compartidas anteriores.

Documentación

Comando	Descripción
pyaedt doc	Abre la página de inicio de la documentación y muestra ayuda
pyaedt doc examples	Abre la sección de ejemplos
pyaedt doc github	Abre el repositorio de GitHub
pyaedt doc user-guide	Abre la guía del usuario
pyaedt doc getting-started	Abre la documentación de inicio
pyaedt doc installation	Abre la documentación de instalación
pyaedt doc api	Abre la referencia de la API
pyaedt doc changelog [VERSION]	Abre el registro de cambios
pyaedt doc issues	Abre la página de problemas
pyaedt doc search <palabras clave>	Busca en la documentación en línea

Flujos de trabajo comunes

Flujo de trabajo 1: Descubrir o iniciar AEDT

# Verificar instancias en ejecución
pyaedt --json session list

# Si no hay ninguna en ejecución, iniciar una
pyaedt --json session start --version 2026.1 --non-graphical

Regla de decisión:

• Si session list no devuelve procesos, inicia AEDT.
• Si devuelve un proceso, reutiliza ese puerto.
• Si devuelve múltiples procesos, pregunta al usuario qué puerto usar.

Flujo de trabajo 2: Inspeccionar proyectos en un puerto

pyaedt --json project list --port 50051

Usa esto primero cuando necesites entender qué selectores de proyecto y diseño se requieren.

Flujo de trabajo 3: Crear un proyecto o un diseño

# Crear un proyecto. Usa --name SOLAMENTE (NO agregues --design o --type)
pyaedt --json project create --name "AntenaParche" --port 50051

# Crear un diseño en un proyecto existente. Usa --project + --design + --type SOLAMENTE (NO agregues --name)
pyaedt --json project create --project "AntenaParche" --design "HFSSDesign1" --type Hfss --port 50051

Flujo de trabajo 4: Exploración interactiva con session attach

Usa session attach como la primera opción cuando el usuario desee explorar, depurar o iterar sobre un diseño de forma interactiva. Abre una consola interactiva de Python que ya está conectada a la sesión AEDT de destino. desktop está preinyectado, por lo que se pueden emitir comandos de PyAEDT uno por uno sin escribir un script completo.

# Adjuntar a una instancia en ejecución (puerto opcional; solicita si se omite)
pyaedt session attach --port 50051

# Dentro de la consola interactiva de Python, la sesión ya está activa:
# >>> 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)

Enviar código multilínea a la consola interactiva de Python

Cuando el agente envía código a la consola interactiva de Python que abarca más de una línea (bucles, condicionales, definiciones de funciones, etc.), pegarlo directamente provoca un IndentationError o SyntaxError porque la consola trata cada línea como una entrada separada.

Siempre envuelve los bloques multilínea en exec(), codificando todos los saltos de línea como \n dentro de una sola cadena:

# Falla porque la consola se rompe en el cuerpo del bucle
for i in range(3):
    print(i)

# Correcto: enviar como una sola llamada exec()
exec("for i in range(3):\n    print(i)")

Reglas:

• Usa exec() para cualquier bloque que contenga código indentado (bucles, if, with, definiciones de funciones o clases).
• Las líneas de una sola declaración (importaciones, asignaciones, llamadas a funciones) no necesitan exec().
• Escapa todas las comillas dobles internas como \" si el delimitador externo es ", o usa literales de cadena concatenados como se muestra arriba.
• Mantén las llamadas exec() lo más cortas posible; si el bloque crece más allá de ~10 líneas, prefiere guardar un script temporal y usar run en su lugar.

Cuándo preferir el comando session attach sobre el comando run:

Situación	Enfoque preferido
Explorar el estado del diseño, objetivo desconocido	session attach
Depurar un paso fallido interactivamente	session attach
Ajustes aislados de geometría / parámetros	session attach
Iterar rápidamente en unos pocos comandos	session attach
Flujo de trabajo definido, repetible y de múltiples pasos	run
CI / headless / pipeline automatizado	run
Flujo de trabajo tiene más de ~5 pasos	run
Trazabilidad y registro requeridos	run

Prefiere session attach primero. Gradua a run solo una vez que el flujo de trabajo sea conocido y necesite ser repetible o automatizado.

Trabajar con múltiples diseños simultáneamente

Cuando el usuario necesita trabajar en más de un diseño al mismo tiempo, abre una consola interactiva de Python separada para cada diseño en lugar de cambiar entre diseños dentro de una sola consola. Esto mantiene cada diseño activo y editable sin cerrar ni liberar ninguno de ellos.

# Terminal 1: consola para el Diseño A
pyaedt session attach --port 50051 --project "ProyectoA" --design "DiseñoA"

# Terminal 2: consola para el Diseño B (mismo o diferente proyecto)
pyaedt session attach --port 50051 --project "ProyectoA" --design "DiseñoB"

# Terminal 3: consola para un diseño en un proyecto diferente
pyaedt session attach --port 50051 --project "ProyectoB" --design "DiseñoC"

Reglas:

• Cada consola mantiene su propio objeto PyAEDT vinculado a un diseño específico. Cerrar una consola no cierra las demás.
• Todas las consolas comparten la misma instancia de AEDT (mismo --port), por lo que los cambios realizados en una son visibles en AEDT de inmediato.
• No llames a desktop.release_desktop() o aedt_app.release_desktop() dentro de ninguna de estas consolas a menos que tengas la intención de apagar AEDT para todas las consolas abiertas.
• Si los diseños residen en diferentes instancias de AEDT, usa el --port correspondiente para cada consola.

Flujo de trabajo 5: Ejecutar automatización

pyaedt --json run "<dir-temp>/setup_antenna.py" --port 50051

Flujo de trabajo 6: Ejecución de script generado

Usa este flujo de trabajo cada vez que se haya generado un script y deba ejecutarse automáticamente.

# Paso 1: descubrir instancias
pyaedt --json session list

# Paso 2: si es necesario, iniciar una
pyaedt --json session start --version 2026.1 --non-graphical

# Paso 3: ejecutar el script en el puerto elegido
pyaedt --json run "<dir-temp>/generated_script.py" --port 50051

Reglas:

• Siempre determina primero el puerto de destino.
• Si hay varias instancias en ejecución, presenta la lista completa y pregunta qué puerto usar.
• No digas al usuario que ejecute el script generado manualmente si el flujo de trabajo requiere ejecución automática.
• Los scripts generados destinados a una instancia AEDT existente deben usar new_desktop=False.

Flujo de trabajo 7: Exportar datos de diseño

# Si la instancia tiene exactamente un proyecto y un diseño, los selectores se pueden omitir
pyaedt --json export screenshot --port 50051 --path "<dir-temp>/preview.jpg"
pyaedt --json export config --port 50051 --output "<dir-temp>/config.json" --overwrite

# Si es ambiguo, especifica el(los) selector(es) faltante(s)
pyaedt --json export screenshot --port 50051 --project "AntenaParche" --design "HFSSDesign1" --path "<dir-temp>/preview.jpg"
pyaedt --json export config --port 50051 --project "AntenaParche" --design "HFSSDesign1" --output "<dir-temp>/config.json" --overwrite

Flujo de trabajo 8: Adjuntar a un diseño conocido

# Adjuntar a una instancia en ejecución y un diseño específico
pyaedt session attach --port 50051 --project "ProyectoA" --design "DiseñoA"

Fragmentos útiles

Predecir la ruta para session attach

Si necesitas encontrar el puerto de una instancia en ejecución para un proyecto específico:

pyaedt --json session list

Verificar el estado de AEDT

pyaedt --json session list