CST Runtime CLI Skill

核心流程参考（agent 快速入口）

从零开始完成 CST 优化任务的标准三步流程：

准备：部署引导（一次性）

新 agent 首次接手工作区按部署引导章节完成部署。后续直接从 ① 开始。

① 创建工程（从零开始）

无源 .cst 文件时，先用 create-blank-project 建空白工程，再用建模工具搭建结构。标准流程：

prepare-run             # 创建 task/run 目录结构
# 建空白工程
uv run python -m cst_runtime create-blank-project --project-path <run>\projects\working.cst
# 建模（按需）
uv run python -m cst_runtime define-brick --args-file <args>
uv run python -m cst_runtime define-port --args-file <args>
uv run python -m cst_runtime set-farfield-monitor --args-file <args>

有源 .cst 时直接跳到 ②。

② 了解工程（一次）

# inspect-project 返回：全部参数名/值/描述 + 全部几何实体 + 远场监视器
uv run python -m cst_runtime inspect-project --project-path <run>\projects\working.cst

输出中有 parameters_count、entities_count、farfield_monitors_count，据此决定优化哪些参数、需要导出哪些远场。

③ 优化循环（每轮两步）

# 改参（支持批量）
uv run python -m cst_runtime prepare-experiment --args-file <args>
# 仿真 + 自动导出 S11 + 远场
uv run python -m cst_runtime run-experiment --args-file <args>
# 解析 exports/s11_run{N}.json → 早停判断

• prepare-experiment 和 run-experiment 是自包含管道，各自管理 session 生命周期
• 产物：s11_run{N}.json（每轮递增）+ farfield/{freq}_port{port}_run{N}_{quantity}.json（每轮独立）

④ 报告 + 清理

uv run python -m cst_runtime generate-report --args-file <args>
uv run python -m cst_runtime cst-session-quit

此流程覆盖 90% 的标准调优任务。如需建模、改边界、设端口等操作，在上述步骤之间插入原子工具即可，管道自管理的 session 不受影响。

部署引导（一次性）

cst_runtime 是 skill 自带的包（scripts/cst_runtime/），首次使用需部署到工作区。

1. agent 准备 python + uv → 缺则下载静默装
2. agent Read skill/scripts/bootstrap.py → Write 为 bootstrap.py
3. uv run python bootstrap.py --skill-path <skill-root>\scripts
4. 输出 status=ready → 删除 bootstrap.py
5. uv run python -m cst_runtime init-workspace --workspace <path>

bootstrap.py 只做两件事：

• 复制 cst_runtime/ + references/ → .cst_runtime/
• uv sync → 将 cst-runtime 作为 local dependency 安装到 .venv

后续 init-workspace 自动完成： 创建 task/refs/docs 目录 + 扫描 CST 路径并注册到 pyproject.toml。不再需要单独 install-cst-libraries 步骤。

权限回退

复制失败（PermissionError）输出 status=need_fallback：

• agent Read skill 下 cst_runtime/ 全部 .py → Write 到 .cst_runtime/cst_runtime/
• 重跑 uv run python bootstrap.py（不带 --skill-path，跳过 copy）

生产入口

uv run python -m cst_runtime <tool> [args]

cst-runtime 以 [tool.uv.sources] local dependency 方式安装到 .venv，无需路径式入口。

• 所有生产任务使用标准 tasks/task_xxx_slug/runs/run_xxx/{projects,exports,logs,stages,analysis} 结构。
• 参考工程一律视为只读蓝本，操作前必须先 prepare-run 创建工作副本。

重新部署

如果后续遇到 ImportError，说明 .cst_runtime/ 中的包可能过期。重新运行 bootstrap.py --skill-path <skill-root>\scripts 即可重新部署最新模块。

为什么隔离：系统 Python 可能有冲突版本的 CST 库或没有 CST 库。uv run 使用工作目录下隔离的 .venv，其中只有 pyproject.toml 声明的精确依赖，与系统环境完全无关。

Skill 包结构

• SKILL.md：触发条件、调用原则、风险判断、验收格式。
• scripts/bootstrap.py：部署引导脚本。
• scripts/cst_runtime/：所有工具实现包（session、modeler、project_ops、results、farfield、audit、workspace、cst_env 等）。
• tests/：无 CST 启动的 contract 测试。
• references/：首次初始化手册（setup_guide.md）、任务卡模板、管道指南、材料库。

维护要求：

• 修改 CLI/runtime contract 后，先更新仓库内 Skill 包，再同步到 agent 安装目录（Copy-Item ...\.config\opencode\skills\...）。
• 无 CST 启动 contract 验证：uv run python -m unittest discover -s skills\cst-runtime-cli\tests。

触发条件

使用本 Skill 的情况：

