新增基础版系统仿真 Skill

skills/system-simulation/references/file-contracts.md

@@ -0,0 +1,95 @@
+# 文件合同与解释规则
+
+## 支持范围
+
+本 Skill 只接受以下两种当前格式：
+
+| 格式 | 版本标志 | 用途 |
+| --- | --- | --- |
+| ReactFlow 工程 JSON | 顶层 `projectSchemaVersion: 1` | 保存组件、画布、端口显示快照、连线和仿真设置，适合继续编辑 |
+| System XML | 根元素 `System/@schemaVersion="3"` 且 `unitSystem="SI"` | 保存可执行模型，适合校验、编译和求解 |
+
+默认让 `inspect --format auto` 根据内容和扩展名识别格式。若内容与扩展名不一致、无法唯一识别或用户明确指定格式，则报告实际证据，不悄悄按另一种格式解释。
+
+System XML v1/v2、缺少 `projectSchemaVersion` 的旧工程、字符串端口和不匹配的组件 `modelVersion` 均不属于本 Skill 的迁移范围。不能只改版本号使其看似当前格式。
+
+## 工程 JSON v1
+
+顶层合同为：
+
+```text
+projectSchemaVersion = 1
+name
+nodes[]
+edges[]
+simulation { t_start, t_stop, step, max_step, method }
+```
+
+重要规则：
+
+- 节点的 `id` 是实例稳定标识；显示标签不能替代它。
+- `data.modelType` 标识注册模型，`data.modelVersion` 必须与当前组件目录精确匹配，执行前不得自动补成当前版本。
+- `data.parameters` 保存输入值；`parameterUnits`、科学计数法偏好、坐标、旋转和镜像属于编辑显示信息。
+- 连接必须保留两端组件及 Handle。不能根据节点位置猜测缺失端口。
+- `simulation.step` 是结果采样间隔；`max_step` 是求解器内部步长上限，两者不能混用。
+
+工程 JSON 可以导出为 System XML v3，但转换后不会保留全部画布显示信息的对等逆转换合同。
+
+## System XML v3
+
+XML v3 只描述“求解什么”：
+
+- 每个 `Component` 必须有唯一 `id`、注册 `type`、精确 `modelVersion` 和完整 SI 参数；
+- 每条连接由两个 `Endpoint(component, port)` 组成；端口类型、方向和物理合同由后端注册表恢复；
+- `Simulation/@sampleStep` 对应工程 JSON 的 `simulation.step`；
+- 不保存组件位置、旋转、镜像、显示单位或端口显示快照；
+- 当前后端固定按 v3 校验，不会根据文件内容选择旧解析器。
+
+XML 校验依次覆盖安全/语法、XSD 和语义层。通过这些检查后，编译和求解仍可能发现未连接端口、缺少储能锚点、方程结构或数值问题。
+
+## 简要解释模型
+
+解释必须依据 `inspect` 的结构化输出以及组件目录，而不是仅凭组件名称推测。优先说明：
+
+1. 文件格式、版本和项目名；
+2. 仿真起止时间、采样间隔、最大内部步长和算法；
+3. 组件数量、稳定 ID、模型类型和主要输入参数；
+4. 连接数量、连接端点及能够确定的物理域；
+5. 错误、警告，以及它们属于格式、语义、编译还是运行阶段。
+
+保持“文件合同正确”和“物理模型合理”两个结论分开。没有组件文档或注册元数据支持时，不声称某个参数具有推测出的物理效果。
+
+## 参数与结果变量
+
+必须明确区分：
+
+- **参数**：仿真开始前设定的固定输入，例如质量、初始压力、摩擦选项；通常没有时间序列。
+- **结果变量**：仿真返回的时间序列，例如位移、速度、压力或流量；只有这类量可以选作曲线。
+
+选择曲线时以结果元数据为准，至少核对：
+
+```text
+key + componentId + componentType + label/quantity + unit
+```
+
+稳定 `key` 是传给 `simulate --variables` 的最终标识。用户只说“质量块的速度”而存在多个质量块，或一个组件存在多个符合描述的速度结果时，列出候选的组件 ID、结果名称和单位，请用户消歧。
+
+`inspect` 默认对组件摘要、连接和结果变量分页。先读取 `componentTypes` 了解完整模型的组件类型分布，再根据 `componentPage`、`connectionPage` 或 `resultVariablePage` 的 `nextOffset` 翻页。优先使用 `--variable-query` 按组件 ID、标签、物理量或单位缩小范围；只有用户点名组件时才使用 `--component` 读取该组件的完整源数据和可用的编译合同。
+
+组件摘要中的 `compiledForSimulation` 表示该节点是否进入动态求解网络。介质/物性配置节点仍属于工程，因此会保留在组件总数和列表中，但通常标记为 `false`；这不表示组件丢失或编译失败。
+
+曲线模式约束：
+
+- `separate`：每个所选结果变量分别成图；
+- `overlay`：只叠加单位相同且含义可比较的结果变量；
+- `stacked`：不同物理量或不同单位上下排列，避免共用一个纵轴造成误读。
+
+本版运行 `simulate` 时必须指定至少一个 `--variables` 稳定键，避免在大型模型上无意生成成百上千张曲线。完整 CSV 仍包含全部可用结果变量。
+
+## 权威来源
+
+- 工程 JSON 请求合同：`app/main.py` 中的 `ReactFlowProjectPayload`
+- 组件目录：`GET /api/components/catalog`
+- XML v3：`schemas/system-simulation-v3.xsd`、`docs/standard/system-xml-v3.md`
+- 接口边界：`docs/standard/backend-interface-version-spec-v1.md`
+- 结果变量：组件注册合同中的 `RESULT_VARIABLES` 及仿真结果元数据