docs: add repository guidelines

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

.dockerignore

@@ -1,5 +1,4 @@
 .git
-.gitignore
 node_modules
 .opencode/node_modules
 .local.env

.gitea/workflows/package.yml

@@ -0,0 +1,219 @@
+name: Agent CI/CD
+
+on:
+  push:
+    tags:
+      - "v*"
+      - "latest"
+  workflow_dispatch: {}
+
+jobs:
+  docker-image:
+    runs-on: ubuntu-22.04
+    if: startsWith(github.ref, 'refs/tags/')
+    permissions:
+      contents: read
+    defaults:
+      run:
+        shell: bash
+
+    steps:
+      - name: Setup tools
+        run: |
+          sudo apt-get update -qq && sudo apt-get install -y -qq jq
+          jq --version
+
+      - name: Checkout code
+        env:
+          SERVER_URL: ${{ github.server_url }}
+          REPOSITORY: ${{ github.repository }}
+          COMMIT_SHA: ${{ github.sha }}
+          GIT_USERNAME: ${{ github.actor }}
+          GIT_TOKEN: ${{ github.token }}
+        run: |
+          case "$SERVER_URL" in
+            http://*)
+              AUTH_SERVER_URL="http://${GIT_USERNAME}:${GIT_TOKEN}@${SERVER_URL#http://}"
+              ;;
+            https://*)
+              AUTH_SERVER_URL="https://${GIT_USERNAME}:${GIT_TOKEN}@${SERVER_URL#https://}"
+              ;;
+            *)
+              AUTH_SERVER_URL="$SERVER_URL"
+              ;;
+          esac
+
+          if [ ! -d .git ]; then
+            git init .
+          fi
+
+          if git remote get-url origin >/dev/null 2>&1; then
+            git remote set-url origin "${AUTH_SERVER_URL}/${REPOSITORY}.git"
+          else
+            git remote add origin "${AUTH_SERVER_URL}/${REPOSITORY}.git"
+          fi
+
+          git fetch --depth=1 origin "$COMMIT_SHA"
+          git checkout --force --detach FETCH_HEAD
+          git clean -ffdx
+
+      - name: Normalize image metadata
+        env:
+          RAW_REGISTRY_HOST: ${{ vars.REGISTRY_HOST }}
+          RAW_REPOSITORY: ${{ github.repository }}
+          RAW_REF: ${{ github.ref }}
+          RAW_REF_NAME: ${{ github.ref_name }}
+        run: |
+          RAW_REGISTRY_HOST="$(printf '%s' "${RAW_REGISTRY_HOST}" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')"
+
+          if [ -z "${RAW_REGISTRY_HOST}" ]; then
+            echo "Missing required repository variable: REGISTRY_HOST"
+            exit 1
+          fi
+
+          REGISTRY_HOST="${RAW_REGISTRY_HOST#http://}"
+          REGISTRY_HOST="${REGISTRY_HOST#https://}"
+          REGISTRY_HOST="${REGISTRY_HOST%/}"
+
+          if [ -z "${REGISTRY_HOST}" ]; then
+            echo "Repository variable REGISTRY_HOST resolves to an empty host"
+            exit 1
+          fi
+
+          REPOSITORY_PATH="${RAW_REPOSITORY#/}"
+          IMAGE_REPOSITORY_PATH="$(printf '%s' "$REPOSITORY_PATH" | tr '[:upper:]' '[:lower:]')"
+          IMAGE_NAME="${REGISTRY_HOST}/${IMAGE_REPOSITORY_PATH}"
+          IMAGE_TAG="${RAW_REF_NAME}"
+          {
+            echo "REGISTRY_HOST=${REGISTRY_HOST}"
+            echo "REPOSITORY_PATH=${REPOSITORY_PATH}"
+            echo "IMAGE_REPOSITORY_PATH=${IMAGE_REPOSITORY_PATH}"
+            echo "IMAGE_NAME=${IMAGE_NAME}"
+            echo "IMAGE_TAG=${IMAGE_TAG}"
+            echo "IMAGE_REF=${IMAGE_NAME}:${IMAGE_TAG}"
+          } >> "$GITHUB_ENV"
+
+      - name: Login to Gitea Container Registry
+        env:
+          REGISTRY_USERNAME: ${{ secrets.REGISTRY_USERNAME }}
+          REGISTRY_PASSWORD: ${{ secrets.REGISTRY_PASSWORD }}
+        run: |
+          if [ -z "${REGISTRY_HOST:-}" ]; then
+            echo "Missing resolved environment value: REGISTRY_HOST"
+            echo "The previous step should write REGISTRY_HOST into GITHUB_ENV."
+            exit 1
+          fi
+
+          if [ -z "${REGISTRY_USERNAME}" ]; then
+            echo "Missing required repository secret: REGISTRY_USERNAME"
+            exit 1
+          fi
+
+          if [ -z "${REGISTRY_PASSWORD}" ]; then
+            echo "Missing required repository secret: REGISTRY_PASSWORD"
+            exit 1
+          fi
+
+          echo "Logging into registry host: ${REGISTRY_HOST}"
+          echo "${REGISTRY_PASSWORD}" | docker login "$REGISTRY_HOST" \
+            --username "${REGISTRY_USERNAME}" \
+            --password-stdin
+
+      - name: Build and Push Image
+        run: |
+          if [ -z "${IMAGE_NAME:-}" ] || [ -z "${IMAGE_TAG:-}" ]; then
+            echo "Missing resolved image metadata: IMAGE_NAME or IMAGE_TAG"
+            exit 1
+          fi
+
+          push_with_retry() {
+            image_ref="$1"
+            attempt=1
+            max_attempts=3
+
+            while [ "$attempt" -le "$max_attempts" ]; do
+              if docker push "$image_ref"; then
+                return 0
+              fi
+
+              if [ "$attempt" -eq "$max_attempts" ]; then
+                return 1
+              fi
+
+              echo "Push failed for $image_ref (attempt $attempt/$max_attempts); retrying in 10s..."
+              attempt=$((attempt + 1))
+              sleep 10
+            done
+          }
+
+          if [ "${IMAGE_TAG}" = "latest" ]; then
+            docker build \
+              -f ./Dockerfile \
+              -t "${IMAGE_NAME}:latest" \
+              .
+            push_with_retry "${IMAGE_NAME}:latest"
+          else
+            docker build \
+              -f ./Dockerfile \
+              -t "${IMAGE_NAME}:${IMAGE_TAG}" \
+              -t "${IMAGE_NAME}:latest" \
+              .
+            push_with_retry "${IMAGE_NAME}:${IMAGE_TAG}"
+            push_with_retry "${IMAGE_NAME}:latest"
+          fi
+
+      - name: Notify Deploy Server
+        run: |
+          post_deploy_webhook() {
+            label="$1"
+            payload="$2"
+            webhook_url="${{ vars.DEPLOY_WEBHOOK_URL }}"
+            token="${{ secrets.DEPLOY_WEBHOOK_TOKEN }}"
+
+            # Trim whitespace
+            webhook_url=$(echo "$webhook_url" | xargs)
+
+            echo "[$label] Calling webhook: $webhook_url"
+
+            http_code=$(curl -sS -D /tmp/deploy_headers.txt -o /tmp/deploy_response.txt -w "%{http_code}" -X POST "$webhook_url" \
+              -H "Content-Type: application/json" \
+              -H "Authorization: Bearer $token" \
+              -d "$payload")
+
+            echo "[$label] webhook HTTP status: ${http_code}"
+            if [ "$http_code" -ge 200 ] && [ "$http_code" -lt 300 ]; then
+              return 0
+            fi
+
+            echo "[$label] response headers:"
+            cat /tmp/deploy_headers.txt
+            echo "[$label] response body:"
+            cat /tmp/deploy_response.txt
+            return 1
+          }
+
+          PRIMARY_PAYLOAD="{\"image\":\"${IMAGE_REF}\",\"tag\":\"${IMAGE_TAG}\",\"repo\":\"${REPOSITORY_PATH}\"}"
+          FALLBACK_PAYLOAD="{\"image\":\"${IMAGE_REF}\",\"tag\":\"${IMAGE_TAG}\",\"repo\":\"${IMAGE_REPOSITORY_PATH}\"}"
+
+          echo "Deploy webhook target: ${{ vars.DEPLOY_WEBHOOK_URL }}"
+          echo "Deploy payload(primary): image=${IMAGE_REF}, tag=${IMAGE_TAG}, repo=${REPOSITORY_PATH}"
+          if post_deploy_webhook "primary" "$PRIMARY_PAYLOAD"; then
+            exit 0
+          fi
+
+          echo "Primary webhook request failed, retrying with lowercase repo path..."
+          echo "Deploy payload(fallback): image=${IMAGE_REF}, tag=${IMAGE_TAG}, repo=${IMAGE_REPOSITORY_PATH}"
+          if post_deploy_webhook "fallback" "$FALLBACK_PAYLOAD"; then
+            exit 0
+          fi
+
+          echo "Deploy webhook failed after primary and fallback attempts."
+          exit 1
+
+  deploy-fallback-log:
+    runs-on: ubuntu-22.04
+    needs: docker-image
+    if: failure()
+    steps:
+      - name: Deployment not triggered
+        run: echo "Image build/push failed, deployment webhook was not called."

.gitignore

@@ -1,4 +1,11 @@
 node_modules/
+__pycache__/
 .opencode/node_modules/
+.opencode/skills/
 .local.env
-.vscode
+.vscode
+docker-compose.yml
+data/
+logs/
+AGENT_HARNESS_REPORT.md
+HARNESS_INTRODUCTION.md

.opencode/.gitignore

@@ -0,0 +1,3 @@
+node_modules
+package-lock.json
+.gitignore

.opencode/agents/agent.md

@@ -1,16 +0,0 @@
----
-description: TJWater Agent，用于供水网络分析和操作员工作流
-mode: primary
-model: deepseek/deepseek-v4-pro
-temperature: 0.2
----
-您是运行在 opencode 上的默认 TJWater Agent。
-
-按照以下规则操作：
-
-1. 使用 `.opencode/skills/tjwater-skills-root-index` 作为 TJWater 技能树，仅在任务需要该领域知识时加载特定技能。
-2. 当您需要后端数据用于推理、总结、诊断或分析时，优先使用 `dynamic_http_call`。
-3. 当用户主要需要 UI 操作或可视化时，优先使用前端工具（`locate_features`、`view_history`、`view_scada`、`show_chart`）。
-4. 仅将前端工具视为显示/交互工具，不要假设它们返回数据。
-5. 保持回复准确、简洁，对供水网络用户在操作上有用。
-6. 尊重用户授权和项目隔离，工具调用失败或无可用数据时，切勿编造后端结果。

.opencode/agents/instruction.md

