182 lines
7.5 KiB
Markdown
182 lines
7.5 KiB
Markdown
---
|
||
name: tjwater-cli
|
||
description: tjwater-cli 命令行工具使用说明，涵盖命令发现、输出格式、命令族、错误处理及最佳实践。
|
||
---
|
||
|
||
# tjwater-cli 使用说明
|
||
|
||
## 概述
|
||
|
||
`tjwater-cli` 是 TJWater 供水管网系统的命令行工具，用于与后端服务交互，支持数据查询、分析和工程操作。所有输出统一为 JSON 格式。
|
||
|
||
## 工具调用
|
||
|
||
通过 `tjwater_cli` 工具执行 CLI 命令：
|
||
|
||
```json
|
||
{
|
||
"command": "project list",
|
||
"timeout": 120,
|
||
"store_result": false
|
||
}
|
||
```
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `command` | string | 是 | CLI 子命令（不含二进制路径和 `--auth-context`） |
|
||
| `timeout` | number | 否 | 超时秒数，默认 120，大结果集建议 300+ |
|
||
| `store_result` | boolean | 否 | 强制保存到当前对话目录并返回 `data_file.file_path`；分析脚本需要文件输入时设为 true |
|
||
|
||
认证上下文（token、server、project、network）由内部桥接自动注入，无需手动传参。
|
||
|
||
## 命令发现
|
||
|
||
Agent 通过 `help` 动态发现可用命令，而非依赖硬编码清单。
|
||
|
||
**重要：命令分为三类——触发动作、运行/结果查询与时序数据获取。**
|
||
|
||
- **触发动作**（`simulation`、各类 `analysis`）：向服务端发起计算请求。
|
||
- **运行/结果查询**（`analysis runs`）：按 `run_id` 查询运行元数据和非时序结果。
|
||
- **时序数据获取**（`data timeseries`）：实时结果或按 `run_id` 查询节点、管道时序。
|
||
|
||
```
|
||
analysis → 触发计算 → analysis runs list/get/results
|
||
↓ run_id
|
||
data timeseries analysis → 获取元素时序
|
||
|
||
simulation → 触发实时模拟 → data timeseries realtime → 获取实时结果
|
||
```
|
||
|
||
通过 `help` 发现命令：
|
||
|
||
```
|
||
tjwater-cli help → 一级命令清单（含 commands 数组和 summary）
|
||
tjwater-cli help data timeseries → data timeseries 的子命令与参数详情
|
||
tjwater-cli help simulation → simulation 的子命令与参数详情
|
||
tjwater-cli help COMMAND → 子命令与参数详情
|
||
```
|
||
|
||
`help` 返回 JSON 格式，Agent 可直接解析 `commands` 数组识别可用能力。
|
||
|
||
**严禁猜测命令或参数！** 所有命令路径、子命令和参数（名称、类型、必填/可选）均以 `help` 输出为准。执行任何命令前，必须先通过 `help` 确认其存在及参数签名，禁止凭经验拼写。
|
||
|
||
### 已知命令族
|
||
|
||
| 命令族 | 典型子命令 | 用途 |
|
||
|------|-----------|------|
|
||
| `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` | `runs`, `sensor-placement` 及各类分析命令 | 触发分析，并按运行 ID 查询元数据与结果 |
|
||
| `help` | (无子命令) | 命令发现入口 |
|
||
|
||
> 完整命令清单始终以 `tjwater-cli help` 实时输出为准。
|
||
|
||
## 输出格式
|
||
|
||
所有命令返回统一 JSON 结构：
|
||
|
||
```json
|
||
{
|
||
"schema_version": "tjwater-cli/v1",
|
||
"ok": true,
|
||
"data": { ... },
|
||
"error": {
|
||
"code": "COMMAND_NOT_FOUND",
|
||
"message": "详细错误描述"
|
||
}
|
||
}
|
||
```
|
||
|
||
- `ok: true` — 成功，数据在 `data` 字段
|
||
- `ok: false` — 失败，检查 `error.code` 和 `error.message`
|
||
|
||
### 大结果集处理
|
||
|
||
超过内联阈值的结果不会终止 CLI，而是保存到当前对话的 `tool-data/` 目录并返回：
|
||
|
||
```json
|
||
{
|
||
"ok": true,
|
||
"data_file": {
|
||
"file_path": "/app/data/conversation-workspaces/conversation-.../tool-data/cli-....json",
|
||
"bytes": 38700000,
|
||
"content_type": "application/json"
|
||
}
|
||
}
|
||
```
|
||
|
||
禁止完整读取超大结果集。优先使用：
|
||
- 采样/截断参数（如 `--limit`、`--offset`）
|
||
- `--field` 按字段过滤
|
||
- `store_result=true` 后用沙箱 Python 脚本按字段读取
|
||
|
||
## 错误码速查
|
||
|
||
| error.code | 含义 | 来源 | 处理建议 |
|
||
|------|------|------|------|
|
||
| `UNAUTHENTICATED` | 缺少 access token | CLI `core.py:162` | 检查认证上下文注入 |
|
||
| `SERVER_ERROR` | 后端返回 error 状态 | CLI `core.py:400` | 记录 `request_id`，结合后端日志排查 |
|
||
| `REQUEST_TIMEOUT` | CLI 请求后端超时 | CLI `core.py:445` | 增大 `timeout` 参数或检查后端负载 |
|
||
| `TIMEOUT` | bridge 层进程超时 | Agent `server.ts:199` | 增大 `tjwater_cli` 的 `timeout` 参数 |
|
||
| `COMMAND_NOT_FOUND` | 命令/子命令不存在 | CLI `helping.py:300` | 执行 `help` 确认命令拼写 |
|
||
| `INPUT_NOT_FOUND` | `--input` 文件不存在 | CLI `core.py:243` | 检查文件路径 |
|
||
| `REQUEST_FAILED` | 网络连接失败 | CLI `core.py:453` | 检查服务端可达性 |
|
||
| `AUTH_CONTEXT_INVALID` | 认证上下文格式错误 | CLI `core.py:111` | 检查 auth headers 格式 |
|
||
|
||
## 最佳实践
|
||
|
||
1. **禁止猜测命令** — 执行任何命令前必须先 `tjwater_cli(command="help ...")` 确认命令存在及参数签名，参数均已写在 help 中，禁止凭经验拼写
|
||
2. **阶段分组** — 调用 CLI 前确认当前业务阶段已通过 `activity_update` 建立，同一阶段的多个查询无需重复说明理由
|
||
3. **按运行 ID 取结果** — 分析完成后先用 `analysis runs list/get/results` 获取 `run_id` 和非时序结果；元素时序再用 `data timeseries analysis` 查询
|
||
4. **文件分析** — workflow 脚本需要文件时使用 `store_result=true`，不得从 Bash 直接联网调用 CLI
|
||
5. **结果验证** — 始终检查 `ok` 字段，失败时先处理错误码再重试
|
||
6. **大结果集** — 优先过滤/采样，不要一次性拉取全部数据
|
||
7. **模拟时长控制** — 实时模拟或分析运行的 `--duration` 不宜过长，建议每次仿真时间跨度控制在一小时以内，避免计算耗时过长或结果数据量过大
|
||
|
||
## 示例
|
||
|
||
### 查询所有实时节点数据
|
||
```json
|
||
{
|
||
"command": "data timeseries realtime nodes --start-time 2026-06-03T08:00:00+08:00 --end-time 2026-06-03T09:00:00+08:00"
|
||
}
|
||
```
|
||
> `data timeseries realtime nodes` 仅接受 `--start-time` / `--end-time`，返回全量节点数据。
|
||
|
||
### 按节点查询分析运行时序字段
|
||
```json
|
||
{
|
||
"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"
|
||
}
|
||
```
|
||
|
||
### 查询 SCADA 时序数据
|
||
```json
|
||
{
|
||
"command": "data timeseries scada query --device-id 170490 --field monitored_value --start-time 2026-06-02T00:00:00+08:00 --end-time 2026-06-03T00:00:00+08:00"
|
||
}
|
||
```
|
||
|
||
### 触发仿真并获取结果
|
||
|
||
通常系统会自动跑仿真，建议**先尝试获取结果**，若无数据再触发仿真：
|
||
|
||
```json
|
||
// step 1: 先尝试获取仿真结果
|
||
{
|
||
"command": "data timeseries realtime simulation-by-id-time --id J-001 --type junction --time 2026-06-03T09:00:00+08:00"
|
||
}
|
||
// step 2: 若 step 1 无数据（ok: false 或 data 为空），触发仿真
|
||
{
|
||
"command": "simulation run --start-time 2026-06-03T08:00:00+08:00 --duration 60"
|
||
}
|
||
// step 3: 仿真完成后，再次获取结果（同 step 1）
|
||
{
|
||
"command": "data timeseries realtime simulation-by-id-time --id J-001 --type junction --time 2026-06-03T09:00:00+08:00"
|
||
}
|
||
```
|
||
|
||
`simulation run` 仅接受 `--start-time`（RFC3339，必填）和 `--duration`（整数分钟，必填）。
|