Community程式設計與開發github.com

shou0715-Arthur/pyaedt-cli

用於透過 PyAEDT CLI 與 ANSYS AEDT 互動。當需要啟動或檢查 AEDT 會話、管理專案、建立設計、執行腳本、匯出螢幕截圖或設定檔，或從工作區虛擬環境使用 PyAEDT 命令列時觸發。

pyaedt-cli 是什麼？

此技能提供與 ANSYS Electronics Desktop (AEDT) 互動的完整介面，透過 PyAEDT 命令列工具實現。它引導 AI 代理程式執行關鍵工作流程，例如探索或啟動 AEDT 實例、管理專案和設計、執行自動化腳本，以及匯出設計資料（如螢幕截圖和設定 JSON）。該技能強調結構化的 JSON 輸出以便於機器解析、基於埠的實例管理，以及清晰的命令分組（包括 session、project、script、export、panels 和 doc）。它支援所有主要平台（Windows、Linux、macOS），並提供在互動式 `session attach` 控制台（適合探索和除錯）與 `run` 命令（適合可重複、自動化的工作流程）之間切換的實用指引，包括處理多行 Python 程式碼的特定規則。

相容平台~Claude Code~Codex CLI~Cursor
Part ofMobileAgent Workflows
npx skills add https://github.com/shou0715-Arthur/pyaedt-examples-and-skills/tree/main/skills/pyaedt-cli

Installed? Explore more 程式設計與開發 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

查看原文→瀏覽所有技能

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

說明文件

PyAEDT CLI 技能

您可以使用 pyaedt CLI 來與 ANSYS Electronics Desktop (AEDT) 互動。此技能教您如何有效地使用它。

預先檢查（先執行）

在任何 CLI 命令之前，請驗證 pyaedt 是否已安裝：

pyaedt --json version

如果命令失敗，請停止，並指示使用者先使用 all 安裝目標進行安裝，以啟用完整功能。

pip install pyaedt[all]

呼叫 CLI

在執行任何命令之前，請解析 pyaedt 二進位檔一次：

  1. 直接嘗試 pyaedt。如果它在系統 PATH 中，則直接使用它。
  2. 如果找不到，則回退到目前工作目錄中 venv-local 的二進位檔：
    • Windows：.venv\Scripts\pyaedt
    • Linux/macOS：.venv/bin/pyaedt

為簡潔起見，所有範例均使用 pyaedt。如有需要，請將其替換為已解析的路徑。

產出檔案的工作目錄

除非使用者另有指定，否則所有匯出和產生的檔案均使用暫存目錄。

規則：

  • 在作業系統暫存目錄下建立一個任務特定的子目錄
  • 使用 tempfile.mkdtemp(prefix="pyaedt-skill-") (Python)、$env:TEMP (Windows) 或 ${TMPDIR:-/tmp} (Linux/macOS)
  • 除非明確要求，否則不要寫入儲存庫或任意資料夾
  • 如果使用者想要保留檔案，請在成功匯出後再從暫存目錄移動檔案

快速參考：

import tempfile

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

在匯出命令中將此路徑傳遞給 --path 或 --output。

對非互動式命令使用 --json

對每個非互動式命令使用 --json，以便輸出保持結構化且可機器解析。

JSON 輸出會傳回：{"status": "ok", "data": {...}} 或 {"status": "error", "error": "message"}

在使用 data 之前，始終解析 status 欄位。切勿依賴人類可讀的輸出。

例外情況：

  • session attach 會啟動一個互動式控制台，因此人類模式是可以接受的。
  • doc 命令會開啟瀏覽器頁面，通常不會作為結構化的自動化輸出來使用。

目前的 CLI 結構

命令按以下方式組織：

pyaedt [--json] <group> <command> [options]

目前 CLI 中可用的群組：

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

頂層命令：

  • version
  • aedt-versions

請勿發明目前 CLI 中不存在的其他命令群組或命令。 如果 CLI 不支援所需的操作，請向使用者報告，而不是嘗試變通解決。

基於埠的模型

目前的 CLI 主要基於埠。

  • session start 會啟動一個新的 AEDT 實例並傳回其 gRPC 埠。
  • session list 會發現正在運行的 AEDT 實例。
  • 大多數操作命令需要明確指定 --port。
  • session attach 也可以用來選擇現有的 AEDT 會話，包括透過 --project 或 --design，因此並非每個工作流程都從已知的埠開始。
  • 沒有永久保存的 session connect 狀態可以稍後重複使用。

實際影響：

# 發現或啟動 AEDT
pyaedt --json session list
pyaedt --json session start --version 2026.1 --non-graphical

# 然後將 --port 傳遞給您想要的命令
pyaedt --json project list --port 50051
pyaedt --json run my_script.py --port 50051

