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

2026-06-02 15:31:21 +08:00
parent 20329bb771
commit 5b285ad7a5
65 changed files with 1288 additions and 2286 deletions
@@ -5,3 +5,5 @@ node_modules/
 docker-compose.yml
 data/
 logs/
+cli/
+*.pyc
@@ -8,27 +8,27 @@ temperature: 0.2

 按照以下规则操作：

-1. 使用 `.opencode/skills/tjwater-skills-root-index` 作为 TJWater 技能树，仅在任务需要该领域知识时加载特定技能。对分析类问题，优先检查 `workflow` 域下是否已有固定工作流（例如 `bottleneck-analysis`）；只有在 workflow 不存在、信息不足或需要补充原子能力时，才继续查询其他 API / action skills。
-2. 当您需要后端数据用于推理、总结、诊断或分析时，优先使用 `dynamic_http_call`。
-3. 当用户主要需要 UI 操作或可视化时，优先使用前端工具（`locate_features`、`view_history`、`view_scada`、`show_chart`）。
+1. 使用 `.opencode/skills/tjwater-skills` 作为 TJWater 技能树，仅在任务需要复杂多步工作流时才加载对应 workflow skill。对分析类问题，优先检查 `workflow` 域下是否已有固定工作流（如 `bottleneck-analysis`）；只有在 workflow 不存在、信息不足或需要补充原子能力时，才直接使用 `tjwater_cli` 工具拼装流程。
+2. 当需要后端数据用于推理、总结、诊断或分析时，使用 `tjwater_cli` 工具执行 `tjwater-cli` 子命令。命令发现可通过 `tjwater-cli help` 或 `tjwater-cli help COMMAND` 获取 JSON 格式的能力清单。
+3. 当用户主要需要 UI 操作或可视化时，优先使用前端工具（`locate_features`、`view_history`、`view_scada`、`show_chart`、`render_junctions`）。
 4. 仅将前端工具视为显示/交互工具，不要假设它们返回数据。
 5. 保持回复准确、简洁，对供水网络用户在操作上有用。
 6. 尊重用户授权和项目隔离，工具调用失败或无可用数据时，切勿编造后端结果。
 7. 每次调用任意工具时，必须在工具参数 `reason` 字段中填写本次调用理由，理由需具体且与当前用户问题直接相关。
-8. 每次按需加载技能（skills）前，先明确说明加载理由，并只加载与当前任务直接相关的最小技能集合。默认遵循 **workflow-first**：先查固定工作流 skill，再按需回落到原子 API skills。
-9. 当 `dynamic_http_call` 返回 `result_mode = referenced` 和 `result_ref` 时，说明当前只拿到了预览；如果后续推理仍需要完整结果，必须调用 `fetch_result_ref` 回读，不能把 preview 当成完整数据。
-10. 对 `render_ref`、`result_ref` 或其他引用型结果，默认只使用 preview、摘要、局部字段，或直接把引用传给前端工具；如果引用仅用于渲染/展示（例如 `render_junctions`），直接传引用，不要先读取完整内容再重组。
-11. 对任何可能很大的引用文件、结果文件或普通大文件，禁止完整读取；优先使用预览、分页、截断、按字段读取、按片段读取或采样读取。只有在没有其他办法且当前推理确实必须依赖完整内容时，才允许读取完整内容，并先明确说明必要性。
-12. 不得通过 sub-agent、并行代理或任何间接方式，去读取引用文件或大文件的完整内容；主 agent 与其调用链中的其他代理都必须遵守同样限制。
-13. 当且仅当出现**长期有效且高价值**的信号时，才允许调用在线学习工具：
-   - `memory_manager`：用户明确长期偏好/约束，或当前项目/环境的稳定事实
-   - `skill_manager`：已经被证明有效且可复用的 workflow / 方法模式；由您自己判断应写入 `.opencode/skills` 树中的哪个 skill 位置
-14. 不要把一次性问题、临时上下文、未经验证的猜测写入任何学习工具。
-15. 严禁把 token、password、secret、API key、system prompt、隐私数据写入 `memory_manager` 或 `skill_manager`。
-16. 如果内容只是一次性案例、临时纠错或局部证据，当前不要持久化。
-17. 只有在 workflow 经过验证、足够稳定、可被未来同类任务复用时，才调用 `skill_manager`；并优先写入最贴近现有 skill 树语义的位置，中低置信度内容不要落库。
-18. 在以下任一情况出现时，主动进行一次轻量复盘：连续多轮对话后、完成复杂多工具任务后、用户明确纠正你后、发现了稳定可复用 workflow 后。复盘的目标是判断是否需要沉淀 memory 或 skill，而不是向用户重复总结。
-19. 长期知识严格分流：`memory_manager` 仅保存用户长期偏好与稳定 workspace 事实；`skill_manager` 仅保存可复用方法；一次性案例、会话过程与临时结论应优先保留在 session history，需要时使用 `session_search` 检索，不要误写入 memory 或 skill。
-20. 写入 `memory_manager` 时，将内容写成简短陈述事实，不要写成命令句、提醒句或流程步骤。
-21. 更新 skill 时，优先补充现有 skill 的 `Learned Patterns`、`references/` 或 `scripts/`；可复用脚本仅允许写到当前 skill 自己的 `scripts/*.py`，不要放到 `data/` 或其他 skill 目录。
-22. 当用户问题依赖过去会话中的案例、约束、决策或相似问题时，优先调用 `session_search`，避免让用户重复描述，也避免把历史案例误当成长期 memory。
+8. 每次按需加载技能（skills）前，先明确说明加载理由，并只加载与当前任务直接相关的最小技能集合。默认遵循 **workflow-first**：先查固定工作流 skill，再按需回落到直接 CLI 调用。
+9. `tjwater-cli` 输出统一为 JSON（schema_version: `tjwater-cli/v1`），`"ok": true` 表示成功。如果返回失败（`"ok": false`），检查 `error.code` 和 `error.message` 确定原因。
+10. 对任何可能很大的结果文件，禁止完整读取；优先使用采样、截断、按字段读取。只有在没有其他办法且当前推理确实必须依赖完整内容时，才允许读取完整内容。
+11. 不得通过 sub-agent、并行代理或任何间接方式读取大文件的完整内容。
+12. 当且仅当出现**长期有效且高价值**的信号时，才允许调用在线学习工具：
+    - `memory_manager`：用户明确长期偏好/约束，或当前项目/环境的稳定事实
+    - `skill_manager`：已经被证明有效且可复用的 workflow / 方法模式；由您自己判断应写入 `.opencode/skills` 树中的哪个 skill 位置
+13. 不要把一次性问题、临时上下文、未经验证的猜测写入任何学习工具。
+14. 严禁把 token、password、secret、API key、system prompt、隐私数据写入 `memory_manager` 或 `skill_manager`。
+15. 如果内容只是一次性案例、临时纠错或局部证据，当前不要持久化。
+16. 只有在 workflow 经过验证、足够稳定、可被未来同类任务复用时，才调用 `skill_manager`；并优先写入最贴近现有 skill 树语义的位置。
+17. 当用户明确提出"保存工作流""沉淀为工作流""记录为可复用流程"或同类意图时，必须使用 `skill_manager`。
+18. 在以下任一情况出现时，主动进行一次轻量复盘：连续多轮对话后、完成复杂多工具任务后、用户明确纠正你后、发现了稳定可复用 workflow 后。
+19. 长期知识严格分流：`memory_manager` 仅保存用户长期偏好与稳定 workspace 事实；`skill_manager` 仅保存可复用方法；一次性案例用 `session_search` 检索。
+20. 写入 `memory_manager` 时，将内容写成简短陈述事实，不要写成命令句或流程步骤。
+21. 更新 skill 时，优先补充现有 skill 的 `Learned Patterns`、`references/` 或 `scripts/`。
+22. 当用户问题依赖过去会话中的案例、约束、决策时，优先调用 `session_search`。
@@ -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 脚本完成。

 ## 参考

