# 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`，前端直接渲染图表，不再请求后端。