• 用户明确说"走 CLI"、"runtime CLI"、"低上下文 CLI 验证"。
• 任务涉及 session 管理、建模、仿真、参数优化、结果读取、远场导出中的任一环节。
• 需要生成可审计的 CLI 调用链，落到 run 的 logs/ 和 stages/。
• 首次在环境安装 Skill，需要自动诊断和配置。

不要使用本 Skill 的情况：

• 纯咨询类问题（如"什么是 S11"、"CST 能做什么"），无需 CLI 执行。
• 非 CST 电磁仿真任务。
• 需要手动交互式建模而非 CLI 编排的场景。

CLI 调用原则

• 入口统一为 uv run python -m cst_runtime。首次部署使用 bootstrap.py（见部署引导章节），部署完成后全部命令走统一入口。
• 禁止读取 cst_runtime/ 下的 Python 源码文件——工具的参数、行为、用法全部通过 describe-tool CLI 命令自描述获取。读源码得到的信息可能过时或不完整。
• 禁止将 cst_runtime/ 模块目录复制到工作区或测试区——那是 skill 内部模块，工作区只需 .venv 和 pyproject.toml。所有命令走 skill 入口。
• 简单发现命令可直接调用。
• 其他 agent 第一次使用时必须先跑 health-check；不要靠猜工具名或参数名。
• 低上下文 agent 不应自己发明管道；先跑 list-pipelines，再对目标链路跑 describe-pipeline --pipeline <name>。
• 发现类命令不要求工作区已初始化；生产命令需要 task 目录和源 CST 工程。
• 带路径或复杂参数的命令优先使用 args-template 生成 JSON，再用 --args-file 调用。
• args-template 不带 --output 时自动写到 .cst_runtime/tmp/args_{tool}_{timestamp}.json，不污染工作区根目录。
• --args-file 加载后自动存档副本到 run 的 stages/args_{tool}_{filename}.json，纳入审计体系；若源文件在 .cst_runtime/tmp/ 则自动清理。
• 只有已经通过 describe-tool 确认支持直接参数时，才使用 CLI flags（注意：直接参数模式已经修复，对所有工具有效）。
• 数组/对象参数必须走 --args-file 方式。 直接参数模式只暴露标量字段（字符串、数字、布尔值）。如 prepare-experiment 的 names/values 是 JSON 数组，不在直接参数列表中，必须用 args-template 生成模板后编辑 names 和 values 字段。
• 所有 project_path、source_project、working_project 都必须指向具体 .cst 文件。
• change-parameter 的参数名固定为 name 和 value。
• 每次调用必须检查 JSON 返回的 status；不得只看退出码。

环境自检与修复

首次初始化上下游工具的细节见 references/setup_guide.md。

全量健康检查

uv run python -m cst_runtime health-check --auto-fix true
uv run python -m cst_runtime health-check --auto-fix false    # 仅诊断

单项自检

uv run python -m cst_runtime health-check --auto-fix false
uv run python -m cst_runtime cst-session-inspect

CST Python 库自安装

init-workspace 会自动扫描并注册 CST 路径到 pyproject.toml，通常无需手动安装。

手动覆盖或指定非标准路径时使用：

uv run python -m cst_runtime install-cst-libraries --dry-run true    # 扫描不修改
uv run python -m cst_runtime install-cst-libraries                    # 自动检测并配置
uv run python -m cst_runtime install-cst-libraries --cst-path "D:\CST\AMD64\python_cst_libraries"

管道工具与原子工具的关系

管道是原子工具的有序编排，不是黑盒。每个管道内部调用若干原子工具完成工作流，agent 可随时查看管道定义，选择使用管道（便捷）或降级到原子工具（灵活）。

管道工具（便捷）         原子工具（灵活编排）
─────────────────        ─────────────────────────
inspect-project           cst-session-open → list-parameters → list-entities → cst-session-close
prepare-experiment        cst-session-open → change-parameter → list-parameters → save-project → cst-session-close
run-experiment            cst-session-open → start-simulation-async → wait-simulation → cst-session-close → open-results-project → export-run-results → cst-session-close

原则：管道覆盖 80% 标准路径，原子工具覆盖 20% 非标场景。 agent 可在管道之间插入自定义步骤，或完全退回到原子工具。

查看管道展开步骤：

uv run python -m cst_runtime describe-pipeline --pipeline prepare-experiment

自包含性

每个管道自管理 session 生命周期——自行创建 DE、打开/关闭工程：

• prepare-experiment: open → 改参(可批量) → 确认 → save → close(kill DE)
• run-experiment: open → start_solver → poll → close → open(results) → 导出 → close
• inspect-project: open → 读参数+实体 → close

不要在管道工具前手动调用 cst-session-open——管道内部会创建独立 DE 并自行清理。手动 open 会导致 session 冲突或 DE 泄漏。

list-open-projects 和 get-run-context 需要 CST Design Environment 正在运行。无 DE 时必然返回 error，不是工具问题。

管道参考表

