# 网关任务 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 | 请求体字段缺失或类型错误 |