專案與設計解析規則

設計範圍的命令使用一組共享的解析規則。這很重要，應在指南和範例中一致地應用。

受影響的命令：

  • export screenshot
  • export config
  • session attach 當與 --project 或 --design 一起使用時

解析規則：

  • 如果同時提供了 --project 和 --design，則直接使用它們。
  • 如果只提供了 --project，則該專案必須只包含一個設計。
  • 如果只提供了 --design，則必須只開啟一個專案。
  • 如果兩者都沒有提供，則必須只開啟一個專案，且其中只有一個設計。
  • 如果選擇不明確，命令將會失敗，並且必須提供缺失的選擇器。

在幫助使用者時，除非命令實際使用該行為，否則不要將此行為描述為「active project」或「active design」回退。預期的行為是基於唯一性的解析。

命令參考

頂層命令

命令說明
pyaedt --json version顯示 PyAEDT 版本
pyaedt --json aedt-versions列出機器上已安裝的 AEDT 版本

會話管理

命令說明
pyaedt --json session start --version 2026.1 [--port 50051] [--non-graphical]啟動一個新的 AEDT 實例
pyaedt --json session list列出正在運行的 AEDT 實例及其 PID、版本和埠
pyaedt --json session stop --port 50051按埠停止特定的 AEDT 實例
pyaedt --json session stop --all關閉所有 AEDT 實例。
pyaedt session attach [--port 50051] [--project NAME] [--design NAME]啟動一個連接到運行中實例的互動式 PyAEDT 控制台

注意事項：

  • 如果省略 --port 且使用者選擇一個實例，session attach 可以互動式工作。
  • 搭配 session attach 使用的 --project 或 --design 僅適用於具有可用埠的 gRPC 實例。

專案命令

所有專案命令都需要指定埠，以指向目標 AEDT 實例。

命令說明
pyaedt --json project list --port 50051列出所有開啟的專案及其設計
pyaedt --json project open "C:/path/to/file.aedt" --port 50051 [--non-graphical]開啟一個 AEDT 專案檔
pyaedt --json project save --port 50051 [--path "C:/new/file.aedt"]儲存作用中的專案，可選擇另存為新檔案
pyaedt --json project create --name ProjectA --port 50051建立一個專案。使用 --name。
pyaedt --json project create --project ProjectA --design Design1 --type Hfss --port 50051在現有專案內建立一個設計。使用 --project + --design + --type。
pyaedt --json project close --port 50051 [--project ProjectA]關閉一個專案，如果省略則關閉作用中的專案

project create 行為：

  • --name 用於建立專案。
  • --project + --design + --type 用於建立設計。
  • 不要將 --name 與 --design / --type 混合使用。

支援的 --type 值：

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

腳本命令

命令說明
pyaedt --json run "path/to/script.py" --port 50051在 AEDT 內部執行 Python 腳本

匯出命令

命令說明
pyaedt --json export screenshot --port 50051 [--path preview.jpg] [--project NAME] [--design NAME]為已解析的設計擷取螢幕截圖
pyaedt --json export config --port 50051 [--output config.json] [--project NAME] [--design NAME] [--overwrite]匯出設計設定 JSON

這兩個命令都屬於設計範圍，因此遵循上述共享的專案/設計解析規則。

文件

命令說明
pyaedt doc開啟文件首頁並列印幫助
pyaedt doc examples開啟範例章節
pyaedt doc github開啟 GitHub 儲存庫
pyaedt doc user-guide開啟使用者指南
pyaedt doc getting-started開啟入門文件
pyaedt doc installation開啟安裝文件
pyaedt doc api開啟 API 參考
pyaedt doc changelog [VERSION]開啟更新日誌
pyaedt doc issues開啟問題頁面
pyaedt doc search <keywords>搜尋線上文件

常見工作流程

工作流程 1：發現或啟動 AEDT

# 檢查正在運行的實例
pyaedt --json session list

# 如果沒有正在運行的，啟動一個
pyaedt --json session start --version 2026.1 --non-graphical

決定規則：

  • 如果 session list 沒有回傳任何程序，則啟動 AEDT。
  • 如果它回傳一個程序，則重複使用該埠。
  • 如果它回傳多個程序，詢問使用者要使用哪個埠。

工作流程 2：檢查某個埠上的專案

pyaedt --json project list --port 50051

當您需要了解需要哪些專案和設計選擇器時，請先使用此命令。

工作流程 3：建立專案或設計

# 建立一個專案。僅使用 --name（不要新增 --design 或 --type）
pyaedt --json project create --name "PatchAntenna" --port 50051

# 在現有專案中建立一個設計。僅使用 --project + --design + --type（不要新增 --name）
pyaedt --json project create --project "PatchAntenna" --design "HFSSDesign1" --type Hfss --port 50051

