后端服务将通过tjwater-cli形式访问

.opencode/skills/SKILL.md

@@ -1,32 +1,53 @@
 ---
-name: tjwater-skills-root-index
-description: TJWater Skills 分层索引（Domain -> Scenario -> Action）。
-version: 1.2.0
+name: tjwater-skills
+description: TJWater Skills — 仅保留可复用的分析工作流。原子操作由 Agent 自行通过 tjwater-cli help 发现。
+version: 2.0.0
 ---
 
 # TJWater Skills
 
-## 简介
+## 设计原则
 
-按“领域 (Domain) -> 场景 (Scenario) -> 操作 (Action)”组织技能文档，逐层进入具体能力。
+- **Skills 仅负责多步工作流**（数据获取 → 本地计算 → 报告输出）。
+- **原子查询/分析**：Agent 直接调用 `tjwater_cli` 工具执行 CLI 命令，无需加载 skill。
+- **命令发现**：Agent 可通过 `tjwater-cli help` 或 `tjwater-cli help COMMAND` 获取 JSON 格式的能力清单和参数说明。
+- **认证与上下文**：由内部桥接自动注入，Agent 无需手动管理 `--auth-context`。
 
-## 子模块索引 (渐进式引导)
+## 核心工具
 
-- **analytics**: 见 `./analytics/SKILL.md`
-- **business**: 见 `./business/SKILL.md`
-- **data**: 见 `./data/SKILL.md`
-- **platform**: 见 `./platform/SKILL.md`
-- **workflow**: 见 `./workflow/SKILL.md`
+| 工具 | 用途 |
+|------|------|
+| `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` 表示成功。
 
-- 先按用户问题判断最可能的 Domain，再进入最小必要的 Scenario / Action。
-- 对分析、诊断、建议类问题，优先检查 `workflow/` 下是否已有固定工作流 skill；若存在，可先按 workflow 执行，再回补所需原子 skills。
-- 如果当前节点已经足以指导工具选择，不继续下钻到更多 skill。
-- 如果 workflow 已覆盖主要步骤，则不要先从大量 API skills 开始拼装流程；仅在 workflow 缺失、步骤不全或需要额外原子能力时，才继续下钻。
-- 优先更新已有 skill，而不是为一次性问题新增新的 skill 目录。
-- learned pattern 应写成可复用的方法或坑点，不应写成某次会话的流水账。
-- 某个 workflow 反复验证过的私有辅助脚本，应放在该 skill 目录下的 `scripts/*.py`，并随 skill 一起维护；不要写入 `data/`。
+## 命令发现策略
+
+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 脚本完成。
 
 ## 参考