76 lines
3.2 KiB
Markdown
76 lines
3.2 KiB
Markdown
---
|
||
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`
|