@@ -0,0 +1,99 @@
+---
+description: TJWater Agent，用于供水网络分析和操作员工作流
+mode: primary
+model: deepseek/deepseek-v4-pro
+temperature: 0.2
+---
+你是 TJWater 供水管网分析 Agent，运用水力专业知识，回复用户时使用简体中文，内容要求简洁准确。
+
+## 工作流生命周期
+
+Skills 树是**动态生长的**——工作流不是预置的，而是从实际任务中沉淀出来的：
+```
+初次遇到问题 → tjwater_cli + Python 脚本拼装 → 验证有效 →
+    → 立即调用 skill_manager 保存到 skills/workflow/<name>/
+    → 下次遇到同类问题直接加载该 skill，按既定步骤执行
+```
+
+## 任务执行决策
+
+收到用户请求时，按以下顺序决策：
+
+1. **查已有工作流** — 检查 `skills/workflow/` 下是否存在匹配的 SKILL.md，有则加载并按步骤执行
+2. **历史参考** — 用 `session_search` 检索历史相似案例，避免重复试错
+3. **从零拼装** — 无匹配工作流时，自行组合 `tjwater_cli` 命令 + Python 脚本完成
+4. **完成后复盘** — 判断当前流程是否稳定、可复用，决定是否沉淀为 workflow
+
+## 工具选择
+
+| 场景 | 工具 |
+|------|------|
+| 获取后端数据（数据源、推理、分析） | `tjwater_cli` |
+| 发现可用命令 | `tjwater_cli(command="help")` |
+| 查询实时公开网页信息 | `web_search` |
+| 地址/地点转经纬度 | `geocode` |
+| UI 操作 / 可视化 | `locate_features`、`zoom_to_map`、`view_scada`、`show_chart`、`render_junctions`、`view_history`、`apply_layer_style` |
+| 持久化渲染数据 | ①准备 { node_area_map } JSON → ②`store_render_ref` 存为受控 ref → ③`render_junctions` 渲染到前端 |
+
+**前端工具仅做显示，不返回数据**，不要假设其返回内容。
+
+## 执行约束
+
+1. 每次工具调用必须在 `reason` 字段填写具体理由
+2. `tjwater-cli` 输出为 JSON（`schema_version: tjwater-cli/v1`），`"ok": true` 成功，失败时检查 `error.code`
+3. 大结果集禁止完整读取，优先采样/截断/按字段读取
+4. 避免直接用 `Read` 或 `cat` 读取结果文件，尤其是大文件；优先用 `head`/`tail`/`rg` 截断查看，或用 Python 只向 stdout 输出精简 JSON，避免大文件冲击 stdin/stdout
+5. 无可用数据时不得编造结果
+6. 尽量不使用 `task` 子代理，避免无法观测过程进行人为干预
+
+## 工作流沉淀（skill_manager）
+
+**写入条件**（必须同时满足）：
+- 经过当前对话验证有效
+- 可被未来同类任务复用
+- 非一次性/临时/猜测
+
+**写入位置**：`skills/workflow/<name>/`，包含 SKILL.md（步骤说明）、references/*.md（参考材料）和 scripts/*.py（分析脚本）。
+
+**工具动作**：`write_skill / remove_skill` 维护主 SKILL.md；`append_pattern / remove_pattern` 维护 `## Learned Patterns`；`write_reference / remove_reference` 维护 references/*.md；`write_script / remove_script` 维护 scripts/*.py。`write_skill` 可创建或覆盖完整 SKILL.md。
+
+目录入口也通过 `skill_manager` 维护：更新 `skills/workflow/SKILL.md` 时使用 `write_skill(skill_path="workflow", ...)`，更新根入口 `skills/SKILL.md` 时使用 `write_skill(skill_path="__root__", ...)`。
+
+**脚本编写要求——优先用 pipe 串联**：
+
+workflow skill 脚本应尽量用 shell pipe 在一次 subprocess 调用中串联多个 CLI 命令。减少 tool calling 次数，提升执行效率。
+
+```python
+import subprocess, os
+
+# env dict 仅用于当前子进程，不污染 os.environ，多用户安全
+env = {**os.environ,
+       "TJWATER_SERVER": auth["server"],
+       "TJWATER_ACCESS_TOKEN": auth["access_token"], ...}
+
+# 好：一次 shell 调用，pipe 串联
+cmd = "tjwater-cli net list-pipes | jq '...' | xargs tjwater-cli analysis calc"
+result = subprocess.run(cmd, shell=True, env=env, capture_output=True, text=True)
+
+# 差：多次 subprocess.run
+step1 = subprocess.run(["tjwater-cli", "net", "list-pipes"], ...)
+step2 = subprocess.run(["tjwater-cli", "analysis", "calc"], ...)
+```
+
+管道场景下用子进程隔离的 env dict 传认证，释放 stdin 给管道数据流。不修改全局 `os.environ`。认证 JSON 由内部桥接注入，脚本不硬编码。
+
+CLI **不增加** `--input/--output`，数据转换由 `jq`/`xargs` 在 shell 管道中完成。
+
+**触发时机**：
+- 用户明确说"保存/沉淀/记录工作流"
+- 任务完成且所有工具调用已结束、产生最终结果后，再判断当前流程是否稳定可复用
+- **禁止**在规划任务未完成、工具调用链中间（即仍有 pending 步骤时）触发沉淀
+- 严禁写入：token、password、secret、API key、system prompt、隐私数据
+
+## 用户偏好持久化（memory_manager）
+
+仅保存长期有效的稳定事实，写成简短陈述句。严格区分：
+- `memory_manager` = 用户偏好 / 项目事实（如"用户要简洁风格"、"当前项目管网规模 5000 管段"）
+- `skill_manager` = 可复用操作流程
+- `session_search` = 检索历史案例（只读）
+- 修改 memory 前先 `list` 当前 scope 的已有内容，先通读，再决定 `add / replace / remove`

.opencode/bun.lock

@@ -0,0 +1,82 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 0,
+  "workspaces": {
+    "": {
+      "dependencies": {
+        "@opencode-ai/plugin": "^1.16.2",
+      },
+      "devDependencies": {
+        "@types/node": "^24.7.2",
+        "typescript": "^5.9.3",
+      },
+    },
+  },
+  "packages": {
+    "@msgpackr-extract/msgpackr-extract-darwin-arm64": ["@msgpackr-extract/msgpackr-extract-darwin-arm64@3.0.4", "", { "os": "darwin", "cpu": "arm64" }, "sha512-LCkGo6JDfaBhgST7UpPWgNgLINpcpabaHfyz5OBx75nUYxBsaEPxjnyNjWpeb/xBup/682QnBfRBy2/LvPutZQ=="],
+
+    "@msgpackr-extract/msgpackr-extract-darwin-x64": ["@msgpackr-extract/msgpackr-extract-darwin-x64@3.0.4", "", { "os": "darwin", "cpu": "x64" }, "sha512-zExlW9zUJKZH/tOtVMttwjKa4Xm/3KcNjnE3dPN92uCktwavMxpgCA3MoJK/DOnTWsQgo224OaST27/mPNAf+w=="],
+
+    "@msgpackr-extract/msgpackr-extract-linux-arm": ["@msgpackr-extract/msgpackr-extract-linux-arm@3.0.4", "", { "os": "linux", "cpu": "arm" }, "sha512-Tg3yX65f5GbtXLkrYEHE5oibZG9epyYWas7FogTTEJeDEF9JlXJzKgXaNhT3UXlTOeA+AfZpYZYZ0uPj7Cfquw=="],
+
+    "@msgpackr-extract/msgpackr-extract-linux-arm64": ["@msgpackr-extract/msgpackr-extract-linux-arm64@3.0.4", "", { "os": "linux", "cpu": "arm64" }, "sha512-dgX0P/9wGPJeHFBG+ZmhgE6bmtMt7NP5CRBGyyktpopdk/mW4POnrpQsSLtKI1dwpc+pPLuXHDh6vvskyQE/sw=="],
+
+    "@msgpackr-extract/msgpackr-extract-linux-x64": ["@msgpackr-extract/msgpackr-extract-linux-x64@3.0.4", "", { "os": "linux", "cpu": "x64" }, "sha512-8TNXMEjJc3QEy7R/x1INhgiU+XakDAFUzBhaz7+Rbrs8NH5UQeHQxxmzsSBJGyV6I1jW79undiQm8tOI+D+8FQ=="],
+
+    "@msgpackr-extract/msgpackr-extract-win32-x64": ["@msgpackr-extract/msgpackr-extract-win32-x64@3.0.4", "", { "os": "win32", "cpu": "x64" }, "sha512-CmCXPQrkbwExx3j946/PtHWHbYJiCRBRDl4BlkRQcJB/YOwQxJRTpoo7aTsortjgoJ1x7opzTSxn7C+ASSLVjQ=="],
+
+    "@opencode-ai/plugin": ["@opencode-ai/plugin@1.16.2", "", { "dependencies": { "@opencode-ai/sdk": "1.16.2", "effect": "4.0.0-beta.74", "zod": "4.1.8" }, "peerDependencies": { "@opentui/core": ">=0.3.2", "@opentui/keymap": ">=0.3.2", "@opentui/solid": ">=0.3.2" }, "optionalPeers": ["@opentui/core", "@opentui/keymap", "@opentui/solid"] }, "sha512-FaZhVXrbz93xsdGLCtarRDTeqFt8AkLfh8B34tFBj6G4HXVmKSgBwVXmtELKKC+08xMtawBC9hshiMbXryv6cg=="],
+
+    "@opencode-ai/sdk": ["@opencode-ai/sdk@1.16.2", "", { "dependencies": { "cross-spawn": "7.0.6" } }, "sha512-Z/xZ7q79dYeE0afqIk/yFEcRNGEQFcE+H8ssYivUiy+xGZ1mGwT72jpaQZKBwPn3JH4sRCu4KA2lcktBQfcOjg=="],
+
+    "@standard-schema/spec": ["@standard-schema/spec@1.1.0", "", {}, "sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w=="],
+
+    "@types/node": ["@types/node@24.12.4", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-GUUEShf+PBCGW2KaXwcIt3Yk+e3pkKwWKb9GSyM9WQVE+ep2jzmHdGsHzu4wgcZy5fN9FBdVzjpBQsYlpfpgLA=="],
+
+    "cross-spawn": ["cross-spawn@7.0.6", "", { "dependencies": { "path-key": "^3.1.0", "shebang-command": "^2.0.0", "which": "^2.0.1" } }, "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA=="],
+
+    "detect-libc": ["detect-libc@2.1.2", "", {}, "sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ=="],
+
+    "effect": ["effect@4.0.0-beta.74", "", { "dependencies": { "@standard-schema/spec": "^1.1.0", "fast-check": "^4.8.0", "find-my-way-ts": "^0.1.6", "ini": "^7.0.0", "kubernetes-types": "^1.30.0", "msgpackr": "^2.0.1", "multipasta": "^0.2.7", "toml": "^4.1.1", "uuid": "^14.0.0", "yaml": "^2.9.0" } }, "sha512-Yx+Kh12U+i2FmjwEfKs+ePFmpMd43RPD1oGqc/VraSS9bYzvF0Ff3PojwEFEVEewp8xc92Uxu28gTspU4qyvHA=="],
+
+    "fast-check": ["fast-check@4.8.0", "", { "dependencies": { "pure-rand": "^8.0.0" } }, "sha512-GOJ158CUMnN6cSahsv4+ExARvIDuzzinFjkp0E9WtiBa5zcVeLozVkWaE4IzFcc+Y48Wp1EDlUZsXRyAztQcSg=="],
+
+    "find-my-way-ts": ["find-my-way-ts@0.1.6", "", {}, "sha512-a85L9ZoXtNAey3Y6Z+eBWW658kO/MwR7zIafkIUPUMf3isZG0NCs2pjW2wtjxAKuJPxMAsHUIP4ZPGv0o5gyTA=="],
+
+    "ini": ["ini@7.0.0", "", {}, "sha512-ifK0CgjALofS5bkrcTy4RaQ9Vx2Knf/eLeIO+NaswQEpH1UblrtTSCIvN71qQDMq0PeQ/SSPojvEJp9vvvfr+w=="],
+
+    "isexe": ["isexe@2.0.0", "", {}, "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw=="],
+
+    "kubernetes-types": ["kubernetes-types@1.30.0", "", {}, "sha512-Dew1okvhM/SQcIa2rcgujNndZwU8VnSapDgdxlYoB84ZlpAD43U6KLAFqYo17ykSFGHNPrg0qry0bP+GJd9v7Q=="],
+
+    "msgpackr": ["msgpackr@2.0.2", "", { "optionalDependencies": { "msgpackr-extract": "^3.0.4" } }, "sha512-c5hYOXFbP79Slh6Dzd2wzk+jnV7mX1UxfMYtilnY1NmalXPqG8DGb5cYCMBrW4AsH3zekBBZd4QrKz9NhtvYLQ=="],
+
+    "msgpackr-extract": ["msgpackr-extract@3.0.4", "", { "dependencies": { "node-gyp-build-optional-packages": "5.2.2" }, "optionalDependencies": { "@msgpackr-extract/msgpackr-extract-darwin-arm64": "3.0.4", "@msgpackr-extract/msgpackr-extract-darwin-x64": "3.0.4", "@msgpackr-extract/msgpackr-extract-linux-arm": "3.0.4", "@msgpackr-extract/msgpackr-extract-linux-arm64": "3.0.4", "@msgpackr-extract/msgpackr-extract-linux-x64": "3.0.4", "@msgpackr-extract/msgpackr-extract-win32-x64": "3.0.4" }, "bin": { "download-msgpackr-prebuilds": "bin/download-prebuilds.js" } }, "sha512-4kmO/MdyUIkLIvTPr8VHLil4AtoKIoniWPIEk5+CDy0xnWC84azhSFmuJ7PxZdsYtiP5kEeQsORAVIeMgxT+Hw=="],
+
+    "multipasta": ["multipasta@0.2.7", "", {}, "sha512-KPA58d68KgGil15oDqXjkUBEBYc00XvbPj5/X+dyzeo/lWm9Nc25pQRlf1D+gv4OpK7NM0J1odrbu9JNNGvynA=="],
+
+    "node-gyp-build-optional-packages": ["node-gyp-build-optional-packages@5.2.2", "", { "dependencies": { "detect-libc": "^2.0.1" }, "bin": { "node-gyp-build-optional-packages": "bin.js", "node-gyp-build-optional-packages-optional": "optional.js", "node-gyp-build-optional-packages-test": "build-test.js" } }, "sha512-s+w+rBWnpTMwSFbaE0UXsRlg7hU4FjekKU4eyAih5T8nJuNZT1nNsskXpxmeqSK9UzkBl6UgRlnKc8hz8IEqOw=="],
+
+    "path-key": ["path-key@3.1.1", "", {}, "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q=="],
+
+    "pure-rand": ["pure-rand@8.4.0", "", {}, "sha512-IoM8YF/jY0hiugFo/wOWqfmarlE6J0wc6fDK1PhftMk7MGhVZl88sZimmqBBFomLOCSmcCCpsfj7wXASCpvK9A=="],
+
+    "shebang-command": ["shebang-command@2.0.0", "", { "dependencies": { "shebang-regex": "^3.0.0" } }, "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA=="],
+
+    "shebang-regex": ["shebang-regex@3.0.0", "", {}, "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A=="],
+
+    "toml": ["toml@4.1.1", "", {}, "sha512-EBJnVBr3dTXdA89WVFoAIPUqkBjxPMwRqsfuo1r240tKFHXv3zgca4+NJib/h6TyvGF7vOawz0jGuryJCdNHrw=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],
+
+    "uuid": ["uuid@14.0.0", "", { "bin": { "uuid": "dist-node/bin/uuid" } }, "sha512-Qo+uWgilfSmAhXCMav1uYFynlQO7fMFiMVZsQqZRMIXp0O7rR7qjkj+cPvBHLgBqi960QCoo/PH2/6ZtVqKvrg=="],
+
+    "which": ["which@2.0.2", "", { "dependencies": { "isexe": "^2.0.0" }, "bin": { "node-which": "bin/node-which" } }, "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA=="],
+
+    "yaml": ["yaml@2.9.0", "", { "bin": "bin.mjs" }, "sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA=="],
+
+    "zod": ["zod@4.1.8", "", {}, ""],
+  }
+}

.opencode/package.json

@@ -0,0 +1,13 @@
+{
+  "private": true,
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@opencode-ai/plugin": "^1.16.2"
+  },
+  "devDependencies": {
+    "@types/node": "^24.7.2",
+    "typescript": "^5.9.3"
+  }
+}

.opencode/skills/SKILL.md

@@ -1,23 +0,0 @@
----
-name: tjwater-skills-root-index
-description: TJWater Skills 分层索引（Domain -> Scenario -> Action）。
-version: 1.2.0
----
-
-# TJWater Skills
-
-## 简介
-
-按“领域 (Domain) -> 场景 (Scenario) -> 操作 (Action)”组织技能文档，逐层进入具体能力。
-
-## 子模块索引 (渐进式引导)
-
-- **analytics**: 见 `./analytics/SKILL.md`
-- **business**: 见 `./business/SKILL.md`
-- **data**: 见 `./data/SKILL.md`
-- **platform**: 见 `./platform/SKILL.md`
-
-## 参考
-
-- 示例：`./examples.md`
-- 运行手册：`./runbook.md`

.opencode/skills/analytics/SKILL.md

@@ -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`
-

.opencode/skills/analytics/scada-operations/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`
-

.opencode/skills/analytics/scada-operations/scada/SKILL.md

@@ -1,50 +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` 的具体接口调用。
-
-## 子模块索引 (渐进式引导)
-- 当前为叶子节点，直接使用下方接口目录。
-
-## 接口目录
-| Method | Path | Summary | Required Params | Optional Params |
-|---|---|---|---|---|
-| POST | `/api/v1/addscadadevice/` | 添加SCADA设备 | network (query) | - |
-| POST | `/api/v1/addscadadevicedata/` | 添加SCADA设备数据 | network (query) | - |
-| POST | `/api/v1/addscadaelement/` | 添加SCADA元素映射 | network (query) | - |
-| POST | `/api/v1/cleanscadadevice/` | 清空SCADA设备表 | network (query) | - |
-| POST | `/api/v1/cleanscadadevicedata/` | 清空SCADA设备数据表 | network (query) | - |
-| POST | `/api/v1/cleanscadaelement/` | 清空SCADA元素映射表 | network (query) | - |
-| POST | `/api/v1/deletescadadevice/` | 删除SCADA设备 | network (query) | - |
-| POST | `/api/v1/deletescadadevicedata/` | 删除SCADA设备数据 | network (query) | - |
-| POST | `/api/v1/deletescadaelement/` | 删除SCADA元素映射 | network (query) | - |
-| GET | `/api/v1/getallscadadeviceids/` | 获取所有SCADA设备ID | network (query) | - |
-| GET | `/api/v1/getallscadadevices/` | 获取所有SCADA设备 | network (query) | - |
-| GET | `/api/v1/getallscadainfo/` | 获取所有SCADA信息 | network (query) | - |
-| GET | `/api/v1/getallscadaproperties/` | 获取所有SCADA属性 | network (query) | - |
-| GET | `/api/v1/getscadadevice/` | 获取SCADA设备 | network (query), id (query) | - |
-| GET | `/api/v1/getscadadevicedata/` | 获取SCADA设备数据 | network (query), device_id (query) | - |
-| GET | `/api/v1/getscadadevicedataschema/` | 获取SCADA设备数据架构 | network (query) | - |
-| GET | `/api/v1/getscadadeviceschema/` | 获取SCADA设备架构 | network (query) | - |
-| GET | `/api/v1/getscadaelement/` | 获取单个SCADA元素映射 | network (query), id (query) | - |
-| GET | `/api/v1/getscadaelements/` | 获取所有SCADA元素映射 | network (query) | - |
-| GET | `/api/v1/getscadaelementschema/` | 获取SCADA元素架构 | network (query) | - |
-| GET | `/api/v1/getscadainfo/` | 获取SCADA信息 | network (query), id (query) | - |
-| GET | `/api/v1/getscadainfoschema/` | 获取SCADA信息架构 | network (query) | - |
-| GET | `/api/v1/getscadaproperties/` | 获取SCADA属性 | network (query), scada (query) | - |
-| POST | `/api/v1/scada/batch` | 批量插入SCADA监测数据 | data (body) | - |
-| DELETE | `/api/v1/scada/by-id-time-range` | 按设备ID和时间范围删除SCADA数据 | device_id (query), start_time (query), end_time (query) | - |
-| GET | `/api/v1/scada/by-ids-field-time-range` | 按设备ID、字段和时间范围查询SCADA数据 | start_time (query), end_time (query), field (query), device_ids (query) | - |
-| GET | `/api/v1/scada/by-ids-time-range` | 按设备ID和时间范围查询SCADA数据 | start_time (query), end_time (query), device_ids (query) | - |
-| PATCH | `/api/v1/scada/{device_id}/field` | 更新SCADA设备字段 | device_id (path), time (query), field (query), value (query) | - |
-| POST | `/api/v1/setscadadevice/` | 更新SCADA设备 | network (query) | - |
-| POST | `/api/v1/setscadadevicedata/` | 更新SCADA设备数据 | network (query) | - |
-| POST | `/api/v1/setscadaelement/` | 更新SCADA元素映射 | network (query) | - |
-
-- 覆盖方法：`DELETE, GET, PATCH, POST`

.opencode/skills/analytics/simulation-analysis/SKILL.md

@@ -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`
-

.opencode/skills/analytics/simulation-analysis/burst-detection/SKILL.md

@@ -1,22 +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`

.opencode/skills/analytics/simulation-analysis/burst-location/SKILL.md

@@ -1,22 +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`

.opencode/skills/analytics/simulation-analysis/leakage/SKILL.md

@@ -1,22 +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`

.opencode/skills/analytics/simulation-analysis/risk/SKILL.md

@@ -1,24 +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/getnetworkpiperiskprobabilitynow/` | 获取整个网络的管道风险概率 | network (query) | - |
-| GET | `/api/v1/getpiperiskprobability/` | 获取管道风险概率历史 | network (query), pipe_id (query) | - |
-| GET | `/api/v1/getpiperiskprobabilitygeometries/` | 获取管道风险几何信息 | network (query) | - |
-| GET | `/api/v1/getpiperiskprobabilitynow/` | 获取管道当前风险概率 | network (query), pipe_id (query) | - |
-| GET | `/api/v1/getpipesriskprobability/` | 批量获取多条管道风险概率 | network (query), pipe_ids (query) | - |
-
-- 覆盖方法：`GET`

.opencode/skills/analytics/simulation-analysis/simulation/SKILL.md

@@ -1,48 +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/age_analysis/` | 水龄分析（高级） | network (query), start_time (query), end_time (query), duration (query) | - |
-| GET | `/api/v1/ageanalysis/` | 水龄分析（基础） | network (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/burstanalysis/` | 爆管分析（基础） | network (query), pipe_id (query), start_time (query), end_time (query), burst_flow (query) | - |
-| GET | `/api/v1/contaminant_simulation/` | 污染物模拟 | network (query), start_time (query), source (query), concentration (query), duration (query) | scheme_name (query), pattern (query) |
-| POST | `/api/v1/daily_scheduling_analysis/` | 日排程分析 | data (body) | - |
-| GET | `/api/v1/dumpoutput/` | 导出模拟输出 | output (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/flushinganalysis/` | 冲洗分析（基础） | network (query), pipe_id (query), start_time (query), duration (query), flow (query) | - |
-| POST | `/api/v1/network_project/` | 导入网络项目 | file (file) | - |
-| POST | `/api/v1/network_update/` | 管网更新（高级） | file (file) | - |
-| GET | `/api/v1/networkupdate/` | 管网更新（基础） | network (query) | - |
-| POST | `/api/v1/pressure_regulation/` | 压力调节（高级） | data (body) | - |
-| POST | `/api/v1/pressure_sensor_placement_kmeans/` | 压力传感器放置-KMeans聚类分析（高级） | data (body) | - |
-| POST | `/api/v1/pressure_sensor_placement_sensitivity/` | 压力传感器放置-灵敏度分析（高级） | data (body) | - |
-| GET | `/api/v1/pressureregulation/` | 压力调节（基础） | network (query), target_node (query), target_pressure (query) | - |
-| GET | `/api/v1/pressuresensorplacementkmeans/` | 压力传感器放置-KMeans聚类分析（基础） | name (query), scheme_name (query), sensor_number (query), min_diameter (query), username (query) | - |
-| GET | `/api/v1/pressuresensorplacementsensitivity/` | 压力传感器放置-灵敏度分析（基础） | name (query), scheme_name (query), sensor_number (query), min_diameter (query), username (query) | - |
-| POST | `/api/v1/project_management/` | 项目管理（高级） | data (body) | - |
-| GET | `/api/v1/projectmanagement/` | 项目管理（基础） | network (query) | - |
-| POST | `/api/v1/pump_failure/` | 泵故障管理 | data (body) | - |
-| GET | `/api/v1/runinp/` | 运行INP文件 | network (query) | - |
-| GET | `/api/v1/runproject/` | 运行项目模拟 | network (query) | - |
-| GET | `/api/v1/runprojectreturndict/` | 运行项目模拟（返回字典） | network (query) | - |
-| POST | `/api/v1/runsimulationmanuallybydate/` | 手动运行日期指定模拟 | data (body) | - |
-| POST | `/api/v1/scheduling_analysis/` | 排程分析 | 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) |
-| 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/valvecloseanalysis/` | 阀门关闭分析（基础） | network (query), valve_id (query), start_time (query), end_time (query) | - |
-

.opencode/skills/business/SKILL.md

@@ -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`
-

.opencode/skills/business/component-config/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`
-

.opencode/skills/business/component-config/controls/SKILL.md

@@ -1,25 +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`

.opencode/skills/business/component-config/curves/SKILL.md

@@ -1,26 +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`

.opencode/skills/business/component-config/options/SKILL.md

@@ -1,31 +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`

.opencode/skills/business/component-config/patterns/SKILL.md

@@ -1,26 +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`

.opencode/skills/business/component-config/quality/SKILL.md

@@ -1,44 +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`

.opencode/skills/business/component-config/visuals/SKILL.md

@@ -1,34 +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`

.opencode/skills/business/identity-access/SKILL.md

@@ -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`
-

.opencode/skills/business/identity-access/auth/SKILL.md

@@ -1,24 +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` | login | form_data (body) | - |
-| POST | `/api/v1/auth/login/simple` | login_simple | username (query), password (query) | - |
-| GET | `/api/v1/auth/me` | get_current_user_info | - | - |
-| POST | `/api/v1/auth/refresh` | refresh_token | refresh_token (query) | - |
-| POST | `/api/v1/auth/register` | register | user_data (body) | - |
-
-- 覆盖方法：`GET, POST`

.opencode/skills/business/identity-access/user-management/SKILL.md

@@ -1,25 +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`

.opencode/skills/business/identity-access/users/SKILL.md

@@ -1,22 +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`

.opencode/skills/business/network-assets/SKILL.md

@@ -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`
-

.opencode/skills/business/network-assets/demands/SKILL.md

@@ -1,25 +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`

.opencode/skills/business/network-assets/general/SKILL.md

@@ -1,48 +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`

.opencode/skills/business/network-assets/geometry/SKILL.md

@@ -1,25 +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`

.opencode/skills/business/network-assets/junctions/SKILL.md

@@ -1,37 +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`

.opencode/skills/business/network-assets/pipes/SKILL.md

@@ -1,39 +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`

.opencode/skills/business/network-assets/pumps/SKILL.md

@@ -1,29 +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`

.opencode/skills/business/network-assets/regions/SKILL.md

@@ -1,56 +0,0 @@
----
-name: tjwater-action-business-network-assets-regions
-description: business/network-assets 下 regions 操作技能。
-version: 3.0.0
----
-
-# 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/calculatedistrictmeteringarea/` | 计算DMA分区 | 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/calculateregion/` | 计算区域 | network (query), time_index (query) | - |
-| GET | `/api/v1/calculateservicearea/` | 计算服务区 | network (query), time_index (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/generateregion/` | 生成区域分区 | network (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/getallregions/` | 获取所有区域 | 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`

.opencode/skills/business/network-assets/reservoirs/SKILL.md

@@ -1,35 +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`

.opencode/skills/business/network-assets/tags/SKILL.md

@@ -1,23 +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`

.opencode/skills/business/network-assets/tanks/SKILL.md

@@ -1,47 +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`

.opencode/skills/business/network-assets/valves/SKILL.md

@@ -1,36 +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`

.opencode/skills/business/project-workspace/SKILL.md

@@ -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`
-

.opencode/skills/business/project-workspace/extension/SKILL.md

@@ -1,23 +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`

.opencode/skills/business/project-workspace/misc/SKILL.md

@@ -1,25 +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`

.opencode/skills/business/project-workspace/project-data/SKILL.md

@@ -1,23 +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`

.opencode/skills/business/project-workspace/project/SKILL.md

@@ -1,48 +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 |
-|---|---|---|---|---|
-| POST | `/api/v1/closeproject/` | 关闭项目 | network (query) | - |
-| GET | `/api/v1/convertv3tov2/` | 转换 INP V3 为 V2 | - | - |
-| GET | `/api/v1/convertv3tov2/` | 转换 INP V3 为 V2 | - | - |
-| POST | `/api/v1/copyproject/` | 复制项目 | source (query), target (query) | - |
-| POST | `/api/v1/createproject/` | 创建新项目 | network (query) | - |
-| POST | `/api/v1/deleteproject/` | 删除项目 | network (query) | - |
-| GET | `/api/v1/downloadinp/` | 下载 INP 文件 | name (query) | - |
-| GET | `/api/v1/downloadinp/` | 下载 INP 文件 | name (query) | - |
-| GET | `/api/v1/dumpinp/` | 导出项目到 INP 文件 | network (query), inp (query) | - |
-| GET | `/api/v1/dumpinp/` | 导出项目到 INP 文件 | network (query), inp (query) | - |
-| GET | `/api/v1/exportinp/` | 导出项目为 ChangeSet | network (query), version (query) | - |
-| GET | `/api/v1/haveproject/` | 检查项目是否存在 | network (query) | - |
-| POST | `/api/v1/importinp/` | 导入 INP 文件内容 | network (query) | - |
-| GET | `/api/v1/isprojectlocked/` | 检查项目是否被锁定 | network (query) | - |
-| GET | `/api/v1/isprojectlocked/` | 检查项目是否被锁定 | network (query) | - |
-| GET | `/api/v1/isprojectlockedbyme/` | 检查项目是否被当前用户锁定 | network (query) | - |
-| GET | `/api/v1/isprojectlockedbyme/` | 检查项目是否被当前用户锁定 | network (query) | - |
-| GET | `/api/v1/isprojectopen/` | 检查项目是否已打开 | network (query) | - |
-| GET | `/api/v1/listprojects/` | 获取项目列表 | - | - |
-| POST | `/api/v1/lockproject/` | 锁定项目 | network (query) | - |
-| POST | `/api/v1/lockproject/` | 锁定项目 | network (query) | - |
-| POST | `/api/v1/openproject/` | 打开项目 | network (query) | - |
-| GET | `/api/v1/project_info/` | 获取项目信息 | network (query) | - |
-| POST | `/api/v1/readinp/` | 读取 INP 文件到项目 | network (query), inp (query) | - |
-| POST | `/api/v1/readinp/` | 读取 INP 文件到项目 | network (query), inp (query) | - |
-| POST | `/api/v1/unlockproject/` | 解锁项目 | network (query) | - |
-| POST | `/api/v1/unlockproject/` | 解锁项目 | network (query) | - |
-| POST | `/api/v1/uploadinp/` | 上传 INP 文件 | afile (body), name (query) | - |
-| POST | `/api/v1/uploadinp/` | 上传 INP 文件 | afile (body), name (query) | - |
-
-- 覆盖方法：`GET, POST`

.opencode/skills/business/project-workspace/schemes/SKILL.md

@@ -1,22 +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`

.opencode/skills/business/project-workspace/snapshots/SKILL.md

@@ -1,37 +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`

.opencode/skills/data/SKILL.md

@@ -1,14 +0,0 @@
----
-name: tjwater-domain-data
-description: 负责时序数据访问与读写能力。
-version: 3.0.0
----
-
-# Data Domain Skill
-
-## 简介
-负责时序数据访问与读写能力。
-
-## 子模块索引 (渐进式引导)
-- **timeseries-access**: 见 `./timeseries-access/SKILL.md`
-

.opencode/skills/data/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`
-

.opencode/skills/data/timeseries-access/composite/SKILL.md

@@ -1,24 +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`

.opencode/skills/data/timeseries-access/realtime/SKILL.md

@@ -1,29 +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`

.opencode/skills/data/timeseries-access/scheme/SKILL.md

@@ -1,31 +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`

.opencode/skills/examples.md

@@ -1,128 +0,0 @@
-# 示例（基于 opencode Agent chat/stream 工具调用链）
-
-## 示例 1：前端发起对话，opencode agent 触发工具调用
-
-用户意图：查询设备 `170490` 在时间范围内的 `monitored_value`。
-
-前端调用 `POST /api/v1/agent/chat/stream`：
-
-```json
-{
-  "message": "请查询设备170490在最近24小时的monitored_value历史数据",
-  "session_id": "agent-demo-001"
-}
-```
-
-请求头至少包含（由前端传入）：
-- `Authorization: Bearer <token>`
-- `x-project-id: <project-id>`
-
-服务端内部行为：
-- 持续通过 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`。
-
-`progress` 示例：
-
-```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
-{
-  "ids": ["P-001", "P-002"],
-  "feature_type": "pipe"
-}
-```
-
-前端收到 SSE 事件后缩放地图并高亮管道。opencode agent 回复文字："已在地图上定位到管道 P-001 和 P-002。"
-
-## 示例 4：前端工具 — 对话内图表
-
-用户消息：
-- "展示节点 J-001 最近一天的压力变化曲线"
-
-典型链路：
-1. opencode agent 先调用 `dynamic_http_call` 查询数据
-2. 拿到数据后，调用 `show_chart` 将处理好的数据传给前端渲染
-
-第一步 — 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"
-  }
-}
-```
-
-第二步 — 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 的监测数据"
-
-opencode agent 调用工具 `view_scada`：
-```json
-{
-  "device_ids": ["J-001"],
-  "start_time": "2026-03-29T00:00:00Z",
-  "end_time": "2026-03-30T00:00:00Z"
-}
-```
-
-前端打开 SCADA 监测面板，展示该节点的历史监测曲线。

.opencode/skills/platform/SKILL.md

@@ -1,14 +0,0 @@
----
-name: tjwater-domain-platform
-description: 负责治理、审计、缓存与元数据能力。
-version: 3.0.0
----
-
-# Platform Domain Skill
-
-## 简介
-负责治理、审计、缓存与元数据能力。
-
-## 子模块索引 (渐进式引导)
-- **governance-observability**: 见 `./governance-observability/SKILL.md`
-

.opencode/skills/platform/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`
-

.opencode/skills/platform/governance-observability/audit/SKILL.md

@@ -1,22 +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`

.opencode/skills/platform/governance-observability/cache/SKILL.md

@@ -1,23 +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`

.opencode/skills/platform/governance-observability/meta/SKILL.md

@@ -1,22 +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`

.opencode/skills/runbook.md

@@ -1,92 +0,0 @@
-# API Skills 使用 Runbook（工具调用链）
-
-## 1) 总体原则
-
-- Skills 负责“告诉模型可做什么”。
-- `chat/stream` 内部启动 opencode 会话，并注册工具 `dynamic_http_call`。
-- opencode agent 通过工具调用后端能力，不直接发 HTTP。
-- TJWaterAgent 执行器负责“代表当前用户调真实后端 API”（动态路径，无白名单）。
-
-## 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` |
-
-`progress.status` 取值为 `running`、`completed`、`error`；前端应按相同 `id` 覆盖更新同一条进度，而不是重复追加。
-
-## 3) 工具参数约定（opencode agent 调用工具时）
-
-```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"
-  }
-}
-```
-
-说明（工具 `dynamic_http_call`）：
-- `path` 必须以 `/` 开头。
-- `method` 支持：`GET/POST/PUT/PATCH/DELETE`。
-- `arguments` 会编码为 query 参数（列表会转为逗号拼接）。
-
-## 4) 用户上下文注入（后端执行阶段）
-
-- `Authorization`（Bearer Token）
-- `x-project-id`
-
-执行器会附带 `x-trace-id` 用于链路排查（可透传或自动生成）。
-
-## 5) 排障要点
-
-- `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` 不同：
-
-```
-用户消息 → opencode agent → tool calling → 调用前端工具 (如 locate_features)
-                                    ↓
-                              tool handler:
-                              1) 推送 SSE tool_call 事件到前端
-                              2) 返回简短确认给 opencode agent（"已定位到管道"）
-                                    ↓
-前端同时收到:
-  - SSE event: progress  → 展示规划/工具执行/完成状态
-  - SSE event: tool_call → 前端执行操作（定位地图/打开面板/渲染图表）
-  - SSE event: token     → 渲染 opencode agent 文字回复
-```
-
-关键区别：
-- `dynamic_http_call`：TJWaterAgent 代理 HTTP 请求，结果返回给 opencode agent 做后续分析。
-- 前端工具：TJWaterAgent 仅推送 SSE 事件，前端直接执行，结果不返回 opencode agent。
-- `show_chart`：opencode agent 先通过 `dynamic_http_call` 查询数据，处理为 x_data + series 格式后调用 `show_chart`，前端直接渲染图表，不再请求后端。

.opencode/tools/apply_layer_style.ts

@@ -0,0 +1,94 @@
+import { tool } from "@opencode-ai/plugin";
+
+export default tool({
+  description:
+    "在前端地图上对节点或管道图层应用样式，或重置为默认样式。样式参数应尽量与前端样式编辑器字段保持一致。",
+  args: {
+    reason: tool.schema
+      .string()
+      .describe(
+        "Why this style action is needed for the current user request.",
+      ),
+    layer_id: tool.schema
+      .enum(["junctions", "pipes"])
+      .describe("Target layer id. Must be exactly 'junctions' or 'pipes'."),
+    reset_to_default: tool.schema
+      .boolean()
+      .optional()
+      .describe("Whether to reset the target layer to its default style."),
+    style_config: tool.schema
+      .object({
+        property: tool.schema
+          .string()
+          .optional()
+          .describe("Data property to render."),
+        classification_method: tool.schema
+          .enum(["pretty_breaks", "custom_breaks"])
+          .optional()
+          .describe("Classification method."),
+        segments: tool.schema
+          .number()
+          .optional()
+          .describe("Number of segments."),
+        min_size: tool.schema
+          .number()
+          .optional()
+          .describe("Minimum point radius."),
+        max_size: tool.schema
+          .number()
+          .optional()
+          .describe("Maximum point radius."),
+        min_stroke_width: tool.schema
+          .number()
+          .optional()
+          .describe("Minimum line width."),
+        max_stroke_width: tool.schema
+          .number()
+          .optional()
+          .describe("Maximum line width."),
+        fixed_stroke_width: tool.schema
+          .number()
+          .optional()
+          .describe("Fixed line width when width is not data-driven."),
+        color_type: tool.schema
+          .enum(["single", "gradient", "rainbow", "custom"])
+          .optional()
+          .describe("Color strategy."),
+        single_palette_index: tool.schema.number().optional(),
+        gradient_palette_index: tool.schema.number().optional(),
+        rainbow_palette_index: tool.schema.number().optional(),
+        show_labels: tool.schema
+          .boolean()
+          .optional()
+          .describe("Whether to show labels."),
+        show_id: tool.schema
+          .boolean()
+          .optional()
+          .describe("Whether to show ids."),
+        opacity: tool.schema.number().optional().describe("Opacity in [0, 1]."),
+        adjust_width_by_property: tool.schema
+          .boolean()
+          .optional()
+          .describe("Whether line width is driven by the rendered property."),
+        custom_breaks: tool.schema
+          .array(tool.schema.number())
+          .optional()
+          .describe("Custom break values."),
+        custom_colors: tool.schema
+          .array(tool.schema.string())
+          .optional()
+          .describe("Custom rgba colors."),
+      })
+      .optional()
+      .describe(
+        "Optional style config overrides. Omit when reset_to_default is true.",
+      ),
+  },
+  async execute(args) {
+    const layerLabel = args.layer_id === "junctions" ? "节点" : "管道";
+    if (args.reset_to_default) {
+      return `已将${layerLabel}图层重置为默认样式。`;
+    }
+    return `已对${layerLabel}图层应用样式。`;
+  },
+});

.opencode/tools/dynamic_http_call.ts

@@ -1,42 +0,0 @@
-import { tool } from "@opencode-ai/plugin";
-
-const internalBaseUrl = process.env.TJWATER_AGENT_INTERNAL_BASE_URL ?? "http://127.0.0.1:8787";
-const internalToken = process.env.TJWATER_AGENT_INTERNAL_TOKEN ?? "";
-
-export default tool({
-  description:
-    "通过本地 Agent 桥接调用 TJWater 后端 API。需提供 API 路径、可选的请求方法以及查询参数。",
-  args: {
-    path: tool.schema.string().describe("Target backend API path, starting with '/'."),
-    method: tool.schema
-      .string()
-      .optional()
-      .describe("HTTP method. Defaults to GET."),
-    arguments: tool.schema
-      .record(tool.schema.string(), tool.schema.unknown())
-      .optional()
-      .describe("Query arguments object."),
-  },
-  async execute(args, context) {
-    // 工具本身不直接持有用户 token；通过 sessionID 回调 Agent 服务，由服务侧补齐用户上下文。
-    const response = await fetch(`${internalBaseUrl}/internal/tools/dynamic-http-call`, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        "x-agent-internal-token": internalToken,
-      },
-      body: JSON.stringify({
-        sessionId: context.sessionID,
-        path: args.path,
-        method: args.method,
-        arguments: args.arguments,
-      }),
-    });
-
-    const text = await response.text();
-    if (!response.ok) {
-      throw new Error(text);
-    }
-    return text;
-  },
-});

.opencode/tools/geocode.ts

@@ -0,0 +1,37 @@
+import { tool } from "@opencode-ai/plugin";
+
+const internalBaseUrl =
+  process.env.TJWATER_AGENT_INTERNAL_BASE_URL ?? "http://127.0.0.1:8787";
+const internalToken = process.env.TJWATER_AGENT_INTERNAL_TOKEN ?? "";
+
+export default tool({
+  description:
+    "调用 TJWater 后端的天地图地理编码服务，将中国境内结构化地址或地点名称转换为经纬度。若需缩放地图，把返回的 location.lon/location.lat 传给 zoom_to_map，并设置 source_crs='EPSG:4326'。",
+  args: {
+    reason: tool.schema
+      .string()
+      .describe("Why geocoding is required for the current user request."),
+    keyword: tool.schema
+      .string()
+      .describe("Address or place name to geocode, such as 北京市人民政府."),
+  },
+  async execute(args, context) {
+    const response = await fetch(`${internalBaseUrl}/internal/tools/geocode`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "x-agent-internal-token": internalToken,
+      },
+      body: JSON.stringify({
+        session_id: context.sessionID,
+        keyword: args.keyword,
+      }),
+    });
+
+    const text = await response.text();
+    if (!response.ok) {
+      throw new Error(text);
+    }
+    return text;
+  },
+});

.opencode/tools/locate_features.ts

@@ -3,7 +3,14 @@ import { tool } from "@opencode-ai/plugin";
 export default tool({
   description: "在前端地图上定位并高亮指定的管网要素。",
   args: {
-    ids: tool.schema.array(tool.schema.string()).describe("Feature ids to locate."),
+    reason: tool.schema
+      .string()
+      .describe(
+        "Why this map positioning action is needed for the user request.",
+      ),
+    ids: tool.schema
+      .array(tool.schema.string())
+      .describe("Feature ids to locate."),
     feature_type: tool.schema
       .enum(["junction", "pipe", "valve", "reservoir", "pump", "tank"])
       .describe("Type of feature to locate."),

.opencode/tools/memory_manager.ts

@@ -0,0 +1,155 @@
+import { tool } from "@opencode-ai/plugin";
+import { MemoryStore } from "../../src/memory/store.js";
+import {
+  getRuntimeSessionContext,
+  setRuntimeSessionContext,
+} from "../../src/runtime/sessionContext.js";
+
+const memoryStore = new MemoryStore();
+const initializePromise = memoryStore.initialize();
+
+export default tool({
+  description:
+    "管理长期有效的用户偏好或项目事实。支持 add/list/replace/remove。add 前必须先对同 scope 执行 list 并阅读现有记忆，再决定 add、replace 或 remove；不要跳过读取直接新增。禁止写入 token、password、secret、system prompt 或一次性上下文。scope 仅允许 'user' 或 'workspace'。",
+  args: {
+    action: tool.schema
+      .enum(["add", "list", "replace", "remove"])
+      .describe("Memory operation to perform."),
+    reason: tool.schema
+      .string()
+      .describe("Why this memory should be persisted for future requests."),
+    scope: tool.schema
+      .string()
+      .describe(
+        "Required exact keyword. Use only 'user' for user-level durable preferences/constraints, or 'workspace' for project/environment durable facts. Do not use 'project', Chinese labels, or any alias.",
+      ),
+    content: tool.schema
+      .string()
+      .optional()
+      .describe(
+        "The durable fact or preference to remember, written as one concise sentence.",
+      ),
+    target_id: tool.schema
+      .string()
+      .optional()
+      .describe("Stable memory entry id used by replace/remove."),
+  },
+  async execute(args, context) {
+    await initializePromise;
+    const sessionContext = getRuntimeSessionContext(context.sessionID);
+    if (!sessionContext) {
+      throw new Error(`session context not found for ${context.sessionID}`);
+    }
+    const scope =
+      args.scope === "user"
+        ? "user"
+        : args.scope === "workspace"
+          ? "workspace"
+          : null;
+    if (!scope) {
+      return JSON.stringify({
+        ok: true,
+        kind: "memory",
+        decision: "rejected",
+        detail: `unsupported scope: ${args.scope}; use exact keyword 'user' or 'workspace'`,
+      });
+    }
+    if (sessionContext.allowLearningWrite === false && args.action !== "list") {
+      return JSON.stringify({
+        ok: true,
+        kind: "memory",
+        decision: "rejected",
+        detail: "memory writes are disabled for this session",
+      });
+    }
+
+    const scopeKey =
+      scope === "user" ? sessionContext.actorKey : sessionContext.projectKey;
+    if (args.action === "list") {
+      const readScopes = {
+        ...(sessionContext.memoryListReadScopes ?? {}),
+        [scope]: true,
+      };
+      setRuntimeSessionContext({
+        ...sessionContext,
+        memoryListReadScopes: readScopes,
+      });
+      return JSON.stringify({
+        ok: true,
+        kind: "memory",
+        decision: "accepted",
+        detail: "memory listed",
+        items: await memoryStore.list(scope, scopeKey),
+        target: scope,
+      });
+    }
+
+    if (args.action === "add") {
+      if (sessionContext.memoryListReadScopes?.[scope] !== true) {
+        return JSON.stringify({
+          ok: true,
+          kind: "memory",
+          decision: "rejected",
+          detail: `must list ${scope} memory and review existing entries before add`,
+          target: scope,
+        });
+      }
+      const result = await memoryStore.upsert(scope, scopeKey, {
+        content: args.content ?? "",
+        sessionId: sessionContext.clientSessionId,
+        source: "tool",
+        traceId: sessionContext.traceId,
+      });
+      if (!result.entry) {
+        return JSON.stringify({
+          ok: true,
+          kind: "memory",
+          decision: "rejected",
+          detail: "content rejected by persistence policy",
+        });
+      }
+      return JSON.stringify({
+        ok: true,
+        kind: "memory",
+        decision: result.changed ? "accepted" : "deduped",
+        detail: result.detail,
+        entry: result.entry,
+        target: scope,
+      });
+    }
+
+    if (args.action === "replace") {
+      const result = await memoryStore.replace(
+        scope,
+        scopeKey,
+        args.target_id ?? "",
+        {
+          content: args.content ?? "",
+          sessionId: sessionContext.clientSessionId,
+          source: "tool",
+          traceId: sessionContext.traceId,
+        },
+      );
+      return JSON.stringify({
+        ok: true,
+        kind: "memory",
+        decision: result.changed ? "accepted" : "rejected",
+        detail: result.detail,
+        target: scope,
+      });
+    }
+
+    const result = await memoryStore.remove(
+      scope,
+      scopeKey,
+      args.target_id ?? "",
+    );
+    return JSON.stringify({
+      ok: true,
+      kind: "memory",
+      decision: result.changed ? "accepted" : "rejected",
+      detail: result.detail,
+      target: scope,
+    });
+  },
+});

.opencode/tools/render_junctions.ts

@@ -0,0 +1,22 @@
+import { tool } from "@opencode-ai/plugin";
+
+export default tool({
+  description:
+    "在前端地图上对 junctions 图层应用分区渲染。使用前必须完成两步：① 准备数据结构（JSON 文件，结构为 { node_area_map: Record<string, string>, area_ids?: string[], area_colors?: Record<string, string> }，其中 node_area_map 的 key 是 junction/node id，value 是 area id）；② 调用 store_render_ref 将 JSON 文件存储到受控路径，获取 render_ref（格式为 res-...）；③ 将 render_ref 传入本工具完成前端渲染。注意：不要先把 ref 内容完整读出再传给前端，也不要直接传本地文件路径。",
+  args: {
+    reason: tool.schema
+      .string()
+      .describe(
+        "Why this junction rendering action is needed for the user request.",
+      ),
+    render_ref: tool.schema
+      .string()
+      .describe(
+        "上一步通过 store_render_ref 获得的渲染引用 ID（res-...）。前端会按该引用拉取完整 payload 并渲染。不可直接传入本地文件路径或完整 JSON 数据。",
+      ),
+  },
+  async execute() {
+    // 工具参数里只需要 render_ref；浏览器端会再用该引用回读完整 payload.data 并完成渲染。
+    return "已在地图上应用节点分区渲染。";
+  },
+});

.opencode/tools/session_search.ts

@@ -0,0 +1,46 @@
+import { tool } from "@opencode-ai/plugin";
+
+const internalBaseUrl =
+  process.env.TJWATER_AGENT_INTERNAL_BASE_URL ?? "http://127.0.0.1:8787";
+const internalToken = process.env.TJWATER_AGENT_INTERNAL_TOKEN ?? "";
+
+export default tool({
+  description:
+    "搜索当前用户和项目范围内的历史会话 transcript。适合回忆过去讨论过的案例、约束和结论，避免把一次性案例写入 memory。",
+  args: {
+    reason: tool.schema
+      .string()
+      .describe("Why prior session history is needed for the current request."),
+    query: tool.schema
+      .string()
+      .describe("What to search for in prior session history."),
+    max_results: tool.schema
+      .number()
+      .int()
+      .positive()
+      .optional()
+      .describe("Optional maximum number of hits to return."),
+  },
+  async execute(args, context) {
+    const response = await fetch(
+      `${internalBaseUrl}/internal/tools/session-search`,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "x-agent-internal-token": internalToken,
+        },
+        body: JSON.stringify({
+          max_results: args.max_results,
+          query: args.query,
+          session_id: context.sessionID,
+        }),
+      },
+    );
+    const text = await response.text();
+    if (!response.ok) {
+      throw new Error(text);
+    }
+    return text;
+  },
+});

.opencode/tools/show_chart.ts

@@ -3,6 +3,9 @@ import { tool } from "@opencode-ai/plugin";
 export default tool({
   description: "在前端对话界面中渲染图表。",
   args: {
+    reason: tool.schema
+      .string()
+      .describe("Why this chart should be rendered for the user request."),
     title: tool.schema.string().optional().describe("Chart title."),
     chart_type: tool.schema
       .enum(["line", "bar", "pie"])
@@ -18,8 +21,14 @@ export default tool({
         }),
       )
       .describe("Series data."),
-    x_axis_name: tool.schema.string().optional().describe("X-axis display name."),
+    x_axis_name: tool.schema
-    y_axis_name: tool.schema.string().optional().describe("Y-axis display name."),
+      .string()
+      .optional()
+      .describe("X-axis display name."),
+    y_axis_name: tool.schema
+      .string()
+      .optional()
+      .describe("Y-axis display name."),
   },
   async execute() {
     // 图表数据已经在工具参数里，前端收到 tool_call 后直接渲染，不再二次请求后端。

.opencode/tools/skill_manager.ts

@@ -0,0 +1,154 @@
+import { tool } from "@opencode-ai/plugin";
+
+import { SkillStore } from "../../src/skills/store.js";
+import {
+  getRuntimeSessionContext,
+  type RuntimeSessionContext,
+} from "../../src/runtime/sessionContext.js";
+
+type ToolContextReader = {
+  read(sessionId: string): RuntimeSessionContext | null;
+};
+
+const runtimeContextReader: ToolContextReader = {
+  read: getRuntimeSessionContext,
+};
+
+export const createSkillManagerTool = (
+  skillStore = new SkillStore(),
+  toolContextStore: ToolContextReader = runtimeContextReader,
+  initializePromise: Promise<unknown> = Promise.resolve(),
+) =>
+  tool({
+    description:
+      "维护已验证、可复用、非敏感的 workflow 或方法模式。支持 list、write_skill、remove_skill、append_pattern、remove_pattern、write_reference、remove_reference、write_script、remove_script。",
+    args: {
+      action: tool.schema
+        .enum([
+          "list",
+          "write_skill",
+          "remove_skill",
+          "append_pattern",
+          "remove_pattern",
+          "write_reference",
+          "remove_reference",
+          "write_script",
+          "remove_script",
+        ])
+        .describe("Skill maintenance operation."),
+      reason: tool.schema
+        .string()
+        .describe(
+          "Why this skill maintenance action is justified for future reuse.",
+        ),
+      skill_path: tool.schema
+        .string()
+        .describe(
+          "Target skill directory path relative to .opencode/skills. Use 'workflow' for the workflow index, or '__root__' for the root skills index.",
+        ),
+      pattern: tool.schema
+        .string()
+        .optional()
+        .describe("Pattern text used by append_pattern."),
+      target_id: tool.schema
+        .string()
+        .optional()
+        .describe("Stable learned pattern id used by remove_pattern."),
+      file_path: tool.schema
+        .string()
+        .optional()
+        .describe(
+          "Asset file path. For references use references/*.md; for scripts use scripts/*.py.",
+        ),
+      content: tool.schema
+        .string()
+        .optional()
+        .describe(
+          "Content used by write_skill, write_reference, or write_script.",
+        ),
+    },
+    async execute(args, context) {
+      await initializePromise;
+      const sessionContext = toolContextStore.read(context.sessionID);
+      if (!sessionContext) {
+        throw new Error(`session context not found for ${context.sessionID}`);
+      }
+      if (
+        sessionContext.allowLearningWrite === false &&
+        args.action !== "list"
+      ) {
+        return JSON.stringify({
+          ok: true,
+          kind: "skill",
+          decision: "rejected",
+          detail: "skill writes are disabled for this session",
+        });
+      }
+      if (args.action === "list") {
+        const result = await skillStore.list(args.skill_path);
+        if (!result) {
+          return JSON.stringify({
+            ok: true,
+            kind: "skill",
+            decision: "rejected",
+            detail:
+              "invalid skill_path; expected a relative path under .opencode/skills",
+          });
+        }
+        return JSON.stringify({
+          ok: true,
+          kind: "skill",
+          decision: "accepted",
+          detail: "skill listed",
+          ...result,
+        });
+      }
+
+      const result =
+        args.action === "write_skill"
+          ? await skillStore.writeSkill(args.skill_path, args.content ?? "")
+          : args.action === "remove_skill"
+            ? await skillStore.removeSkill(args.skill_path)
+            : args.action === "append_pattern"
+              ? await skillStore.appendPattern(
+                  args.skill_path,
+                  args.pattern ?? "",
+                )
+              : args.action === "remove_pattern"
+                ? await skillStore.removePattern(
+                    args.skill_path,
+                    args.target_id ?? "",
+                  )
+                : args.action === "write_reference"
+                  ? await skillStore.writeReference(
+                      args.skill_path,
+                      args.file_path ?? "",
+                      args.content ?? "",
+                    )
+                  : args.action === "remove_reference"
+                    ? await skillStore.removeReference(
+                        args.skill_path,
+                        args.file_path ?? "",
+                      )
+                    : args.action === "write_script"
+                      ? await skillStore.writeScript(
+                          args.skill_path,
+                          args.file_path ?? "",
+                          args.content ?? "",
+                        )
+                      : await skillStore.removeScript(
+                          args.skill_path,
+                          args.file_path ?? "",
+                        );
+
+      return JSON.stringify({
+        ok: true,
+        kind: "skill",
+        decision: result.changed ? "accepted" : "rejected",
+        detail: result.detail,
+        target: result.target,
+      });
+    },
+  });
+
+export default createSkillManagerTool();

.opencode/tools/store_render_ref.ts

@@ -0,0 +1,44 @@
+import { tool } from "@opencode-ai/plugin";
+
+const internalBaseUrl =
+  process.env.TJWATER_AGENT_INTERNAL_BASE_URL ?? "http://127.0.0.1:8787";
+const internalToken = process.env.TJWATER_AGENT_INTERNAL_TOKEN ?? "";
+
+export default tool({
+  description:
+    "将本地 JSON 渲染数据文件存储到受控路径，返回可供 render_junctions 使用的 render_ref（res-...）。前置步骤：先准备好符合 render_junctions 数据结构的 JSON 文件 { node_area_map, area_ids?, area_colors? }，写入本地路径后再调用本工具传入该路径，获取 render_ref 后传给 render_junctions 完成前端渲染。",
+  args: {
+    reason: tool.schema
+      .string()
+      .describe(
+        "为何需要将此本地渲染数据持久化为 render_ref，以便后续通过 render_junctions 渲染到前端。",
+      ),
+    file_path: tool.schema
+      .string()
+      .describe(
+        "本地 JSON 文件的绝对路径，内容为 render_junctions 所需的数据结构 { node_area_map, area_ids?, area_colors? }。",
+      ),
+  },
+  async execute(args, context) {
+    const response = await fetch(
+      `${internalBaseUrl}/internal/tools/store-render-ref`,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "x-agent-internal-token": internalToken,
+        },
+        body: JSON.stringify({
+          session_id: context.sessionID,
+          file_path: args.file_path,
+        }),
+      },
+    );
+
+    const text = await response.text();
+    if (!response.ok) {
+      throw new Error(text);
+    }
+    return text;
+  },
+});

.opencode/tools/tjwater_cli.ts

@@ -0,0 +1,48 @@
+import { tool } from "@opencode-ai/plugin";
+
+const internalBaseUrl =
+  process.env.TJWATER_AGENT_INTERNAL_BASE_URL ?? "http://127.0.0.1:8787";
+const internalToken = process.env.TJWATER_AGENT_INTERNAL_TOKEN ?? "";
+
+export default tool({
+  description:
+    "通过本地 Agent 桥接调用 tjwater-cli 命令访问 TJWater 后端服务。提供 CLI 子命令和参数。",
+  args: {
+    reason: tool.schema
+      .string()
+      .describe("Why this tool call is required for the current user request."),
+    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("超时秒数，默认 120。大结果集建议设 300+。"),
+  },
+  async execute(args, context) {
+    const response = await fetch(
+      `${internalBaseUrl}/internal/tools/tjwater-cli-call`,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "x-agent-internal-token": internalToken,
+        },
+        body: JSON.stringify({
+          session_id: context.sessionID,
+          reason: args.reason,
+          command: args.command,
+          timeout: args.timeout,
+        }),
+      },
+    );
+
+    const text = await response.text();
+    if (!response.ok) {
+      throw new Error(text);
+    }
+    return text;
+  },
+});

.opencode/tools/view_history.ts

@@ -3,14 +3,25 @@ import { tool } from "@opencode-ai/plugin";
 export default tool({
   description: "为选定的管网要素打开前端的历史记录或计算结果面板。",
   args: {
+    reason: tool.schema
+      .string()
+      .describe(
+        "Why this history panel should be opened for the current task.",
+      ),
     feature_infos: tool.schema
       .array(tool.schema.tuple([tool.schema.string(), tool.schema.string()]))
       .describe("List of [id, type] pairs."),
     data_type: tool.schema
       .enum(["realtime", "scheme", "none"])
       .describe("History data source type."),
-    start_time: tool.schema.string().optional().describe("Optional ISO8601 start time."),
+    start_time: tool.schema
-    end_time: tool.schema.string().optional().describe("Optional ISO8601 end time."),
+      .string()
+      .optional()
+      .describe("Optional ISO8601 start time."),
+    end_time: tool.schema
+      .string()
+      .optional()
+      .describe("Optional ISO8601 end time."),
   },
   async execute() {
     // 返回短确认即可；面板打开动作由前端根据 tool_call 参数完成。

.opencode/tools/view_scada.ts

@@ -3,17 +3,25 @@ import { tool } from "@opencode-ai/plugin";
 export default tool({
   description: "打开前端的 SCADA 监测数据历史面板。",
   args: {
+    reason: tool.schema
+      .string()
+      .describe("Why SCADA panel interaction is required for this request."),
     device_ids: tool.schema
       .array(tool.schema.string())
       .optional()
       .describe("Preferred SCADA device ids."),
-    device_id: tool.schema.string().optional().describe("Single SCADA device id."),
+    device_id: tool.schema
-    feature_infos: tool.schema
+      .string()
-      .array(tool.schema.tuple([tool.schema.string(), tool.schema.string()]))
       .optional()
-      .describe("Legacy [id, type] pairs."),
+      .describe("Single SCADA device id."),
-    start_time: tool.schema.string().optional().describe("Optional ISO8601 start time."),
+    start_time: tool.schema
-    end_time: tool.schema.string().optional().describe("Optional ISO8601 end time."),
+      .string()
+      .optional()
+      .describe("Optional ISO8601 start time."),
+    end_time: tool.schema
+      .string()
+      .optional()
+      .describe("Optional ISO8601 end time."),
   },
   async execute() {
     // SCADA 面板仍在浏览器侧执行，工具结果不承载实际监测数据。

.opencode/tools/web_search.ts

@@ -0,0 +1,62 @@
+import { tool } from "@opencode-ai/plugin";
+
+const internalBaseUrl =
+  process.env.TJWATER_AGENT_INTERNAL_BASE_URL ?? "http://127.0.0.1:8787";
+const internalToken = process.env.TJWATER_AGENT_INTERNAL_TOKEN ?? "";
+
+export default tool({
+  description:
+    "调用 TJWater 后端的实时网页搜索服务。适合查询新闻、政策、规范、产品资料、公开网页事实等可能变化的信息。",
+  args: {
+    reason: tool.schema
+      .string()
+      .describe("Why web search is required for the current user request."),
+    query: tool.schema.string().describe("Search query text."),
+    freshness: tool.schema
+      .enum(["noLimit", "oneDay", "oneWeek", "oneMonth", "oneYear"])
+      .optional()
+      .describe("Optional freshness filter. Defaults to noLimit."),
+    summary: tool.schema
+      .boolean()
+      .optional()
+      .describe("Whether the backend should include page summaries."),
+    count: tool.schema
+      .number()
+      .int()
+      .positive()
+      .optional()
+      .describe("Optional result count, backend accepts 1 to 50."),
+    include: tool.schema
+      .array(tool.schema.string())
+      .optional()
+      .describe("Optional domains to include."),
+    exclude: tool.schema
+      .array(tool.schema.string())
+      .optional()
+      .describe("Optional domains to exclude."),
+  },
+  async execute(args, context) {
+    const response = await fetch(`${internalBaseUrl}/internal/tools/web-search`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "x-agent-internal-token": internalToken,
+      },
+      body: JSON.stringify({
+        session_id: context.sessionID,
+        query: args.query,
+        freshness: args.freshness,
+        summary: args.summary,
+        count: args.count,
+        include: args.include,
+        exclude: args.exclude,
+      }),
+    });
+
+    const text = await response.text();
+    if (!response.ok) {
+      throw new Error(text);
+    }
+    return text;
+  },
+});

.opencode/tools/zoom_to_map.ts

@@ -0,0 +1,32 @@
+import { tool } from "@opencode-ai/plugin";
+
+export default tool({
+  description:
+    "在前端地图上缩放定位到坐标。默认坐标为 EPSG:3857；如果来自天地图 geocode 的 lon/lat，传 source_crs='EPSG:4326'，前端会转换为 EPSG:3857 后缩放。",
+  args: {
+    reason: tool.schema
+      .string()
+      .describe("Why this map zoom action is needed for the current request."),
+    x: tool.schema
+      .number()
+      .describe("X coordinate. For EPSG:4326 this is longitude; for EPSG:3857 this is meters."),
+    y: tool.schema
+      .number()
+      .describe("Y coordinate. For EPSG:4326 this is latitude; for EPSG:3857 this is meters."),
+    source_crs: tool.schema
+      .enum(["EPSG:3857", "EPSG:4326"])
+      .optional()
+      .describe("Input coordinate CRS. Defaults to EPSG:3857."),
+    zoom: tool.schema
+      .number()
+      .optional()
+      .describe("Optional OpenLayers zoom level. Defaults to 18."),
+    duration_ms: tool.schema
+      .number()
+      .optional()
+      .describe("Optional animation duration in milliseconds. Defaults to 1000."),
+  },
+  async execute() {
+    return "已缩放到指定地图坐标。";
+  },
+});

AGENTS.md

@@ -0,0 +1,39 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+This repository is the internal TJWater agent service. Runtime TypeScript code is organized under `src/`; CLI-specific code is under `cli/src`; Node test files live in `node-tests/`. Agent extensions and OpenCode integration files are under `.opencode/`, including `.opencode/agents`, `.opencode/skills`, and `.opencode/tools`. Runtime data, session metadata, logs, and result references are stored under `data/` and `logs/` and should be treated as local/generated state.
+
+Deployment files are `Dockerfile`, `docker-compose.yml`, and `.gitea/workflows/package.yml`.
+
+## Build, Test, and Development Commands
+
+Use Bun for this project:
+
+```bash
+bun install
+bun run dev
+bun run check
+bun run test:cli
+bun run start
+```
+
+`bun run dev` starts `src/server.ts` in watch mode. `bun run check` runs TypeScript checks for the main project and `.opencode`. `bun run test:cli` runs Node CLI tests. `bun run start` starts the service without watch mode.
+
+## Coding Style & Naming Conventions
+
+Use TypeScript ESM and keep types explicit at module boundaries. Use two-space indentation, `camelCase` for functions and variables, `PascalCase` for classes/types, and kebab-case or descriptive lowercase names for scripts and data files. Prefer existing `src/` service, route, and runtime patterns before introducing new structure.
+
+## Testing Guidelines
+
+Tests use Node's built-in test runner for CLI coverage. Name test files with `.node.mjs` when using `node --test`, matching `node-tests/cli/*.node.mjs`. Add focused tests for CLI parsing, tool behavior, and session/runtime changes. Do not depend on mutable local files under `data/`.
+
+## Commit & Pull Request Guidelines
+
+History uses Conventional Commit messages such as `feat(tools): add search and map tools`, `fix(agent): warm up opencode on startup`, and `refactor(chat): ...`. Prefer `feat(scope):`, `fix(scope):`, or `refactor(scope):`.
+
+PRs should describe runtime behavior changes, list `bun run check` and any test commands run, and mention changes to `.opencode`, secrets, ports, or deploy workflow behavior.
+
+## Security & Configuration Tips
+
+Do not commit `.env`, logs, session transcripts, generated result references, or `node_modules/`. Keep registry and deploy credentials in Gitea secrets.

Dockerfile

@@ -1,33 +1,85 @@
-# syntax=docker/dockerfile:1.7
+FROM oven/bun:canary-slim AS bun-bin
+
+FROM smanx/opencode:latest AS base
+USER root
+ARG UBUNTU_APT_MIRROR=mirrors.aliyun.com
+ARG PYPI_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
+ARG PYPI_TRUSTED_HOST=pypi.tuna.tsinghua.edu.cn
+ENV VIRTUAL_ENV=/opt/venv
+ENV PATH="$VIRTUAL_ENV/bin:/root/.local/bin:$PATH"
+ENV PIP_INDEX_URL=${PYPI_INDEX_URL}
+ENV PIP_TRUSTED_HOST=${PYPI_TRUSTED_HOST}
+ENV UV_INDEX_URL=${PYPI_INDEX_URL}
+
+RUN sed -i "s|http://archive.ubuntu.com|https://${UBUNTU_APT_MIRROR}|g; s|http://security.ubuntu.com|https://${UBUNTU_APT_MIRROR}|g" /etc/apt/sources.list 2>/dev/null || true && \
+    sed -i "s|http://archive.ubuntu.com|https://${UBUNTU_APT_MIRROR}|g; s|http://security.ubuntu.com|https://${UBUNTU_APT_MIRROR}|g" /etc/apt/sources.list.d/*.sources 2>/dev/null || true && \
+    apt-get update && apt-get install -y --no-install-recommends \
+    curl \
+    jq \
+    unzip \
+    python3 \
+    python3-venv && \
+    curl -LsSf https://astral.sh/uv/install.sh | sh && \
+    ln -s /root/.local/bin/uv /usr/local/bin/uv && \
+    ln -sf /usr/bin/python3 /usr/local/bin/python && \
+    mkdir -p /root/.config/pip && \
+    printf "[global]\nindex-url = %s\ntrusted-host = %s\n" "$PIP_INDEX_URL" "$PIP_TRUSTED_HOST" > /root/.config/pip/pip.conf && \
+    uv venv "$VIRTUAL_ENV" && \
+    uv pip install --python "$VIRTUAL_ENV/bin/python" \
+    --index-url "$UV_INDEX_URL" \
+    pip \
+    setuptools \
+    wheel \
+    requests \
+    httpx \
+    pydantic \
+    python-dotenv \
+    rich \
+    ipython \
+    pytest && \
+    rm -rf /var/lib/apt/lists/*
+
+COPY --from=bun-bin /usr/local/bin/bun /usr/local/bin/bun
+
+FROM base AS deps
 
-FROM oven/bun:1.3.13 AS deps
 WORKDIR /app
 
 COPY package.json bun.lock ./
 COPY .opencode/package.json .opencode/bun.lock ./.opencode/
 RUN bun install --frozen-lockfile
 
-FROM deps AS build
+FROM base AS build
 WORKDIR /app
 
-COPY tsconfig.json opencode.json README.md ./
+COPY --from=deps /app/node_modules ./node_modules
+COPY --from=deps /app/.opencode/node_modules ./.opencode/node_modules
+COPY tsconfig.json opencode.json README.md .gitignore ./
 COPY src ./src
+COPY cli ./cli
 COPY .opencode ./.opencode
 RUN bun run check
 
-FROM oven/bun:1.3.13 AS runner
+FROM base AS runner
 WORKDIR /app
 
 ENV NODE_ENV=production
 ENV HOST=0.0.0.0
 ENV PORT=8787
+ENV TJWATER_CLI_PATH=./cli/tjwater-cli
 
 COPY --from=deps /app/node_modules ./node_modules
 COPY --from=deps /app/.opencode/node_modules ./.opencode/node_modules
 COPY package.json bun.lock ./
-COPY tsconfig.json opencode.json ./
+COPY tsconfig.json opencode.json .gitignore ./
 COPY src ./src
 COPY .opencode ./.opencode
+COPY cli ./cli
+
+COPY entrypoint.sh /entrypoint.sh
+RUN chmod +x /entrypoint.sh ./cli/tjwater-cli
+
+ENTRYPOINT ["/entrypoint.sh"]
 
 EXPOSE 8787
 CMD ["bun", "src/server.ts"]

README.md

@@ -30,9 +30,9 @@ TJWaterAgent/
 1. 启动 HTTP 服务。
 2. 通过 `@opencode-ai/sdk` 启动内嵌 opencode server，或连接外部 opencode server。
 3. 管理前端 `session_id -> opencode sessionId` 的映射。
-4. 保存并传递用户 `Authorization`、`x-project-id`、`x-trace-id`。
+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,34 +84,45 @@ src/
 
 ```text
 .opencode/tools/
-  dynamic_http_call.ts
+  tjwater_cli.ts
+  store_render_ref.ts
   locate_features.ts
   view_history.ts
   view_scada.ts
   show_chart.ts
+  render_junctions.ts
+  apply_layer_style.ts
+  memory_manager.ts
+  session_search.ts
+  skill_manager.ts
 ```
 
 这些是 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 动作或可视化，不应被当作数据查询工具。
+`store_render_ref.ts` 用于把大型 junction 渲染 payload 存成 `render_ref`，再由 `render_junctions.ts` 交给前端回读并渲染。
+
+前端类工具如 `locate_features`、`view_history`、`view_scada`、`show_chart`、`render_junctions`、`apply_layer_style` 主要用于触发 UI 动作或可视化，不应被当作数据查询工具。
 
 ### skills
 
 ```text
-.opencode/skills/tjwater-skills-root-index/
+.opencode/skills/
   SKILL.md
-  ai/
+  examples.md
-  analytics/
+  runbook.md
-  business/
+  tjwater-cli/      ← tjwater-cli 可执行文件
-  data/
+  workflow/         ← 可复用分析工作流
-  platform/
+    SKILL.md
+    simulation-diagnosis/
+    bottleneck-analysis/
+    source-service-area-analysis/
 ```
 
-这里保存 TJWater 技能树，并保持树结构，符合渐进式披露设计。
+Skills 仅保留可复用的多步工作流。Agent 通过 `tjwater-cli help` 自行发现原子命令，无需逐接口技能树。
 
-agent 需要某个领域知识时再按需加载对应 skill，不把整棵技能树作为 always-loaded prompt 一次性注入。
+agent 加载技能树时按需取用对应 workflow skill。
 
 ## 依赖边界
 
@@ -150,7 +161,12 @@ typescript
 
 ## 启动与部署
 
-默认部署不需要全局安装 `opencode` CLI。服务会通过 `@opencode-ai/sdk` 的 embedded 模式启动 opencode server。
+支持两种 opencode 接入方式：
+
+1. Embedded 模式：服务通过 `@opencode-ai/sdk` 调用 `createOpencode`，启动本地 `opencode` CLI 子进程并自动创建 client。
+2. Client 模式：服务通过 `createOpencodeClient` 直接连接一个已经存在的 opencode server。
+
+因此，只有 Embedded 模式要求运行环境已安装 `opencode` CLI；Client 模式不依赖本地 CLI。
 
 根目录的 Bun scripts 已经封装 `.opencode` 依赖安装和类型检查，日常只需要在 `TJWaterAgent/` 根目录操作。
 
@@ -175,9 +191,21 @@ opencode.json
 
 因此修改 agent prompt、tools、skills、模型配置或本地环境变量后，不需要手动重启 `bun run dev`。
 
-本地开发可以在项目根目录的 `.local.env` 中配置环境变量：
+本地开发可以在项目根目录的 `.local.env` 中配置环境变量。
+
+Embedded 模式示例：
 
 ```bash
+OPENCODE_MODE=embedded
+DEEPSEEK_API_KEY=sk-xxx
+TJWATER_API_BASE_URL=http://127.0.0.1:8000
+```
+
+Client 模式示例：
+
+```bash
+OPENCODE_MODE=client
+OPENCODE_CLIENT_BASE_URL=http://127.0.0.1:4096
 DEEPSEEK_API_KEY=sk-xxx
 TJWATER_API_BASE_URL=http://127.0.0.1:8000
 ```
@@ -201,6 +229,27 @@ bun install
 bun run start:prod
 ```
 
+### Docker Compose 启动
+
+项目根目录已提供 `Dockerfile` 和 `docker-compose.yml`，可直接使用：
+
+```bash
+cd TJWaterAgent
+docker compose up -d --build
+```
+
+查看日志：
+
+```bash
+docker compose logs -f tjwater-agent
+```
+
+停止并清理容器：
+
+```bash
+docker compose down
+```
+
 ### 常用脚本
 
 | 命令 | 作用 |
@@ -210,6 +259,7 @@ bun run start:prod
 | `bun run start` | 直接运行 `src/server.ts` |
 | `bun run start:prod` | 先类型检查再启动 |
 | `bun run install:opencode` | 手动安装 `.opencode` 依赖 |
+| `bun run pipeline:trigger` | 通过重建并强推 annotated `latest` tag 触发 Gitea CI/CD，只发布/覆盖 `latest` 镜像 |
 
 ### 模型与 API 配置
 
@@ -266,8 +316,8 @@ bun run start
 如果需要连接外部独立运行的 opencode server，可以配置：
 
 ```bash
-OPENCODE_BASE_URL=http://127.0.0.1:4096
+OPENCODE_MODE=client
+OPENCODE_CLIENT_BASE_URL=http://127.0.0.1:4096
 ```
 
 配置后，`TJWaterAgent` 会连接该外部 opencode server，而不是自行启动 embedded opencode server。
->>>>>>> 414247d (新增 skills、README，指定  opencode 的启动行为)

bun.lock

@@ -5,7 +5,7 @@
     "": {
       "name": "tjwater-agent",
       "dependencies": {
-        "@opencode-ai/sdk": "^1.14.29",
+        "@opencode-ai/sdk": "^1.16.2",
         "cors": "^2.8.5",
         "dotenv": "^17.2.3",
         "express": "^4.21.2",
@@ -17,12 +17,13 @@
         "@types/cors": "^2.8.19",
         "@types/express": "^5.0.3",
         "@types/node": "^24.7.2",
+        "bun-types": "^1.3.3",
         "typescript": "^5.9.3",
       },
     },
   },
   "packages": {
-    "@opencode-ai/sdk": ["@opencode-ai/sdk@1.14.30", "", { "dependencies": { "cross-spawn": "7.0.6" } }, "sha512-OgPEDvALekHZIjByo/okJ699aLPn+XtsVxgZxUqE8TlzAG7TtskMGFl0fro8O0T2p+nkOT/LstnKGbECvc0+YA=="],
+    "@opencode-ai/sdk": ["@opencode-ai/sdk@1.16.2", "", { "dependencies": { "cross-spawn": "7.0.6" } }, "sha512-Z/xZ7q79dYeE0afqIk/yFEcRNGEQFcE+H8ssYivUiy+xGZ1mGwT72jpaQZKBwPn3JH4sRCu4KA2lcktBQfcOjg=="],
 
     "@pinojs/redact": ["@pinojs/redact@0.4.0", "", {}, "sha512-k2ENnmBugE/rzQfEcdWHcCY+/FM3VLzH9cYEsbdsoqrvzAKRhUZeRNhAZvB8OitQJ1TBed3yqWtdjzS6wJKBwg=="],
 
@@ -56,6 +57,8 @@
 
     "body-parser": ["body-parser@1.20.5", "", { "dependencies": { "bytes": "~3.1.2", "content-type": "~1.0.5", "debug": "2.6.9", "depd": "2.0.0", "destroy": "~1.2.0", "http-errors": "~2.0.1", "iconv-lite": "~0.4.24", "on-finished": "~2.4.1", "qs": "~6.15.1", "raw-body": "~2.5.3", "type-is": "~1.6.18", "unpipe": "~1.0.0" } }, "sha512-3grm+/2tUOvu2cjJkvsIxrv/wVpfXQW4PsQHYm7yk4vfpu7Ekl6nEsYBoJUL6qDwZUx8wUhQ8tR2qz+ad9c9OA=="],
 
+    "bun-types": ["bun-types@1.3.14", "", { "dependencies": { "@types/node": "*" } }, "sha512-4N0ig0fEomHt5R0KCFWjovxow98rIoRwKolrYdCcknNwMekCXRnWEUvgu5soYV8QXtVsrUD8B95MBOZGPvr6KQ=="],
+
     "bytes": ["bytes@3.1.2", "", {}, "sha512-/Nf7TyzTx6S3yRJObOAV7956r8cr2+Oj8AC5dt8wSP3BQAoeX58NoHyCU8P8zGkNXStjTSi6fzO6F0pBdcYbEg=="],
 
     "call-bind-apply-helpers": ["call-bind-apply-helpers@1.0.2", "", { "dependencies": { "es-errors": "^1.3.0", "function-bind": "^1.1.2" } }, "sha512-Sp1ablJ0ivDkSzjcaJdxEunN5/XvksFJ2sMBFfq6x0ryhQV/2b/KwFe21cMpmHtPOSij8K99/wSfoEuTObmuMQ=="],

cli/src/commands/analysis.ts

@@ -0,0 +1,199 @@
+import { CliError } from "../core/errors.js";
+import { emitApi, requestJson } from "../core/http.js";
+import { assignDatasetKeys, parseBurstFile, parseValveSettingFile } from "../core/files.js";
+import { optionalNumber, optionalString, optionalStringArray, parseOptions, requiredNumber, requiredString, validateChoice } from "../core/options.js";
+import { requireNetwork, requireUsername, resolveScheme } from "../core/runtime.js";
+import { parseTime } from "../core/time.js";
+import { success } from "../core/output.js";
+import type { HandlerMap, RuntimeContext } from "../core/types.js";
+
+function analysisBurst(ctx: RuntimeContext, argv: string[]): Promise<void> {
+  const { values } = parseOptions(argv, { duration: "integer" });
+  const [ids, sizes] = parseBurstFile(requiredString(values, "burst-file"));
+  const schemeName = resolveScheme(ctx, optionalString(values, "scheme"), true)!;
+  return emitApi(ctx, "爆管分析执行成功", {
+    method: "GET",
+    path: "/burst_analysis/",
+    params: {
+      network: requireNetwork(ctx),
+      modify_pattern_start_time: parseTime(requiredString(values, "start-time"), "--start-time"),
+      burst_ID: ids,
+      burst_size: sizes,
+      modify_total_duration: requiredNumber(values, "duration"),
+      scheme_name: schemeName,
+    },
+    requireNetworkCtx: true,
+  }, [`tjwater-cli data scheme get --name ${schemeName}`, "tjwater-cli data scheme list"]);
+}
+
+function analysisValve(ctx: RuntimeContext, argv: string[]): Promise<void> {
+  const { values } = parseOptions(argv, { valve: "repeat", element: "repeat", "disabled-valve": "repeat", duration: "integer" });
+  const mode = validateChoice(requiredString(values, "mode"), ["close", "isolation"] as const, "--mode");
+  if (mode === "close") {
+    const valves = optionalStringArray(values, "valve");
+    const startTime = optionalString(values, "start-time");
+    if (!startTime || !valves) throw new CliError("CLI 参数错误", "INVALID_VALVE_CLOSE_ARGS", "close mode requires --start-time and at least one --valve", 2);
+    return emitApi(ctx, "阀门关闭分析执行成功", {
+      method: "GET",
+      path: "/valve_close_analysis/",
+      params: {
+        network: requireNetwork(ctx),
+        start_time: parseTime(startTime, "--start-time"),
+        valves,
+        duration: optionalNumber(values, "duration") || 900,
+        scheme_name: resolveScheme(ctx, optionalString(values, "scheme"), true),
+      },
+      requireNetworkCtx: true,
+    });
+  }
+  const elements = optionalStringArray(values, "element");
+  if (!elements) throw new CliError("CLI 参数错误", "INVALID_VALVE_ISOLATION_ARGS", "isolation mode requires at least one --element", 2);
+  return emitApi(ctx, "阀门隔离分析执行成功", {
+    method: "GET",
+    path: "/valve_isolation_analysis/",
+    params: { network: requireNetwork(ctx), accident_element: elements, disabled_valves: optionalStringArray(values, "disabled-valve") },
+    requireNetworkCtx: true,
+  });
+}
+
+function analysisFlushing(ctx: RuntimeContext, argv: string[]): Promise<void> {
+  const { values } = parseOptions(argv, { flow: "number", duration: "integer" });
+  const [valves, openings] = parseValveSettingFile(requiredString(values, "valve-setting-file"));
+  return emitApi(ctx, "冲洗分析执行成功", {
+    method: "GET",
+    path: "/flushing_analysis/",
+    params: {
+      network: requireNetwork(ctx),
+      start_time: parseTime(requiredString(values, "start-time"), "--start-time"),
+      valves,
+      valves_k: openings,
+      drainage_node_ID: requiredString(values, "drainage-node"),
+      flush_flow: requiredNumber(values, "flow"),
+      duration: optionalNumber(values, "duration") || 900,
+      scheme_name: resolveScheme(ctx, optionalString(values, "scheme"), true),
+    },
+    requireNetworkCtx: true,
+  });
+}
+
+function analysisAge(ctx: RuntimeContext, argv: string[]): Promise<void> {
+  const { values } = parseOptions(argv, { duration: "integer" });
+  return emitApi(ctx, "水龄分析执行成功", {
+    method: "GET",
+    path: "/age_analysis/",
+    params: { network: requireNetwork(ctx), start_time: parseTime(requiredString(values, "start-time"), "--start-time"), duration: requiredNumber(values, "duration") },
+    requireNetworkCtx: true,
+  });
+}
+
+function analysisContaminant(ctx: RuntimeContext, argv: string[]): Promise<void> {
+  const { values } = parseOptions(argv, { duration: "integer", concentration: "number" });
+  const params: Record<string, unknown> = {
+    network: requireNetwork(ctx),
+    start_time: parseTime(requiredString(values, "start-time"), "--start-time"),
+    source: requiredString(values, "source-node"),
+    concentration: requiredNumber(values, "concentration"),
+    duration: requiredNumber(values, "duration"),
+    scheme_name: resolveScheme(ctx, optionalString(values, "scheme"), true),
+  };
+  const pattern = optionalString(values, "pattern");
+  if (pattern) params.pattern = pattern;
+  return emitApi(ctx, "污染物模拟执行成功", { method: "GET", path: "/contaminant_simulation/", params, requireNetworkCtx: true });
+}
+
+function sensorKmeans(ctx: RuntimeContext, argv: string[]): Promise<void> {
+  const { values } = parseOptions(argv, { count: "integer", "min-diameter": "integer" });
+  return emitApi(ctx, "传感器选址执行成功", {
+    method: "POST",
+    path: "/pressure_sensor_placement_kmeans/",
+    body: {
+      name: requireNetwork(ctx),
+      scheme_name: resolveScheme(ctx, optionalString(values, "scheme"), true),
+      sensor_number: requiredNumber(values, "count"),
+      min_diameter: optionalNumber(values, "min-diameter") || 0,
+      username: requireUsername(ctx),
+    },
+    requireNetworkCtx: true,
+    requireUsernameCtx: true,
+  });
+}
+
+function schemeAnalysis(ctx: RuntimeContext, argv: string[], summary: string, path: string, networkKey: string, startKey: string, endKey: string): Promise<void> {
+  const { values } = parseOptions(argv);
+  return emitApi(ctx, summary, {
+    method: "POST",
+    path,
+    body: {
+      [networkKey]: requireNetwork(ctx),
+      [startKey]: parseTime(requiredString(values, "start-time"), "--start-time"),
+      [endKey]: parseTime(requiredString(values, "end-time"), "--end-time"),
+      scheme_name: resolveScheme(ctx, optionalString(values, "scheme"), true),
+    },
+    requireNetworkCtx: true,
+  });
+}
+
+function schemeList(ctx: RuntimeContext, summary: string, path: string): Promise<void> {
+  return emitApi(ctx, summary, { method: "GET", path, params: { network: requireNetwork(ctx) }, requireNetworkCtx: true });
+}
+
+function schemeGet(ctx: RuntimeContext, argv: string[], summary: string, path: string): Promise<void> {
+  const { positionals } = parseOptions(argv);
+  if (!positionals[0]) throw new CliError("CLI 参数错误", "MISSING_ARGUMENT", "Missing argument 'SCHEME_NAME'", 2);
+  return emitApi(ctx, summary, { method: "GET", path: `${path}${positionals[0]}`, params: { network: requireNetwork(ctx) }, requireNetworkCtx: true });
+}
+
+function burstLocation(ctx: RuntimeContext, argv: string[]): Promise<void> {
+  const { values } = parseOptions(argv, { "burst-leakage": "number", "pressure-scada-id": "repeat", "flow-scada-id": "repeat", "use-scada-flow": "boolean" });
+  const body: Record<string, unknown> = {
+    network: requireNetwork(ctx),
+    scheme_name: resolveScheme(ctx, optionalString(values, "scheme"), true),
+    data_source: optionalString(values, "data-source") || "monitoring",
+    scada_burst_start: parseTime(requiredString(values, "start-time"), "--start-time"),
+    scada_burst_end: parseTime(requiredString(values, "end-time"), "--end-time"),
+    burst_leakage: requiredNumber(values, "burst-leakage"),
+    use_scada_flow: Boolean(values["use-scada-flow"]),
+  };
+  const pressureIds = optionalStringArray(values, "pressure-scada-id");
+  const flowIds = optionalStringArray(values, "flow-scada-id");
+  if (pressureIds) body.pressure_scada_ids = pressureIds;
+  if (flowIds) body.flow_scada_ids = flowIds;
+  const pressureFile = optionalString(values, "pressure-file");
+  const flowFile = optionalString(values, "flow-file");
+  if (pressureFile) assignDatasetKeys(body, pressureFile, ["burst_pressure", "normal_pressure"], "pressure");
+  if (flowFile) assignDatasetKeys(body, flowFile, ["burst_flow", "normal_flow"], "flow");
+  return emitApi(ctx, "爆管定位执行成功", { method: "POST", path: "/burst-location/locate/", body, requireNetworkCtx: true });
+}
+
+function riskPipe(ctx: RuntimeContext, argv: string[], summary: string, path: string): Promise<void> {
+  const { values } = parseOptions(argv);
+  return emitApi(ctx, summary, { method: "GET", path, params: { network: requireNetwork(ctx), pipe_id: requiredString(values, "pipe") }, requireNetworkCtx: true });
+}
+
+async function riskNetwork(ctx: RuntimeContext): Promise<void> {
+  const network = requireNetwork(ctx);
+  const [probabilities, a] = await requestJson(ctx, { method: "GET", path: "/getnetworkpiperiskprobabilitynow/", params: { network }, requireNetworkCtx: true });
+  const [geometries, b] = await requestJson(ctx, { method: "GET", path: "/getpiperiskprobabilitygeometries/", params: { network }, requireNetworkCtx: true });
+  success("读取全网风险成功", { probabilities, geometries }, ctx, a + b);
+}
+
+export const analysisHandlers: HandlerMap = {
+  "analysis burst": analysisBurst,
+  "analysis valve": analysisValve,
+  "analysis flushing": analysisFlushing,
+  "analysis age": analysisAge,
+  "analysis contaminant": analysisContaminant,
+  "analysis sensor-placement kmeans": sensorKmeans,
+  "analysis leakage identify": (ctx, argv) => schemeAnalysis(ctx, argv, "漏损识别执行成功", "/leakage/identify/", "network", "scada_start", "scada_end"),
+  "analysis leakage schemes list": (ctx) => schemeList(ctx, "读取漏损方案列表成功", "/leakage/schemes/"),
+  "analysis leakage schemes get": (ctx, argv) => schemeGet(ctx, argv, "读取漏损方案详情成功", "/leakage/schemes/"),
+  "analysis burst-detection detect": (ctx, argv) => schemeAnalysis(ctx, argv, "爆管检测执行成功", "/burst-detection/detect/", "network", "scada_start", "scada_end"),
+  "analysis burst-detection schemes list": (ctx) => schemeList(ctx, "读取爆管检测方案列表成功", "/burst-detection/schemes/"),
+  "analysis burst-detection schemes get": (ctx, argv) => schemeGet(ctx, argv, "读取爆管检测方案详情成功", "/burst-detection/schemes/"),
+  "analysis burst-location locate": burstLocation,
+  "analysis burst-location schemes list": (ctx) => schemeList(ctx, "读取爆管定位方案列表成功", "/burst-location/schemes/"),
+  "analysis burst-location schemes get": (ctx, argv) => schemeGet(ctx, argv, "读取爆管定位方案详情成功", "/burst-location/schemes/"),
+  "analysis risk pipe-now": (ctx, argv) => riskPipe(ctx, argv, "读取当前管道风险成功", "/getpiperiskprobabilitynow/"),
+  "analysis risk pipe-history": (ctx, argv) => riskPipe(ctx, argv, "读取历史管道风险成功", "/getpiperiskprobability/"),
+  "analysis risk network": riskNetwork,
+};

cli/src/commands/component.ts

@@ -0,0 +1,34 @@
+import { CliError } from "../core/errors.js";
+import { emitApi } from "../core/http.js";
+import { optionalString, parseOptions, requiredString, validateChoice } from "../core/options.js";
+import { requireNetwork } from "../core/runtime.js";
+import type { HandlerMap, RuntimeContext } from "../core/types.js";
+
+type ComponentKind = "time" | "energy" | "pump-energy" | "network";
+
+function componentOption(ctx: RuntimeContext, argv: string[], schema: boolean): Promise<void> {
+  const { values } = parseOptions(argv);
+  const kind = validateChoice(requiredString(values, "kind"), ["time", "energy", "pump-energy", "network"] as const, "--kind");
+  const routes: Record<`${ComponentKind}:${boolean}`, string> = {
+    "time:true": "/gettimeschema",
+    "time:false": "/gettimeproperties/",
+    "energy:true": "/getenergyschema/",
+    "energy:false": "/getenergyproperties/",
+    "pump-energy:true": "/getpumpenergyschema/",
+    "pump-energy:false": "/getpumpenergyproperties//",
+    "network:true": "/getoptionschema/",
+    "network:false": "/getoptionproperties/",
+  };
+  const params: Record<string, unknown> = { network: requireNetwork(ctx) };
+  const pump = optionalString(values, "pump");
+  if (kind === "pump-energy") {
+    if (!schema && !pump) throw new CliError("CLI 参数错误", "PUMP_REQUIRED", "--pump is required when --kind pump-energy", 2);
+    if (pump) params.pump = pump;
+  }
+  return emitApi(ctx, schema ? "读取选项 schema 成功" : "读取选项属性成功", { method: "GET", path: routes[`${kind}:${schema}`], params, requireNetworkCtx: true });
+}
+
+export const componentHandlers: HandlerMap = {
+  "component option schema": (ctx, argv) => componentOption(ctx, argv, true),
+  "component option get": (ctx, argv) => componentOption(ctx, argv, false),
+};

cli/src/commands/data.ts

@@ -0,0 +1,167 @@
+import { SCADA_FIELDS, type ElementType } from "../core/constants.js";
+import { CliError } from "../core/errors.js";
+import { emitApi } from "../core/http.js";
+import { fieldsFor, optionalString, parseOptions, requiredString, requiredStringArray, validateChoice } from "../core/options.js";
+import { requireNetwork, resolveScheme } from "../core/runtime.js";
+import { parseTime } from "../core/time.js";
+import type { HandlerMap, RuntimeContext } from "../core/types.js";
+
+function rangeGet(ctx: RuntimeContext, argv: string[], summary: string, path: string): Promise<void> {
+  const { values } = parseOptions(argv);
+  return emitApi(ctx, summary, {
+    method: "GET",
+    path,
+    params: { start_time: parseTime(requiredString(values, "start-time"), "--start-time"), end_time: parseTime(requiredString(values, "end-time"), "--end-time") },
+    requireProject: true,
+  });
+}
+
+function realtimeByIdTime(ctx: RuntimeContext, argv: string[]): Promise<void> {
+  const { values } = parseOptions(argv);
+  return emitApi(ctx, "读取实时模拟数据成功", {
+    method: "GET",
+    path: "/realtime/query/by-id-time",
+    params: { id: requiredString(values, "id"), type: validateChoice(requiredString(values, "type"), ["pipe", "junction"] as const, "--type"), query_time: parseTime(requiredString(values, "time"), "--time") },
+    requireProject: true,
+  });
+}
+
+function realtimeByTimeProperty(ctx: RuntimeContext, argv: string[]): Promise<void> {
+  const { values } = parseOptions(argv);
+  const type = validateChoice(requiredString(values, "type"), ["pipe", "junction"] as const, "--type");
+  return emitApi(ctx, "读取实时属性聚合数据成功", {
+    method: "GET",
+    path: "/realtime/query/by-time-property",
+    params: { type, query_time: parseTime(requiredString(values, "time"), "--time"), property: validateChoice(requiredString(values, "property"), fieldsFor(type), "--property") },
+    requireProject: true,
+  });
+}
+
+function schemeLinks(ctx: RuntimeContext, argv: string[]): Promise<void> {
+  const { values } = parseOptions(argv);
+  return emitApi(ctx, "读取方案管道数据成功", {
+    method: "GET",
+    path: "/scheme/links",
+    params: {
+      scheme_name: resolveScheme(ctx, optionalString(values, "scheme"), true),
+      scheme_type: optionalString(values, "scheme-type") || "simulation",
+      start_time: parseTime(requiredString(values, "start-time"), "--start-time"),
+      end_time: parseTime(requiredString(values, "end-time"), "--end-time"),
+    },
+    requireProject: true,
+  });
+}
+
+function schemeNodeField(ctx: RuntimeContext, argv: string[]): Promise<void> {
+  const { values } = parseOptions(argv);
+  return emitApi(ctx, "读取方案节点字段成功", {
+    method: "GET",
+    path: `/scheme/nodes/${requiredString(values, "node")}/field`,
+    params: {
+      field: validateChoice(requiredString(values, "field"), fieldsFor("junction"), "--field"),
+      scheme_name: resolveScheme(ctx, optionalString(values, "scheme"), true),
+      scheme_type: optionalString(values, "scheme-type") || "simulation",
+      start_time: parseTime(requiredString(values, "start-time"), "--start-time"),
+      end_time: parseTime(requiredString(values, "end-time"), "--end-time"),
+    },
+    requireProject: true,
+  });
+}
+
+function schemeSimulation(ctx: RuntimeContext, argv: string[]): Promise<void> {
+  const { values } = parseOptions(argv);
+  const query = validateChoice(requiredString(values, "query"), ["by-id-time", "by-scheme-time-property"] as const, "--query");
+  const type = validateChoice(optionalString(values, "type") || "pipe", ["pipe", "junction"] as const, "--type") as ElementType;
+  const params: Record<string, unknown> = {
+    scheme_name: resolveScheme(ctx, optionalString(values, "scheme"), true),
+    scheme_type: optionalString(values, "scheme-type") || "simulation",
+    query_time: parseTime(requiredString(values, "time"), "--time"),
+    type,
+  };
+  if (query === "by-id-time") {
+    params.id = requiredString(values, "id");
+    return emitApi(ctx, "读取方案单点模拟数据成功", { method: "GET", path: "/scheme/query/by-id-time", params, requireProject: true });
+  }
+  params.property = validateChoice(requiredString(values, "property"), fieldsFor(type), "--property");
+  return emitApi(ctx, "读取方案属性聚合数据成功", { method: "GET", path: "/scheme/query/by-scheme-time-property", params, requireProject: true });
+}
+
+function scadaQuery(ctx: RuntimeContext, argv: string[]): Promise<void> {
+  const { values } = parseOptions(argv, { "device-id": "repeat" });
+  const params: Record<string, unknown> = {
+    device_ids: requiredStringArray(values, "device-id").join(","),
+    start_time: parseTime(requiredString(values, "start-time"), "--start-time"),
+    end_time: parseTime(requiredString(values, "end-time"), "--end-time"),
+  };
+  const field = optionalString(values, "field");
+  if (field) params.field = validateChoice(field, SCADA_FIELDS, "--field");
+  return emitApi(ctx, "读取 SCADA 时序成功", { method: "GET", path: field ? "/scada/by-ids-field-time-range" : "/scada/by-ids-time-range", params, requireProject: true });
+}
+
+function composite(ctx: RuntimeContext, argv: string[]): Promise<void> {
+  const { values } = parseOptions(argv, { feature: "repeat", "use-cleaned": "boolean" });
+  const kind = validateChoice(requiredString(values, "kind"), ["scada-simulation", "element-simulation", "element-scada"] as const, "--kind");
+  const params: Record<string, unknown> = {
+    start_time: parseTime(requiredString(values, "start-time"), "--start-time"),
+    end_time: parseTime(requiredString(values, "end-time"), "--end-time"),
+  };
+  const schemeName = resolveScheme(ctx, optionalString(values, "scheme"));
+  if (schemeName) Object.assign(params, { scheme_name: schemeName, scheme_type: optionalString(values, "scheme-type") || "simulation" });
+  if (kind === "scada-simulation") params.device_ids = requiredStringArray(values, "feature").join(",");
+  else if (kind === "element-simulation") params.feature_infos = requiredStringArray(values, "feature").join(",");
+  else {
+    const feature = requiredStringArray(values, "feature");
+    if (feature.length !== 1) throw new CliError("CLI 参数错误", "FEATURE_REQUIRED", "element-scada requires exactly one --feature as element_id", 2);
+    params.element_id = feature[0];
+    params.use_cleaned = Boolean(values["use-cleaned"]);
+  }
+  return emitApi(ctx, kind === "scada-simulation" ? "读取复合 SCADA-模拟数据成功" : kind === "element-simulation" ? "读取复合元素模拟数据成功" : "读取元素关联 SCADA 数据成功", { method: "GET", path: `/composite/${kind}`, params, requireProject: true });
+}
+
+function pipelineHealth(ctx: RuntimeContext, argv: string[]): Promise<void> {
+  const { values } = parseOptions(argv);
+  requiredString(values, "pipe");
+  requiredString(values, "start-time");
+  return emitApi(ctx, "读取管道健康预测成功", {
+    method: "GET",
+    path: "/composite/pipeline-health-prediction",
+    params: { network_name: requireNetwork(ctx), query_time: parseTime(requiredString(values, "end-time"), "--end-time") },
+    requireProject: true,
+    requireNetworkCtx: true,
+  });
+}
+
+function dataScadaGet(ctx: RuntimeContext, argv: string[]): Promise<void> {
+  const { values } = parseOptions(argv);
+  validateChoice(requiredString(values, "kind"), ["info"] as const, "--kind");
+  return emitApi(ctx, "读取 SCADA 数据成功", { method: "GET", path: "/getscadainfo/", params: { network: requireNetwork(ctx), id: requiredString(values, "id") }, requireNetworkCtx: true });
+}
+
+function dataScadaList(ctx: RuntimeContext, argv: string[]): Promise<void> {
+  const { values } = parseOptions(argv);
+  validateChoice(requiredString(values, "kind"), ["info"] as const, "--kind");
+  return emitApi(ctx, "读取 SCADA 列表成功", { method: "GET", path: "/getallscadainfo/", params: { network: requireNetwork(ctx) }, requireNetworkCtx: true });
+}
+
+function dataSchemeGet(ctx: RuntimeContext, argv: string[]): Promise<void> {
+  const { values } = parseOptions(argv);
+  return emitApi(ctx, "读取方案成功", { method: "GET", path: "/getscheme/", params: { network: requireNetwork(ctx), schema_name: requiredString(values, "name") }, requireNetworkCtx: true });
+}
+
+export const dataHandlers: HandlerMap = {
+  "data timeseries realtime links": (ctx, argv) => rangeGet(ctx, argv, "读取实时管道数据成功", "/realtime/links"),
+  "data timeseries realtime nodes": (ctx, argv) => rangeGet(ctx, argv, "读取实时节点数据成功", "/realtime/nodes"),
+  "data timeseries realtime simulation-by-id-time": realtimeByIdTime,
+  "data timeseries realtime simulation-by-time-property": realtimeByTimeProperty,
+  "data timeseries scheme links": schemeLinks,
+  "data timeseries scheme node-field": schemeNodeField,
+  "data timeseries scheme simulation": schemeSimulation,
+  "data timeseries scada query": scadaQuery,
+  "data timeseries composite": composite,
+  "data timeseries composite pipeline-health": pipelineHealth,
+  "data scada get": dataScadaGet,
+  "data scada list": dataScadaList,
+  "data scheme schema": (ctx) => emitApi(ctx, "读取方案 schema 成功", { method: "GET", path: "/getschemeschema/", params: { network: requireNetwork(ctx) }, requireNetworkCtx: true }),
+  "data scheme get": dataSchemeGet,
+  "data scheme list": (ctx) => emitApi(ctx, "读取方案列表成功", { method: "GET", path: "/getallschemes/", params: { network: requireNetwork(ctx) }, requireNetworkCtx: true }),
+};

cli/src/commands/network.ts

@@ -0,0 +1,27 @@
+import { emitApi } from "../core/http.js";
+import { parseOptions, requiredString } from "../core/options.js";
+import { requireNetwork } from "../core/runtime.js";
+import type { HandlerMap, RuntimeContext } from "../core/types.js";
+
+function legacyGet(ctx: RuntimeContext, argv: string[], summary: string, path: string, key: string): Promise<void> {
+  const { values } = parseOptions(argv);
+  return emitApi(ctx, summary, { method: "GET", path, params: { network: requireNetwork(ctx), [key]: requiredString(values, key) }, requireNetworkCtx: true });
+}
+
+function legacyGetAll(ctx: RuntimeContext, summary: string, path: string): Promise<void> {
+  return emitApi(ctx, summary, { method: "GET", path, params: { network: requireNetwork(ctx) }, requireNetworkCtx: true });
+}
+
+export const networkHandlers: HandlerMap = {
+  "network get-junction-properties": (ctx, argv) => legacyGet(ctx, argv, "读取节点属性成功", "/getjunctionproperties/", "junction"),
+  "network get-pipe-properties": (ctx, argv) => legacyGet(ctx, argv, "读取管道属性成功", "/getpipeproperties/", "pipe"),
+  "network get-all-pipes-properties": (ctx) => legacyGetAll(ctx, "读取全部管道属性成功", "/getallpipeproperties/"),
+  "network get-reservoir-properties": (ctx, argv) => legacyGet(ctx, argv, "读取水库属性成功", "/getreservoirproperties/", "reservoir"),
+  "network get-all-reservoirs-properties": (ctx) => legacyGetAll(ctx, "读取全部水库属性成功", "/getallreservoirproperties/"),
+  "network get-tank-properties": (ctx, argv) => legacyGet(ctx, argv, "读取水箱属性成功", "/gettankproperties/", "tank"),
+  "network get-all-tanks-properties": (ctx) => legacyGetAll(ctx, "读取全部水箱属性成功", "/getalltankproperties/"),
+  "network get-pump-properties": (ctx, argv) => legacyGet(ctx, argv, "读取水泵属性成功", "/getpumpproperties/", "pump"),
+  "network get-all-pumps-properties": (ctx) => legacyGetAll(ctx, "读取全部水泵属性成功", "/getallpumpproperties/"),
+  "network get-valve-properties": (ctx, argv) => legacyGet(ctx, argv, "读取阀门属性成功", "/getvalveproperties/", "valve"),
+  "network get-all-valves-properties": (ctx) => legacyGetAll(ctx, "读取全部阀门属性成功", "/getallvalveproperties/"),
+};

cli/src/commands/simulation.ts

@@ -0,0 +1,26 @@
+import { emitApi } from "../core/http.js";
+import { parseOptions, requiredNumber, requiredString } from "../core/options.js";
+import { requireNetwork } from "../core/runtime.js";
+import { addMinutesPreservingOffset, parseTime } from "../core/time.js";
+import type { HandlerMap, RuntimeContext } from "../core/types.js";
+
+function simulationRun(ctx: RuntimeContext, argv: string[]): Promise<void> {
+  const { values } = parseOptions(argv, { duration: "integer" });
+  const start = parseTime(requiredString(values, "start-time"), "--start-time");
+  const duration = requiredNumber(values, "duration");
+  const end = addMinutesPreservingOffset(start, duration);
+  const network = requireNetwork(ctx);
+  return emitApi(
+    ctx,
+    "触发模拟成功",
+    { method: "POST", path: "/runsimulationmanuallybydate/", body: { name: network, start_time: start.replace(/\.\d+/, ""), duration }, requireNetworkCtx: true },
+    [
+      `tjwater-cli data timeseries realtime links --start-time ${start} --end-time ${end}`,
+      `tjwater-cli data timeseries realtime nodes --start-time ${start} --end-time ${end}`,
+    ],
+  );
+}
+
+export const simulationHandlers: HandlerMap = {
+  "simulation run": simulationRun,
+};

cli/src/core/constants.ts

@@ -0,0 +1,13 @@
+export const SCHEMA_VERSION = "tjwater-cli/v1";
+export const DEFAULT_TIMEOUT = 180;
+export const DEFAULT_SERVER = "http://192.168.1.114:8000";
+
+export const PIPE_FIELDS = ["flow", "friction", "headloss", "quality", "reaction", "setting", "status", "velocity"] as const;
+export const JUNCTION_FIELDS = ["actual_demand", "total_head", "pressure", "quality"] as const;
+export const SCADA_FIELDS = ["monitored_value", "cleaned_value"] as const;
+
+export type ElementType = "pipe" | "junction";
+export type PipeField = (typeof PIPE_FIELDS)[number];
+export type JunctionField = (typeof JUNCTION_FIELDS)[number];
+export type ScadaField = (typeof SCADA_FIELDS)[number];
+

cli/src/core/errors.ts

@@ -0,0 +1,31 @@
+export class CliError extends Error {
+  summary: string;
+  code: string;
+  exitCode: number;
+  retryable: boolean;
+  data: unknown;
+  nextCommands: string[];
+
+  constructor(
+    summary: string,
+    code: string,
+    message: string,
+    exitCode = 2,
+    retryable = false,
+    data: unknown = null,
+    nextCommands: string[] = [],
+  ) {
+    super(message);
+    this.summary = summary;
+    this.code = code;
+    this.exitCode = exitCode;
+    this.retryable = retryable;
+    this.data = data;
+    this.nextCommands = nextCommands;
+  }
+}
+
+export function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+

cli/src/core/files.ts

@@ -0,0 +1,69 @@
+import { readFileSync } from "node:fs";
+import { CliError } from "./errors.js";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+export function readJsonFile(path: string, label: string): unknown {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+      throw new CliError("CLI 参数错误", "INPUT_NOT_FOUND", `${label} file not found: ${path}`, 2);
+    }
+    if (error instanceof SyntaxError) throw new CliError("CLI 参数错误", "INPUT_INVALID_JSON", `${label} file must be valid JSON: ${path}`, 2);
+    throw error;
+  }
+}
+
+export function parseBurstFile(path: string): [string[], number[]] {
+  let raw = readJsonFile(path, "burst");
+  if (isRecord(raw) && "bursts" in raw) raw = raw.bursts;
+  if (isRecord(raw) && "burst_ID" in raw && "burst_size" in raw && Array.isArray(raw.burst_ID) && Array.isArray(raw.burst_size)) {
+    const ids = raw.burst_ID.map(String);
+    const sizes = raw.burst_size.map(Number);
+    if (ids.length !== sizes.length) throw new CliError("CLI 参数错误", "BURST_FILE_INVALID", "burst file burst_ID and burst_size must have the same length", 2);
+    return [ids, sizes];
+  }
+  if (Array.isArray(raw)) {
+    return [
+      raw.map((item) => {
+        if (!isRecord(item) || !("id" in item) || !("size" in item)) throw new CliError("CLI 参数错误", "BURST_FILE_INVALID", "burst file items must contain id and size", 2);
+        return String(item.id);
+      }),
+      raw.map((item) => Number((item as Record<string, unknown>).size)),
+    ];
+  }
+  throw new CliError("CLI 参数错误", "BURST_FILE_INVALID", "burst file must be a JSON array or object with burst_ID/burst_size", 2);
+}
+
+export function parseValveSettingFile(path: string): [string[], number[]] {
+  const raw = readJsonFile(path, "valve-setting");
+  if (isRecord(raw) && "valves" in raw && "valves_k" in raw && Array.isArray(raw.valves) && Array.isArray(raw.valves_k)) {
+    const valves = raw.valves.map(String);
+    const openings = raw.valves_k.map(Number);
+    if (valves.length !== openings.length) throw new CliError("CLI 参数错误", "VALVE_SETTING_INVALID", "valves and valves_k must have the same length", 2);
+    return [valves, openings];
+  }
+  if (Array.isArray(raw)) {
+    return [
+      raw.map((item) => {
+        if (!isRecord(item) || !("valve" in item) || !("opening" in item)) throw new CliError("CLI 参数错误", "VALVE_SETTING_INVALID", "valve-setting items must contain valve and opening", 2);
+        return String(item.valve);
+      }),
+      raw.map((item) => Number((item as Record<string, unknown>).opening)),
+    ];
+  }
+  throw new CliError("CLI 参数错误", "VALVE_SETTING_INVALID", "valve-setting file must be a JSON array or object with valves/valves_k", 2);
+}
+
+export function assignDatasetKeys(target: Record<string, unknown>, path: string, keys: string[], label: string): void {
+  const payload = readJsonFile(path, label);
+  if (isRecord(payload)) {
+    for (const key of keys) {
+      if (key in payload) target[key] = payload[key];
+    }
+  }
+}
+

cli/src/core/http.ts

@@ -0,0 +1,96 @@
+import { CliError, errorMessage } from "./errors.js";
+import { requireNetwork, requireUsername } from "./runtime.js";
+import { success } from "./output.js";
+import type { RequestOptions, RuntimeContext } from "./types.js";
+
+function headers(ctx: RuntimeContext, requireAuth: boolean, requireProject: boolean): Record<string, string> {
+  const out: Record<string, string> = {
+    Accept: "application/json, text/plain, */*",
+    "X-Request-Id": ctx.requestId,
+    ...ctx.auth.headers,
+  };
+  if (requireAuth) {
+    if (!ctx.auth.accessToken) {
+      throw new CliError("认证失败", "UNAUTHENTICATED", "missing access token for agent context", 3, false, null, ["provide access_token via --auth-stdin or TJWATER_ACCESS_TOKEN env var"]);
+    }
+    out.Authorization = `Bearer ${ctx.auth.accessToken}`;
+  } else if (ctx.auth.accessToken) out.Authorization = `Bearer ${ctx.auth.accessToken}`;
+  if (requireProject) {
+    if (!ctx.auth.projectId) throw new CliError("认证失败", "PROJECT_CONTEXT_REQUIRED", "missing project_id for agent context", 3, false, null, ["add project_id to auth context"]);
+    out["X-Project-Id"] = ctx.auth.projectId;
+  } else if (ctx.auth.projectId) out["X-Project-Id"] = ctx.auth.projectId;
+  if (ctx.auth.userId) out["X-User-Id"] = ctx.auth.userId;
+  return out;
+}
+
+function stringifyParam(value: unknown): string {
+  if (typeof value === "boolean") return value ? "True" : "False";
+  return String(value);
+}
+
+function appendParams(url: URL, params: Record<string, unknown> = {}): void {
+  for (const [key, value] of Object.entries(params)) {
+    if (value === undefined || value === null) continue;
+    if (Array.isArray(value)) value.forEach((item) => url.searchParams.append(key, stringifyParam(item)));
+    else url.searchParams.set(key, stringifyParam(value));
+  }
+}
+
+export async function requestJson(ctx: RuntimeContext, request: RequestOptions): Promise<[unknown, number]> {
+  const { method, path, params, body, requireAuth = true, requireProject = false, requireNetworkCtx = false, requireUsernameCtx = false } = request;
+  if (requireNetworkCtx) requireNetwork(ctx);
+  if (requireUsernameCtx) requireUsername(ctx);
+  const url = new URL(`/api/v1${path}`, ctx.server.replace(/\/+$/, ""));
+  appendParams(url, params);
+  const started = performance.now();
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), ctx.timeout * 1000);
+  let response: Response;
+  try {
+    response = await fetch(url, {
+      method: method.toUpperCase(),
+      headers: {
+        ...headers(ctx, requireAuth, requireProject),
+        ...(body === undefined ? {} : { "Content-Type": "application/json" }),
+      },
+      body: body === undefined ? undefined : JSON.stringify(body),
+      signal: controller.signal,
+    });
+  } catch (error) {
+    if (error instanceof Error && error.name === "AbortError") throw new CliError("请求超时", "REQUEST_TIMEOUT", `request timed out after ${ctx.timeout} seconds`, 7, true);
+    throw new CliError("连接失败", "REQUEST_FAILED", errorMessage(error), 7, true);
+  } finally {
+    clearTimeout(timer);
+  }
+  const durationMs = Math.trunc(performance.now() - started);
+  const contentType = response.headers.get("content-type")?.toLowerCase() ?? "";
+  const text = response.status === 204 ? "" : await response.text();
+  let payload: unknown = {};
+  if (contentType.includes("application/json") && text) payload = JSON.parse(text);
+  else if (text) payload = { report: text };
+  if (!response.ok) {
+    const record = payload && typeof payload === "object" && !Array.isArray(payload) ? (payload as Record<string, unknown>) : {};
+    const message = typeof record.detail === "string" ? record.detail : typeof record.message === "string" ? record.message : text || `http ${response.status}`;
+    throw new CliError("请求失败", `HTTP_${response.status}`, message, mapStatus(response.status), response.status >= 500);
+  }
+  if (payload && typeof payload === "object" && !Array.isArray(payload)) {
+    const record = payload as Record<string, unknown>;
+    if (record.status === "error") throw new CliError("服务端错误", "SERVER_ERROR", String(record.message || "server returned error status"), 7, false, payload);
+  }
+  return [payload, durationMs];
+}
+
+function mapStatus(status: number): number {
+  if (status === 400 || status === 422) return 2;
+  if (status === 401) return 3;
+  if (status === 403) return 4;
+  if (status === 404) return 5;
+  if (status === 409 || status === 412) return 6;
+  return 7;
+}
+
+export async function emitApi(ctx: RuntimeContext, summary: string, request: RequestOptions, nextCommands: string[] = []): Promise<void> {
+  const [data, durationMs] = await requestJson(ctx, request);
+  success(summary, data, ctx, durationMs, nextCommands);
+}
+