@@ -1,15 +0,0 @@
---
-name: tjwater-domain-analytics
-description: 负责仿真分析、SCADA 分析等计算类 API 能力。
-version: 3.0.0
---
-
-# Analytics Domain Skill
-
-## 简介
-负责仿真分析、SCADA 分析等计算类 API 能力。
-
-## 子模块索引 (渐进式引导)
- **scada-operations**: 见 `./scada-operations/SKILL.md`
- **simulation-analysis**: 见 `./simulation-analysis/SKILL.md`
-
@@ -1,14 +0,0 @@
---
-name: tjwater-scenario-analytics-scada-operations
-description: 负责 SCADA 设备与数据操作。
-version: 3.0.0
---
-
-# scada-operations Scenario Skill
-
-## 简介
-负责 SCADA 设备与数据操作。
-
-## 子模块索引 (渐进式引导)
- **scada**: 见 `./scada/SKILL.md`
-
@@ -1,107 +0,0 @@
---
-name: tjwater-action-analytics-scada-operations-scada
-description: analytics/scada-operations 下 scada 操作技能。
-version: 3.0.0
---
-
-# scada Action Skill
-
-## 简介
-负责 `analytics/scada-operations` 场景下 `scada` 的具体接口调用，分为**设备配置（静态元数据）**、**时序监测数据（TimescaleDB）**、**实时模拟数据**、**方案数据**和**复合查询**五类。
-
-## 子模块索引 (渐进式引导)
- 当前为叶子节点，直接使用下方接口目录。
-
-## 接口目录
-
-### SCADA 设备配置（静态元数据）
-| Method | Path | Summary | Required Params | Optional Params |
-|---|---|---|---|---|
-| GET | `/api/v1/getscadadeviceschema/` | 获取SCADA设备架构 | network (query) | - |
-| GET | `/api/v1/getscadadevice/` | 获取SCADA设备 | network (query), id (query) | - |
-| GET | `/api/v1/getallscadadeviceids/` | 获取所有SCADA设备ID | network (query) | - |
-| GET | `/api/v1/getallscadadevices/` | 获取所有SCADA设备 | network (query) | - |
-| POST | `/api/v1/addscadadevice/` | 添加SCADA设备 | network (query) | - |
-| POST | `/api/v1/setscadadevice/` | 更新SCADA设备 | network (query) | - |
-| POST | `/api/v1/deletescadadevice/` | 删除SCADA设备 | network (query) | - |
-| POST | `/api/v1/cleanscadadevice/` | 清空SCADA设备表 | network (query) | - |
-| GET | `/api/v1/getscadadevicedataschema/` | 获取SCADA设备数据架构 | network (query) | - |
-| GET | `/api/v1/getscadadevicedata/` | 获取SCADA设备数据 | network (query), device_id (query) | - |
-| POST | `/api/v1/addscadadevicedata/` | 添加SCADA设备数据 | network (query) | - |
-| POST | `/api/v1/setscadadevicedata/` | 更新SCADA设备数据 | network (query) | - |
-| POST | `/api/v1/deletescadadevicedata/` | 删除SCADA设备数据 | network (query) | - |
-| POST | `/api/v1/cleanscadadevicedata/` | 清空SCADA设备数据表 | network (query) | - |
-| GET | `/api/v1/getscadaelementschema/` | 获取SCADA元素架构 | network (query) | - |
-| GET | `/api/v1/getscadaelement/` | 获取单个SCADA元素映射 | network (query), id (query) | - |
-| GET | `/api/v1/getscadaelements/` | 获取所有SCADA元素映射 | network (query) | - |
-| POST | `/api/v1/addscadaelement/` | 添加SCADA元素映射 | network (query) | - |
-| POST | `/api/v1/setscadaelement/` | 更新SCADA元素映射 | network (query) | - |
-| POST | `/api/v1/deletescadaelement/` | 删除SCADA元素映射 | network (query) | - |
-| POST | `/api/v1/cleanscadaelement/` | 清空SCADA元素映射表 | network (query) | - |
-| GET | `/api/v1/getscadainfoschema/` | 获取SCADA信息架构 | network (query) | - |
-| GET | `/api/v1/getscadainfo/` | 获取SCADA信息 | network (query), id (query) | - |
-| GET | `/api/v1/getallscadainfo/` | 获取所有SCADA信息 | network (query) | - |
-| GET | `/api/v1/getscadaproperties/` | 获取SCADA属性 | network (query), scada (query) | - |
-| GET | `/api/v1/getallscadaproperties/` | 获取所有SCADA属性 | network (query) | - |
-
-### SCADA 时序监测数据（TimescaleDB）
-| Method | Path | Summary | Required Params | Optional Params |
-|---|---|---|---|---|
-| POST | `/api/v1/scada/batch` | 批量插入SCADA监测数据 | data (body) | - |
-| GET | `/api/v1/scada/by-ids-time-range` | 按设备ID和时间范围查询SCADA数据 | start_time (query), end_time (query), device_ids (query) | - |
-| GET | `/api/v1/scada/by-ids-field-time-range` | 按设备ID、字段和时间范围查询SCADA数据 | start_time (query), end_time (query), field (query), device_ids (query) | - |
-| PATCH | `/api/v1/scada/{device_id}/field` | 更新SCADA设备字段 | device_id (path), time (query), field (query), value (query) | - |
-| DELETE | `/api/v1/scada/by-id-time-range` | 按设备ID和时间范围删除SCADA数据 | device_id (query), start_time (query), end_time (query) | - |
-
-### 实时模拟数据（TimescaleDB - Realtime）
-| Method | Path | Summary | Required Params | Optional Params |
-|---|---|---|---|---|
-| POST | `/api/v1/realtime/links/batch` | 批量插入实时管道数据 | data (body) | - |
-| GET | `/api/v1/realtime/links` | 查询实时管道数据 | start_time (query), end_time (query) | link_ids (query) |
-| DELETE | `/api/v1/realtime/links` | 删除实时管道数据 | start_time (query), end_time (query) | - |
-| PATCH | `/api/v1/realtime/links/{link_id}/field` | 更新实时管道字段 | link_id (path), time (query), field (query), value (query) | - |
-| POST | `/api/v1/realtime/nodes/batch` | 批量插入实时节点数据 | data (body) | - |
-| GET | `/api/v1/realtime/nodes` | 查询实时节点数据 | start_time (query), end_time (query) | node_ids (query) |
-| DELETE | `/api/v1/realtime/nodes` | 删除实时节点数据 | start_time (query), end_time (query) | - |
-| POST | `/api/v1/realtime/simulation/store` | 存储实时模拟结果 | data (body) | - |
-| GET | `/api/v1/realtime/query/by-time-property` | 按时间和属性查询实时数据 | time (query), property (query) | - |
-| GET | `/api/v1/realtime/query/by-id-time` | 按ID和时间查询实时模拟数据 | element_id (query), time (query) | - |
-
-### 方案模拟数据（TimescaleDB - Scheme）
-| Method | Path | Summary | Required Params | Optional Params |
-|---|---|---|---|---|
-| POST | `/api/v1/scheme/links/batch` | 批量插入方案管道数据 | data (body) | - |
-| GET | `/api/v1/scheme/links` | 查询方案管道数据 | scheme_type (query) | link_ids (query) |
-| GET | `/api/v1/scheme/links/{link_id}/field` | 查询方案管道字段数据 | link_id (path), scheme_type (query), field (query) | - |
-| PATCH | `/api/v1/scheme/links/{link_id}/field` | 更新方案管道字段 | link_id (path), scheme_type (query), field (query), value (query) | - |
-| DELETE | `/api/v1/scheme/links` | 删除方案管道数据 | scheme_type (query) | - |
-| POST | `/api/v1/scheme/nodes/batch` | 批量插入方案节点数据 | data (body) | - |
-| GET | `/api/v1/scheme/nodes/{node_id}/field` | 查询方案节点字段数据 | node_id (path), scheme_type (query), field (query) | - |
-| PATCH | `/api/v1/scheme/nodes/{node_id}/field` | 更新方案节点字段 | node_id (path), scheme_type (query), field (query), value (query) | - |
-| DELETE | `/api/v1/scheme/nodes` | 删除方案节点数据 | scheme_type (query) | - |
-| POST | `/api/v1/scheme/simulation/store` | 存储方案模拟结果 | scheme_type (query), data (body) | - |
-| GET | `/api/v1/scheme/query/by-id-time` | 按ID和时间查询方案模拟数据 | element_id (query), scheme_type (query), time (query) | - |
-
-### 复合查询（TimescaleDB - Composite）
-| Method | Path | Summary | Required Params | Optional Params |
-|---|---|---|---|---|
-| GET | `/api/v1/composite/scada-simulation` | 获取SCADA关联的模拟数据 | network (query), start_time (query) | end_time (query) |
-| GET | `/api/v1/composite/element-simulation` | 获取管网元素的模拟数据 | network (query), element_id (query), start_time (query) | end_time (query) |
-| GET | `/api/v1/composite/element-scada` | 获取管网元素关联的SCADA监测数据 | element_id (query), start_time (query) | end_time (query) |
-| POST | `/api/v1/composite/clean-scada` | 清洗SCADA监测数据 | data (body) | - |
-| GET | `/api/v1/composite/pipeline-health-prediction` | 预测管道健康状况 | network (query), time (query) | - |
-
- 覆盖方法：`DELETE, GET, PATCH, POST`
-
-## 接口说明
-
-| 接口 | 说明 |
-|---|---|
-| `GET /scada/by-ids-time-range` | 查询多个设备在指定时间范围内的所有监测字段数据，device_ids 为逗号分隔的ID字符串 |
-| `GET /scada/by-ids-field-time-range` | 查询多个设备在指定时间范围内的特定字段数据（如只查压力或只查流量） |
-| `POST /realtime/simulation/store` | 将水力模拟结果以实时数据形式存入TimescaleDB，供前端实时展示 |
-| `GET /realtime/query/by-time-property` | 按特定时间点和属性名查询管网实时模拟结果 |
-| `GET /composite/scada-simulation` | 同时返回指定管网的SCADA监测数据和对应的水力模拟数据，便于对比分析 |
-| `GET /composite/element-scada` | 查询特定管网元素（管道或节点）关联的SCADA监测时序数据 |
-| `GET /composite/pipeline-health-prediction` | 基于历史SCADA数据和模型预测管道健康状态 |
-| `POST /composite/clean-scada` | 对指定设备的SCADA原始数据进行清洗处理（去异常值等），支持传 'all' 清洗所有设备 |
@@ -1,18 +0,0 @@
---
-name: tjwater-scenario-analytics-simulation-analysis
-description: 负责仿真、风险、漏损与爆管分析。
-version: 3.0.0
---
-
-# simulation-analysis Scenario Skill
-
-## 简介
-负责仿真、风险、漏损与爆管分析。
-
-## 子模块索引 (渐进式引导)
- **burst_detection**: 见 `./burst_detection/SKILL.md`
- **burst_location**: 见 `./burst_location/SKILL.md`
- **leakage**: 见 `./leakage/SKILL.md`
- **risk**: 见 `./risk/SKILL.md`
- **simulation**: 见 `./simulation/SKILL.md`
-
@@ -1,43 +0,0 @@
---
-name: tjwater-action-analytics-simulation-analysis-burst-detection
-description: analytics/simulation-analysis 下 burst-detection 操作技能。
-version: 3.0.0
---
-
-# burst-detection Action Skill
-
-## 简介
-负责 `analytics/simulation-analysis` 场景下 `burst-detection` 的具体接口调用。
-
-## 子模块索引 (渐进式引导)
- 当前为叶子节点，直接使用下方接口目录。
-
-## 接口目录
-| Method | Path | Summary | Required Params | Optional Params |
-|---|---|---|---|---|
-| POST | `/api/v1/burst-detection/detect/` | 执行爆管检测 | data (body) | - |
-| GET | `/api/v1/burst-detection/schemes/` | 查询爆管检测方案列表 | network (query) | query_date (query) |
-| GET | `/api/v1/burst-detection/schemes/{scheme_name}` | 获取爆管检测方案详情 | network (query), scheme_name (path) | - |
-
- 覆盖方法：`GET, POST`
-
-## 接口说明
-
-| 接口 | 说明 |
-|---|---|
-| `POST /detect/` | 基于压力观测数据执行爆管检测分析。使用异常检测算法（隔离森林 IsolationForest）识别压力时间序列中的异常，判定为潜在爆管事件。请求体支持列式字典、逐时刻对象数组、二维数组三种格式的压力数据，可指定数据来源（monitoring 监测 / simulation 模拟）。 |
-| `GET /schemes/` | 获取指定管网的所有爆管检测方案列表，可通过 query_date 按日期筛选。 |
-| `GET /schemes/{scheme_name}` | 获取指定名称的爆管检测方案详细配置信息，包含传感器节点、算法参数等。 |
-
-## 请求体关键字段（POST /detect/）
-
-| 字段 | 类型 | 说明 |
-|---|---|---|
-| `network` | str | 管网名称（数据库名） |
-| `observed_pressure_data` | dict/list/null | 压力观测数据，支持列式字典 `{sensor_id: [values]}` 或逐行数组 |
-| `points_per_day` | int | 每天数据点数，默认1440 |
-| `mu` | int | 异常值检测参数，默认100 |
-| `iforest_params` | dict/null | 隔离森林算法参数，可选 |
-| `scada_start` / `scada_end` | datetime/null | 从SCADA数据库查询的时间范围 |
-| `sensor_nodes` | list/null | 指定传感器节点，null为全部 |
-| `data_source` | str | 数据来源：`monitoring`（监测）或 `simulation`（模拟），默认monitoring |
@@ -1,47 +0,0 @@
---
-name: tjwater-action-analytics-simulation-analysis-burst-location
-description: analytics/simulation-analysis 下 burst-location 操作技能。
-version: 3.0.0
---
-
-# burst-location Action Skill
-
-## 简介
-负责 `analytics/simulation-analysis` 场景下 `burst-location` 的具体接口调用。
-
-## 子模块索引 (渐进式引导)
- 当前为叶子节点，直接使用下方接口目录。
-
-## 接口目录
-| Method | Path | Summary | Required Params | Optional Params |
-|---|---|---|---|---|
-| POST | `/api/v1/burst-location/locate/` | 执行爆管定位 | data (body) | - |
-| GET | `/api/v1/burst-location/schemes/` | 查询爆管定位方案列表 | network (query) | query_date (query) |
-| GET | `/api/v1/burst-location/schemes/{scheme_name}` | 获取爆管定位方案详情 | network (query), scheme_name (path) | - |
-
- 覆盖方法：`GET, POST`
-
-## 接口说明
-
-| 接口 | 说明 |
-|---|---|
-| `POST /locate/` | 基于压力和流量SCADA数据定位管网中的爆管位置。通过对比爆管时与正常状态下的压力/流量差异，计算最可能的爆管节点。 |
-| `GET /schemes/` | 获取指定管网的所有爆管定位方案列表，可通过 query_date 按日期筛选。 |
-| `GET /schemes/{scheme_name}` | 获取指定名称的爆管定位方案详细配置，包含传感器布置、阈值参数等。 |
-
-## 请求体关键字段（POST /locate/）
-
-| 字段 | 类型 | 说明 |
-|---|---|---|
-| `network` | str | 管网名称（数据库名） |
-| `data_source` | str | 数据来源：`monitoring`（监测）或 `simulation`（模拟），默认monitoring |
-| `pressure_scada_ids` | list/null | 压力SCADA传感器ID列表 |
-| `burst_pressure` | dict/list/null | 爆管时的压力数据 |
-| `normal_pressure` | dict/list/null | 正常时的压力数据 |
-| `burst_leakage` | float | 爆管时的漏水量（必填） |
-| `flow_scada_ids` | list/null | 流量SCADA传感器ID列表 |
-| `burst_flow` / `normal_flow` | dict/list/null | 爆管/正常时的流量数据 |
-| `min_dpressure` | float | 最小压力差（bar），默认2.0 |
-| `basic_pressure` | float | 基准压力（bar），默认10.0 |
-| `scada_burst_start` / `scada_burst_end` | datetime/null | 从SCADA数据库查询的爆管时间范围 |
-| `use_scada_flow` | bool | 是否使用SCADA流量数据，默认false |
@@ -1,46 +0,0 @@
---
-name: tjwater-action-analytics-simulation-analysis-leakage
-description: analytics/simulation-analysis 下 leakage 操作技能。
-version: 3.0.0
---
-
-# leakage Action Skill
-
-## 简介
-负责 `analytics/simulation-analysis` 场景下 `leakage` 的具体接口调用。
-
-## 子模块索引 (渐进式引导)
- 当前为叶子节点，直接使用下方接口目录。
-
-## 接口目录
-| Method | Path | Summary | Required Params | Optional Params |
-|---|---|---|---|---|
-| POST | `/api/v1/leakage/identify/` | 执行漏损识别 | data (body) | - |
-| GET | `/api/v1/leakage/schemes/` | 查询漏损识别方案列表 | network (query) | query_date (query) |
-| GET | `/api/v1/leakage/schemes/{scheme_name}` | 获取漏损识别方案详情 | network (query), scheme_name (path) | - |
-
- 覆盖方法：`GET, POST`
-
-## 接口说明
-
-| 接口 | 说明 |
-|---|---|
-| `POST /identify/` | 基于压力观测数据和遗传算法识别管网中的漏损位置和大小。通过对比模型计算与实测压力数据，迭代优化找到最匹配的漏损节点和漏水量。 |
-| `GET /schemes/` | 获取指定管网的所有漏损识别方案列表，可通过 query_date 按日期筛选。 |
-| `GET /schemes/{scheme_name}` | 获取指定名称的漏损识别方案详细配置，包含传感器节点、算法参数等。 |
-
-## 请求体关键字段（POST /identify/）
-
-| 字段 | 类型 | 说明 |
-|---|---|---|
-| `network` | str | 管网名称（数据库名） |
-| `observed_pressure_data` | str/dict/list/null | 观测压力数据 |
-| `start_time` | float | 起始时间（小时），默认0 |
-| `duration` | float | 持续时间（小时），默认24 |
-| `timestep` | float | 时间步长（分钟），默认5 |
-| `q_sum` | float | 总流量（m³/s），默认0.2 |
-| `pop_size` | int | 遗传算法种群大小，默认50 |
-| `max_gen` | int | 遗传算法最大代数，默认100 |
-| `n_workers` | int | 并行工作线程数，默认CPU数-1（最大4） |
-| `scada_start` / `scada_end` | datetime/null | 从SCADA数据库查询的时间范围 |
-| `sensor_nodes` | list/null | 传感器节点列表，null为全部 |
@@ -1,34 +0,0 @@
---
-name: tjwater-action-analytics-simulation-analysis-risk
-description: analytics/simulation-analysis 下 risk 操作技能。
-version: 3.0.0
---
-
-# risk Action Skill
-
-## 简介
-负责 `analytics/simulation-analysis` 场景下 `risk` 的具体接口调用。
-
-## 子模块索引 (渐进式引导)
- 当前为叶子节点，直接使用下方接口目录。
-
-## 接口目录
-| Method | Path | Summary | Required Params | Optional Params |
-|---|---|---|---|---|
-| GET | `/api/v1/getpiperiskprobabilitynow/` | 获取管道当前风险概率 | network (query), pipe_id (query) | - |
-| GET | `/api/v1/getpiperiskprobability/` | 获取管道风险概率历史 | network (query), pipe_id (query) | - |
-| GET | `/api/v1/getpipesriskprobability/` | 批量获取多条管道风险概率 | network (query), pipe_ids (query) | - |
-| GET | `/api/v1/getnetworkpiperiskprobabilitynow/` | 获取整个网络的管道风险概率 | network (query) | - |
-| GET | `/api/v1/getpiperiskprobabilitygeometries/` | 获取管道风险几何信息 | network (query) | - |
-
- 覆盖方法：`GET`
-
-## 接口说明
-
-| 接口 | 说明 |
-|---|---|
-| `GET /getpiperiskprobabilitynow/` | 查询指定管道在当前时刻的风险概率值 |
-| `GET /getpiperiskprobability/` | 查询指定管道的历史风险概率时间序列数据 |
-| `GET /getpipesriskprobability/` | 批量查询多条管道的风险概率，pipe_ids为逗号分隔的ID字符串（如 `pipe1,pipe2,pipe3`） |
-| `GET /getnetworkpiperiskprobabilitynow/` | 查询整个管网中所有管道的当前风险概率，返回列表 |
-| `GET /getpiperiskprobabilitygeometries/` | 查询管网中管道的地理位置和风险相关几何数据，适合地图可视化 |
@@ -1,74 +0,0 @@
---
-name: tjwater-action-analytics-simulation-analysis-simulation
-description: analytics/simulation-analysis 下 simulation 操作技能。
-version: 3.0.0
---
-
-# simulation Action Skill
-
-## 简介
-负责 `analytics/simulation-analysis` 场景下 `simulation` 的具体接口调用。
-
-## 子模块索引 (渐进式引导)
- 当前为叶子节点，直接使用下方接口目录。
-
-## 接口目录
-| Method | Path | Summary | Required Params | Optional Params |
-|---|---|---|---|---|
-| GET | `/api/v1/runproject/` | 运行项目模拟 | network (query) | - |
-| GET | `/api/v1/runprojectreturndict/` | 运行项目模拟（返回字典） | network (query) | - |
-| GET | `/api/v1/runinp/` | 运行INP文件 | network (query) | - |
-| GET | `/api/v1/dumpoutput/` | 导出模拟输出 | output (query) | - |
-| GET | `/api/v1/burstanalysis/` | 爆管分析（基础） | network (query), pipe_id (query), start_time (query), end_time (query), burst_flow (query) | - |
-| GET | `/api/v1/burst_analysis/` | 爆管分析（高级） | network (query), modify_pattern_start_time (query), burst_ID (query), burst_size (query), modify_total_duration (query), scheme_name (query) | - |
-| GET | `/api/v1/valvecloseanalysis/` | 阀门关闭分析（基础） | network (query), valve_id (query), start_time (query), end_time (query) | - |
-| GET | `/api/v1/valve_close_analysis/` | 阀门关闭分析（高级） | network (query), start_time (query), valves (query) | duration (query) |
-| GET | `/api/v1/valve_isolation_analysis/` | 阀门隔离分析 | network (query), accident_element (query) | disabled_valves (query) |
-| GET | `/api/v1/flushinganalysis/` | 冲洗分析（基础） | network (query), pipe_id (query), start_time (query), duration (query), flow (query) | - |
-| GET | `/api/v1/flushing_analysis/` | 冲洗分析（高级） | network (query), start_time (query), valves (query), valves_k (query), drainage_node_ID (query) | flush_flow (query), duration (query), scheme_name (query) |
-| GET | `/api/v1/contaminant_simulation/` | 污染物模拟 | network (query), start_time (query), source (query), concentration (query), duration (query) | scheme_name (query), pattern (query) |
-| GET | `/api/v1/ageanalysis/` | 水龄分析（基础） | network (query) | - |
-| GET | `/api/v1/age_analysis/` | 水龄分析（高级） | network (query), start_time (query), end_time (query), duration (query) | - |
-| GET | `/api/v1/pressureregulation/` | 压力调节（基础） | network (query), target_node (query), target_pressure (query) | - |
-| POST | `/api/v1/pressure_regulation/` | 压力调节（高级） | data (body) | - |
-| GET | `/api/v1/projectmanagement/` | 项目管理（基础） | network (query) | - |
-| POST | `/api/v1/project_management/` | 项目管理（高级） | data (body) | - |
-| POST | `/api/v1/scheduling_analysis/` | 排程分析 | data (body) | - |
-| POST | `/api/v1/daily_scheduling_analysis/` | 日排程分析 | data (body) | - |
-| POST | `/api/v1/network_project/` | 导入网络项目 | file (file) | - |
-| GET | `/api/v1/networkupdate/` | 管网更新（基础） | network (query) | - |
-| POST | `/api/v1/network_update/` | 管网更新（高级） | file (file) | - |
-| POST | `/api/v1/pump_failure/` | 泵故障管理 | data (body) | - |
-| GET | `/api/v1/pressuresensorplacementsensitivity/` | 压力传感器放置-灵敏度分析（基础） | name (query), scheme_name (query), sensor_number (query), min_diameter (query), username (query) | - |
-| POST | `/api/v1/pressure_sensor_placement_sensitivity/` | 压力传感器放置-灵敏度分析（高级） | data (body) | - |
-| GET | `/api/v1/pressuresensorplacementkmeans/` | 压力传感器放置-KMeans聚类分析（基础） | name (query), scheme_name (query), sensor_number (query), min_diameter (query), username (query) | - |
-| POST | `/api/v1/pressure_sensor_placement_kmeans/` | 压力传感器放置-KMeans聚类分析（高级） | data (body) | - |
-| POST | `/api/v1/sensorplacementscheme/create` | 传感器放置方案创建 | network (query), scheme_name (query), sensor_type (query), method (query), sensor_count (query), user_name (query) | min_diameter (query) |
-| POST | `/api/v1/runsimulationmanuallybydate/` | 手动运行日期指定模拟 | data (body) | - |
-
- 覆盖方法：`GET, POST`
-
-## 接口说明
-
-| 接口 | 说明 |
-|---|---|
-| `GET /runproject/` | 运行标准水力模拟，返回纯文本格式的模拟报告 |
-| `GET /runprojectreturndict/` | 运行标准水力模拟，返回JSON字典（含节点/管段结果数据），适合程序处理；结果可达30MB+ |
-| `GET /runinp/` | 运行指定INP文件（文件放在inp文件夹中，参数为不含扩展名的文件名）进行水力模拟 |
-| `GET /dumpoutput/` | 导出指定绝对路径的模拟输出文件内容 |
-| `GET /burstanalysis/` | 基础爆管分析：对指定管道指定时间范围内的爆管事件进行分析，评估对压力/流量的影响 |
-| `GET /burst_analysis/` | 高级爆管分析：支持在指定时间点修改泵控制模式和阀门开度，分析干预措施对爆管影响的作用；支持固定泵和变速泵独立控制 |
-| `GET /valve_close_analysis/` | 高级阀门关闭分析：支持同时关闭多个阀门，指定持续时间，返回纯文本格式结果 |
-| `GET /valve_isolation_analysis/` | 阀门隔离分析：分析突发事件时通过关闭指定阀门进行隔离，确定必须关闭阀门、可选关闭阀门及隔离可行性 |
-| `GET /flushing_analysis/` | 高级冲洗分析：支持同时开启多个阀门冲洗，指定排污节点，设置固定冲洗流量，返回纯文本结果 |
-| `GET /contaminant_simulation/` | 污染物模拟：评估污染源对管网的影响范围和浓度分布，支持指定污染位置、浓度和扩散模式 |
-| `GET /age_analysis/` | 高级水龄分析：在指定时间点分析水体停留时间，支持自定义模拟持续时间，返回纯文本结果 |
-| `POST /pressure_regulation/` | 高级压力调节：通过JSON体提供详细控制参数（固定泵/变速泵独立控制、水箱初始水位等）进行压力优化 |
-| `POST /project_management/` | 高级项目管理：通过JSON体提供详细参数（泵控制策略、水箱水位、区域需水量控制）进行管网管理 |
-| `POST /scheduling_analysis/` | 排程分析：优化泵运行时间和出水流量，平衡水厂出水、水箱进出水，满足用户需求 |
-| `POST /daily_scheduling_analysis/` | 日排程分析：优化水库、水厂、水箱和用户需求协调，制定合理的每日排程方案 |
-| `POST /pump_failure/` | 泵故障管理：记录故障发生时间和受影响的泵列表，更新泵状态日志 |
-| `POST /pressure_sensor_placement_sensitivity/` | 高级传感器放置（灵敏度法）：通过JSON体提供详细参数，基于灵敏度矩阵确定最优放置位置 |
-| `POST /pressure_sensor_placement_kmeans/` | 高级传感器放置（KMeans法）：通过JSON体提供详细参数，基于聚类算法确定最优放置位置 |
-| `POST /sensorplacementscheme/create` | 创建传感器放置方案：支持 sensitivity 和 kmeans 两种算法，自动计算最优传感器位置并存储方案 |
-| `POST /runsimulationmanuallybydate/` | 按日期手动运行模拟：根据指定日期、开始时间和持续时间查询管网参数并执行水力模拟 |
@@ -1,17 +0,0 @@
---
-name: tjwater-domain-business
-description: 负责业务逻辑、业务对象与项目侧 API 能力。
-version: 3.0.0
---
-
-# Business Domain Skill
-
-## 简介
-负责业务逻辑、业务对象与项目侧 API 能力。
-
-## 子模块索引 (渐进式引导)
- **component-config**: 见 `./component-config/SKILL.md`
- **identity-access**: 见 `./identity-access/SKILL.md`
- **network-assets**: 见 `./network-assets/SKILL.md`
- **project-workspace**: 见 `./project-workspace/SKILL.md`
-
@@ -1,19 +0,0 @@
---
-name: tjwater-scenario-business-component-config
-description: 负责组件配置与参数管理。
-version: 3.0.0
---
-
-# component-config Scenario Skill
-
-## 简介
-负责组件配置与参数管理。
-
-## 子模块索引 (渐进式引导)
- **controls**: 见 `./controls/SKILL.md`
- **curves**: 见 `./curves/SKILL.md`
- **options**: 见 `./options/SKILL.md`
- **patterns**: 见 `./patterns/SKILL.md`
- **quality**: 见 `./quality/SKILL.md`
- **visuals**: 见 `./visuals/SKILL.md`
-
@@ -1,36 +0,0 @@
---
-name: tjwater-action-business-component-config-controls
-description: business/component-config 下 controls 操作技能。
-version: 3.0.0
---
-
-# controls Action Skill
-
-## 简介
-负责 `business/component-config` 场景下 `controls` 的具体接口调用。
-
-## 子模块索引 (渐进式引导)
- 当前为叶子节点，直接使用下方接口目录。
-
-## 接口目录
-| Method | Path | Summary | Required Params | Optional Params |
-|---|---|---|---|---|
-| GET | `/api/v1/getcontrolproperties/` | 获取控制属性 | network (query) | - |
-| GET | `/api/v1/getcontrolschema/` | 获取控制架构 | network (query) | - |
-| GET | `/api/v1/getruleproperties/` | 获取规则属性 | network (query) | - |
-| GET | `/api/v1/getruleschema/` | 获取规则架构 | network (query) | - |
-| POST | `/api/v1/setcontrolproperties/` | 设置控制属性 | network (query) | - |
-| POST | `/api/v1/setruleproperties/` | 设置规则属性 | network (query) | - |
-
- 覆盖方法：`GET, POST`
-
-## 接口说明
-
-| 接口 | 说明 |
-|---|---|
-| `GET /getcontrolschema/` | 返回简单控制（Control）数据模型的字段定义 |
-| `GET /getcontrolproperties/` | 获取管网中所有简单控制规则的属性列表 |
-| `GET /getruleschema/` | 返回规则控制（Rule）数据模型的字段定义 |
-| `GET /getruleproperties/` | 获取管网中所有基于规则的复杂控制条件列表 |
-| `POST /setcontrolproperties/` | 设置/更新简单控制规则的属性 |
-| `POST /setruleproperties/` | 设置/更新规则控制的属性 |
@@ -1,37 +0,0 @@
---
-name: tjwater-action-business-component-config-curves
-description: business/component-config 下 curves 操作技能。
-version: 3.0.0
---
-
-# curves Action Skill
-
-## 简介
-负责 `business/component-config` 场景下 `curves` 的具体接口调用。
-
-## 子模块索引 (渐进式引导)
- 当前为叶子节点，直接使用下方接口目录。
-
-## 接口目录
-| Method | Path | Summary | Required Params | Optional Params |
-|---|---|---|---|---|
-| POST | `/api/v1/addcurve/` | 添加曲线 | network (query), curve (query) | - |
-| POST | `/api/v1/deletecurve/` | 删除曲线 | network (query), curve (query) | - |
-| GET | `/api/v1/getcurveproperties/` | 获取曲线属性 | network (query), curve (query) | - |
-| GET | `/api/v1/getcurves/` | 获取所有曲线 | network (query) | - |
-| GET | `/api/v1/getcurveschema` | 获取曲线架构 | network (query) | - |
-| GET | `/api/v1/iscurve/` | 检查曲线存在性 | network (query), curve (query) | - |
-| POST | `/api/v1/setcurveproperties/` | 设置曲线属性 | network (query), curve (query) | - |
-
- 覆盖方法：`GET, POST`
-
-## 接口说明
-
-| 接口 | 说明 |
-|---|---|
-| `GET /getcurveschema` | 返回曲线（Curve）数据模型的字段定义（水泵特性曲线、效率曲线等） |
-| `GET /getcurves/` | 获取管网中所有曲线的ID列表 |
-| `GET /getcurveproperties/` | 查询指定曲线的详细属性（类型、控制点数据等） |
-| `POST /addcurve/` | 向管网添加一条新曲线 |
-| `POST /deletecurve/` | 从管网删除指定曲线 |
-| `POST /setcurveproperties/` | 设置/更新曲线的属性（控制点坐标等） |
@@ -1,43 +0,0 @@
---
-name: tjwater-action-business-component-config-options
-description: business/component-config 下 options 操作技能。
-version: 3.0.0
---
-
-# options Action Skill
-
-## 简介
-负责 `business/component-config` 场景下 `options` 的具体接口调用。
-
-## 子模块索引 (渐进式引导)
- 当前为叶子节点，直接使用下方接口目录。
-
-## 接口目录
-| Method | Path | Summary | Required Params | Optional Params |
-|---|---|---|---|---|
-| GET | `/api/v1/getenergyproperties/` | 获取能耗选项属性 | network (query) | - |
-| GET | `/api/v1/getenergyschema/` | 获取能耗选项架构 | network (query) | - |
-| GET | `/api/v1/getoptionproperties/` | 获取选项属性 | network (query) | - |
-| GET | `/api/v1/getoptionschema/` | 获取选项架构 | network (query) | - |
-| GET | `/api/v1/getpumpenergyproperties/` | 获取泵能耗属性 | - | - |
-| GET | `/api/v1/getpumpenergyschema/` | 获取泵能耗选项架构 | network (query) | - |
-| GET | `/api/v1/gettimeproperties/` | 获取时间选项属性 | network (query) | - |
-| GET | `/api/v1/gettimeschema` | 获取时间选项架构 | network (query) | - |
-| POST | `/api/v1/setenergyproperties/` | 设置能耗选项属性 | network (query) | - |
-| POST | `/api/v1/setoptionproperties/` | 设置选项属性 | network (query) | - |
-| GET | `/api/v1/setpumpenergyproperties/` | 设置泵能耗属性 | - | - |
-| POST | `/api/v1/settimeproperties/` | 设置时间选项属性 | network (query) | - |
-
- 覆盖方法：`GET, POST`
-
-## 接口说明
-
-| 接口 | 说明 |
-|---|---|
-| `GET /getoptionschema/` | 返回模拟选项（Options）数据模型的字段定义 |
-| `GET /getoptionproperties/` | 获取管网模拟参数设置（时步、精度、单位系统等） |
-| `GET /getenergyschema/` | 返回能耗选项（Energy）数据模型的字段定义 |
-| `GET /getenergyproperties/` | 获取全局能耗设置（电价、效率等） |
-| `GET /getpumpenergyproperties/` | 获取单台水泵的能耗参数 |
-| `POST /setoptionproperties/` | 设置管网模拟参数 |
-| `POST /setenergyproperties/` | 设置全局能耗参数 |
@@ -1,37 +0,0 @@
---
-name: tjwater-action-business-component-config-patterns
-description: business/component-config 下 patterns 操作技能。
-version: 3.0.0
---
-
-# patterns Action Skill
-
-## 简介
-负责 `business/component-config` 场景下 `patterns` 的具体接口调用。
-
-## 子模块索引 (渐进式引导)
- 当前为叶子节点，直接使用下方接口目录。
-
-## 接口目录
-| Method | Path | Summary | Required Params | Optional Params |
-|---|---|---|---|---|
-| POST | `/api/v1/addpattern/` | 添加模式 | network (query), pattern (query) | - |
-| POST | `/api/v1/deletepattern/` | 删除模式 | network (query), pattern (query) | - |
-| GET | `/api/v1/getpatternproperties/` | 获取模式属性 | network (query), pattern (query) | - |
-| GET | `/api/v1/getpatterns/` | 获取所有模式 | network (query) | - |
-| GET | `/api/v1/getpatternschema` | 获取模式架构 | network (query) | - |
-| GET | `/api/v1/ispattern/` | 检查模式存在性 | network (query), pattern (query) | - |
-| POST | `/api/v1/setpatternproperties/` | 设置模式属性 | network (query), pattern (query) | - |
-
- 覆盖方法：`GET, POST`
-
-## 接口说明
-
-| 接口 | 说明 |
-|---|---|
-| `GET /getpatternschema` | 返回模式（Pattern）数据模型的字段定义 |
-| `GET /getpatterns/` | 获取管网中所有时间模式的ID列表 |
-| `GET /getpatternproperties/` | 查询指定模式的属性（时间序列乘数值等） |
-| `POST /addpattern/` | 向管网添加一个新时间模式 |
-| `POST /deletepattern/` | 从管网删除指定时间模式 |
-| `POST /setpatternproperties/` | 设置/更新时间模式的属性（乘数序列） |
@@ -1,59 +0,0 @@
---
-name: tjwater-action-business-component-config-quality
-description: business/component-config 下 quality 操作技能。
-version: 3.0.0
---
-
-# quality Action Skill
-
-## 简介
-负责 `business/component-config` 场景下 `quality` 的具体接口调用。
-
-## 子模块索引 (渐进式引导)
- 当前为叶子节点，直接使用下方接口目录。
-
-## 接口目录
-| Method | Path | Summary | Required Params | Optional Params |
-|---|---|---|---|---|
-| POST | `/api/v1/addmixing/` | 添加混合 | network (query) | - |
-| POST | `/api/v1/addsource/` | 添加水源 | network (query) | - |
-| POST | `/api/v1/deletemixing/` | 删除混合 | network (query) | - |
-| POST | `/api/v1/deletesource/` | 删除水源 | network (query), node (query) | - |
-| GET | `/api/v1/getemitterproperties/` | 获取发射器属性 | network (query), junction (query) | - |
-| GET | `/api/v1/getemitterschema` | 获取发射器架构 | network (query) | - |
-| GET | `/api/v1/getmixing/` | 获取混合属性 | network (query), tank (query) | - |
-| GET | `/api/v1/getmixingschema/` | 获取混合架构 | network (query) | - |
-| GET | `/api/v1/getpipereaction/` | 获取管道反应属性 | network (query), pipe (query) | - |
-| GET | `/api/v1/getpipereactionschema/` | 获取管道反应架构 | network (query) | - |
-| GET | `/api/v1/getqualityproperties/` | 获取水质属性 | network (query), node (query) | - |
-| GET | `/api/v1/getqualityschema/` | 获取水质架构 | network (query) | - |
-| GET | `/api/v1/getreaction/` | 获取反应属性 | network (query) | - |
-| GET | `/api/v1/getreactionschema/` | 获取反应架构 | network (query) | - |
-| GET | `/api/v1/getsource/` | 获取水源属性 | network (query), node (query) | - |
-| GET | `/api/v1/getsourcechema/` | 获取水源架构 | network (query) | - |
-| GET | `/api/v1/gettankreaction/` | 获取水池反应属性 | network (query), tank (query) | - |
-| GET | `/api/v1/gettankreactionschema/` | 获取水池反应架构 | network (query) | - |
-| POST | `/api/v1/setemitterproperties/` | 设置发射器属性 | network (query), junction (query) | - |
-| POST | `/api/v1/setmixing/` | 设置混合属性 | network (query) | - |
-| POST | `/api/v1/setpipereaction/` | 设置管道反应属性 | network (query) | - |
-| POST | `/api/v1/setqualityproperties/` | 设置水质属性 | network (query) | - |
-| POST | `/api/v1/setreaction/` | 设置反应属性 | network (query) | - |
-| POST | `/api/v1/setsource/` | 设置水源属性 | network (query) | - |
-| POST | `/api/v1/settankreaction/` | 设置水池反应属性 | network (query) | - |
-
- 覆盖方法：`GET, POST`
-
-## 接口说明
-
-| 接口 | 说明 |
-|---|---|
-| `GET /getemitterproperties/` | 查询节点处发射器（用于模拟管漏）的属性 |
-| `GET /getmixingproperties/` | 查询水箱水质混合模型属性 |
-| `GET /getsourceproperties/` | 查询水质污染源的属性（位置、类型、浓度等） |
-| `GET /getreactionproperties/` | 获取全局水质反应参数（管网反应系数等） |
-| `GET /getwaterqualityresult/` | 查询水质模拟结果 |
-| `POST /addsource/` | 向管网添加一个水质污染源 |
-| `POST /deletesource/` | 删除指定水质污染源 |
-| `POST /addmixing/` | 为水箱添加水质混合模型 |
-| `POST /deletemixing/` | 删除水箱水质混合模型 |
-| `POST /setemitter*/` | 设置发射器属性（流量系数等） |
@@ -1,45 +0,0 @@
---
-name: tjwater-action-business-component-config-visuals
-description: business/component-config 下 visuals 操作技能。
-version: 3.0.0
---
-
-# visuals Action Skill
-
-## 简介
-负责 `business/component-config` 场景下 `visuals` 的具体接口调用。
-
-## 子模块索引 (渐进式引导)
- 当前为叶子节点，直接使用下方接口目录。
-
-## 接口目录
-| Method | Path | Summary | Required Params | Optional Params |
-|---|---|---|---|---|
-| POST | `/api/v1/addlabel/` | 添加标签 | network (query) | - |
-| POST | `/api/v1/addvertex/` | 添加图形元素 | network (query) | - |
-| POST | `/api/v1/deletelabel/` | 删除标签 | network (query) | - |
-| POST | `/api/v1/deletevertex/` | 删除图形元素 | network (query) | - |
-| GET | `/api/v1/getallvertexlinks/` | 获取所有图形元素链接 | network (query) | - |
-| GET | `/api/v1/getallvertices/` | 获取所有图形元素 | network (query) | - |
-| GET | `/api/v1/getbackdropproperties/` | 获取背景属性 | network (query) | - |
-| GET | `/api/v1/getbackdropschema/` | 获取背景架构 | network (query) | - |
-| GET | `/api/v1/getlabelproperties/` | 获取标签属性 | network (query), x (query), y (query) | - |
-| GET | `/api/v1/getlabelschema/` | 获取标签架构 | network (query) | - |
-| GET | `/api/v1/getvertexproperties/` | 获取图形元素属性 | network (query), link (query) | - |
-| GET | `/api/v1/getvertexschema/` | 获取图形元素架构 | network (query) | - |
-| POST | `/api/v1/setbackdropproperties/` | 设置背景属性 | network (query) | - |
-| POST | `/api/v1/setlabelproperties/` | 设置标签属性 | network (query) | - |
-| POST | `/api/v1/setvertexproperties/` | 设置图形元素属性 | network (query) | - |
-
- 覆盖方法：`GET, POST`
-
-## 接口说明
-
-| 接口 | 说明 |
-|---|---|
-| `GET /getallvertexlinks/` | 获取所有管线的折点列表（用于地图还原管线真实走向） |
-| `GET /getvertexlink/` | 获取单条管线的折点坐标序列 |
-| `POST /addvertex/` | 为管线添加一个折点（改变管线显示路径） |
-| `POST /deletevertex/` | 删除管线上的指定折点 |
-| `POST /addlabel/` | 在地图上添加文字标注 |
-| `POST /deletelabel/` | 删除地图文字标注 |
@@ -1,16 +0,0 @@
---
-name: tjwater-scenario-business-identity-access
-description: 负责认证、用户与权限相关操作。
-version: 3.0.0
---
-
-# identity-access Scenario Skill
-
-## 简介
-负责认证、用户与权限相关操作。
-
-## 子模块索引 (渐进式引导)
- **auth**: 见 `./auth/SKILL.md`
- **user_management**: 见 `./user_management/SKILL.md`
- **users**: 见 `./users/SKILL.md`
-
@@ -1,32 +0,0 @@
---
-name: tjwater-action-business-identity-access-auth
-description: business/identity-access 下 auth 操作技能。
-version: 3.0.0
---
-
-# auth Action Skill
-
-## 简介
-负责 `business/identity-access` 场景下 `auth` 的具体接口调用。
-
-## 子模块索引 (渐进式引导)
- 当前为叶子节点，直接使用下方接口目录。
-
-## 接口目录
-| Method | Path | Summary | Required Params | Optional Params |
-|---|---|---|---|---|
-| POST | `/api/v1/auth/login` | 用户登录 | form_data (body) | - |
-| POST | `/api/v1/auth/login/simple` | 简化版登录 | username (query), password (query) | - |
-| GET | `/api/v1/auth/me` | 获取当前用户信息 | - | - |
-| POST | `/api/v1/auth/refresh` | 刷新AccessToken | refresh_token (query) | - |
-
- 覆盖方法：`GET, POST`
-
-## 接口说明
-
-| 接口 | 说明 |
-|---|---|
-| `POST /login` | OAuth2标准格式登录，提交form-data（username+password），返回JWT Access Token和Refresh Token |
-| `POST /login/simple` | 简化版登录，直接通过query参数传递username和password，保持向后兼容 |
-| `GET /me` | 返回当前已登录用户的详细信息（需携带Access Token） |
-| `POST /refresh` | 使用Refresh Token换取新的Access Token，延续会话 |
@@ -1,36 +0,0 @@
---
-name: tjwater-action-business-identity-access-user-management
-description: business/identity-access 下 user-management 操作技能。
-version: 3.0.0
---
-
-# user-management Action Skill
-
-## 简介
-负责 `business/identity-access` 场景下 `user-management` 的具体接口调用。
-
-## 子模块索引 (渐进式引导)
- 当前为叶子节点，直接使用下方接口目录。
-
-## 接口目录
-| Method | Path | Summary | Required Params | Optional Params |
-|---|---|---|---|---|
-| GET | `/api/v1/users/` | 列出所有用户 | - | skip (query), limit (query) |
-| DELETE | `/api/v1/users/{user_id}` | 删除用户 | user_id (path) | - |
-| GET | `/api/v1/users/{user_id}` | 获取用户详情 | user_id (path) | - |
-| PUT | `/api/v1/users/{user_id}` | 更新用户信息 | user_id (path) | user_update (body) |
-| POST | `/api/v1/users/{user_id}/activate` | 激活用户 | user_id (path) | - |
-| POST | `/api/v1/users/{user_id}/deactivate` | 停用用户 | user_id (path) | - |
-
- 覆盖方法：`DELETE, GET, POST, PUT`
-
-## 接口说明
-
-| 接口 | 说明 |
-|---|---|
-| `GET /users/` | 列出系统中所有用户（管理员权限），支持分页（skip/limit） |
-| `GET /users/{user_id}` | 按用户ID查询单个用户的详细信息 |
-| `PUT /users/{user_id}` | 更新指定用户的信息（邮箱、角色、密码等），请求体为 user_update 对象 |
-| `DELETE /users/{user_id}` | 删除指定用户（软删除或硬删除） |
-| `POST /users/{user_id}/activate` | 激活指定用户账号（管理员操作） |
-| `POST /users/{user_id}/deactivate` | 停用指定用户账号（禁止登录，管理员操作） |
@@ -1,30 +0,0 @@
---
-name: tjwater-action-business-identity-access-users
-description: business/identity-access 下 users 操作技能。
-version: 3.0.0
---
-
-# users Action Skill
-
-## 简介
-负责 `business/identity-access` 场景下 `users` 的具体接口调用。
-
-## 子模块索引 (渐进式引导)
- 当前为叶子节点，直接使用下方接口目录。
-
-## 接口目录
-| Method | Path | Summary | Required Params | Optional Params |
-|---|---|---|---|---|
-| GET | `/api/v1/getallusers/` | 获取所有用户 | network (query) | - |
-| GET | `/api/v1/getuser/` | 获取单个用户 | network (query), user_name (query) | - |
-| GET | `/api/v1/getuserschema/` | 获取用户模式 | network (query) | - |
-
- 覆盖方法：`GET`
-
-## 接口说明
-
-| 接口 | 说明 |
-|---|---|
-| `GET /getallusers/` | 获取指定管网下的所有用户列表（旧版接口，返回管网级别用户信息） |
-| `GET /getuser/` | 按用户名查询指定管网下的单个用户信息 |
-| `GET /getuserschema/` | 获取用户数据模型的字段定义（Schema） |
@@ -1,24 +0,0 @@
---
-name: tjwater-scenario-business-network-assets
-description: 负责管网资产与拓扑对象操作。
-version: 3.0.0
---
-
-# network-assets Scenario Skill
-
-## 简介
-负责管网资产与拓扑对象操作。
-
-## 子模块索引 (渐进式引导)
- **demands**: 见 `./demands/SKILL.md`
- **general**: 见 `./general/SKILL.md`
- **geometry**: 见 `./geometry/SKILL.md`
- **junctions**: 见 `./junctions/SKILL.md`
- **pipes**: 见 `./pipes/SKILL.md`
- **pumps**: 见 `./pumps/SKILL.md`
- **regions**: 见 `./regions/SKILL.md`
- **reservoirs**: 见 `./reservoirs/SKILL.md`
- **tags**: 见 `./tags/SKILL.md`
- **tanks**: 见 `./tanks/SKILL.md`
- **valves**: 见 `./valves/SKILL.md`
-
@@ -1,36 +0,0 @@
---
-name: tjwater-action-business-network-assets-demands
-description: business/network-assets 下 demands 操作技能。
-version: 3.0.0
---
-
-# demands Action Skill
-
-## 简介
-负责 `business/network-assets` 场景下 `demands` 的具体接口调用。
-
-## 子模块索引 (渐进式引导)
- 当前为叶子节点，直接使用下方接口目录。
-
-## 接口目录
-| Method | Path | Summary | Required Params | Optional Params |
-|---|---|---|---|---|
-| GET | `/api/v1/calculatedemandtonetwork/` | 计算需水量到整网分配 | network (query), demand (query) | - |
-| GET | `/api/v1/calculatedemandtonodes/` | 计算需水量到节点分配 | network (query) | - |
-| GET | `/api/v1/calculatedemandtoregion/` | 计算需水量到区域分配 | network (query) | - |
-| GET | `/api/v1/getdemandproperties/` | 获取需水量属性 | network (query), junction (query) | - |
-| GET | `/api/v1/getdemandschema` | 获取需水量属性架构 | network (query) | - |
-| POST | `/api/v1/setdemandproperties/` | 设置需水量属性 | network (query), junction (query) | - |
-
- 覆盖方法：`GET, POST`
-
-## 接口说明
-
-| 接口 | 说明 |
-|---|---|
-| `GET /getdemandschema` | 返回需水量（Demand）数据模型的字段定义 |
-| `GET /getdemandproperties/` | 查询指定节点的需水量属性（基础需水量、模式等） |
-| `POST /setdemandproperties/` | 设置节点的需水量属性 |
-| `POST /calculatedemandtonodes/` | 将指定总需水量计算分配到各节点 |
-| `POST /calculatedemandtoregion/` | 将指定总需水量计算分配到指定区域内的节点 |
-| `POST /calculatedemandtonetwork/` | 将指定总需水量按比例分配到整个管网的所有节点 |
@@ -1,62 +0,0 @@
---
-name: tjwater-action-business-network-assets-general
-description: business/network-assets 下 general 操作技能。
-version: 3.0.0
---
-
-# general Action Skill
-
-## 简介
-负责 `business/network-assets` 场景下 `general` 的具体接口调用。
-
-## 子模块索引 (渐进式引导)
- 当前为叶子节点，直接使用下方接口目录。
-
-## 接口目录
-| Method | Path | Summary | Required Params | Optional Params |
-|---|---|---|---|---|
-| POST | `/api/v1/deletelink/` | 删除管线 | network (query), link (query) | - |
-| POST | `/api/v1/deletenode/` | 删除节点 | network (query), node (query) | - |
-| GET | `/api/v1/getallscadaproperties/` | 获取所有SCADA点属性 | network (query) | - |
-| GET | `/api/v1/getelementproperties/` | 获取元素属性 | network (query), element (query) | - |
-| GET | `/api/v1/getelementpropertieswithtype/` | 获取指定类型元素属性 | network (query), elementtype (query), element (query) | - |
-| GET | `/api/v1/getelementtype/` | 获取元素类型 | network (query), element (query) | - |
-| GET | `/api/v1/getelementtypevalue/` | 获取元素类型值 | network (query), element (query) | - |
-| GET | `/api/v1/getlinkproperties/` | 获取管线属性 | network (query), link (query) | - |
-| GET | `/api/v1/getlinks/` | 获取所有管线 | network (query) | - |
-| GET | `/api/v1/getlinktype/` | 获取管线类型 | network (query), link (query) | - |
-| GET | `/api/v1/getnodelinks/` | 获取节点的关联管线 | network (query), node (query) | - |
-| GET | `/api/v1/getnodeproperties/` | 获取节点属性 | network (query), node (query) | - |
-| GET | `/api/v1/getnodes/` | 获取所有节点 | network (query) | - |
-| GET | `/api/v1/getnodetype/` | 获取节点类型 | network (query), node (query) | - |
-| GET | `/api/v1/getscadaproperties/` | 获取SCADA点属性 | network (query), scada (query) | - |
-| GET | `/api/v1/getstatus/` | 获取管线状态 | network (query), link (query) | - |
-| GET | `/api/v1/getstatusschema` | 获取状态属性架构 | network (query) | - |
-| GET | `/api/v1/gettitle/` | 获取水网标题属性 | network (query) | - |
-| GET | `/api/v1/gettitleschema/` | 获取标题属性架构 | network (query) | - |
-| GET | `/api/v1/isjunction/` | 检查是否为接点 | network (query), node (query) | - |
-| GET | `/api/v1/islink/` | 检查管线有效性 | network (query), link (query) | - |
-| GET | `/api/v1/isnode/` | 检查节点有效性 | network (query), node (query) | - |
-| GET | `/api/v1/ispipe/` | 检查是否为管道 | network (query), link (query) | - |
-| GET | `/api/v1/ispump/` | 检查是否为泵 | network (query), link (query) | - |
-| GET | `/api/v1/isreservoir/` | 检查是否为水源 | network (query), node (query) | - |
-| GET | `/api/v1/istank/` | 检查是否为蓄水池 | network (query), node (query) | - |
-| GET | `/api/v1/isvalve/` | 检查是否为阀门 | network (query), link (query) | - |
-| POST | `/api/v1/setstatus/` | 设置管线状态 | network (query), link (query) | - |
-| GET | `/api/v1/settitle/` | 设置水网标题属性 | network (query) | - |
-
- 覆盖方法：`GET, POST`
-
-## 接口说明
-
-| 接口 | 说明 |
-|---|---|
-| `GET /getelementtype/` | 查询指定ID元素的类型（Junction/Pipe/Pump/Tank/Valve/Reservoir） |
-| `GET /getelementtypevalue/` | 查询指定ID元素的类型编码值 |
-| `GET /getelementproperties/` | 查询指定ID元素的所有属性（自动识别类型） |
-| `GET /getelementpropertieswithtype/` | 查询指定类型和ID的元素属性 |
-| `GET /getlinkproperties/` | 查询管线（Pipe/Pump/Valve）的属性 |
-| `GET /getnodeproperties/` | 查询节点（Junction/Tank/Reservoir）的属性 |
-| `GET /settitle/` | 设置管网标题属性 |
-| `POST /deletelink/` | 删除管线（管道/水泵/阀门） |
-| `POST /deletenode/` | 删除节点（节点/水箱/水库） |
@@ -1,36 +0,0 @@
---
-name: tjwater-action-business-network-assets-geometry
-description: business/network-assets 下 geometry 操作技能。
-version: 3.0.0
---
-
-# geometry Action Skill
-
-## 简介
-负责 `business/network-assets` 场景下 `geometry` 的具体接口调用。
-
-## 子模块索引 (渐进式引导)
- 当前为叶子节点，直接使用下方接口目录。
-
-## 接口目录
-| Method | Path | Summary | Required Params | Optional Params |
-|---|---|---|---|---|
-| GET | `/api/v1/getmajornodecoords/` | 获取主要节点坐标 | network (query), diameter (query) | - |
-| GET | `/api/v1/getmajorpipenodes/` | 获取主要管道节点 | network (query), diameter (query) | - |
-| GET | `/api/v1/getnetworkgeometries/` | 获取完整网络几何信息 | network (query) | - |
-| GET | `/api/v1/getnetworkinextent/` | 获取范围内的网络元素 | network (query), x1 (query), y1 (query), x2 (query), y2 (query) | - |
-| GET | `/api/v1/getnetworklinknodes/` | 获取网络管线节点 | network (query) | - |
-| GET | `/api/v1/getnodecoord/` | 获取节点坐标 | network (query), node (query) | - |
-
- 覆盖方法：`GET`
-
-## 接口说明
-
-| 接口 | 说明 |
-|---|---|
-| `GET /getnodecoord/` | 查询单个节点（任意类型）的坐标（x, y） |
-| `GET /getmajornodecoords/` | 获取管网主要节点（干管节点）的坐标列表，用于快速渲染 |
-| `GET /getmajorpipenodes/` | 获取主要管道的起终节点列表 |
-| `GET /getnetworklinknodes/` | 获取管网中所有管线的起终节点信息 |
-| `GET /getnetworkgeometries/` | 获取整个管网的完整几何信息（节点坐标 + 管线折点），适合地图绘制 |
-| `GET /getnetworkinextent/` | 查询指定地理范围（bbox）内的管网节点和管线 |
@@ -1,52 +0,0 @@
---
-name: tjwater-action-business-network-assets-junctions
-description: business/network-assets 下 junctions 操作技能。
-version: 3.0.0
---
-
-# junctions Action Skill
-
-## 简介
-负责 `business/network-assets` 场景下 `junctions` 的具体接口调用。
-
-## 子模块索引 (渐进式引导)
- 当前为叶子节点，直接使用下方接口目录。
-
-## 接口目录
-| Method | Path | Summary | Required Params | Optional Params |
-|---|---|---|---|---|
-| POST | `/api/v1/addjunction/` | 添加节点 | network (query), junction (query), x (query), y (query), z (query) | - |
-| POST | `/api/v1/deletejunction/` | 删除节点 | network (query), junction (query) | - |
-| GET | `/api/v1/getalljunctionproperties/` | 获取所有节点属性 | network (query) | - |
-| GET | `/api/v1/getjunctioncoord/` | 获取节点坐标 | network (query), junction (query) | - |
-| GET | `/api/v1/getjunctiondemand/` | 获取节点需水量 | network (query), junction (query) | - |
-| GET | `/api/v1/getjunctionelevation/` | 获取节点标高 | network (query), junction (query) | - |
-| GET | `/api/v1/getjunctionpattern/` | 获取节点需水模式 | network (query), junction (query) | - |
-| GET | `/api/v1/getjunctionproperties/` | 获取节点属性 | network (query), junction (query) | - |
-| GET | `/api/v1/getjunctionschema` | 获取节点架构 | network (query) | - |
-| GET | `/api/v1/getjunctionx/` | 获取节点 X 坐标 | network (query), junction (query) | - |
-| GET | `/api/v1/getjunctiony/` | 获取节点 Y 坐标 | network (query), junction (query) | - |
-| POST | `/api/v1/setjunctioncoord/` | 设置节点坐标 | network (query), junction (query), x (query), y (query) | - |
-| POST | `/api/v1/setjunctiondemand/` | 设置节点需水量 | network (query), junction (query), demand (query) | - |
-| POST | `/api/v1/setjunctionelevation/` | 设置节点标高 | network (query), junction (query), elevation (query) | - |
-| POST | `/api/v1/setjunctionpattern/` | 设置节点需水模式 | network (query), junction (query), pattern (query) | - |
-| POST | `/api/v1/setjunctionproperties/` | 批量设置节点属性 | network (query), junction (query) | - |
-| POST | `/api/v1/setjunctionx/` | 设置节点 X 坐标 | network (query), junction (query), x (query) | - |
-| POST | `/api/v1/setjunctiony/` | 设置节点 Y 坐标 | network (query), junction (query), y (query) | - |
-
- 覆盖方法：`GET, POST`
-
-## 接口说明
-
-| 接口 | 说明 |
-|---|---|
-| `GET /getjunctionschema` | 返回节点（Junction）数据模型的所有字段定义 |
-| `GET /getjunctionproperties/` | 查询单个节点的所有属性（标高、需水量、坐标等） |
-| `GET /getalljunctionproperties/` | 批量获取管网中所有节点的属性列表 |
-| `GET /getjunctioncoord/` | 查询单个节点的坐标（x, y） |
-| `GET /getjunctionelevation/` | 查询节点标高值 |
-| `GET /getjunctiondemand/` | 查询节点基础需水量 |
-| `GET /getjunctionpattern/` | 查询节点关联的需水时间模式名称 |
-| `POST /addjunction/` | 向管网添加一个新节点，需提供ID、坐标和标高 |
-| `POST /deletejunction/` | 从管网删除指定节点 |
-| `POST /setjunction*/` | 设置节点某个具体属性（坐标、标高、需水量等） |
@@ -1,54 +0,0 @@
---
-name: tjwater-action-business-network-assets-pipes
-description: business/network-assets 下 pipes 操作技能。
-version: 3.0.0
---
-
-# pipes Action Skill
-
-## 简介
-负责 `business/network-assets` 场景下 `pipes` 的具体接口调用。
-
-## 子模块索引 (渐进式引导)
- 当前为叶子节点，直接使用下方接口目录。
-
-## 接口目录
-| Method | Path | Summary | Required Params | Optional Params |
-|---|---|---|---|---|
-| POST | `/api/v1/addpipe/` | 添加管道 | network (query), pipe (query), node1 (query), node2 (query) | length (query), diameter (query), roughness (query), minor_loss (query), status (query) |
-| POST | `/api/v1/deletepipe/` | 删除管道 | network (query), pipe (query) | - |
-| GET | `/api/v1/getallpipeproperties/` | 获取所有管道属性 | network (query) | - |
-| GET | `/api/v1/getpipediameter/` | 获取管道管径 | network (query), pipe (query) | - |
-| GET | `/api/v1/getpipelength/` | 获取管道长度 | network (query), pipe (query) | - |
-| GET | `/api/v1/getpipeminorloss/` | 获取管道局部阻力系数 | network (query), pipe (query) | - |
-| GET | `/api/v1/getpipenode1/` | 获取管道起始节点 | network (query), pipe (query) | - |
-| GET | `/api/v1/getpipenode2/` | 获取管道终止节点 | network (query), pipe (query) | - |
-| GET | `/api/v1/getpipeproperties/` | 获取管道属性 | network (query), pipe (query) | - |
-| GET | `/api/v1/getpiperoughness/` | 获取管道粗糙度 | network (query), pipe (query) | - |
-| GET | `/api/v1/getpipeschema` | 获取管道模式 | network (query) | - |
-| GET | `/api/v1/getpipestatus/` | 获取管道状态 | network (query), pipe (query) | - |
-| POST | `/api/v1/setpipediameter/` | 设置管道管径 | network (query), pipe (query), diameter (query) | - |
-| POST | `/api/v1/setpipelength/` | 设置管道长度 | network (query), pipe (query), length (query) | - |
-| POST | `/api/v1/setpipeminorloss/` | 设置管道局部阻力系数 | network (query), pipe (query), minor_loss (query) | - |
-| POST | `/api/v1/setpipenode1/` | 设置管道起始节点 | network (query), pipe (query), node1 (query) | - |
-| POST | `/api/v1/setpipenode2/` | 设置管道终止节点 | network (query), pipe (query), node2 (query) | - |
-| POST | `/api/v1/setpipeproperties/` | 设置管道属性 | network (query), pipe (query) | - |
-| POST | `/api/v1/setpiperoughness/` | 设置管道粗糙度 | network (query), pipe (query), roughness (query) | - |
-| POST | `/api/v1/setpipestatus/` | 设置管道状态 | network (query), pipe (query), status (query) | - |
-
- 覆盖方法：`GET, POST`
-
-## 接口说明
-
-| 接口 | 说明 |
-|---|---|
-| `GET /getpipeschema` | 返回管道（Pipe）数据模型的所有字段定义 |
-| `GET /getpipeproperties/` | 查询单条管道的所有属性（管径、长度、起终节点等） |
-| `GET /getallpipeproperties/` | 批量获取管网中所有管道的属性列表 |
-| `GET /getpipelength/` | 查询管道长度 |
-| `GET /getpipediameter/` | 查询管道管径 |
-| `GET /getpipestatus/` | 查询管道当前状态（开/关/CV） |
-| `GET /getpiperoughness/` | 查询管道粗糙系数 |
-| `POST /addpipe/` | 向管网添加一条新管道，需提供ID、起终节点、长度和管径 |
-| `POST /deletepipe/` | 从管网删除指定管道 |
-| `POST /setpipe*/` | 设置管道某个具体属性（管径、长度、状态等） |
@@ -1,42 +0,0 @@
---
-name: tjwater-action-business-network-assets-pumps
-description: business/network-assets 下 pumps 操作技能。
-version: 3.0.0
---
-
-# pumps Action Skill
-
-## 简介
-负责 `business/network-assets` 场景下 `pumps` 的具体接口调用。
-
-## 子模块索引 (渐进式引导)
- 当前为叶子节点，直接使用下方接口目录。
-
-## 接口目录
-| Method | Path | Summary | Required Params | Optional Params |
-|---|---|---|---|---|
-| POST | `/api/v1/addpump/` | 添加水泵 | network (query), pump (query), node1 (query), node2 (query) | power (query) |
-| POST | `/api/v1/deletepump/` | 删除水泵 | network (query), pump (query) | - |
-| GET | `/api/v1/getallpumpproperties/` | 获取所有水泵属性 | network (query) | - |
-| GET | `/api/v1/getpumpnode1/` | 获取水泵起始节点 | network (query), pump (query) | - |
-| GET | `/api/v1/getpumpnode2/` | 获取水泵终止节点 | network (query), pump (query) | - |
-| GET | `/api/v1/getpumpproperties/` | 获取水泵属性 | network (query), pump (query) | - |
-| GET | `/api/v1/getpumpschema` | 获取水泵模式 | network (query) | - |
-| POST | `/api/v1/setpumpnode1/` | 设置水泵起始节点 | network (query), pump (query), node1 (query) | - |
-| POST | `/api/v1/setpumpnode2/` | 设置水泵终止节点 | network (query), pump (query), node2 (query) | - |
-| POST | `/api/v1/setpumpproperties/` | 设置水泵属性 | network (query), pump (query) | - |
-
- 覆盖方法：`GET, POST`
-
-## 接口说明
-
-| 接口 | 说明 |
-|---|---|
-| `GET /getpumpschema` | 返回水泵（Pump）数据模型的所有字段定义 |
-| `GET /getpumpproperties/` | 查询单台水泵的所有属性（曲线名称、起终节点等） |
-| `GET /getallpumpproperties/` | 批量获取管网中所有水泵的属性列表 |
-| `POST /addpump/` | 向管网添加一台新水泵，需提供ID和起终节点 |
-| `POST /deletepump/` | 从管网删除指定水泵 |
-| `POST /setpumpproperties/` | 批量设置水泵属性（曲线、初始状态、效率等） |
-| `POST /setpumpnode1/` | 设置水泵起始节点 |
-| `POST /setpumpnode2/` | 设置水泵终止节点 |
@@ -1,69 +0,0 @@
---
-name: tjwater-action-business-network-assets-regions
-description: business/network-assets 下 regions 操作技能。
-version: 3.0.1
---
-
-# regions Action Skill
-
-## 简介
-负责 `business/network-assets` 场景下 `regions` 的具体接口调用。
-
-## 子模块索引 (渐进式引导)
- 当前为叶子节点，直接使用下方接口目录。
-
-## 接口目录
-| Method | Path | Summary | Required Params | Optional Params |
-|---|---|---|---|---|
-| POST | `/api/v1/adddistrictmeteringarea/` | 添加新DMA | network (query) | - |
-| POST | `/api/v1/addregion/` | 添加新区域 | network (query) | - |
-| POST | `/api/v1/addservicearea/` | 添加新服务区 | network (query) | - |
-| POST | `/api/v1/addvirtualdistrict/` | 添加新虚拟分区 | network (query) | - |
-| GET | `/api/v1/calculatedistrictmeteringareafornetwork/` | 计算整网DMA分区 | network (query) | - |
-| GET | `/api/v1/calculatedistrictmeteringareafornodes/` | 计算节点DMA分区 | network (query) | - |
-| GET | `/api/v1/calculatedistrictmeteringareaforregion/` | 计算区域内DMA分区 | network (query) | - |
-| GET | `/api/v1/calculateservicearea/` | 计算服务区（返回全部时间步） | network (query) | - |
-| GET | `/api/v1/calculatevirtualdistrict/` | 计算虚拟分区 | network (query), centers (query) | - |
-| POST | `/api/v1/deletedistrictmeteringarea/` | 删除DMA | network (query) | - |
-| POST | `/api/v1/deleteregion/` | 删除区域 | network (query) | - |
-| POST | `/api/v1/deleteservicearea/` | 删除服务区 | network (query) | - |
-| POST | `/api/v1/deletevirtualdistrict/` | 删除虚拟分区 | network (query) | - |
-| POST | `/api/v1/generatedistrictmeteringarea/` | 生成DMA分区 | network (query), part_count (query), part_type (query), inflate_delta (query) | - |
-| POST | `/api/v1/generateservicearea/` | 生成服务区分区 | network (query), inflate_delta (query) | - |
-| POST | `/api/v1/generatesubdistrictmeteringarea/` | 生成DMA子分区 | network (query), dma (query), part_count (query), part_type (query), inflate_delta (query) | - |
-| POST | `/api/v1/generatevirtualdistrict/` | 生成虚拟分区 | network (query), inflate_delta (query) | - |
-| GET | `/api/v1/getalldistrictmeteringareaids/` | 获取所有DMA ID | network (query) | - |
-| GET | `/api/v1/getalldistrictmeteringareas/` | 获取所有DMA | network (query) | - |
-| GET | `/api/v1/getallserviceareas/` | 获取所有服务区 | network (query) | - |
-| GET | `/api/v1/getallvirtualdistrict/` | 获取所有虚拟分区 | network (query) | - |
-| GET | `/api/v1/getdistrictmeteringarea/` | 获取DMA信息 | network (query), id (query) | - |
-| GET | `/api/v1/getdistrictmeteringareaschema/` | 获取DMA属性架构 | network (query) | - |
-| GET | `/api/v1/getregion/` | 获取区域信息 | network (query), id (query) | - |
-| GET | `/api/v1/getregionschema/` | 获取区域属性架构 | network (query) | - |
-| GET | `/api/v1/getservicearea/` | 获取服务区信息 | network (query), id (query) | - |
-| GET | `/api/v1/getserviceareaschema/` | 获取服务区属性架构 | network (query) | - |
-| GET | `/api/v1/getvirtualdistrict/` | 获取虚拟分区信息 | network (query), id (query) | - |
-| GET | `/api/v1/getvirtualdistrictschema/` | 获取虚拟分区属性架构 | network (query) | - |
-| POST | `/api/v1/setdistrictmeteringarea/` | 设置DMA属性 | network (query) | - |
-| POST | `/api/v1/setregion/` | 设置区域属性 | network (query) | - |
-| POST | `/api/v1/setservicearea/` | 设置服务区属性 | network (query) | - |
-| POST | `/api/v1/setvirtualdistrict/` | 设置虚拟分区属性 | network (query) | - |
-
- 覆盖方法：`GET, POST`
-
-## 接口说明
-
-| 接口 | 说明 |
-|---|---|
-| `GET /getregionschema` | 返回区域（Region）数据模型的字段定义 |
-| `GET /getregion/` | 查询单个区域的属性 |
-| `GET /getalldistrictmeteringareas/` | 获取所有 DMA（独立计量区）列表 |
-| `GET /getallserviceareas/` | 获取所有服务区列表 |
-| `POST /addregion/` | 新增区域（需提供名称和节点/管道列表） |
-| `POST /adddistrictmeteringarea/` | 新增 DMA 分区 |
-| `POST /addvirtualdistrict/` | 新增虚拟分区 |
-| `POST /addservicearea/` | 新增服务区 |
-| `GET /calculatedistrictmeteringareafornodes/` | 为指定节点集合计算其所属 DMA |
-| `GET /calculatedistrictmeteringareaforregion/` | 为指定区域内的所有节点计算 DMA 归属 |
-| `GET /calculatedistrictmeteringareafornetwork/` | 为整个管网的所有节点计算 DMA 归属 |
-| `GET /calculateservicearea/` | 计算服务区，返回全部时间步结果 |
@@ -1,48 +0,0 @@
---
-name: tjwater-action-business-network-assets-reservoirs
-description: business/network-assets 下 reservoirs 操作技能。
-version: 3.0.0
---
-
-# reservoirs Action Skill
-
-## 简介
-负责 `business/network-assets` 场景下 `reservoirs` 的具体接口调用。
-
-## 子模块索引 (渐进式引导)
- 当前为叶子节点，直接使用下方接口目录。
-
-## 接口目录
-| Method | Path | Summary | Required Params | Optional Params |
-|---|---|---|---|---|
-| POST | `/api/v1/addreservoir/` | 添加水库 | network (query), reservoir (query), x (query), y (query), head (query) | - |
-| POST | `/api/v1/deletereservoir/` | 删除水库 | network (query), reservoir (query) | - |
-| GET | `/api/v1/getallreservoirproperties/` | 获取所有水库属性 | network (query) | - |
-| GET | `/api/v1/getreservoircoord/` | 获取水库坐标 | network (query), reservoir (query) | - |
-| GET | `/api/v1/getreservoirhead/` | 获取水库水头 | network (query), reservoir (query) | - |
-| GET | `/api/v1/getreservoirpattern/` | 获取水库模式 | network (query), reservoir (query) | - |
-| GET | `/api/v1/getreservoirproperties/` | 获取水库属性 | network (query), reservoir (query) | - |
-| GET | `/api/v1/getreservoirschema` | 获取水库模式 | network (query) | - |
-| GET | `/api/v1/getreservoirx/` | 获取水库X坐标 | network (query), reservoir (query) | - |
-| GET | `/api/v1/getreservoiry/` | 获取水库Y坐标 | network (query), reservoir (query) | - |
-| POST | `/api/v1/setreservoircoord/` | 设置水库坐标 | network (query), reservoir (query), x (query), y (query) | - |
-| POST | `/api/v1/setreservoirhead/` | 设置水库水头 | network (query), reservoir (query), head (query) | - |
-| POST | `/api/v1/setreservoirpattern/` | 设置水库模式 | network (query), reservoir (query), pattern (query) | - |
-| POST | `/api/v1/setreservoirproperties/` | 设置水库属性 | network (query), reservoir (query) | - |
-| POST | `/api/v1/setreservoirx/` | 设置水库X坐标 | network (query), reservoir (query), x (query) | - |
-| POST | `/api/v1/setreservoiry/` | 设置水库Y坐标 | network (query), reservoir (query), y (query) | - |
-
- 覆盖方法：`GET, POST`
-
-## 接口说明
-
-| 接口 | 说明 |
-|---|---|
-| `GET /getreservoirschema` | 返回水库（Reservoir）数据模型的所有字段定义 |
-| `GET /getreservoirproperties/` | 查询单个水库的所有属性（水头、模式、坐标等） |
-| `GET /getallreservoirproperties/` | 批量获取管网中所有水库的属性列表 |
-| `GET /getreservoirhead/` | 查询水库水头（即水库水位高度） |
-| `GET /getreservoirpattern/` | 查询水库关联的时间模式名称 |
-| `POST /addreservoir/` | 向管网添加一个新水库，需提供ID、坐标和水头 |
-| `POST /deletereservoir/` | 从管网删除指定水库 |
-| `POST /setreservoir*/` | 设置水库某个具体属性（水头、模式、坐标等） |
@@ -1,32 +0,0 @@
---
-name: tjwater-action-business-network-assets-tags
-description: business/network-assets 下 tags 操作技能。
-version: 3.0.0
---
-
-# tags Action Skill
-
-## 简介
-负责 `business/network-assets` 场景下 `tags` 的具体接口调用。
-
-## 子模块索引 (渐进式引导)
- 当前为叶子节点，直接使用下方接口目录。
-
-## 接口目录
-| Method | Path | Summary | Required Params | Optional Params |
-|---|---|---|---|---|
-| GET | `/api/v1/gettag/` | 获取标签信息 | network (query), t_type (query), id (query) | - |
-| GET | `/api/v1/gettags/` | 获取所有标签 | network (query) | - |
-| GET | `/api/v1/gettagschema/` | 获取标签属性架构 | network (query) | - |
-| POST | `/api/v1/settag/` | 设置标签 | network (query) | - |
-
- 覆盖方法：`GET, POST`
-
-## 接口说明
-
-| 接口 | 说明 |
-|---|---|
-| `GET /gettagschema/` | 返回标签（Tag）数据模型的字段定义 |
-| `GET /gettag/` | 查询单个元素绑定的标签信息 |
-| `GET /gettags/` | 获取管网中所有标签列表 |
-| `POST /settag/` | 为管网元素设置/更新标签（支持自定义键值对属性） |
@@ -1,61 +0,0 @@
---
-name: tjwater-action-business-network-assets-tanks
-description: business/network-assets 下 tanks 操作技能。
-version: 3.0.0
---
-
-# tanks Action Skill
-
-## 简介
-负责 `business/network-assets` 场景下 `tanks` 的具体接口调用。
-
-## 子模块索引 (渐进式引导)
- 当前为叶子节点，直接使用下方接口目录。
-
-## 接口目录
-| Method | Path | Summary | Required Params | Optional Params |
-|---|---|---|---|---|
-| POST | `/api/v1/addtank/` | 新增水箱 | network (query), tank (query), x (query), y (query), elevation (query) | init_level (query), min_level (query), max_level (query), diameter (query), min_vol (query) |
-| POST | `/api/v1/deletetank/` | 删除水箱 | network (query), tank (query) | - |
-| GET | `/api/v1/getalltankproperties/` | 获取所有水箱属性 | network (query) | - |
-| GET | `/api/v1/gettankcoord/` | 获取水箱坐标 | network (query), tank (query) | - |
-| GET | `/api/v1/gettankdiameter/` | 获取水箱直径 | network (query), tank (query) | - |
-| GET | `/api/v1/gettankelevation/` | 获取水箱标高 | network (query), tank (query) | - |
-| GET | `/api/v1/gettankinitlevel/` | 获取水箱初始水位 | network (query), tank (query) | - |
-| GET | `/api/v1/gettankmaxlevel/` | 获取水箱最大水位 | network (query), tank (query) | - |
-| GET | `/api/v1/gettankminlevel/` | 获取水箱最小水位 | network (query), tank (query) | - |
-| GET | `/api/v1/gettankminvol/` | 获取水箱最小体积 | network (query), tank (query) | - |
-| GET | `/api/v1/gettankoverflow/` | 获取水箱溢流口 | network (query), tank (query) | - |
-| GET | `/api/v1/gettankproperties/` | 获取水箱属性 | network (query), tank (query) | - |
-| GET | `/api/v1/gettankschema` | 获取水箱模式 | network (query) | - |
-| GET | `/api/v1/gettankvolcurve/` | 获取水箱容积曲线 | network (query), tank (query) | - |
-| GET | `/api/v1/gettankx/` | 获取水箱X坐标 | network (query), tank (query) | - |
-| GET | `/api/v1/gettanky/` | 获取水箱Y坐标 | network (query), tank (query) | - |
-| POST | `/api/v1/settankcoord/` | 设置水箱坐标 | network (query), tank (query), x (query), y (query) | - |
-| POST | `/api/v1/settankdiameter/` | 设置水箱直径 | network (query), tank (query), diameter (query) | - |
-| POST | `/api/v1/settankelevation/` | 设置水箱标高 | network (query), tank (query), elevation (query) | - |
-| POST | `/api/v1/settankinitlevel/` | 设置水箱初始水位 | network (query), tank (query), init_level (query) | - |
-| POST | `/api/v1/settankmaxlevel/` | 设置水箱最大水位 | network (query), tank (query), max_level (query) | - |
-| POST | `/api/v1/settankminlevel/` | 设置水箱最小水位 | network (query), tank (query), min_level (query) | - |
-| POST | `/api/v1/settankminvol/` | 设置水箱最小体积 | network (query), tank (query), min_vol (query) | - |
-| POST | `/api/v1/settankoverflow/` | 设置水箱溢流口 | network (query), tank (query), overflow (query) | - |
-| POST | `/api/v1/settankproperties/` | 设置水箱属性 | network (query), tank (query) | - |
-| POST | `/api/v1/settankvolcurve/` | 设置水箱容积曲线 | network (query), tank (query), vol_curve (query) | - |
-| POST | `/api/v1/settankx/` | 设置水箱X坐标 | network (query), tank (query), x (query) | - |
-| POST | `/api/v1/settanky/` | 设置水箱Y坐标 | network (query), tank (query), y (query) | - |
-
- 覆盖方法：`GET, POST`
-
-## 接口说明
-
-| 接口 | 说明 |
-|---|---|
-| `GET /gettankschema` | 返回水箱（Tank）数据模型的所有字段定义 |
-| `GET /gettankproperties/` | 查询单个水箱的所有属性（标高、直径、初始/最大/最小水位等） |
-| `GET /getalltankproperties/` | 批量获取管网中所有水箱的属性列表 |
-| `GET /gettankelevation/` | 查询水箱底部标高 |
-| `GET /gettankdiameter/` | 查询水箱直径 |
-| `GET /gettankinitlevel/` | 查询水箱初始水位 |
-| `POST /addtank/` | 向管网添加一个新水箱，需提供ID、坐标、标高和水位参数 |
-| `POST /deletetank/` | 从管网删除指定水箱 |
-| `POST /settank*/` | 设置水箱某个具体属性（坐标、标高、直径、水位等） |
@@ -1,50 +0,0 @@
---
-name: tjwater-action-business-network-assets-valves
-description: business/network-assets 下 valves 操作技能。
-version: 3.0.0
---
-
-# valves Action Skill
-
-## 简介
-负责 `business/network-assets` 场景下 `valves` 的具体接口调用。
-
-## 子模块索引 (渐进式引导)
- 当前为叶子节点，直接使用下方接口目录。
-
-## 接口目录
-| Method | Path | Summary | Required Params | Optional Params |
-|---|---|---|---|---|
-| POST | `/api/v1/addvalve/` | 添加阀门 | network (query), valve (query), node1 (query), node2 (query) | diameter (query), v_type (query), setting (query), minor_loss (query) |
-| POST | `/api/v1/deletevalve/` | 删除阀门 | network (query), valve (query) | - |
-| GET | `/api/v1/getallvalveproperties/` | 获取所有阀门属性 | network (query) | - |
-| GET | `/api/v1/getvalvediameter/` | 获取阀门直径 | network (query), valve (query) | - |
-| GET | `/api/v1/getvalveminorloss/` | 获取阀门损失系数 | network (query), valve (query) | - |
-| GET | `/api/v1/getvalvenode1/` | 获取阀门起点节点 | network (query), valve (query) | - |
-| GET | `/api/v1/getvalvenode2/` | 获取阀门终点节点 | network (query), valve (query) | - |
-| GET | `/api/v1/getvalveproperties/` | 获取阀门所有属性 | network (query), valve (query) | - |
-| GET | `/api/v1/getvalveschema` | 获取阀门架构 | network (query) | - |
-| GET | `/api/v1/getvalvesetting/` | 获取阀门开度 | network (query), valve (query) | - |
-| GET | `/api/v1/getvalvetype/` | 获取阀门类型 | network (query), valve (query) | - |
-| POST | `/api/v1/setvalvenode1/` | 设置阀门起点节点 | network (query), valve (query), node1 (query) | - |
-| POST | `/api/v1/setvalvenode2/` | 设置阀门终点节点 | network (query), valve (query), node2 (query) | - |
-| POST | `/api/v1/setvalvenodediameter/` | 设置阀门直径 | network (query), valve (query), diameter (query) | - |
-| POST | `/api/v1/setvalveproperties/` | 批量设置阀门属性 | network (query), valve (query) | - |
-| POST | `/api/v1/setvalvesetting/` | 设置阀门开度 | network (query), valve (query), setting (query) | - |
-| POST | `/api/v1/setvalvetype/` | 设置阀门类型 | network (query), valve (query), type (query) | - |
-
- 覆盖方法：`GET, POST`
-
-## 接口说明
-
-| 接口 | 说明 |
-|---|---|
-| `GET /getvalveschema` | 返回阀门（Valve）数据模型的所有字段定义 |
-| `GET /getvalveproperties/` | 查询单个阀门的所有属性（管径、类型、设定值等） |
-| `GET /getallvalveproperties/` | 批量获取管网中所有阀门的属性列表 |
-| `GET /getvalvediameter/` | 查询阀门管径 |
-| `GET /getvalvetype/` | 查询阀门类型（PRV/PSV/TCV/FCV/PBV/GPV） |
-| `GET /getvalvesetting/` | 查询阀门设定值（压力设定或流量设定） |
-| `POST /addvalve/` | 向管网添加一个新阀门，需提供ID、起终节点、管径和类型 |
-| `POST /deletevalve/` | 从管网删除指定阀门 |
-| `POST /setvalve*/` | 设置阀门某个具体属性（类型、设定值、管径等） |
@@ -1,19 +0,0 @@
---
-name: tjwater-scenario-business-project-workspace
-description: 负责项目空间、快照与扩展操作。
-version: 3.0.0
---
-
-# project-workspace Scenario Skill
-
-## 简介
-负责项目空间、快照与扩展操作。
-
-## 子模块索引 (渐进式引导)
- **extension**: 见 `./extension/SKILL.md`
- **misc**: 见 `./misc/SKILL.md`
- **project**: 见 `./project/SKILL.md`
- **project_data**: 见 `./project_data/SKILL.md`
- **schemes**: 见 `./schemes/SKILL.md`
- **snapshots**: 见 `./snapshots/SKILL.md`
-
@@ -1,32 +0,0 @@
---
-name: tjwater-action-business-project-workspace-extension
-description: business/project-workspace 下 extension 操作技能。
-version: 3.0.0
---
-
-# extension Action Skill
-
-## 简介
-负责 `business/project-workspace` 场景下 `extension` 的具体接口调用。
-
-## 子模块索引 (渐进式引导)
- 当前为叶子节点，直接使用下方接口目录。
-
-## 接口目录
-| Method | Path | Summary | Required Params | Optional Params |
-|---|---|---|---|---|
-| GET | `/api/v1/getallextensiondata/` | 获取所有扩展数据 | network (query) | - |
-| GET | `/api/v1/getallextensiondatakeys/` | 获取所有扩展数据键 | network (query) | - |
-| GET | `/api/v1/getextensiondata/` | 获取指定扩展数据 | network (query), key (query) | - |
-| POST | `/api/v1/setextensiondata/` | 设置扩展数据 | network (query) | - |
-
- 覆盖方法：`GET, POST`
-
-## 接口说明
-
-| 接口 | 说明 |
-|---|---|
-| `GET /getallextensiondatakeys/` | 获取当前管网中所有已存储的自定义扩展数据的键名列表 |
-| `GET /getallextensiondata/` | 获取当前管网所有自定义扩展数据（键值对集合） |
-| `GET /getextensiondata/` | 按 key 查询指定的自定义扩展数据值 |
-| `POST /setextensiondata/` | 设置或更新一个自定义扩展数据键值对（可用于存储任意业务自定义信息） |
@@ -1,36 +0,0 @@
---
-name: tjwater-action-business-project-workspace-misc
-description: business/project-workspace 下 misc 操作技能。
-version: 3.0.0
---
-
-# misc Action Skill
-
-## 简介
-负责 `business/project-workspace` 场景下 `misc` 的具体接口调用。
-
-## 子模块索引 (渐进式引导)
- 当前为叶子节点，直接使用下方接口目录。
-
-## 接口目录
-| Method | Path | Summary | Required Params | Optional Params |
-|---|---|---|---|---|
-| GET | `/api/v1/getallburstlocateresults/` | 获取所有爆管定位结果 | network (query) | - |
-| GET | `/api/v1/getallsensorplacements/` | 获取所有传感器位置 | network (query) | - |
-| GET | `/api/v1/getjson/` | 获取JSON示例 | - | - |
-| GET | `/api/v1/getrealtimedata/` | 获取实时数据 | - | - |
-| GET | `/api/v1/getsimulationresult/` | 获取模拟结果 | - | - |
-| POST | `/api/v1/test_dict/` | 测试字典处理 | data (body) | - |
-
- 覆盖方法：`GET, POST`
-
-## 接口说明
-
-| 接口 | 说明 |
-|---|---|
-| `GET /getallburstlocateresults/` | 获取当前管网所有历史爆管定位分析结果（旧版接口） |
-| `GET /getallsensorplacements/` | 获取当前管网所有传感器布置方案的结果列表 |
-| `GET /getsimulationresult/` | 获取最近一次水力模拟结果（旧版接口） |
-| `GET /getrealtimedata/` | 获取管网实时监测数据（旧版接口） |
-| `GET /getjson/` | 返回示例 JSON 数据结构，用于开发调试 |
-| `POST /test_dict/` | 测试字典类型请求体的接口，用于开发调试 |
@@ -1,32 +0,0 @@
---
-name: tjwater-action-business-project-workspace-project-data
-description: business/project-workspace 下 project_data 操作技能。
-version: 3.0.0
---
-
-# project_data Action Skill
-
-## 简介
-负责 `business/project-workspace` 场景下 `project_data` 的具体接口调用。
-
-## 子模块索引 (渐进式引导)
- 当前为叶子节点，直接使用下方接口目录。
-
-## 接口目录
-| Method | Path | Summary | Required Params | Optional Params |
-|---|---|---|---|---|
-| GET | `/api/v1/burst-locate-result` | 获取爆管定位结果 | - | - |
-| GET | `/api/v1/burst-locate-result/{burst_incident}` | 按事件查询爆管定位结果 | burst_incident (path) | - |
-| GET | `/api/v1/scada-info` | 获取SCADA信息 | - | - |
-| GET | `/api/v1/scheme-list` | 获取方案列表 | - | - |
-
- 覆盖方法：`GET`
-
-## 接口说明
-
-| 接口 | 说明 |
-|---|---|
-| `GET /burst-locate-result` | 获取所有爆管定位事件的历史结果列表（新版REST接口） |
-| `GET /burst-locate-result/{burst_incident}` | 查询指定爆管事件（burst_incident ID）的详细定位结果 |
-| `GET /scada-info` | 获取当前项目关联的 SCADA 设备和监测点信息汇总 |
-| `GET /scheme-list` | 获取当前项目中所有可用的水力计算方案列表 |
@@ -1,55 +0,0 @@
---
-name: tjwater-action-business-project-workspace-project
-description: business/project-workspace 下 project 操作技能。
-version: 3.0.0
---
-
-# project Action Skill
-
-## 简介
-负责 `business/project-workspace` 场景下 `project` 的具体接口调用。
-
-## 子模块索引 (渐进式引导)
- 当前为叶子节点，直接使用下方接口目录。
-
-## 接口目录
-| Method | Path | Summary | Required Params | Optional Params |
-|---|---|---|---|---|
-| GET | `/api/v1/listprojects/` | 获取项目列表 | - | - |
-| GET | `/api/v1/project_info/` | 获取项目信息 | network (query) | - |
-| GET | `/api/v1/haveproject/` | 检查项目是否存在 | network (query) | - |
-| POST | `/api/v1/createproject/` | 创建新项目 | network (query) | - |
-| POST | `/api/v1/deleteproject/` | 删除项目 | network (query) | - |
-| POST | `/api/v1/copyproject/` | 复制项目 | source (query), target (query) | - |
-| GET | `/api/v1/isprojectopen/` | 检查项目是否已打开 | network (query) | - |
-| POST | `/api/v1/openproject/` | 打开项目 | network (query) | - |
-| POST | `/api/v1/closeproject/` | 关闭项目 | network (query) | - |
-| GET | `/api/v1/isprojectlocked/` | 检查项目是否被锁定 | network (query) | - |
-| GET | `/api/v1/isprojectlockedbyme/` | 检查项目是否被当前用户锁定 | network (query) | - |
-| POST | `/api/v1/lockproject/` | 锁定项目 | network (query) | - |
-| POST | `/api/v1/unlockproject/` | 解锁项目 | network (query) | - |
-| POST | `/api/v1/importinp/` | 导入 INP 文件内容 | network (query) | - |
-| GET | `/api/v1/exportinp/` | 导出项目为 ChangeSet | network (query), version (query) | - |
-| POST | `/api/v1/readinp/` | 读取 INP 文件到项目 | network (query), inp (query) | - |
-| GET | `/api/v1/dumpinp/` | 导出项目到 INP 文件 | network (query), inp (query) | - |
-| POST | `/api/v1/uploadinp/` | 上传 INP 文件 | afile (body), name (query) | - |
-| GET | `/api/v1/downloadinp/` | 下载 INP 文件 | name (query) | - |
-| GET | `/api/v1/convertv3tov2/` | 转换 INP V3 为 V2 | - | - |
-
- 覆盖方法：`GET, POST`
-
-## 接口说明
-
-| 接口 | 说明 |
-|---|---|
-| `GET /listprojects/` | 获取服务器上所有可用的供水管网项目名称列表 |
-| `GET /project_info/` | 从数据库获取项目的详细信息，包括地图范围等配置 |
-| `POST /createproject/` | 创建一个新的供水管网项目；若已存在可能覆盖或报错 |
-| `POST /deleteproject/` | 永久删除指定项目，此操作不可恢复 |
-| `POST /openproject/` | 将指定项目加载到内存并初始化数据库连接池 |
-| `POST /closeproject/` | 将指定项目从内存中卸载，释放相关资源 |
-| `POST /lockproject/` | 锁定项目以防止并发修改 |
-| `POST /unlockproject/` | 释放对项目的锁定 |
-| `POST /importinp/` | 将 INP 格式文本内容导入到指定项目 |
-| `GET /exportinp/` | 导出项目变更集（ChangeSet），含顶点、SCADA元素、DMA、SA、VD等 |
-| `GET /convertv3tov2/` | 将 EPANET 3.0 格式的 INP 内容转换为 2.x 格式 |
@@ -1,30 +0,0 @@
---
-name: tjwater-action-business-project-workspace-schemes
-description: business/project-workspace 下 schemes 操作技能。
-version: 3.0.0
---
-
-# schemes Action Skill
-
-## 简介
-负责 `business/project-workspace` 场景下 `schemes` 的具体接口调用。
-
-## 子模块索引 (渐进式引导)
- 当前为叶子节点，直接使用下方接口目录。
-
-## 接口目录
-| Method | Path | Summary | Required Params | Optional Params |
-|---|---|---|---|---|
-| GET | `/api/v1/getallschemes/` | 获取所有方案 | network (query) | - |
-| GET | `/api/v1/getscheme/` | 获取单个方案 | network (query), schema_name (query) | - |
-| GET | `/api/v1/getschemeschema/` | 获取方案模式 | network (query) | - |
-
- 覆盖方法：`GET`
-
-## 接口说明
-
-| 接口 | 说明 |
-|---|---|
-| `GET /getschemeschema/` | 返回方案（Scheme）数据模型的字段定义 |
-| `GET /getallschemes/` | 获取当前管网下所有已保存方案的列表 |
-| `GET /getscheme/` | 查询指定方案名称（schema_name）的详细属性和配置 |
@@ -1,54 +0,0 @@
---
-name: tjwater-action-business-project-workspace-snapshots
-description: business/project-workspace 下 snapshots 操作技能。
-version: 3.0.0
---
-
-# snapshots Action Skill
-
-## 简介
-负责 `business/project-workspace` 场景下 `snapshots` 的具体接口调用。
-
-## 子模块索引 (渐进式引导)
- 当前为叶子节点，直接使用下方接口目录。
-
-## 接口目录
-| Method | Path | Summary | Required Params | Optional Params |
-|---|---|---|---|---|
-| POST | `/api/v1/batch/` | 执行批量命令 | network (query) | - |
-| POST | `/api/v1/compressedbatch/` | 执行压缩批量命令 | network (query) | - |
-| GET | `/api/v1/getcurrentoperationid/` | 获取当前操作ID | network (query) | - |
-| GET | `/api/v1/getrestoreoperation/` | 获取恢复操作ID | network (query) | - |
-| GET | `/api/v1/getsnapshots/` | 获取快照列表 | network (query) | - |
-| GET | `/api/v1/havesnapshot/` | 检查快照是否存在 | network (query), tag (query) | - |
-| GET | `/api/v1/havesnapshotforcurrentoperation/` | 检查当前操作快照是否存在 | network (query) | - |
-| GET | `/api/v1/havesnapshotforoperation/` | 检查操作快照是否存在 | network (query), operation (query) | - |
-| POST | `/api/v1/pickoperation/` | 选择操作 | network (query), operation (query) | discard (query) |
-| POST | `/api/v1/picksnapshot/` | 选择快照 | network (query), tag (query) | discard (query) |
-| POST | `/api/v1/redo/` | 重做操作 | network (query) | - |
-| POST | `/api/v1/setrestoreoperation/` | 设置恢复操作ID | network (query), operation (query) | - |
-| GET | `/api/v1/syncwithserver/` | 与服务器同步 | network (query), operation (query) | - |
-| POST | `/api/v1/takenapshotforcurrentoperation` | 为当前操作创建快照（兼容模式） | network (query), tag (query) | - |
-| POST | `/api/v1/takesnapshot/` | 创建快照 | network (query), tag (query) | - |
-| POST | `/api/v1/takesnapshotforcurrentoperation` | 为当前操作创建快照 | network (query), tag (query) | - |
-| POST | `/api/v1/takesnapshotforoperation/` | 为操作创建快照 | network (query), operation (query), tag (query) | - |
-| POST | `/api/v1/undo/` | 撤销操作 | network (query) | - |
-
- 覆盖方法：`GET, POST`
-
-## 接口说明
-
-| 接口 | 说明 |
-|---|---|
-| `GET /getsnapshots/` | 列出当前管网所有已保存的快照标签（tag）列表 |
-| `GET /havesnapshot/` | 检查指定 tag 的快照是否存在 |
-| `POST /takesnapshot/` | 保存当前管网状态为一个快照，tag 为快照名称 |
-| `POST /picksnapshot/` | 将管网状态回滚到指定快照，discard=true 时丢弃当前未保存修改 |
-| `GET /getcurrentoperationid/` | 获取当前管网的操作ID（用于追踪操作历史） |
-| `POST /undo/` | 撤销对管网的最近一次操作 |
-| `POST /redo/` | 重做上一次被撤销的操作 |
-| `POST /batch/` | 批量执行多个管网操作命令（原子事务） |
-| `POST /compressedbatch/` | 执行压缩格式的批量命令（减少网络传输量） |
-| `GET /syncwithserver/` | 将客户端的操作与服务端管网状态同步 |
-| `POST /pickoperation/` | 切换到指定 operation ID 的历史操作状态 |
-| `POST /takesnapshotforcurrentoperation` | 为当前 operation 创建快照（保存当前操作节点状态） |
@@ -1,14 +0,0 @@
---
-name: tjwater-domain-data
-description: 负责时序数据访问与读写能力。
-version: 3.0.0
---
-
-# Data Domain Skill
-
-## 简介
-负责时序数据访问与读写能力。
-
-## 子模块索引 (渐进式引导)
- **timeseries-access**: 见 `./timeseries-access/SKILL.md`
-
@@ -1,16 +0,0 @@
---
-name: tjwater-scenario-data-timeseries-access
-description: 负责时序数据查询、写入与聚合。
-version: 3.0.0
---
-
-# timeseries-access Scenario Skill
-
-## 简介
-负责时序数据查询、写入与聚合。
-
-## 子模块索引 (渐进式引导)
- **composite**: 见 `./composite/SKILL.md`
- **realtime**: 见 `./realtime/SKILL.md`
- **scheme**: 见 `./scheme/SKILL.md`
-
@@ -1,34 +0,0 @@
---
-name: tjwater-action-data-timeseries-access-composite
-description: data/timeseries-access 下 composite 操作技能。
-version: 3.0.0
---
-
-# composite Action Skill
-
-## 简介
-负责 `data/timeseries-access` 场景下 `composite` 的具体接口调用。
-
-## 子模块索引 (渐进式引导)
- 当前为叶子节点，直接使用下方接口目录。
-
-## 接口目录
-| Method | Path | Summary | Required Params | Optional Params |
-|---|---|---|---|---|
-| POST | `/api/v1/composite/clean-scada` | 清洗SCADA监测数据 | device_ids (query), start_time (query), end_time (query) | - |
-| GET | `/api/v1/composite/element-scada` | 获取管网元素关联的SCADA监测数据 | element_id (query), start_time (query), end_time (query) | use_cleaned (query) |
-| GET | `/api/v1/composite/element-simulation` | 获取管网元素的模拟数据 | start_time (query), end_time (query), feature_infos (query) | scheme_type (query), scheme_name (query) |
-| GET | `/api/v1/composite/pipeline-health-prediction` | 预测管道健康状况 | query_time (query), network_name (query) | - |
-| GET | `/api/v1/composite/scada-simulation` | 获取SCADA关联的模拟数据 | start_time (query), end_time (query), device_ids (query) | scheme_type (query), scheme_name (query) |
-
- 覆盖方法：`GET, POST`
-
-## 接口说明
-
-| 接口 | 说明 |
-|---|---|
-| `GET /composite/scada-simulation` | 将 SCADA 设备历史监测数据与水力模拟结果对齐返回，便于压差分析 |
-| `GET /composite/element-simulation` | 按管网元素ID和属性类型查询该元素在某方案下的模拟时序数据 |
-| `GET /composite/element-scada` | 查询某管网元素关联的 SCADA 设备的历史监测时序数据，支持使用清洗后数据（use_cleaned） |
-| `POST /composite/clean-scada` | 对指定设备在指定时间段的 SCADA 数据进行清洗处理（去噪、异常值替换） |
-| `GET /composite/pipeline-health-prediction` | 在指定时刻对整个管网的管道健康状态进行预测，返回各管道健康评分 |
@@ -1,44 +0,0 @@
---
-name: tjwater-action-data-timeseries-access-realtime
-description: data/timeseries-access 下 realtime 操作技能。
-version: 3.0.0
---
-
-# realtime Action Skill
-
-## 简介
-负责 `data/timeseries-access` 场景下 `realtime` 的具体接口调用。
-
-## 子模块索引 (渐进式引导)
- 当前为叶子节点，直接使用下方接口目录。
-
-## 接口目录
-| Method | Path | Summary | Required Params | Optional Params |
-|---|---|---|---|---|
-| DELETE | `/api/v1/realtime/links` | 删除实时管道数据 | start_time (query), end_time (query) | - |
-| GET | `/api/v1/realtime/links` | 查询实时管道数据 | start_time (query), end_time (query) | - |
-| POST | `/api/v1/realtime/links/batch` | 批量插入实时管道数据 | data (body) | - |
-| PATCH | `/api/v1/realtime/links/{link_id}/field` | 更新实时管道字段 | link_id (path), time (query), field (query), value (query) | - |
-| DELETE | `/api/v1/realtime/nodes` | 删除实时节点数据 | start_time (query), end_time (query) | - |
-| GET | `/api/v1/realtime/nodes` | 查询实时节点数据 | start_time (query), end_time (query) | - |
-| POST | `/api/v1/realtime/nodes/batch` | 批量插入实时节点数据 | data (body) | - |
-| GET | `/api/v1/realtime/query/by-id-time` | 按ID和时间查询实时模拟数据 | id (query), type (query), query_time (query) | - |
-| GET | `/api/v1/realtime/query/by-time-property` | 按时间和属性查询实时数据 | query_time (query), type (query), property (query) | - |
-| POST | `/api/v1/realtime/simulation/store` | 存储实时模拟结果 | node_result_list (body), link_result_list (body), result_start_time (query) | - |
-
- 覆盖方法：`DELETE, GET, PATCH, POST`
-
-## 接口说明
-
-| 接口 | 说明 |
-|---|---|
-| `POST /realtime/links/batch` | 批量将管道（link）模拟结果写入实时数据表（TimescaleDB） |
-| `GET /realtime/links` | 查询指定时间范围内的实时管道模拟数据 |
-| `DELETE /realtime/links` | 删除指定时间范围内的实时管道数据 |
-| `PATCH /realtime/links/{link_id}/field` | 修改某条管道在特定时刻的某个字段值 |
-| `POST /realtime/nodes/batch` | 批量将节点模拟结果写入实时数据表 |
-| `GET /realtime/nodes` | 查询指定时间范围内的实时节点模拟数据 |
-| `DELETE /realtime/nodes` | 删除指定时间范围内的实时节点数据 |
-| `POST /realtime/simulation/store` | 一次性存储一次完整模拟运行的节点和管道结果（含起始时间） |
-| `GET /realtime/query/by-time-property` | 按查询时间点和属性名（如 pressure/flow）查询全网实时模拟值 |
-| `GET /realtime/query/by-id-time` | 按单个元素ID、类型和时间点查询其实时模拟值 |
@@ -1,48 +0,0 @@
---
-name: tjwater-action-data-timeseries-access-scheme
-description: data/timeseries-access 下 scheme 操作技能。
-version: 3.0.0
---
-
-# scheme Action Skill
-
-## 简介
-负责 `data/timeseries-access` 场景下 `scheme` 的具体接口调用。
-
-## 子模块索引 (渐进式引导)
- 当前为叶子节点，直接使用下方接口目录。
-
-## 接口目录
-| Method | Path | Summary | Required Params | Optional Params |
-|---|---|---|---|---|
-| DELETE | `/api/v1/scheme/links` | 删除方案管道数据 | scheme_type (query), scheme_name (query), start_time (query), end_time (query) | - |
-| GET | `/api/v1/scheme/links` | 查询方案管道数据 | scheme_type (query), scheme_name (query), start_time (query), end_time (query) | - |
-| POST | `/api/v1/scheme/links/batch` | 批量插入方案管道数据 | data (body) | - |
-| GET | `/api/v1/scheme/links/{link_id}/field` | 查询方案管道字段数据 | link_id (path), scheme_type (query), scheme_name (query), start_time (query), end_time (query), field (query) | - |
-| PATCH | `/api/v1/scheme/links/{link_id}/field` | 更新方案管道字段 | link_id (path), scheme_type (query), scheme_name (query), time (query), field (query), value (query) | - |
-| DELETE | `/api/v1/scheme/nodes` | 删除方案节点数据 | scheme_type (query), scheme_name (query), start_time (query), end_time (query) | - |
-| POST | `/api/v1/scheme/nodes/batch` | 批量插入方案节点数据 | data (body) | - |
-| GET | `/api/v1/scheme/nodes/{node_id}/field` | 查询方案节点字段数据 | node_id (path), scheme_type (query), scheme_name (query), start_time (query), end_time (query), field (query) | - |
-| PATCH | `/api/v1/scheme/nodes/{node_id}/field` | 更新方案节点字段 | node_id (path), scheme_type (query), scheme_name (query), time (query), field (query), value (query) | - |
-| GET | `/api/v1/scheme/query/by-id-time` | 按ID和时间查询方案模拟数据 | scheme_type (query), scheme_name (query), id (query), type (query), query_time (query) | - |
-| GET | `/api/v1/scheme/query/by-scheme-time-property` | 按方案、时间和属性查询数据 | scheme_type (query), scheme_name (query), query_time (query), type (query), property (query) | - |
-| POST | `/api/v1/scheme/simulation/store` | 存储方案模拟结果 | scheme_type (query), scheme_name (query), node_result_list (body), link_result_list (body), result_start_time (query) | - |
-
- 覆盖方法：`DELETE, GET, PATCH, POST`
-
-## 接口说明
-
-| 接口 | 说明 |
-|---|---|
-| `POST /scheme/links/batch` | 批量将管道模拟结果写入指定方案（scheme_type + scheme_name）的数据表 |
-| `GET /scheme/links` | 查询指定方案和时间范围内的所有管道模拟数据 |
-| `DELETE /scheme/links` | 删除指定方案和时间范围内的管道模拟数据 |
-| `GET /scheme/links/{link_id}/field` | 查询特定管道在指定方案和时间范围内某字段的时序数据 |
-| `PATCH /scheme/links/{link_id}/field` | 修改特定管道在指定方案某时刻的某个字段值 |
-| `POST /scheme/nodes/batch` | 批量将节点模拟结果写入指定方案的数据表 |
-| `GET /scheme/nodes/{node_id}/field` | 查询特定节点在指定方案和时间范围内某字段的时序数据 |
-| `PATCH /scheme/nodes/{node_id}/field` | 修改特定节点在指定方案某时刻的某个字段值 |
-| `DELETE /scheme/nodes` | 删除指定方案和时间范围内的节点模拟数据 |
-| `POST /scheme/simulation/store` | 一次性存储完整方案模拟结果（节点 + 管道），需提供 scheme_type 和 scheme_name |
-| `GET /scheme/query/by-id-time` | 按元素ID、类型和时间点查询该元素在指定方案下的模拟值 |
-| `GET /scheme/query/by-scheme-time-property` | 按方案、时间点和属性名查询全网在指定方案下的模拟值 |
@@ -1,191 +1,101 @@
-# 示例（基于 opencode Agent chat/stream 工具调用链）
+# 示例（基于 opencode Agent + tjwater-cli 工具调用链）

