47 lines
2.3 KiB
Markdown
47 lines
2.3 KiB
Markdown
# 开发文档索引
|
|
|
|
本目录是 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` 的机器可读结构。
|
|
|
|
建议人工和 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) |
|
|
| 元件完整示例 | [`app/simulation/components/example.md`](../app/simulation/components/example.md) |
|
|
|
|
## AI 使用原则
|
|
|
|
- 先读规范和相邻模型，再改代码。
|
|
- 只从 `library.py` 受控登记公开模型。
|
|
- 不在前端复制后端端口、参数或默认值作为正式来源。
|
|
- 不覆盖用户已有改动。
|
|
- 不自行猜测缺失的物理方程。
|
|
- 修改后运行针对性测试和完整回归，并报告未完成的验证。
|