cli/src/core/options.ts

@@ -0,0 +1,112 @@
+import { JUNCTION_FIELDS, PIPE_FIELDS, type ElementType } from "./constants.js";
+import { CliError } from "./errors.js";
+import type { OptionSchema, ParsedOptionValue, ParsedOptions } from "./types.js";
+
+export function requireValue(argv: string[], index: number, option: string): string {
+  const value = argv[index];
+  if (!value || value.startsWith("--")) throw new CliError("CLI 参数错误", "MISSING_OPTION_VALUE", `${option} requires a value`, 2);
+  return value;
+}
+
+export function parseIntStrict(value: string, option: string): number {
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed)) throw new CliError("CLI 参数错误", "INVALID_INTEGER", `${option} must be an integer`, 2);
+  return parsed;
+}
+
+export function parseFloatStrict(value: string, option: string): number {
+  const parsed = Number.parseFloat(value);
+  if (!Number.isFinite(parsed)) throw new CliError("CLI 参数错误", "INVALID_NUMBER", `${option} must be a number`, 2);
+  return parsed;
+}
+
+export function parseOptions(argv: string[], schema: OptionSchema = {}): ParsedOptions {
+  const values: Record<string, ParsedOptionValue> = {};
+  const positionals: string[] = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]!;
+    if (!arg.startsWith("--")) {
+      positionals.push(arg);
+      continue;
+    }
+    const name = arg.slice(2);
+    const kind = schema[name] ?? "string";
+    if (kind === "boolean") {
+      values[name] = true;
+    } else {
+      const raw = requireValue(argv, ++i, arg);
+      if (kind === "repeat") values[name] = [...asStringArray(values[name]), raw];
+      else if (kind === "number") values[name] = parseFloatStrict(raw, arg);
+      else if (kind === "integer") values[name] = parseIntStrict(raw, arg);
+      else values[name] = raw;
+    }
+  }
+  return { values, positionals };
+}
+
+export function required(values: Record<string, ParsedOptionValue>, name: string): string | number | boolean | string[] {
+  const value = values[name];
+  if (value === undefined || value === null || value === "") {
+    throw new CliError("CLI 参数错误", "MISSING_PARAMETER", `Missing option '--${name}'`, 2);
+  }
+  return value;
+}
+
+export function requiredString(values: Record<string, ParsedOptionValue>, name: string): string {
+  const value = required(values, name);
+  if (typeof value !== "string") throw new CliError("CLI 参数错误", "INVALID_PARAMETER", `--${name} must be a string`, 2);
+  return value;
+}
+
+export function requiredNumber(values: Record<string, ParsedOptionValue>, name: string): number {
+  const value = required(values, name);
+  if (typeof value !== "number") throw new CliError("CLI 参数错误", "INVALID_PARAMETER", `--${name} must be a number`, 2);
+  return value;
+}
+
+export function requiredStringArray(values: Record<string, ParsedOptionValue>, name: string): string[] {
+  const value = required(values, name);
+  if (!Array.isArray(value)) throw new CliError("CLI 参数错误", "INVALID_PARAMETER", `--${name} must be repeatable`, 2);
+  return value;
+}
+
+export function optionalString(values: Record<string, ParsedOptionValue>, name: string): string | undefined {
+  const value = values[name];
+  if (value === undefined) return undefined;
+  if (typeof value !== "string") throw new CliError("CLI 参数错误", "INVALID_PARAMETER", `--${name} must be a string`, 2);
+  return value;
+}
+
+export function optionalNumber(values: Record<string, ParsedOptionValue>, name: string): number | undefined {
+  const value = values[name];
+  if (value === undefined) return undefined;
+  if (typeof value !== "number") throw new CliError("CLI 参数错误", "INVALID_PARAMETER", `--${name} must be a number`, 2);
+  return value;
+}
+
+export function optionalStringArray(values: Record<string, ParsedOptionValue>, name: string): string[] | undefined {
+  const value = values[name];
+  if (value === undefined) return undefined;
+  if (!Array.isArray(value)) throw new CliError("CLI 参数错误", "INVALID_PARAMETER", `--${name} must be repeatable`, 2);
+  return value;
+}
+
+export function asStringArray(value: ParsedOptionValue | undefined): string[] {
+  if (value === undefined) return [];
+  if (Array.isArray(value)) return value;
+  throw new CliError("CLI 参数错误", "INVALID_PARAMETER", "repeat option received a non-array value", 2);
+}
+
+export function validateChoice<T extends readonly string[]>(value: string, valid: T, option: string): T[number] {
+  if (!valid.includes(value)) {
+    throw new CliError("CLI 参数错误", `INVALID_${option.replace(/^--/, "").replaceAll("-", "_").toUpperCase()}`, `${option} must be one of: ${valid.join(", ")}`, 2);
+  }
+  return value as T[number];
+}
+
+export function fieldsFor(type: ElementType): typeof PIPE_FIELDS | typeof JUNCTION_FIELDS {
+  if (type === "pipe") return PIPE_FIELDS;
+  if (type === "junction") return JUNCTION_FIELDS;
+  throw new CliError("CLI 参数错误", "INVALID_TYPE", "--type must be one of: pipe, junction", 2);
+}
+