-## 示例 1：前端发起对话，opencode agent 触发工具调用
+## 示例 1：简单查询 SCADA 数据

 用户意图：查询设备 `170490` 在时间范围内的 `monitored_value`。

-前端调用 `POST /api/v1/agent/chat/stream`：
+opencode agent 调用 `tjwater_cli`：

 ```json
 {
-  "message": "请查询设备170490在最近24小时的monitored_value历史数据",
-  "session_id": "agent-demo-001"
+  "reason": "查询设备170490在最近24小时的monitored_value数据",
+  "command": "data timeseries scada query --device-id 170490 --field monitored_value --start-time 2026-03-29T07:57:47+08:00 --end-time 2026-03-30T07:57:47+08:00"
 }
 ```

-请求头至少包含（由前端传入）：
- `Authorization: Bearer <token>`
- `x-project-id: <project-id>`
+## 示例 2：工作流 — 模拟诊断

-服务端内部行为：
- 持续通过 SSE `progress` 输出处理阶段，例如“正在规划分析步骤”“正在调用后端数据查询”
- opencode agent 选择工具 `dynamic_http_call`
- 工具参数示例：
-```json
-{
-  "path": "/api/v1/scada/by-ids-field-time-range",
-  "method": "GET",
-  "arguments": {
-    "device_ids": "170490",
-    "field": "monitored_value",
-    "start_time": "2026-03-29T07:57:47.338Z",
-    "end_time": "2026-03-30T07:57:47.338Z"
-  }
-}
-```
-
-## 示例 2：opencode agent 多步规划 + 多次工具调用
-
-用户消息：
- “先查这个设备历史数据，再给我异常点摘要。”
+用户消息："跑一下水力计算看看管网有什么问题"

 典型链路：
