feat: integrate AMESim media models and editor UI

docs/README.md

@@ -12,6 +12,8 @@
    `GET /api/components/catalog` 的机器可读结构。
 4. [AMESim 子模型公开组件迁移矩阵](amesim-component-migration-matrix.md)
    用于划分 `test_mql` 子模型族的公开组件、内部模型和暂不支持范围。
+5. [AMESim 氦气 Peng-Robinson 介质模型](amesim-helium-peng-robinson.md)
+   记录本地 AMESim 资料、氦气参数、索引映射和首版计算边界。
 
 建议人工和 AI 先阅读建模规范，再阅读读取规范，然后参考目标分类中最接近的现有
 模型。不要从前端兜底数据反推后端物理契约。
@@ -36,6 +38,8 @@
 | 库和显示声明 | [`app/simulation/core/catalog.py`](../app/simulation/core/catalog.py) |
 | 库发现与注册校验 | [`app/simulation/registry.py`](../app/simulation/registry.py) |
 | 临时库清单 | [`app/simulation/components/experimental/library.py`](../app/simulation/components/experimental/library.py) |
+| AMESim 第一版公开临时库清单 | [`app/simulation/components/amesim/library.py`](../app/simulation/components/amesim/library.py) |
+| `test_mql` 固定算例入口 | [`app/simulation/examples/test_mql/system.py`](../app/simulation/examples/test_mql/system.py) |
 | 元件完整示例 | [`app/simulation/components/example.md`](../app/simulation/components/example.md) |
 
 ## AI 使用原则

docs/amesim-component-migration-matrix.md

@@ -1,62 +1,64 @@
 # AMESim 子模型公开组件迁移矩阵
 
-状态：规划中  
-适用模型：`AmesimModels/test_mql.ame` / `PythonModels.systems.test_mql`  
+状态：21 个模型已在临时 AMESim 库完成第一版公开，持续校准中
+
+适用模型：`AmesimModels/test_mql.ame` / `app.simulation.examples.test_mql.system`
+
 配套规范：[`component-model-authoring-spec-v1.md`](component-model-authoring-spec-v1.md)
 
 ## 目标
 
-本文档把 `test_mql` 中的 AMESim 子模型族拆成可执行的迁移批次。它不是组件注册清单；只有完成公开模型契约、方程实现、最小 XML 编译/仿真测试后，子模型才能加入某个 `library.py` 的 `models` 清单并出现在前端组件库中。
+本文档记录 `test_mql` 中 AMESim 子模型族的公开状态和后续校准批次。实际注册清单以 `app/simulation/components/amesim/library.py` 为准。
 
 当前原则：
 
 - 不把现有固定拓扑 `TestMqlSystem` 整体注册为公开拖拽组件。
-- 不把机械、信号、事件元件提前伪装成可由当前气动求解器仿真的公开组件。
-- 可先公开当前 `app.simulation` 求解链路能承载的气动元件：储能、阻性、孔口、三通/四通、准稳态管段。
-- 对 AMESim 精确语义尚未复刻的元件，允许先做内部模型或文档化候选，不能在目录中标记为完成。
+- 第一版公开只表示模型契约、目录、XML 编译和最小仿真链路已接通，不表示 AMESim 精确语义已完成复刻。
+- 气动、标量信号和一维机械模型按当前求解链路能力公开；事件与跨域耦合继续保留明确限制。
+- 固定算例专用的校准原语留在 `examples/test_mql/`，不与公共组件目录混为同一实现。
 
 ## 当前求解器能力边界
 
 `app.simulation` 当前支持：
 
-- 物理域：`pneumatic`。
-- 端口变量：`p`、`m_flow`、`h_outflow`。
+- 物理域：`pneumatic`、标量 `signal` 和一维 `mechanical`。
+- 端口变量：气动 `p/m_flow/h_outflow`、信号 `signal`、机械 `x/v/f`。
 - 流量符号：`m_flow > 0` 表示流入当前组件。
-- 网络方程：连接压力相等、连接流量和为零、组件压力-流量残差、stream 焓传播。
+- 网络方程：气动连接压力相等、流量和为零、组件压力-流量残差与 stream 焓传播；标量信号传播；机械 `x/v` 等值和 `f` 平衡。
 - 动态：半显式 ODE，动态组件提供质量和内能状态导数。
