新增 skills、README，指定 opencode 的启动行为

.opencode/skills/runbook.md

@@ -0,0 +1,70 @@
+# API Skills 使用 Runbook（工具调用链）
+
+## 1) 总体原则
+
+- Skills 负责“告诉模型可做什么”。
+- `chat/stream` 内部启动 LLM 会话，并注册工具 `dynamic_http_call`。
+- LLM 通过工具调用后端能力，不直接发 HTTP。
+- Sidecar 执行器负责“代表当前用户调真实后端 API”（动态路径，无白名单）。
+
+## 2) 请求入口（前端）
+
+- `POST /api/v1/copilot/chat/stream`（唯一前端入口）
+
+不提供 `/execute` 对外调用路径，统一通过 `chat/stream` + 工具调用链执行。
+
+## 3) 工具参数约定（LLM 调用工具时）
+
+```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` 不同：
+
+```
+用户消息 → LLM → function calling → 调用前端工具 (如 locate_features)
+                                    ↓
+                              tool handler:
+                              1) 推送 SSE tool_call 事件到前端
+                              2) 返回简短确认给 LLM（"已定位到管道"）
+                                    ↓
+前端同时收到:
+  - SSE event: tool_call → 前端执行操作（定位地图/打开面板/渲染图表）
+  - SSE event: token     → 渲染 LLM 文字回复
+```
+
+关键区别：
+- `dynamic_http_call`：Sidecar 代理 HTTP 请求，结果返回给 LLM 做后续分析。
+- 前端工具：Sidecar 仅推送 SSE 事件，前端直接执行，结果不返回 LLM。
+- `show_chart`：LLM 先通过 `dynamic_http_call` 查询数据，处理为 x_data + series 格式后调用 `show_chart`，前端直接渲染图表，不再请求后端。