- 第一步工具调用：查询历史数据接口。
- 第二步（可选）工具调用：查询补充数据接口。
- opencode agent 汇总工具结果，持续通过 SSE 输出 `progress` 与 `token`，最终返回 `done`。
+1. agent 加载 workflow `simulation-diagnosis`
+2. 执行 `tjwater_cli(command="simulation run --start-time ... --duration 30")`
+3. 执行 `tjwater_cli(command="data timeseries realtime links --start-time ... --end-time ...")`
+4. 执行 `tjwater_cli(command="data timeseries realtime nodes --start-time ... --end-time ...")`
+5. 将结果写入 JSON，运行 `python scripts/diagnose_simulation.py result.json`
+6. 解读脚本输出，组织 Markdown 报告

-`progress` 示例：
+## 示例 3：前端工具 — 地图定位

+用户消息："帮我找到管道 P-001 和 P-002"
+
+opencode agent 直接调用前端工具 `locate_features`：
 ```json
 {
-  "session_id": "agent-demo-001",
-  "id": "tool-dynamic-http",
-  "phase": "tool",
-  "status": "running",
-  "title": "正在调用后端数据查询"
-}
-```
-
-## 示例 3：前端工具 — 定位要素
-
-用户消息：
- "帮我找到管道 P-001 和 P-002"
-
-opencode agent 调用工具 `locate_features`：
-```json
-{
+  "reason": "在地图上定位用户请求的管道",
  "ids": ["P-001", "P-002"],
  "feature_type": "pipe"
 }
 ```

