@@ -0,0 +1,164 @@
---
name: tjwater-cli
description: tjwater-cli 命令行工具使用说明，涵盖命令发现、输出格式、命令族、错误处理及最佳实践。
---
# tjwater-cli 使用说明
## 概述
`tjwater-cli` 是 TJWater 供水管网系统的命令行工具，用于与后端服务交互，支持数据查询、分析和工程操作。所有输出统一为 JSON 格式。
## 工具调用
通过 `tjwater_cli` 工具执行 CLI 命令：
``` json
{
"reason" : "说明调用原因" ,
"command" : "project list" ,
"timeout" : 60
}
```
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `reason` | string | 是 | 调用原因 |
| `command` | string | 是 | CLI 子命令（不含二进制路径和 `--auth-context` ）
| `timeout` | number | 否 | 超时秒数，默认 60，大结果集建议 300+ |
认证上下文（token、server、project、network）由内部桥接自动注入，无需手动传参。
## 命令发现
Agent 通过 `help` 动态发现可用命令，而非依赖硬编码清单。
**重要：命令分为两类——触发动作与数据获取。 **
- **触发动作**（ `simulation` 、`analysis` ）：向服务端发起计算请求，返回任务状态/ID，**不直接返回分析结果**。
- **数据获取**（ `data timeseries` ）：所有计算结果（仿真压力、分析指标等）的唯一数据出口，需在触发动作完成后调用。
```
simulation/analysis → 触发计算 → 返回状态/任务ID
↓
data timeseries → 获取计算结果
```
通过 `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` 确认其存在及参数签名，禁止凭经验拼写。
### 已知命令族
| 命令族 | 典型子命令 | 用途 |
|------|-----------|------|
| `project` | `list` , `db-health` | 项目管理、数据库健康检查 |
| `data` | `timeseries realtime links / nodes` , `timeseries scada query` | **时序数据查询 ** （实时/SCADA），所有分析结果的唯一获取渠道 |
| `simulation` | 通过 `help simulation` 发现 | **触发水力仿真计算 ** （执行成功返回状态，实际结果需走 `data timeseries` 获取） |
| `analysis` | 通过 `help analysis` 发现 | **触发分析计算 ** （执行成功返回状态，实际结果需走 `data timeseries` 获取） |
| `net` | `list-pipes` | 管网拓扑查询 |
| `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`
### 大结果集处理
禁止完整读取超大结果集。优先使用：
- 采样/截断参数（如 `--limit` 、`--offset` ）
- `--field` 按字段过滤
- `jq` 管道提取关键字段
## 错误码速查
| 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. **reason 必填 ** — 每次调用必须说明具体理由
3. **触发后取数据 ** — `simulation` /`analysis` 仅触发计算，结果必须从 `data timeseries` 获取，勿将触发返回的状态信息当作分析结果
4. **管道串联 ** — workflow 脚本中用 shell pipe 串联多个 CLI 命令，减少 `subprocess.run` 次数
5. **结果验证 ** — 始终检查 `ok` 字段，失败时先处理错误码再重试
6. **大结果集 ** — 优先过滤/采样，不要一次性拉取全部数据
## 示例
### 查询所有实时节点数据
``` json
{
"reason" : "获取最近1小时内全部节点的实时数据" ,
"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
{
"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"
}
```
### 查询 SCADA 时序数据
``` json
{
"reason" : "查询 SCADA 设备 170490 在指定时间范围的 monitored_value" ,
"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"
}
```
### 触发仿真并获取结果
`simulation run` 仅接受 `--start-time` （ `--duration` （整数分钟，必填）。结果需从 `data timeseries` 获取：
``` json
// step 1: 触发仿真 (duration 为分钟数)
{
"reason" : "触发24小时水力仿真" ,
"command" : "simulation run --start-time 2026-06-03T08:00:00+08:00 --duration 1440"
}
// step 2: 按节点和时间获取仿真结果
{
"reason" : "获取仿真结果中节点 J-001 09:00 时刻的压力" ,
"command" : "data timeseries realtime simulation-by-id-time --id J-001 --type junction --time 2026-06-03T09:00:00+08:00"
}
```