-- 暂不支持：机械端口、信号端口仿真、事件系统、一般高指数 DAE、AMESim 气体定义组件对全局 medium 的动态切换。
+- 暂不支持：完整事件系统、一般高指数 DAE、气动-机械实时跨域组件，以及从 PNGD00 自动批量导入其他气体。公共编译链已经支持“介质 + 物性计算方法”定义元件：`gi=0` 使用内置空气理想气体，`gi=1..99` 引用画布中的显式介质物性实例；介质定义内部通过 `property_model` 下拉接口选择计算方法。氦气已提供 Peng-Robinson 首版。
 
 ## 子模型族矩阵
 
 | AMESim 子模型 | 数量 | AMESim 角色 | 当前公开状态 | 建议目标 | 先决条件 / 限制 |
 | --- | ---: | --- | --- | --- | --- |
-| `PNCH023` | 4 | 固定容积气室，带换热 | 候选公开 | `amesim_pnch023`，`storage` | 可基于 `ThermodynamicVolumeComponent`；需按 AMESim `cvol/extemp/kth/sth/gi` 复核质量、能量、换热方程。 |
-| `PNCH012` | 8 | 变容气室，带换热 | 参数化第一版公开 | `amesim_pnch012`，`storage` | 已将 AMESim `vol1..4/dvol1..4` 外部体积输入映射为 SI 参数，支持固定/预设体积场景；实时机械耦合仍需后续机械域或输入端口协议。 |
-| `PNOR001` | 8 | 常系数气动孔口 | 候选公开 | `amesim_pnor001`，`flow` | 可基于 `AlgebraicComponent`；需按 AMESim `cq/area/Cv/Kv/flowset/gi` 复核双向流、零压差正则化和单位换算。 |
-| `PNVO001` | 8 | 信号调制气动孔口 | 第一版公开 | `amesim_pnvo001`，`flow` | 已接入标量信号端口 `res`，可由 `amesim_step0` 驱动开度；精确事件语义和 AMESim baseline 仍留后续修模。固定开度变体 `amesim_pnvo001_fixed` 继续保留。 |
-| `PN3NODE2` | 8 | 三端气动节点，压力温度由 port 2 固定 | 候选公开 | `amesim_pn3node2`，`junctions` | 当前 `Tee` 是通用三通近似；AMESim port 2 参考温压语义和 stream 混合需单独测试。 |
-| `P4NODE2` | 8 | 四端气动节点，压力温度由 port 2 固定 | 候选公开 | `amesim_p4node2`，`junctions` | 需要新增四端 junction 基类/模型；复核 port 2 参考温压和多支路混合。 |
-| `PNL00R` | 4 | 管路纯阻性摩擦段 | 候选公开 | `amesim_pnl00r`，`flow` | 可基于准稳态阻性管；需按 AMESim `PNL00R` 参数和摩擦公式复核。 |
+| `PNCH023` | 4 | 固定容积气室，带换热 | 第一版公开 | `amesim_pnch023`，`storage` | 已基于 `ThermodynamicVolumeComponent` 接入公开契约；仍需按 AMESim `cvol/extemp/kth/sth/gi` 复核质量、能量、换热方程。 |
+| `PNCH012` | 8 | 变容气室，带换热 | 参数化第一版公开 | `amesim_pnch012`，`storage` | 已将 AMESim `vol1..4/dvol1..4` 外部体积输入映射为 SI 参数，支持固定/预设体积场景；实时机械耦合仍需跨域组件契约和闭合支持。 |
+| `PNOR001` | 8 | 常系数气动孔口 | 第一版公开 | `amesim_pnor001`，`flow` | 已接入代数组件公开契约；仍需按 AMESim `cq/area/Cv/Kv/flowset/gi` 复核双向流、零压差正则化和单位换算。 |
+| `PNVO001` | 8 | 信号调制气动孔口 | 第一版公开 | `amesim_pnvo001`，`flow` | 已接入名为 `res` 的标量信号输入端口，可由 `amesim_step0` 驱动开度；精确事件语义和 AMESim baseline 仍留后续修模。固定开度变体 `amesim_pnvo001_fixed` 继续保留。 |
+| `PN3NODE2` | 8 | 三端气动节点，压力温度由 port 2 固定 | 第一版公开 | `amesim_pn3node2`，`junctions` | 已接入三端等压、流量守恒基础版；AMESim port 2 参考温压语义和 stream 混合仍需单独测试。 |
+| `P4NODE2` | 8 | 四端气动节点，压力温度由 port 2 固定 | 第一版公开 | `amesim_p4node2`，`junctions` | 已接入四端等压、流量守恒基础版；仍需复核 port 2 参考温压和多支路混合。 |
+| `PNL00R` | 4 | 管路纯阻性摩擦段 | 第一版公开 | `amesim_pnl00r`，`flow` | 已接入准稳态阻性管公开契约；仍需按 AMESim `PNL00R` 参数和摩擦公式复核。 |
 | `PNL0001` | 20 | C-R 动态管路 | 第一版公开 | `amesim_pnl0001`，`flow` | 已按公开契约接入两状态管内容积 + port 1 摩擦残差 + mode 2 换热项；仍需后续按 AMESim baseline 复核 `pn2pipefr_` 和 mode 1 多方语义。 |
 | `PNL0002` | 8 | R-C-R 动态管路 | 第一版公开 | `amesim_pnl0002`，`flow` | 已按公开契约接入中心两状态容积 + 两端半长摩擦残差 + mode 2 换热项；仍需后续按 AMESim baseline 复核 `pn2pipefr_` 和 mode 1 多方语义。 |
 | `PNL0003` | 8 | C-R-C 动态管路 | 第一版公开 | `amesim_pnl0003`，`flow` | 已按公开契约接入两端四状态容积 + 中心摩擦流 + mode 2 换热项；大压差动态闭合和 AMESim baseline 误差仍留后续修模。 |
 | `PNPL01` | 16 | 零气动流源 | 第一版公开 | `amesim_pnpl01`，`boundary` | 当前实现一端零流边界，只约束端口质量流量为 0；压力源/外部边界语义留后续扩展。 |
