更新v2版本适配skill
This commit is contained in:
ljz committed
1 parent
7611f13208
commit
2f3f7d00ec
58 files changed
+180419
-526
No files matched your search
@@ -1,95 +1,67 @@
|
||||
# 文件合同与解释规则
|
||||
# 文件合同与当前代码依据
|
||||
|
||||
## 支持范围
|
||||
## 格式与单位
|
||||
|
||||
本 Skill 只接受以下两种当前格式：
|
||||
| 格式 | 当前合同 |
|
||||
| --- | --- |
|
||||
| 工程 JSON v2 | 新建/导出的编辑工程；数值、十进制数字字符串、表达式全部按 parameterUnits[name] 解释，省略单位使用目录 SI 单位 |
|
||||
| 工程 JSON v1 | 兼容读取；普通数值/十进制数字字符串为 SI，表达式按显示单位解释 |
|
||||
| System XML v3 | 根元素 schemaVersion="3" unitSystem="SI"，只保存执行模型 |
|
||||
|
||||
| 格式 | 版本标志 | 用途 |
|
||||
| --- | --- | --- |
|
||||
| ReactFlow 工程 JSON | 顶层 `projectSchemaVersion: 1` | 保存组件、画布、端口显示快照、连线和仿真设置，适合继续编辑 |
|
||||
| System XML | 根元素 `System/@schemaVersion="3"` 且 `unitSystem="SI"` | 保存可执行模型，适合校验、编译和求解 |
|
||||
v2 的 p0: 2.5、"2.5"、"=2.5" 配 bar 都是 250000 Pa；20 degC 为 293.15 K。压力为绝压，不能自动加减大气压。缺失参数使用目录 SI 默认值，不随显示单位二次换算。
|
||||
|
||||
默认让 `inspect --format auto` 根据内容和扩展名识别格式。若内容与扩展名不一致、无法唯一识别或用户明确指定格式，则报告实际证据，不悄悄按另一种格式解释。
|
||||
v1→v2 由前端 encodeProjectParameters() 等现有转换逻辑完成，不得只改版本号。内部归一化的 v1/SI 对象不是 v2 导出文件。未知型号、参数、单位不能靠改版本掩盖。
|
||||
|
||||
System XML v1/v2、缺少 `projectSchemaVersion` 的旧工程、字符串端口和不匹配的组件 `modelVersion` 均不属于本 Skill 的迁移范围。不能只改版本号使其看似当前格式。
|
||||
|
||||
## 工程 JSON v1
|
||||
|
||||
顶层合同为：
|
||||
## 编辑工程字段
|
||||
|
||||
```text
|
||||
projectSchemaVersion = 1
|
||||
name
|
||||
nodes[]
|
||||
edges[]
|
||||
simulation { t_start, t_stop, step, max_step, method }
|
||||
projectSchemaVersion: 2
|
||||
name: string
|
||||
nodes[]:
|
||||
id: 唯一稳定 ID
|
||||
type: "simulationComponent"
|
||||
position: { x: 有限数值, y: 有限数值 }
|
||||
data:
|
||||
label, componentType, modelType, modelVersion
|
||||
ports[]: { name, kind, domain, nominalRole, side, positiveFlowDirection? }
|
||||
parameters: { 参数名: 数值或表达式字符串 }
|
||||
parameterUnits: { 参数名: 单位 }
|
||||
parameterScientificNotation: {}
|
||||
rotation: 0 | 90 | 180 | 270
|
||||
mirrored: boolean
|
||||
edges[]:
|
||||
id, source, target, sourceHandle, targetHandle
|
||||
data: { isContactEdge: boolean, routePoints?: [{x,y}] }
|
||||
simulation: { t_start, t_stop, step, max_step, method }
|
||||
```
|
||||
|
||||
重要规则：
|
||||
- 顶层禁止未知字段，假设与验收记录放独立报告。componentType/modelType 均用真实注册类型，显示标签不是模型标识。
|
||||
- Handle 用真实端口名，不按画面编号猜测。普通连线 isContactEdge=false，接触连线由网页几何决定。
|
||||
- 目录端口不能原样复制：信号端口 positiveFlowDirection:null 必须省略。生成器只复制必要快照字段；物理合同始终来自注册表。
|
||||
- LMECHN1 保存完整 21 个注册端口快照；v1=N 决定 N 个右端口和 port_(N+1) 左参考端口。连通性只统计注册模型 active_ports() 返回的活动端口。
|
||||
- 网页要求每个活动显示端口恰好连接一次，不能用后端对某些未接信号口的容忍替代网页检查，不能删快照端口绕过。
|
||||
- 介质节点属于工程但不一定进入动态求解。gi=0 为内置空气；1..99 引用唯一介质定义。多介质不能重复套用默认 gi=1。
|
||||
- 离散参数按目录 editor/options 数值编码，部分开关为 1/2，不能推定为 0/1。
|
||||
|
||||
- 节点的 `id` 是实例稳定标识；显示标签不能替代它。
|
||||
- `data.modelType` 标识注册模型，`data.modelVersion` 必须与当前组件目录精确匹配，执行前不得自动补成当前版本。
|
||||
- `data.parameters` 保存输入值；`parameterUnits`、科学计数法偏好、坐标、旋转和镜像属于编辑显示信息。
|
||||
- 连接必须保留两端组件及 Handle。不能根据节点位置猜测缺失端口。
|
||||
- `simulation.step` 是结果采样间隔；`max_step` 是求解器内部步长上限，两者不能混用。
|
||||
## 执行与结果
|
||||
|
||||
工程 JSON 可以导出为 System XML v3，但转换后不会保留全部画布显示信息的对等逆转换合同。
|
||||
step 是结果采样间隔，max_step 是内部最大步长。当前执行方法为 RK45/BDF；四个时间字段支持平台表达式。
|
||||
|
||||
## System XML v3
|
||||
JSON 适配层对不同/缺失组件版本警告并选择当前模型；类型、端口、未知参数和数值错误仍拒绝。LMECHN1/FORC 的显式兼容处理由平台完成，不能推广为任意迁移。新工程始终取当前版本。
|
||||
|
||||
XML v3 只描述“求解什么”：
|
||||
XML 的组件需要精确 modelVersion 和完整 SI 参数，连接为两个 Endpoint(component,port)。JSON 导出器补齐默认参数，XML 解析器本身不猜默认值。XML parse 返回执行模型，不能直接作为可无损恢复布局的工程。
|
||||
|
||||
- 每个 `Component` 必须有唯一 `id`、注册 `type`、精确 `modelVersion` 和完整 SI 参数；
|
||||
- 每条连接由两个 `Endpoint(component, port)` 组成；端口类型、方向和物理合同由后端注册表恢复；
|
||||
- `Simulation/@sampleStep` 对应工程 JSON 的 `simulation.step`；
|
||||
- 不保存组件位置、旋转、镜像、显示单位或端口显示快照；
|
||||
- 当前后端固定按 v3 校验，不会根据文件内容选择旧解析器。
|
||||
simulation_skill.py inspect 返回源哈希、版本、组件/连接/变量分页、诊断与未接端口；不是网页导入验收。默认页大小分别为 50/25/20，用 --component ID、--variable-query QUERY 和 offset/limit 定位。compiledForSimulation=false 的配置节点仍属于工程。
|
||||
|
||||
XML 校验依次覆盖安全/语法、XSD 和语义层。通过这些检查后，编译和求解仍可能发现未连接端口、缺少储能锚点、方程结构或数值问题。
|
||||
结果曲线按 key + componentId + quantity + unit 选择。separate 分图；overlay 仅叠加同单位且可比较的量；stacked 用于不同量。不能把固定参数当时间序列。
|
||||
|
||||
## 简要解释模型
|
||||
## 权威来源（相对仓库根目录）
|
||||
|
||||
解释必须依据 `inspect` 的结构化输出以及组件目录，而不是仅凭组件名称推测。优先说明：
|
||||
- app/main.py：ReactFlowProjectPayload、JSON→XML、编译及 HTTP 接口。
|
||||
- app/project_parameters.py、frontend/src/projectCompatibility.ts：版本、单位、表达式与兼容转换。
|
||||
- app/simulation/registry.py、GET /api/components/catalog：型号、参数、端口、版本。
|
||||
- frontend/src/App.tsx：parseProjectPayload、displayedPortsForNodeData、导入导出与网页检查。
|
||||
- schemas/parameter-units.json、schemas/system-simulation-v3.xsd。
|
||||
- docs/standard/backend-interface-version-spec-v1.md、component-library-spec-v1.md、port-computation-contract.md、system-xml-v3.md。
|
||||
|
||||
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` 及仿真结果元数据
|
||||
文档文件名 v1 不是工程版本。代码变更与说明不一致时核对解析器、注册表与测试。
|
||||
Reference in new issue
Block a user