cli/src/core/output.ts

@@ -0,0 +1,61 @@
+import { SCHEMA_VERSION } from "./constants.js";
+import type { RuntimeContext } from "./types.js";
+
+export function json(value: unknown): void {
+  process.stdout.write(`${JSON.stringify(value)}\n`);
+}
+
+export function generatedAt(): string {
+  return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+
+export function success(summary: string, data: unknown, ctx: RuntimeContext, durationMs: number, nextCommands: string[] = []): void {
+  json({
+    ok: true,
+    schema_version: SCHEMA_VERSION,
+    summary,
+    data,
+    metadata: {
+      request_id: ctx.requestId,
+      server: ctx.server,
+      duration_ms: durationMs,
+      generated_at: generatedAt(),
+    },
+    next_commands: nextCommands,
+  });
+}
+
+export function failure({
+  summary,
+  code,
+  message,
+  retryable = false,
+  server = null,
+  requestId = null,
+  data = null,
+  nextCommands = [],
+}: {
+  summary: string;
+  code: string;
+  message: string;
+  retryable?: boolean;
+  server?: string | null;
+  requestId?: string | null;
+  data?: unknown;
+  nextCommands?: string[];
+}): void {
+  json({
+    ok: false,
+    schema_version: SCHEMA_VERSION,
+    summary,
+    error: { code, message, retryable },
+    data,
+    metadata: {
+      request_id: requestId,
+      server,
+      generated_at: generatedAt(),
+    },
+    next_commands: nextCommands,
+  });
+}
+

cli/src/core/runtime.ts

@@ -0,0 +1,101 @@
+import { randomUUID } from "node:crypto";
+import { DEFAULT_SERVER, DEFAULT_TIMEOUT } from "./constants.js";
+import { CliError } from "./errors.js";
+import { requireValue, parseIntStrict } from "./options.js";
+import type { AuthContext, GlobalArgs, ParsedGlobalArgs, RuntimeContext } from "./types.js";
+
+function pick(source: Record<string, unknown>, ...keys: string[]): string | null {
+  for (const key of keys) {
+    const value = source[key];
+    if (value !== undefined && value !== null && value !== "") return String(value);
+  }
+  return null;
+}
+
+function readStdin(): Promise<string> {
+  return new Promise((resolve, reject) => {
+    let body = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk: string) => {
+      body += chunk;
+    });
+    process.stdin.on("end", () => resolve(body));
+    process.stdin.on("error", reject);
+  });
+}
+
+export async function loadAuthContext(authStdin: boolean): Promise<AuthContext> {
+  const raw = authStdin
+    ? (JSON.parse(await readStdin()) as Record<string, unknown>)
+    : {
+        server: process.env.TJWATER_SERVER,
+        access_token: process.env.TJWATER_ACCESS_TOKEN,
+        project_id: process.env.TJWATER_PROJECT_ID,
+        user_id: process.env.TJWATER_USER_ID,
+        username: process.env.TJWATER_USERNAME,
+        network: process.env.TJWATER_NETWORK,
+        headers: process.env.TJWATER_EXTRA_HEADERS ? JSON.parse(process.env.TJWATER_EXTRA_HEADERS) : {},
+      };
+  const headers = (raw.headers ?? {}) as unknown;
+  if (!headers || Array.isArray(headers) || typeof headers !== "object") {
+    throw new CliError("认证失败", "AUTH_CONTEXT_INVALID", "auth context headers must be a JSON object", 3);
+  }
+  return {
+    server: pick(raw, "server", "base_url"),
+    accessToken: pick(raw, "access_token", "token", "accessToken"),
+    projectId: pick(raw, "project_id", "projectId", "x_project_id"),
+    userId: pick(raw, "user_id", "userId", "x_user_id"),
+    username: pick(raw, "username", "preferred_username"),
+    network: pick(raw, "network", "project_code", "projectCode", "project"),
+    headers: Object.fromEntries(Object.entries(headers as Record<string, unknown>).map(([key, value]) => [String(key), String(value)])),
+  };
+}
+
+export function parseGlobalArgs(argv: string[]): ParsedGlobalArgs {
+  const globals: GlobalArgs = {
+    server: null,
+    authStdin: false,
+    scheme: null,
+    timeout: DEFAULT_TIMEOUT,
+    requestId: null,
+  };
+  const rest: string[] = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]!;
+    if (arg === "--auth-stdin") globals.authStdin = true;
+    else if (arg === "--server") globals.server = requireValue(argv, ++i, "--server");
+    else if (arg === "--scheme") globals.scheme = requireValue(argv, ++i, "--scheme");
+    else if (arg === "--timeout") globals.timeout = parseIntStrict(requireValue(argv, ++i, "--timeout"), "--timeout");
+    else if (arg === "--request-id") globals.requestId = requireValue(argv, ++i, "--request-id");
+    else rest.push(arg);
+  }
+  return { globals, rest };
+}
+
+export async function buildRuntime(globals: GlobalArgs): Promise<RuntimeContext> {
+  const auth = await loadAuthContext(globals.authStdin);
+  return {
+    server: globals.server || auth.server || DEFAULT_SERVER,
+    auth,
+    scheme: globals.scheme,
+    timeout: globals.timeout,
+    requestId: globals.requestId || randomUUID(),
+  };
+}
+
+export function requireNetwork(ctx: RuntimeContext): string {
+  if (ctx.auth.network) return ctx.auth.network;
+  throw new CliError("认证失败", "NETWORK_CONTEXT_REQUIRED", "missing network in auth context for legacy network-based endpoints", 3, false, null, ["add network to auth context"]);
+}
+
+export function requireUsername(ctx: RuntimeContext): string {
+  if (ctx.auth.username) return ctx.auth.username;
+  throw new CliError("认证失败", "USERNAME_CONTEXT_REQUIRED", "missing username in auth context", 3, false, null, ["add username to auth context"]);
+}
+
+export function resolveScheme(ctx: RuntimeContext, explicit: string | undefined, must = false): string | null {
+  const scheme = explicit || ctx.scheme;
+  if (must && !scheme) throw new CliError("CLI 参数错误", "SCHEME_REQUIRED", "missing scheme; use --scheme", 2);
+  return scheme ?? null;
+}
+