-| `PNGD00` | 1 | 氦气气体定义 | 暂不公开 | medium 配置，不是画布物理组件 | 应映射为系统/介质设置；不能作为普通可连接组件注册。 |
-| `PNRP17` | 8 | 气动活塞与移动体耦合 | 暂不公开 | 内部固定算例；后续跨域组件 | 依赖气动端口和机械端口耦合；需要新增机械域、跨域状态和连接规则。 |
+| `PNGD00` | 1 | 氦气气体定义 | 氦气 Peng-Robinson 首版公开 | `amesim_helium_medium`，`media` | 已映射源模型 `fluidType=12/eosType=6`；密度和压力使用 PR EOS，热量学暂用手册参考点的定比热闭合。完整压力相关残余焓、比热和真实气体临界流仍待状态相关物性接口。 |
+| `PNRP17` | 8 | 气动活塞与移动体耦合 | 暂不公开 | 内部固定算例；后续跨域组件 | 需要跨域组件契约、实时气动-机械耦合，以及对应的事件、状态和闭合规则。 |
 | `MECMAS21` | 10 | 一维平动质量 | 第一版公开 | `amesim_mecmas21`，`mechanical` | 已接入一维机械端口 `x/v/f`、双端质量状态和基本摩擦/限位项，并跑通零力源与信号力源最小 System XML；完整 AMESim 接触/事件语义仍留后续对齐。 |
 | `LMECHN1` | 2 | 动态线性机械节点 | 第一版公开 | `amesim_lmechn1`，`mechanical` | 已接入 9 端一维机械节点、端口位移/速度等值和节点力平衡，并跑通 `FORC -> LMECHN1 -> MECMAS21` 最小 System XML；端口朝向/符号细节留后续 AMESim baseline 对齐。 |
 | `LSTP00A` | 8 | 弹性接触/端止动 | 第一版公开 | `amesim_lstp00a`，`mechanical` | 已接入两端一维机械端口、相对位移/速度接触力和最小 System XML 仿真；当前是连续罚函数基础版，完整 AMESim 事件/非光滑接触语义留后续 baseline 对齐。 |
 | `F000` | 16 | 零力源 | 第一版公开 | `amesim_f000`，`mechanical` | 已作为一端机械零力边界公开，约束端口力为 0。 |
 | `FORC` | 2 | 信号转力 | 第一版公开 | `amesim_forc`，`mechanical` | 已接入信号输入 `res` 到机械端口力源，可由 `STEP0/UD00` 驱动质量组件。 |
 | `STEP0` | 8 | 阶跃信号源 | 第一版公开 | `amesim_step0`，`signals` | 已接入标量信号输出端口和求解时信号传播；当前是基础阶跃，不含更复杂事件调度语义。 |
