CST 仿真编排 aomk20201110-commits/CST_AI

CST_AI v2.0

CST_AI 把一份声明式任务规格，变成一套经过规划、带预算、可持久化的 CST Studio Suite 工作流，并返回结构化结果，附带足以让你信任这些结果的溯源信息。

它既不是 GUI，也不是自主科研智能体。它不决定该仿真什么，数据不存在时也不会猜一个数字出来。你在 TaskSpec 里描述任务，CST_AI 负责规划，在任何东西跑起来之前就报出求解器开销，在授权的预算内执行，并写下一份持久化的运行记录，之后一个完全全新的进程也能把它读回来。

version = 2.0.0

目录

- CST_AI 是什么
- 状态
- 功能特性
- 架构
- 环境要求
- 安装
- 快速开始
- 公开动作
- TaskSpec 示例
- 安全与求解预算模型
- 结果能力
- 限制
- 路线图
- 许可证
- 第三方免责声明

CST_AI 是什么

CST_AI 是 CST Studio Suite 外面的一层插件。它夹在智能体或脚本与 CST Python API 之间，只提供四样东西：

1. 声明式入口。 任务是一份 JSON 文档（TaskSpec），里面写明任务类型、各阶段、求解策略和输入。未知字段一律拒绝，所以打错一个字也绝不会悄悄改变一次运行。
2. 先出计划，再产生副作用。 plan 经过验证，不接触 CST、不构建、不求解、不写工程文件。它会提前报出阶段顺序、计划求解次数和授权预算。
3. 带预算的执行。 run 只做计划里列出的副作用。求解器能不能启动，只由 TaskSpec 的求解策略决定。不存在「既然都进来了，顺手求解一下」这种隐藏行为。
4. 持久化、结构化的输出。 每次运行都会写一份原子检查点、一份只追加的事件日志，以及一个 ResultBundle（JSON + Markdown）。它把执行状态、数值状态、科学状态和溯源状态分开保存——因为求解器正常退出，跟结果能拿去做科研，不是一回事。

大数组绝不会以原始样本的形式穿过智能体接口：它们写入 artifact，通过路径、大小和 SHA-256 来引用。

状态

| 项目 | 值 |
| 版本 | 2.0.0 |
| 发布状态 | 可用，功能集已冻结 |
| 能力注册表 | 21 项能力，全部 VERIFIED_E2E |
| 公开 API | PUBLIC_API_V1 = plan / run / status / inspect / resume / load_task |
| 树内 API 版本 | PUBLIC_API_VERSION = 1.16.0，PUBLIC_API_REVISION = 1.17.0 |
| 验证环境 | CST Studio Suite 2026，Windows，随附 Python 3.12.x |
| 自动化测试 | tests/（标准库 unittest，零第三方依赖） |
| 已知问题 | 见 KNOWN_ISSUES.md |

发布证据、逐项能力限制和验收运行记录汇总在 RELEASE_NOTES.md。

功能特性

* 五个公开动作 —— plan、run、status、inspect、resume —— 可从同一个启动器调用，也可从 Python 调用。
* 求解预算强制 —— solve_policy（FORBID / ALLOW_ONE / ALLOW_UP_TO_N / REUSE_ONLY）加上 max_solves；任务在 FORBID 下声明 SOLVE 阶段会被判定为矛盾并拒绝，不会执行。
* 持久化运行存储 —— <store_root>/<run_id>/{state.json, events.jsonl, bundle.json, bundle.md}；status 和 inspect 在新进程里也能给出答案，resume 能继续中断的运行，不会重新求解已经解过的部分。
* 参数扫描 —— spec.points[]，每个点一个隔离项目，共享一份预算，带签名校验的复用缓存，中断后可真正恢复。
* 结果保持诚实 —— 当半功率电平交点落在频带之外时，谐振 f0 / FWHM / Q 返回 null 并附带明确的有效性代码，而不是编造一个数字。
* 结构化错误 —— 每个失败都是 {ok: false, error_type, stage, message, detail}，附带来自固定分类体系（23 个代码）的机器可读代码，消息里不含原始 traceback。
* 复用而不重新求解 —— 复用的点必须同时通过签名校验和产物哈希校验，否则拒绝复用。

架构

