新增基础版系统仿真 Skill

skills/system-simulation/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: system-simulation
+description: 读取、校验并简要解释 SystemSimulationApp 工程 JSON v1 或 System XML v3，安全规范化文件文本，并在用户选定结果曲线后启动、监视或取消仿真及导出 CSV。适用于检查模型文件、修复编码或换行、运行仿真和获取结果；不用于旧格式迁移、任意语义修复、自动迭代或网页自动预装。
+---
+
+# 系统仿真
+
+使用本 Skill 随附的确定性脚本检查模型、调用现有后端并保存结果；不要让语言模型自行重写模型或猜测求解数据。
+
+## 基本边界
+
+- 仅处理 ReactFlow 工程 JSON v1 和 System XML v3。版本缺失、不受支持或模型版本不匹配时，说明问题并停止，不进行迁移猜测。
+- 组件参数是仿真前设定的固定输入；结果变量才是可随时间绘制的量。不要把“参数”当成结果曲线。
+- 文件通过格式校验不等于物理系统一定可求解。不要隐瞒编译或运行阶段的诊断。
+- 不直接覆盖源文件，不自行修改参数、连接、组件类型、模型版本或求解设置。
+- 本版不支持把模型自动注入网页、生成可直接打开的预装页面、任意损坏文件修复、模型迁移或自动调参迭代。明确告知用户这些能力尚未实现，不要用手工网页操作冒充支持。
+
+处理文件、解释格式或选择结果变量时，读取 [references/file-contracts.md](references/file-contracts.md)。请求文件修复时，再读取 [references/repair-policy.md](references/repair-policy.md)。需要运行、监视、取消仿真或交付结果时，读取 [references/workflows.md](references/workflows.md)。
+
+## 工作原则
+
+1. 先用 `inspect` 确认输入格式、版本、结构和诊断，再基于检查结果简要解释组件、连接与仿真设置。
+2. 如果用户要求修复，只能执行文本规范化。先展示预览和源文件 SHA-256，获得针对该预览的明确确认后，才可写入另一个输出路径；随后重新 `inspect`。
+3. 仿真前必须让用户选择直接曲线查看方式，并解析具体结果变量：
+   - 分别查看所选变量；
+   - 将多个同单位、可比较的变量叠加；
+   - 将不同物理量或单位的变量上下排列。
+4. 用户用显示名称描述组件或变量时，利用检查结果中的稳定 ID、结果 `key`、物理量和单位消歧。存在重名、多个候选或“参数/结果变量”含义不清时，先询问，不能替用户猜。
+5. 使用 `simulate` 的事件流持续判断 queued、validating、compiling、integrating 和结束状态。仿真时间暂时不变但内部活动仍增长时，只说明正在处理慢步，不能宣称卡死。
+6. 成功运行后交付用户选择的 SVG 曲线和完整 `results.csv`，并简要说明完成状态、实际仿真终点和重要诊断。失败或取消时交付能够安全生成的部分结果；若运行前即失败而没有 CSV，要明确说明原因。
+
+脚本命令统一从仓库根目录运行：
+
+```powershell
+py -3.12 skills/system-simulation/scripts/simulation_skill.py --help
+```
+
+Windows 优先使用仓库 `.venv-win\Scripts\python.exe`（若存在），否则使用 `py -3.12`；Linux 优先使用 `.venv/bin/python`，否则使用 `python3.12`。不要调用未经版本确认的 `python`，本项目要求 Python 3.12。
+
+优先依赖脚本返回的结构化 JSON/JSONL、稳定错误码和退出码做判断，不解析中文提示文本来驱动下一步。

skills/system-simulation/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "系统仿真文件助手"
+  short_description: "读取与校验模型文件，监视仿真并导出结果曲线和 CSV 文件"
+  default_prompt: "使用 $system-simulation 检查我的模型文件，并在我选定结果曲线后运行和监视仿真。"
+
+policy:
+  allow_implicit_invocation: true

skills/system-simulation/references/file-contracts.md