-| `UD00` | 2 | 分段线性信号源 | 第一版公开 | `amesim_ud00`，`signals` | 已接入标量信号输出端口、8 段 start/end/t 参数、循环模式和 System XML signal connection；当前按已转换 PythonModels 语义处理最后一段外推，AMESim baseline 仍留后续复核。 |
+| `UD00` | 2 | 分段线性信号源 | 第一版公开 | `amesim_ud00`，`signals` | 已接入标量信号输出端口、8 段 start/end/t 参数、循环模式和 System XML signal connection；当前按迁移实现语义处理最后一段外推，AMESim baseline 仍留后续复核。 |
 | `DIRECT` | 44 | 直接连接 | 不注册为组件 | System XML `Connection` | 连接不是组件；物理连接必须保持无方向端点语义。 |
 
 ## 建议迁移批次
 
-### 批次 1：可进入当前气动求解器的公开组件
+### 批次 1：已进入当前气动求解器的公开组件
 
-优先级最高，但仍需先补 AMESim 公式与测试：
+以下模型已完成第一版公开，后续重点是 AMESim 公式和 baseline 精修：
 
 - `amesim_pnor001`
 - `amesim_pnl00r`
@@ -64,7 +66,7 @@
 - `amesim_pn3node2`
 - `amesim_p4node2`
 
-完成定义：每个模型必须有 `MODEL_TYPE/MODEL_VERSION/PORTS/PARAMETERS/RESULT_VARIABLES/DISPLAY/create()`，并补目录、参数边界、残差、零流量/反向流、最小 XML 编译和短时仿真测试。
+这些模型已有 `MODEL_TYPE/MODEL_VERSION/PORTS/PARAMETERS/RESULT_VARIABLES/DISPLAY/create()` 契约和目录、XML、最小仿真测试；第一版状态不代表数值对齐完成。
 
 ### 批次 2：动态管路
 
@@ -86,7 +88,7 @@
 
 ## 下一步执行建议
 
-1. 先为 AMESim 公开组件建立独立库，例如 `app.simulation.components.amesim`，不要混入 `experimental`。
-2. 先只登记一个完成度最高的气动代数组件，例如 `PNOR001` 或 `PNL00R`。
-3. 每登记一个模型，都同步补充测试和目录校验，确认 `/api/components/catalog`、System XML 编译和最小仿真都通过。
-4. 动态管路 `PNL0001/2/3`、参数化 `PNCH012`、`STEP0`、`UD00`、信号版 `PNVO001` 和机械基础件 `F000/FORC/MECMAS21/LSTP00A/LMECHN1` 已完成第一版公开接入；下一步转向 `PNRP17` 或完整实时耦合。
+1. 以 `app.simulation.components.amesim.library` 的 21 个模型为公开清单唯一来源。
+2. 优先校准 `PNCH023 / PNOR001 / PN3NODE2 / P4NODE2 / PNL00R` 与动态管路的 AMESim baseline 误差。
+3. 每次调整模型都同步补充目录校验、参数边界、System XML 编译和最小仿真测试。
+4. 跨域能力下一步聚焦 `PNRP17` 或等价实时气动-机械耦合；在事件和闭合能力完成前保持暂不公开。

docs/amesim-helium-peng-robinson.md

