96 lines
5.1 KiB
Markdown
96 lines
5.1 KiB
Markdown
# 文件合同与解释规则
|
||
|
||
## 支持范围
|
||
|
||
本 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` 及仿真结果元数据
|