# Agent 新增接口说明（供远程运维工具对接）

> 说明：本文件仅覆盖本次新增/扩展的 agent 接口与返回字段，不包含已有接口的完整文档。

## 通用
- 鉴权：需要 `X-RK-Token`（写操作必需；读操作依配置而定）。
- 返回：统一 JSON。

## 1) 指标接口
### GET `/v1/metrics`
**用途**：资源/进程运行指标（JSON）。

**响应示例**（字段可能随平台略有不同）：
```json
{
  "timestamp_ms": 1710000000000,
  "uptime_sec": 12345,
  "cpu": {"usage_pct": 12.3, "sample_ms": 1000, "total_ticks": 123, "idle_ticks": 45},
  "memory": {"total_kb": 1024000, "available_kb": 512000, "free_kb": 128000, "buffers_kb": 64000, "cached_kb": 256000},
  "load_avg": {"one": 0.12, "five": 0.20, "fifteen": 0.30},
  "disk": {"path": "/", "total_bytes": 1000000, "free_bytes": 200000, "used_bytes": 800000, "used_pct": 80},
  "disk_io": {"read_bytes": 123456, "write_bytes": 654321},
  "net": {"rx_bytes": 111, "tx_bytes": 222},
  "media_server": {"supported": true, "running": true, "pid": 1234, "config_path": "/path", "started_at_ms": 1710000000000, "uptime_sec": 120}
}
```

## 2) 版本与资产
### GET `/v1/versions`
**用途**：版本信息与二进制/模型清单。

**响应示例**：
```json
{
  "agent": {
    "version": "0.0.0-dev",
    "git_sha": "...",
    "binary": {"path": "...", "sha256": "...", "size": 123, "mtime_ms": 1710000000000}
  },
  "media_server": {
    "supported": true,
    "version": "...",
    "binary": {"path": "...", "sha256": "...", "size": 456, "mtime_ms": 1710000000000}
  },
  "models": {
    "count": 2,
    "items": [{"name": "yolo", "sha256": "...", "path": "...", "size": 123, "mtime_ms": 1710000000000}]
  }
}
```

### GET `/v1/assets`
**用途**：资产详情（配置、二进制、模型清单）。

**响应示例**：
```json
{
  "agent_binary": {"path": "...", "sha256": "...", "size": 123, "mtime_ms": 1710000000000},
  "config": {"path": "...", "sha256": "...", "size": 456, "mtime_ms": 1710000000000},
  "config_last_good": {"path": "...", "sha256": "...", "size": 456, "mtime_ms": 1710000000000},
  "media_server_binary": {"path": "...", "sha256": "...", "size": 789, "mtime_ms": 1710000000000},
  "models": {"items": [...]}
}
```

## 3) 任务状态查询
### GET `/v1/tasks/{id}`
**用途**：查询异步/长耗时任务状态。

**响应示例**：
```json
{
  "id": "...",
  "type": "media_binary_update",
  "status": "success",
  "started_at_ms": 1710000000000,
  "ended_at_ms": 1710000001000,
  "error": "",
  "result": {"path": "...", "sha256": "..."}
}
```

## 4) media-server 二进制回滚
### POST `/v1/media-server/binary/rollback`
**用途**：使用备份文件回滚 media-server 可执行文件。

**请求体**：
```json
{ "backup_path": "/path/to/media-server.bak.20250101-120000" }
```

**响应示例**：
```json
{
  "ok": true,
  "path": "...",
  "sha256": "...",
  "size": 123,
  "mtime_ms": 1710000000000,
  "backup_path": "...",
  "task_id": "..."
}
```

## 5) 关键接口新增字段
- `/v1/media-server/status`、`/v1/media-server/start`、`/v1/media-server/restart`、`/v1/media-server/stop`
  - **新增字段**：`started_at_ms`

## 6) 操作审计（服务端日志）
- 审计日志（JSONL）默认落盘：`{baseDir}/logs/agent_audit.jsonl`
- 覆盖操作：配置更新/应用、模型上传、media-server 启停与更新/回滚、face_gallery 更新与 reload 等