@@ -0,0 +1,76 @@
+# AMESim 氦气 Peng-Robinson 介质模型
+
+## 本地资料依据
+
+仓库中已经包含该模型所需的说明和算例数据：
+
+- `AmesimModels/help/pneumatic_library_manual/03_gas_properties.pdf` 第 3.3 节
+  给出 AMESim Pneumatic Library 的气体物性层级和 Peng-Robinson 状态方程。
+- `AmesimModels/help/pneumatic_library_manual/lib_pneumatic.pdf` 第 87--88 页
+  给出 293.15 K、1 barA 下的氦气参考物性。
+- `AmesimModels/test_mql.ame` 中的 `PNGD00` 实例明确选择
+  `fluidType=12`（helium）和 `eosType=6`（Peng-Robinson）。
+- `app/simulation/core/peng_robinson.py` 已实现纯物质 Peng-Robinson 方程，
+  并定义了 `HELIUM_PR`。
+
+AMESim 手册中的 Peng-Robinson 形式为：
+
+```text
+p = r T / (v - b) - a alpha(T) / (v^2 + 2 b v - b^2)
+a = 0.457235583 r^2 Tc^2 / Pc
+b = 0.07779607 r Tc / Pc
+alpha(T) = [1 + m (1 - sqrt(T/Tc))]^2
+m = 0.37464 + 1.54226 omega - 0.26992 omega^2
+```
+
+当前 Python EOS 使用等价的摩尔体积形式，并通过最大物理解选择气相根。
+
+## 首版参数
+
+| 参数 | 数值 | 本地依据 |
+| --- | ---: | --- |
+| 摩尔质量 | `0.004002602 kg/mol` | `HELIUM_PR` |
+| 临界温度 | `5.1953 K` | `HELIUM_PR` |
+| 临界压力 | `227460 Pa` | `HELIUM_PR` |
+| 偏心因子 | `-0.385` | `HELIUM_PR` |
+| 定压比热 | `5193 J/(kg*K)` | AMESim 手册表 11.1 |
+| 定容比热 | `3116 J/(kg*K)` | AMESim 手册表 11.1 |
+| 比气体常数 | 由 `R/M` 计算，约 `2077.26 J/(kg*K)` | EOS + 手册表 11.1 |
+| 293.15 K 黏度 | `1.96e-5 Pa*s` | AMESim 手册表 11.2 |
+| Sutherland 常数 | `79.4 K` | 已迁移 `test_mql` 管路近似 |
+
+手册参考点还给出 `rho=0.164 kg/m3`、`gamma=1.667`、`Z=1.0005`。
+
+## 组件与索引映射
+
+公开介质组件使用：
+
+```text
+modelType       = amesim_helium_medium
+gi              = 画布自动分配的 1..99 引用索引
+property_model  = 0  (Peng-Robinson，本应用内的稳定编号)
+fluidType       = 12 (AMESim 元数据)
+eosType         = 6  (AMESim 元数据)
+```
+
+`property_model` 与 AMESim 的 `eosType` 有意分离：前者是单个介质组件内部的
+下拉选项编号，后者用于保留 AMESim 原模型语义。以后给氦气增加其他计算方法时，
+只需扩展氦气的物性模型注册表。
+
+源归档的 `gasName` 缓存文本与结构字段存在冲突，因此介质识别以
+`fluidType=12`、`PNGD_HELIUM` 和组件标签为准，不使用 `gasName` 猜测。
+
+## 首版计算边界
+
+首版公共组件实现以下闭合：
+
+- `rho(p,T)`、`p(rho,T)` 和控制容积压力使用 Peng-Robinson EOS；
+- `u=cv*T`、`h=cp*T`，温度反解使用同一组定比热；
+- 黏度使用以 293.15 K 为参考点的 Sutherland 近似；
+- `gi` 注册、气动连通域一致性、XML/JSON 保存均复用现有介质机制。
+
+这是一版可运行的“PR 压力--密度闭合 + 定比热热量学”，不是 AMESim 真实气体
+物性的完全复刻。AMESim 的 `Cp/Cv/h/mu/rho/Z` 接口均可随 `(p,T)` 变化，而当前
+`GasMedium` 的焓、内能和比热接口只有温度参数。后续若要接入完整残余焓、
+压力相关比热和真实气体临界流，应先扩展为状态相关物性接口，再调整气室、管路和
+孔口公式。

