旧版前端工程文件导入时版本对比查验、审阅与仿真时部分阻挡功能实现；前端参数输入格式统一规范

docs/standard/component-model-authoring-spec-v1.md

@@ -1,6 +1,11 @@
 # 组件模型建模规范 v1
 
-状态：2026-09-10 更新为 Python 声明、C 数值实现
+文档版本：1.2.0
+修订日期：2026-09-12
+核对代码基线：`22579e5` 加本次输入合同实现；配套工程 JSON v2，XML v3 和模型版本不变。
+
+状态：Python 声明、C 数值实现；本版按实际注册与浏览器导入演练修订。
+总流程：[新组件注册流程](component-registration-workflow-v1.md)；示例：[注册示例与验证](component-registration-example-v1.md)。
 适用对象：人工开发者、代码生成工具和 AI 编程助手
 配套读取规范：[组件库分类、发现与读取规范 v1](component-library-spec-v1.md)
 端口供需规范：[气动端口变量供需合同](port-computation-contract.md)
@@ -22,7 +27,7 @@
 
 ### 2.1 新增公开模型
 
-公开模型会出现在前端组件库中，也能被 System XML 创建。必须：
+公开模型加入启用库后能被目录和 System XML 识别；前端当前隐藏 `experimental` 库，其余有效库可见。参与原生仿真还需第 12 节的完整数值接入。必须：
 
 - 放入某个组件库的分类目录。
 - 实现完整模型契约。
@@ -36,15 +41,15 @@
 | 改动 | 版本建议 | 兼容性要求 |
 | --- | --- | --- |
 | 修复数值实现但不改变契约 | 修订版本 | 若提高 `modelVersion`，既有 XML 会因精确版本不匹配而被拒绝；需明确是否真的变更合同 |
-| 新增有默认值的参数或结果 | 次版本 | 新 XML 必须写全当前参数；本阶段不提供旧文件自动迁移 |
+| 新增有默认值的参数或结果 | 次版本 | 新 XML 必须写全当前参数；无通用迁移，前端已有部分型号专用迁移 |
 | 修改界面名称或图标 | 库修订版本 | 不修改机器标识 |
 | 修改方程的物理语义 | 根据影响提高次版本或主版本 | 补充基准和变更说明 |
 | 删除、改名端口或参数 | 主版本 | 当前格式直接拒绝旧端口或参数；如以后需要兼容，再单独设计迁移器 |
-| 修改 `MODEL_TYPE` | 视为新模型 | 旧类型必须保留迁移映射 |
+| 修改 `MODEL_TYPE` | 视为新模型 | 明确保留旧实现、显式迁移或拒绝旧工程；没有自动生成的迁移映射 |
 
 ### 2.3 新增内部模型
 
-不进入前端目录的研究模型不加入 `library.py`。需要执行时仍应编写 C 内核并显式纳入编译器支持合同；不要恢复旧 Python 求解路径。
+研究类可以不加入生产清单。但当前原生入口要求精确的类及版本合同，不能只新增 C 函数和白名单就直接执行未发现的类。需要端到端演练时，在隔离源码副本中建立明确的测试库、原生发现入口与方程适配，见注册示例；或设计并验证专门的内部适配入口。不要恢复旧 Python 求解路径，也不要把演练类留在正式目录。
 
 ### 2.4 新增物理域
 
@@ -94,7 +99,7 @@ app/simulation/components/experimental/junctions/tee.py
 
 规则：
 
-- 一个公开模型原则上对应一个文件和一个主要模型类。
+- 推荐每个公开模型单独成文件；注册器不按文件名发现，现有同一文件包含多个相关型号的组织方式仍有效。
 - 模块名、`MODEL_TYPE`、端口名和参数名使用稳定机器标识。
 - `MODEL_TYPE` 使用小写 `snake_case`。
 - 参数和结果变量允许保留已有热力学惯例，如 `T0`、`T`、`U`。
