shou0715-Arthur/pyaedt-cli

PyAEDT CLI-Fertigkeit

Sie haben Zugriff auf die pyaedt-CLI zur Interaktion mit ANSYS Electronics Desktop (AEDT). Diese Fertigkeit lehrt Sie, wie Sie diese effektiv einsetzen.

Vorab-Prüfung (zuerst ausführen)

Überprüfen Sie vor jedem CLI-Befehl, ob pyaedt installiert ist:

pyaedt --json version

Wenn der Befehl fehlschlägt, stoppen Sie und weisen Sie den Benutzer an, es zuerst mit dem Installationsziel all zu installieren, um alle Funktionen zu aktivieren.

pip install pyaedt[all]

---

Aufruf der CLI

Lösen Sie vor dem Ausführen eines Befehls das Binärprogramm pyaedt einmal auf:

1. Versuchen Sie pyaedt direkt. Wenn es im System-PATH vorhanden ist, verwenden Sie es wie besehen.
2. Wenn nicht gefunden, greifen Sie auf das lokale venv-Binärprogramm im aktuellen Arbeitsverzeichnis zurück:
   • Windows: .venv\Scripts\pyaedt
   • Linux/macOS: .venv/bin/pyaedt

Alle Beispiele verwenden der Kürze halber pyaedt. Ersetzen Sie es bei Bedarf durch den aufgelösten Pfad.

Arbeitsverzeichnis für generierte Artefakte

Verwenden Sie temporäre Verzeichnisse für alle Exporte und generierten Dateien, sofern der Benutzer nichts anderes angibt.

Regeln:

• Erstellen Sie ein aufgabenspezifisches Unterverzeichnis unter dem temporären OS-Verzeichnis
• Verwenden Sie tempfile.mkdtemp(prefix="pyaedt-skill-") (Python), $env:TEMP (Windows) oder ${TMPDIR:-/tmp} (Linux/macOS)
• Schreiben Sie nicht in das Repository oder beliebige Ordner, es sei denn, es wird ausdrücklich verlangt
• Verschieben Sie Artefakte aus dem temporären Verzeichnis erst nach erfolgreichem Export, wenn der Benutzer sie behalten möchte

Kurzreferenz:

import tempfile

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

Übergeben Sie diesen Pfad an --path oder --output in Exportbefehlen.

Verwenden Sie --json für nicht-interaktive Befehle

Verwenden Sie --json für jeden nicht-interaktiven Befehl, damit die Ausgabe strukturiert und maschinenlesbar bleibt.

JSON-Ausgabe gibt zurück: {"status": "ok", "data": {...}} oder {"status": "error", "error": "message"}

Analysieren Sie immer das Feld status, bevor Sie data verwenden. Verlassen Sie sich niemals auf menschenlesbare Ausgabe.

Ausnahmen:

• session attach startet eine interaktive Konsole, daher ist der menschliche Modus akzeptabel.
• doc-Befehle öffnen Browser-Seiten und werden normalerweise nicht als strukturierte Automatisierungsausgabe konsumiert.

Aktuelle CLI-Struktur

Befehle sind organisiert als:

pyaedt [--json] <gruppe> <befehl> [optionen]

Verfügbare Gruppen in der aktuellen CLI:

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

Top-Level-Befehle:

• version
• aedt-versions

Erfinden Sie keine anderen Befehlsgruppen oder -befehle, die in der aktuellen CLI nicht existieren. Wenn ein erforderlicher Vorgang nicht von der CLI unterstützt wird, melden Sie dies dem Benutzer, anstatt zu versuchen, ihn zu umgehen.

Portbasiertes Modell

Die aktuelle CLI ist hauptsächlich portbasiert.

• session start startet eine neue AEDT-Instanz und gibt ihren gRPC-Port zurück.
• session list entdeckt laufende AEDT-Instanzen.
• Die meisten Betriebsbefehle erfordern explizit --port.
• session attach kann auch verwendet werden, um eine vorhandene AEDT-Sitzung auszuwählen, auch mittels --project oder --design, sodass nicht jeder Workflow von einem bekannten Port ausgeht.
• Es gibt keinen persistenten session connect-Zustand, der später wiederverwendet werden kann.

Praktische Auswirkung:

# AEDT entdecken oder starten
pyaedt --json session list
pyaedt --json session start --version 2026.1 --non-graphical

