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