@@ -136,6 +141,8 @@ def create(
 
 `AlgebraicComponent` 表示没有积分状态的元件；`DynamicComponent` 表示有积分状态的元件；`ThermodynamicVolumeComponent` 提供标准 `m,U,p,T,rho,u,h` 结果声明。这些基类只描述模型，不再实现数值求值方法。
 
+`state_size` 只描述 Python 对象，不能自动生成原生状态；状态索引、初值、导数和输出须在生成路径逐项实现。
+
 构造函数负责参数校验、几何预处理和端口注册。介质对象保存物性常量与模型选择。状态初值、流量、焓、受力和导数必须在 C 中计算。
 
 用 `EQUATIONS` 或 `equation_definitions()` 声明结构化连接约束，返回 `EquationDefinition`，包括关系、变量和归属，不包含运行时残差值。`__MODEL__` 占位符由基类替换为实例名。该声明供网络结构展示与检查使用，不替代 C 方程或构建支持白名单。
@@ -278,8 +285,7 @@ ParameterDefinition(
 | `volume_flow` | `m3/s` |
 | `windage` | `N/(m/s)^2` |
 
-新增物理量时必须先扩展后端受控单位表，再评估前端是否需要单位换算选项。禁止在
-单个模型中私自拼写新的同义 `quantity`。
+新增物理量时先扩展后端受控单位表，并核对共享参数单位表 `schemas/parameter-units.json`、结果页 `RESULT_UNIT_OPTIONS` 及三入口换算测试。目录的 `unit` 只给出基准单位，不会自动产生全部换算选项；例如当前 `time` 参数只显示 `s`，不能假设已支持 `ms`。新增编辑器需同时扩展元数据枚举、注册校验、目录解析和实际控件。禁止在单个模型中私自拼写新的同义 `quantity`。
 
 构造函数必须调用：
 
@@ -293,7 +299,7 @@ self.set_parameter_values(
 )
 ```
 
-保存值、方程计算和结果输出都使用 SI。前端显示单位变化不能改变后端参数语义。
+方程和结果输出使用 SI。外部工程 JSON v2 数值、数字字符串、表达式统一使用所选参数单位；网页、HTTP、CLI 在适配层归一化，内核仅接受有限 SI 数字。旧 v1 数值为 SI，导入保留含义后再转换导出 v2。单位源表为 `schemas/parameter-units.json`，详见[参数入口合同](backend-interface-version-spec-v1.md#61-工程存储与执行入口)。
 
 ## 9. 结果变量规范
 
@@ -312,7 +318,7 @@ ResultVariableDefinition(
 )
 ```
 
-声明的每个输出必须在 C 生成器的输出布局中有对应值。测试应核对实际 EXE 输出键与 `result_variable_metadata()` 一致，不再实现 Python `component_result_values()`。
+声明为可见的组件输出和活动端口可见输出必须在 C 生成器的输出布局中有对应值。测试应核对实际 EXE 输出键与 `result_variable_metadata()` 一致，不再实现 Python `component_result_values()`。
 
 ### 9.2 端口结果
 
@@ -351,10 +357,12 @@ DISPLAY = ComponentDisplaySpec(
 - `library_id` 必须等于所属库 ID。
 - `category_id` 必须存在于所属库的 `categories`。
 - `symbol` 是前端图形键，不是模型类型。
-- 未实现专用图标时使用新的稳定键，前端会回退到通用图形。
+- 可复用已存在的图形键；也可使用新的稳定键并暂时回退通用图形，不能据此声称已实现专用图标。
 - 只有确实需要专用工程图标时才修改前端图标渲染器。
 - `side` 只允许 `left` 或 `right`。
 - 旋转和镜像不能改变端口名或物理语义。
+- `role="amesimGasMediumDefinition"` 是介质识别元数据，XML/前端和网络的介质定义基类必须配套；不是只设图形角色就能实现新介质。
+- 动态端口不是通用目录能力；当前 LMECHN1 存在专用逻辑。新动态型号必须同步有效端口查询、前端布局、参数变更后旧连线处理及往返测试。
 
 ## 11. 标准创建入口
 
@@ -389,26 +397,30 @@ def create(
 3. 实际端口与 `PORTS` 完全一致。
 4. 实例保存的参数与规范化参数完全一致。
 
-`create()` 不应重复实现参数默认值和边界校验，也不能静默修改传入参数。
+`create()` 不另造一套默认值或偷偷修改传入参数。构造函数仍须调用 `set_parameter_values()`，并处理必要的跨字段约束；不能以注册器已检查为由删除直接构造所需的校验。XML 要求完整参数，不能把 Python 工厂的补默认行为当成 XML 的规则。
 
 ## 12. C 方程实现要求
 
-1. 在 `native/components/kernels.c` 及 `native/include/kernels.h` 实现物性或元件数值公式。
-2. 在 `native_codegen/extended.py` 注册状态、端口、参数、初始化与输出映射；符合简单拓扑的模型还应核对 `compiler.py` 快速路径。
-3. 在 `native_codegen/contracts.py` 声明支持版本，不允许仅注册 Python 模型就声称具备 C 求解能力。
-4. 当前状态与试探状态分离，求值不能覆盖已接受状态。无效物性、欠定连接和不收敛必须明确失败。
-5. 信号跳变和限位事件接入 C 运行库；不能改动刚度、阻尼或容差来隐藏数值错误。
-6. 保持 SI 单位和端口流入为正，核对逆流、质量/能量守恒及边界状态。
+1. 优先复用现有内核；新公式放入 `native/components/modules/` 合适模块，公共声明放入 `native/include/kernels.h`。增加函数或模块依赖时同步 `native_codegen/modules.py::EXPORTS/DEPENDENCIES`，防止生成代码已有调用但链接遗漏实现。
+2. `native/components/kernels.c` 是模块的诊断聚合入口，生产按需构建不直接编译它。新增模块核对聚合包含清单；不要同时链接聚合文件和各模块造成重复定义。
+3. 在 `native_codegen/extended.py` 接入端口、介质、状态、初始化、方程、导数、输出与事件。新型号默认走支持它的路径；只有将其纳入 `compiler.py` 紧凑路径时才同步实现该路径，不能只扩充类型集合。
+4. 新库还要加入 `extended.py::catalog_contracts()`；核对精确类及 `contracts.py::SUPPORTED_VERSIONS`。版本表代表已实现的能力，不能代替方程或 C 输出映射。
+5. 用 `Computation/EvaluationSchedule` 声明实际计算依赖，多输出函数区分读取参数与写出指针；别名和依赖流量的汇总拆开。新增循环需要对应的求解能力，不是图排序成功就一定能求解。
+6. 核对 `jacobian.py` 的表达式和状态依赖分析。新函数经审查后才纳入识别集合；分支、投影、多输出依赖必须完整。未知依赖允许保守逐列差分，禁止当常量处理来保留着色。动态模型适用时给生成的 `model`/`model.exe` 传 `--verify-jacobian` 对照；Python 包装 CLI 当前没有该参数。
+7. 核对 `tolerances.py` 的量纲尺度：当前 `m/m1/m2` 为 `1e-14`，`x/v` 为 `1e-12`，其他字段默认 `1e-8`。新状态按物理量评估，不能只依名称套用默认值。
+8. 当前状态与试探状态分离，无效物性、欠定连接和不收敛明确失败。气动物性复用传递 `NativePropertyCache` 上下文，不跨试算无条件复用旧值。信号跳变和限位接入运行库，不能改物理参数或放宽容差隐藏错误。
+9. 保持 SI、端口符号和适用的质量/能量守恒；按需编译及缓存由内容失效机制管理，测试完整模型命中、参数变化、模块变化及遗漏导出错误。
+10. C 代码、构建依赖、进程与文件操作遵守[跨平台交付约定](跨平台交付约定.md)。分别记录 Linux 与 Windows 实际结果，不把 Linux 模拟测试写成 Windows 验收。
 
 ## 13. 模型实现示例
 
-可参照 [气瓶声明](../../app/simulation/components/experimental/storage/cylinder.py)、[气腔声明](../../app/simulation/components/amesim/storage/chambers.py)、[C 内核](../../native/components/kernels.c) 与 [系统 C 生成器](../../app/simulation/native_codegen/extended.py)。完整开发顺序见 [组件目录说明](../../app/simulation/components/example.md)。
+可参照 [气瓶声明](../../app/simulation/components/experimental/storage/cylinder.py)、[气腔声明](../../app/simulation/components/amesim/storage/chambers.py)、[C 数值模块](../../native/components/modules/) 与 [系统 C 生成器](../../app/simulation/native_codegen/extended.py)。完整开发顺序见 [注册示例与验证](component-registration-example-v1.md)。
 
 Python `create()` 只创建经校验的描述对象；C `model_init()` 生成质量、能量及机械状态，`model_eval()` 计算导数和输出。两者通过生成的状态/参数布局关联。
 
 ## 14. 注册模型
 
-模型文件完成后，只修改所属库的 `library.py`：
+元数据发现这一步，在所属库的 `library.py` 加入类路径；它不替代第 12 节的原生接入：
 
 ```python
 models=(
@@ -434,10 +446,12 @@ models=(
 3. 参数边界测试。
 4. 端口与显示布局一致性测试。
 5. C 方程与独立解析解或冻结参考值对照。
-6. 零流量或反向流动测试。
+6. 按物理适用性覆盖零流量、反向流动或信号边界；无流量的信号源不套用气动守恒验收。
 7. 目录输出测试。
 8. 最小 XML 编译测试。
-9. 使用 C RK45/BDF 的短时仿真与事件测试。
+9. 使用当前支持的 C RK45/BDF 做短时仿真，事件按模型适用性验证；XSD 中出现其他方法不代表运行库已支持。
+10. 浏览器完整接线工程的导入、编辑、XML、运行、结果保存、CSV 和刷新恢复。后端单元件允许的未接端口警告，在前端可能是阻止运行的错误。
+11. 编译/缓存与实际 Windows/Linux 验证；依赖着色的动态模型另有雅可比对照。
 
 推荐先运行：
 
@@ -448,7 +462,7 @@ models=(
   tests.test_component_metadata
 ```
 
-然后运行完整回归：
+随后按改动范围运行型号数值、网络、原生构建与浏览器测试；涉及共享合同、内核或求解行为时运行完整回归：
 
 ```powershell
 .\.venv-win\Scripts\python.exe -m unittest discover -s tests
@@ -458,7 +472,7 @@ models=(
 
 ```powershell
 cd frontend
-$env:Path = 'F:\Master\SystemSimulationApp\.tools\node-v24.18.0-win-x64;' + $env:Path
+$env:Path = (Join-Path (Split-Path $PWD) '.tools\node-v24.18.0-win-x64') + ';' + $env:Path
 npm.cmd run build
 ```
 
@@ -471,7 +485,7 @@ npm.cmd run build
 5. 修改模型类，不在注册器和前端复制规则。
 6. 检查默认实例和旧参数是否仍能创建。
 7. 检查最小系统是否仍然闭合。
-8. 运行针对性测试和完整回归。
+8. 运行针对性测试，涉及共享机制时完成相应完整回归。
 9. 同步本文档或模型专属说明中的物理假设。
 
 ## 17. 人工或 AI 的任务输入卡
@@ -526,7 +540,7 @@ AI 创建或修改模型时必须遵守：
 
 1. 展示涉及的模型、清单和测试文件。
 2. 报告版本变化和兼容性影响。
-3. 运行针对性测试、完整后端测试和必要的前端构建。
+3. 运行针对性测试和必要的前端构建；共享机制修改运行相应完整后端回归。
 4. 检查 `GET /api/components/catalog` 中的模型、分类、端口和参数。
 5. 告知用户需要重启 FastAPI 才能加载新的 Python 模块。
 6. 未执行的校验必须明确说明原因。
@@ -551,11 +565,12 @@ AI 创建或修改模型时必须遵守：
 - 模型契约完整且启动校验通过。
 - 默认参数和边界有效。
 - 端口、参数和结果具有稳定物理含义。
-- 方程覆盖零流量、正常流动和必要的反向流动。
+- 方程覆盖正常、边界与适用的反向流动/事件，并有独立参考。
 - 模型已加入正确库清单。
 - 目录接口能自动输出模型。
 - 前端无需复制参数和端口定义即可使用。
 - XML 能映射到正确模型。
 - 最小系统能够编译；声称可仿真的模型必须产生有限结果。
-- 针对性测试、完整回归和必要的前端构建通过。
+- 相应分层测试及必要的构建/回归通过，浏览器能实际运行完整接线案例。
+- Windows/Linux 的验证状态明确，尚未实测的平台不能标记为通过。
 - 文档记录了模型假设、适用范围和已知限制。