文件合同与解释规则

支持范围

本 Skill 只接受以下两种当前格式：

格式	版本标志	用途
ReactFlow 工程 JSON	顶层 `projectSchemaVersion: 1`	保存组件、画布、端口显示快照、连线和仿真设置，适合继续编辑
System XML	根元素 `System/@schemaVersion="3"` 且 `unitSystem="SI"`	保存可执行模型，适合校验、编译和求解

默认让 inspect --format auto 根据内容和扩展名识别格式。若内容与扩展名不一致、无法唯一识别或用户明确指定格式，则报告实际证据，不悄悄按另一种格式解释。

System XML v1/v2、缺少 projectSchemaVersion 的旧工程、字符串端口和不匹配的组件 modelVersion 均不属于本 Skill 的迁移范围。不能只改版本号使其看似当前格式。

工程 JSON v1

顶层合同为：

projectSchemaVersion = 1
name
nodes[]
edges[]
simulation { t_start, t_stop, step, max_step, method }

重要规则：

节点的 id 是实例稳定标识；显示标签不能替代它。
data.modelType 标识注册模型，data.modelVersion 必须与当前组件目录精确匹配，执行前不得自动补成当前版本。
data.parameters 保存输入值；parameterUnits、科学计数法偏好、坐标、旋转和镜像属于编辑显示信息。
连续数值参数可保存受限算术表达式字符串。支持可选前导 =、+ - * / ^ **、括号、科学计数法、pi/e 和白名单函数 sqrt/abs/sin/cos/tan/asin/acos/atan/exp/ln/log/log10/min/max/pow。不支持变量引用、组件间引用、属性访问或任意代码。
普通数值及可直接解析的数值字符串按已存储的 SI 值处理；只有表达式的计算结果才按 parameterUnits 中的显示单位换算为 SI。例如 area0 = "3.14*10**2/4" 且单位为 mm2 时，XML 值为 7.85e-05 m²，JSON 仍保留原表达式。
下拉选项、介质引用等离散参数不允许使用表达式。表达式语法、值域或复杂度不合法时，必须在编译/仿真前明确报错，不得猜测或改写。
连接必须保留两端组件及 Handle。不能根据节点位置猜测缺失端口。
simulation.step 是结果采样间隔；max_step 是求解器内部步长上限，两者不能混用。

工程 JSON 可以导出为 System XML v3，但转换后不会保留全部画布显示信息的对等逆转换合同。导出时表达式仅在内存中求值，System XML 只写入换算后的 SI 数值，不改动输入工程对象或源 JSON 文件。

System XML v3

XML v3 只描述“求解什么”：

每个 Component 必须有唯一 id、注册 type、精确 modelVersion 和完整 SI 参数；
每条连接由两个 Endpoint(component, port) 组成；端口类型、方向和物理合同由后端注册表恢复；
Simulation/@sampleStep 对应工程 JSON 的 simulation.step；
不保存组件位置、旋转、镜像、显示单位或端口显示快照；
当前后端固定按 v3 校验，不会根据文件内容选择旧解析器。

XML 校验依次覆盖安全/语法、XSD 和语义层。通过这些检查后，编译和求解仍可能发现未连接端口、缺少储能锚点、方程结构或数值问题。

简要解释模型

解释必须依据 inspect 的结构化输出以及组件目录，而不是仅凭组件名称推测。优先说明：

文件格式、版本和项目名；
仿真起止时间、采样间隔、最大内部步长和算法；
组件数量、稳定 ID、模型类型和主要输入参数；
连接数量、连接端点及能够确定的物理域；
错误、警告，以及它们属于格式、语义、编译还是运行阶段。

保持“文件合同正确”和“物理模型合理”两个结论分开。没有组件文档或注册元数据支持时，不声称某个参数具有推测出的物理效果。

参数与结果变量

必须明确区分：

参数：仿真开始前设定的固定输入，例如质量、初始压力、摩擦选项；通常没有时间序列。
结果变量：仿真返回的时间序列，例如位移、速度、压力或流量；只有这类量可以选作曲线。

选择曲线时以结果元数据为准，至少核对：

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 及仿真结果元数据

6.0 KiB Raw Blame History Unescape Escape