docs/component-library-spec-v1.md

@@ -550,6 +550,30 @@ GET /api/components/catalog
 6. 使用 `symbol` 选择图标渲染器。
 7. 不在前端重新定义参数默认值、边界或端口语义。
 
+目录协议提供以下可选的 AMESim 介质扩展字段：
+
+- 参数的 `editor: "amesimGasReference"` 表示该数值不是普通连续量，而是
+  项目介质定义的 `gi` 引用。前端应保留索引 `0`，并从当前画布的介质定义
+  组件生成其余下拉项；索引下拉项只显示数值，不拼接介质名称或中文说明。
+- 参数的 `editor: "amesimGasPropertyModel"` 表示该参数选择介质定义内部的
+  物性计算模型。参数同时提供 `options: [{"value": 0, "label": "理想气体"}]`
+  一类目录数据，前端据此生成下拉栏；后续增加算法时由介质模型注册新的选项，
+  前端不硬编码算法名称。
+- 模型的 `role: "amesimGasMediumDefinition"` 表示该模型是项目级介质定义。
+  此类模型允许 `ports: []`，在 System XML v2 中仍按普通零端口
+  `Component` 保存。
+
+这些字段在目录对象中均为可选。宽松读取目录的消费者可以把未知编辑器参数
+退化为普通数值输入；按本仓库 JSON Schema 严格校验的消费者必须与后端成套
+升级，才能识别新增的 `editor` 值和 `options` 字段。正式前端必须依据目录字段
+生成控件，不能硬编码具体 AMESim 模型名。
+
+`property_model` 是每种介质组件内部的稳定选项编号，不等同于 AMESim 原始
+`eosType`。例如空气组件的 `property_model=0` 表示理想气体，并映射到
+`fluidType=2/eosType=1`；氦气组件的 `property_model=0` 表示
+Peng-Robinson，并映射到 `fluidType=12/eosType=6`。编译层负责保存这种映射，
+前端只使用目录选项。
+
 当前前端保留内置兜底目录，用于后端未启动时继续打开工程。兜底只是一种开发期
 容错机制，不能成为新增模型的正式注册方式；正式环境应明确提示目录加载失败。
 
@@ -603,6 +627,12 @@ System XML 中：
 - `<Port name>`：必须存在于模型的 `PORTS`。
 - `<Parameter name>`：必须存在于模型的 `PARAMETERS`。
 
+介质定义组件不通过物理端口连接。编译器先收集目录角色为
+`amesimGasMediumDefinition` 的零端口组件，再解析带
+`editor="amesimGasReference"` 参数的组件引用；介质定义组件本身不进入数值
+仿真网络。System XML 语义校验会在编译前检查介质索引的整数范围、定义唯一
+性、正索引引用完整性，以及同一气动连通分量的引用一致性。
+
 XML 解析器只负责结构、引用和契约校验；模型注册中心负责选择 Python 类并创建实例；
 模型自身负责方程和状态。三层职责不得混合。
 

docs/system-xml-v2.md

@@ -5,6 +5,8 @@ System XML v2 是 ReactFlow 建模前端与 `app.simulation` 仿真层之间的
 ## 基本约定
 
 - 根元素 `System` 的 `schemaVersion` 固定为 `2`，`unitSystem` 固定为 `SI`。
+- 新导出的介质引用语义使用可选根属性
+  `mediumReferenceVersion="1"`。缺少该属性的文档按旧版介质索引规则读取。
 - 子元素顺序固定为 `Simulation`、`Components`、`Connections`。
 - `Component.id` 是稳定实例 ID，`name` 是用户可编辑名称。
 - 参数以 SI 基准值保存；显示单位不改变 XML 中的数值含义。
@@ -16,7 +18,7 @@ System XML v2 是 ReactFlow 建模前端与 `app.simulation` 仿真层之间的
 
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
-<System name="transfer-system" schemaVersion="2" unitSystem="SI">
+<System name="transfer-system" schemaVersion="2" unitSystem="SI" mediumReferenceVersion="1">
   <Simulation tStart="0" tStop="2" step="0.1" maxStep="0.005" method="BDF"/>
   <Components>
     <Component id="cylinder_1" name="cylinder_1" type="cylinder" componentType="cylinder" x="90" y="180" rotation="0" mirrored="false">
