# 命令与对话工作流

## 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` 作为诊断依据，但通常无需把完整事件日志逐行展示给用户。

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