SystemSimulationApp/docs/README.md

开发文档索引

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

模型开发

1. 组件模型建模规范 v1 用于创建或修改模型，包括端口、参数、结果、方程、版本、测试和 AI 修改协议。
2. 组件库分类、发现与读取规范 v1 用于理解组件库清单、自动发现、启动校验、目录接口和前端读取流程。
3. 组件目录 JSON Schema v1 GET /api/components/catalog 的机器可读结构。

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

System XML

• System XML v2 协议
• System XML v2 XSD
• System XML v1 协议（旧版）
• System XML v1 XSD（旧版）

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

当前代码入口

目的	文件
组件基类	app/simulation/core/base.py
端口契约	app/simulation/core/ports.py
参数与结果元数据	app/simulation/core/metadata.py
库和显示声明	app/simulation/core/catalog.py
库发现与注册校验	app/simulation/registry.py
临时库清单	app/simulation/components/experimental/library.py
元件完整示例	app/simulation/components/example.md

AI 使用原则

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