更新v2版本适配skill
This commit is contained in:
ljz committed
1 parent
7611f13208
commit
2f3f7d00ec
58 files changed
+180419
-526
No files matched your search
@@ -0,0 +1,39 @@
|
||||
# 网页搭建、导入与验收
|
||||
|
||||
使用会话实际提供的浏览器工具，先读其操作文档；需要原生 Windows 交互时才使用已提供的 Computer Use 技能。不要假设原生桌面或某个浏览器工具必定可用。无界面工具仍可生成/检查文件，但网页验收标记未执行。
|
||||
|
||||
## 准备
|
||||
|
||||
- 按用户指定浏览器/标签页选择目标。开发前端通常为 127.0.0.1:5173，后端为 127.0.0.1:8000，以实际启动状态为准。
|
||||
- 观察当前工程、组件库状态和未保存修改。使用隔离浏览器上下文，或先导出当前工程备份再新建/导入；同源新标签页共享 localStorage，不等于隔离。
|
||||
- 以下控件名称来自当前代码，只作定位线索。操作以当下可访问树/截图为准，页面变化后重新观察，不能凭旧坐标点击。
|
||||
|
||||
## 文件导入
|
||||
|
||||
1. 用“导入工程 JSON”及工具支持的文件选择能力选中生成文件。不写 localStorage、React 内部状态或隐藏接口冒充 UI 导入。
|
||||
2. 检查工程名、画布和控制台；确认没有丢弃连线、未知组件、版本/参数错误。文件选择器关闭不代表成功。
|
||||
3. 按实例核对关键参数及单位。单位切换可能联动换算数值，以最终显示与导出 SI 值为准；多实例通过标签或稳定 ID 消歧。
|
||||
4. 点击“检查模型”，展开控制台看诊断，再“生成系统 XML”核对输入。需要运行时点击“运行仿真”并观察阶段和终态；可用后端状态辅助监视，但 API 成功不能代替 UI 步骤记录。
|
||||
5. 点击“导出工程 JSON”，取得实际下载文件后运行 project_builder.py compare。
|
||||
|
||||
## 界面模拟操作搭建
|
||||
|
||||
按建模清单操作，不把直接生成 JSON 描述成拖拽搭建：
|
||||
|
||||
1. 从组件库拖入目标型号，确认新增节点；必要时用“组件名称”设置易区分标签。
|
||||
2. 先配介质定义与引用、影响端口数量的参数，再确认活动端口。LMECHN1 先设 N，再连接 port_1..N 和 port_(N+1) 参考口。
|
||||
3. 参数表按真实标签填写，并设置对应单位；每次改变单位后复核最终数值。离散项用选项控件。参数隐藏时先核对控制条件，不盲输不存在的控件。
|
||||
4. 用观察到的端口完成拖拽/连接。当前端口可访问标签形如“组件标签 端口 port_1”；连线后检查端点实际存在，不能把交叉线或贴近布局当成连接。
|
||||
5. 调整布局和仿真配置，检查模型、导出、短时仿真及回读核对。
|
||||
|
||||
拖拽、缩放、滚动后重新观察。记录完成的组件和连接，失败后从实际状态恢复，避免重复添加。
|
||||
|
||||
## 验收
|
||||
|
||||
- 组件类型/ID/数量、连接端点与清单相符，无静默丢线。
|
||||
- 关键参数、SI 值、介质引用和边界条件符合描述；目录默认项已披露。
|
||||
- 网页检查无阻断错误，警告如实报告。
|
||||
- 要求仿真时取得真实终态和终点；“已开始”不是成功。
|
||||
- 实际下载 JSON 通过 check，compare 证明执行输入等价；布局另行确认。
|
||||
|
||||
此流程通过实际导入或界面操作完成，不承诺仅凭 URL 自动预装模型。若当前工具无法文件选择、下载或操作控件，交付文件并说明具体未验收步骤。
|
||||
@@ -1,95 +1,67 @@
|
||||
# 文件合同与解释规则
|
||||
# 文件合同与当前代码依据
|
||||
|
||||
## 支持范围
|
||||
## 格式与单位
|
||||
|
||||
本 Skill 只接受以下两种当前格式：
|
||||
| 格式 | 当前合同 |
|
||||
| --- | --- |
|
||||
| 工程 JSON v2 | 新建/导出的编辑工程；数值、十进制数字字符串、表达式全部按 parameterUnits[name] 解释，省略单位使用目录 SI 单位 |
|
||||
| 工程 JSON v1 | 兼容读取；普通数值/十进制数字字符串为 SI，表达式按显示单位解释 |
|
||||
| System XML v3 | 根元素 schemaVersion="3" unitSystem="SI"，只保存执行模型 |
|
||||
|
||||
| 格式 | 版本标志 | 用途 |
|
||||
| --- | --- | --- |
|
||||
| ReactFlow 工程 JSON | 顶层 `projectSchemaVersion: 1` | 保存组件、画布、端口显示快照、连线和仿真设置，适合继续编辑 |
|
||||
| System XML | 根元素 `System/@schemaVersion="3"` 且 `unitSystem="SI"` | 保存可执行模型，适合校验、编译和求解 |
|
||||
v2 的 p0: 2.5、"2.5"、"=2.5" 配 bar 都是 250000 Pa；20 degC 为 293.15 K。压力为绝压，不能自动加减大气压。缺失参数使用目录 SI 默认值，不随显示单位二次换算。
|
||||
|
||||
默认让 `inspect --format auto` 根据内容和扩展名识别格式。若内容与扩展名不一致、无法唯一识别或用户明确指定格式，则报告实际证据，不悄悄按另一种格式解释。
|
||||
v1→v2 由前端 encodeProjectParameters() 等现有转换逻辑完成，不得只改版本号。内部归一化的 v1/SI 对象不是 v2 导出文件。未知型号、参数、单位不能靠改版本掩盖。
|
||||
|
||||
System XML v1/v2、缺少 `projectSchemaVersion` 的旧工程、字符串端口和不匹配的组件 `modelVersion` 均不属于本 Skill 的迁移范围。不能只改版本号使其看似当前格式。
|
||||
|
||||
## 工程 JSON v1
|
||||
|
||||
顶层合同为：
|
||||
## 编辑工程字段
|
||||
|
||||
```text
|
||||
projectSchemaVersion = 1
|
||||
name
|
||||
nodes[]
|
||||
edges[]
|
||||
simulation { t_start, t_stop, step, max_step, method }
|
||||
projectSchemaVersion: 2
|
||||
name: string
|
||||
nodes[]:
|
||||
id: 唯一稳定 ID
|
||||
type: "simulationComponent"
|
||||
position: { x: 有限数值, y: 有限数值 }
|
||||
data:
|
||||
label, componentType, modelType, modelVersion
|
||||
ports[]: { name, kind, domain, nominalRole, side, positiveFlowDirection? }
|
||||
parameters: { 参数名: 数值或表达式字符串 }
|
||||
parameterUnits: { 参数名: 单位 }
|
||||
parameterScientificNotation: {}
|
||||
rotation: 0 | 90 | 180 | 270
|
||||
mirrored: boolean
|
||||
edges[]:
|
||||
id, source, target, sourceHandle, targetHandle
|
||||
data: { isContactEdge: boolean, routePoints?: [{x,y}] }
|
||||
simulation: { t_start, t_stop, step, max_step, method }
|
||||
```
|
||||
|
||||
重要规则：
|
||||
- 顶层禁止未知字段，假设与验收记录放独立报告。componentType/modelType 均用真实注册类型，显示标签不是模型标识。
|
||||
- Handle 用真实端口名，不按画面编号猜测。普通连线 isContactEdge=false，接触连线由网页几何决定。
|
||||
- 目录端口不能原样复制：信号端口 positiveFlowDirection:null 必须省略。生成器只复制必要快照字段；物理合同始终来自注册表。
|
||||
- LMECHN1 保存完整 21 个注册端口快照；v1=N 决定 N 个右端口和 port_(N+1) 左参考端口。连通性只统计注册模型 active_ports() 返回的活动端口。
|
||||
- 网页要求每个活动显示端口恰好连接一次，不能用后端对某些未接信号口的容忍替代网页检查，不能删快照端口绕过。
|
||||
- 介质节点属于工程但不一定进入动态求解。gi=0 为内置空气；1..99 引用唯一介质定义。多介质不能重复套用默认 gi=1。
|
||||
- 离散参数按目录 editor/options 数值编码，部分开关为 1/2，不能推定为 0/1。
|
||||
|
||||
- 节点的 `id` 是实例稳定标识；显示标签不能替代它。
|
||||
- `data.modelType` 标识注册模型，`data.modelVersion` 必须与当前组件目录精确匹配，执行前不得自动补成当前版本。
|
||||
- `data.parameters` 保存输入值；`parameterUnits`、科学计数法偏好、坐标、旋转和镜像属于编辑显示信息。
|
||||
- 连接必须保留两端组件及 Handle。不能根据节点位置猜测缺失端口。
|
||||
- `simulation.step` 是结果采样间隔；`max_step` 是求解器内部步长上限，两者不能混用。
|
||||
## 执行与结果
|
||||
|
||||
工程 JSON 可以导出为 System XML v3，但转换后不会保留全部画布显示信息的对等逆转换合同。
|
||||
step 是结果采样间隔，max_step 是内部最大步长。当前执行方法为 RK45/BDF；四个时间字段支持平台表达式。
|
||||
|
||||
## System XML v3
|
||||
JSON 适配层对不同/缺失组件版本警告并选择当前模型；类型、端口、未知参数和数值错误仍拒绝。LMECHN1/FORC 的显式兼容处理由平台完成，不能推广为任意迁移。新工程始终取当前版本。
|
||||
|
||||
XML v3 只描述“求解什么”：
|
||||
XML 的组件需要精确 modelVersion 和完整 SI 参数，连接为两个 Endpoint(component,port)。JSON 导出器补齐默认参数，XML 解析器本身不猜默认值。XML parse 返回执行模型，不能直接作为可无损恢复布局的工程。
|
||||
|
||||
- 每个 `Component` 必须有唯一 `id`、注册 `type`、精确 `modelVersion` 和完整 SI 参数；
|
||||
- 每条连接由两个 `Endpoint(component, port)` 组成；端口类型、方向和物理合同由后端注册表恢复；
|
||||
- `Simulation/@sampleStep` 对应工程 JSON 的 `simulation.step`；
|
||||
- 不保存组件位置、旋转、镜像、显示单位或端口显示快照；
|
||||
- 当前后端固定按 v3 校验，不会根据文件内容选择旧解析器。
|
||||
simulation_skill.py inspect 返回源哈希、版本、组件/连接/变量分页、诊断与未接端口；不是网页导入验收。默认页大小分别为 50/25/20，用 --component ID、--variable-query QUERY 和 offset/limit 定位。compiledForSimulation=false 的配置节点仍属于工程。
|
||||
|
||||
XML 校验依次覆盖安全/语法、XSD 和语义层。通过这些检查后，编译和求解仍可能发现未连接端口、缺少储能锚点、方程结构或数值问题。
|
||||
结果曲线按 key + componentId + quantity + unit 选择。separate 分图；overlay 仅叠加同单位且可比较的量；stacked 用于不同量。不能把固定参数当时间序列。
|
||||
|
||||
## 简要解释模型
|
||||
## 权威来源（相对仓库根目录）
|
||||
|
||||
解释必须依据 `inspect` 的结构化输出以及组件目录，而不是仅凭组件名称推测。优先说明：
|
||||
- app/main.py：ReactFlowProjectPayload、JSON→XML、编译及 HTTP 接口。
|
||||
- app/project_parameters.py、frontend/src/projectCompatibility.ts：版本、单位、表达式与兼容转换。
|
||||
- app/simulation/registry.py、GET /api/components/catalog：型号、参数、端口、版本。
|
||||
- frontend/src/App.tsx：parseProjectPayload、displayedPortsForNodeData、导入导出与网页检查。
|
||||
- schemas/parameter-units.json、schemas/system-simulation-v3.xsd。
|
||||
- docs/standard/backend-interface-version-spec-v1.md、component-library-spec-v1.md、port-computation-contract.md、system-xml-v3.md。
|
||||
|
||||
1. 文件格式、版本和项目名；
|
||||
2. 仿真起止时间、采样间隔、最大内部步长和算法；
|
||||
3. 组件数量、稳定 ID、模型类型和主要输入参数；
|
||||
4. 连接数量、连接端点及能够确定的物理域；
|
||||
5. 错误、警告，以及它们属于格式、语义、编译还是运行阶段。
|
||||
|
||||
保持“文件合同正确”和“物理模型合理”两个结论分开。没有组件文档或注册元数据支持时，不声称某个参数具有推测出的物理效果。
|
||||
|
||||
## 参数与结果变量
|
||||
|
||||
必须明确区分：
|
||||
|
||||
- **参数**：仿真开始前设定的固定输入，例如质量、初始压力、摩擦选项；通常没有时间序列。
|
||||
- **结果变量**：仿真返回的时间序列，例如位移、速度、压力或流量；只有这类量可以选作曲线。
|
||||
|
||||
选择曲线时以结果元数据为准，至少核对：
|
||||
|
||||
```text
|
||||
key + componentId + componentType + label/quantity + unit
|
||||
```
|
||||
|
||||
稳定 `key` 是传给 `simulate --variables` 的最终标识。用户只说“质量块的速度”而存在多个质量块，或一个组件存在多个符合描述的速度结果时，列出候选的组件 ID、结果名称和单位，请用户消歧。
|
||||
|
||||
`inspect` 默认对组件摘要、连接和结果变量分页。先读取 `componentTypes` 了解完整模型的组件类型分布，再根据 `componentPage`、`connectionPage` 或 `resultVariablePage` 的 `nextOffset` 翻页。优先使用 `--variable-query` 按组件 ID、标签、物理量或单位缩小范围；只有用户点名组件时才使用 `--component` 读取该组件的完整源数据和可用的编译合同。
|
||||
|
||||
组件摘要中的 `compiledForSimulation` 表示该节点是否进入动态求解网络。介质/物性配置节点仍属于工程，因此会保留在组件总数和列表中，但通常标记为 `false`；这不表示组件丢失或编译失败。
|
||||
|
||||
曲线模式约束：
|
||||
|
||||
- `separate`：每个所选结果变量分别成图；
|
||||
- `overlay`：只叠加单位相同且含义可比较的结果变量；
|
||||
- `stacked`：不同物理量或不同单位上下排列，避免共用一个纵轴造成误读。
|
||||
|
||||
本版运行 `simulate` 时必须指定至少一个 `--variables` 稳定键，避免在大型模型上无意生成成百上千张曲线。完整 CSV 仍包含全部可用结果变量。
|
||||
|
||||
## 权威来源
|
||||
|
||||
- 工程 JSON 请求合同：`app/main.py` 中的 `ReactFlowProjectPayload`
|
||||
- 组件目录：`GET /api/components/catalog`
|
||||
- XML v3：`schemas/system-simulation-v3.xsd`、`docs/standard/system-xml-v3.md`
|
||||
- 接口边界：`docs/standard/backend-interface-version-spec-v1.md`
|
||||
- 结果变量：组件注册合同中的 `RESULT_VARIABLES` 及仿真结果元数据
|
||||
文档文件名 v1 不是工程版本。代码变更与说明不一致时核对解析器、注册表与测试。
|
||||
@@ -0,0 +1,65 @@
|
||||
# 描述到工程与分层验收
|
||||
|
||||
## 建模清单
|
||||
|
||||
从描述提取系统目的、组件型号/实例 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，保留已完成成果。
|
||||
|
||||
用户已授权范围内的生成/操作错误可直接纠正。需要改变物理需求、猜关键输入或新增模型时询问。相同错误在针对性修正后仍出现，应分析注册表/合同，不做无依据的参数搜索。
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
## 目的
|
||||
|
||||
`repair-format` 只解决可解析 JSON v1 或 XML v3 的文本层问题，使文件采用稳定的 UTF-8 和跨平台文本格式。它不是模型迁移器，也不是语义修复器。
|
||||
`repair-format` 只解决可解析 JSON v1/v2 或 XML v3 的文本层问题，使文件采用稳定的 UTF-8 和跨平台文本格式。它不是模型迁移器，也不是语义修复器。以下限制只用于此命令；用户请求的拓扑/参数修改按 [建模流程](modeling.md) 处理。
|
||||
|
||||
## 允许的修改
|
||||
|
||||
@@ -17,7 +17,7 @@
|
||||
|
||||
## 禁止的修改
|
||||
|
||||
本版不得自动执行下列动作：
|
||||
`repair-format` 不得执行下列动作：
|
||||
|
||||
- 新增、删除、更换或重命名组件和连接；
|
||||
- 修改组件 ID、类型、端口、`modelVersion` 或 Schema 版本；
|
||||
|
||||
@@ -75,11 +75,11 @@ token 同时绑定源文件哈希、规范化输出哈希和目标绝对路径
|
||||
运行前必须完成以下判断：
|
||||
|
||||
1. `inspect` 通过，并取得可用结果变量清单。
|
||||
2. 用户选择 `separate`、`overlay` 或 `stacked`。
|
||||
2. 使用用户已选择的 `separate`、`overlay` 或 `stacked`；未指定展示方式时可采用 `separate` 并告知。仅当选择影响用户意图时询问。
|
||||
3. 把自然语言对象解析为稳定结果 `key`；重名、缺单位或把输入参数误称为曲线时先澄清。
|
||||
4. 向用户复述将运行的文件、仿真时段、算法、所选结果变量和曲线方式。
|
||||
|
||||
本版没有网页自动预装能力。用户要求“网页查看”时，说明当前只能直接交付 SVG 曲线与 CSV；不要启动浏览器、生成临时 URL，或声称现有页面会自动载入文件。
|
||||
用户要求网页查看或搭建时，按 [网页操作](browser-workflow.md) 通过实际导入/操作完成。没有浏览器工具则交付文件与曲线并明确网页步骤未执行；不声称仅凭 URL 可自动载入。
|
||||
|
||||
## 启动并监视仿真
|
||||
|
||||
@@ -139,4 +139,4 @@ py -3.12 skills/system-simulation/scripts/simulation_skill.py cancel SIMULATION_
|
||||
5. 若没有产生可用时间序列，明确说明没有 CSV，不能创建空文件冒充结果；
|
||||
6. 保留 `result.json` 和 `progress.jsonl` 作为诊断依据，但通常无需把完整事件日志逐行展示给用户。
|
||||
|
||||
本版不会根据结果自动改变模型并重试。诊断后若要改参数、拓扑或算法，先把建议交给用户，等待后续迭代能力或单独授权的人工修改流程。
|
||||
可在用户已授权的建模/配置范围内纠正生成与操作错误，重跑受影响检查。不能为了成功擅改物理拓扑、边界或算法；需要改变需求时说明并询问。短时验收使用独立副本，详见 [建模与验收](modeling.md)。
|
||||
Reference in new issue
Block a user