208 lines
7.3 KiB
Markdown
208 lines
7.3 KiB
Markdown
# 网关任务 API 参考
|
||
|
||
网关 Base URL：`http://localhost:8000`。
|
||
|
||
## 认证
|
||
|
||
```bash
|
||
# 本机开发环境：
|
||
# - 后端 D:\workspace\ADK-gateway .env 中 GATEWAY_AUTH=<实际值>
|
||
# - 若未配置，默认值为 dev-gateway-auth
|
||
AUTH="<GATEWAY_AUTH>"
|
||
```
|
||
|
||
**认证传递方式：**
|
||
- POST 写入型接口（提交任务、Agent 注册/心跳/结果/注销）：`auth` 在请求体 JSON 中。
|
||
- GET 查询、SSE 订阅、取消：`auth` 作为 query 参数 `?auth=<AUTH>`。
|
||
|
||
## 任务接口
|
||
|
||
### 1. 提交任务（推荐：带 `cli_session_id` 以便 SSE 免轮询）
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8000/api/cli/tasks \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"auth": "'"$AUTH"'",
|
||
"task_type": "generate",
|
||
"task_tags": ["dev"],
|
||
"cli_session_id": "cli-123",
|
||
"payload": {"prompt": "生成一个炫酷的时钟 HTML 文件"},
|
||
"timeout": 300
|
||
}'
|
||
```
|
||
|
||
> **关键**：若要免轮询通过 SSE 拿结果，`cli_session_id` **必须传**，且与订阅 `GET /api/cli/events` 时用的 session 完全一致。
|
||
|
||
### 中文编码（重要，Windows 下必读）
|
||
|
||
Windows PowerShell 下直接用 `curl -d '{...中文...}'` 或 `Invoke-WebRequest` 传中文，会把中文转成 `?` 乱码。**必须用 UTF-8 编码的 JSON 文件 + `--data-binary @file`**：
|
||
|
||
1. 用 UTF-8（无 BOM）写入请求文件 `request.json`：
|
||
```json
|
||
{
|
||
"auth": "gw_xxx",
|
||
"task_type": "generate",
|
||
"task_tags": ["dev"],
|
||
"cli_session_id": "cli-123",
|
||
"timeout": 300,
|
||
"payload": {"prompt": "请在您的工作目录下创建一个炫酷的时钟 HTML 文件"}
|
||
}
|
||
```
|
||
2. 提交：
|
||
```bash
|
||
curl -s -X POST "http://localhost:8000/api/cli/tasks?auth=<AUTH>" \
|
||
-H "Content-Type: application/json" \
|
||
--data-binary "@request.json"
|
||
```
|
||
> 注意 `auth` 放在 query 或 body 均可，但 body 内的 `auth` 也需保留。用 `--data-binary @file` 可避免 Shell 对引号/中文的再转义。
|
||
|
||
响应（`TaskInfo`）：
|
||
|
||
```json
|
||
{
|
||
"request_id": "9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c",
|
||
"task_type": "generate",
|
||
"task_tags": ["dev"],
|
||
"payload": {"prompt": "生成一个炫酷的时钟 HTML 文件"},
|
||
"status": "pending",
|
||
"agent_id": null,
|
||
"cli_session_id": "cli-123",
|
||
"create_time": 1710000000.0,
|
||
"timeout": 300,
|
||
"progress": 0,
|
||
"result": null,
|
||
"error_info": null
|
||
}
|
||
```
|
||
|
||
### 2. 订阅任务完成事件（SSE，推荐，免轮询）
|
||
|
||
```bash
|
||
curl -N http://localhost:8000/api/cli/events?cli_session_id=cli-123\&auth="$AUTH"
|
||
```
|
||
|
||
- SSE 长连接（`text/event-stream`）。**先订阅，再提交带相同 `cli_session_id` 的任务**。
|
||
- 任务到达终态（`success` / `failed`，含取消/超时）时，网关推送：
|
||
|
||
```
|
||
data: {"event": "task_done", "request_id": "9f8e...", "status": "success", "result": {...}, "error_info": null}
|
||
```
|
||
|
||
- 支持回放：即使连接晚于任务完成，也会先收到历史完成事件，再收实时事件。
|
||
- 收到目标 `request_id` 的 `task_done` 即完成，无需轮询。
|
||
|
||
### 3. 查询任务状态（兜底）
|
||
|
||
```bash
|
||
curl "http://localhost:8000/api/cli/tasks/<request_id>?auth=$AUTH"
|
||
```
|
||
|
||
- 未找到返回 `404`。
|
||
- `status` 取值：`pending`（排队）、`running`（执行中）、`success`（成功）、`failed`（失败/取消/超时）。
|
||
- `success` 时 `result` 为结果字典；`failed` 时 `error_info` 说明原因（如 `cancelled by user`、`timeout`、`无可用 Agent`）。
|
||
- `progress` 为 0~100 的整数进度。
|
||
|
||
**成功任务的 `result` 结构：**
|
||
|
||
```json
|
||
{
|
||
"reply": "我先查看工作目录环境，然后创建烟花特效文件。",
|
||
"output": "已生成文件：D:\\workspace\\firework.html（17236 字节）。实现：Canvas 粒子系统、火箭拖尾升空、爆炸粒子、点击放花与自动循环。"
|
||
}
|
||
```
|
||
|
||
- `reply`：Agent 接受任务后的**首条完整回复**（展示为"Agent 接受任务回复"）。
|
||
- `output`：Agent 执行完成后的**最终总结**（展示为"Agent 总结"）。
|
||
- 失败/取消/超时任务 `result` 为 `null`，此时以 `error_info` 为准。
|
||
|
||
### 4. 取消任务
|
||
|
||
```bash
|
||
curl -X POST "http://localhost:8000/api/cli/tasks/<request_id>/cancel?auth=$AUTH"
|
||
```
|
||
|
||
- 仅 `pending` / `running` 可取消；已终态返回 `400`。
|
||
- 成功：`{"ok": true, "request_id": "<request_id>"}`。
|
||
|
||
## Agent 接口
|
||
|
||
所有 Agent 接口 `auth` 在请求体 JSON 中。
|
||
|
||
### 注册
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8000/api/agent/register \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"auth": "'"$AUTH"'",
|
||
"agent_id": "agent-001",
|
||
"endpoint": "http://agent-host:9000",
|
||
"agent_tags": ["dev"],
|
||
"max_concurrent": 2,
|
||
"current_load": 0
|
||
}'
|
||
```
|
||
|
||
### 心跳
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8000/api/agent/heartbeat \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"agent_id": "agent-001"}'
|
||
```
|
||
|
||
未注册返回 `404`。
|
||
|
||
### 结果回传
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8000/api/agent/result \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"request_id": "<request_id>",
|
||
"agent_id": "agent-001",
|
||
"status": "success",
|
||
"progress": 100,
|
||
"result": {"output": "build ok"},
|
||
"error_info": null
|
||
}'
|
||
```
|
||
|
||
### 注销
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8000/api/agent/unregister \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"agent_id": "agent-001"}'
|
||
```
|
||
|
||
## 典型对话引导（CLI 中提交任务）
|
||
|
||
当用户（CLI 中）请求提交任务时，按以下顺序执行：
|
||
|
||
1. 读取网关 `.env` 获取 `GATEWAY_AUTH`（默认 `dev-gateway-auth`）与 `ADMIN_AUTH`。
|
||
2. 与用户确认 `task_type` 与关键参数（`task_tags`、`payload`），不明确时做合理假设并说明。
|
||
3. **生成一个 `cli_session_id`**（如 `cli-<时间戳>`）。
|
||
4. **先订阅 SSE**：`GET /api/cli/events?cli_session_id=<sid>&auth=<AUTH>`（后台发起）。
|
||
5. **再提交任务**：`POST /api/cli/tasks`，请求体带相同的 `cli_session_id`。**若 payload 含中文，务必用 UTF-8 文件 + `--data-binary @file`**（见上文"中文编码"）。
|
||
6. **从 SSE 事件流**中等待该 `request_id` 的 `task_done` 事件，拿到 `status` / `result` / `error_info`；若 SSE 不可用则回退为 `GET /api/cli/tasks/{request_id}` 轮询。
|
||
7. 向用户汇报最终状态与 `result`（`reply` = Agent 接受任务回复、`output` = Agent 总结）；失败时汇报 `error_info`。
|
||
|
||
### 任务卡住时的排查步骤
|
||
|
||
若任务长时间 `pending` 或 `failed`：
|
||
|
||
1. 查 `error_info` 定位原因（`无可用 Agent` / `timeout` / `cancelled by user` / 具体异常）。
|
||
2. **`无可用 Agent`**：调 `GET /api/admin/agents`（Header `X-Admin-Auth: <ADMIN_AUTH>`）核对 Agent 的标签交集、状态（须 `ready`/`processing`）、是否满载。
|
||
3. **`timeout`/`cancelled`**：多为 Agent 侧执行慢、被取消，或 Agent 进程异常；先确认 Agent 进程存活（访问其 endpoint 健康路径），必要时重启 Agent。
|
||
4. 展示时注意：**PowerShell 会把嵌套 JSON 包装成 CLIXML**，直接用 `type file.json` 看会误以为 `result` 是 `{"type":"execute_command_result",...}`。应改用 `python -c "import json,sys; print(json.load(open(f))['result'])"` 或 `python -m json.tool` 等干净解析，再判断 reply/output 是否真实存在。
|
||
|
||
## 错误码
|
||
|
||
| HTTP | 含义 |
|
||
| --- | --- |
|
||
| 400 | 请求不合法（如取消已结束任务、缺少 agent_id） |
|
||
| 401 | `auth` 与 `GATEWAY_AUTH` 不一致（POST 在 body、GET/取消/SSE 在 query） |
|
||
| 404 | 任务/Agent 不存在 |
|
||
| 422 | 请求体字段缺失或类型错误 | |