工作流程 4：使用 session attach 進行互動式探索

當使用者想要互動式地探索、除錯或迭代一個設計時，請使用 session attach 作為首選。它會開啟一個已經連接到目標 AEDT 會話的互動式 Python 控制台。desktop 已預先注入，因此可以一個接一個地發出 PyAEDT 命令，而無需編寫完整的腳本。

# 連接到一個正在運行的實例（埠為可選；如果省略則會提示）
pyaedt session attach --port 50051

# 在互動式 Python 控制台內部，會話已經存在：
# >>> 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)

將多行程式碼傳送到互動式 Python 控制台

當代理程式將跨越一行以上（迴圈、條件判斷、函數定義等）的程式碼傳送到互動式 Python 控制台時，直接貼上會導致 IndentationError 或 SyntaxError，因為控制台會將每行視為單獨的輸入。

始終將多行區塊包裝在 exec() 中，在單一字串內將所有換行符編碼為 \n：

# 由於控制台在迴圈主體處中斷而失敗
for i in range(3):
    print(i)

# 正確：作為單一 exec() 呼叫傳送
exec("for i in range(3):\n    print(i)")

規則：

  • 對任何包含縮排程式碼的區塊（迴圈、if、with、函數或類別定義）使用 exec()。
  • 單行語句（匯入、賦值、函數呼叫）不需要 exec()。
  • 如果外部分隔符是 "，則將所有內部雙引號逸出為 \"，或如上所示使用串聯的字串字面量。
  • 盡量保持 exec() 呼叫簡短；如果區塊超過約 10 行，更偏好將暫存腳本儲存後使用 run。

何時偏好 session attach 命令勝過 run 命令：

情況偏好方法
探索設計狀態，未知目標session attach
互動式除錯失敗步驟session attach
一次性幾何 / 參數調整session attach
快速迭代少量命令session attach
已定義、可重複、多步驟的工作流程run
CI / 無頭模式 / 自動化管道run
工作流程包含超過約 5 個步驟run
需要可追溯性和日誌記錄run

優先使用 session attach。只有在工作流程已知且需要可重複或自動化時，才升級到 run。

同時處理多個設計

當使用者需要同時處理多個設計時，請為每個設計開啟一個單獨的互動式 Python 控制台，而不是在單個控制台中切換設計。這樣可以保持每個設計都處於活躍且可編輯的狀態，無需關閉或釋放任何一個。

# 終端機 1：設計 A 的控制台
pyaedt session attach --port 50051 --project "ProjectA" --design "DesignA"

# 終端機 2：設計 B 的控制台（相同或不同的專案）
pyaedt session attach --port 50051 --project "ProjectA" --design "DesignB"

# 終端機 3：不同專案中設計的控制台
pyaedt session attach --port 50051 --project "ProjectB" --design "DesignC"

規則：

  • 每個控制台都持有自己的 PyAEDT 物件，綁定到一個特定的設計。關閉一個控制台不會關閉其他控制台。
  • 所有控制台共享同一個 AEDT 實例（相同的 --port），因此在一個控制台中做出的更改會立即在 AEDT 中可見。
  • 除非您有意要關閉所有開啟控制台的 AEDT，否則不要在任何這些控制台內部呼叫 desktop.release_desktop() 或 aedt_app.release_desktop()。
  • 如果設計存在於不同的 AEDT 實例中，請為每個控制台使用匹配的 --port。

工作流程 5：執行自動化

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

工作流程 6：產出的腳本執行

每當已產出腳本且必須自動執行時，請使用此工作流程。

# 步驟 1：發現實例
pyaedt --json session list

# 步驟 2：如有需要，啟動一個
pyaedt --json session start --version 2026.1 --non-graphical

# 步驟 3：在選擇的埠上執行腳本
pyaedt --json run "<temp-dir>/generated_script.py" --port 50051

規則：

  • 始終先確定目標埠。
  • 如果有多個實例在運行，請呈現完整列表並詢問要使用哪個埠。
  • 如果工作流程需要自動執行，請不要告訴使用者手動執行產出的腳本。
  • 為現有 AEDT 實例產出的腳本應使用 new_desktop=False。

工作流程 7：匯出設計資料

# 如果實例恰好只有一個專案和一個設計，則可以省略選擇器
pyaedt --json export screenshot --port 50051 --path "<temp-dir>/preview.jpg"
pyaedt --json export config --port 50051 --output "<temp-dir>/config.json" --overwrite

# 如果不明確，請指定缺失的選擇器
pyaedt --json export screenshot --port 50051 --project "PatchAntenna" --design "HFSSDesign1" --path "<temp-dir>/preview.jpg"
pyaedt --json export config --port 50051 --project "PatchAntenna" --design "HFSSDesign1" --output "<temp-dir>/config.json" --overwrite