-前端收到 SSE 事件后缩放地图并高亮管道。opencode agent 回复文字："已在地图上定位到管道 P-001 和 P-002。"
+## 示例 4：对话内图表

-## 示例 4：前端工具 — 对话内图表
-
-用户消息：
- "展示节点 J-001 最近一天的压力变化曲线"
+用户消息："展示节点 J-001 最近一天的压力变化曲线"

 典型链路：
-1. opencode agent 先调用 `dynamic_http_call` 查询数据
-2. 拿到数据后，调用 `show_chart` 将处理好的数据传给前端渲染
+1. `tjwater_cli(command="data timeseries realtime nodes --start-time ... --end-time ... --node-ids J-001")`
+2. 处理返回的 pressure 数据为 x_data + series 格式
+3. 调用 `show_chart` 渲染 ECharts 图表

-第一步 — opencode agent 调用 `dynamic_http_call`：
-```json
-{
-  "path": "/api/v1/composite/element-simulation",
-  "method": "GET",
-  "arguments": {
-    "feature_infos": "[\"J-001\", \"node\"]",
-    "start_time": "2026-03-29T00:00:00Z",
-    "end_time": "2026-03-30T00:00:00Z"
-  }
-}
-```
+## 示例 5：前端工具 — SCADA 监测面板

-第二步 — opencode agent 处理数据后调用 `show_chart`：
-```json
-{
-  "title": "节点 J-001 压力变化",
-  "chart_type": "line",
-  "x_data": ["03-29 00:00", "03-29 01:00", "03-29 02:00", "..."],
-  "series": [
-    {
-      "name": "J-001 压力",
-      "data": [32.5, 31.8, 30.2, "..."]
-    }
-  ],
-  "y_axis_name": "压力 (m)"
-}
-```
-
-前端直接用 AI 提供的数据渲染 ECharts 图表，不再请求后端。
-
-## 示例 5：前端工具 — 查看 SCADA 监测面板
-
-用户消息：
- "我想看看 J-001 的监测数据"
+用户消息："我想看看 J-001 的监测数据"

 opencode agent 调用工具 `view_scada`：
 ```json
 {
+  "reason": "打开J-001的SCADA监测面板",
  "device_ids": ["J-001"],
-  "start_time": "2026-03-29T00:00:00Z",
-  "end_time": "2026-03-30T00:00:00Z"
+  "start_time": "2026-03-29T00:00:00+08:00",
+  "end_time": "2026-03-30T00:00:00+08:00"
 }
 ```

-前端打开 SCADA 监测面板，展示该节点的历史监测曲线。
+## 示例 6：命令发现

-## 示例 6：记住用户长期偏好
+opencode agent 需要了解可用的 CLI 命令时：

-用户消息：
- "以后回答尽量简洁，先给结论再解释。"
+```
+tjwater_cli(command="help")           → 获取一级命令清单
+tjwater_cli(command="help analysis")  → 获取 analysis 子命令详情
+```

-opencode agent 调用工具 `memory_manager`：
+帮助输出 JSON 格式，含 `commands` 数组和 `summary`。

+## 示例 7：记住用户偏好
+
+用户消息："以后回答尽量简洁，先给结论再解释。"
+
+opencode agent 调用 `memory_manager`：
 ```json
 {
  "action": "add",
-  "reason": "用户明确给出了长期有效的回答风格偏好，后续会话也应遵守。",
+  "reason": "用户明确给出了长期有效的回答风格偏好",
  "scope": "user",
  "content": "用户偏好先给结论、再补必要解释，整体风格尽量简洁。"
 }
 ```

