From 7139c8c19d994b91adfe847d5de930fd41b720a0 Mon Sep 17 00:00:00 2001 From: jiweiqi <8445647+jiweiqi@users.noreply.github.com> Date: Mon, 11 May 2026 12:38:59 +0800 Subject: [PATCH] docs: make agent setup uv-first --- README.md | 48 +++++++++++++---------- src/sim_plugin_hfss/_skills/hfss/SKILL.md | 28 ++++++------- 2 files changed, 42 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index 7ddbee7..7d4ddcb 100644 --- a/README.md +++ b/README.md @@ -41,32 +41,40 @@ Out of scope for this first version: AEDT is available. - Execute bounded Python snippets against the active `hfss` object. - Inspect session, project, and design summaries before continuing. -- Run complete PyAEDT Python scripts through `sim run --solver hfss`. +- Run complete PyAEDT Python scripts through `uv run sim run --solver hfss`. ## Install -Install from PyPI: +For agent projects, install sim-cli-core and the HFSS plugin in the project +environment: -```bash -uv pip install "sim-plugin-hfss==0.1.0" +```powershell +uv init # only if this is not already a uv project +uv add sim-cli-core sim-plugin-hfss +uv run sim plugin sync-skills --target .agents/skills --copy +uv run sim check hfss +uv run sim plugin doctor hfss --deep ``` -For source testing against the current main branch: +For Claude Code, sync the bundled skill to `.claude/skills` instead: -```bash -uv pip install "git+https://github.com/svd-ai-lab/sim-plugin-hfss.git@main" +```powershell +uv run sim plugin sync-skills --target .claude/skills --copy ``` -After installation, sim-cli should auto-discover the driver and bundled skill: +For source testing against the current main branch: -```bash -sim check hfss -sim run --solver hfss path/to/script.py +```powershell +uv add sim-cli-core "git+https://github.com/svd-ai-lab/sim-plugin-hfss.git@main" ``` -If `sim check hfss` reports that AEDT itself is unavailable, first confirm the -Python package installed correctly, then fix the local AEDT installation, -environment variables, or runtime prerequisites. +`uv run sim ...` runs sim from this project environment, so it sees this +project's plugins. Without uv, create and activate a venv, then install +`sim-cli-core` plus this plugin with `python -m pip`. + +If `uv run sim check hfss` reports that AEDT itself is unavailable, first +confirm the Python package installed correctly, then fix the local AEDT +installation, environment variables, or runtime prerequisites. ## AEDT discovery @@ -83,7 +91,7 @@ If AEDT is installed in a nonstandard location, set an explicit root: ```powershell $env:SIM_HFSS_AEDT_ROOT = 'C:\path\to\AnsysEM' -sim check hfss +uv run sim check hfss ``` You do not need to add AEDT to the global system `PATH` when default discovery @@ -91,16 +99,16 @@ or one of the explicit environment variables works. ## Common agent workflow -1. Run `sim check hfss`. +1. Run `uv run sim check hfss`. 2. Choose GUI mode only when visual review is required; otherwise prefer non-graphical mode. 3. Connect and inspect the active project/design before mutating anything: ```bash - sim connect --solver hfss --ui-mode no_gui - sim inspect session.summary - sim inspect hfss.project.identity - sim inspect hfss.design.summary + uv run sim connect --solver hfss --ui-mode no_gui + uv run sim inspect session.summary + uv run sim inspect hfss.project.identity + uv run sim inspect hfss.design.summary ``` 4. Run one bounded PyAEDT snippet at a time. diff --git a/src/sim_plugin_hfss/_skills/hfss/SKILL.md b/src/sim_plugin_hfss/_skills/hfss/SKILL.md index 69f0f7b..ea250ee 100644 --- a/src/sim_plugin_hfss/_skills/hfss/SKILL.md +++ b/src/sim_plugin_hfss/_skills/hfss/SKILL.md @@ -12,16 +12,16 @@ This initial plugin targets HFSS 3D through PyAEDT. It does not yet cover HFSS ## Required Protocol -1. Run `sim check hfss` before launching or editing anything. -2. If `sim check hfss` reports `not_installed`, stop and ask the user for an +1. Run `uv run sim check hfss` before launching or editing anything. +2. If `uv run sim check hfss` reports `not_installed`, stop and ask the user for an AEDT installation or `SIM_HFSS_AEDT_ROOT` path. Do not invent install paths. 3. Prefer `--ui-mode no_gui` unless the user explicitly needs visual review. 4. Before setup, solve, export, or result interpretation, inspect: ```bash -sim inspect session.summary -sim inspect hfss.project.identity -sim inspect hfss.design.summary +uv run sim inspect session.summary +uv run sim inspect hfss.project.identity +uv run sim inspect hfss.design.summary ``` 5. Run one bounded PyAEDT snippet at a time. @@ -36,16 +36,16 @@ sim inspect hfss.design.summary ### Connect to HFSS ```bash -sim connect --solver hfss --ui-mode no_gui -sim inspect session.summary -sim inspect hfss.project.identity -sim inspect hfss.design.summary +uv run sim connect --solver hfss --ui-mode no_gui +uv run sim inspect session.summary +uv run sim inspect hfss.project.identity +uv run sim inspect hfss.design.summary ``` Use GUI mode only when the user needs to watch AEDT: ```bash -sim connect --solver hfss --ui-mode gui +uv run sim connect --solver hfss --ui-mode gui ``` ### Run a PyAEDT script @@ -53,8 +53,8 @@ sim connect --solver hfss --ui-mode gui Use this for a complete script that constructs or opens an HFSS project: ```bash -sim lint --solver hfss path/to/script.py -sim run --solver hfss path/to/script.py +uv run sim lint --solver hfss path/to/script.py +uv run sim run --solver hfss path/to/script.py ``` The script runs in the current Python environment. PyAEDT and AEDT must be @@ -62,7 +62,7 @@ available there. ### Execute a bounded snippet -After `sim connect`, snippets can use the live `hfss` object: +After `uv run sim connect`, snippets can use the live `hfss` object: ```python hfss.project_name @@ -102,7 +102,7 @@ Return JSON-serializable data from the last expression when possible: ## Troubleshooting - Driver not discovered: reinstall the plugin in the same environment as - sim-cli and rerun `sim check hfss`. + sim-cli and rerun `uv run sim check hfss`. - AEDT not detected: set `SIM_HFSS_AEDT_ROOT` to the directory containing an AEDT launcher, or rely on default discovery for common install layouts. A permanent global `PATH` change is optional, not required.