TJWaterAgent/.opencode/skills/tjwater-cli/SKILL.md

name, description

name	description
tjwater-cli	tjwater-cli 命令行工具使用说明，涵盖命令发现、输出格式、命令族、错误处理及最佳实践。

tjwater-cli 使用说明

概述

tjwater-cli 是 TJWater 供水管网系统的命令行工具，用于与后端服务交互，支持数据查询、分析和工程操作。所有输出统一为 JSON 格式。

工具调用

通过 tjwater_cli 工具执行 CLI 命令：

{
  "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 结构：

{
  "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/ 目录并返回：

{
  "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 不宜过长，建议每次仿真时间跨度控制在一小时以内，避免计算耗时过长或结果数据量过大

示例

查询所有实时节点数据

{
  "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，返回全量节点数据。

按节点查询分析运行时序字段

{
  "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 时序数据

{
  "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"
}

触发仿真并获取结果

通常系统会自动跑仿真，建议先尝试获取结果，若无数据再触发仿真：

// 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（整数分钟，必填）。