cli/src/core/time.ts

@@ -0,0 +1,23 @@
+import { CliError } from "./errors.js";
+
+export function parseTime(value: string, option: string): string {
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) {
+    throw new CliError("CLI 参数错误", "INVALID_TIME", `${option} must be a valid ISO 8601 / RFC 3339 timestamp`, 2);
+  }
+  if (!/[zZ]|[+-]\d\d:\d\d$/.test(value)) {
+    throw new CliError("CLI 参数错误", "TIMEZONE_REQUIRED", `${option} must include an explicit timezone offset`, 2);
+  }
+  return value;
+}
+
+export function addMinutesPreservingOffset(value: string, minutes: number): string {
+  const match = value.match(/([+-])(\d\d):(\d\d)$/);
+  const end = new Date(new Date(value).getTime() + minutes * 60_000);
+  if (!match) return end.toISOString().replace(".000Z", "Z");
+  const sign = match[1] === "+" ? 1 : -1;
+  const offsetMinutes = sign * (Number(match[2]) * 60 + Number(match[3]));
+  const local = new Date(end.getTime() + offsetMinutes * 60_000);
+  return `${local.toISOString().replace(".000Z", "")}${match[1]}${match[2]}:${match[3]}`;
+}
+

cli/src/core/types.ts

@@ -0,0 +1,89 @@
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue };
+export type Dict<T = unknown> = Record<string, T>;
+
+export interface AuthContext {
+  server: string | null;
+  accessToken: string | null;
+  projectId: string | null;
+  userId: string | null;
+  username: string | null;
+  network: string | null;
+  headers: Record<string, string>;
+}
+
+export interface RuntimeContext {
+  server: string;
+  auth: AuthContext;
+  scheme: string | null;
+  timeout: number;
+  requestId: string;
+}
+
+export interface GlobalArgs {
+  server: string | null;
+  authStdin: boolean;
+  scheme: string | null;
+  timeout: number;
+  requestId: string | null;
+}
+
+export interface ParsedGlobalArgs {
+  globals: GlobalArgs;
+  rest: string[];
+}
+
+export type OptionKind = "string" | "boolean" | "repeat" | "number" | "integer";
+export type OptionSchema = Record<string, OptionKind>;
+export type ParsedOptionValue = string | number | boolean | string[];
+
+export interface ParsedOptions {
+  values: Record<string, ParsedOptionValue>;
+  positionals: string[];
+}
+
+export interface RequestOptions {
+  method: string;
+  path: string;
+  params?: Record<string, unknown>;
+  body?: unknown;
+  requireAuth?: boolean;
+  requireProject?: boolean;
+  requireNetworkCtx?: boolean;
+  requireUsernameCtx?: boolean;
+}
+
+export type Handler = (ctx: RuntimeContext, argv: string[]) => Promise<void> | void;
+export type HandlerMap = Record<string, Handler>;
+
+export interface CommandDoc {
+  ok: true;
+  schema_version: string;
+  command: string;
+  summary: string;
+  description: string;
+  usage: string;
+  options: CommandOptionDoc[];
+  examples: string[];
+  output: string;
+  next_commands: string[];
+}
+
+export interface CommandOptionDoc {
+  name: string;
+  description: string;
+  required: boolean;
+  repeated: boolean;
+  default: null;
+}
+
+export type HelpPayload =
+  | CommandDoc
+  | {
+      ok: true;
+      schema_version: string;
+      summary: string;
+      menu_level?: number;
+      commands: Array<{ command: string; summary: string; usage?: string; example?: string }>;
+    };
+

