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

name, description

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

tjwater-cli 使用说明

概述

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

工具调用

通过 tjwater_cli 工具执行 CLI 命令：

{
  "reason": "说明调用原因",
  "command": "project list",
  "timeout": 120
}

参数	类型	必填	说明
reason	string	是	调用原因
command	string	是	CLI 子命令（不含二进制路径和 --auth-context）
timeout	number	否	超时秒数，默认 120，大结果集建议 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 结构：

{
  "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. 大结果集 — 优先过滤/采样，不要一次性拉取全部数据
7. 模拟时长控制 — 模拟（simulation）或方案模拟的 --duration 不宜过长，建议每次仿真时间跨度控制在一小时以内，避免计算耗时过长或结果数据量过大

示例

查询所有实时节点数据

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

按节点查询方案时序字段

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

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

触发仿真并获取结果

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

// step 1: 先尝试获取仿真结果
{
  "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"
}
// step 2: 若 step 1 无数据（ok: false 或 data 为空），触发仿真
{
  "reason": "无已有仿真结果，触发1小时水力仿真",
  "command": "simulation run --start-time 2026-06-03T08:00:00+08:00 --duration 60"
}
// step 3: 仿真完成后，再次获取结果（同 step 1）
{
  "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"
}

simulation run 仅接受 --start-time（RFC3339，必填）和 --duration（整数分钟，必填）。