# Dann übergeben Sie --port an den gewünschten Befehl
pyaedt --json project list --port 50051
pyaedt --json run my_script.py --port 50051

Regeln für die Auflösung von Projekten und Designs

Designbezogene Befehle verwenden einen gemeinsamen Satz von Auflösungsregeln. Dies ist wichtig und sollte in Anleitungen und Beispielen konsistent angewendet werden.

Betroffene Befehle:

• export screenshot
• export config
• session attach bei Verwendung mit --project oder --design

Auflösungsregeln:

• Wenn sowohl --project als auch --design angegeben sind, verwenden Sie diese direkt.
• Wenn nur --project angegeben ist, muss dieses Projekt genau ein Design enthalten.
• Wenn nur --design angegeben ist, muss genau ein Projekt geöffnet sein.
• Wenn keines angegeben ist, muss genau ein geöffnetes Projekt mit genau einem Design vorhanden sein.
• Wenn die Auswahl mehrdeutig ist, schlägt der Befehl fehl, und der fehlende Selektor muss angegeben werden.

Wenn Sie einem Benutzer helfen, beschreiben Sie dieses Verhalten nicht als Fallback auf "aktives Projekt" oder "aktives Design", es sei denn, der Befehl verwendet dieses Verhalten tatsächlich. Das beabsichtigte Verhalten ist eine auf Einzigartigkeit basierende Auflösung.

Befehlsreferenz

Top-Level-Befehle

Befehl	Beschreibung
pyaedt --json version	Zeigt die PyAEDT-Version an
pyaedt --json aedt-versions	Listet installierte AEDT-Versionen auf dem Rechner auf

Sitzungsverwaltung

Befehl	Beschreibung
pyaedt --json session start --version 2026.1 [--port 50051] [--non-graphical]	Startet eine neue AEDT-Instanz
pyaedt --json session list	Listet laufende AEDT-Instanzen mit PID, Version und Port auf
pyaedt --json session stop --port 50051	Stoppt eine bestimmte AEDT-Instanz anhand des Ports
pyaedt --json session stop --all	Schließt alle AEDT-Instanzen
pyaedt session attach [--port 50051] [--project NAME] [--design NAME]	Startet eine interaktive PyAEDT-Konsole, die an eine laufende Instanz angehängt ist

Hinweise:

• session attach kann interaktiv arbeiten, wenn --port weggelassen wird und der Benutzer eine Instanz auswählt.
• --project oder --design mit session attach funktioniert nur für gRPC-Instanzen mit einem nutzbaren Port.

Projektbefehle

Port ist für alle Projektbefehle erforderlich, um anzugeben, welche AEDT-Instanz anvisiert werden soll.

Befehl	Beschreibung
pyaedt --json project list --port 50051	Listet alle geöffneten Projekte und ihre Designs auf
pyaedt --json project open "C:/path/to/file.aedt" --port 50051 [--non-graphical]	Öffnet eine AEDT-Projektdatei
pyaedt --json project save --port 50051 [--path "C:/new/file.aedt"]	Speichert das aktive Projekt, optional als neue Datei
pyaedt --json project create --name ProjektA --port 50051	Erstellt ein Projekt. Verwenden Sie --name.
pyaedt --json project create --project ProjektA --design Design1 --type Hfss --port 50051	Erstellt ein Design innerhalb eines vorhandenen Projekts. Verwenden Sie --project + --design + --type.
pyaedt --json project close --port 50051 [--project ProjektA]	Schließt ein Projekt oder das aktive Projekt, wenn nicht angegeben

project create-Verhalten:

• --name ist für die Projekterstellung.
• --project + --design + --type ist für die Designerstellung.
• Mischen Sie --name nicht mit --design / --type.

Unterstützte --type-Werte:

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

Skriptbefehle

Befehl	Beschreibung
pyaedt --json run "path/to/script.py" --port 50051	Führt ein Python-Skript innerhalb von AEDT aus

Exportbefehle

Befehl	Beschreibung
pyaedt --json export screenshot --port 50051 [--path preview.jpg] [--project NAME] [--design NAME]	Erstellt einen Screenshot für ein aufgelöstes Design
pyaedt --json export config --port 50051 [--output config.json] [--project NAME] [--design NAME] [--overwrite]	Exportiert eine Designkonfiguration als JSON

