lujingze/SystemSimulationApp

0 Fork 0

Files

T

ljz 48da6be21c 新增基础版系统仿真 Skill

2026-09-03 16:15:44 +08:00

7.0 KiB

Raw Blame History

命令与对话工作流

CLI 合同

从仓库根目录调用：

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 中的状态。不要通过匹配本地化消息文本判断状态。

检查与解释

py -3.12 skills/system-simulation/scripts/simulation_skill.py inspect INPUT --format auto

--format 可为 auto、json 或 xml。完成后按 file-contracts.md 解释模型。错误和警告应保留层级、稳定错误码、路径或行号；不要只复述最后一句消息。

默认只返回首批 50 个紧凑组件、25 条连接和 20 个结果变量，避免大型工程输出撑满上下文。翻阅模型摘要、按组件查看完整合同或搜索结果变量时使用：

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 调用只返回差异预览、不会写文件：

py -3.12 skills/system-simulation/scripts/simulation_skill.py repair-format INPUT `
  --format auto `
  --output OUTPUT `
  --expected-sha256 SHA256

向用户展示预览中的目标路径、源/输出哈希和 confirmationToken，取得明确确认后，再用原样 token 执行写入：

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。写入后再次运行 inspect OUTPUT。

仿真前对话

运行前必须完成以下判断：

inspect 通过，并取得可用结果变量清单。
用户选择 separate、overlay 或 stacked。
把自然语言对象解析为稳定结果 key；重名、缺单位或把输入参数误称为曲线时先澄清。
向用户复述将运行的文件、仿真时段、算法、所选结果变量和曲线方式。

本版没有网页自动预装能力。用户要求“网页查看”时，说明当前只能直接交付 SVG 曲线与 CSV；不要启动浏览器、生成临时 URL，或声称现有页面会自动载入文件。

启动并监视仿真

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。

恢复查询：

py -3.12 skills/system-simulation/scripts/simulation_skill.py status SIMULATION_ID

用户要求取消时：

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 曲线。

交付时：

说明最终状态和实际计算到的仿真时间；
返回用户选择的 SVG 曲线；
无论用户只选了几条曲线，都同时返回完整 results.csv；
若失败或取消但存在部分序列，明确标注曲线和 CSV 是部分结果；
若没有产生可用时间序列，明确说明没有 CSV，不能创建空文件冒充结果；
保留 result.json 和 progress.jsonl 作为诊断依据，但通常无需把完整事件日志逐行展示给用户。

本版不会根据结果自动改变模型并重试。诊断后若要改参数、拓扑或算法，先把建议交给用户，等待后续迭代能力或单独授权的人工修改流程。

7.0 KiB Raw Blame History Unescape Escape