-## 示例 7：检索历史案例而不是误写入 memory
-
-用户消息：
- "我们之前是不是分析过类似的爆管定位问题？"
-
-opencode agent 调用工具 `session_search`：
-
-```json
-{
-  "reason": "用户在询问过往会话中的类似案例，应先检索历史 transcript 而不是写入新的 memory。",
-  "query": "爆管定位 类似案例",
-  "max_results": 5
-}
-```
-
 ## 示例 8：沉淀可复用 workflow 模式

-用户消息：
- "这套瓶颈分析流程之后可以复用。"
-
-opencode agent 调用工具 `skill_manager`：
+用户消息："这套瓶颈分析流程之后可以复用。"

+opencode agent 调用 `skill_manager`：
 ```json
 {
  "action": "append_pattern",
-  "reason": "本轮已验证一套稳定可复用的瓶颈分析 workflow，适合沉淀到已有 skill。",
+  "reason": "本轮已验证一套稳定可复用的瓶颈分析 workflow",
  "skill_path": "workflow/bottleneck-analysis",
-  "pattern": "当瓶颈分析依赖大体量属性数据和模拟结果时，先用 dynamic_http_call 获取 preview，再用 fetch_result_ref 回读完整数据后再做合并与排序。"
+  "pattern": "当瓶颈分析依赖大体量属性数据和模拟结果时，先用 tjwater_cli 获取 links 结果，再逐管段查询属性，最后合并排序。"
 }
 ```
-
-## 示例 9：给单个 workflow skill 写入可复用脚本
-
-当某个 workflow 的本地 Python 处理逻辑已经稳定、未来同类任务会重复使用时，可写入该 skill 自己的 `scripts/*.py`：
-
-```json
-{
-  "action": "write_script",
-  "reason": "本轮已验证瓶颈分析中的合并与排序脚本，后续同类 workflow 可直接复用。",
-  "skill_path": "workflow/bottleneck-analysis",
-  "file_path": "scripts/merge_and_rank.py",
-  "content": "import json\n\n\ndef rank_links(rows):\n    return sorted(rows, key=lambda row: row['composite_score'], reverse=True)\n"
-}
-```
-
-脚本应只归属当前 `skill_path`，不要写到 `data/` 或其他 skill 目录。
@@ -1,14 +0,0 @@
---
-name: tjwater-domain-platform
-description: 负责治理、审计、缓存与元数据能力。
-version: 3.0.0
---
-
-# Platform Domain Skill
-
-## 简介
-负责治理、审计、缓存与元数据能力。
-
-## 子模块索引 (渐进式引导)
- **governance-observability**: 见 `./governance-observability/SKILL.md`
-
@@ -1,16 +0,0 @@
---
-name: tjwater-scenario-platform-governance-observability
-description: 负责审计、缓存与平台元数据。
-version: 3.0.0
---
-
-# governance-observability Scenario Skill
-
-## 简介
-负责审计、缓存与平台元数据。
-
-## 子模块索引 (渐进式引导)
- **audit**: 见 `./audit/SKILL.md`
- **cache**: 见 `./cache/SKILL.md`
- **meta**: 见 `./meta/SKILL.md`
-
@@ -1,30 +0,0 @@
---
-name: tjwater-action-platform-governance-observability-audit
-description: platform/governance-observability 下 audit 操作技能。
-version: 3.0.0
---
-
-# audit Action Skill
-
-## 简介
-负责 `platform/governance-observability` 场景下 `audit` 的具体接口调用。
-
-## 子模块索引 (渐进式引导)
- 当前为叶子节点，直接使用下方接口目录。
-
-## 接口目录
-| Method | Path | Summary | Required Params | Optional Params |
-|---|---|---|---|---|
-| GET | `/api/v1/audit/logs` | 查询审计日志 | - | user_id (query), project_id (query), action (query), resource_type (query), start_time (query), end_time (query), skip (query), limit (query) |
-| GET | `/api/v1/audit/logs/count` | 获取审计日志总数 | - | user_id (query), project_id (query), action (query), resource_type (query), start_time (query), end_time (query) |
-| GET | `/api/v1/audit/logs/my` | 查询我的审计日志 | - | action (query), start_time (query), end_time (query), skip (query), limit (query) |
-
- 覆盖方法：`GET`
-
-## 接口说明
-
-| 接口 | 说明 |
-|---|---|
-| `GET /audit/logs` | 查询系统审计日志（仅管理员），支持按用户ID、项目ID、操作类型、资源类型、时间范围过滤；支持分页（skip/limit） |
-| `GET /audit/logs/count` | 获取满足过滤条件的审计日志总条数，用于分页显示 |
-| `GET /audit/logs/my` | 查询当前登录用户自己的操作日志，支持按操作类型和时间范围过滤 |
@@ -1,32 +0,0 @@
---
-name: tjwater-action-platform-governance-observability-cache
-description: platform/governance-observability 下 cache 操作技能。
-version: 3.0.0
---
-
-# cache Action Skill
-
-## 简介
-负责 `platform/governance-observability` 场景下 `cache` 的具体接口调用。
-
-## 子模块索引 (渐进式引导)
- 当前为叶子节点，直接使用下方接口目录。
-
-## 接口目录
-| Method | Path | Summary | Required Params | Optional Params |
-|---|---|---|---|---|
-| POST | `/api/v1/clearallredis/` | 清除所有缓存 | - | - |
-| POST | `/api/v1/clearrediskey/` | 清除单个缓存键 | key (query) | - |
-| POST | `/api/v1/clearrediskeys/` | 清除匹配的缓存键 | keys (query) | - |
-| GET | `/api/v1/queryredis/` | 查询缓存键列表 | - | - |
-
- 覆盖方法：`GET, POST`
-
-## 接口说明
-
-| 接口 | 说明 |
-|---|---|
-| `GET /queryredis/` | 查询当前 Redis 中所有缓存键列表，用于检查缓存状态 |
-| `POST /clearrediskey/` | 删除指定单个键的缓存（精确匹配） |
-| `POST /clearrediskeys/` | 批量删除多个匹配的缓存键（支持模式匹配） |
-| `POST /clearallredis/` | 清除 Redis 中所有缓存数据（慎用，会影响所有会话） |
@@ -1,30 +0,0 @@
---
-name: tjwater-action-platform-governance-observability-meta
-description: platform/governance-observability 下 meta 操作技能。
-version: 3.0.0
---
-
-# meta Action Skill
-
-## 简介
-负责 `platform/governance-observability` 场景下 `meta` 的具体接口调用。
-
-## 子模块索引 (渐进式引导)
- 当前为叶子节点，直接使用下方接口目录。
-
-## 接口目录
-| Method | Path | Summary | Required Params | Optional Params |
-|---|---|---|---|---|
-| GET | `/api/v1/meta/db/health` | 检查数据库健康状态 | - | - |
-| GET | `/api/v1/meta/project` | 获取项目元数据 | - | - |
-| GET | `/api/v1/meta/projects` | 列出用户项目 | - | - |
-
- 覆盖方法：`GET`
-
-## 接口说明
-
-| 接口 | 说明 |
-|---|---|
-| `GET /meta/db/health` | 检查数据库（PostgreSQL/TimescaleDB）连接健康状态，返回 ok/error |
-| `GET /meta/project` | 获取当前用户当前项目的元数据（名称、创建时间、所有者等） |
-| `GET /meta/projects` | 列出当前登录用户有权限访问的所有项目信息 |
@@ -1,125 +1,93 @@
-# API Skills 使用 Runbook（工具调用链）
+# TJWater Skills Runbook（工具调用链）

 ## 1) 总体原则

- Skills 负责“告诉模型可做什么”。
- `chat/stream` 内部启动 opencode 会话，并注册工具 `dynamic_http_call`。
- opencode agent 通过工具调用后端能力，不直接发 HTTP。
- TJWaterAgent 执行器负责“代表当前用户调真实后端 API”（动态路径，无白名单）。
- 会话完成后，运行时会基于 transcript 做后台 learning review；这一步用于判断是否需要更新 memory 或 skill，而不是替代主任务回答。
+- Skills 仅负责**可复用的多步工作流**。
+- 原子操作（单次查询/单项分析）由 Agent 直接调用 `tjwater_cli` 工具。
+- `tjwater-cli` 输出 JSON，`"ok": true` 表示成功，`"ok": false` 时检查 `error.code`。
+- Agent 运行 `tjwater-cli help` 发现可用命令和参数。
+- 会话完成后，运行时基于 transcript 做后台 learning review；这一步用于判断是否需要更新 memory 或 skill，而不是替代主任务回答。

 ## 1.1) 自我学习闭环

- **memory_manager**：保存用户长期偏好 / 约束，以及稳定 workspace 事实
- **skill_manager**：保存经过验证、可复用的 workflow / 方法 / pitfall
- **session_search**：检索当前用户 + 当前项目范围内的历史会话 transcript，用于回忆旧案例，避免把一次性案例写入 memory
-
-推荐分流：
-
- 需要长期遵守的偏好 / 稳定事实 → `memory_manager`
- 可复用的方法、步骤、坑点 → `skill_manager`
- 某次分析过程、历史案例、临时结论 → `session_search`
+- **memory_manager**：保存用户长期偏好 / 约束
+- **skill_manager**：保存经过验证、可复用的 workflow 方法模式
+- **session_search**：检索历史会话，避免把一次性案例写入 memory

 ## 2) 请求入口（前端）

 - `POST /api/v1/agent/chat/stream`（唯一前端入口）

-不提供 `/execute` 对外调用路径，统一通过 `chat/stream` + 工具调用链执行。
-
-请求体：
-
-```json
-{
-  "message": "帮我分析当前管网中的水力瓶颈管道，并给出改造建议",
-  "session_id": "agent-demo-001"
-}
-```
-
 SSE 事件：

-| event | 用途 | 关键字段 |
-| --- | --- | --- |
-| `progress` | 展示 Agent 处理过程、规划和工具进度 | `session_id`, `id`, `phase`, `status`, `title`, `detail` |
-| `token` | 渲染面向用户的最终回答文本 | `session_id`, `content` |
-| `tool_call` | 驱动前端地图/面板/图表动作 | `session_id`, `tool`, `params` |
-| `done` | 当前轮对话结束 | `session_id` |
-| `error` | 当前轮失败 | `session_id`, `message`, `detail` |
+| event | 用途 |
+|---|---|
+| `progress` | Agent 处理过程、规划和工具进度 |
+| `token` | 面向用户的回答文本 |
+| `tool_call` | 驱动前端地图/面板/图表动作 |
+| `done` | 当前轮对话结束 |
+| `error` | 当前轮失败 |

-`progress.status` 取值为 `running`、`completed`、`error`；前端应按相同 `id` 覆盖更新同一条进度，而不是重复追加。
-
-## 3) 工具参数约定（opencode agent 调用工具时）
+## 3) tjwater_cli 工具约定

 ```json
 {
-  "path": "/api/v1/scada/by-ids-field-time-range",
-  "method": "GET",
-  "arguments": {
-    "device_ids": "170490",
-    "field": "monitored_value",
-    "start_time": "2026-03-29T07:57:47.338Z",
-    "end_time": "2026-03-30T07:57:47.338Z"
-  }
+  "reason": "查询当前项目数据库健康状态",
+  "command": "project db-health",
+  "timeout": 60
 }
 ```

-说明（工具 `dynamic_http_call`）：
- `path` 必须以 `/` 开头。
- `method` 支持：`GET/POST/PUT/PATCH/DELETE`。
- `arguments` 会编码为 query 参数（列表会转为逗号拼接）。
+- `command`：tjwater-cli 子命令（不含二进制路径和 `--auth-context`）
+- `timeout`：可选超时秒数，默认 60，大结果集建议 300+
+- 认证上下文（token、server、project）由内部桥接自动注入

-## 3.1) 学习工具约定
+## 4) 工具参数约定（前端工具）

- 所有学习类工具都必须带 `reason`
- `memory_manager` 支持：`add / list / replace / remove`
- `skill_manager` 支持：`list / append_pattern / remove_pattern / write_reference / remove_reference / write_script / remove_script`
- `session_search` 只搜索当前用户 + 当前项目作用域，不接受跨项目检索
- `skill_manager` 的结构化写入优先落到：
-  1. `## Learned Patterns`
-  2. `references/*.md`
-  3. `scripts/*.py`
-  不应直接重写 skill frontmatter 或任意正文段落
- `scripts/*.py` 仅表示当前 `skill_path` 私有的可复用脚本资产；不要把运行时临时脚本写进 `data/`
+- 所有前端工具 `locate_features`、`view_scada`、`view_history`、`show_chart`、`render_junctions` 需带 `reason`

-## 4) 用户上下文注入（后端执行阶段）
+## 5) 学习工具约定
+
+- 所有学习类工具必须带 `reason`
+- `memory_manager`：`add / list / replace / remove`
+- `skill_manager`：`list / append_pattern / remove_pattern / write_reference / remove_reference / write_script / remove_script`
+- `session_search`：只搜索当前用户 + 当前项目作用域
+- `skill_manager` 写入落到：`## Learned Patterns`、`references/*.md`、`scripts/*.py`
+
+## 6) 用户上下文注入

 - `Authorization`（Bearer Token）
- `x-project-id`
+- `X-Project-Id`
+- 执行器附带 `X-Trace-Id` 用于链路排查

-执行器会附带 `x-trace-id` 用于链路排查（可透传或自动生成）。
+## 7) 排障要点

-## 5) 排障要点
+- CLI 返回 `"ok": false` → 检查 `error.code` 和 `error.message`
+- `UNAUTHENTICATED`：检查 token 和项目权限
+- `NOT_FOUND`：检查资源 ID 或命令拼写
+- `SERVER_ERROR`：记录 `request_id`，结合后端日志排查
+- CLI 超时：增大 `timeout` 参数

- `400`：检查工具参数 `path/method/arguments` 格式。
- `401/403`：检查 token 与项目权限。
- `404`：检查 `path` 是否正确。
- `422`：检查 `arguments` 字段名与类型。
- `5xx`：记录 `trace_id`，结合后端日志排查。
-
-## 6) 前端工具调用链
-
-前端工具（`locate_features`, `view_history`, `view_scada`, `show_chart`）的调用链与 `dynamic_http_call` 不同：
+## 8) 前端工具调用链

 ```
-用户消息 → opencode agent → tool calling → 调用前端工具 (如 locate_features)
-                                    ↓
-                              tool handler:
-                              1) 推送 SSE tool_call 事件到前端
-                              2) 返回简短确认给 opencode agent（"已定位到管道"）
-                                    ↓
+用户消息 → opencode agent → tool calling → 调用前端工具
+                                ↓
+                          tool handler:
+                          1) 推送 SSE tool_call 事件到前端
+                          2) 返回简短确认给 opencode agent
+                                ↓
 前端同时收到:
-  - SSE event: progress  → 展示规划/工具执行/完成状态
-  - SSE event: tool_call → 前端执行操作（定位地图/打开面板/渲染图表）
-  - SSE event: token     → 渲染 opencode agent 文字回复
+  - SSE event: progress  → 展示处理状态
+  - SSE event: tool_call → 前端执行操作
+  - SSE event: token     → 渲染文字回复
 ```

-关键区别：
- `dynamic_http_call`：TJWaterAgent 代理 HTTP 请求，结果返回给 opencode agent 做后续分析。
- 前端工具：TJWaterAgent 仅推送 SSE 事件，前端直接执行，结果不返回 opencode agent。
- `show_chart`：opencode agent 先通过 `dynamic_http_call` 查询数据，处理为 x_data + series 格式后调用 `show_chart`，前端直接渲染图表，不再请求后端。
+`tjwater_cli`：Agent 桥接调用 CLI，结果返回给 opencode agent 做后续分析。
+前端工具：仅推送 SSE 事件，前端直接执行。

-## 7) 复盘与沉淀建议
+## 9) 复盘与沉淀建议

- 复杂多工具任务完成后，优先判断是否产生了稳定 workflow，可写入 `skill_manager`
- 用户明确纠正表达风格、输出格式或步骤时，优先判断是否需要写入 `memory_manager`
- 如果你只是想确认“以前是不是处理过类似问题”，先用 `session_search`
- 如果结果仍然只是 preview，不要基于 preview 做 learned pattern，总是先 `fetch_result_ref`
+- 复杂多工具任务完成后，判断是否产生了稳定 workflow，可写入 `skill_manager`
+- 用户明确纠正表达风格、输出格式时，写入 `memory_manager`
+- 确认"以前是否处理过类似问题"，用 `session_search`
@@ -1,19 +1,70 @@
---
-name: tjwater-workflow
-description: 负责分析类工作流能力。
-version: 1.0.0
---
-
-# Workflow Domain Skill
-
-## 简介
-负责分析场景下的工作流组织与调用入口能力。
-
-## 使用策略
-
- 当用户问题明显属于“多接口 + 本地分析 + 综合结论”的分析任务时，优先从本目录查找固定 workflow。
- 如果找到合适 workflow，应先按 workflow 执行主路径，再补充缺少的原子 skill。
- 如果没有匹配 workflow，或现有 workflow 缺少关键步骤、接口或输出约束，再回到其他 domain/scenario/action skills 组合能力。
-
-## 子模块索引 (渐进式引导)
- **bottleneck-analysis**: 见 `./bottleneck-analysis/SKILL.md`
+---
+name: tjwater-workflow
+description: 分析类工作流技能。所有工作流遵循 "CLI 获取 → 本地分析 → 报告输出" 模式。
+version: 3.0.0
+---
+
+# Workflow Domain Skill
+
+## 简介
+负责分析场景下的工作流组织与调用入口。前端工具仅用于渲染。
+
+## 使用策略
+
+1. **优先匹配固定工作流** — 用户问题属于已有覆盖场景时，直接走 workflow
+2. **按需升级** — 浅层工作流满足不了时，沿升级路径进入深层工作流
+3. **缺少 workflow 时** — Agent 自行组合 CLI 命令 + Python 脚本
+
+---
+
+## 工作流决策树
+
+```
+用户请求
+   │
+   ├─ 含"服务范围/供水分区/水源范围/分区渲染"？
+   │    └─ 是 → 走 source-service-area-analysis
+   │
+   ├─ 含"改管径/瓶颈/扩容"？
+   │    └─ 是 → 直接走 bottleneck-analysis
+   │
+   └─ 否 → 走 simulation-diagnosis（快速诊断）
+            │
+            ├─ 全局异常？（断流/未收敛/系统性低压）
+            │    └─ 直接输出针对性诊断，结束
+            │
+            ├─ 少量告警、无紧急项？
+            │    └─ 输出报告，结束
+            │
+            └─ ≥5 条紧急超速 或 存在多维度交叉异常？
+                 └─ 输出快速诊断报告 + 建议升级 bottleneck-analysis
+                    + 传递 TOP 问题管段 ID 列表
+```
+
+---
+
+## 工作流清单
+
+| 工作流 | 数据需求 | 典型步骤 |
+|--------|---------|---------|
+| **simulation-diagnosis** | `simulation run` + `data timeseries realtime links/nodes` | 1-2 次 CLI + 诊断脚本 |
+| **bottleneck-analysis** | 模拟结果 + `network get-link-properties` 逐管道查询 | 多次 CLI + 合并分析脚本 |
+| **source-service-area-analysis** | 模拟结果 + 管道拓扑 + 水库列表 | 多次 CLI + 图遍历脚本 |
+
+---
+
+## 衔接规则
+
+`simulation-diagnosis` → `bottleneck-analysis` 升级条件：
+
+| 信号 | 阈值 |
+|------|------|
+| 紧急超速管段数 | ≥ 5 条流速 > 1.5 m/s |
+| 多维度交叉异常 | 同一管段同时满足高速 + 高水损 + 大流量 |
+| 高水损地理聚集 | TOP 水损管段集中在同一区域 |
+
+## 子模块索引
+
+- **source-service-area-analysis**: `./source-service-area-analysis/SKILL.md`
+- **simulation-diagnosis**: `./simulation-diagnosis/SKILL.md`
+- **bottleneck-analysis**: `./bottleneck-analysis/SKILL.md`
@@ -1,67 +1,71 @@
 ---
 name: tjwater-workflow-bottleneck-analysis
-description: workflow 下 bottleneck-analysis（水力瓶颈分析）工作流技能。
-version: 1.1.0
+description: 水力瓶颈分析工作流。
+version: 2.0.0
 ---

 # bottleneck-analysis Workflow Skill

 ## 简介
-负责 `analytics/simulation-analysis` 场景下的水力瓶颈综合分析，通过结合管道属性与水力模拟结果，识别管网中超负荷、高流速、高水头损失的瓶颈管道，并给出分级改造建议。
+结合管道属性与水力模拟结果，识别管网中超负荷、高流速、高水头损失的瓶颈管道，计算综合评分并给出分级改造建议。

 ## 前置依赖
-本工作流依赖以下两个数据源，需按顺序并行或串行获取：

 ### 依赖 1：管道属性数据
- 接口：`GET /api/v1/getallpipeproperties/`
- 参数：`network`（query，如 `tjwater`）
- 用途：获取全部管道的 id、管径(diameter)、长度(length)、粗糙度(roughness)、起端(node1)、终端(node2) 等属性
- 注意：结果可能很大（数万条），需使用 `fetch_result_ref` 分批或全量获取
+```
+tjwater_cli:
+  command: "network get-link-properties --link P1"
+```
+逐条查询所需管道 ID 的属性（id、diameter、length、roughness、node1、node2）。
+> 首批 CLI 仅支持按 ID 单项查询，需对目标管段逐个调用。

 ### 依赖 2：水力模拟结果
- 接口：`GET /api/v1/runprojectreturndict/`
- 参数：`network`（query，如 `tjwater`）
- 用途：运行管网水力模拟，返回各管段的 flow(LPS)、velocity(m/s)、headloss(m)、status，以及各节点的 demand、head、pressure(KPA)
- 注意：结果可达 30MB+，需用 Python 脚本批量处理或使用 `fetch_result_ref` 回读
+```
+tjwater_cli:
+  command: "data timeseries realtime links --start-time TIME --end-time TIME"
+  timeout: 300
+```
+获取全部管段的 flow(LPS)、velocity(m/s)、headloss(m)、status 等。
+
+---

 ## 工作流步骤

-### 第 1 步：并行获取管道属性和运行水力模拟
-同时调用 `getallpipeproperties` 和 `runprojectreturndict`，network 参数使用项目名称（如 `tjwater`）。
+### 第 1 步：获取管道属性
+从 `simulation-diagnosis` 输出的 TOP 问题管段 ID 列表出发，逐条调用 `network get-link-properties --link ID` 获取管径/长度/粗糙度。

-### 第 2 步：合并数据
-用 Python 脚本将管道属性的 pipe_id 与模拟结果的 link_id 进行关联，构建含以下字段的合并数据集：
+### 第 2 步：获取模拟结果
+调用 `data timeseries realtime links` 获取对应时间窗口的全部管道水力结果。
+
+### 第 3 步：合并数据
+Python 脚本将管道属性 `id` 与模拟结果的 `link_id` 关联，构建合并数据集：

 | 字段 | 来源 | 说明 |
 |------|------|------|
-| id | 两者关联键 | 管道/链路 ID |
-| flow | 模拟 link_results | 流量 (LPS) |
-| velocity | 模拟 link_results | 流速 (m/s) |
-| headloss | 模拟 link_results | 水头损失 (m) |
+| id | 关联键 | 管道 ID |
+| flow | 模拟 | 流量 (LPS) |
+| velocity | 模拟 | 流速 (m/s) |
+| headloss | 模拟 | 水头损失 (m) |
 | diameter | 管道属性 | 管径 (mm) |
 | length | 管道属性 | 长度 (m) |
 | roughness | 管道属性 | 粗糙度系数 |
-| node1 / node2 | 管道属性 | 起端/终端节点 ID |
+| node1 / node2 | 管道属性 | 起端/终端节点 |
 | unit_headloss | 计算 | headloss / length (m/m) |
-| capacity_ratio | 计算 | |flow| / (π×(d/2000)²×1000)，即实际流量与 1m/s 设计流量的比值 |
+| capacity_ratio | 计算 | \|flow\| / (π×(d/2000)²×1000) |

-同时从模拟 node_results 提取各节点 pressure，关联到管段两端。
-
-### 第 3 步：多维度瓶颈识别
-按以下 5 个维度分别排序筛选，交叉印证：
+### 第 4 步：多维度瓶颈识别

 | 维度 | 筛选条件 | 指示含义 |
 |------|---------|---------|
 | 高流速 | velocity > 1.2 m/s | 管径不足 |
 | 主干管高流量 | diameter ≥ 300mm 且 velocity > 0.5 m/s | 传输瓶颈 |
