---
name: tjwater-skills
description: TJWater Skills — 仅保留可复用的分析工作流。原子操作由 Agent 自行通过 tjwater-cli help 发现。
version: 2.0.0
---

# TJWater Skills

## 设计原则

- **Skills 仅负责多步工作流**（数据获取 → 本地计算 → 报告输出）。
- **原子查询/分析**：Agent 直接调用 `tjwater_cli` 工具执行 CLI 命令，无需加载 skill。
- **命令发现**：Agent 可通过 `tjwater-cli help` 或 `tjwater-cli help COMMAND` 获取 JSON 格式的能力清单和参数说明。
- **认证与上下文**：由内部桥接自动注入，Agent 无需手动管理 `--auth-context`。

## 核心工具

| 工具 | 用途 |
|------|------|
| `tjwater_cli` | 执行任意 `tjwater-cli` 子命令。参数：`reason`、`command`、`timeout`(可选) |
| 前端工具 | `locate_features`、`show_chart`、`view_scada`、`view_history`、`render_junctions` 等 |

> `tjwater-cli` 输出统一 JSON (schema_version: `tjwater-cli/v1`)，`"ok": true` 表示成功。

## 命令发现策略

Agent 在需要了解可用命令时，优先运行：

```
tjwater-cli help                          → 一级命令清单
tjwater-cli help COMMAND                  → 子命令与参数详情
tjwater_cli(command="help")               → 通过工具调用
```

`help` 返回 JSON 格式，包含 `commands` 数组和 `summary`，Agent 可直接解析识别可用能力。

## 工作流清单

| 工作流 | 数据需求 | 输出 | 适用场景 |
|--------|---------|------|---------|
| **simulation-diagnosis** | 模拟结果 links/nodes | 问题概览 + 异常清单 + 严重级别 | 日常巡检、快速诊断 |
| **bottleneck-analysis** | 模拟结果 + 管道属性 | 瓶颈排名 + composite_score + 管径升级建议 | 规划改造 |
| **source-service-area-analysis** | 模拟结果 + 管道拓扑 + 水库列表 | 各水源服务节点数 + 分区渲染 | 供水分区可视化 |

## 使用策略

1. **工作流优先** — 用户意图匹配已有工作流时，直接加载对应 workflow skill。
2. **原子优先** — 简单查询/单项分析直接调用 `tjwater_cli`，不加载 skill。
3. **按需升级** — 浅层工作流不足时走升级路径（如 diagnosis → bottleneck）。
4. **应急拼装** — 无匹配工作流时，Agent 自行组合 CLI 命令 + Python 脚本完成。

## 参考

- 示例：`./examples.md`
- 运行手册：`./runbook.md`