agent / script
│
▼
index.js DSH tool adapter (Node, optional)
│ base64 JSON request
▼
cst_ai_tool_bridge.ps1 PowerShell launcher (resolves interpreter)
│
▼
cst_ai_tool.py request adapter: TaskSpec → envelope
│
▼
cst_ai_plugin.public PUBLIC API v1: plan/run/status/inspect/resume
│
├── planner.py pure: no CST, no solve, no writes
├── orchestrator.py stages: CONNECT → BUILD → VERIFY → SOLVE → EXTRACT → ANALYZE → REPORT
├── runstore.py atomic checkpoints + append-only events
├── capabilities.py capability registry (21 entries)
├── validation.py TaskSpec runtime validation
├── preflight.py preconditions, protected paths
├── depsnapshot.py dependency/config snapshot per run
└── bundle.py ResultBundle (JSON + Markdown)
│
▼
cst.interface / cst.results CST Studio Suite Python API
│
▼
CST Studio Suite (NOT distributed with this project)

cst_cli.py 是一个小型命令行入口，不想用 Node 适配器时，可以用它执行同样的五个动作。更多内容见 docs/ARCHITECTURE.md 逐层契约与工具适配器细节见 docs/DSH_INTEGRATION.md。

环境要求

* Windows（启动器是 PowerShell；CST Python API 按安装状态直接使用）。
* CST Studio Suite 2026，以及它自带的 Python 3.12.x 解释器。
CST_AI 会导入 cst.interface / cst.results，这两个模块只存在于该解释器中——原版 CPython 安装没有它们。
* PowerShell 5.1 或更高版本，用于 cst_ai_tool_bridge.ps1。
* Node.js 18+，仅在你需要 DSH 工具适配器（dsh-cst-tools bundle）时才需要。
* 不需要任何 Python 包。 CST_AI 只用标准库。没有东西要 pip install，也不用创建虚拟环境。

安装

1. 把本仓库克隆或复制到可写位置：

git clone <your-fork-url> CST_AI_public

2. 让 bridge 指向你的 CST 解释器。可以设置环境变量（推荐）：

$env:CST_AI_PYTHON = "C:\Program Files\CST Studio Suite 2026\Python\python.exe"

也可以直接改 cst_ai_tool_bridge.ps1 里的默认值。

3. 创建本地配置（可选，但推荐）。复制 cst_ai_config.json 并设置：

* run_store_path —— 运行记录写入位置（默认 runs），
* default_output_root —— 任务输出目录的解析根（默认 runs），
* cst_runtime_pid_policy —— AUTO 或 EXPLICIT（见下文），
* expected_project —— 可选防护：本次运行预期触及的项目路径，
* parameter_rules —— 可选的参数校验 min/max 规则。

4. （可选） 安装 DSH bundle，省去手动接线：

dsh plugin --profile web add github:aomk20201110-commits/CST_AI#<40-char-commit>

仓库根目录就是 bundle：package.json 声明了 dsh.bundle.patch: ./cordis.patch.yml，所以一条 dsh plugin add 就能同时装好 Node 适配器、PowerShell bridge 和 Python 包。没有构建步骤，安装时也不执行代码，因此 pnpm 永远不需要加白名单。请锁定 commit —— 从 GitHub 安装拉取的是源码，分支随时可能在你脚下变动。

手动 checkout 依然可用：CST_AI_BRIDGE 让适配器指向另一份安装的 bridge。

$env:CST_AI_BRIDGE = "C:\path\to\CST_AI_public\cst_ai_tool_bridge.ps1"

DSH 应用市场的上架信息还没发布；在发布之前，按上面的方式从 GitHub 安装。

5. 跑测试，确认 checkout 健康（见 tests/）：

& $env:CST_AI_PYTHON -m unittest discover -s tests -v

CST_AI 从不启动、停止、杀掉或提权 CST。Design Environment 必须已经在运行（或者你能自己启动它）。

快速开始

1. 规划 —— 不接触 CST，不求解，不写入：

.\cst_ai_tool_bridge.ps1 plan (base64 of the request)

或者从 Python：

from cst_ai_plugin import publicpython
plan = public.plan({
"task_id": "read_my_result",
"task_kind": "LOAD_EXISTING_RESULT",
"stages": ["CONNECT", "EXTRACT", "ANALYZE", "REPORT"],
"solve_policy": "FORBID",
"spec": {"existing_project": "C:/work/solved_model.cst",
"incident_mode": "Zmin(1)"},
"inputs": {},
"expected_outputs": ["resonance_table"],
"output_dir": "runs/read_my_result",
})