@@ -0,0 +1,95 @@
+# 文件合同与解释规则
+
+## 支持范围
+
+本 Skill 只接受以下两种当前格式：
+
+| 格式 | 版本标志 | 用途 |
+| --- | --- | --- |
+| ReactFlow 工程 JSON | 顶层 `projectSchemaVersion: 1` | 保存组件、画布、端口显示快照、连线和仿真设置，适合继续编辑 |
+| System XML | 根元素 `System/@schemaVersion="3"` 且 `unitSystem="SI"` | 保存可执行模型，适合校验、编译和求解 |
+
+默认让 `inspect --format auto` 根据内容和扩展名识别格式。若内容与扩展名不一致、无法唯一识别或用户明确指定格式，则报告实际证据，不悄悄按另一种格式解释。
+
+System XML v1/v2、缺少 `projectSchemaVersion` 的旧工程、字符串端口和不匹配的组件 `modelVersion` 均不属于本 Skill 的迁移范围。不能只改版本号使其看似当前格式。
+
+## 工程 JSON v1
+
+顶层合同为：
+
+```text
+projectSchemaVersion = 1
+name
+nodes[]
+edges[]
+simulation { t_start, t_stop, step, max_step, method }
+```
+
+重要规则：
+
+- 节点的 `id` 是实例稳定标识；显示标签不能替代它。
+- `data.modelType` 标识注册模型，`data.modelVersion` 必须与当前组件目录精确匹配，执行前不得自动补成当前版本。
+- `data.parameters` 保存输入值；`parameterUnits`、科学计数法偏好、坐标、旋转和镜像属于编辑显示信息。
+- 连接必须保留两端组件及 Handle。不能根据节点位置猜测缺失端口。
+- `simulation.step` 是结果采样间隔；`max_step` 是求解器内部步长上限，两者不能混用。
+
+工程 JSON 可以导出为 System XML v3，但转换后不会保留全部画布显示信息的对等逆转换合同。
+
+## System XML v3
+
+XML v3 只描述“求解什么”：
+
+- 每个 `Component` 必须有唯一 `id`、注册 `type`、精确 `modelVersion` 和完整 SI 参数；
+- 每条连接由两个 `Endpoint(component, port)` 组成；端口类型、方向和物理合同由后端注册表恢复；
+- `Simulation/@sampleStep` 对应工程 JSON 的 `simulation.step`；
+- 不保存组件位置、旋转、镜像、显示单位或端口显示快照；
+- 当前后端固定按 v3 校验，不会根据文件内容选择旧解析器。
+
+XML 校验依次覆盖安全/语法、XSD 和语义层。通过这些检查后，编译和求解仍可能发现未连接端口、缺少储能锚点、方程结构或数值问题。
+
+## 简要解释模型
+
+解释必须依据 `inspect` 的结构化输出以及组件目录，而不是仅凭组件名称推测。优先说明：
+
+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` 及仿真结果元数据

skills/system-simulation/references/repair-policy.md

@@ -0,0 +1,48 @@
+# 安全文本规范化策略
+
+## 目的
+
+`repair-format` 只解决可解析 JSON v1 或 XML v3 的文本层问题，使文件采用稳定的 UTF-8 和跨平台文本格式。它不是模型迁移器，也不是语义修复器。
+
+## 允许的修改
+
+仅允许脚本已经证明不会改变解析后数据合同的规范化，例如：
+
+- 将可安全解码的输入统一写为 UTF-8；
+- 统一 BOM 和换行表现；
+- 规范化文件末尾换行；
+- 对可解析内容采用脚本规定的稳定文本序列化形式。
+
+以脚本返回的预览、变更摘要和哈希为准；不要在脚本外另写正则替换或自制格式化器。若文件连语法都无法可靠解析，停止并报告诊断，不能尝试猜测闭合括号、XML 标签或截断内容。
+
+## 禁止的修改
+
+本版不得自动执行下列动作：
+
+- 新增、删除、更换或重命名组件和连接；
+- 修改组件 ID、类型、端口、`modelVersion` 或 Schema 版本；
+- 填猜缺失参数、改变数值、单位、离散选项或介质引用；
+- 修改仿真起止时间、采样间隔、最大步长或求解算法；
+- 把 XML v1/v2 或旧工程升级到当前版本；
+- 根据报错放宽容差、删除失败组件或改变物理拓扑；
+- 覆盖源文件，即使用户给出的输出路径通过大小写、相对路径或符号链接指向源文件也不行。
+
+发现上述问题时，可以解释和给出人工处理建议，但不能借“修复格式”的名义实施。
+
+## 强制确认流程
+
+1. 对源文件运行 `inspect`，记录格式、诊断和 SHA-256。
+2. 生成或读取 `repair-format` 的规范化预览，向用户说明只会改变哪些文本表现，并展示目标输出路径。
+3. 等待用户针对该预览明确确认。笼统的“帮我看看”或先前对其他版本的确认不能复用。
+4. 使用同一个源文件 SHA-256、预览返回的 `confirmationToken`、`--confirmed` 和预览中相同的 `--output` 路径执行写入。token 绑定源哈希、规范化输出哈希和目标绝对路径。
+5. 如果哈希、规范化结果或目标路径已变化，停止并重新预览；不能绕过 `--expected-sha256` 或确认 token。
+6. 对输出文件重新运行 `inspect`。只有重新校验通过且解析后的模型语义未改变时，才能报告完成。
+
+示例命令形状见 [workflows.md](workflows.md)。
+
+## 输出与交付
+
+- 输出名称建议为原名加 `.normalized`，例如 `plant.normalized.json` 或 `plant.normalized.xml`。
+- 保留源文件；清楚列出新文件、源 SHA-256、输出 SHA-256 和重新校验结果。
+- 如果没有文本差异，说明文件无需规范化，不制造副本冒充修复结果。
+- 如果写入失败或输出校验失败，不能把不完整文件当作成功结果交付。

skills/system-simulation/references/workflows.md

@@ -0,0 +1,142 @@
+# 命令与对话工作流
+
+## CLI 合同
+
+从仓库根目录调用：
+
+```powershell
+py -3.12 skills/system-simulation/scripts/simulation_skill.py [--base-url URL] [--timeout SECONDS] COMMAND
+```
+
+若仓库已有 `.venv-win\Scripts\python.exe`，Windows 应优先用它替换 `py -3.12`；Linux 使用 `.venv/bin/python` 或 `python3.12`。不要使用本机可能指向旧版本的裸 `python`。默认服务地址为 `http://127.0.0.1:8000`，超时参数不得低于 10 秒，以保持在后端 5 秒心跳间隔之上。`inspect`、`repair-format`、`status` 和 `cancel` 在标准输出返回一个结构化 JSON；`simulate` 在标准输出给出节流后的 JSONL 进展和精简完成摘要。输出目录的 `progress.jsonl` 保留完整进展/错误事件，但只保存精简结果摘要；完整数值结果另存为 `result.json`，避免时间序列重复占用空间和智能体上下文。
+
+退出码：
+
+| 退出码 | 含义 |
+| --- | --- |
+| `0` | 命令按合同成功完成 |
+| `2` | 输入、参数或安全前置条件错误 |
+| `3` | HTTP、连接或后端结构化错误 |
+| `4` | 仿真事件流报告失败 |
+| `5` | 本地结果文件写入失败 |
+
+不要只看退出码 `0` 就声称仿真数值成功；还要检查最终事件和 `result.json` 中的状态。不要通过匹配本地化消息文本判断状态。
+
+## 检查与解释
+
+```powershell
+py -3.12 skills/system-simulation/scripts/simulation_skill.py inspect INPUT --format auto
+```
+
+`--format` 可为 `auto`、`json` 或 `xml`。完成后按 [file-contracts.md](file-contracts.md) 解释模型。错误和警告应保留层级、稳定错误码、路径或行号；不要只复述最后一句消息。
+
+默认只返回首批 50 个紧凑组件、25 条连接和 20 个结果变量，避免大型工程输出撑满上下文。翻阅模型摘要、按组件查看完整合同或搜索结果变量时使用：
+
+```powershell
+py -3.12 skills/system-simulation/scripts/simulation_skill.py inspect INPUT `
+  --component COMPONENT_ID `
+  --component-offset 0 `
+  --component-limit 50 `
+  --connection-offset 0 `
+  --connection-limit 25 `
+  --variable-query QUERY `
+  --variable-offset 0 `
+  --variable-limit 20
+```
+
+分别依据 `componentPage`、`connectionPage` 和 `resultVariablePage` 的 `hasMore`、`nextOffset` 继续分页，不要为寻找一个组件或变量请求全部详细合同。`componentTypes` 始终汇总完整模型，可先用它判断系统构成。`--component` 返回该 ID 的源文件数据和（若参与求解）编译合同，因此物性介质等配置节点也能查看参数。
+
+## 文本规范化修复
+
+先检查并取得源文件 SHA-256。第一次不带 `--confirmed` 调用只返回差异预览、不会写文件：
+
+```powershell
+py -3.12 skills/system-simulation/scripts/simulation_skill.py repair-format INPUT `
+  --format auto `
+  --output OUTPUT `
+  --expected-sha256 SHA256
+```
+
+向用户展示预览中的目标路径、源/输出哈希和 `confirmationToken`，取得明确确认后，再用原样 token 执行写入：
+
+```powershell
+py -3.12 skills/system-simulation/scripts/simulation_skill.py repair-format INPUT `
+  --format auto `
+  --output OUTPUT `
+  --expected-sha256 SHA256 `
+  --confirmation-token PREVIEW_TOKEN `
+  --confirmed
+```
+
+token 同时绑定源文件哈希、规范化输出哈希和目标绝对路径；任何一项变化都必须重新预览和确认。脚本拒绝覆盖源文件、哈希/token 不匹配和未确认写入。完整边界见 [repair-policy.md](repair-policy.md)。写入后再次运行 `inspect OUTPUT`。
+
+## 仿真前对话
+
+运行前必须完成以下判断：
+
+1. `inspect` 通过，并取得可用结果变量清单。
+2. 用户选择 `separate`、`overlay` 或 `stacked`。
+3. 把自然语言对象解析为稳定结果 `key`；重名、缺单位或把输入参数误称为曲线时先澄清。
+4. 向用户复述将运行的文件、仿真时段、算法、所选结果变量和曲线方式。
+
+本版没有网页自动预装能力。用户要求“网页查看”时，说明当前只能直接交付 SVG 曲线与 CSV；不要启动浏览器、生成临时 URL，或声称现有页面会自动载入文件。
+
+## 启动并监视仿真
+
+```powershell
+py -3.12 skills/system-simulation/scripts/simulation_skill.py simulate INPUT `
+  --format auto `
+  --output-dir OUTPUT_DIR `
+  --variables RESULT_KEY_1 RESULT_KEY_2 `
+  --chart-mode overlay `
+  --simulation-id SIMULATION_ID
+```
+
+`--variables` 接受结果变量稳定 `key`；不能传组件参数名。`--simulation-id` 可省略并由脚本生成，但应保存最终 ID，供恢复查询或取消使用。
+
+监视规则：
+
+- 消费 JSONL，记录最新 `progress`、`phase`、`simulatedTime/totalTime`、心跳和内部活动快照；
+- 长任务期间定期向用户给出简短进展，避免逐条转发事件；
+- 仅有仿真时间平台期不能证明卡死。活动序号、RHS、solver step、Jacobian 或闭合计数仍增长时，应报告“正在处理慢步”；
+- 网络读取中断后，用已知 simulation ID 查询一次任务快照，再决定是否继续说明、恢复结果或报告连接问题；
+- 不因运行缓慢自动取消。只有用户明确要求取消，或既有系统已经把任务判定为 stalled 时，才使用对应取消原因；
+- `completed` 才表示完整完成；`stopped`、`stalled`、`failed` 都必须标明是非完整结果。
+
+当前任务状态保存在后端进程内，终态记录只短期保留，服务重启后也不能恢复。本 Skill 不承诺跨进程或长期断线续传；需要查询时应及时保存 simulation ID、事件日志和已经写出的结果文件。
+
+`status` 对已完成任务只输出结果摘要，不在终端重复打印整套时间序列；正常 `simulate` 流程会把完整数据保存为 `result.json` 和 `results.csv`。
+
+恢复查询：
+
+```powershell
+py -3.12 skills/system-simulation/scripts/simulation_skill.py status SIMULATION_ID
+```
+
+用户要求取消时：
+
+```powershell
+py -3.12 skills/system-simulation/scripts/simulation_skill.py cancel SIMULATION_ID --reason user
+```
+
+`--reason stalled` 只用于已有充分停滞证据的内部流程，不用来表达普通的用户取消。
+
+## 结果文件与交付
+
+正常运行目录应包含：
+
+- `progress.jsonl`：原始进度、心跳和结束事件；
+- `result.json`：最终结构化结果；
+- `results.csv`：全部可用结果变量的 UTF-8 CSV；
+- 根据 `separate`、`overlay` 或 `stacked` 生成的 SVG 曲线。
+
+交付时：
+
+1. 说明最终状态和实际计算到的仿真时间；
+2. 返回用户选择的 SVG 曲线；
+3. 无论用户只选了几条曲线，都同时返回完整 `results.csv`；
+4. 若失败或取消但存在部分序列，明确标注曲线和 CSV 是部分结果；
+5. 若没有产生可用时间序列，明确说明没有 CSV，不能创建空文件冒充结果；
+6. 保留 `result.json` 和 `progress.jsonl` 作为诊断依据，但通常无需把完整事件日志逐行展示给用户。
+
+本版不会根据结果自动改变模型并重试。诊断后若要改参数、拓扑或算法，先把建议交给用户，等待后续迭代能力或单独授权的人工修改流程。