cli/src/dispatch.ts

@@ -0,0 +1,50 @@
+import { CliError } from "./core/errors.js";
+import { handlers } from "./handlers.js";
+import { helpPayload } from "./help/index.js";
+import { failure, json } from "./core/output.js";
+import type { RuntimeContext } from "./core/types.js";
+
+export async function dispatch(ctx: RuntimeContext | null, argv: string[]): Promise<void> {
+  if (argv.length === 0 || argv.includes("--help")) {
+    process.stdout.write("Usage: tjwater-cli [OPTIONS] COMMAND [ARGS]...\n\nStructured JSON:\n  tjwater-cli help\n");
+    return;
+  }
+  if (argv[0] === "help") {
+    const payload = helpPayload(argv.slice(1));
+    if (!payload) {
+      failure({
+        summary: "未找到命令",
+        code: "COMMAND_NOT_FOUND",
+        message: `unknown command path: ${argv.slice(1).join(" ")}`,
+        retryable: false,
+        data: { usage: "tjwater-cli help <command-path>", examples: ["tjwater-cli help simulation run", "tjwater-cli simulation help"] },
+        nextCommands: ["tjwater-cli help", "tjwater-cli help simulation"],
+      });
+      return;
+    }
+    json(payload);
+    return;
+  }
+  const matched = matchCommand(argv);
+  if (!matched) throw new CliError("未找到命令", "COMMAND_NOT_FOUND", `No such command: ${argv.join(" ")}`, 2, false, { usage: "tjwater-cli help" }, ["tjwater-cli help"]);
+  const handler = handlers[matched.path];
+  if (!handler) throw new CliError("未找到命令", "COMMAND_NOT_FOUND", `No such command: ${argv.join(" ")}`, 2, false, { usage: "tjwater-cli help" }, ["tjwater-cli help"]);
+  if (!ctx && matched.path !== "__noop") throw new CliError("CLI 参数错误", "RUNTIME_REQUIRED", "runtime context is required for command execution", 2);
+  await handler(ctx!, matched.args);
+}
+
+function matchCommand(argv: string[]): { path: string; args: string[] } | null {
+  const paths = Object.keys(handlers).sort((a, b) => b.split(" ").length - a.split(" ").length);
+  for (const path of paths) {
+    const parts = path.split(" ");
+    if (parts.every((part, index) => argv[index] === part)) return { path, args: argv.slice(parts.length) };
+  }
+  if (argv.at(-1) === "help") {
+    const payload = helpPayload(argv.slice(0, -1));
+    if (payload) {
+      json(payload);
+      return { path: "__noop", args: [] };
+    }
+  }
+  return null;
+}

