# 描述到工程与分层验收

## 建模清单

从描述提取系统目的、组件型号/实例 ID、真实端口拓扑、介质和边界条件、初始状态、参数值与单位、仿真配置、期望结果变量。关键型号或压力口径不明确时询问；布局可自行决定。不要要求用户先手写 JSON。

下文 PYTHON 代表入口说明中的 Python 3.12 命令。

```text
PYTHON skills/system-simulation/scripts/project_builder.py catalog --query 气室
PYTHON skills/system-simulation/scripts/project_builder.py catalog --model amesim_pnch023
```

默认返回分页摘要，--model 可重复并返回完整模型目录；--offset/--limit 翻页。目录来自本地 checkout，过滤网页隐藏的 experimental 库。与服务配合前核对 GET /api/components/catalog 中所用型号、版本、参数和端口是否一致；不能混用不同代码版本。

智能体将需求写为任务输出目录中的 plan.json（中间格式，不是平台工程）。完整接线的示例见 [closed-tank.plan.json](../assets/closed-tank.plan.json)，只代表一个封闭气罐：

```text
name: 工程名
simulation: { t_start, t_stop, step, max_step, method }
components[]:
  id, modelType
  parameters?: { 参数键: 数值或表达式字符串 }
  parameterUnits?: { 参数键: 单位 }
  label?, position?: {x,y}, rotation?, mirrored?
connections[]:
  id
  source: { component: 实例ID, port: 真实端口名 }
  target: { component: 实例ID, port: 真实端口名 }
```

参数用目录真实键名；省略项用目录 SI 默认值，报告 defaultsUsed 列出。设置 parameterUnits 时必须同时提供该参数值，防止将默认 SI 数值当所选单位。仿真五字段必须明确提供。布局省略时采用四列网格。

## 生成与本地检查

```text
PYTHON skills/system-simulation/scripts/project_builder.py build OUTPUT/plan.json --output OUTPUT/project.json
PYTHON skills/system-simulation/scripts/project_builder.py check OUTPUT/project.json --xml-output OUTPUT/project.xml
```

build 从目录构造节点及当前版本、精简端口快照、完整参数/单位，完成 check 相同的校验后才写文件。它不猜拓扑、不自动添加堵头/介质来掩盖缺失需求。未知字段/参数/单位/端口、重复 ID、未接或多接活动端口、语义错误都会失败；输出只写新路径。

check 支持 v1/v2，复用平台代码执行编辑器结构预检、单位/版本适配、XML v3 语义、活动端口连通和网络编译，不运行积分器。报告 browserImport:notRun、simulation:notRun 不能冒充通过。networkCompile 也不代表 C 编译成功。

修改已有工程时保留未涉及的 ID、布局、参数、拓扑与元数据，另存后 check；不要为使用 build 而将整个工程重建。旧版迁移优先网页导入再导出。

## 网页与运行验收

1. 按 [网页操作](browser-workflow.md) 导入文件，检查组件/连接、数值/单位、控制台诊断，记录实际导入结果。
2. 网页“生成系统 XML”或 check --xml-output 核对执行输入；服务目录与生成目录应一致。
3. 完整建模验收包含短时冒烟仿真；用户只要求文件时可交付文件及未运行说明。原时段很长时复制为独立 smoke.json，只在副本里设置明确记录的短终点，覆盖关心的事件并包含至少两个采样点。保留原工程，不能为跑通而改变参数、拓扑、容差或算法。
4. inspect smoke.json 获取结果键，再 simulate 或网页运行。检查终态、实际终点、有限结果与关键物理预期。短时通过不代表完整工况/精度通过。曲线方式未指定可选 separate 并告知，不必阻断验收。
5. 网页导出原工程为 roundtrip.json，比较规范化 SI 输入：

```text
PYTHON skills/system-simulation/scripts/project_builder.py compare OUTPUT/project.json OUTPUT/roundtrip.json
```

compare 重新检查两个文件，比较组件 ID/类型/当前版本/完整 SI 参数、连接 ID/端点及仿真配置，忽略布局、标签和连线两端书写顺序。它不比较仿真结果、不证明布局相同；布局另行目视核对。不要把 smoke 副本与原工程直接比较。

## 交付与边界

交付需求摘要、建模清单、工程 JSON、默认值清单与分层检查结果；不在工程顶层加验收字段。CLI 成功只证明报告中 passed 的层。网页或数值工具缺失时明确 notRun，保留已完成成果。

用户已授权范围内的生成/操作错误可直接纠正。需要改变物理需求、猜关键输入或新增模型时询问。相同错误在针对性修正后仍出现，应分析注册表/合同，不做无依据的参数搜索。