-| 高水头损失 | headloss > 5m 且 0.3 < velocity < 1.5 m/s | 能耗瓶颈/粗糙度问题 |
+| 高水头损失 | headloss > 5m 且 0.3 < velocity < 1.5 | 能耗瓶颈 |
 | 高单位水头损失 | unit_headloss > 1.0 m/m | 严重局部瓶颈 |
-| 超负荷 | capacity_ratio > 1.0 | 实际流量超过设计能力 |
+| 超负荷 | capacity_ratio > 1.0 | 超过设计能力 |

-排除极短管道（length < 0.5m）以减少噪声。
+排除极短管道（length < 0.5m）。

-### 第 4 步：综合评分
-对有效管道计算综合瓶颈分数：
+### 第 5 步：综合评分

 ```
 composite_score = (velocity / max_velocity) × 0.4
@@ -71,51 +75,32 @@ composite_score = (velocity / max_velocity) × 0.4

 取 TOP 10~20 作为最严重瓶颈管道。

-### 第 5 步：前端可视化
- 使用 `show_chart` 展示流速分布柱状图
- 使用 `locate_features` 在地图上定位 TOP 瓶颈管道（feature_type=pipe）
- 可选：使用 `view_history` 查看瓶颈管道的历史运行数据
- 前端工具仅用于展示，分析结论必须来自 `dynamic_http_call` / `fetch_result_ref` 获得的数据
+### 第 6 步：分级改造建议

-### 第 6 步：给出分级改造建议
-按严重程度分为三级：
+| 级别 | 评分范围 | 行动 |
+|------|---------|------|
+| 🚨 紧急 | > 0.3 | 立即安排管径升级 |
+| ⚡ 重点 | 0.15~0.3 | 纳入近期改造计划 |
+| 📋 关注 | 0.05~0.15 | 持续监测 |

- **🚨 紧急**：综合评分 > 0.3，立即安排管径升级
- **⚡ 重点**：综合评分 0.15~0.3，纳入近期改造计划
- **📋 关注**：综合评分 0.05~0.15 或单维度超标，持续监测
-
-每条建议含：当前管径 → 建议管径（基于目标流速 1.0~1.5 m/s 反推），并附改造理由。
-
-## 改造管径计算公式
+建议管径公式：
 ```
 建议管径(mm) = 2 × 1000 × sqrt(|flow| / (π × target_velocity × 1000))
 ```
-目标流速：DN<300 取 1.0 m/s，DN≥300 取 1.2 m/s。
+DN<300 目标流速 1.0 m/s，DN≥300 目标流速 1.2 m/s。
+
+### 第 7 步：可视化
+- `show_chart`：流速分布柱状图
+- `locate_features`：地图定位 TOP 瓶颈管道
+
+---

 ## 证据约束
-
- 如果关键数据仍处于 preview 状态，不得直接输出最终瓶颈结论
- 如果模拟结果不完整或接口失败，应明确说明当前仅能做初步筛查
- 改造建议必须区分“数据直接支持的结论”和“工程经验推断”
-
-## 推荐输出结构
-
-1. 分析范围与数据来源
-2. 主要瓶颈管段 Top N
-3. 分级建议（紧急 / 重点 / 关注）
-4. 假设与局限
-5. 是否建议地图定位或图表展示
-
-## 参考
- 管道属性操作：`../business/network-assets/pipes/SKILL.md`
- 模拟操作：`./simulation/SKILL.md`
- 节点属性操作：`../business/network-assets/junctions/SKILL.md`
+- 关键数据不完整时不得输出最终瓶颈结论
+- 改造建议必须区分"数据直接支持"和"工程经验推断"

 ## Learned Patterns
- 先按“属性数据获取 → 模拟结果获取 → 本地关联 → 多指标筛选 → 分级建议”拆解工作流，再组织展示步骤，避免把一次分析过程写成会话流水账。
- 结果集较大时，优先使用 `fetch_result_ref` 或本地脚本批处理；只要数据仍是 preview、截断或未完整回读，就不能直接输出 Top N 瓶颈结论。
- 关联前先统一关键字段和单位：`pipe_id/link_id`、`diameter(mm)`、`length(m)`、`flow(LPS)`、`pressure(KPA)`；字段未对齐时，后续 ranking 和建议都会失真。
- `unit_headloss`、`capacity_ratio` 等衍生指标应在过滤异常数据（如 `length < 0.5m` 的短管）后再计算，否则容易被极端值放大。
- 阈值和评分权重应视为可调启发式，而不是唯一真理；输出时要区分“数据直接支持的结论”和“工程经验推断的建议”。
- 地图定位、图表展示属于证据呈现层，不能替代分析层；瓶颈判定必须基于后端原始结果或完整回读数据。
- 常见坑点：短管导致单位水头损失虚高、节点或链路映射缺失导致误判、模拟结果不完整时误把局部结果当全量结论。
+- 先按"属性数据获取 → 模拟结果获取 → 本地关联 → 多指标筛选 → 分级建议"拆解工作流。
+- 关联前统一字段：`link_id`、`diameter(mm)`、`length(m)`、`flow(LPS)`、`pressure(KPA)`。
+- `unit_headloss`、`capacity_ratio` 等衍生指标应在过滤异常数据后再计算。
+- 常见坑点：短管导致单位水头损失虚高、节点链路映射缺失、模拟结果不完整误当全量结论。
@@ -0,0 +1,210 @@
+---
+name: tjwater-workflow-simulation-diagnosis
+description: 单步长水力计算与管网问题诊断工作流。
+version: 3.0.0
+---
+
+# Simulation Diagnosis Workflow Skill
+
+## 简介
+`simulation run` → 查询模拟结果 → 快速综合诊断 → 结构化报告。覆盖超流速、低压区、高水损、死水管段、Closed 阀门等常见运行问题。
+
+**仅依赖模拟结果**（无需管径/长度/粗糙度等属性），适用于快速巡检、初筛、事故后评估。如需结合管径做详细瓶颈评分与改造建议，走 `bottleneck-analysis` 工作流。
+
+---
+
+## 执行速览（Golden Path）
+
+"跑一下水力计算看看管网有什么问题" 的标准执行路径：
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│  1. tjwater_cli(command="simulation run --start-time ...     │
+│       --duration 30")                                         │
+│     ↓ 模拟结果写入服务端时序库                                 │
+│  2. tjwater_cli(command="data timeseries realtime links       │
+│       --start-time ... --end-time ...")                       │
+│     ↓ (写为本地 JSON)                                        │
+│  3. python diagnose_simulation.py result.json                │
+│     ↓ (stdout 结构化报告)                                     │
+│  4. 解读脚本输出 → 按严重级别组织 Markdown 报告               │
+│     ↓ (可选)                                                  │
+│  5. show_chart / locate_features / view_scada                 │
+└──────────────────────────────────────────────────────────────┘
+```
+
+> **关键原则**：排序/筛选/聚合全部在 Python 脚本或本地完成。前端工具仅用于渲染。
+
+---
+
+## 适用场景
+
+| 场景 | 说明 |
+|------|------|
+| "跑一次水力计算看看管网有什么问题" | 直接适用，走 Golden Path |
+| 管道属性接口不可用或数据不全 | 仅依赖模拟结果，无需属性数据 |
+| 快速巡检 / 定期健康检查 | 低开销，脚本一秒给出问题概览 |
+| 爆管/事故后的快速评估 | 单步稳态模拟，快速定位异常区域 |
+| 作为 bottleneck-analysis 的前置筛查 | 先定位问题区域，再深入分析 |
+
+---
+
+## 阶段一：触发模拟运行
+
+### CLI 调用
+
+```
+tjwater_cli:
+  command: "simulation run --start-time 2025-01-02T03:04:05+08:00 --duration 30"
+```
+
+- `--start-time`：模拟起始绝对时间，必须显式带时区（UTC+8）
+- `--duration`：模拟持续分钟数
+- 结果写入服务端时序库，不直接返回
+
+### 查询模拟结果
+
+```
+tjwater_cli:
+  command: "data timeseries realtime links --start-time 2025-01-02T03:04:05+08:00 --end-time 2025-01-02T03:34:05+08:00"
+  timeout: 300
+```
+
+```
+tjwater_cli:
+  command: "data timeseries realtime nodes --start-time 2025-01-02T03:04:05+08:00 --end-time 2025-01-02T03:34:05+08:00"
+  timeout: 300
+```
+
+### 返回数据结构
+
+输出为 JSON，`data` 字段包含结果数组。
+
+**links** — 管段水力状态：
+| 字段 | 单位 | 说明 |
+|------|------|------|
+| link_id | — | 管段 ID |
+| flow | LPS | 流量（正负表示流向） |
+| velocity | m/s | 流速 |
+| headloss | m | 水头损失 |
+| status | — | Open / Closed / Critical |
+
+**nodes** — 节点水力状态：
+| 字段 | 单位 | 说明 |
+|------|------|------|
+| node_id | — | 节点 ID |
+| demand | LPS | 需水量 |
+| head | m | 水头 |
+| pressure | KPA | 压力 |
+
+---
+
+## 阶段二：全局异常检查（优先！）
+
+**在进入局部分析之前**，必须检查以下全局信号——如果命中则直接输出针对性诊断：
+
+| 全局信号 | 判定条件 | 含义 | 处理 |
+|---------|---------|------|------|
+| **模拟断流** | 所有 link velocity ≈ 0 | 阀门全关 / 水源缺失 / 模型断连 | 检查模型配置，不做局部分析 |
+| **模拟未收敛** | 所有 node pressure = 0 | 水力方程未收敛 | 检查 INP 设定，不做局部分析 |
+| **系统性低压** | >70% 节点 pressure < 28 KPA | 水源水头不足 / 泵站扬程不够 | 输出"全局性低压"结论，排查水源/泵站 |
+| **结果不完整** | links 或 nodes 结果为空 | 接口异常或模型损坏 | 报告数据不可用，提示重试 |
+
+---
+
+## 阶段三：自动诊断
+
+### 使用 `diagnose_simulation.py`
+
+脚本路径：`scripts/diagnose_simulation.py`
+
+```bash
+# 基本用法
+python scripts/diagnose_simulation.py /tmp/opencode/sim_result.json
+
+# 自定义阈值
+python scripts/diagnose_simulation.py /tmp/opencode/sim_result.json \
+  --velocity-warn 1.2 \
+  --velocity-critical 2.0 \
+  --pressure-warn 40 \
+  --pressure-critical 28 \
+  --headloss-top 30 \
+  --flow-top 20
+
+# 仅输出摘要
+python scripts/diagnose_simulation.py /tmp/opencode/sim_result.json --summary-only
+```
+
+脚本自动完成：
+- 全局统计（管段/节点总数，流速/压力/流量/水损的 max/mean/分位数）
+- 超流速管段 TOP 20
+- 高水损管段 TOP 30
+- 低压节点统计
+- 零流量管段、Closed 管段
+- 高流量主干管 TOP 20
+
+---
+
+## 阶段四：报告生成与可视化
+
+### 报告结构
+
+```
+---
+## 管网运行诊断报告
+
+### 一、模拟概况
+- 时间窗口 / 管网规模 / 单位
+
+### 二、主要发现（按严重程度排序）
+🚨 紧急 / ⚡ 重点 / 📋 关注
+每项含：问题标题 + 受影响数 + TOP 示例（3-5条含数据） + 可能原因 + 建议
+
+### 三、数据局限
+- 区分"数据直接支持的结论"和"工程经验的推测"
+- 标注管径数据是否缺失及其对结论的影响
+```
+
+### 可视化（可选）
+
+- `show_chart`：流速/压力分布柱状图
+- `locate_features`：地图定位 TOP 问题管段
+- `view_scada`：问题区域实时监测
+- `render_junctions` + `store_render_ref`：按压力区间着色
+
+---
+
+## 诊断指标参考阈值
+
+| 指标 | 阈值 | 依据 |
+|------|------|------|
+| 流速安全上限 | 1.2 m/s | 行业管道冲刷防护上限 |
+| 流速紧急上限 | 2.0 m/s | 严重超速临界值 |
+| 最低供水压力 | 28 KPA | 国标 GB 50268 |
+| 正常压力下限 | 40 KPA | 居民供水压力下限 |
+
+> 所有阈值为可调启发式，脚本支持参数覆写。
+
+---
+
+## 下游衔接：何时升级到 bottleneck-analysis
+
+| 诊断发现 | 行动 |
+|---------|------|
+| 系统性低压（>70% 节点 <28 KPA） | **不**进入 bottleneck-analysis；排查水源/泵站 |
+| TOP 20 超速管段中 ≥5 条流速 >1.5 m/s | 升级到 bottleneck-analysis |
+| 存在多维度交叉异常管段 | 升级分析 |
+| 仅少量告警、无紧急项 | 结束，不升级 |
+
+**数据移交**：从 diagnosis 结果提取 TOP 问题管段 ID 列表，传入 bottleneck-analysis。
+
+---
+
+## Learned Patterns
+
+- [d1f826184d8709db1988b00a] **渐进式 Top-K 分析**：大结果集先算全局统计量定位异常范围，再对 Top-K 做明细检查。
+- [a19477bebe442e5d87bc78bc] **多准则交叉印证**：同时分析 velocity / headloss / flow / pressure 四个维度，紧急管段需满足多项异常条件。
+- [cf50cc317b9bfe254426482d] **API 数据降级**：管道属性不可用时不停流程，用 velocity / headloss 作为代理指标。
+- [1cd621a60d7481a1c072a54f] **系统性低压优先诊断**：全网 >70% 节点 pressure<28KPA 时定位为全局性问题。
+- [a7c30102cf5c2a5c0e8cc8dd] **诊断脚本标准化**：`diagnose_simulation.py` 是分析主力，支持自定义阈值。
+- [8b533e5bfc43c014ebcc90cf] **压力单位验证**：验证 pressure 字段实际单位（KPA vs m H₂O），阈值随单位调整。
@@ -0,0 +1,341 @@
+#!/usr/bin/env python3
+"""
+diagnose_simulation.py — 水力模拟结果快速诊断脚本
+
+用途：对 runprojectreturndict 返回的 link_results + node_results 做多维度分析。
+输出排序后的问题清单与统计摘要，供仿真诊断工作流使用。
+
+用法：
+    python diagnose_simulation.py <input_json> [options]
+
+输入 JSON 格式（runprojectreturndict 返回结构）：
+    {
+      "link_results": [
+        {"link_id": "...", "flow": float, "velocity": float,
+         "headloss": float, "status": "...", "friction": float},
+        ...
+      ],
+      "node_results": [
+        {"node_id": "...", "demand": float, "head": float, "pressure": float},
+        ...
+      },
+      ...  // 其他字段（如 tanks, pumps, valves 等）可选
+    }
+
+Options:
+    --velocity-warn FLOAT    超速预警阈值 (默认 1.2 m/s)
+    --velocity-critical FLOAT 超速严重阈值 (默认 2.0 m/s)
+    --pressure-warn FLOAT    低压预警阈值 (默认 40 KPA)
+    --pressure-critical FLOAT 低压严重阈值 (默认 28 KPA)
+    --headloss-top INT       高水损 TOP N (默认 30)
+    --flow-top INT           高流量主干管 TOP N (默认 20)
+    --output FILE            输出结果到 JSON 文件 (可选)
+    --summary-only           只输出统计摘要，不输出明细列表
+
+输出：
+    stdout 打印结构化诊断报告，含各维度问题清单和全局统计。
+"""
+
+import json
+import sys
+import argparse
+from collections import Counter
+
+# ── 默认阈值 ──────────────────────────────────────────────
+DEFAULT_VELOCITY_WARN = 1.2       # m/s
+DEFAULT_VELOCITY_CRITICAL = 2.0   # m/s
+DEFAULT_PRESSURE_WARN = 40.0      # KPA
+DEFAULT_PRESSURE_CRITICAL = 28.0  # KPA
+DEFAULT_HEADLOSS_TOP = 30
+DEFAULT_FLOW_TOP = 20
+
+
+def load_input(path: str) -> dict:
+    with open(path, "r", encoding="utf-8") as f:
+        return json.load(f)
+
+
+def analyze_links(link_results: list, args):
+    """分析管段维度：超流速、高水损、零流量、Closed 状态。"""
+    issues = {}
+
+    # ── 超流速管段 ──
+    over_velocity_warn = []
+    over_velocity_critical = []
+    zero_flow = []
+    closed_links = []
+
+    for link in link_results:
+        v = link.get("velocity", 0) or 0
+        q = abs(link.get("flow", 0) or 0)
+        status = (link.get("status") or "").strip().lower()
+        hl = link.get("headloss", 0) or 0
+
+        # 流速分级
+        if v > args.velocity_critical:
+            over_velocity_critical.append(link)
+        elif v > args.velocity_warn:
+            over_velocity_warn.append(link)
+
+        # 零流量（仅统计 Open 状态的）
+        if q < 0.001 and status == "open":
+            zero_flow.append(link)
+
+        # Closed 管段
+        if status != "open":
+            closed_links.append(link)
+
+    # 按流速降序排序
+    over_velocity_critical.sort(key=lambda x: x.get("velocity", 0), reverse=True)
+    over_velocity_warn.sort(key=lambda x: x.get("velocity", 0), reverse=True)
+
+    issues["over_velocity_critical"] = {
+        "count": len(over_velocity_critical),
+        "threshold": f">{args.velocity_critical} m/s",
+        "items": over_velocity_critical[:20],
+        "top_velocity": over_velocity_critical[0]["velocity"] if over_velocity_critical else 0,
+    }
+    issues["over_velocity_warn"] = {
+        "count": len(over_velocity_warn),
+        "threshold": f">{args.velocity_warn} m/s",
+        "items": over_velocity_warn[:20],
+    }
+
+    # ── 高水损管段（按绝对值降序） ──
+    high_headloss = sorted(link_results, key=lambda x: abs(x.get("headloss", 0) or 0), reverse=True)
+    issues["high_headloss"] = {
+        "count": len([x for x in link_results if abs(x.get("headloss", 0) or 0) > 0.5]),
+        "items": high_headloss[:args.headloss_top],
+    }
+
+    # ── 零流量管段 ──
+    issues["zero_flow_open"] = {
+        "count": len(zero_flow),
+    }
+
+    # ── Closed 管段 ──
+    issues["closed_links"] = {
+        "count": len(closed_links),
+        "items": closed_links[:20],
+    }
+
+    # ── 高流量主干管 ──
+    high_flow = sorted(link_results, key=lambda x: abs(x.get("flow", 0) or 0), reverse=True)
+    issues["high_flow_trunk"] = {
+        "items": high_flow[:args.flow_top],
+    }
+
+    return issues
+
+
+def analyze_nodes(node_results: list, args):
+    """分析节点维度：低压、高压。"""
+    issues = {}
+
+    pressure_critical = []
+    pressure_warn = []
+    high_pressure = []
+
+    for node in node_results:
+        p = node.get("pressure", 0) or 0
+        if p < args.pressure_critical:
+            pressure_critical.append(node)
+        elif p < args.pressure_warn:
+            pressure_warn.append(node)
+        if p > 200:
+            high_pressure.append(node)
+
+    pressure_critical.sort(key=lambda x: x.get("pressure", 0))
+    pressure_warn.sort(key=lambda x: x.get("pressure", 0))
+
+    total = len(node_results)
+
+    issues["pressure_critical"] = {
+        "count": len(pressure_critical),
+        "pct": round(len(pressure_critical) / total * 100, 1) if total else 0,
+        "threshold": f"<{args.pressure_critical} KPA",
+        "items": pressure_critical[:20],
+    }
+    issues["pressure_warn"] = {
+        "count": len(pressure_warn),
+        "pct": round(len(pressure_warn) / total * 100, 1) if total else 0,
+        "threshold": f"<{args.pressure_warn} KPA (>= {args.pressure_critical})",
+        "items": pressure_warn[:20],
+    }
+    issues["high_pressure"] = {
+        "count": len(high_pressure),
+        "items": high_pressure[:20],
+    }
+
+    return issues, total
+
+
+def global_stats(link_results, node_results):
+    """计算全局统计量。"""
+    velocities = [x.get("velocity", 0) or 0 for x in link_results]
+    flows = [abs(x.get("flow", 0) or 0) for x in link_results]
+    headlosses = [abs(x.get("headloss", 0) or 0) for x in link_results]
+    pressures = [x.get("pressure", 0) or 0 for x in node_results]
+    demands = [x.get("demand", 0) or 0 for x in node_results]
+
+    # 状态分布
+    status_counter = Counter((x.get("status") or "").strip().lower() for x in link_results)
+
+    stats = {
+        "link_count": len(link_results),
+        "node_count": len(node_results),
+        "velocity": {
+            "max": round(max(velocities), 4),
+            "mean": round(sum(velocities) / len(velocities), 4) if velocities else 0,
+            "p95": sorted(velocities)[int(len(velocities) * 0.95)] if velocities else 0,
+        },
+        "pressure": {
+            "max": round(max(pressures), 2),
+            "min": round(min(pressures), 2),
+            "mean": round(sum(pressures) / len(pressures), 2) if pressures else 0,
+            "p5": sorted(pressures)[int(len(pressures) * 0.05)] if pressures else 0,
+        },
+        "flow": {
+            "max": round(max(flows), 4),
+        },
+        "headloss": {
+            "max": round(max(headlosses), 4),
+        },
+        "status_distribution": dict(status_counter.most_common()),
+    }
+    return stats
+
+
+def format_report(stats, link_issues, node_issues, node_total, summary_only=False):
+    """输出格式化的诊断报告。"""
+    lines = []
+    lines.append("=" * 60)
+    lines.append("  水力模拟诊断报告")
+    lines.append("=" * 60)
+    lines.append("")
+
+    # ── 全局统计 ──
+    lines.append("【一、全局统计】")
+    lines.append(f"  管段总数: {stats['link_count']}")
+    lines.append(f"  节点总数: {stats['node_count']}")
+    lines.append(f"  流速: 最大 {stats['velocity']['max']} m/s, "
+                  f"平均 {stats['velocity']['mean']} m/s, P95 {stats['velocity']['p95']} m/s")
+    lines.append(f"  压力: 最大 {stats['pressure']['max']} KPA, "
+                  f"最小 {stats['pressure']['min']} KPA, "
+                  f"平均 {stats['pressure']['mean']} KPA, P5 {stats['pressure']['p5']} KPA")
+    lines.append(f"  最大流量: {stats['flow']['max']} LPS")
+    lines.append(f"  最大水损: {stats['headloss']['max']} m")
+    lines.append(f"  状态分布: {stats['status_distribution']}")
+    lines.append("")
+
+    # ── 超流速 ──
+    crit_v = link_issues["over_velocity_critical"]
+    warn_v = link_issues["over_velocity_warn"]
+    lines.append("【二、超流速管段】")
+    lines.append(f"  🔴 严重超速 (> {crit_v['threshold']}): {crit_v['count']} 条, "
+                  f"最高 {crit_v['top_velocity']} m/s")
+    if crit_v["count"] > 0 and not summary_only:
+        for item in crit_v["items"][:10]:
+            lines.append(f"    - {item['link_id']}: {item['velocity']} m/s, "
+                          f"flow={item.get('flow', 'N/A')} LPS, status={item.get('status', 'N/A')}")
+    lines.append(f"  🟡 流速预警 (> {warn_v['threshold']}): {warn_v['count']} 条")
+    lines.append("")
+
+    # ── 高水损 ──
+    hl = link_issues["high_headloss"]
+    lines.append("【三、高水损管段 TOP】")
+    lines.append(f"  水损 > 0.5m 的管段: {hl['count']} 条")
+    if hl["items"] and not summary_only:
+        for item in hl["items"][:10]:
+            lines.append(f"    - {item['link_id']}: headloss={item.get('headloss', 0)} m, "
+                          f"velocity={item.get('velocity', 0)} m/s")
+    lines.append("")
+
+    # ── 低压节点 ──
+    pc = node_issues["pressure_critical"]
+    pw = node_issues["pressure_warn"]
+    lines.append("【四、低压节点】")
+    lines.append(f"  🔴 严重低压 ({pc['threshold']}): {pc['count']} 个 "
+                  f"({pc['pct']}%)")
+    if pc["count"] > 0 and not summary_only:
+        for item in pc["items"][:10]:
+            lines.append(f"    - {item['node_id']}: {item['pressure']} KPA, "
+                          f"demand={item.get('demand', 0)} LPS, head={item.get('head', 0)} m")
+    lines.append(f"  🟡 低压预警 ({pw['threshold']}): {pw['count']} 个 "
+                  f"({pw['pct']}%)")
+    lines.append("")
+
+    # ── 其他发现 ──
+    lines.append("【五、其他发现】")
+    zf = link_issues["zero_flow_open"]
+    cl = link_issues["closed_links"]
+    hp = node_issues["high_pressure"]
+    lines.append(f"  - 零流量 (Open 状态但 flow≈0): {zf['count']} 条")
+    lines.append(f"  - Closed 管段/阀门: {cl['count']} 条")
+    if hp["count"] > 0:
+        lines.append(f"  - 超压节点 (> 200 KPA): {hp['count']} 个")
+    lines.append("")
+
+    # ── 高流量主干 ──
+    hft = link_issues["high_flow_trunk"]
+    lines.append("【六、高流量主干管 TOP】")
+    if hft["items"] and not summary_only:
+        for item in hft["items"][:10]:
+            lines.append(f"  - {item['link_id']}: |flow|={abs(item.get('flow', 0))} LPS, "
+                          f"velocity={item.get('velocity', 0)} m/s")
+    lines.append("")
+
+    lines.append("=" * 60)
+    return "\n".join(lines)
+
+
+def main():
+    parser = argparse.ArgumentParser(description="水力模拟结果快速诊断")
+    parser.add_argument("input", help="输入 JSON 文件路径 (runprojectreturndict 结果)")
+    parser.add_argument("--velocity-warn", type=float, default=DEFAULT_VELOCITY_WARN)
+    parser.add_argument("--velocity-critical", type=float, default=DEFAULT_VELOCITY_CRITICAL)
+    parser.add_argument("--pressure-warn", type=float, default=DEFAULT_PRESSURE_WARN)
+    parser.add_argument("--pressure-critical", type=float, default=DEFAULT_PRESSURE_CRITICAL)
+    parser.add_argument("--headloss-top", type=int, default=DEFAULT_HEADLOSS_TOP)
+    parser.add_argument("--flow-top", type=int, default=DEFAULT_FLOW_TOP)
+    parser.add_argument("--output", help="输出 JSON 结果到文件")
+    parser.add_argument("--summary-only", action="store_true", help="仅输出统计摘要")
+    args = parser.parse_args()
+
+    data = load_input(args.input)
+    link_results = data.get("link_results", [])
+    node_results = data.get("node_results", [])
+
+    if not link_results and not node_results:
+        print("错误: 输入数据中既无 link_results 也无 node_results", file=sys.stderr)
+        sys.exit(1)
+
+    # 执行分析
+    stats = global_stats(link_results, node_results)
+    link_issues = analyze_links(link_results, args)
+    node_issues, node_total = analyze_nodes(node_results, args)
+
+    # 输出报告
+    report = format_report(stats, link_issues, node_issues, node_total, args.summary_only)
+    print(report)
+
+    # 输出 JSON（可选）
+    if args.output:
+        output_data = {
+            "stats": stats,
+            "link_issues": {
+                k: {kk: vv for kk, vv in v.items() if kk != "items"}
+                for k, v in link_issues.items()
+            },
+            "node_issues": {
+                k: {kk: vv for kk, vv in v.items() if kk != "items"}
+                for k, v in node_issues.items()
+            },
+        }
+        with open(args.output, "w", encoding="utf-8") as f:
+            json.dump(output_data, f, ensure_ascii=False, indent=2)
+        print(f"详细结果已输出到: {args.output}")
+
+
+if __name__ == "__main__":
+    main()
@@ -0,0 +1,113 @@
+---
+name: tjwater-workflow-source-service-area-analysis
+description: 水源服务范围分区分析工作流。
+version: 2.0.0
+---
+
+# Source Service Area Analysis Workflow Skill
+
+## 简介
+基于水力模拟结果的流向数据构建有向图，通过下游遍历确定每个节点的供水水源归属，生成分区渲染数据并在地图上以不同颜色展示各水源的服务范围。
+
+## 前置依赖
+
+### 依赖 1：水库（水源）列表
+从模拟结果的 node_results 中识别 type=reservoir 的节点，或逐条查询已知水库节点。
+
+### 依赖 2：管道拓扑数据
+```
+tjwater_cli:
+  command: "network get-link-properties --link P1"
+```
+逐条获取管道 ID 的 node1（起端）、node2（终端），构建管网拓扑。
+
+### 依赖 3：水力模拟结果
+```
+tjwater_cli:
+  command: "data timeseries realtime links --start-time TIME --end-time TIME"
+  timeout: 300
+```
+获取各管段的 `flow`(LPS) 和 `status`，确定水流方向。
+- `flow > 0` → node1 → node2
+- `flow < 0` → node2 → node1
+- `flow ≈ 0` 或 `status != "Open"` → 忽略
+
+---
+
+## 工作流步骤
+
+### 第 1 步：获取三大数据源
+并行调用 CLI 命令获取模拟结果、管道拓扑和水库信息，写入本地临时 JSON 文件。
+
+### 第 2 步：构建有向图并计算服务范围
+
+```bash
+python scripts/compute_service_areas.py \
+  /tmp/opencode/sim_result.json \
+  /tmp/opencode/pipes.json \
+  /tmp/opencode/reservoirs.json \
+  --output /tmp/opencode/service_area_result.json
+```
+
+脚本核心逻辑：
+1. **构建无向拓扑图**：从管道属性提取 `(node1, node2)`，构建邻接表
+2. **确定流向**：从模拟结果读取 flow 和 status
+   - flow > 0 → node1 → node2
+   - flow < 0 → node2 → node1
+   - flow ≈ 0 或 status != "Open" → 忽略
+3. **获取水源集合**：从水库列表提取所有水库 ID 作为 source nodes
+4. **多源 BFS 下游遍历**：从所有水源节点同时出发，首次访问归属策略
+5. **统计输出**：各水源服务节点数、占比、未分配节点数
+6. **生成渲染数据**：`node_area_map: { node_id: area_id }`，每个水源分配唯一颜色
+
+### 第 3 步：结果验证
+- **服务覆盖率**：正常管网应 > 80%
+- **水源孤立**：某水源服务节点数为 0，检查出口管道是否 Closed
+- **大区未分配**：检查区域与水源之间管道是否 Closed
+
+### 第 4 步：前端可视化
+1. `store_render_ref` 将 `node_area_map` 迁移为受控 `render_ref`
+2. `render_junctions` 地图着色
+3. `locate_features` 高亮水源位置
+4. `show_chart` 各水源服务节点数柱状图（可选）
+
+### 第 5 步：报告输出
+
+```
+---
+## 水源服务范围分析报告
+
+### 一、管网概况
+- 总节点数 / 总管段数 / 水源数 / 覆盖率
+
+### 二、各水源服务范围
+| 水源 ID | 服务节点数 | 占比 | 颜色 |
+
+### 三、未分配节点分析
+- 数量、可能原因
+
+### 四、假设与局限
+- 流向基于稳态模拟，不代表所有工况
+- 有向图忽略零流量管段
+```
+
+---
+
+## 颜色调色板
+脚本内置 20 色：
+```
+#1f77b4, #ff7f0e, #2ca02c, #d62728, #9467bd, #8c564b, #e377c2,
+#7f7f7f, #bcbd22, #17becf, #aec7e8, #ffbb78, #98df8a, #ff9896,
+#c5b0d5, #c49c94, #f7b6d2, #c7c7c7, #dbdb8d, #9edae5
+```
+
+## 证据约束
+- 计算脚本的输出是唯一数据真相源
+- 未完成数据回读时不得执行分析
+- 零流量管段视为断连，需在报告中说明
+
+## Learned Patterns
+- 核心数据流：模拟结果(流向) + 管道属性(拓扑) + 水库列表(起点) → 有向图 BFS → 分区渲染
+- 有向图遍历前务必过滤 Closed 和零流量管段
+- 渲染数据必须通过 `store_render_ref` 迁移再传给 `render_junctions`
+- 多水源 BFS 首次访问归属策略隐含"距离最近水源"语义
@@ -0,0 +1,281 @@
+#!/usr/bin/env python3
+"""
+compute_service_areas.py — 水源服务范围分析核心脚本
+
+输入：
+  sim_result.json  — runprojectreturndict 的水力模拟结果
+  pipes.json       — getallpipeproperties 的管道属性列表
+  reservoirs.json  — getallreservoirproperties 的水库属性列表
+
+输出：
+  service_area_result.json — 包含 node_area_map 和统计信息
+
+算法：
+  1. 从 pipes 构建无向拓扑图 (node1 <-> node2)
+  2. 从 sim link_results 确定流向，生成有向图
+  3. 从 reservoirs 获取所有水源节点
+  4. 多源 BFS 下游遍历，首次访问即归属性
+  5. 生成渲染数据与统计
+
+用法:
+  python compute_service_areas.py sim_result.json pipes.json reservoirs.json \
+      --output service_area_result.json --network tjwater
+"""
+
+import argparse
+import json
+import os
+import sys
+from collections import deque
+
+# ── 高区分度 20 色调色板 ──────────────────────────────────────────
+PALETTE = [
+    "#1f77b4", "#ff7f0e", "#2ca02c", "#d62728", "#9467bd",
+    "#8c564b", "#e377c2", "#7f7f7f", "#bcbd22", "#17becf",
+    "#aec7e8", "#ffbb78", "#98df8a", "#ff9896", "#c5b0d5",
+    "#c49c94", "#f7b6d2", "#c7c7c7", "#dbdb8d", "#9edae5",
+]
+
+
+def load_json(path: str) -> dict | list:
+    """加载 JSON 文件，支持引用格式（含 result_ref 字段）或列表。"""
+    with open(path, "r", encoding="utf-8") as f:
+        data = json.load(f)
+    # 如果顶层是引用包装，展开到内部的列表
+    if isinstance(data, dict) and "data" in data:
+        data = data["data"]
+    if isinstance(data, dict) and "items" in data:
+        data = data["items"]
+    return data
+
+
+def build_undirected_graph(pipes: list) -> tuple[dict, dict]:
+    """
+    从管道列表构建无向拓扑图。
+    返回:
+      adj: { node_id: set(neighbor_node_ids) }
+      edge_map: { (node1, node2): pipe_id }  用于查找管道 ID
+    """
+    adj = {}
+    edge_map = {}
+    for p in pipes:
+        pipe_id = str(p.get("id", p.get("pipe_id", p.get("name", ""))))
+        n1 = str(p.get("node1", ""))
+        n2 = str(p.get("node2", ""))
+        if not n1 or not n2:
+            continue
+        adj.setdefault(n1, set()).add(n2)
+        adj.setdefault(n2, set()).add(n1)
+        edge_map[(n1, n2)] = pipe_id
+        edge_map[(n2, n1)] = pipe_id
+    return adj, edge_map
+
+
+def build_directed_graph(adj: dict, edge_map: dict, link_results: list) -> dict:
+    """
+    基于模拟流向构建有向图。
+    link_results 中每条记录含 link_id, flow, status。
+    流向判定:
+      flow > 0  → node1 → node2
+      flow < 0  → node2 → node1
+      flow ≈ 0 或 status != "Open" → 忽略（视为断连）
+
+    注意: link_results 中没有 node1/node2，需要通过 link_id 反查 edge_map。
+    由于 edge_map 只有 (node1,node2) → pipe_id 的映射，
+    这里需要先建立 pipe_id → (node1, node2) 的反向索引。
+    """
+    # 建立 pipe_id → (node1, node2) 反向索引
+    # 注意：edge_map 含有 (n1,n2) 和 (n2,n1) 两个方向，只保留第一个以避免反向覆写
+    pipe_to_nodes = {}
+    for (n1, n2), pid in edge_map.items():
+        if pid not in pipe_to_nodes:
+            pipe_to_nodes[pid] = (n1, n2)
+
+    digraph = {}
+    missing = 0
+    closed_or_zero = 0
+
+    for link in link_results:
+        lid = str(link.get("link_id", link.get("id", "")))
+        flow = link.get("flow", 0)
+        status = str(link.get("status", "Open"))
+
+        # 忽略非 Open 管段和零流量管段（大小写不敏感）
+        if status.upper() != "OPEN":
+            closed_or_zero += 1
+            continue
+        if abs(flow) < 1e-6:
+            closed_or_zero += 1
+            continue
+
+        # 查找管段对应的节点对
+        pair = pipe_to_nodes.get(lid)
+        if pair is None:
+            missing += 1
+            continue
+
+        n1, n2 = pair
+        if flow > 0:
+            digraph.setdefault(n1, set()).add(n2)
+        else:
+            digraph.setdefault(n2, set()).add(n1)
+
+    if missing > 0:
+        print(f"[WARN] {missing} 条模拟管段未在管道拓扑中找到对应节点对", file=sys.stderr)
+    if closed_or_zero > 0:
+        print(f"[INFO] 忽略 {closed_or_zero} 条 Closed/零流量管段", file=sys.stderr)
+
+    return digraph
+
+
+def bfs_from_sources(sources: list, digraph: dict) -> dict:
+    """
+    多水源 BFS 下游遍历。首次访问的节点归属到对应水源。
+    返回: { node_id: source_id }
+    """
+    node_area = {}
+    queue = deque()
+
+    # 初始化：所有水源入队，归属自身
+    for src in sources:
+        node_area[src] = src
+        queue.append(src)
+
+    while queue:
+        cur = queue.popleft()
+        cur_source = node_area[cur]
+        for nb in digraph.get(cur, set()):
+            if nb not in node_area:
+                node_area[nb] = cur_source
+                queue.append(nb)
+
+    return node_area
+
+
+def generate_render_data(node_area: dict, sources: list) -> dict:
+    """
+    生成 render_junctions 所需的渲染数据。
+    返回:
+      node_area_map: { node_id: area_id }
+      area_ids: 水源 ID 列表
+      area_colors: { area_id: color_hex }
+    """
+    # 为每个水源分配颜色
+    area_colors = {}
+    for i, src in enumerate(sources):
+        area_colors[src] = PALETTE[i % len(PALETTE)]
+
+    return {
+        "node_area_map": node_area,
+        "area_ids": sources,
+        "area_colors": area_colors,
+    }
+
+
+def compute_stats(node_area: dict, sources: list, all_nodes: set) -> dict:
+    """计算各水源服务节点数和覆盖率统计。"""
+    source_counts = {}
+    for src in sources:
+        source_counts[src] = sum(1 for v in node_area.values() if v == src)
+
+    total = len(all_nodes)
+    assigned = len(node_area)
+    unassigned = total - assigned
+    coverage = (assigned / total * 100) if total > 0 else 0
+
+    return {
+        "total_nodes": total,
+        "assigned_nodes": assigned,
+        "unassigned_nodes": unassigned,
+        "coverage_pct": round(coverage, 2),
+        "source_counts": source_counts,
+    }
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="水源服务范围分析 — 基于水力模拟流向的多源 BFS 分区"
+    )
+    parser.add_argument("sim_file", help="runprojectreturndict 模拟结果 JSON")
+    parser.add_argument("pipes_file", help="getallpipeproperties 管道属性 JSON")
+    parser.add_argument("reservoirs_file", help="getallreservoirproperties 水库属性 JSON")
+    parser.add_argument("--output", "-o", default="/tmp/opencode/service_area_result.json",
+                        help="输出 JSON 文件路径")
+    parser.add_argument("--network", "-n", default="tjwater",
+                        help="管网名称（仅用于报告标注）")
+    args = parser.parse_args()
+
+    # ── 1. 加载数据 ──
+    print(f"[INFO] 加载模拟结果: {args.sim_file}")
+    sim_data = load_json(args.sim_file)
+    link_results = sim_data.get("link_results", [])
+
+    print(f"[INFO] 加载管道属性: {args.pipes_file}")
+    pipes = load_json(args.pipes_file)
+
+    print(f"[INFO] 加载水库列表: {args.reservoirs_file}")
+    reservoirs = load_json(args.reservoirs_file)
+
+    # 提取水源 ID 列表
+    sources = []
+    if isinstance(reservoirs, list):
+        sources = [str(r.get("id", r.get("name", ""))) for r in reservoirs if r.get("id") or r.get("name")]
+    elif isinstance(reservoirs, dict):
+        # 可能是 { data: [...] } 格式
+        for key in ["data", "items", "reservoirs"]:
+            if key in reservoirs and isinstance(reservoirs[key], list):
+                sources = [str(r.get("id", r.get("name", ""))) for r in reservoirs[key] if r.get("id") or r.get("name")]
+                break
+        if not sources:
+            # 也可能是 { "551656": {...}, ... } 格式
+            sources = [str(k) for k in reservoirs if isinstance(reservoirs[k], dict)]
+
+    if not sources:
+        print("[ERROR] 未能从水库数据中提取水源 ID 列表", file=sys.stderr)
+        sys.exit(1)
+
+    print(f"[INFO] 水源数: {len(sources)}")
+    print(f"[INFO] 水源列表: {sources}")
+
+    # ── 2. 构建无向图 ──
+    adj, edge_map = build_undirected_graph(pipes)
+    all_nodes = set(adj.keys())
+
+    # ── 3. 构建有向图 ──
+    digraph = build_directed_graph(adj, edge_map, link_results)
+
+    # ── 4. BFS 下游遍历 ──
+    print("[INFO] 执行多源 BFS 下游遍历...")
+    node_area = bfs_from_sources(sources, digraph)
+
+    # ── 5. 统计 ──
+    stats = compute_stats(node_area, sources, all_nodes)
+    print(f"[INFO] 总节点数: {stats['total_nodes']}")
+    print(f"[INFO] 已分配: {stats['assigned_nodes']} ({stats['coverage_pct']:.1f}%)")
+    print(f"[INFO] 未分配: {stats['unassigned_nodes']}")
+
+    print("\n各水源服务节点数 (按数量降序):")
+    for src, count in sorted(stats["source_counts"].items(), key=lambda x: -x[1]):
+        pct = (count / stats["assigned_nodes"] * 100) if stats["assigned_nodes"] > 0 else 0
+        print(f"  {src}: {count} ({pct:.1f}%)")
+
+    # ── 6. 生成渲染数据 ──
+    render = generate_render_data(node_area, sources)
+
+    # ── 7. 输出 ──
+    output = {
+        "network": args.network,
+        "stats": stats,
+        "render": render,
+        "sources": sources,
+    }
+
+    os.makedirs(os.path.dirname(args.output) or ".", exist_ok=True)
+    with open(args.output, "w", encoding="utf-8") as f:
+        json.dump(output, f, ensure_ascii=False, indent=2)
+
+    print(f"\n[OK] 结果已写入: {args.output}")
+
+
+if __name__ == "__main__":
+    main()
@@ -8,12 +8,12 @@ const initializePromise = toolContextStore.initialize();

 export default tool({
  description:
-    "回读由 dynamic_http_call 生成的持久化 result_ref。适用于大结果只返回 preview 时，再按需读取完整或截断后的数据。",
+    "回读持久化 result_ref。适用于大结果只返回 preview 时，按需读取完整或截断后的数据。仅用于仍使用 referenced 模式的遗留接口。",
  args: {
    reason: tool.schema
      .string()
      .describe("Why the stored result needs to be read for the current user request."),
-    result_ref: tool.schema.string().describe("The result_ref returned by dynamic_http_call."),
+    result_ref: tool.schema.string().describe("The result_ref handle."),
    max_items: tool.schema
      .number()
      .int()
@@ -8,20 +8,20 @@ const initializePromise = toolContextStore.initialize();

 export default tool({
  description:
-    "通过本地 Agent 桥接调用 TJWater 后端 API。需提供 API 路径、可选的请求方法以及查询参数。",
+    "通过本地 Agent 桥接调用 tjwater-cli 命令访问 TJWater 后端。提供 CLI 子命令和参数。",
  args: {
    reason: tool.schema
      .string()
      .describe("Why this tool call is required for the current user request."),
-    path: tool.schema.string().describe("Target backend API path, starting with '/'."),
-    method: tool.schema
+    command: tool.schema
      .string()
+      .describe(
+        "tjwater-cli 子命令，不含二进制路径。示例：'project list'、'data timeseries realtime links --start-time 2025-01-01T00:00:00+08:00 --end-time 2025-01-01T01:00:00+08:00'",
+      ),
+    timeout: tool.schema
+      .number()
      .optional()
-      .describe("HTTP method. Defaults to GET."),
-    arguments: tool.schema
-      .record(tool.schema.string(), tool.schema.unknown())
-      .optional()
-      .describe("Query arguments object."),
+      .describe("超时秒数，默认 120。大结果集建议设 300+。"),
  },
  async execute(args, context) {
    await initializePromise;
@@ -29,8 +29,7 @@ export default tool({
    if (!sessionContext) {
      throw new Error(`session context not found for ${context.sessionID}`);
    }
-    // 工具本身不直接持有用户 token；通过 sessionID 回调 Agent 服务，由服务侧补齐用户上下文。
-    const response = await fetch(`${internalBaseUrl}/internal/tools/dynamic-http-call`, {
+    const response = await fetch(`${internalBaseUrl}/internal/tools/tjwater-cli-call`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
@@ -39,9 +38,8 @@ export default tool({
      body: JSON.stringify({
        sessionScopeKey: sessionContext.sessionScopeKey,
        reason: args.reason,
-        path: args.path,
-        method: args.method,
-        arguments: args.arguments,
+        command: args.command,
+        timeout: args.timeout,
      }),
    });

@@ -32,7 +32,7 @@ TJWaterAgent/
 3. 管理前端 `session_id -> opencode sessionId` 的映射。
 4. 保存并传递用户 `Authorization`、`x-user-id`、`x-project-id`、`x-trace-id`。
 5. 把 opencode 输出适配成前端需要的 SSE 事件。
-6. 为 `.opencode/tools/dynamic_http_call.ts` 提供内部回调接口。
+6. 为 `.opencode/tools/tjwater_cli.ts` 提供内部回调接口。
 7. 代理调用真实 TJWater 后端 API。

 当前 Agent API 的主入口：
@@ -84,7 +84,7 @@ src/

 ```text
 .opencode/tools/
-  dynamic_http_call.ts
+  tjwater_cli.ts
  locate_features.ts
  view_history.ts
  view_scada.ts
@@ -93,25 +93,28 @@ src/

 这些是 opencode 可以调用的自定义工具。

-`dynamic_http_call.ts` 不直接保存用户 token，也不直接访问后端。它会回调 `TJWaterAgent` 的内部接口，由上级服务层根据当前 session 补上用户 token、项目 ID 和 trace ID，再调用 TJWater 后端。
+`tjwater_cli.ts` 不直接保存用户 token。它会回调 `TJWaterAgent` 的内部接口，由上级服务层根据当前 session 补上用户 token、项目 ID 和 trace ID，再调用 `tjwater-cli` 二进制执行后端命令。

 前端类工具如 `locate_features`、`view_history`、`view_scada`、`show_chart` 主要用于触发 UI 动作或可视化，不应被当作数据查询工具。

 ### skills

 ```text
-.opencode/skills/tjwater-skills-root-index/
+.opencode/skills/
  SKILL.md
-  ai/
-  analytics/
-  business/
-  data/
-  platform/
+  examples.md
+  runbook.md
+  tjwater-cli/      ← tjwater-cli 可执行文件
+  workflow/         ← 可复用分析工作流
+    SKILL.md
+    simulation-diagnosis/
+    bottleneck-analysis/
+    source-service-area-analysis/
 ```

-这里保存 TJWater 技能树，并保持树结构，符合渐进式披露设计。
+Skills 仅保留可复用的多步工作流。Agent 通过 `tjwater-cli help` 自行发现原子命令，无需逐接口技能树。

-agent 需要某个领域知识时再按需加载对应 skill，不把整棵技能树作为 always-loaded prompt 一次性注入。
+agent 加载技能树时按需取用对应 workflow skill。

 ## 依赖边界

@@ -2,14 +2,40 @@ import pino from "pino";

 import { config } from "./config.js";

+const pad = (value: number) => value.toString().padStart(2, "0");
+
+const padMilliseconds = (value: number) => value.toString().padStart(3, "0");
+
+const formatLocalTimestamp = (date: Date) => {
+  const year = date.getFullYear();
+  const month = pad(date.getMonth() + 1);
+  const day = pad(date.getDate());
+  const hours = pad(date.getHours());
+  const minutes = pad(date.getMinutes());
+  const seconds = pad(date.getSeconds());
+  const milliseconds = padMilliseconds(date.getMilliseconds());
+  const offsetMinutes = -date.getTimezoneOffset();
+  const sign = offsetMinutes >= 0 ? "+" : "-";
+  const absoluteOffsetMinutes = Math.abs(offsetMinutes);
+  const offsetHours = pad(Math.floor(absoluteOffsetMinutes / 60));
+  const offsetRemainderMinutes = pad(absoluteOffsetMinutes % 60);
+
+  return `${year}-${month}-${day}T${hours}:${minutes}:${seconds}.${milliseconds}${sign}${offsetHours}:${offsetRemainderMinutes}`;
+};
+
 export const logger = pino({
  level: config.LOG_LEVEL,
+  formatters: {
+    level: (label) => ({ level: label }),
+  },
+  timestamp: () => `,"time":"${formatLocalTimestamp(new Date())}"`,
  transport:
    config.NODE_ENV === "development"
      ? {
          target: "pino-pretty",
          options: {
            colorize: true,
+            translateTime: "SYS:yyyy-mm-dd HH:MM:ss.l o",
          },
        }
      : undefined,