---
name: skills
description: TJWater Skills — 动态生长的分析工作流树。后端服务由 Agent 自行通过 tjwater-cli help 发现。
---

# 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 可直接解析识别可用能力。

## 使用策略

Skills 树是动态生长的——没有预置的 workflow，所有工作流从实际任务中沉淀：

1. **查已有** — 先检查 `skills/workflow/` 下是否有匹配的 workflow skill
2. **从零拼装** — 无匹配时，Agent 自行组合 `tjwater_cli` 命令 + Python 脚本完成
3. **沉淀复用** — 任务完成后复盘，如果流程稳定可复用，用 `skill_manager` 保存到 `skills/workflow/<name>/`（含 SKILL.md + scripts/*.py）
4. **原子操作** — 简单查询直接调用 `tjwater_cli`，不走 skill

## Workflow 脚本编写规范

**原则：尽量用 pipe 串联 CLI 调用，减少 tool calling 次数。**

workflow skill 的 Python 脚本应在一次 `subprocess.run(shell=True)` 中用 shell pipe 串联多个 CLI 命令，而非多次 `subprocess.run` 逐次调用。中间数据转换由 `jq`/`xargs` 完成，CLI 不增加 `--input/--output`。

```
subprocess 次数：  1（pipe 串联） < N（逐次调用）
tool calling 次数： 1 次 skill call < N 次 tjwater_cli 调用
```

**环境变量认证**（管道场景，多用户安全）：

```python
# env dict 仅用于当前子进程，不污染 os.environ，多用户并发隔离
env = {**os.environ}
env["TJWATER_SERVER"] = auth["server"]
env["TJWATER_ACCESS_TOKEN"] = auth["access_token"]
env["TJWATER_PROJECT_ID"] = auth["project_id"]
env["TJWATER_NETWORK"] = auth.get("network", "")

cmd = "tjwater-cli cmd1 | jq '...' | xargs tjwater-cli cmd2"
result = subprocess.run(cmd, shell=True, env=env, capture_output=True, text=True)
```

单次 CLI 调用仍用 `--auth-stdin`（桥接端点场景）。管道场景用子进程 env dict，两个场景各司其职。认证 JSON 由内部桥接注入，脚本不硬编码 token/server/project。

## 参考

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