cst-sim-agent AGENTS.md

AGENTS.md — Repo Guide / 仓库指引

Read this before touching any code — it is written for any human or agent that will read or modify this repo. 先读它，再动代码——本文件写给任何将要阅读、修改本仓库的人或 agent。

---

English Version

One-liner

cst-sim-agent is a Claude Code plugin that turns CST Studio Suite into a conversational electromagnetic-simulation assistant via MCP (FastMCP server) + CST's COM interface. It targets Windows (CST COM is Windows-only).

Repo layout

src/server.py          tool registry: 52 @mcp.tool cst_* tools. Thin wrappers, no business logic.
src/controller.py      CSTController facade: all business logic lives here; tools just forward.
src/connection.py      CST process/project lifecycle (connect, new, open, close, save, project type).
src/dezip.py           Parser for CST's private DE-ZIP container (.cst) — zipfile can't open it.
src/popup_utils.py     Popup detect/read/dismiss. Pure Win32 (ctypes + user32.dll), zero third-party deps.
src/popup_watchdog.py  Popup watchdog: auto-presses Enter on modal dialogs to unblock the solver.
src/version_manager.py Checkpoint versioning: op log + named snapshots + git automation.
hooks/                 4 hooks (pre_vba/post_vba/post_mutate/stop_check); remind only, never block.
skills/cst-expert/     Bundled domain-knowledge skill (SKILL.md + references/).
docs/                  Architecture & verification docs (architecture.md / verification-report.md).

• server.py registers (thin); controller.py owns business (thick); connection.py manages lifecycle. New business logic goes in controller, not server.

Call chain

Claude Code
  └─ MCP tool (server.py) → controller.py → connection.py → official cst.interface → CST COM

Two channels:

1. Official Python API direct calls (parameters, solvers, queries, sweeps, full-history rebuild) — preferred when the official API works.
2. VBA strings (cst_execute_vba → add_to_history): modeling primitives, materials, ports, SBR, STEP import, frequency. This is the fallback channel and is gated by a static checker.