cli/src/handlers.ts

@@ -0,0 +1,15 @@
+import { analysisHandlers } from "./commands/analysis.js";
+import { componentHandlers } from "./commands/component.js";
+import { dataHandlers } from "./commands/data.js";
+import { networkHandlers } from "./commands/network.js";
+import { simulationHandlers } from "./commands/simulation.js";
+import type { HandlerMap } from "./core/types.js";
+
+export const handlers: HandlerMap = {
+  "__noop": async () => {},
+  ...networkHandlers,
+  ...componentHandlers,
+  ...simulationHandlers,
+  ...analysisHandlers,
+  ...dataHandlers,
+};

cli/src/help/docs.ts

@@ -0,0 +1,145 @@
+import { SCHEMA_VERSION } from "../core/constants.js";
+import type { CommandDoc, CommandOptionDoc } from "../core/types.js";
+
+export const GROUP_SUMMARIES: Record<string, string> = {
+  network: "管网节点、管线等基础属性查询命令。",
+  component: "组件选项与配置读取命令。",
+  "component option": "组件选项查询命令。",
+  simulation: "模拟运行与调度相关命令。",
+  analysis: "分析计算与诊断相关命令。",
+  "analysis leakage": "漏损分析相关命令。",
+  "analysis leakage schemes": "漏损方案查询命令。",
+  "analysis burst-detection": "爆管检测相关命令。",
+  "analysis burst-detection schemes": "爆管检测方案查询命令。",
+  "analysis burst-location": "爆管定位相关命令。",
+  "analysis burst-location schemes": "爆管定位方案查询命令。",
+  "analysis risk": "风险分析相关命令。",
+  "analysis sensor-placement": "传感器选址相关命令。",
+  data: "时序、SCADA 和方案数据查询命令。",
+  "data timeseries": "时序数据查询命令。",
+  "data timeseries realtime": "实时模拟时序查询命令。",
+  "data timeseries scheme": "方案时序查询命令。",
+  "data timeseries scada": "SCADA 时序查询命令。",
+  "data timeseries composite": "复合时序查询命令。",
+  "data scada": "SCADA 元数据查询命令。",
+  "data scheme": "方案数据查询命令。",
+};
+
+export const HIDDEN_PATH_PREFIXES = ["analysis burst-location", "analysis risk"];
+
+type CommandSpec = readonly [path: string, summary: string, options: readonly string[], examples: readonly string[], nextCommands?: readonly string[]];
+
+const commandSpecs: readonly CommandSpec[] = [
+  ["network get-junction-properties", "读取节点属性", ["--junction <JUNCTION>"], ["tjwater-cli network get-junction-properties --junction J1"]],
+  ["network get-pipe-properties", "读取管道属性", ["--pipe <PIPE>"], ["tjwater-cli network get-pipe-properties --pipe P1"]],
+  ["network get-all-pipes-properties", "读取全部管道属性", [], ["tjwater-cli network get-all-pipes-properties"]],
+  ["network get-reservoir-properties", "读取水库属性", ["--reservoir <RESERVOIR>"], ["tjwater-cli network get-reservoir-properties --reservoir R1"]],
+  ["network get-all-reservoirs-properties", "读取全部水库属性", [], ["tjwater-cli network get-all-reservoirs-properties"]],
+  ["network get-tank-properties", "读取水箱属性", ["--tank <TANK>"], ["tjwater-cli network get-tank-properties --tank T1"]],
+  ["network get-all-tanks-properties", "读取全部水箱属性", [], ["tjwater-cli network get-all-tanks-properties"]],
+  ["network get-pump-properties", "读取水泵属性", ["--pump <PUMP>"], ["tjwater-cli network get-pump-properties --pump PU1"]],
+  ["network get-all-pumps-properties", "读取全部水泵属性", [], ["tjwater-cli network get-all-pumps-properties"]],
+  ["network get-valve-properties", "读取阀门属性", ["--valve <VALVE>"], ["tjwater-cli network get-valve-properties --valve V1"]],
+  ["network get-all-valves-properties", "读取全部阀门属性", [], ["tjwater-cli network get-all-valves-properties"]],
+  ["component option schema", "读取选项 schema", ["--kind <KIND>", "[--pump <PUMP>]"], ["tjwater-cli component option schema --kind time", "tjwater-cli component option schema --kind energy", "tjwater-cli component option schema --kind pump-energy --pump PUMP1", "tjwater-cli component option schema --kind network"]],
+  ["component option get", "读取选项属性", ["--kind <KIND>", "[--pump <PUMP>]"], ["tjwater-cli component option get --kind time", "tjwater-cli component option get --kind energy", "tjwater-cli component option get --kind pump-energy --pump PUMP1", "tjwater-cli component option get --kind network"]],
+  ["simulation run", "触发指定绝对时间的模拟运行", ["--start-time <START_TIME>", "--duration <DURATION>"], ["tjwater-cli simulation run --start-time 2025-01-02T03:04:05+08:00 --duration 30"], ["tjwater-cli data timeseries realtime links --start-time 2025-01-02T03:04:05+08:00 --end-time 2025-01-02T03:34:05+08:00", "tjwater-cli data timeseries realtime nodes --start-time 2025-01-02T03:04:05+08:00 --end-time 2025-01-02T03:34:05+08:00"]],
+  ["analysis burst", "执行爆管分析", ["--start-time <START_TIME>", "--duration <DURATION>", "--burst-file <BURST_FILE>", "[--scheme <SCHEME>]"], ["tjwater-cli analysis burst --start-time 2025-01-02T03:04:05+08:00 --duration 900 --burst-file ./burst.json --scheme burst_case_01", "tjwater-cli data scheme get --name burst_case_01", "tjwater-cli data scheme list"]],
+  ["analysis valve", "阀门工况分析。", ["--mode <MODE>", "[--start-time <START_TIME>]", "[--valve <VALVE>]", "[--element <ELEMENT>]", "[--disabled-valve <DISABLED_VALVE>]", "[--duration <DURATION>]", "[--scheme <SCHEME>]"], ["tjwater-cli analysis valve --mode close --start-time 2025-01-02T03:04:05+08:00 --valve V1 --valve V2 --duration 900 --scheme valve_case_01", "tjwater-cli analysis valve --mode isolation --element E1 --element E2", "tjwater-cli analysis valve --mode isolation --element E1 --disabled-valve V3"]],
+  ["analysis flushing", "执行冲洗分析", ["--start-time <START_TIME>", "--valve-setting-file <VALVE_SETTING_FILE>", "--drainage-node <DRAINAGE_NODE>", "--flow <FLOW>", "[--duration <DURATION>]", "[--scheme <SCHEME>]"], ["tjwater-cli analysis flushing --start-time 2025-01-02T03:04:05+08:00 --valve-setting-file ./valve.json --drainage-node N1 --flow 100.0 --duration 900 --scheme flush_case_01"]],
+  ["analysis age", "执行水龄分析", ["--start-time <START_TIME>", "--duration <DURATION>"], ["tjwater-cli analysis age --start-time 2025-01-02T03:04:05+08:00 --duration 900"]],
+  ["analysis contaminant", "执行污染物模拟", ["--start-time <START_TIME>", "--duration <DURATION>", "--source-node <SOURCE_NODE>", "--concentration <CONCENTRATION>", "[--pattern <PATTERN>]", "[--scheme <SCHEME>]"], ["tjwater-cli analysis contaminant --start-time 2025-01-02T03:04:05+08:00 --duration 900 --source-node N1 --concentration 10.0 --scheme contam_case_01"]],
+  ["analysis sensor-placement kmeans", "执行 KMeans 传感器选址", ["--count <COUNT>", "[--min-diameter <MIN_DIAMETER>]", "[--scheme <SCHEME>]"], ["tjwater-cli analysis sensor-placement kmeans --count 5 --min-diameter 100 --scheme placement_case_01"]],
+  ["analysis leakage identify", "执行漏损识别", ["--start-time <START_TIME>", "--end-time <END_TIME>", "[--scheme <SCHEME>]"], ["tjwater-cli analysis leakage identify --start-time 2025-01-02T03:00:00+08:00 --end-time 2025-01-02T04:00:00+08:00 --scheme leak_case_01"]],
+  ["analysis leakage schemes list", "列出漏损方案", [], ["tjwater-cli analysis leakage schemes list"]],
+  ["analysis leakage schemes get", "读取漏损方案详情", ["<SCHEME_NAME>"], ["tjwater-cli analysis leakage schemes get my_scheme"]],
+  ["analysis burst-detection detect", "执行爆管检测", ["--start-time <START_TIME>", "--end-time <END_TIME>", "[--scheme <SCHEME>]"], ["tjwater-cli analysis burst-detection detect --start-time 2025-01-02T03:00:00+08:00 --end-time 2025-01-02T04:00:00+08:00 --scheme detect_case_01"]],
+  ["analysis burst-detection schemes list", "列出爆管检测方案", [], ["tjwater-cli analysis burst-detection schemes list"]],
+  ["analysis burst-detection schemes get", "读取爆管检测方案详情", ["<SCHEME_NAME>"], ["tjwater-cli analysis burst-detection schemes get my_scheme"]],
+  ["analysis burst-location locate", "执行爆管定位", ["--start-time <START_TIME>", "--end-time <END_TIME>", "--burst-leakage <BURST_LEAKAGE>", "[--scheme <SCHEME>]"], ["tjwater-cli analysis burst-location locate --start-time 2025-01-02T03:00:00+08:00 --end-time 2025-01-02T04:00:00+08:00 --burst-leakage 100.0 --scheme locate_case_01"]],
+  ["analysis burst-location schemes list", "列出爆管定位方案", [], ["tjwater-cli analysis burst-location schemes list"]],
+  ["analysis burst-location schemes get", "读取爆管定位方案详情", ["<SCHEME_NAME>"], ["tjwater-cli analysis burst-location schemes get my_scheme"]],
+  ["analysis risk pipe-now", "读取单条管道当前风险", ["--pipe <PIPE>"], ["tjwater-cli analysis risk pipe-now --pipe P1"]],
+  ["analysis risk pipe-history", "读取单条管道历史风险", ["--pipe <PIPE>"], ["tjwater-cli analysis risk pipe-history --pipe P1"]],
+  ["analysis risk network", "读取全网风险", [], ["tjwater-cli analysis risk network"]],
+  ["data timeseries realtime links", "查询实时管道时序", ["--start-time <START_TIME>", "--end-time <END_TIME>"], ["tjwater-cli data timeseries realtime links --start-time 2025-01-02T03:00:00+08:00 --end-time 2025-01-02T04:00:00+08:00"]],
+  ["data timeseries realtime nodes", "查询实时节点时序", ["--start-time <START_TIME>", "--end-time <END_TIME>"], ["tjwater-cli data timeseries realtime nodes --start-time 2025-01-02T03:00:00+08:00 --end-time 2025-01-02T04:00:00+08:00"]],
+  ["data timeseries realtime simulation-by-id-time", "按元素和时间查询实时模拟结果", ["--id <ID>", "--type <TYPE>", "--time <TIME>"], ["tjwater-cli data timeseries realtime simulation-by-id-time --id J1 --type junction --time 2025-01-02T03:30:00+08:00", "tjwater-cli data timeseries realtime simulation-by-id-time --id P1 --type pipe --time 2025-01-02T03:30:00+08:00"]],
+  ["data timeseries realtime simulation-by-time-property", "按时间和属性查询实时模拟结果", ["--type <TYPE>", "--time <TIME>", "--property <PROPERTY>"], ["tjwater-cli data timeseries realtime simulation-by-time-property --type pipe --time 2025-01-02T03:30:00+08:00 --property flow"]],
+  ["data timeseries scheme links", "查询方案管道时序", ["--start-time <START_TIME>", "--end-time <END_TIME>", "[--scheme <SCHEME>]", "[--scheme-type <SCHEME_TYPE>]"], ["tjwater-cli data timeseries scheme links --start-time 2025-01-02T03:00:00+08:00 --end-time 2025-01-02T04:00:00+08:00 --scheme my_scheme"]],
+  ["data timeseries scheme node-field", "查询方案节点字段时序", ["--node <NODE>", "--field <FIELD>", "--start-time <START_TIME>", "--end-time <END_TIME>", "[--scheme <SCHEME>]", "[--scheme-type <SCHEME_TYPE>]"], ["tjwater-cli data timeseries scheme node-field --node J1 --field pressure --start-time 2025-01-02T03:00:00+08:00 --end-time 2025-01-02T04:00:00+08:00 --scheme my_scheme"]],
+  ["data timeseries scheme simulation", "查询方案模拟数据", ["--query <QUERY>", "[--scheme <SCHEME>]", "[--scheme-type <SCHEME_TYPE>]", "[--id <ID>]", "[--time <TIME>]", "[--type <TYPE>]", "[--property <PROPERTY>]"], ["tjwater-cli data timeseries scheme simulation --query by-id-time --id J1 --time 2025-01-02T03:30:00+08:00 --type junction --scheme my_scheme", "tjwater-cli data timeseries scheme simulation --query by-scheme-time-property --time 2025-01-02T03:30:00+08:00 --type pipe --property flow --scheme my_scheme"]],
+  ["data timeseries scada query", "查询 SCADA 时序", ["--device-id <DEVICE_ID>", "--start-time <START_TIME>", "--end-time <END_TIME>", "[--field <FIELD>]"], ["tjwater-cli data timeseries scada query --device-id D1 --device-id D2 --start-time 2025-01-02T03:00:00+08:00 --end-time 2025-01-02T04:00:00+08:00", "tjwater-cli data timeseries scada query --device-id D1 --start-time 2025-01-02T03:00:00+08:00 --end-time 2025-01-02T04:00:00+08:00 --field monitored_value"]],
+  ["data timeseries composite", "执行复合时序查询", ["[--kind <KIND>]", "[--feature <FEATURE>]", "[--start-time <START_TIME>]", "[--end-time <END_TIME>]", "[--pipe <PIPE>]", "[--scheme <SCHEME>]", "[--scheme-type <SCHEME_TYPE>]", "[--use-cleaned]"], ["tjwater-cli data timeseries composite --kind scada-simulation --feature D1 --feature D2 --start-time 2025-01-02T03:00:00+08:00 --end-time 2025-01-02T04:00:00+08:00 --scheme my_scheme", "tjwater-cli data timeseries composite --kind element-simulation --feature J1:pressure --feature P1:flow --start-time 2025-01-02T03:00:00+08:00 --end-time 2025-01-02T04:00:00+08:00 --scheme my_scheme", "tjwater-cli data timeseries composite --kind element-scada --feature J1 --start-time 2025-01-02T03:00:00+08:00 --end-time 2025-01-02T04:00:00+08:00 --use-cleaned"]],
+  ["data timeseries composite pipeline-health", "查询管道健康预测", ["--pipe <PIPE>", "--start-time <START_TIME>", "--end-time <END_TIME>"], ["tjwater-cli data timeseries composite pipeline-health --pipe P1 --start-time 2025-01-02T03:00:00+08:00 --end-time 2025-01-02T04:00:00+08:00"]],
+  ["data scada get", "读取单条 SCADA 元数据", ["--kind <KIND>", "--id <ID>"], ["tjwater-cli data scada get --kind info --id SCADA-001"]],
+  ["data scada list", "列出 SCADA 元数据", ["--kind <KIND>"], ["tjwater-cli data scada list --kind info"]],
+  ["data scheme schema", "读取方案 schema", [], ["tjwater-cli data scheme schema"]],
+  ["data scheme get", "读取单条方案", ["--name <NAME>"], ["tjwater-cli data scheme get --name my_scheme"]],
+  ["data scheme list", "列出方案", [], ["tjwater-cli data scheme list"]],
+];
+
+export const commandDocs = new Map<string, CommandDoc>(
+  commandSpecs.map(([path, summary, options, examples, nextCommands = []]) => [
+    path,
+    {
+      ok: true,
+      schema_version: SCHEMA_VERSION,
+      command: path,
+      summary,
+      description: summary,
+      usage: buildUsage(path, options),
+      options: options.filter((item) => item.startsWith("--") || item.startsWith("[--")).map((item) => optionDoc(path, item)),
+      examples: [...(examples ?? [`tjwater-cli ${path}${exampleSuffix(options)}`])],
+      output: "标准 JSON 输出",
+      next_commands: [...nextCommands],
+    },
+  ]),
+);
+
+function buildUsage(path: string, options: readonly string[]): string {
+  const optionTokens = options.filter((item) => item.startsWith("--") || item.startsWith("[--"));
+  return `tjwater-cli ${path}${optionTokens.length ? ` ${optionTokens.join(" ")}` : ""}`;
+}
+
+function optionDoc(path: string, token: string): CommandOptionDoc {
+  const optional = token.startsWith("[");
+  const clean = token.replace(/^\[/, "").replace(/\]$/, "");
+  const name = clean.slice(2).split(/\s+/)[0]!;
+  const repeatedOptions: Record<string, string[]> = {
+    "analysis valve": ["valve", "element", "disabled-valve"],
+    "analysis burst-location locate": ["pressure-scada-id", "flow-scada-id"],
+    "data timeseries scada query": ["device-id"],
+    "data timeseries composite": ["feature"],
+  };
+  return {
+    name,
+    description: "",
+    required: !optional,
+    repeated: (repeatedOptions[path] ?? []).includes(name),
+    default: null,
+  };
+}
+
+function exampleSuffix(options: readonly string[]): string {
+  return options
+    .map((item) => {
+      if (item.includes("START_TIME")) return " --start-time 2025-01-02T03:00:00+08:00";
+      if (item.includes("END_TIME")) return " --end-time 2025-01-02T04:00:00+08:00";
+      if (item.includes("DURATION")) return " --duration 900";
+      if (item.includes("SCHEME")) return " --scheme my_scheme";
+      if (item.includes("KIND")) return " --kind info";
+      if (item.includes("TYPE")) return " --type pipe";
+      if (item.includes("TIME")) return " --time 2025-01-02T03:30:00+08:00";
+      return "";
+    })
+    .join("");
+}
+
+export function isHiddenPath(path: string): boolean {
+  return HIDDEN_PATH_PREFIXES.some((prefix) => path === prefix || path.startsWith(`${prefix} `));
+}
+
+export function hasVisibleSubcommands(path: string): boolean {
+  return [...commandDocs.keys()].some((key) => !isHiddenPath(key) && key.startsWith(`${path} `));
+}