工作流程 8：關閉

# 按埠停止一個特定的實例
pyaedt --json session stop --port 50051

# 或停止所有實例
pyaedt --json session stop --all

輸出處理規則

狀態處理

# 預期的 JSON 結構
{"status": "ok", "data": {...}}
{"status": "error", "error": "message"}

規則：

  • 僅當 status 為 ok 時才讀取 data。
  • 如果 status 為 error，則將錯誤訊息報告給使用者，不要假設任何資料有效。
  • 如果 status 既不是 ok 也不是 error，則視為無法解析的異常。

錯誤處理與重試策略

許多 CLI 錯誤是由於競態條件（AEDT 仍在啟動）、短暫的網路問題或非圖形模式下的過早命令發送引起的。

在將問題報告給使用者之前，請套用以下自動重試邏輯：

  1. 通訊相關錯誤（例如，Connection refused、503、timeout）：

    • 最多重試 3 次，每次間隔等待 5 秒。
    • 如果 3 次後仍然失敗，則檢查實例是否仍在運行 (session list)。如果已關閉，則建議使用者重新啟動它。

  2. 未知命令 / 解析錯誤：

    • 不要重試。立即報告給使用者，因為這些錯誤表明結構問題。

  3. session start 特定錯誤（例如，AEDT not found、License error）：

    • 如果找到錯誤報告，則不要重試。向使用者解釋該錯誤。啟動前始終使用 --non-graphical，除非使用者明確要求使用圖形模式。

限制與邊界情況

  1. 無 session connect 永久狀態：

    • 與某些使用持久會話句柄的 SDK 不同，此 CLI 不維護 session connect 以便在命令之間自動重複使用。必須在每個需要的命令上明確傳遞 --port。在兩次呼叫之間不要假設「活動」會話。

  2. 非圖形模式是預設配置：

    • 除非使用者明確要求使用圖形模式，否則使用 --non-graphical 啟動 AEDT 以節省資源並實現無頭自動化。

  3. 腳本執行隔離：

    • run 命令在目標 AEDT 會話內啟動一個新的 Python 程序。因此，在腳本執行之間變數狀態不會保留。如果使用者想要增量更新設計數據，請使用 session attach（互動式控制台）或將所有步驟組合在一個 .py 檔案中，然後使用 run 執行。

  4. 無 export screenshot 互動式預覽彈出：

    • export screenshot 命令將圖像寫入檔案。它不會在螢幕上顯示預覽。如果使用者想要互動式預覽，請指示他們使用圖形模式手動開啟 AEDT。

  5. 無設計命名空間隔離：

    • 在一個互動式控制台中對設計物件所做的更改可能會影響同一專案中其他控制台所持有的設計物件，具體取決於 AEDT 的內部狀態。如果發生無法解釋的行為，請重新附加到一個專用控制台。

  6. 平台特定的二進位路徑：

    • Windows：.venv\Scripts\pyaedt
    • Linux/macOS：.venv/bin/pyaedt

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

shou0715-Arthur/hfss-pyaedt

Automate ANSYS HFSS tasks on Windows through PyAEDT. Use when Codex needs to inspect the local HFSS environment, create or modify HFSS projects, set design variables, build simple geometry, create setups and sweeps, run analyses, or export Touchstone results from `.aedt` projects.

shou0715-Arthur/pyaedt-hfss-antenna

用 PyAEDT 驱动 Ansys HFSS / AEDT 完成天线与 RF 仿真自动化的工作流骨架。当用户提到 HFSS、Ansys Electronics Desktop、AEDT、pyaedt、ansys.aedt.core,或要做天线仿真、S 参数(S11/S21)、回波损耗(return loss)、VSWR、远场方向图(far-field)、增益、辐射效率、阻抗匹配、参数化扫频(frequency sweep)、参扫优化(parametric sweep),或者说"自动化跑 HFSS / 用脚本驱动 HFSS / 让 agent 帮我跑仿真"时,务必使用本 skill。即使用户没明说"用 pyaedt",只要任务核心是"用 Python 控制 HFSS 做天线/RF 仿真",也应触发。

相關技能

steipete/bluebubbles

Send and manage iMessages via BlueBubbles, including attachments, tapbacks, edits, replies, and groups.

community

steipete/eightctl

Control Eight Sleep pods (status, temperature, alarms, schedules).

community

steipete/blucli

BluOS CLI (blu) for discovery, playback, grouping, and volume.

community

steipete/bear-notes

Create, search, and manage Bear notes via grizzly CLI.

community

steipete/camsnap

Capture frames or clips from RTSP/ONVIF cameras.

community

steipete/gifgrep

Search GIF providers with CLI/TUI, download results, and extract stills/sheets.

community
← More 程式設計與開發 skills