@@ -80,6 +82,71 @@ System XML v2 是 ReactFlow 建模前端与 `app.simulation` 仿真层之间的
 
 XSD 负责结构和基础枚举校验，端口注册、拓扑完整性与可求解性由模型校验层负责。
 
+### AMESim 介质定义与索引兼容
+
+AMESim 介质定义继续使用普通的零端口 `Component`，不增加新的 XML
+层级。其介质索引和物性选择仍以数值 `Parameter` 保存，例如：
+
+```xml
+<Component id="air_1" name="Air 1"
+           type="amesim_ideal_air_medium"
+           componentType="amesim_ideal_air_medium"
+           x="40" y="40">
+  <Parameter name="gi" value="1"/>
+  <Parameter name="property_model" value="0"/>
+</Component>
+```
+
+氦气 Peng-Robinson 定义使用相同结构：
+
+```xml
+<Component id="helium_1" name="Helium 1"
+           type="amesim_helium_medium"
+           componentType="amesim_helium_medium"
+           x="40" y="140">
+  <Parameter name="gi" value="2"/>
+  <Parameter name="property_model" value="0"/>
+</Component>
+```
+
+这里的 `property_model=0` 是氦气组件内部的 Peng-Robinson 选项编号；编译时
+同时保留源 AMESim `fluidType=12/eosType=6` 元数据，不能把两个编号体系混用。
+
+气动组件的 `gi=0` 表示内置的空气理想气体；正整数引用画布中的显式介质
+定义。介质定义的 `property_model` 是该介质内部的物性计算模型编号，当前
+空气定义中的 `0` 表示理想气体。界面中的 `gi` 下拉栏只显示索引数值，
+`property_model` 下拉栏的名称和可选值则来自组件目录。
+
+解析旧文档时，只有同时满足以下条件才执行旧 `gi` 兼容转换：
+
+- 根元素没有 `mediumReferenceVersion`；
+- 所有组件类型均可由当前注册表识别；
+- 画布中不存在目录角色为 `amesimGasMediumDefinition` 的组件。
+
+在这种可证明没有显式介质定义的旧文档中，缺失的 `gi` 会补为 `0`，旧
+`gi=1` 会映射为 `0`，并返回语义层警告。带有
+`mediumReferenceVersion="1"` 的新文档不会重解释正整数索引。
+
+在物性计算模型下拉接口加入之前保存的介质定义可能只有 `gi`。无论是否存在
+`mediumReferenceVersion`，解析器都会为缺失的 `property_model` 注入组件目录
+声明的默认值，并返回 `AMESIM_GAS_PROPERTY_MODEL_DEFAULTED` 警告；重新保存后
+该参数会显式写入 XML。
+
+完成兼容转换后，解析器统一按介质引用版本 1 执行以下语义校验：
+
+- 介质定义组件的 `gi` 必须是 `1..99` 的整数，且工程内不得重复。
+- 气动组件的介质引用必须是 `0..99` 的整数。
+- `gi=0` 始终引用内置空气理想气体；所有正索引必须存在对应介质定义。
+- 同一个气动连通分量内只能使用一个 `gi`，不同的独立气动网络可以选择不同
+  介质。
+
+相应错误码为 `AMESIM_GAS_MEDIUM_INDEX_INVALID`、
+`AMESIM_GAS_MEDIUM_INDEX_DUPLICATE`、
+`AMESIM_GAS_REFERENCE_INDEX_INVALID`、`AMESIM_GAS_REFERENCE_UNDEFINED` 和
+`AMESIM_GAS_REFERENCE_CONFLICT`。XML 解析得到的规范化工程 JSON 总是输出
+数值字段 `"mediumReferenceVersion": 1`；因此旧文档一经解析并重新保存，便
+不再依赖旧版启发式迁移。
+
 ## 仿真模型编译接口
 
 `POST /api/reactflow/compile-model` 接收与工程保存、XML 导出相同的 ReactFlow 工程 JSON。它会执行以下操作：