TJWaterAgent/.opencode/skills/SKILL.md

name, description

name	description
skills	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 调用

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

# 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