print(plan["PLANNED_SOLVE_COUNT"], plan["MAX_AUTHORIZED_SOLVES"])

2. 运行——只产生计划里列出的副作用： python
result = public.run(task, store_root="runs")
print(result["run_id"], result["execution_status"])

3. 之后从任意进程读回结果： python
public.status(run_id) # offline: execution status + solver_usage
public.inspect(run_id)["observables"] # the numbers, and their status
public.resume(run_id) # continue an interrupted run

QUICKSTART.md 用 examples/ 里的示例任务规格走了一遍同样的流程。

公开操作

| 操作 | 是否连接 CST | 是否可能求解 | 写入内容 | 用途 |
| plan | 否 | 否 | 无 | 阶段顺序、计划求解次数、授权预算、阻塞项 |
| run | 是，前提是计划要求 | 只在授权预算内 | run store、artifacts、bundle | 执行 TaskSpec |
| status | 否 | 否 | 无 | 从 run store 读取持久状态：生命周期、检查点、阶段、执行/数值/科学/溯源状态、solver_usage |
| inspect | 否 | 否 | 无 | 只读查看已存储的 run 详情：任务规格、计划、阶段、artifacts、observables、警告、错误、未解决项、事件。工具适配器可以把它过滤到某一节（summary、plan、artifacts、observables、errors、events、all）；Python API 返回全部节 |
| resume | 是，前提是 run 需要 | 只针对尚未完成的阶段 | run store、artifacts | 继续中断的 run，不重复求解已完成的工作 |

status 和 inspect 按约定都是离线的。在 V2.0 里，从 status 请求运行时刷新是刻意不授权的：它会返回 REFRESH_RUNTIME_NOT_AUTHORIZED，而不是悄悄去碰 CST。

TaskSpec 示例 json { "task_id": "cross_fss_point_7p0", "task_kind": "PARAMETER_SWEEP",
"stages": ["CONNECT", "BUILD", "VERIFY", "SOLVE", "EXTRACT", "ANALYZE", "REPORT"],
"solve_policy": "ALLOW_UP_TO_N",
"max_solves": 2,
"spec": {
"fixture_definition": "fixtures/my_unit_cell.json",
"points": [
{"parameter": "cross_span_mm", "value": 6.5, "project_path": "work/point_6p5.cst"},
{"parameter": "cross_span_mm", "value": 7.0, "project_path": "work/point_7p0.cst"}
],
"incident_mode": "Zmin(1)"
},
"inputs": {},
"expected_outputs": ["s_parameters", "resonance_table"],
"output_dir": "runs/cross_fss_point_7p0",
"notes": "TEST_ONLY: not valid for science"
}

必填字段：task_id、task_kind、stages、solve_policy、output_dir。
其余字段都是可选的，会做校验。完整 schema、stage 规则、solve 策略以及各 kind 的要求见 docs/TASKSPEC.md。

安全与 solve 预算模型

* 不会意外触发求解。 真正跑一次求解器，需要同时有 SOLVE stage 和 授权它的 solve 策略（ALLOW_ONE 或 ALLOW_UP_TO_N）。REUSE_ONLY 会把 stage 留在计划里，但把它变成一次复用决策；FORBID 则直接拒绝声明了 SOLVE stage 的任务。
* 求解次数只在一个地方授权。 计划在执行前报告 PLANNED_SOLVE_COUNT 和 MAX_AUTHORIZED_SOLVES；运行记录报告实际执行了什么。超出预算会抛出 SOLVE_BUDGET_EXCEEDED。
* 绝不重复求解已求解的工作。 复用的点必须同时匹配签名 和 产物哈希。不匹配就拒绝复用（SIGNATURE_MISMATCH / CACHE_INVALID），而不是悄悄重新仿真。
* 输出位置不能隐式指定。 output_dir 是必填项；preflight 会拒绝空目录、仓库根目录，或与受保护输入重叠的输出目录。
* CST 被当作别人的活进程。 CST_AI 发现已有的 Design Environment 并挂接上去；它从不启动、停止、杀死或提权 CST。cst_runtime_pid_policy 可以是 AUTO（跟随记录的 runtime PID，失败后回退到发现）或 EXPLICIT（只用你指定的 PID）；两者都要求 PID 经过验证，遇到歧义就报告，而不是猜。
* 各种状态不能互换。 execution_status、numerical_status、scientific_status 和 provenance_status 分别报告。一次完成的求解器运行，如果观测量无法解析，就是 COMPLETED 且 UNRESOLVED —— 两者都成立。