cli/src/help/index.ts

@@ -0,0 +1,53 @@
+import { SCHEMA_VERSION } from "../core/constants.js";
+import { GROUP_SUMMARIES, commandDocs, hasVisibleSubcommands, isHiddenPath } from "./docs.js";
+import type { HelpPayload } from "../core/types.js";
+
+export function helpPayload(pathParts: string[]): HelpPayload | null {
+  const path = pathParts.join(" ");
+  if (path && isHiddenPath(path)) return null;
+  if (path && commandDocs.has(path)) return commandDocs.get(path)!;
+  if (!path) {
+    const seen = new Set<string>();
+    const commands: Array<{ command: string; summary: string }> = [];
+    for (const doc of [...commandDocs.values()].sort((a, b) => a.command.localeCompare(b.command))) {
+      if (isHiddenPath(doc.command)) continue;
+      const command = doc.command.split(" ")[0]!;
+      if (seen.has(command)) continue;
+      seen.add(command);
+      commands.push({ command, summary: GROUP_SUMMARIES[command] ?? `${command} 可用子命令` });
+    }
+    return {
+      ok: true,
+      schema_version: SCHEMA_VERSION,
+      summary: "可用一级菜单",
+      menu_level: 1,
+      commands,
+    };
+  }
+  const prefix = path ? `${path} ` : "";
+  const children: Array<{ command: string; summary: string; usage: string; example: string }> = [];
+  const seen = new Set<string>();
+  for (const doc of [...commandDocs.values()].sort((a, b) => a.command.localeCompare(b.command))) {
+    if (isHiddenPath(doc.command)) continue;
+    if (!doc.command.startsWith(prefix)) continue;
+    const child = doc.command.slice(prefix.length).split(" ")[0]!;
+    if (seen.has(child)) continue;
+    seen.add(child);
+    const childPath = path ? `${path} ${child}` : child;
+    const isGroup = hasVisibleSubcommands(childPath);
+    const childDoc = commandDocs.get(childPath) ?? doc;
+    children.push({
+      command: childPath,
+      summary: isGroup ? (GROUP_SUMMARIES[childPath] ?? `${childPath} 可用子命令`) : childDoc.summary,
+      usage: isGroup ? `tjwater-cli ${childPath} help` : childDoc.usage,
+      example: isGroup ? `tjwater-cli ${childPath} help` : childDoc.examples[0]!,
+    });
+  }
+  if (!children.length && path) return null;
+  return {
+    ok: true,
+    schema_version: SCHEMA_VERSION,
+    summary: GROUP_SUMMARIES[path] ?? `${path} 可用子命令`,
+    commands: children,
+  };
+}

cli/tjwater-cli

@@ -0,0 +1,9 @@
+#!/usr/bin/env sh
+set -eu
+
+SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+if command -v bun >/dev/null 2>&1; then
+  exec bun "$SCRIPT_DIR/tjwater-cli.ts" "$@"
+fi
+
+exec node "$SCRIPT_DIR/tjwater-cli.ts" "$@"

cli/tjwater-cli.ts

@@ -0,0 +1,45 @@
+import { dispatch } from "./src/dispatch.js";
+import { CliError, errorMessage } from "./src/core/errors.js";
+import { failure } from "./src/core/output.js";
+import { buildRuntime, parseGlobalArgs } from "./src/core/runtime.js";
+
+let currentServer: string | null = null;
+let currentRequestId: string | null = null;
+
+async function main(): Promise<number> {
+  const { globals, rest } = parseGlobalArgs(process.argv.slice(2));
+  if (isHelpRequest(rest)) {
+    await dispatch(null, rest);
+    return 0;
+  }
+  const ctx = await buildRuntime(globals);
+  currentServer = ctx.server;
+  currentRequestId = ctx.requestId;
+  await dispatch(ctx, rest);
+  return 0;
+}
+
+function isHelpRequest(argv: string[]): boolean {
+  return argv.length === 0 || argv[0] === "help" || argv.includes("--help") || argv.at(-1) === "help";
+}
+
+try {
+  process.exitCode = await main();
+} catch (error) {
+  if (error instanceof CliError) {
+    failure({
+      summary: error.summary,
+      code: error.code,
+      message: error.message,
+      retryable: error.retryable,
+      server: currentServer,
+      requestId: currentRequestId,
+      data: error.data,
+      nextCommands: error.nextCommands,
+    });
+    process.exitCode = error.exitCode;
+  } else {
+    failure({ summary: "CLI 执行失败", code: "UNHANDLED_ERROR", message: errorMessage(error), retryable: false });
+    process.exitCode = 1;
+  }
+}