refactor(cli)!: align commands with analysis run APIs

Replace legacy scheme commands with run-id based analysis and timeseries queries. Update sensor placement and SCADA routes, and refresh CLI help, tests, and usage guidance.

BREAKING CHANGE: legacy scheme, risk, and valve-close CLI command paths are removed.
This commit is contained in:
2026-08-26 17:28:41 +08:00
parent 4ec010455b
commit a438433068
6 changed files with 215 additions and 206 deletions
+17 -14
View File
@@ -35,15 +35,18 @@ description: tjwater-cli 命令行工具使用说明,涵盖命令发现、输
Agent 通过 `help` 动态发现可用命令,而非依赖硬编码清单。
**重要:命令分为类——触发动作数据获取。**
**重要:命令分为类——触发动作、运行/结果查询与时序数据获取。**
- **触发动作**`simulation``analysis`):向服务端发起计算请求,返回任务状态/ID,**不直接返回分析结果**
- **数据获取**`data timeseries`):所有计算结果(仿真压力、分析指标等)的唯一数据出口,需在触发动作完成后调用
- **触发动作**`simulation`各类 `analysis`):向服务端发起计算请求。
- **运行/结果查询**`analysis runs`):按 `run_id` 查询运行元数据和非时序结果
- **时序数据获取**`data timeseries`):实时结果或按 `run_id` 查询节点、管道时序。
```
simulation/analysis → 触发计算 → 返回状态/任务ID
data timeseries → 获取计算结果
analysis → 触发计算 → analysis runs list/get/results
run_id
data timeseries analysis → 获取元素时序
simulation → 触发实时模拟 → data timeseries realtime → 获取实时结果
```
通过 `help` 发现命令:
@@ -63,11 +66,11 @@ tjwater-cli help COMMAND → 子命令与参数详情
| 命令族 | 典型子命令 | 用途 |
|------|-----------|------|
| `project` | `list`, `db-health` | 项目管理、数据库健康检查 |
| `data` | `timeseries realtime links / nodes`, `timeseries scada query` | **时序数据查询**(实时/SCADA),所有分析结果的唯一获取渠道 |
| `network` | `get-pipe-properties`, `get-all-pipes-properties` | 管网元素查询 |
| `component` | `option get`, `option schema` | 模型选项和结构查询 |
| `data` | `timeseries realtime`, `timeseries analysis`, `timeseries scada`, `scada` | 实时、分析时序和 SCADA 查询 |
| `simulation` | 通过 `help simulation` 发现 | **触发水力仿真计算**(执行成功返回状态,实际结果需走 `data timeseries` 获取) |
| `analysis` | 通过 `help analysis` 发现 | **触发分析计算**(执行成功返回状态,实际结果需走 `data timeseries` 获取) |
| `net` | `list-pipes` | 管网拓扑查询 |
| `analysis` | `runs`, `sensor-placement` 及各类分析命令 | 触发分析,并按运行 ID 查询元数据与结果 |
| `help` | (无子命令) | 命令发现入口 |
> 完整命令清单始终以 `tjwater-cli help` 实时输出为准。
@@ -128,11 +131,11 @@ tjwater-cli help COMMAND → 子命令与参数详情
1. **禁止猜测命令** — 执行任何命令前必须先 `tjwater_cli(command="help ...")` 确认命令存在及参数签名,参数均已写在 help 中,禁止凭经验拼写
2. **reason 必填** — 每次调用必须说明具体理由
3. **触发后取数据**`simulation`/`analysis` 仅触发计算,结果必须从 `data timeseries` 获取,勿将触发返回的状态信息当作分析结果
3. **按运行 ID 取结果** — 分析完成后先用 `analysis runs list/get/results` 获取 `run_id` 和非时序结果;元素时序再用 `data timeseries analysis` 查询
4. **文件分析** — workflow 脚本需要文件时使用 `store_result=true`,不得从 Bash 直接联网调用 CLI
5. **结果验证** — 始终检查 `ok` 字段,失败时先处理错误码再重试
6. **大结果集** — 优先过滤/采样,不要一次性拉取全部数据
7. **模拟时长控制**模拟(`simulation`)或方案模拟`--duration` 不宜过长,建议每次仿真时间跨度控制在一小时以内,避免计算耗时过长或结果数据量过大
7. **模拟时长控制**实时模拟或分析运行`--duration` 不宜过长,建议每次仿真时间跨度控制在一小时以内,避免计算耗时过长或结果数据量过大
## 示例
@@ -145,11 +148,11 @@ tjwater-cli help COMMAND → 子命令与参数详情
```
> `data timeseries realtime nodes` 仅接受 `--start-time` / `--end-time`,返回全量节点数据。
### 按节点查询方案时序字段
### 按节点查询分析运行时序字段
```json
{
"reason": "查询节点 J-001 最近1小时的压力数据",
"command": "data timeseries scheme node-field --node J-001 --field pressure --start-time 2026-06-03T08:00:00+08:00 --end-time 2026-06-03T09:00:00+08:00"
"command": "data timeseries analysis node-field --run-id 00000000-0000-0000-0000-000000000001 --node J-001 --field pressure --start-time 2026-06-03T08:00:00+08:00 --end-time 2026-06-03T09:00:00+08:00"
}
```
+1 -1
View File
@@ -14,7 +14,7 @@ export default tool({
command: tool.schema
.string()
.describe(
"tjwater-cli 子命令,不含二进制路径。示例:'data scheme list'、'data timeseries realtime links --start-time 2025-01-01T00:00:00+08:00 --end-time 2025-01-01T01:00:00+08:00'",
"tjwater-cli 子命令,不含二进制路径。示例:'analysis runs list'、'data timeseries realtime links --start-time 2025-01-01T00:00:00+08:00 --end-time 2025-01-01T01:00:00+08:00'",
),
timeout: tool.schema
.number()