结果能力

共注册了 21 项能力；每项都带有验证状态、输入输出，以及是否需要求解。重点如下：

| 能力 | 你能得到什么 | solve |
| S_PARAMETERS | 1D 结果树通道，只读，解析成 port/mode 结构 | never |
| FLOQUET_MULTIMODE | 单胞 Floquet 通道，带声明的模式数 | never |
| POWER_RTA | 每个频点的反射 / 透射 / 吸收能量平衡 | never |
| RESONANCE_F0、FWHM、Q_LINEWIDTH | 经过验证的谐振指标，带明确的 validity 码 | never |
| MESH_CONVERGENCE、FREQUENCY_CONVERGENCE | 求解器记录的关于自适应与收敛的信息 | never |
| FARFIELD_COMPLEX_FIELD | 来自已有 farfield monitor 的 theta/phi 网格上的复场 | never |
| DIRECTIVITY、GAIN、REALIZED_GAIN | 峰值，线性或 dB，并说明归一化方式 | never |
| BEAM_DIRECTION | 最大值处的拓扑（相关时为 NEAR_DEGENERATE_AZIMUTH_RING） | never |
| HPBW | 从读取的网格算出的 −3 dB 波束宽度，并报告所用切面 | never |
| MODEL_BUILD、DRY_BUILD | 从 fixture 构建模型，再读回语义 | 不求解 |
| SOLVE、PARAMETER_SWEEP | 仅有的两个会消耗求解额度的能力 | 受预算约束 |
| REFERENCE_COMPARATOR | 可选的语义比较器 | 从不消耗 |

除 REFERENCE_COMPARATOR 外，其余能力都能通过五个公开 action 触达。
完整表格——验证阶段、证据、可用性与限制——见 CAPABILITY_MATRIX_V2.0.md。

限制

* 仅支持 Windows。 启动器和 CST Python API 集成都基于 Windows。
* 你必须自己拥有 CST。 CST Studio Suite 不属于本项目；CST_AI 只是一个客户端，连接你单独授权的安装。
* 同一时间只能有一个活动 Design Environment。 CST_AI 只挂接单个活动 DE，遇到歧义会直接报告，而不是随意挑一个。
* 只读能力要求结果已存在。 FARFIELD_、DIRECTIVITY、GAIN、REALIZED_GAIN、BEAM_DIRECTION 和 HPBW 会激活已存储的远场结果；它们绝不会重新求解来获取结果。
远场读回依赖结果激活。 选中已存储的树节点后，角度数据通过文档化的远场评估列表链读取。CST 原生的 GetMainLobeDirection / GetAngularWidthXdB getter 仅对 .Plottype "Polar" 有文档支持，在本插件读取的结果上会抛错，因此波束方向取自读回的网格，HPBW 也由该网格计算。
* 不做优化。 PARAMETER_SWEEP 只评估你列出的点；它不会自适应调整参数、搜索空间，也不声称某个点是「最优」。
* 不支持自然语言输入。 TaskSpec 由你手写。（见路线图。）
* fixture 由你自备。 CST 工程几何不可再分发，因此本仓库只提供 fixture 定义的形状，不提供现成的 CST 模型。
* 可重复性受物理与求解器限制。 对已存储结果的数值完全相同的重读是精确的；新求解的可重复性则与 CST 本身一致。

路线图

| 版本 | 主题 |
| 2.0.x | 可靠性、产物定稿、错误处理（包含 KNOWN_ISSUE_V2_0_001 / _002） |
| 2.1 | 自然语言 → TaskSpec（仅规划；求解预算规则保持不变） |
| 2.2 | 在现有 sweep 引擎之上做优化与参数搜索 |
| 2.3 | 任务队列与多会话执行 |

路线图条目只是意向，不是承诺，且其中任何一项都不会削弱上述求解预算或来源追溯规则。

许可证

MIT —— 见 LICENSE。第三方声明，包括与 CST Studio Suite 的关系，见 THIRD_PARTY_NOTICES.md。

第三方免责声明

CST Studio Suite 及其 Python API 是 Dassault Systèmes 的产品。它们不随本项目分发，本项目也不隶属于、也不获得其背书由 Dassault Systèmes 提供、或由其赞助。要使用 CST_AI，你必须自行安装有效的 CST Studio Suite，并持有相应许可证。详见 THIRD_PARTY_NOTICES.md。