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

.opencode/skills/runbook.md

@@ -1,125 +1,93 @@
-# API Skills 使用 Runbook（工具调用链）
+# TJWater Skills Runbook（工具调用链）
 
 ## 1) 总体原则
 
-- Skills 负责“告诉模型可做什么”。
-- `chat/stream` 内部启动 opencode 会话，并注册工具 `dynamic_http_call`。
-- opencode agent 通过工具调用后端能力，不直接发 HTTP。
-- TJWaterAgent 执行器负责“代表当前用户调真实后端 API”（动态路径，无白名单）。
-- 会话完成后，运行时会基于 transcript 做后台 learning review；这一步用于判断是否需要更新 memory 或 skill，而不是替代主任务回答。
+- Skills 仅负责**可复用的多步工作流**。
+- 原子操作（单次查询/单项分析）由 Agent 直接调用 `tjwater_cli` 工具。
+- `tjwater-cli` 输出 JSON，`"ok": true` 表示成功，`"ok": false` 时检查 `error.code`。
+- Agent 运行 `tjwater-cli help` 发现可用命令和参数。
+- 会话完成后，运行时基于 transcript 做后台 learning review；这一步用于判断是否需要更新 memory 或 skill，而不是替代主任务回答。
 
 ## 1.1) 自我学习闭环
 
-- **memory_manager**：保存用户长期偏好 / 约束，以及稳定 workspace 事实
-- **skill_manager**：保存经过验证、可复用的 workflow / 方法 / pitfall
-- **session_search**：检索当前用户 + 当前项目范围内的历史会话 transcript，用于回忆旧案例，避免把一次性案例写入 memory
-
-推荐分流：
-
-- 需要长期遵守的偏好 / 稳定事实 → `memory_manager`
-- 可复用的方法、步骤、坑点 → `skill_manager`
-- 某次分析过程、历史案例、临时结论 → `session_search`
+- **memory_manager**：保存用户长期偏好 / 约束
+- **skill_manager**：保存经过验证、可复用的 workflow 方法模式
+- **session_search**：检索历史会话，避免把一次性案例写入 memory
 
 ## 2) 请求入口（前端）
 
 - `POST /api/v1/agent/chat/stream`（唯一前端入口）
 
-不提供 `/execute` 对外调用路径，统一通过 `chat/stream` + 工具调用链执行。
-
-请求体：
-
-```json
-{
-  "message": "帮我分析当前管网中的水力瓶颈管道，并给出改造建议",
-  "session_id": "agent-demo-001"
-}
-```
-
 SSE 事件：
 
-| event | 用途 | 关键字段 |
-| --- | --- | --- |
-| `progress` | 展示 Agent 处理过程、规划和工具进度 | `session_id`, `id`, `phase`, `status`, `title`, `detail` |
-| `token` | 渲染面向用户的最终回答文本 | `session_id`, `content` |
-| `tool_call` | 驱动前端地图/面板/图表动作 | `session_id`, `tool`, `params` |
-| `done` | 当前轮对话结束 | `session_id` |
-| `error` | 当前轮失败 | `session_id`, `message`, `detail` |
+| event | 用途 |
+|---|---|
+| `progress` | Agent 处理过程、规划和工具进度 |
+| `token` | 面向用户的回答文本 |
+| `tool_call` | 驱动前端地图/面板/图表动作 |
+| `done` | 当前轮对话结束 |
+| `error` | 当前轮失败 |
 
-`progress.status` 取值为 `running`、`completed`、`error`；前端应按相同 `id` 覆盖更新同一条进度，而不是重复追加。
-
-## 3) 工具参数约定（opencode agent 调用工具时）
+## 3) tjwater_cli 工具约定
 
 ```json
 {
-  "path": "/api/v1/scada/by-ids-field-time-range",
-  "method": "GET",
-  "arguments": {
-    "device_ids": "170490",
-    "field": "monitored_value",
-    "start_time": "2026-03-29T07:57:47.338Z",
-    "end_time": "2026-03-30T07:57:47.338Z"
-  }
+  "reason": "查询当前项目数据库健康状态",
+  "command": "project db-health",
+  "timeout": 60
 }
 ```
 
-说明（工具 `dynamic_http_call`）：
-- `path` 必须以 `/` 开头。
-- `method` 支持：`GET/POST/PUT/PATCH/DELETE`。
-- `arguments` 会编码为 query 参数（列表会转为逗号拼接）。
+- `command`：tjwater-cli 子命令（不含二进制路径和 `--auth-context`）
+- `timeout`：可选超时秒数，默认 60，大结果集建议 300+
+- 认证上下文（token、server、project）由内部桥接自动注入
 
-## 3.1) 学习工具约定
+## 4) 工具参数约定（前端工具）
 
