---
name: system-simulation
description: 读取、校验并简要解释 SystemSimulationApp 工程 JSON v1 或 System XML v3，安全规范化文件文本，运行并监视仿真、导出结果，以及在用户确认计划后对 JSON v1 执行单目标、有界连续 SI 参数优化。适用于检查模型、修复编码或换行、运行仿真、获取结果和优化结果统计量；不用于旧格式迁移、任意语义修复、离散或拓扑优化、多目标优化或网页自动预装。
metadata:
  openclaw:
    requires:
      bins: [python3.12]
---

# 系统仿真

使用本 Skill 随附的确定性脚本检查模型、调用现有后端并保存结果；不要让语言模型自行重写模型或猜测求解数据。`simulation_skill.py` 处理文件和单次仿真，同一 Skill 内的独立入口 `optimization_skill.py` 处理优化计划与执行。

## 基本边界

- 仅处理 ReactFlow 工程 JSON v1 和 System XML v3。版本缺失、不受支持或模型版本不匹配时，说明问题并停止，不进行迁移猜测。
- 组件参数是仿真前设定的固定输入；结果变量才是可随时间绘制的量。不要把“参数”当成结果曲线。
- 工程 JSON 可在连续数值参数中保存受限算术表达式。检查、编译或生成 XML 时由后端安全求值并换算为 SI；不得把计算结果回写到源 JSON。
- 文件通过格式校验不等于物理系统一定可求解。不要隐瞒编译或运行阶段的诊断。
- 不直接覆盖源文件。普通检查或仿真不自行修改参数、连接、组件类型、模型版本或求解设置；优化也只能在用户确认的派生副本中改变明确选定的参数。
- 优化仅面向 ReactFlow 工程 JSON v1，设计变量必须由用户指定，或由用户明确授权 Skill 提议后再纳入计划；它们必须是连续、线性 SI 参数。现有后端不负责证明参数连续性，不能只因字段是数字就自动选作设计变量。带编辑器、离散选项或后端显式否决的参数必须拒绝，整数、条件显示控制量及会改变活动端口、模式或拓扑的参数不得进入连续优化。
- 本版不支持把模型自动注入网页、生成可直接打开的预装页面、任意损坏文件修复、模型迁移、离散或拓扑优化以及多目标优化。不要用手工网页操作冒充支持。

处理文件、解释格式或选择结果变量时，读取 [references/file-contracts.md](references/file-contracts.md)。请求文件修复时，再读取 [references/repair-policy.md](references/repair-policy.md)。需要运行、监视、取消仿真或交付结果时，读取 [references/workflows.md](references/workflows.md)。用户请求按仿真结果优化参数时，必须读取 [references/optimization-workflow.md](references/optimization-workflow.md)。

## 工作原则

1. 先用 `inspect` 确认输入格式、版本、结构和诊断，再基于检查结果简要解释组件、连接与仿真设置。
2. 如果用户要求修复，只能执行文本规范化。先展示预览和源文件 SHA-256，获得针对该预览的明确确认后，才可写入另一个输出路径；随后重新 `inspect`。
3. 单次仿真前必须让用户选择直接曲线查看方式，并解析具体结果变量：
   - 分别查看所选变量；
   - 将多个同单位、可比较的变量叠加；
   - 将不同物理量或单位的变量上下排列。
4. 用户用显示名称描述组件或变量时，利用检查结果中的稳定 ID、结果 `key`、物理量和单位消歧。存在重名、多个候选或“参数/结果变量”含义不清时，先询问，不能替用户猜。
5. 使用 `simulate` 的事件流持续判断 queued、validating、compiling、integrating 和结束状态。仿真时间暂时不变但内部活动仍增长时，只说明正在处理慢步，不能宣称卡死。
6. 成功运行后交付用户选择的 SVG 曲线和完整 `results.csv`，并简要说明完成状态、实际仿真终点和重要诊断。失败或取消时交付能够安全生成的部分结果；若运行前即失败而没有 CSV，要明确说明原因。
7. 优化需求优先按自然语言理解：从检查结果补齐稳定结果 `key`、单位和当前参数值，未指定的算法、预算、容差和输出目录采用参考文档中的推荐默认值。不要要求用户填写规格 JSON，也不要追问随机种子、变异因子等已有默认值。
8. 信息足以形成规格后，直接在内部写入规格并执行无候选仿真的 `plan`，无需先征求生成计划的许可。计划阶段用普通语言只展示目标、可调参数及范围、约束、最多仿真次数、输出位置和重要假设。参数明显是连续物理标量时，把连续性作为计划假设，一次整体执行确认即可覆盖；只有语义确有歧义时才自然地追问。内部声明代码、SHA、`planHash` 和 `confirmationToken` 默认不展示。
9. 生成计划不等于获准执行。只有用户看过计划摘要并明确表示开始后才能传入 `--confirmed`；用户只要求计划时必须停在计划阶段。计划任一实质内容变化都要重新确认。
10. 优化中的失败、取消、停滞或不完整仿真不计算目标分数。最终只对预算内找到的最佳可行候选做一次绕过缓存的完整复验；复验通过前不把候选称为已验证方案。
11. 严格区分搜索停止与候选复验：`verified` 只说明最佳搜索候选的新鲜复验通过，不等于搜索收敛、系统达到稳态或全局最优。报告时分别说明搜索候选评估、按阶段拆分的仿真预算槽位占用及完成/失败记录、未形成试验记录的槽位、缓存命中、独立复验、未用预算和真实停止原因；槽位占用不能说成后端已接收或已完成。内部防死循环上限及重复停滞后的种群塌缩都不得解释成“已收敛”。
12. 目标使用 `final` 时必须报告脚本给出的末段趋势诊断状态；只有完整且覆盖计划终点的新鲜序列才能分析趋势，诊断不可用或样本不足时明确说明且不自行推断。检测到明显变化时，说明终点值只是快照。新鲜复验已经通过后不再建议重复同一复验；最佳点落在边界时，只能说明已采样点的趋势，未经工程可行性确认不得建议放宽边界。

脚本命令统一从仓库根目录运行：

```powershell
py -3.12 skills/system-simulation/scripts/simulation_skill.py --help
py -3.12 skills/system-simulation/scripts/optimization_skill.py --help
```

在 OpenClaw 中不要假设当前目录是仓库根目录。使用 `"{baseDir}/scripts/simulation_skill.py"` 或 `"{baseDir}/scripts/optimization_skill.py"`，也可以先进入本 Skill 目录再从 `scripts/` 运行；不要把 `{baseDir}` 当成需要手工猜测的仓库路径。

Windows 优先使用仓库 `.venv-win\Scripts\python.exe`（若存在），否则使用 `py -3.12`；Linux 优先使用 `.venv/bin/python`，否则使用 `python3.12`。不要调用未经版本确认的 `python`，本项目要求 Python 3.12。

优先依赖脚本返回的结构化 JSON/JSONL、稳定错误码和退出码做判断，不解析中文提示文本来驱动下一步。