Beide Befehle sind designbezogen und folgen daher den oben genannten gemeinsamen Regeln zur Projekt-/Designauflösung.

Dokumentation

Befehl	Beschreibung
pyaedt doc	Öffnet die Startseite der Dokumentation und zeigt Hilfe an
pyaedt doc examples	Öffnet den Beispielbereich
pyaedt doc github	Öffnet das GitHub-Repository
pyaedt doc user-guide	Öffnet die Benutzeranleitung
pyaedt doc getting-started	Öffnet die Erste-Schritte-Dokumentation
pyaedt doc installation	Öffnet die Installationsdokumentation
pyaedt doc api	Öffnet die API-Referenz
pyaedt doc changelog [VERSION]	Öffnet das Änderungsprotokoll
pyaedt doc issues	Öffnet die Problemseite
pyaedt doc search <suchbegriffe>	Durchsucht die Online-Dokumentation

Häufige Arbeitsabläufe

Arbeitsablauf 1: AEDT entdecken oder starten

# Nach laufenden Instanzen suchen
pyaedt --json session list

# Wenn keine läuft, eine starten
pyaedt --json session start --version 2026.1 --non-graphical

Entscheidungsregel:

• Wenn session list keine Prozesse zurückgibt, starten Sie AEDT.
• Wenn ein Prozess zurückgegeben wird, verwenden Sie diesen Port wieder.
• Wenn mehrere Prozesse zurückgegeben werden, fragen Sie den Benutzer, welcher Port verwendet werden soll.

Arbeitsablauf 2: Projekte auf einem Port überprüfen

pyaedt --json project list --port 50051

Verwenden Sie dies zuerst, wenn Sie verstehen müssen, welche Projekt- und Designselektoren erforderlich sind.

Arbeitsablauf 3: Ein Projekt oder ein Design erstellen

# Ein Projekt erstellen. Verwenden Sie NUR --name (fügen Sie NICHT --design oder --type hinzu)
pyaedt --json project create --name "PatchAntenne" --port 50051

# Ein Design in einem bestehenden Projekt erstellen. Verwenden Sie NUR --project + --design + --type (fügen Sie NICHT --name hinzu)
pyaedt --json project create --project "PatchAntenne" --design "HFSSDesign1" --type Hfss --port 50051

Arbeitsablauf 4: Interaktive Erkundung mit session attach

Verwenden Sie session attach als erste Wahl, wenn der Benutzer ein Design interaktiv erkunden, debuggen oder iterieren möchte. Es öffnet eine interaktive Python-Konsole, die bereits mit der Ziel-AEDT-Sitzung verbunden ist. desktop ist vorab injiziert, sodass PyAEDT-Befehle nacheinander ausgegeben werden können, ohne ein vollständiges Skript zu schreiben.

# An eine laufende Instanz anhängen (Port optional; fordert zur Eingabe auf, wenn nicht angegeben)
pyaedt session attach --port 50051

# Innerhalb der interaktiven Python-Konsole ist die Sitzung bereits aktiv:
# >>> 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)

Senden von mehrzeiligem Code an die interaktive Python-Konsole

Wenn der Agent Code an die interaktive Python-Konsole sendet, der mehr als eine Zeile umfasst (Schleifen, Bedingungen, Funktionsdefinitionen usw.), führt ein direktes Einfügen zu einem IndentationError oder SyntaxError, da die Konsole jede Zeile als separate Eingabe behandelt.

Umwickeln Sie mehrzeilige Blöcke immer mit exec() und codieren Sie alle Zeilenumbrüche als \n innerhalb eines einzelnen Strings:

# Schlägt fehl, weil die Konsole am Schleifenkörper abbricht
for i in range(3):
    print(i)

# Richtig: als einzelnen exec()-Aufruf senden
exec("for i in range(3):\n    print(i)")

Regeln:

• Verwenden Sie exec() für jeden Block, der eingerückten Code enthält (Schleifen, if, with, Funktions- oder Klassendefinitionen).
• Einzeilige Anweisungen (Imports, Zuweisungen, Funktionsaufrufe) benötigen kein exec().
• Escapen Sie alle inneren doppelten Anführungszeichen als \", wenn das äußere Trennzeichen " ist, oder verwenden Sie verkettete String-Literale wie oben gezeigt.
• Halten Sie exec()-Aufrufe so kurz wie möglich; wenn der Block über ~10 Zeilen hinauswächst, bevorzugen Sie das Speichern eines temporären Skripts und die Verwendung von run.

