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.

Read before editing

1. Single persistent session: reuse connect/open; never reconnect needlessly.
2. Process/project two-layer separation: the CST process is always reused; creating a project is an explicit action, never implicit from state.
3. Channel rule: if the official Python API works reliably → use it; otherwise → VBA. Never the reverse.
4. Check the library first — but the official docs are the highest authority: the bundled syntax library is a quick-lookup + pitfall layer and may be stale or incomplete; when it doesn't cover something (or you're unsure), defer to CST's official documentation (installed Online Help / PDF manuals) — see references/official-docs.md for how to search. Don't blind-try — LLM-invented phantom methods fail with (10091).
5. Hooks only remind, never block: hook scripts must not return permissionDecision.
6. Disconnect must be graceful; taskkill is forbidden.
7. Text I/O is explicit encoding="utf-8"; source is UTF-8 without BOM.

Common edit tasks

• Add an MCP tool: one thin @mcp.tool in server.py + a business method in controller.py; follow the knowledge base for modeling/material/port. Update README's feature table.
• Edit VBA-related logic: check vba_syntax first (quick lookup); when in doubt, CST's official docs are the final authority. Changes affecting real CST behavior must be tested live via cst_connect (CI can't cover it).
• Edit hooks: update hooks/hooks.json + scripts. Note the install cache (~/.claude/plugins/cache/) may need rebuilding; hooks remind only.
• Edit docs: comments and docs may be in Chinese or English (keep a file internally consistent); if structure changes, update docs/architecture.md too.

Verification

Local quick check (= what CI runs):

python -m py_compile src/*.py hooks/*.py
python -c "import json,glob;[json.load(open(f,encoding='utf-8')) for f in ['.claude-plugin/plugin.json','.claude-plugin/marketplace.json','.mcp.json','hooks/hooks.json']];print('ok')"

Changes touching real CST behavior can't be verified by CI — run a minimal live repro instead.

Hard constraints

• Don't bypass the _vba_static_check gate (blocked ops like SaveAs/Close must go through their dedicated tools, not raw VBA).
• Don't taskkill CST processes (and never touch Session-0 system-service processes).
• No new third-party runtime deps (MCP server depends only on mcp and pywin32).
• Don't commit .cst / .step / __pycache__ (.gitignore covers these; self-check with git status before committing).

中文版

一句话

cst-sim-agent 是一个 Claude Code 插件：通过 MCP（FastMCP server）+ CST 的 COM 接口，把 CST Studio Suite 变成可对话的电磁仿真助手。它面向 Windows（CST COM 只在 Windows）。

仓库结构

src/server.py          工具注册层：52 个 @mcp.tool 的 cst_* 工具。薄封装，不写业务逻辑。
src/controller.py      CSTController facade：收敛所有业务逻辑，工具层只做转发。
src/connection.py      CST 进程/工程生命周期（连接、新建、打开、关闭、保存、工程类型）。
src/dezip.py           CST .cst 私有 DE-ZIP 容器解析（Python zipfile 打不开 .cst）。
src/popup_utils.py     弹窗检测/读取/关闭。纯 Win32（ctypes + user32.dll），零第三方依赖。
src/popup_watchdog.py  弹窗看门狗：识别模态弹窗自动按 Enter，防求解阻塞。
src/version_manager.py checkpoint 版本管理：操作日志 + 命名快照 + git 自动化。
hooks/                 4 个 hook（pre_vba/post_vba/post_mutate/stop_check），只提醒、不阻断。
skills/cst-expert/     内嵌领域知识库 skill（SKILL.md + references/）。
docs/                  架构与验证文档（architecture.md / verification-report.md）。

• server.py 注册工具（薄）；controller.py 收业务（厚）；connection.py 管生命周期。新增业务逻辑放 controller，不要堆进 server。

调用链

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

双通道：

1. 官方 Python API 直调（参数、求解、查询、扫描、全历史重建）——官方接口可靠时优先。
2. VBA 字符串（cst_execute_vba → add_to_history）：建模原语、材料、端口、SBR、STEP 导入、频率。这是兜底通道，且带静态闸门。

改动前必读

1. 单实例持续操作：connect/open 优先复用，不要重复连接。
2. 进程/工程两层分离：CST 进程永远复用；新建工程是显式动作，绝不因现场状态隐式新建。
3. 通道规则：能用官方 API 可靠直调 → 直调；否则 → VBA。别反向（能用 VBA 就绕开官方 API 是错的）。
4. 写 VBA 前先查库；但官方文档才是最高标准：内嵌语法库只是速查 + 经验避坑层，可能过时或覆盖不全；查不到或存疑时，以 CST 官方文档（安装目录 Online Help / PDF 手册）为最终权威，检索方法见 references/official-docs.md。不盲试——通用大模型编造的幽灵方法会报 (10091)，浪费几小时。
5. hooks 只提醒、不阻断：hook 脚本不返回 permissionDecision。
6. 断开必须优雅关闭，禁止 taskkill。
7. 文本 I/O 显式 encoding="utf-8"，源码 UTF-8 无 BOM。

常见改动任务

• 新增 MCP 工具：server.py 加一个 @mcp.tool 薄封装 + controller.py 加业务方法；若属建模/材料/端口，遵循知识库写法。同步 README「特性」表。
• 改 VBA 相关逻辑：先查 vba_syntax 库（速查），存疑时以 CST 官方文档为最终权威；涉及真实 CST 行为的改动必须在本机 cst_connect 实测才算数（CI 覆盖不到）。
• 改 hook：改 hooks/hooks.json + 对应脚本。注意：安装缓存副本（~/.claude/plugins/cache/）可能需重建才生效；hooks 只提醒不阻断。
• 改文档：中英文均可（单文件内保持一致）；动了结构同步更新 docs/architecture.md。

验证

本地快速检查（= CI 内容）：

python -m py_compile src/*.py hooks/*.py
python -c "import json,glob;[json.load(open(f,encoding='utf-8')) for f in ['.claude-plugin/plugin.json','.claude-plugin/marketplace.json','.mcp.json','hooks/hooks.json']];print('ok')"

涉及真实 CST 行为的改动，CI 无法验证——必须真机跑通最小复现。

红线

• 不绕过 _vba_static_check 静态闸门（SaveAs/Close 等被拦截的操作用对应专用工具，不硬写 VBA）。
• 不 taskkill CST 进程（先查系统服务进程，Session 0 的服务绝不能动）。
• 不新增第三方运行时依赖（MCP server 仅依赖 mcp、pywin32）。
• 不提交 .cst / .step / __pycache__（.gitignore 已覆盖，提交前 git status 自查）。