# Cst Runtime Optimization

> Cst Runtime Optimization is an Agent Skill for apps & automation published in the Cai-aa/CAE-Agent-Hub repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

当用户要求使用 CLI/runtime 执行 CST 参数优化循环、S11 指标迭代、多轮仿真对比时调用此 Skill。本 Skill 依赖 cst-runtime-cli 提供基础设施，不携带 runtime scripts，所有 CLI 调用走 base skill 的 uv run python -m cst_runtime 入口。

- Skill name: `cst-runtime-optimization`
- Category: [Apps & Automation](https://www.openparable.com/skill/apps-automation/1)
- Source: https://github.com/Cai-aa/CAE-Agent-Hub/blob/HEAD/MCP/CST/vendor/cst-runtime-cli/skills/cst-runtime-optimization/SKILL.md
- Repository: Cai-aa/CAE-Agent-Hub (596 GitHub stars when collected)

## SKILL.md

# CST Runtime 优化 Skill

## 优化流程速查

```text
Phase 0: 准备
  task 确认(工程/目标/参数/约束) → inspect-project(含category)
  [agent: 选几何参数 → 用户确认 → 翻译为objective spec]

Phase 1: 探针(参数≥4强制)
  run-probe-phase --objective <spec>
  [agent: 看top_params/edge_hit → 选参数/调范围/定算法]

Phase 2: 优化循环
  loop:
    run-optimization-step --objective <spec>
    [agent: objective达标? → break / ask_study_failed? → 换优化器]

Phase 3: 收尾
  generate-report → 灵敏度验证 → 经验→docs/
  [agent: 收敛质量判断 + 结论沉淀]
```

**关键决策点：**
| 阶段 | 节点 | agent 行动 |
|------|------|-----------|
| 0 | inspect-project | 筛选 `category=geometry` 的参数作为候选 |
| 0 | task确认 | 向用户确认5项：工程类型、objective函数、目标阈值、参数列表、几何约束 |
| 1 | run-probe-phase 返回 | `main_effects_normalized > 0.1` 保留，`edge_hit=true` 扩范围 |
| 1 | 算法选择 | 参数少+线性=TPE，多+交互复杂=CMA-ES，默认 `suggested_algorithm` |
| 2 | 每轮返回 | `objective_value` vs 目标阈值 → 达标break |
| 2 | ask_study_failed | 未达标且 study 认为收敛 → 换优化器(最多一次) |
| 3 | 收尾 | 灵敏度验证 + 经验入库 |

## 定位

本 Skill 专注 CST 参数优化闭环，依赖 `cst-runtime-cli` 提供底层基础设施。

- 不携带 `scripts/` 或 `cst_runtime/` 源码；所有 CLI 调用走 base skill。
- 负责定义优化迭代流程、早停判断、参数策略、数据导出和报告生成。
- 所有生产任务使用标准 `tasks/task_xxx_slug/runs/run_xxx/{projects,exports,logs,stages,analysis}` 结构。

## 依赖声明

本 Skill 不实现 CST 操作，以下工具全部由 `cst-runtime-cli` 提供。所有 CLI 调用通过工作区的 `-m cst_runtime` 入口执行。

| 职责 | CLI 工具 |
|------|---------|
| run 创建 | `prepare-run`、`get-run-context` |
| 审计 | `record-stage`、`update-status` |
| 进程/session | `cst-session-open`、`cst-session-close`、`cst-session-quit` |
| 参数 | `list-parameters`、`change-parameter` |
| 仿真 | `start-simulation-async`、`wait-simulation` |
| 结果导出 | **`export-run-results`**（统一导出 S11+2D+远场） |
| 结果显示 | **`generate-report`**（生成综合报告） |
| **探针阶段** | **`run-probe-phase`**（一键探针：设计→仿真→分析→注入 study） |
| **优化迭代** | **`run-optimization-step`**（一步迭代：ask→改参→仿真→tell，agent 判断早停） |
| Objective 函数 | 内置在管道中 — `s11_min_db`, `s11_at_freq`, `gain_max`, `bandwidth`, `expression` |

## Objective 函数系统

优化目标不再硬编码为 S11 min dB。通过在管道工具中传入 `--objective <spec>` 指定目标函数：

| 类型 | 格式 | 示例场景 |
|------|------|----------|
| S11 全局最小值 | `{"type": "s11_min_db"}` | 默认，最小化反射 |
| 指定频率 S11 | `{"type": "s11_at_freq", "freq": 2.4}` | 2.4GHz 阻抗匹配 |
| 最大增益 | `{"type": "gain_max", "port": 1}` | 优化天线增益 |
| 带宽 | `{"type": "bandwidth", "below_db": -10}` | S11<-10dB 带宽最大化 |
| 自定义表达式 | `{"type": "expression", "expr": "min(s11_db)"}` | 灵活组合 |

objective 默认方向：s11 类为最小化，gain/bandwidth 类为最大化。可通过 `direction` 覆盖。

两个管道（`run-probe-phase`、`run-optimization-step`）均接受 `objective` 参数。省略时默认 `{"type": "s11_min_db"}`，与旧行为完全一致。

## 触发条件

使用本 Skill：
- 参数优化循环、S11 指标迭代、多轮仿真对比
- 需要实现"仿真 → 读结果 → 解析指标 → 判断是否达目标"的自动化循环
- 需要定义早停条件（target S11 阈值、轮数上限）

不使用本 Skill：
- 单次仿真或结果读取（用 `cst-runtime-cli`）
- 纯几何建模、材料、边界定义

## 文件名约定

导出文件统一放到 `exports/`，固定命名：

```text
exports/
  s11_run{N}.json              ← {N}=CST run_id，无时间戳
  farfield/{freq}_port{port}_run{N}_{quantity}.json ← 每轮独立
  result_2d_*.json
  report.html                  ← generate-report 输出
```

## 优化迭代模式

所有优化迭代走统一模式：

```text
┌─ agent 循环 ──────────────────────────────────────────────┐
│ run-optimization-step --objective <spec>                   │
│   → objective_value, study_best, steps_since_improvement   │
│   → 达标? → break / ask_study_failed? → switch sampler    │
│   → 未达标 → 继续循环                                       │
└───────────────────────────────────────────────────────────┘
```

> `run-probe-phase` 和 `run-optimization-step` 是**自包含管道**，各自管理完整的 session 生命周期。详见 `describe-pipeline`。
>
> 如需在标准流程中插入自定义步骤（如改参后验证实体），可回退到原子工具（`prepare-experiment` + `run-experiment` + `ask-study` + `tell-study` 等）。

### 降级模式（无需 Optuna 时）

适合仅需简单改参仿真对比、不建 study 的场景：

```text
┌─ 每轮迭代 ──────────────────────────────────────────────────────┐
│ prepare-experiment  ← 修改参数（支持 names+values 批量改参）      │
│   → run-experiment  ← 仿真 + 自动导出 S11 + 远场                     │
│   → agent 看 objective_value → 早停判断                           │
│   → 达标 break / 未达标继续下一轮                                  │
└─────────────────────────────────────────────────────────────────┘
```

> `prepare-experiment` 和 `run-experiment` 是**自包含管道**，各自管理完整的 session 生命周期。

### 原子工具模式（需要自定义步骤时）

```text
┌─ 每轮迭代 ─────────────────────────────────────────┐
│ cst-session-open                                    │
│   → change-parameter → save-project                 │
│   → start-simulation-async → wait-simulation        │
│   → cst-session-close --save false                  │
│   → export-run-results                              │
│   → 早停判断 → 达标 break / 未达标继续下一轮              │
└────────────────────────────────────────────────────┘
```

### 每次新建项目

适合改变几何实体或需要完全独立数据。每轮独立 `run_00N` 目录。

```text
prepare-run(run_00N) → prepare-experiment
  → run-experiment
```

### 结果显示

```powershell
# 先用 args-template 生成参数，再调用
uv run python -m cst_runtime args-template --tool generate-report
# 编辑模板中的 data_dir、output_html、modules 字段
uv run python -m cst_runtime generate-report --args-file <模板.json>
```

`modules` 默认 `s11,farfield3d,timeline`，可选 `metrics,optimization`。

`generate-report` 自动读取 `exports/` 下的全部 `s11_run*.json` 和 `farfield/*.json`，渲染 S11 曲线、3D 远场、参数变更记录和操作审计。

**3D 远场仪表板**：使用 WebGL Canvas 渲染，支持鼠标拖拽旋转、滚轮缩放、自动旋转。页面自包含（无 CDN 依赖），可作为独立 HTML 文件离线查看。

## 自动化优化循环红线

> **早停判断** 是本 Skill 区别于照单执行的关键红线。其他通用红线（session 分离、S11 复数处理、远场增益证据约束等）见 `cst-runtime-cli` SKILL.md。

- 每轮执行流程必须包含早停判断：`仿真 → 读结果 → 计算 objective → 判断是否达目标 → 达则 break，不达则继续`
- "执行"和"评估"不得拆分为两个独立阶段；目标指标必须在每轮循环体内部实时解析和判断
- 若未实现早停导致超过目标后继续执行额外轮次，任务输出必须明确标记为 `overrun`
- 参数发现：使用 `inspect-project`（而非 `list-parameters`）一次性获取全部参数名、值、中文描述。避免逐一 `describe-tool` 查每个参数。
- **探针强制**：待优化参数 ≥ 4 个时，**必须先执行探针阶段**（`run-probe-phase`），筛选关键参数后再进入正式优化循环。跳过探针直接进入正式优化的，任务输出必须标记为 `probes_skipped`，由此产生的浪费轮次计入 agent 成本。

### 禁止自编优化脚本

agent **不得**为优化循环编写独立 Python 脚本（如 `optimize_loop.py`、`run_optimization.py` 等）。

所有优化迭代必须使用现有管道工具（`run-probe-phase` + `run-optimization-step`，或降级到 `prepare-experiment` + `run-experiment`）或原子工具的 CLI 原生编排。脚本层无法正确处理：
- CST 缓存命中后的状态恢复
- DE 进程锁死后的自动重启
- 多 run_id 的数值排序读取
- 远场导出的时序依赖
- 探针阶段的多轮循环状态管理

任何偏离管道工具的自定义脚本均视为违规，由此产生的浪费（仿真轮次、时间、结果丢失）由 agent 承担。

### 禁止销毁已有 run 数据

run 目录（`runs/run_xxx/`）是**不可逆数据容器**。禁止：

- 删除或覆写 `exports/` 下的历史导出文件
- 从源工程重新拷贝 `.cst` 替换 `projects/working.cst`——这会丢失所有历史 run_id 和结果

当需要干净工程状态（如清除 CST 内部缓存、重置仿真历史）时，必须：

```text
prepare-run → 创建新 run_00N 目录
             → 从源工程拷贝到新 run 的 projects/
             → 新旧 run 各自保留完整数据
```

这样旧 `run_00N-1/` 的 `exports/` 和 project 历史保持完整，新 `run_00N/` 从零开始，互不干扰。

### 已知问题与恢复

| 问题 | 原因 | 恢复方式 |
|------|------|---------|
| 端口非均匀填充 | 修改 `g`(脊间距) 导致端口区域出现多种材料 | `cst-session-close --save false` 丢弃改参，恢复原值 |
| 部分仿真未重跑 | CST 检测到网格未改变时可能返回缓存结果 | `run-experiment` 内置 run_id 预检对比，输出 `warning` 字段 |
| 远场导后保存 | 远场导出使 CST 进入错误状态 | `close(save=False)` 自动处理；**不要额外调用 save** |

## 优化闭环流程

### Phase 0：准备

**目的：** 确保 agent 和用户对优化目标一致理解。

1. `prepare-run` → `get-run-context`
2. `inspect-project` → 返回全参数（含 `category`）
3. agent 筛选 `category=geometry` 的参数作为候选，列出给用户
4. 向用户确认 5 项：
   - 工程类型
   - 优化目标函数（S11 min / 指定频率 S11 / 增益 / 带宽 / 自定义表达式）
   - 目标阈值
   - 候选参数列表（含初始范围）
   - 几何约束（如 L ≥ g）
5. agent 将用户确认的优化目标翻译为 `objective` 参数格式

**引导规则：**
> 优化目标必须向用户确认后才能进入探针阶段。参数选择以 `category=geometry` 为主。
> 用户描述的目标由 agent 翻译为 objective spec。无明确目标时默认最小化 objective。

### Phase 1：探针（参数≥4 强制）

```powershell
uv run python -m cst_runtime run-probe-phase \
  --project-path <run>\projects\working.cst \
  --parameters '{"R":{"min":0.1,"max":0.5},"g":{"min":20,"max":30}}' \
  --study-storage <run>\studies\optimization.db \
  --study-name horn_matching \
  --objective '{"type":"s11_min_db"}'
```

`run-probe-phase` 自动完成：
1. 复制 `working.cst` → `working_probe.cst`（基线隔离）
2. 设计 Plackett-Burman 折因实验
3. 逐点仿真，按 `objective` 函数计算值
4. 导出移入 `exports/probe/`
5. 分析主效应 + 交互效应
6. 注入 Optuna study

**返回：** `main_effects`、`interactions`、`top_params`、`edge_hit`、`suggested_algorithm`

**agent 决策：**

| 决策 | 信号 | 规则 |
|------|------|------|
| 选参数 | `main_effects_normalized` | > 0.1 保留，< 0.05 固定为中心值 |
| 调范围 | `edge_hit` | true → 扩范围或提示用户 |
| 选算法 | `suggested_algorithm` | TPE（默认）/ CMA-ES（多参数+强交互） |

### Phase 2：优化循环

```powershell
uv run python -m cst_runtime run-optimization-step \
  --project-path <run>\projects\working.cst \
  --study-storage <run>\studies\optimization.db \
  --study-name horn_matching \
  --objective '{"type":"s11_min_db"}'
```

`run-optimization-step` 自动完成：
1. 切换优化器（如指定 `--sampler`）
2. `ask-study` — Optuna 采样
3. `prepare-experiment` — 改参 + 保存
4. `run-experiment` — 仿真 + 导出
5. 按 `objective` 函数计算值
6. `tell-study` — 回报结果

**返回：** `objective_value`、`study_best`、`steps_since_improvement`

**agent 早停判断：**

```
每轮返回后:
  1. objective_value < target? → break ✓
  2. ask_study_failed 且未达标且未换过优化器? → --sampler cma-es 切换
  3. 否则继续循环
```

**切换优化器：** 加 `--sampler cma-es` 或 `--sampler random`。pipe 内部重建 study + 迁移历史 trial。

### Phase 3：收尾

1. `generate-report`
2. 收敛质量评估：`study_best` 在边界？相比 probe `mean_value` 有改善？
3. 灵敏度验证：最优 ±1%、±5% 跑 check-point，用同一 `objective` 函数评估
4. 经验写入 `docs/opt-exp-*.md`

**引导规则：**
> 灵敏度验证使用与优化阶段相同的 `objective` 函数。经验入库是验收项，缺少 docs/ 记录的任务标记为 `incomplete_docs`。

## 泛用经验总结

每次优化任务完成后，必须提炼**可复用的泛用经验**，写入工作区根目录的 `docs/` 目录。

### 触发条件

满足以下任一条件即需总结：
- 遇到新的 CST 行为陷阱（缓存、覆盖、状态异常等）
- 发现参数间的交互效应或非线性关系
- 探针阶段筛选出意外的关键参数
- 优化策略（TPE、网格搜索等）在特定场景下表现异常
- 管道工具组合使用中发现的新模式或限制

### 输出格式

文件命名：`docs/opt-exp-{YYYY-MM-DD}-{简短主题}.md`

内容结构：
```markdown
# 经验：{标题}

## 场景
- 工程类型：
- 参数集：
- 优化目标：

## 发现
{具体现象、数据、对比结果}

## 根因
{分析结论，区分 CST 行为 vs 物理规律 vs 工具限制}

## 泛用规则
{可迁移到其他工程的经验，1-3 条}

## 验证状态
- [ ] 单次验证 / [ ] 多次验证 / [ ] 跨工程验证
```

### 存放位置

工作区根目录 `docs/` 下，按主题分类：
- `docs/opt-exp-*.md` — 优化经验
- `docs/cst-traps-*.md` — CST 陷阱
- `docs/pipeline-patterns-*.md` — 管道编排模式

### 质量要求

- **泛用性**：经验必须能迁移到至少 2 个不同工程场景，否则不写
- **证据驱动**：每条结论必须有对应的 `exports/` 数据或 `stages/` 记录支撑
- **不重复**：写入前检查 `docs/` 是否已有同类经验，有则追加而非新建
- **不写过程**：只写结论和规则，不记录"我做了什么"的流水账

## 引用

以下通用规则详见 `cst-runtime-cli` SKILL.md：
- **CLI 调用原则** — 入口模式、JSON 契约、args-template 优先（默认写到 `.cst_runtime/tmp/`）、project_path 约束
- **管道工具自包含性** — `prepare-experiment`/`run-experiment`/`inspect-project` 各自管理 session，无需前置 `cst-session-open`
- **错误处理** — `workspace_not_initialized`、`source_project_missing`、`ambiguous_open_projects`、`lock_not_released`、`Access is denied`
- **进程管理前置 gate** — `cst-session-management-gate` 管道、硬性停止条件
- **结果与远场红线** — S11 复数处理、modeler/results session 分离、仿真后关闭顺序、`close(save=False)` 规则

## 最终验收清单

- [ ] 优化循环每轮均实现早停判断
- [ ] `exports/` 下有导出文件（s11_run{N}.json 等）
- [ ] `status.json` 状态正确
- [ ] 工程已关闭且无 `.lok` 锁文件
- [ ] 清理 CST 进程结果已记录
- [ ] `logs/tool_calls.jsonl` 和 `stages/` 可追溯
- [ ] 只使用了 Skill + CLI，没有调用旧脚本
- [ ] 使用了 objective 函数（非默认需确认）
- [ ] 参数数 ≥ 4 的优化已执行探针阶段（`run-probe-phase` 或 `design-probes` + `analyze-probes` + `study-add-trials`）
- [ ] 探针结果（主效应、交互效应、`top_params`）已记录到 `stages/`

---

Source: https://www.openparable.com/skill/apps-automation/cst-runtime-optimization (OpenParable). Cite the canonical URL above.