Wann der Befehl session attach gegenüber dem Befehl run zu bevorzugen ist:

Situation	Bevorzugter Ansatz
Erkundung des Designzustands, unbekanntes Ziel	session attach
Interaktives Debuggen eines fehlschlagenden Schritts	session attach
Einmalige Geometrie-/Parameteranpassungen	session attach
Schnelles Iterieren über wenige Befehle	session attach
Definierter, wiederholbarer, mehrschrittiger Workflow	run
CI / headless / automatisierte Pipeline	run
Workflow mit mehr als ~5 Schritten	run
Rückverfolgbarkeit und Protokollierung erforderlich	run

Bevorzugen Sie zuerst session attach. Wechseln Sie zu run, sobald der Workflow bekannt ist und wiederholbar oder automatisierbar sein muss.

Gleichzeitiges Arbeiten mit mehreren Designs

Wenn der Benutzer an mehr als einem Design gleichzeitig arbeiten muss, öffnen Sie für jedes Design eine separate interaktive Python-Konsole, anstatt Designs innerhalb einer einzigen Konsole zu wechseln. Dadurch bleibt jedes Design live und bearbeitbar, ohne dass eines geschlossen oder freigegeben werden muss.

# Terminal 1: Konsole für Design A
pyaedt session attach --port 50051 --project "ProjektA" --design "DesignA"

# Terminal 2: Konsole für Design B (gleiches oder anderes Projekt)
pyaedt session attach --port 50051 --project "ProjektA" --design "DesignB"

# Terminal 3: Konsole für ein Design in einem anderen Projekt
pyaedt session attach --port 50051 --project "ProjektB" --design "DesignC"

Regeln:

• Jede Konsole hält ihr eigenes PyAEDT-Objekt, das an ein bestimmtes Design gebunden ist. Das Schließen einer Konsole schließt nicht die anderen.
• Alle Konsolen teilen sich dieselbe AEDT-Instanz (derselbe --port), sodass Änderungen in einer Konsole sofort in AEDT sichtbar sind.
• Rufen Sie nicht desktop.release_desktop() oder aedt_app.release_desktop() in einer dieser Konsolen auf, es sei denn, Sie möchten AEDT absichtlich für alle geöffneten Konsolen herunterfahren.
• Wenn die Designs in verschiedenen AEDT-Instanzen leben, verwenden Sie den passenden --port für jede Konsole.

Arbeitsablauf 5: Automatisierung ausführen

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

Arbeitsablauf 6: Ausführung generierter Skripte

Verwenden Sie diesen Workflow immer dann, wenn ein Skript generiert wurde und automatisch ausgeführt werden muss.

# Schritt 1: Instanzen entdecken
pyaedt --json session list

# Schritt 2: falls nötig, eine starten
pyaedt --json session start --version 2026.1 --non-graphical

# Schritt 3: das Skript auf dem gewählten Port ausführen
pyaedt --json run "<temp-verz>/generated_script.py" --port 50051

Regeln:

• Bestimmen Sie immer zuerst den Zielport.
• Wenn mehrere Instanzen laufen, präsentieren Sie die vollständige Liste und fragen Sie, welcher Port verwendet werden soll.
• Weisen Sie den Benutzer nicht an, das generierte Skript manuell auszuführen, wenn der Workflow eine automatische Ausführung erfordert.
• Generierte Skripte, die für eine vorhandene AEDT-Instanz bestimmt sind, sollten new_desktop=False verwenden.

Arbeitsablauf 7: Designdaten exportieren

# Wenn die Instanz genau ein Projekt und ein Design hat, können Selektoren weggelassen werden
pyaedt --json export screenshot --port 50051 --path "<temp-verz>/preview.jpg"
pyaedt --json export config --port 50051 --output "<temp-verz>/config.json" --overwrite

# Bei Mehrdeutigkeit den/die fehlenden Selektor(en) angeben
pyaedt --json export screenshot --port 50051 --project "PatchAntenne" --design "HFSSDesign1" --path "<temp-verz>/preview.jpg"