# 开发文档索引

本目录是 SystemSimulationApp 协议和开发规范的统一入口。

## 模型开发

1. [组件模型建模规范 v1](component-model-authoring-spec-v1.md)
   用于创建或修改模型，包括端口、参数、结果、方程、版本、测试和 AI 修改协议。
2. [组件库分类、发现与读取规范 v1](component-library-spec-v1.md)
   用于理解组件库清单、自动发现、启动校验、目录接口和前端读取流程。
3. [组件目录 JSON Schema v1](../schemas/component-catalog-v1.schema.json)
   `GET /api/components/catalog` 的机器可读结构。
4. [AMESim 子模型公开组件迁移矩阵](amesim-component-migration-matrix.md)
   用于划分 `test_mql` 子模型族的公开组件、内部模型和暂不支持范围。
5. [AMESim 氦气 Peng-Robinson 介质模型](amesim-helium-peng-robinson.md)
   记录本地 AMESim 资料、氦气参数、索引映射和首版计算边界。

建议人工和 AI 先阅读建模规范，再阅读读取规范，然后参考目标分类中最接近的现有
模型。不要从前端兜底数据反推后端物理契约。

## System XML

- [System XML v2 协议](system-xml-v2.md)
- [System XML v2 XSD](../schemas/system-simulation-v2.xsd)
- [System XML v1 协议（旧版）](system-xml-v1.md)
- [System XML v1 XSD（旧版）](../schemas/system-simulation-v1.xsd)

新增模型时，模型类和组件库清单是后端事实来源；System XML 保存组件实例、参数和
连接。XML 解析器不能自行创造模型端口或参数。

## 当前代码入口

| 目的 | 文件 |
| --- | --- |
| 组件基类 | [`app/simulation/core/base.py`](../app/simulation/core/base.py) |
| 端口契约 | [`app/simulation/core/ports.py`](../app/simulation/core/ports.py) |
| 参数与结果元数据 | [`app/simulation/core/metadata.py`](../app/simulation/core/metadata.py) |
| 库和显示声明 | [`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 使用原则

- 先读规范和相邻模型，再改代码。
- 只从 `library.py` 受控登记公开模型。
- 不在前端复制后端端口、参数或默认值作为正式来源。
- 不覆盖用户已有改动。
- 不自行猜测缺失的物理方程。
- 修改后运行针对性测试和完整回归，并报告未完成的验证。