-- 所有学习类工具都必须带 `reason`
-- `memory_manager` 支持：`add / list / replace / remove`
-- `skill_manager` 支持：`list / append_pattern / remove_pattern / write_reference / remove_reference / write_script / remove_script`
-- `session_search` 只搜索当前用户 + 当前项目作用域，不接受跨项目检索
-- `skill_manager` 的结构化写入优先落到：
-  1. `## Learned Patterns`
-  2. `references/*.md`
-  3. `scripts/*.py`
-  不应直接重写 skill frontmatter 或任意正文段落
-- `scripts/*.py` 仅表示当前 `skill_path` 私有的可复用脚本资产；不要把运行时临时脚本写进 `data/`
+- 所有前端工具 `locate_features`、`view_scada`、`view_history`、`show_chart`、`render_junctions` 需带 `reason`
 
-## 4) 用户上下文注入（后端执行阶段）
+## 5) 学习工具约定
+
+- 所有学习类工具必须带 `reason`
+- `memory_manager`：`add / list / replace / remove`
+- `skill_manager`：`list / append_pattern / remove_pattern / write_reference / remove_reference / write_script / remove_script`
+- `session_search`：只搜索当前用户 + 当前项目作用域
+- `skill_manager` 写入落到：`## Learned Patterns`、`references/*.md`、`scripts/*.py`
+
+## 6) 用户上下文注入
 
 - `Authorization`（Bearer Token）
-- `x-project-id`
+- `X-Project-Id`
+- 执行器附带 `X-Trace-Id` 用于链路排查
 
-执行器会附带 `x-trace-id` 用于链路排查（可透传或自动生成）。
+## 7) 排障要点
 
-## 5) 排障要点
+- CLI 返回 `"ok": false` → 检查 `error.code` 和 `error.message`
+- `UNAUTHENTICATED`：检查 token 和项目权限
+- `NOT_FOUND`：检查资源 ID 或命令拼写
+- `SERVER_ERROR`：记录 `request_id`，结合后端日志排查
+- CLI 超时：增大 `timeout` 参数
 
-- `400`：检查工具参数 `path/method/arguments` 格式。
-- `401/403`：检查 token 与项目权限。
-- `404`：检查 `path` 是否正确。
-- `422`：检查 `arguments` 字段名与类型。
-- `5xx`：记录 `trace_id`，结合后端日志排查。
-
-## 6) 前端工具调用链
-
-前端工具（`locate_features`, `view_history`, `view_scada`, `show_chart`）的调用链与 `dynamic_http_call` 不同：
+## 8) 前端工具调用链
 
 ```
-用户消息 → opencode agent → tool calling → 调用前端工具 (如 locate_features)
-                                    ↓
-                              tool handler:
-                              1) 推送 SSE tool_call 事件到前端
-                              2) 返回简短确认给 opencode agent（"已定位到管道"）
-                                    ↓
+用户消息 → opencode agent → tool calling → 调用前端工具
+                                ↓
+                          tool handler:
+                          1) 推送 SSE tool_call 事件到前端
+                          2) 返回简短确认给 opencode agent
+                                ↓
 前端同时收到:
-  - SSE event: progress  → 展示规划/工具执行/完成状态
-  - SSE event: tool_call → 前端执行操作（定位地图/打开面板/渲染图表）
-  - SSE event: token     → 渲染 opencode agent 文字回复
+  - SSE event: progress  → 展示处理状态
+  - SSE event: tool_call → 前端执行操作
+  - SSE event: token     → 渲染文字回复
 ```
 
-关键区别：
-- `dynamic_http_call`：TJWaterAgent 代理 HTTP 请求，结果返回给 opencode agent 做后续分析。
-- 前端工具：TJWaterAgent 仅推送 SSE 事件，前端直接执行，结果不返回 opencode agent。
-- `show_chart`：opencode agent 先通过 `dynamic_http_call` 查询数据，处理为 x_data + series 格式后调用 `show_chart`，前端直接渲染图表，不再请求后端。
+`tjwater_cli`：Agent 桥接调用 CLI，结果返回给 opencode agent 做后续分析。
+前端工具：仅推送 SSE 事件，前端直接执行。
 
-## 7) 复盘与沉淀建议
+## 9) 复盘与沉淀建议
 
-- 复杂多工具任务完成后，优先判断是否产生了稳定 workflow，可写入 `skill_manager`
-- 用户明确纠正表达风格、输出格式或步骤时，优先判断是否需要写入 `memory_manager`
-- 如果你只是想确认“以前是不是处理过类似问题”，先用 `session_search`
-- 如果结果仍然只是 preview，不要基于 preview 做 learned pattern，总是先 `fetch_result_ref`
+- 复杂多工具任务完成后，判断是否产生了稳定 workflow，可写入 `skill_manager`
+- 用户明确纠正表达风格、输出格式时，写入 `memory_manager`
+- 确认"以前是否处理过类似问题"，用 `session_search`