所有管道定义通过 describe-pipeline --pipeline <name> 查询，以下是 9 条管道的概览：

管道	原子工具展开	用途
inspect-project	cst-session-open → list-parameters → list-entities → inspect-farfield-monitors → cst-session-close	了解工程（参数+实体+远场）
prepare-experiment	cst-session-open → change-parameter → list-parameters → save-project → cst-session-close	改参→保存
run-experiment	cst-session-open → start-simulation-async → wait-simulation → cst-session-close → export-run-results	仿真→导出
async-simulation-refresh-results	start-simulation-async → wait-simulation → cst-session-close → list-run-ids → get-1d-result	异步仿真→读结果
project-unlock-check	infer-run-dir → wait-project-unlocked	检查锁文件
cst-session-management-gate	6 步完整 session 生命周期验证	session 管理
args-file-tool-call	describe-tool → args-template → <tool>	复杂参数调用
first-run	health-check → help → list-tools → list-pipelines	首次环境设置
self-learn-cli	health-check → help → list-tools → list-pipelines → describe-pipeline → describe-tool → args-template	agent 入场自学

用法：

# 查看管道展开步骤
uv run python -m cst_runtime describe-pipeline --pipeline prepare-experiment

# 生成管道执行计划文件
uv run python -m cst_runtime pipeline-template --pipeline run-experiment --output stages\pipeline_plan.json

管道停止规则：

• 每一步都解析 stdout JSON，status!="success" 立即停止，除非下一步是明确恢复动作。
• health-check 返回 overall=blocked 时，必须先解决 remaining_issues。
• 任何会触发 CST session、保存、关闭、导出、清理进程的链路，都必须遵守本文件的红线。

核心结果工具

工具	用途
export-run-results	仿真后统一导出 S11、2D 数据、远场到 exports/
generate-report	生成综合报告（S11 曲线、3D 远场、2D 热力图、操作审计）

优化迭代流程请参阅 cst-runtime-optimization skill，本 skill 只提供底层工具。

进程管理前置 gate

CLI 命令：cst-session-inspect / cst-session-open / cst-session-reattach / cst-session-close / cst-session-quit

完整 gate 顺序见 describe-pipeline --pipeline cst-session-management-gate。

硬性停止条件：

• cst-session-close 或 close_project 未成功时，不执行后续操作。
• close_project() 默认 kill_processes=True，自动杀死该 project 的 DE 进程并清理孤悬 DE。如需保留 DE（罕见），传 kill_processes=False。
• 存在多个 open projects 时，不做写操作或关闭操作。
• Access is denied 残留只能记录；必须带 PID、进程名、错误文本和锁文件状态。

结果与远场红线

• 远场导出必须放在流程最后；导出后 close_project(project_path, save=False) 自动清理 DE 进程。远场导出操作会使 CST 处于错误状态，若保存则下次打开工程将无法正常使用。
• 远场导出放在每轮最后可以免去额外开关 session 的开销——close_project(save=False) 自动清理，工程文件不受影响。
• S11 原始数据是复数字典，不是 dB 值。
• 远场增益证据只允许使用 Realized Gain、Gain 或 Directivity。Abs(E) 不能写成 dBi 增益。
• modeler session 与 results session 是两个独立 session，禁止混用。
• 仿真完成后调用 close_project()（默认 kill_processes=True）释放工程并清理 DE 进程。下次 open_project() 自动获得干净 DE。
• 关闭 project 的正确做法：save=True 时先 project.save()，再调用 close_project()。远场导出后 close_project(save=False)。

错误处理

• workspace_not_initialized：先 init-workspace。
• source_project_missing：source_project 路径不存在。
• production_dependency_missing：缺少 CST Python 库依赖。先确认 CST 已安装，再用 install-cst-libraries 手动配置。
• cst_not_found：未检测到 CST 安装；提供 --cst-path 或确认 CST 已安装。
• pyproject_update_failed：pyproject.toml 无法修改；检查文件权限或手动编辑。
• overall=blocked：health-check 返回阻塞状态；查看 remaining_issues 和 user_instructions。

历史说明

skills/cst-runtime-optimization/（仅 SKILL.md，无代码）是此 Skill 的优化闭环配套 skill，本 skill 只提供底层工具。

最终验收清单

• health-check 返回 overall=pass。
• status.json 状态正确（validated / blocked / needs_validation）。
• 所有输出文件（S11 JSON/HTML、远场 TXT/HTML、grid JSON）已落盘。
• 工程已关闭且无 .lok 锁文件（close_project 自动清理 DE 进程，无需额外 cleanup-cst-processes）。
• 清理 CST 进程结果已记录；Access denied 残留没有写成已杀掉（有残留属于非阻塞，记录即可）。
• logs/tool_calls.jsonl 和 stages/ 能追溯每一步。
• 只使用了 Skill + CLI，没有调用旧脚本。