From 67d027e60c6176a50b78a7f19da727f2c8f7047c Mon Sep 17 00:00:00 2001 From: Huarch Date: Fri, 5 Jun 2026 14:30:05 +0800 Subject: [PATCH] Remove .opencode/skills/ from git tracking --- .opencode/skills/SKILL.md | 78 -------- .opencode/skills/examples.md | 76 -------- .opencode/skills/runbook.md | 94 ---------- .opencode/skills/tjwater-cli/SKILL.md | 172 ------------------ .opencode/skills/workflow/SKILL.md | 30 --- .../hydraulic-bottleneck-analysis/SKILL.md | 14 -- 6 files changed, 464 deletions(-) delete mode 100644 .opencode/skills/SKILL.md delete mode 100644 .opencode/skills/examples.md delete mode 100644 .opencode/skills/runbook.md delete mode 100644 .opencode/skills/tjwater-cli/SKILL.md delete mode 100644 .opencode/skills/workflow/SKILL.md delete mode 100644 .opencode/skills/workflow/hydraulic-bottleneck-analysis/SKILL.md diff --git a/.opencode/skills/SKILL.md b/.opencode/skills/SKILL.md deleted file mode 100644 index 5789bb1..0000000 --- a/.opencode/skills/SKILL.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -name: skills -description: TJWater Skills — 动态生长的分析工作流树。后端服务由 Agent 自行通过 tjwater-cli help 发现。 ---- - -# TJWater Skills - -## 设计原则 - -- **Skills 仅负责多步工作流**（数据获取 → 本地计算 → 报告输出）。 -- **原子查询/分析**：Agent 直接调用 `tjwater_cli` 工具执行 CLI 命令，无需加载 skill。 -- **命令发现**：Agent 可通过 `tjwater-cli help` 或 `tjwater-cli help COMMAND` 获取 JSON 格式的能力清单和参数说明。 -- **认证与上下文**：由内部桥接自动注入，Agent 无需手动管理 `--auth-context`。 - -## 核心工具 - -| 工具 | 用途 | -|------|------| -| `tjwater_cli` | 执行任意 `tjwater-cli` 子命令。参数：`reason`、`command`、`timeout`(可选) | -| 前端工具 | `locate_features`、`show_chart`、`view_scada`、`view_history`、`render_junctions` 等 | - -> `tjwater-cli` 输出统一 JSON (schema_version: `tjwater-cli/v1`)，`"ok": true` 表示成功。 - -## 命令发现策略 - -Agent 在需要了解可用命令时，优先运行： - -``` -tjwater-cli help → 一级命令清单 -tjwater-cli help COMMAND → 子命令与参数详情 -tjwater_cli(command="help") → 通过工具调用 -``` - -`help` 返回 JSON 格式，包含 `commands` 数组和 `summary`，Agent 可直接解析识别可用能力。 - -## 使用策略 - -Skills 树是动态生长的——没有预置的 workflow，所有工作流从实际任务中沉淀： - -1. **查已有** — 先检查 `skills/workflow/` 下是否有匹配的 workflow skill -2. **从零拼装** — 无匹配时，Agent 自行组合 `tjwater_cli` 命令 + Python 脚本完成 -3. **沉淀复用** — 任务完成后复盘，如果流程稳定可复用，用 `skill_manager` 保存到 `skills/workflow//`（含 SKILL.md、references/*.md、scripts/*.py） -4. **原子操作** — 简单查询直接调用 `tjwater_cli`，不走 skill - -`skill_manager` 可维护主 SKILL.md、`## Learned Patterns`、references/*.md 和 scripts/*.py；完整写入 SKILL.md 时需包含 `name` 和 `description` frontmatter。 -目录入口也通过 `skill_manager` 维护：`skill_path="workflow"` 对应 `skills/workflow/SKILL.md`，`skill_path="__root__"` 对应 `skills/SKILL.md`。 - -## Workflow 脚本编写规范 - -**原则：尽量用 pipe 串联 CLI 调用，减少 tool calling 次数。** - -workflow skill 的 Python 脚本应在一次 `subprocess.run(shell=True)` 中用 shell pipe 串联多个 CLI 命令，而非多次 `subprocess.run` 逐次调用。中间数据转换由 `jq`/`xargs` 完成，CLI 不增加 `--input/--output`。 - -``` -subprocess 次数： 1（pipe 串联） < N（逐次调用） -tool calling 次数： 1 次 skill call < N 次 tjwater_cli 调用 -``` - -**环境变量认证**（管道场景，多用户安全）： - -```python -# env dict 仅用于当前子进程，不污染 os.environ，多用户并发隔离 -env = {**os.environ} -env["TJWATER_SERVER"] = auth["server"] -env["TJWATER_ACCESS_TOKEN"] = auth["access_token"] -env["TJWATER_PROJECT_ID"] = auth["project_id"] -env["TJWATER_NETWORK"] = auth.get("network", "") - -cmd = "tjwater-cli cmd1 | jq '...' | xargs tjwater-cli cmd2" -result = subprocess.run(cmd, shell=True, env=env, capture_output=True, text=True) -``` - -单次 CLI 调用仍用 `--auth-stdin`（桥接端点场景）。管道场景用子进程 env dict，两个场景各司其职。认证 JSON 由内部桥接注入，脚本不硬编码 token/server/project。 - -## 参考 - -- 示例：`./examples.md` -- 运行手册：`./runbook.md` diff --git a/.opencode/skills/examples.md b/.opencode/skills/examples.md deleted file mode 100644 index 6201ab8..0000000 --- a/.opencode/skills/examples.md +++ /dev/null @@ -1,76 +0,0 @@ -# 示例（基于 opencode Agent + tjwater-cli 工具调用链） - -## 示例 1：简单查询 SCADA 数据 - -用户意图：查询设备 `170490` 在时间范围内的 `monitored_value`。 - -opencode agent 调用 `tjwater_cli`： - -```json -{ - "reason": "查询设备170490在最近24小时的monitored_value数据", - "command": "data timeseries scada query --device-id 170490 --field monitored_value --start-time 2026-03-29T07:57:47+08:00 --end-time 2026-03-30T07:57:47+08:00" -} -``` - -## 示例 2：前端工具 — 地图定位 - -用户消息："帮我找到管道 P-001 和 P-002" - -opencode agent 直接调用前端工具 `locate_features`： -```json -{ - "reason": "在地图上定位用户请求的管道", - "ids": ["P-001", "P-002"], - "feature_type": "pipe" -} -``` - -## 示例 3：对话内图表 - -用户消息："展示节点 J-001 最近一天的压力变化曲线" - -典型链路： -1. `tjwater_cli(command="data timeseries realtime nodes --start-time ... --end-time ... --node-ids J-001")` -2. 处理返回的 pressure 数据为 x_data + series 格式 -3. 调用 `show_chart` 渲染 ECharts 图表 - -## 示例 4：前端工具 — SCADA 监测面板 - -用户消息："我想看看 J-001 的监测数据" - -opencode agent 调用工具 `view_scada`： -```json -{ - "reason": "打开J-001的SCADA监测面板", - "device_ids": ["J-001"], - "start_time": "2026-03-29T00:00:00+08:00", - "end_time": "2026-03-30T00:00:00+08:00" -} -``` - -## 示例 5：命令发现 - -opencode agent 需要了解可用的 CLI 命令时： - -``` -tjwater_cli(command="help") → 获取一级命令清单 -tjwater_cli(command="help analysis") → 获取 analysis 子命令详情 -``` - -帮助输出 JSON 格式，含 `commands` 数组和 `summary`。 - -## 示例 6：记住用户偏好 - -用户消息："以后回答尽量简洁，先给结论再解释。" - -opencode agent 调用 `memory_manager`： -```json -{ - "action": "add", - "reason": "用户明确给出了长期有效的回答风格偏好", - "scope": "user", - "content": "用户偏好先给结论、再补必要解释，整体风格尽量简洁。" -} -``` - diff --git a/.opencode/skills/runbook.md b/.opencode/skills/runbook.md deleted file mode 100644 index 4bf80ba..0000000 --- a/.opencode/skills/runbook.md +++ /dev/null @@ -1,94 +0,0 @@ -# TJWater Skills Runbook（工具调用链） - -## 1) 总体原则 - -- Skills 仅负责**可复用的多步工作流**。 -- 原子操作（单次查询/单项分析）由 Agent 直接调用 `tjwater_cli` 工具。 -- `tjwater-cli` 输出 JSON，`"ok": true` 表示成功，`"ok": false` 时检查 `error.code`。 -- Agent 运行 `tjwater-cli help` 发现可用命令和参数。 -- 会话完成后，运行时基于 transcript 做后台 learning review；这一步用于判断是否需要更新 memory 或 skill，而不是替代主任务回答。 - -## 1.1) 自我学习闭环 - -- **memory_manager**：保存用户长期偏好 / 约束 -- **skill_manager**：保存经过验证、可复用的 workflow 方法模式 -- **session_search**：检索历史会话，避免把一次性案例写入 memory - -## 2) 请求入口（前端） - -- `POST /api/v1/agent/chat/stream`（唯一前端入口） - -SSE 事件： - -| event | 用途 | -|---|---| -| `progress` | Agent 处理过程、规划和工具进度 | -| `token` | 面向用户的回答文本 | -| `tool_call` | 驱动前端地图/面板/图表动作 | -| `done` | 当前轮对话结束 | -| `error` | 当前轮失败 | - -## 3) tjwater_cli 工具约定 - -```json -{ - "reason": "查询当前项目数据库健康状态", - "command": "project db-health", - "timeout": 120 -} -``` - -- `command`：tjwater-cli 子命令（不含二进制路径和 `--auth-context`） -- `timeout`：可选超时秒数，默认 120，大结果集建议 300+ -- 认证上下文（token、server、project）由内部桥接自动注入 - -## 4) 工具参数约定（前端工具） - -- 所有前端工具 `locate_features`、`view_scada`、`view_history`、`show_chart`、`render_junctions` 需带 `reason` - -## 5) 学习工具约定 - -- 所有学习类工具必须带 `reason` -- `memory_manager`：`add / list / replace / remove` -- `skill_manager`：`list / write_skill / remove_skill / append_pattern / remove_pattern / write_reference / remove_reference / write_script / remove_script` -- `session_search`：只搜索当前用户 + 当前项目作用域 -- `skill_manager` 写入落到：`SKILL.md`、`## Learned Patterns`、`references/*.md`、`scripts/*.py` -- 目录入口同样走 `skill_manager`：`skill_path="workflow"` 维护 `skills/workflow/SKILL.md`，`skill_path="__root__"` 维护 `skills/SKILL.md` - -## 6) 用户上下文注入 - -- `Authorization`（Bearer Token） -- `X-Project-Id` -- 执行器附带 `X-Trace-Id` 用于链路排查 - -## 7) 排障要点 - -- CLI 返回 `"ok": false` → 检查 `error.code` 和 `error.message` -- `UNAUTHENTICATED`：检查 token 和项目权限 -- `COMMAND_NOT_FOUND` / `INPUT_NOT_FOUND`：检查命令拼写或文件路径 -- `SERVER_ERROR`：记录 `request_id`，结合后端日志排查 -- `REQUEST_TIMEOUT` / `TIMEOUT`：增大 `timeout` 参数 - -## 8) 前端工具调用链 - -``` -用户消息 → opencode agent → tool calling → 调用前端工具 - ↓ - tool handler: - 1) 推送 SSE tool_call 事件到前端 - 2) 返回简短确认给 opencode agent - ↓ -前端同时收到: - - SSE event: progress → 展示处理状态 - - SSE event: tool_call → 前端执行操作 - - SSE event: token → 渲染文字回复 -``` - -`tjwater_cli`：Agent 桥接调用 CLI，结果返回给 opencode agent 做后续分析。 -前端工具：仅推送 SSE 事件，前端直接执行。 - -## 9) 复盘与沉淀建议 - -- 复杂多工具任务完成后，判断是否产生了稳定 workflow，可写入 `skill_manager` -- 用户明确纠正表达风格、输出格式时，写入 `memory_manager` -- 确认"以前是否处理过类似问题"，用 `session_search` diff --git a/.opencode/skills/tjwater-cli/SKILL.md b/.opencode/skills/tjwater-cli/SKILL.md deleted file mode 100644 index 8274803..0000000 --- a/.opencode/skills/tjwater-cli/SKILL.md +++ /dev/null @@ -1,172 +0,0 @@ ---- -name: tjwater-cli -description: tjwater-cli 命令行工具使用说明，涵盖命令发现、输出格式、命令族、错误处理及最佳实践。 ---- - -# tjwater-cli 使用说明 - -## 概述 - -`tjwater-cli` 是 TJWater 供水管网系统的命令行工具，用于与后端服务交互，支持数据查询、分析和工程操作。所有输出统一为 JSON 格式。 - -## 工具调用 - -通过 `tjwater_cli` 工具执行 CLI 命令： - -```json -{ - "reason": "说明调用原因", - "command": "project list", - "timeout": 120 -} -``` - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| `reason` | string | 是 | 调用原因 | -| `command` | string | 是 | CLI 子命令（不含二进制路径和 `--auth-context`） | -| `timeout` | number | 否 | 超时秒数，默认 120，大结果集建议 300+ | - -认证上下文（token、server、project、network）由内部桥接自动注入，无需手动传参。 - -## 命令发现 - -Agent 通过 `help` 动态发现可用命令，而非依赖硬编码清单。 - -**重要：命令分为两类——触发动作与数据获取。** - -- **触发动作**（`simulation`、`analysis`）：向服务端发起计算请求，返回任务状态/ID，**不直接返回分析结果**。 -- **数据获取**（`data timeseries`）：所有计算结果（仿真压力、分析指标等）的唯一数据出口，需在触发动作完成后调用。 - -``` -simulation/analysis → 触发计算 → 返回状态/任务ID - ↓ - data timeseries → 获取计算结果 -``` - -通过 `help` 发现命令： - -``` -tjwater-cli help → 一级命令清单（含 commands 数组和 summary） -tjwater-cli help data timeseries → data timeseries 的子命令与参数详情 -tjwater-cli help simulation → simulation 的子命令与参数详情 -tjwater-cli help COMMAND → 子命令与参数详情 -``` - -`help` 返回 JSON 格式，Agent 可直接解析 `commands` 数组识别可用能力。 - -**严禁猜测命令或参数！** 所有命令路径、子命令和参数（名称、类型、必填/可选）均以 `help` 输出为准。执行任何命令前，必须先通过 `help` 确认其存在及参数签名，禁止凭经验拼写。 - -### 已知命令族 - -| 命令族 | 典型子命令 | 用途 | -|------|-----------|------| -| `project` | `list`, `db-health` | 项目管理、数据库健康检查 | -| `data` | `timeseries realtime links / nodes`, `timeseries scada query` | **时序数据查询**（实时/SCADA），所有分析结果的唯一获取渠道 | -| `simulation` | 通过 `help simulation` 发现 | **触发水力仿真计算**（执行成功返回状态，实际结果需走 `data timeseries` 获取） | -| `analysis` | 通过 `help analysis` 发现 | **触发分析计算**（执行成功返回状态，实际结果需走 `data timeseries` 获取） | -| `net` | `list-pipes` | 管网拓扑查询 | -| `help` | (无子命令) | 命令发现入口 | - -> 完整命令清单始终以 `tjwater-cli help` 实时输出为准。 - -## 输出格式 - -所有命令返回统一 JSON 结构： - -```json -{ - "schema_version": "tjwater-cli/v1", - "ok": true, - "data": { ... }, - "error": { - "code": "COMMAND_NOT_FOUND", - "message": "详细错误描述" - } -} -``` - -- `ok: true` — 成功，数据在 `data` 字段 -- `ok: false` — 失败，检查 `error.code` 和 `error.message` - -### 大结果集处理 - -禁止完整读取超大结果集。优先使用： -- 采样/截断参数（如 `--limit`、`--offset`） -- `--field` 按字段过滤 -- `jq` 管道提取关键字段 - -## 错误码速查 - -| error.code | 含义 | 来源 | 处理建议 | -|------|------|------|------| -| `UNAUTHENTICATED` | 缺少 access token | CLI `core.py:162` | 检查认证上下文注入 | -| `SERVER_ERROR` | 后端返回 error 状态 | CLI `core.py:400` | 记录 `request_id`，结合后端日志排查 | -| `REQUEST_TIMEOUT` | CLI 请求后端超时 | CLI `core.py:445` | 增大 `timeout` 参数或检查后端负载 | -| `TIMEOUT` | bridge 层进程超时 | Agent `server.ts:199` | 增大 `tjwater_cli` 的 `timeout` 参数 | -| `COMMAND_NOT_FOUND` | 命令/子命令不存在 | CLI `helping.py:300` | 执行 `help` 确认命令拼写 | -| `INPUT_NOT_FOUND` | `--input` 文件不存在 | CLI `core.py:243` | 检查文件路径 | -| `REQUEST_FAILED` | 网络连接失败 | CLI `core.py:453` | 检查服务端可达性 | -| `AUTH_CONTEXT_INVALID` | 认证上下文格式错误 | CLI `core.py:111` | 检查 auth headers 格式 | - -## 最佳实践 - -1. **禁止猜测命令** — 执行任何命令前必须先 `tjwater_cli(command="help ...")` 确认命令存在及参数签名，参数均已写在 help 中，禁止凭经验拼写 -2. **reason 必填** — 每次调用必须说明具体理由 -3. **触发后取数据** — `simulation`/`analysis` 仅触发计算，结果必须从 `data timeseries` 获取，勿将触发返回的状态信息当作分析结果 -4. **管道串联** — workflow 脚本中用 shell pipe 串联多个 CLI 命令，减少 `subprocess.run` 次数 -5. **结果验证** — 始终检查 `ok` 字段，失败时先处理错误码再重试 -6. **大结果集** — 优先过滤/采样，不要一次性拉取全部数据 -7. **模拟时长控制** — 模拟（`simulation`）或方案模拟的 `--duration` 不宜过长，建议每次仿真时间跨度控制在一小时以内，避免计算耗时过长或结果数据量过大 - -## 示例 - -### 查询所有实时节点数据 -```json -{ - "reason": "获取最近1小时内全部节点的实时数据", - "command": "data timeseries realtime nodes --start-time 2026-06-03T08:00:00+08:00 --end-time 2026-06-03T09:00:00+08:00" -} -``` -> `data timeseries realtime nodes` 仅接受 `--start-time` / `--end-time`，返回全量节点数据。 - -### 按节点查询方案时序字段 -```json -{ - "reason": "查询节点 J-001 最近1小时的压力数据", - "command": "data timeseries scheme node-field --node J-001 --field pressure --start-time 2026-06-03T08:00:00+08:00 --end-time 2026-06-03T09:00:00+08:00" -} -``` - -### 查询 SCADA 时序数据 -```json -{ - "reason": "查询 SCADA 设备 170490 在指定时间范围的 monitored_value", - "command": "data timeseries scada query --device-id 170490 --field monitored_value --start-time 2026-06-02T00:00:00+08:00 --end-time 2026-06-03T00:00:00+08:00" -} -``` - -### 触发仿真并获取结果 - -通常系统会自动跑仿真，建议**先尝试获取结果**，若无数据再触发仿真： - -```json -// step 1: 先尝试获取仿真结果 -{ - "reason": "尝试获取节点 J-001 09:00 时刻的仿真压力", - "command": "data timeseries realtime simulation-by-id-time --id J-001 --type junction --time 2026-06-03T09:00:00+08:00" -} -// step 2: 若 step 1 无数据（ok: false 或 data 为空），触发仿真 -{ - "reason": "无已有仿真结果，触发1小时水力仿真", - "command": "simulation run --start-time 2026-06-03T08:00:00+08:00 --duration 60" -} -// step 3: 仿真完成后，再次获取结果（同 step 1） -{ - "reason": "获取仿真结果中节点 J-001 09:00 时刻的压力", - "command": "data timeseries realtime simulation-by-id-time --id J-001 --type junction --time 2026-06-03T09:00:00+08:00" -} -``` - -`simulation run` 仅接受 `--start-time`（RFC3339，必填）和 `--duration`（整数分钟，必填）。 - diff --git a/.opencode/skills/workflow/SKILL.md b/.opencode/skills/workflow/SKILL.md deleted file mode 100644 index fb78189..0000000 --- a/.opencode/skills/workflow/SKILL.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -name: workflow -description: 供水管网分析工作流目录，描述可复用的分析流程与操作序列。 ---- - -# workflow 工作流 - -## 简介 - -本 skill 为工作流目录入口，汇总可复用的多步骤分析流程。每个工作流对应一个子目录，内含该流程的完整操作步骤、所需数据来源与判定策略。 - -## 可用工作流 - -| 工作流 | 子目录 | 用途 | -|--------|--------|------| -| 水力瓶颈分析 | `hydraulic-bottleneck-analysis` | 复合评分法识别管网水力瓶颈，区分管径不足与阀门节流问题 | - -## 使用方式 - -1. 根据分析需求匹配对应工作流 -2. 按子目录 `SKILL.md` 中的步骤依次执行 -3. 严格遵循判定策略与阈值，避免凭经验跳过步骤 - -## 工作流规范 - -- 每个工作流子目录包含独立的 `SKILL.md`，描述目的、步骤、参数与判定阈值 -- 所有数据获取均通过 `tjwater-cli` 命令族（见 `tjwater-cli` skill） -- 流程中若涉及仿真，遵循"先查结果后触发"原则 -- 新工作流由 `skill_manager` 在线写入或更新，若子目录不存在则无对应工作流 -- 新增工作流后，如需更新本目录索引，使用 `skill_manager.write_skill(skill_path="workflow", ...)` diff --git a/.opencode/skills/workflow/hydraulic-bottleneck-analysis/SKILL.md b/.opencode/skills/workflow/hydraulic-bottleneck-analysis/SKILL.md deleted file mode 100644 index 598ef09..0000000 --- a/.opencode/skills/workflow/hydraulic-bottleneck-analysis/SKILL.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -name: hydraulic-bottleneck-analysis -description: 由 skill_manager 在线追加的高置信度可复用 workflow。 -version: 1.0.0 ---- - -# learned skill - -## 简介 - -记录由 `skill_manager` 在线追加的高置信度 workflow 模式。 - -## Learned Patterns -- [350873f4366ebc50601f694a] 水力瓶颈复合评分法：流速分级(>3.0m/s=极危, >2.0m/s=严重, >1.5m/s=偏高) × 水头损失绝对值(>P90=严重, >P80=中度)，双侧超标为复合瓶颈；辅以节点压力(<20m低压, 20-25m偏低)验证。管道setting字段<100=阀门节流(优先调整阀门), >100=疑似水泵增压